feat(gui): system tray with opt-in close-to-tray setting

Add a StatusNotifierItem tray (ksni — pure-Rust over the zbus stack
notify-rust already pulls; only new crate is the pastey macro helper).
The icon reflects host/viewer status via its tooltip and offers
Show / Quit; it runs on its own thread, channel-wired to the egui app.

Add a Settings screen with a persisted toggle 'keep running in the tray
when I close the window' (config.toml [gui] close_to_tray), defaulting
OFF so the close button quits as users expect. When ON, closing hides
to the tray on X11 / minimizes on Wayland (which has no protocol to hide
a toplevel) and keeps any live stream running. If no tray is present the
close behaves normally, so the window can never be stranded.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

src/gui/mod.rs

@@ -10,10 +10,12 @@
 //! the GUI can be closed or crash without taking a live stream down.
 
 mod child;
+mod tray;
 
 use eframe::egui;
 
 use self::child::{ChildEvent, ChildProc};
+use self::tray::{TrayAction, TrayHandle, TrayStatus};
 
 /// Launch the GUI event loop. Blocks until the window is closed. Runs on the
 /// main thread (a winit requirement), which is where `main` calls it from.
@@ -43,7 +45,7 @@ pub fn run() -> anyhow::Result<()> {
     eframe::run_native(
         "PixelPass",
         options,
-        Box::new(|_cc| Ok(Box::new(PixelPassApp::default()))),
+        Box::new(|cc| Ok(Box::new(PixelPassApp::new(cc.egui_ctx.clone())))),
     )
     .map_err(|e| anyhow::anyhow!("GUI failed to start: {e}"))
 }
@@ -109,6 +111,17 @@ fn notify(summary: &'static str, body: String) {
     });
 }
 
