open_sesame/lib.rs
1//! Open Sesame - Vimium-style Window Switcher for COSMIC Desktop
2//!
3//! A keyboard-driven window switcher that assigns letter hints to windows,
4//! allowing rapid window switching with minimal keystrokes. Inspired by Vimium's
5//! link-hinting interface, Open Sesame brings the same efficient navigation
6//! paradigm to desktop window management on the COSMIC desktop environment.
7//!
8//! # Features
9//!
10//! - **Vimium-style hints**: Windows are assigned letter sequences (g, gg, ggg, etc.)
11//! based on their application type, making window selection predictable and fast
12//! - **Focus-or-launch**: Press a key to focus a window or launch an app if not running,
13//! combining window switching and application launching into a single workflow
14//! - **Configurable**: XDG-compliant configuration with system and user overrides,
15//! supporting per-application key bindings and launch commands
16//! - **Fast**: Minimal latency with configurable activation delays for disambiguation
17//! and quick-switch support for Alt+Tab-style behavior
18//! - **Visual overlay**: Full-screen overlay with window hints and card-based UI
19//! for visual navigation and selection
20//!
21//! # Quick Start
22//!
23//! ## Installation
24//!
25//! Install the `sesame` binary and configure a COSMIC keybinding:
26//!
27//! ```bash
28//! # Setup keybinding (uses activation_key from config, default: alt+space)
29//! sesame --setup-keybinding
30//!
31//! # Or specify a custom key combination
32//! sesame --setup-keybinding alt+tab
33//! ```
34//!
35//! ## Configuration
36//!
37//! Open Sesame uses XDG configuration paths. Generate a default config:
38//!
39//! ```bash
40//! sesame --print-config > ~/.config/open-sesame/config.toml
41//! ```
42//!
43//! Example configuration:
44//!
45//! ```toml
46//! [settings]
47//! activation_key = "alt+space"
48//! activation_delay = 200
49//! overlay_delay = 720
50//! quick_switch_threshold = 250
51//!
52//! [keys.g]
53//! apps = ["ghostty", "com.mitchellh.ghostty"]
54//! launch = "ghostty"
55//!
56//! [keys.f]
57//! apps = ["firefox", "org.mozilla.firefox"]
58//! launch = "firefox"
59//! ```
60//!
61//! # Architecture
62//!
63//! The crate is organized into several modules following clean architecture principles:
64//!
65//! - [`app`]: Application orchestration and Wayland event loop integration
66//! - [`config`]: Configuration loading, validation, and XDG path resolution
67//! - [`core`]: Domain types and business logic (window hints, matching, launching)
68//! - [`input`]: Keyboard input processing and action conversion
69//! - [`platform`]: Platform abstraction layer (Wayland protocols, COSMIC integration)
70//! - [`render`]: Rendering pipeline with composable passes for overlay UI
71//! - [`ui`]: UI components (overlay window, theming)
72//! - [`util`]: Shared utilities (error handling, logging, IPC, MRU tracking)
73//!
74//! ## Data Flow
75//!
76//! 1. **Window Enumeration**: [`platform::enumerate_windows`] queries Wayland compositor
77//! for all toplevel windows via COSMIC protocols
78//! 2. **Hint Assignment**: [`HintAssignment::assign`] assigns letter hints based on
79//! application IDs using configured key bindings from [`Config`]
80//! 3. **User Input**: [`input`] module processes keyboard events and matches them
81//! against hint sequences
82//! 4. **Rendering**: [`render`] module draws the overlay UI with window hints
83//! 5. **Activation**: [`platform::activate_window`] focuses the selected window
84//!
85//! # Examples
86//!
87//! ## Programmatic Usage
88//!
89//! While Open Sesame is primarily a CLI application, the library exports types
90//! for programmatic usage:
91//!
92//! ```no_run
93//! use open_sesame::{Config, HintAssignment};
94//!
95//! # fn main() -> Result<(), open_sesame::Error> {
96//! // Load configuration
97//! let config = Config::load()?;
98//! println!("Activation key: {}", config.settings.activation_key);
99//!
100//! // Enumerate windows and assign hints
101//! # #[cfg(feature = "mock")]
102//! # {
103//! let windows = vec![]; // platform::enumerate_windows()?
104//! let assignment = HintAssignment::assign(&windows, |app_id| {
105//! config.key_for_app(app_id.as_str())
106//! });
107//!
108//! for hint in assignment.hints() {
109//! println!("[{}] {} - {}", hint.hint, hint.app_id, hint.title);
110//! }
111//! # }
112//! # Ok(())
113//! # }
114//! ```
115//!
116//! ## Configuration Loading
117//!
118//! ```no_run
119//! use open_sesame::Config;
120//!
121//! # fn main() -> Result<(), open_sesame::Error> {
122//! // Load from default XDG paths
123//! let config = Config::load()?;
124//!
125//! // Check if an app has a key binding
126//! if let Some(key) = config.key_for_app("firefox") {
127//! println!("Firefox is bound to key: {}", key);
128//! }
129//!
130//! // Get launch config for a key
131//! if let Some(launch) = config.launch_config("g") {
132//! println!("'g' launches: {}", launch.command());
133//! }
134//! # Ok(())
135//! # }
136//! ```
137//!
138//! # Platform Support
139//!
140//! Open Sesame requires:
141//! - **COSMIC Desktop Environment**: Uses COSMIC-specific Wayland protocols
142//! (`zcosmic_toplevel_manager_v1`) for window enumeration and activation
143//! - **Wayland Compositor**: Built on smithay-client-toolkit for Wayland integration
144//! - **Fontconfig**: System font resolution for text rendering
145//!
146//! # Links
147//!
148//! - [Repository](https://github.com/ScopeCreep-zip/open-sesame)
149//! - [Configuration Reference](https://github.com/ScopeCreep-zip/open-sesame#configuration)
150//! - [COSMIC Desktop](https://system76.com/cosmic)
151
152#![warn(missing_docs)]
153#![warn(clippy::all)]
154#![cfg_attr(docsrs, feature(doc_cfg))]
155
156pub mod app;
157pub mod config;
158pub mod core;
159pub mod input;
160pub mod platform;
161pub mod render;
162pub mod ui;
163pub mod util;
164
165// Re-export commonly used types
166pub use config::Config;
167pub use core::{AppId, HintAssignment, HintMatcher, MatchResult, Window, WindowHint, WindowId};
168pub use util::{Error, Result};