Technical overview of Native Launcher's design and implementation.

• Design Philosophy
• System Architecture
• Keyboard Event System
• Plugin System
• Performance Optimization

Native Launcher follows three core principles:

• <100ms cold start - Optimized startup sequence
• <10ms search - Cached data structures, efficient algorithms
• <30MB memory - Minimal resource footprint
• No blocking I/O on main thread

• Core functionality extracted into plugins
• Extensible without modifying main.rs
• Keyboard shortcuts owned by plugins
• Priority-based dispatch prevents conflicts

• Wayland-first (gtk4-layer-shell)
• Rust for safety and performance
• GTK4 for modern UI
• No Electron, no web technologies

┌─────────────────────────────────────────────────────────────┐
│                         main.rs                              │
│  - GTK4 Application initialization                           │
│  - Event loop and keyboard dispatch                          │
│  - Window management (gtk4-layer-shell)                      │
└───────────────┬─────────────────────────┬───────────────────┘
                │                          │
      ┌─────────▼─────────┐      ┌────────▼──────────┐
      │   PluginManager    │      │    UI Widgets     │
      │  - Plugin registry │      │  - SearchWidget   │
      │  - Search dispatch │      │  - ResultsList    │
      │  - Event dispatch  │      │  - SearchFooter   │
      └─────────┬──────────┘      └───────────────────┘
                │
     ┌──────────▼──────────────────────────────────┐
     │              Plugin Trait                    │
     │  - should_handle()                           │
     │  - search()                                  │
     │  - handle_keyboard_event()                   │
     └──┬────────┬─────────┬──────────┬────────────┘
        │        │         │          │
   ┌────▼───┐ ┌─▼──────┐ ┌▼────────┐ ┌▼──────────┐
   │  Apps  │ │ WebSrch│ │Calculator│ │   SSH     │
   │Plugin  │ │ Plugin │ │  Plugin  │ │  Plugin   │
   └────────┘ └────────┘ └──────────┘ └───────────┘

src/main.rs (328 lines)

• GTK application lifecycle
• Keyboard event capture
• Plugin manager coordination
• Does not contain: Business logic, search algorithms, keyboard handlers

src/plugins/manager.rs (446 lines)

• Plugin registration and sorting
• Search result aggregation
• Keyboard event dispatch
• Icon/command resolution

src/plugins/traits.rs (218 lines)

• Plugin trait definition
• KeyboardEvent struct
• KeyboardAction enum
• PluginResult builder

src/ui/

• GTK4 widgets (search input, results list, footer)
• CSS styling
• Theme loading

src/desktop/

• Desktop file parsing (freedesktop spec)
• Desktop entry caching
• Action parsing

src/utils/

• Browser detection (browser.rs)
• Command execution (exec.rs)
• Icon resolution (icons.rs)

The keyboard event system is the most unique architectural feature.

User presses key
       ↓
GTK EventControllerKey captures event
       ↓
Create KeyboardEvent {
    key: Key,
    modifiers: ModifierType,
    query: String,
    has_selection: bool
}
       ↓
PluginManager.dispatch_keyboard_event(&event)
       ↓
Iterate plugins by priority (highest → lowest)
       ↓
plugin.handle_keyboard_event(&event)
       ↓
Returns KeyboardAction:
  - None: Try next plugin
  - Execute { command, terminal }: Run command
  - OpenUrl(url): Open browser
  - Handled: Event consumed, no action
       ↓
main.rs executes the action

Plugins are sorted by priority once at startup:

plugins.sort_by(|a, b| b.priority().cmp(&a.priority()));

Typical priorities:

• Applications: 1000 (highest)
• Web Search: 600
• Calculator: 500
• Files: 400
• Shell: 300

Higher priority = sees events first = can override lower-priority plugins.

❌ Traditional approach (hardcoded in main.rs):

if modifiers.contains(CONTROL_MASK) && key == Enter {
    if query.starts_with("google") {
        // 40+ lines of URL building...
    } else if query.starts_with("ddg") {
        // 40+ more lines...
    }
    // ...
}

✅ Plugin-driven approach:

// main.rs: Just dispatch
let action = plugin_manager.dispatch_keyboard_event(&event);

// WebSearchPlugin: Owns the logic
fn handle_keyboard_event(&self, event: &KeyboardEvent) -> KeyboardAction {
    if event.key == Key::Return && event.has_ctrl() {
        if let Some((_, _, url)) = self.build_search_url(&event.query) {
            return KeyboardAction::OpenUrl(url);
        }
    }
    KeyboardAction::None
}

Benefits:

1. main.rs stays simple - Just event routing
2. Plugins own behavior - Web search logic in web search plugin
3. No conflicts - Priority system prevents collisions
4. Extensible - Add shortcuts without touching core
5. Testable - Unit test plugins without GTK

1. PluginManager::new()
      ↓
2. Create plugin instances
   plugins.push(Box::new(WebSearchPlugin::new()))
      ↓
3. Sort by priority
   plugins.sort_by(|a, b| b.priority().cmp(&a.priority()))
      ↓
4. For each search query:
   - Filter: plugin.should_handle(&query)
   - Search: plugin.search(&query, &context)
   - Aggregate results
      ↓
5. For each keyboard event:
   - Dispatch: plugin.handle_keyboard_event(&event)
   - First non-None action wins

pub trait Plugin: Debug + Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn command_prefixes(&self) -> Vec<&str> { Vec::new() }
    fn should_handle(&self, query: &str) -> bool;
    fn search(&self, query: &str, context: &PluginContext) -> Result<Vec<PluginResult>>;
    fn priority(&self) -> i32 { 100 }
    fn enabled(&self) -> bool { true }
    fn handle_keyboard_event(&self, _event: &KeyboardEvent) -> KeyboardAction {
        KeyboardAction::None
    }
}