+/// Persist just the close-to-tray preference, preserving the rest of the
+/// on-disk config (e.g. the bandwidth section the headless child may have
+/// written). Best-effort: a write failure is logged, not surfaced.
+fn persist_close_to_tray(value: bool) {
+    let mut cfg = crate::common::config::load().unwrap_or_default();
+    cfg.gui.close_to_tray = value;
+    if let Err(e) = crate::common::config::save(&cfg) {
+        tracing::warn!("failed to save settings: {e}");
+    }
+}
+
 /// Which screen the single window is currently showing.
 #[derive(Default, PartialEq)]
 enum Screen {
@@ -116,6 +129,7 @@ enum Screen {
     Menu,
     Host,
     Viewer,
+    Settings,
 }
 
 /// Quality preset choices, mirroring `cli::Quality`. Map to the `--quality`
@@ -237,24 +251,113 @@ struct PixelPassApp {
     screen: Screen,
     host: HostState,
     viewer: ViewerState,
+    /// System-tray handle; `None` if the tray couldn't start, in which case the
+    /// window behaves normally (no minimize-to-tray).
+    tray: Option<TrayHandle>,
+    /// winit can't truly hide a Wayland toplevel, so close-to-tray iconifies
+    /// there and fully hides on X11.
+    is_wayland: bool,
+    /// Set by the tray's "Quit" item so the next close really exits — the
+    /// window's own close button only hides to the tray.
+    really_quit: bool,
+    /// Persisted preference: when true, the close button hides to the tray
+    /// instead of quitting. Loaded at startup, written on toggle in Settings.
+    close_to_tray: bool,
 }
 
 impl eframe::App for PixelPassApp {
     // eframe 0.34 hands us the central-panel `ui` directly.
     fn ui(&mut self, ui: &mut egui::Ui, _frame: &mut eframe::Frame) {
+        // Tray clicks + close-to-tray come first, before any drawing.
+        let ctx = ui.ctx().clone();
+        self.handle_tray(&ctx);
         // Drain any pending child events before drawing this frame.
         self.pump_host_events();
         self.pump_viewer_events();
+        // Reflect the resulting host/viewer state into the tray icon.
+        self.sync_tray_status();
 
         match self.screen {
             Screen::Menu => self.menu(ui),
             Screen::Host => self.host(ui),
             Screen::Viewer => self.viewer(ui),
+            Screen::Settings => self.settings(ui),
         }
     }
 }
 
 impl PixelPassApp {
+    /// Build the app and start the tray with the live egui context (needed so
+    /// tray clicks can wake a hidden/minimized window).
+    fn new(ctx: egui::Context) -> Self {
+        let close_to_tray = crate::common::config::load()
+            .map(|c| c.gui.close_to_tray)
+            .unwrap_or(false);
+        Self {
+            tray: tray::start(ctx),
+            is_wayland: std::env::var_os("WAYLAND_DISPLAY").is_some(),
+            close_to_tray,
+            ..Default::default()
+        }
+    }
+
+    /// Drain tray actions and divert the window's close button to the tray
+    /// (keeping any live host stream running) instead of quitting.
+    fn handle_tray(&mut self, ctx: &egui::Context) {
+        let actions: Vec<TrayAction> = match &self.tray {
+            Some(t) => std::iter::from_fn(|| t.actions.try_recv().ok()).collect(),
+            None => Vec::new(),
+        };
+        for action in actions {
+            match action {
+                TrayAction::Show => {
+                    // Restore from whichever hide path this backend used, then
+                    // raise. The no-op one of these two is harmless.
+                    ctx.send_viewport_cmd(egui::ViewportCommand::Minimized(false));
+                    ctx.send_viewport_cmd(egui::ViewportCommand::Visible(true));
+                    ctx.send_viewport_cmd(egui::ViewportCommand::Focus);
+                }
+                TrayAction::Quit => {
+                    self.really_quit = true;
+                    ctx.send_viewport_cmd(egui::ViewportCommand::Close);
+                }
+            }
+        }
+
+        // Only divert the close when a tray is actually showing our icon —
+        // otherwise hiding would strand the window with no way to get it back.
+        let tray_live = self.tray.as_ref().is_some_and(TrayHandle::registered);
+        if tray_live
+            && self.close_to_tray
+            && !self.really_quit
+            && ctx.input(|i| i.viewport().close_requested())
+        {
+            ctx.send_viewport_cmd(egui::ViewportCommand::CancelClose);
+            if self.is_wayland {
+                ctx.send_viewport_cmd(egui::ViewportCommand::Minimized(true));
+            } else {
+                ctx.send_viewport_cmd(egui::ViewportCommand::Visible(false));
+            }
+        }
+    }
+
+    /// Mirror current activity into the tray icon's tooltip/menu.
+    fn sync_tray_status(&mut self) {
+        let status = if self.host.proc.is_some() {
+            TrayStatus::Hosting {
+                active: self.host.active,
+                max: self.host.max,
+            }
+        } else if self.viewer.proc.is_some() {
+            TrayStatus::Viewing
+        } else {
+            TrayStatus::Idle
+        };
+        if let Some(tray) = &mut self.tray {
+            tray.set_status(status);
+        }
+    }
+
     fn menu(&mut self, ui: &mut egui::Ui) {
         ui.vertical_centered(|ui| {
             ui.add_space(24.0);
@@ -283,9 +386,52 @@ impl PixelPassApp {
                 self.screen = Screen::Viewer;
                 self.prefill_viewer_ticket();
             }
+            ui.add_space(20.0);
+            if ui.button("⚙ Settings").clicked() {
+                self.screen = Screen::Settings;
+            }
         });
     }
 
+    fn settings(&mut self, ui: &mut egui::Ui) {
+        ui.horizontal(|ui| {
+            if ui.button("← Menu").clicked() {
+                self.screen = Screen::Menu;
+            }
+            ui.heading("Settings");
+        });
+        ui.separator();
+        ui.add_space(4.0);
+
+        let resp = ui.checkbox(
+            &mut self.close_to_tray,
+            "Keep running in the tray when I close the window",
+        );
+        if resp.changed() {
+            persist_close_to_tray(self.close_to_tray);
+        }
+
+        ui.add_space(4.0);
+        ui.label(
+            egui::RichText::new(
+                "Off: closing the window quits PixelPass.\n\
+                 On: closing hides it to the system tray and any active stream \
+                 keeps running — reopen it from the tray icon.",
+            )
+            .small()
+            .weak(),
+        );
+
+        // The option does nothing without a tray to hide into; say so plainly.
+        if !self.tray.as_ref().is_some_and(TrayHandle::registered) {
+            ui.add_space(8.0);
+            ui.colored_label(
+                egui::Color32::from_rgb(220, 160, 60),
+                "⚠ No system tray detected — this option has no effect right now.",
+            );
+        }
+    }
+
     // ── Host screen ──────────────────────────────────────────────────────
 
     fn host(&mut self, ui: &mut egui::Ui) {