P0 — build the PySide6 desktop shell and canonical system tray #84

New issue

Closed

opened 2026-08-12 14:41:26 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-08-12 14:41:26 +00:00

(Migrated from github.com)

Motivation

Zara already has a PySide6 Pet overlay with a working QSystemTrayIcon, but the desktop Copilot needs one canonical application shell and tray that remain alive when normal windows are hidden.

Scope

Add a zara.desktop application entry point using the existing PySide6 dependency.
Create one QApplication with setQuitOnLastWindowClosed(False).
Build the canonical Zara QSystemTrayIcon and capability-derived menu.
Define Hide Zara versus explicit Quit Zara behavior.
Surface coarse runtime status from #82/#83: idle, listening, thinking, tool running, needs input, ready, disconnected/error.
Add desktop shell lifecycle hooks for startup, runtime restart, explicit quit, and cleanup.
Detect unavailable system tray support and degrade gracefully.
Keep existing standalone Pet entry points working; do not unify Pet tray behavior yet.

Architecture

The desktop shell owns process-level UI lifecycle only. Runtime behavior remains behind RuntimeHost.

QApplication
  +-- ZaraTray
  +-- future Quick Copilot
  +-- future Full Chat
        |
      RuntimeHost

Acceptance criteria

zara-desktop (or equivalent focused entry point) launches one PySide6 application shell.
Closing normal desktop windows does not terminate the assistant.
Explicit Quit drains/stops the runtime and exits the application.
Tray left-click activation has a deterministic toggle/show behavior where Qt exposes the activation reason.
Right-click menu exposes only supported/runtime-derived actions and status.
Tray availability is checked and absence is non-fatal.
Runtime error/disconnected state remains visible and offers restart/diagnostics hooks.
No duplicate canonical desktop tray is created.

Testing requirements

Qt tests for application startup, hide/close, explicit quit, tray action wiring, and runtime-state mapping.
Tray implementation must be mockable/headless-testable when CI has no tray host.
QT_QPA_PLATFORM=offscreen-compatible shell tests where practical.
Full repository/Nix test suite.

Dependencies

#82 runtime events.
#83 RuntimeHost/command bridge.
Design: #81.

Explicit non-goals

No full chat UI yet.
No global shortcut yet.
No Pet tray unification yet.
No autostart/login integration yet.
No animated tray icon for every event.

## Motivation Zara already has a PySide6 Pet overlay with a working `QSystemTrayIcon`, but the desktop Copilot needs one canonical application shell and tray that remain alive when normal windows are hidden. ## Scope - Add a `zara.desktop` application entry point using the existing PySide6 dependency. - Create one `QApplication` with `setQuitOnLastWindowClosed(False)`. - Build the canonical Zara `QSystemTrayIcon` and capability-derived menu. - Define `Hide Zara` versus explicit `Quit Zara` behavior. - Surface coarse runtime status from #82/#83: idle, listening, thinking, tool running, needs input, ready, disconnected/error. - Add desktop shell lifecycle hooks for startup, runtime restart, explicit quit, and cleanup. - Detect unavailable system tray support and degrade gracefully. - Keep existing standalone Pet entry points working; do not unify Pet tray behavior yet. ## Architecture The desktop shell owns process-level UI lifecycle only. Runtime behavior remains behind `RuntimeHost`. ```text QApplication +-- ZaraTray +-- future Quick Copilot +-- future Full Chat | RuntimeHost ``` ## Acceptance criteria - [ ] `zara-desktop` (or equivalent focused entry point) launches one PySide6 application shell. - [ ] Closing normal desktop windows does not terminate the assistant. - [ ] Explicit Quit drains/stops the runtime and exits the application. - [ ] Tray left-click activation has a deterministic toggle/show behavior where Qt exposes the activation reason. - [ ] Right-click menu exposes only supported/runtime-derived actions and status. - [ ] Tray availability is checked and absence is non-fatal. - [ ] Runtime error/disconnected state remains visible and offers restart/diagnostics hooks. - [ ] No duplicate canonical desktop tray is created. ## Testing requirements - Qt tests for application startup, hide/close, explicit quit, tray action wiring, and runtime-state mapping. - Tray implementation must be mockable/headless-testable when CI has no tray host. - `QT_QPA_PLATFORM=offscreen`-compatible shell tests where practical. - Full repository/Nix test suite. ## Dependencies - #82 runtime events. - #83 RuntimeHost/command bridge. - Design: #81. ## Explicit non-goals - No full chat UI yet. - No global shortcut yet. - No Pet tray unification yet. - No autostart/login integration yet. - No animated tray icon for every event.