0021 - Tray
Status: Implemented (2026-11-18; icon selection, menu and click callbacks)
Phase 2 needs apps to be able to show a system tray icon with a small menu and react to clicks. This
spec fixes the tray service contract. The backend is pluggable so tests can inspect visibility,
tooltip and menu changes and fire events instead of creating a real tray icon. The
auro::services re-export requires the facade's services feature, and Tray additionally
requires the tray feature. On Linux the backend speaks StatusNotifierItem over D-Bus; it needs no
GTK initialization and no GTK event loop, which an app built on GPUI cannot provide.
Scope
auro-services::Tray: show or hide a tray icon, set its tooltip and supply RGBA pixels.TrayIcon: validated RGBA pixels and dimensions.TrayMenuItemandTray::set_menu: replace the context menu.Tray::on_menu_event: receive the activated item's id.TrayClick,TrayButton,TrayButtonStateandTray::on_click: receive icon clicks.TrayBackend: a pluggable backend trait; the default istray-icon.auro::services::Trayre-export.
Out of scope
- App bundle icon discovery or packaging; apps provide RGBA pixels.
- Tray persistence across app restarts.
- PNG/theme file decoding.
- Submenus, check items, icons-in-menu and accelerators.
- Other platform services.
Decisions
D1 - tray-icon is the default backend
Auro delegates the per-OS mechanics to tray-icon, which uses the Windows shell, macOS
NSStatusItem and, on Linux, the StatusNotifierItem D-Bus protocol through its ksni backend. The
ksni backend runs its own D-Bus thread, so Tray::new() works before any GTK or GPUI loop exists
and does not need the application to pump a GTK loop.
Rejected: implementing the three mechanisms inside Auro. tray-icon is MIT licensed and already
handles the quirks. Rejected: tray-icon's AppIndicator backend, which requires gtk::init on a
thread that must also run the GTK main loop; a GPUI app owns its main thread and cannot provide
that loop without a second event loop.
D2 - The backend is pluggable for tests
Tray::with_backend accepts any TrayBackend. Tests can inject a recorder and verify show/hide,
tooltip and menu changes, then invoke the stored callbacks without creating a real tray icon.
Production code uses Tray::new().
TrayBackend is not Send + Sync, because tray-icon's internal handle is not Send. The
service stores the backend in an Arc, but the trait object is main-thread-only like a GPUI view.
Callbacks are Send + Sync; they run off the app thread.
Rejected: a mock flag on the production type. It keeps the boundary explicit and makes the test double a test-only type.
D3 - Menus, click callbacks and icons
TrayMenuItem is a flat id/label/enabled item. Tray::set_menu rebuilds and installs a platform
menu; Tray::on_menu_event receives the activated id. Tray::on_click receives a TrayClick with
the button and up/down state; enter/move/leave/double-click events are ignored. TrayIcon carries
validated RGBA pixels; Tray::set_icon replaces or clears the icon.
The callback runs off the app thread. Apps use EventSender (or another channel) to move the work
onto the main thread; the service does not depend on GPUI or auro-core.
The platform event handlers are process-global and can only be installed once per process. The
service documents this; a second on_menu_event or on_click call is intentionally not supported.
On Linux, StatusNotifierItem delivers the primary activation as a left-button Up click and the
secondary activation as a middle-button Up click; right-click is owned by the status-notifier
host, which opens the menu. Menus and icons can be replaced after creation.
Rejected: a per-tray event dispatcher thread. tray-icon already owns the platform event source;
an extra thread would only copy events and complicate shutdown.
Interfaces
#![allow(unused)] fn main() { pub enum TrayError { /* tray_icon, menu or icon error */ } pub struct TrayIcon { /* rgba, width, height */ } impl TrayIcon { pub fn from_rgba(rgba: Vec<u8>, width: u32, height: u32) -> Result<Self, TrayError>; pub fn width(&self) -> u32; pub fn height(&self) -> u32; pub fn rgba(&self) -> &[u8]; } pub struct TrayMenuItem { pub id: String, pub label: String, pub enabled: bool, } pub enum TrayButton { Left, Right, Middle } pub enum TrayButtonState { Up, Down } pub struct TrayClick { pub button: TrayButton, pub state: TrayButtonState, } pub trait TrayBackend { fn set_visible(&self, visible: bool) -> Result<(), TrayError>; fn set_tooltip(&self, tooltip: Option<String>) -> Result<(), TrayError>; fn is_visible(&self) -> bool; fn set_icon(&self, icon: Option<TrayIcon>) -> Result<(), TrayError>; fn set_menu(&self, items: Vec<TrayMenuItem>) -> Result<(), TrayError>; fn set_menu_event_handler(&self, handler: Arc<dyn Fn(&str) + Send + Sync>); fn set_click_event_handler(&self, handler: Arc<dyn Fn(TrayClick) + Send + Sync>); } pub struct Tray { /* backend */ } impl Tray { pub fn new() -> Result<Self, TrayError>; pub fn with_backend(backend: impl TrayBackend + 'static) -> Self; pub fn set_visible(&self, visible: bool) -> Result<(), TrayError>; pub fn set_tooltip(&self, tooltip: Option<String>) -> Result<(), TrayError>; pub fn is_visible(&self) -> bool; pub fn set_icon(&self, icon: Option<TrayIcon>) -> Result<(), TrayError>; pub fn set_menu(&self, items: &[TrayMenuItem]) -> Result<(), TrayError>; pub fn on_menu_event<F>(&self, handler: F) where F: Fn(&str) + Send + Sync + 'static; pub fn on_click<F>(&self, handler: F) where F: Fn(TrayClick) + Send + Sync + 'static; } }
Usage:
let tray = auro::services::Tray::new()?;
tray.set_menu(&[
auro::services::TrayMenuItem::new("show", "Show"),
auro::services::TrayMenuItem::new("quit", "Quit"),
])?;
tray.on_menu_event(|id| {
// Send `id` to the app thread.
});
tray.set_visible(true)?;
Acceptance
set_visibletoggles the backend and is reflected byis_visible(shows_and_hides_the_icon).set_tooltippasses the tooltip to the backend and can clear it (updates_the_tooltip).- A valid RGBA icon can be set and cleared; invalid pixels are rejected
(
sets_and_clears_the_icon). set_menupasses the items to the backend and menu events reach the callback (sets_a_menu_and_dispatches_its_events).- Click events reach the callback (
dispatches_clicks). - A backend error surfaces as
TrayError(backend_errors_surface). auro::servicesre-exports the API surface (crates/auro/src/lib.rs).cargo fmt --all --check,cargo clippy --workspace --all-targets --locked -- -D warnings,cargo test --workspace --locked,cargo test -p auro-services --features tray --locked,cargo check -p auro --features services,tray --locked, andmdbook build docspass.
Open questions
| Question | Where it settles |
|---|---|
| PNG/theme icon decoding | Tray UX spec |
| Tray persistence across restarts | Tray UX spec |
| Submenus, check items and accelerators | Tray UX spec |
| Other platform services | Platform services specs |