P1 — add Linux global shortcut backends for Wayland and X11 #87

New issue

Open

opened 2026-08-12 14:42:27 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-08-12 14:42:27 +00:00

(Migrated from github.com)

Motivation

Quick Copilot needs a configurable system-wide summon shortcut. Modern Wayland desktops cannot be treated like X11; the shortcut layer needs explicit platform backends and graceful degradation.

Scope

Define a platform-neutral GlobalShortcutService.
Implement a Wayland-first backend using the XDG Desktop Portal GlobalShortcuts interface where available.
Implement/evaluate an X11 backend behind the same interface; reuse pynput only if it passes the required behavior tests.
Persist shortcut configuration through Zara's existing TOML configuration system.
Surface backend availability/permission/error state in desktop settings/status.
Use compositor/portal activation tokens where available when presenting Quick Copilot.
Ensure failure to bind a shortcut never prevents Zara from running from tray/application launcher.

Acceptance criteria

Wayland and X11 backend selection is explicit and testable.
Portal denial/unavailability produces a visible degraded state, not a crash.
Shortcut changes can be applied/rebound without restarting the assistant where the platform permits it.
The shortcut summons #86 and does not create duplicate windows.
The UI does not contain direct X11-specific key-grab logic.
Tray summon remains functional if no global shortcut backend is available.

Testing requirements

Unit tests for backend selection, configuration and error mapping.
Fake DBus/portal tests for bind/activate/deny flows.
X11 backend tests isolated from widget logic.
Qt integration test proving activation routes to the existing Quick Copilot instance.
Full repository/Nix suite.

Dependencies

#86 Quick Copilot.
#84 desktop shell.
Design: #81.

Explicit non-goals

No Windows/macOS global-hotkey implementation yet.
No X11-only solution presented as Wayland support.
No keylogging/general keyboard capture.
No hard failure when the desktop environment lacks portal support.

## Motivation Quick Copilot needs a configurable system-wide summon shortcut. Modern Wayland desktops cannot be treated like X11; the shortcut layer needs explicit platform backends and graceful degradation. ## Scope - Define a platform-neutral `GlobalShortcutService`. - Implement a Wayland-first backend using the XDG Desktop Portal GlobalShortcuts interface where available. - Implement/evaluate an X11 backend behind the same interface; reuse `pynput` only if it passes the required behavior tests. - Persist shortcut configuration through Zara's existing TOML configuration system. - Surface backend availability/permission/error state in desktop settings/status. - Use compositor/portal activation tokens where available when presenting Quick Copilot. - Ensure failure to bind a shortcut never prevents Zara from running from tray/application launcher. ## Acceptance criteria - [ ] Wayland and X11 backend selection is explicit and testable. - [ ] Portal denial/unavailability produces a visible degraded state, not a crash. - [ ] Shortcut changes can be applied/rebound without restarting the assistant where the platform permits it. - [ ] The shortcut summons #86 and does not create duplicate windows. - [ ] The UI does not contain direct X11-specific key-grab logic. - [ ] Tray summon remains functional if no global shortcut backend is available. ## Testing requirements - Unit tests for backend selection, configuration and error mapping. - Fake DBus/portal tests for bind/activate/deny flows. - X11 backend tests isolated from widget logic. - Qt integration test proving activation routes to the existing Quick Copilot instance. - Full repository/Nix suite. ## Dependencies - #86 Quick Copilot. - #84 desktop shell. - Design: #81. ## Explicit non-goals - No Windows/macOS global-hotkey implementation yet. - No X11-only solution presented as Wayland support. - No keylogging/general keyboard capture. - No hard failure when the desktop environment lacks portal support.