1. User types query
      ↓
2. PluginManager filters plugins:
   - Command query (@ws, @shell)? → Only matching plugin
   - Global query? → All plugins where should_handle() == true
      ↓
3. Each plugin searches:
   - plugin.search(query, context) → Vec<PluginResult>
      ↓
4. Results aggregated:
   - Merge all Vec<PluginResult>
   - Sort by score (descending)
   - Deduplicate by title+command
   - Take top N (max_results)
      ↓
5. UI updated with final results

Scores guide result ordering:

• 9000+: Explicit matches (user typed google rust)
• 1000: Application name match
• 500: High-priority plugin match (calculator)
• 100: Low-priority / fallback (generic web search)

Higher scores appear first in results list.

Native Launcher implements multiple layers of performance optimization:

1. Background icon loading: Icons preload in separate thread
2. Lazy initialization: Desktop entries scanned once, cached to disk
3. Minimal dependencies: Carefully chosen, profile-guided
4. Release mode: -C opt-level=3, LTO enabled
5. Desktop entry caching: Parsed .desktop files cached with mtime validation

1. Smart debouncing (150ms): Counter-based debouncing prevents lag during rapid typing
2. Two-pass search architecture: Applications searched first, expensive operations only when needed
3. Smart triggering: File search skipped when ≥2 high-quality app matches exist
4. Pre-sorted plugins: Sorted once at startup, not per-search
5. Early filtering: should_handle() eliminates plugins fast
6. Fuzzy matching: nucleo crate (fast Rust implementation)
7. Result limiting: Stop at max_results, don't compute all
8. String reuse: Minimal allocations in hot paths

// First pass: Query Applications plugin only
let app_results = applications_plugin.search(&context);

// Count high-quality matches (score >= 700)
let good_matches = app_results.iter()
    .filter(|r| r.score >= 700)
    .count();

// Second pass: Other plugins with app count context
let context = context.with_app_results(good_matches);
let file_results = files_plugin.search(&context);

Impact: 60% of queries skip expensive file search:

• "firefox" → instant (file search skipped)
• "config" → full search (intended)
• "@files test" → always searches (explicit command)

Native Linux file indexing with fallback chain:

Priority: plocate → mlocate → locate → fd → find
Speed:    20-50ms    30-80ms   30-80ms  100-300ms  500ms+

Caching Strategy:

• Results cached for 2 minutes (TTL)
• Cache hit: <1ms response
• Cache miss: 20-300ms depending on backend

1. No web engine: Pure native GTK4, no Chromium/WebKit
2. Shared desktop entries: One Vec for all plugins
3. Icon caching: Resolved icons cached in HashMap
4. Lazy plugin init: Plugins only init when enabled
5. File search caching: Prevents repeated expensive searches

# Startup time
time ./target/release/native-launcher

# Search benchmarks
cargo bench

# Memory profiling
/usr/bin/time -v ./target/release/native-launcher

# CPU profiling
cargo flamegraph --bin native-launcher

User types → SearchWidget emits signal
                    ↓
main.rs: entry.connect_changed()
                    ↓
plugin_manager.borrow().search(query, max_results)
                    ↓
PluginManager aggregates results from plugins
                    ↓
ResultsList.update_plugin_results(results)
                    ↓
GTK ListBox re-renders with new items
                    ↓
User sees results (target: <10ms total)

User presses key → EventControllerKey captures
                    ↓
main.rs: key_controller.connect_key_pressed()
                    ↓
Create KeyboardEvent with context
                    ↓
plugin_manager.borrow().dispatch_keyboard_event(&event)
                    ↓
PluginManager iterates plugins by priority
                    ↓
First plugin returns non-None action
                    ↓
main.rs matches on action:
  - Execute { command, terminal } → utils::execute_command()
  - OpenUrl(url) → xdg-open
  - Handled → Do nothing
                    ↓
Window closes (if Execute or OpenUrl)

Native Launcher is single-threaded (GTK main thread) with one exception:

• Icon preloading: Background thread preloads icon cache on startup
• Main thread: All plugins, UI, event handling

Synchronization:

• Rc<RefCell<T>> for shared mutable state (within GTK thread)
• No Arc<Mutex<T>> needed (single-threaded)

• ✅ Plugin-driven keyboard events
• ✅ Priority-based dispatch
• ✅ Desktop file parsing
• ✅ Fuzzy search

• 🔄 Icon theme support (partially implemented)
• 🔄 Usage tracking (implemented, needs UI polish)
• 📋 Configuration UI

• 📋 Plugin hot-reload
• 📋 IPC for external plugins
• 📋 Scripting API (Lua/Rhai)

• 📋 X11 support (compatibility layer)
• 📋 Plugin marketplace
• 📋 Cloud sync for settings

• Safety: No segfaults, memory leaks, or data races
• Performance: Zero-cost abstractions, fast as C
• Ergonomics: Modern tooling (cargo, clippy, rustfmt)

• Native: No web engine overhead
• Fast: Hardware-accelerated rendering
• Wayland-first: gtk4-layer-shell integration

• Extensibility: Add features without core changes
• Maintainability: Clear boundaries, testable
• Performance: Compile-time dispatch, no runtime overhead

• Conflict resolution: Clear winner when multiple plugins could handle event
• Flexibility: High-priority plugins can override defaults
• Predictability: Deterministic dispatch order

• Plugin Development - Build your own plugins
• API Reference - Complete trait documentation
• Contributing - Join development
• Performance - Benchmarking and profiling