Lumotia/docs/architecture-map/02-tauri-runtime/system-tray.md

name, type, slice, last_verified

name	type	slice	last_verified
System tray	architecture-map-page	02-tauri-runtime	2026/05/09

System tray

Where you are: Architecture map → Tauri runtime → System tray

Plain English summary. Builds the desktop tray icon that lives in the system status area. The tray menu has Show, a disabled status row, an Evening wind-down shortcut (Phase 5 ritual), and Quit. Left-clicking the icon shows and focuses the main window.

At a glance

• Path: src-tauri/src/tray.rs.
• LOC: 73.
• Compile gate: #[cfg(not(target_os = "android"))] — Android has no tray surface (declared at the mod tray line in src-tauri/src/lib.rs:5).
• Tauri commands exposed: none. The tray is set up imperatively from lib.rs::run setup hook.
• Events emitted: magnotia:open-wind-down (no payload) when the user clicks the wind-down menu item (src-tauri/src/tray.rs:51).
• Depends on: tauri::image::Image, tauri::menu::{MenuBuilder, MenuItemBuilder}, tauri::tray::TrayIconBuilder, tauri::{Emitter, Manager}. No workspace crates.
• Called from frontend at: the frontend layout listens for magnotia:open-wind-down and routes to the wind-down page.

What's in here

setup(app) (src-tauri/src/tray.rs:6)

Builds the menu items: show, status (disabled, label "Ready"), wind-down, quit. Assembles them into a MenuBuilder with separators between groups. Falls back to a 1×1 transparent icon if default_window_icon() is None (which would be a packaging failure in production builds).

Wires three handlers:

• on_menu_event (src-tauri/src/tray.rs:37):
  • show → window.show(); window.set_focus();
  • wind-down → show + focus + emit magnotia:open-wind-down.
  • quit → app.exit(0).
  • All other ids fall through.
• on_tray_icon_event (src-tauri/src/tray.rs:58): a left-click brings the main window forward. Right-click is left to the platform default (which opens the menu).

The tray icon's tooltip is "Magnotia — Ready". The status menu item has label "Ready" and is disabled (the enabled(false) builder call leaves it visible but unclickable).

Data flow

Out only: clicks on the tray menu either hide/show the window directly or fire one event to the frontend (magnotia:open-wind-down). The tray does not read any state.

Watch-outs

• The status menu item is hard-coded "Ready". There is no wiring to update it dynamically as the engine moves between idle / loading / recording. If you want a live status, you'll need to retain a TrayIcon handle in AppState (or somewhere similar) so a command can call set_tooltip / update the menu item text.
• The icon comes from app.default_window_icon() which is the packaged bundle icon (set in tauri.conf.json bundle.icon). Replacing the tray icon means re-running tauri icon or shipping a separate tray PNG.
• The magnotia:open-wind-down event payload is () — the frontend just needs to know "navigate to the wind-down page", and the page itself decides whether to render the ritual or a "you have not enabled this yet" stub.
• Close-to-tray (intercepting WindowEvent::CloseRequested) lives in lib.rs::run setup hook (src-tauri/src/lib.rs:282), not here. The two halves are split because the close-to-tray handler needs the cloned WebviewWindow.

See also

• App lifecycle — tray::setup(app) is called at the end of the setup hook (src-tauri/src/lib.rs:315), and the close-to-tray handler in setup is what makes the tray useful.
• Tauri config — bundle icon list feeds the tray.
• Capabilities and ACL — the main capability includes core:window:allow-show / allow-set-focus / allow-hide, which are what the tray's menu actions implicitly rely on through Tauri's IPC layer.