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>

Cargo.lock

@@ -2902,6 +2902,19 @@ version = "3.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e2db585e1d738fc771bf08a151420d3ed193d9d895a36df7f6f8a9456b911ddc"
 
+[[package]]
+name = "ksni"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7ca513d0be42df5edb485af9f44a12b2cb85af773d91c27dc796d1c58b78edc"
+dependencies = [
+ "futures-util",
+ "pastey",
+ "serde",
+ "tokio",
+ "zbus 5.15.0",
+]
+
 [[package]]
 name = "kurbo"
 version = "0.13.1"
@@ -4021,6 +4034,12 @@ version = "1.0.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"
 
+[[package]]
+name = "pastey"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ee67f1008b1ba2321834326597b8e186293b049a023cdef258527550b9935b4"
+
 [[package]]
 name = "pem-rfc7468"
 version = "1.0.0"
@@ -4149,6 +4168,7 @@ dependencies = [
  "eframe",
  "iroh",
  "iroh-tickets",
+ "ksni",
  "nix 0.30.1",
  "notify-rust",
  "pipewire",
@@ -7181,6 +7201,7 @@ dependencies = [
  "rustix 1.1.4",
  "serde",
  "serde_repr",
+ "tokio",
  "tracing",
  "uds_windows",
  "uuid",

Cargo.toml

@@ -37,6 +37,9 @@ eframe = { version = "0.34.2", default-features = false, features = ["glow", "de
 # Desktop notifications on viewer join/leave. Default features give the
 # pure-Rust zbus backend (no system libdbus, no image crate).
 notify-rust = { version = "4", optional = true }
+# System-tray icon (StatusNotifierItem over D-Bus). Pure-Rust, riding the same
+# zbus stack notify-rust already pulls — no GTK, no libappindicator/C libdbus.
+ksni = { version = "0.3", optional = true }
 
 [profile.release]
 lto = "thin"
@@ -46,4 +49,4 @@ strip = "symbols"
 [features]
 # Opt-in graphical front-end (pixelpass --gui). Default-off so the headless
 # build never pulls the GUI toolkit tree.
-gui = ["dep:eframe", "dep:notify-rust"]
+gui = ["dep:eframe", "dep:notify-rust", "dep:ksni"]

LICENSE-APACHE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 mollusk
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mollusk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

assets/pixelpass.desktop

@@ -0,0 +1,12 @@
+[Desktop Entry]
+Type=Application
+Name=pixelpass
+GenericName=Screen Sharing
+Comment=P2P screen sharing over iroh — no port forwarding, no signup
+Exec=pixelpass --gui
+Icon=pixelpass
+StartupWMClass=pixelpass
+Terminal=false
+Categories=Network;RemoteAccess;
+Keywords=screen;share;sharing;remote;p2p;iroh;cast;
+StartupNotify=true

assets/pixelpass.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="256" viewBox="0 0 256 256">
+  <title>pixelpass</title>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="256" y2="256" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#4338ca"/>
+      <stop offset="1" stop-color="#7c3aed"/>
+    </linearGradient>
+  </defs>
+  <rect x="8" y="8" width="240" height="240" rx="56" fill="url(#bg)"/>
+  <!-- pixel stream: squares fading cyan -> white, "passed" toward the arrow -->
+  <rect x="50.25" y="181.29" width="16" height="16" rx="3.2" fill="#2dd5ef"/>
+  <rect x="67" y="124.44" width="20" height="20" rx="4" fill="#62dff2"/>
+  <rect x="96.25" y="82.09" width="24" height="24" rx="4.8" fill="#98e8f6"/>
+  <rect x="134.04" y="55.77" width="28" height="28" rx="5.6" fill="#c9f1f9"/>
+  <path d="M 225.5 57.5 L 183.1 85.8 L 176.9 42.2 Z" fill="#f8fafc"/>
+</svg>

packaging/arch/.gitignore

@@ -0,0 +1,6 @@
+# makepkg build artifacts
+src/
+pkg/
+/pixelpass/
+*.pkg.tar.*
+*.log

packaging/arch/PKGBUILD

@@ -0,0 +1,63 @@
+# Maintainer: mollusk <jitty+lc1iz0dc@protonmail.com>
+#
+# Local versioned package, built from the local git repo on `main`.
+# For a tagged release, switch the source fragment to `#tag=v0.1.0`.
+
+pkgname=pixelpass
+pkgver=0.1.0
+pkgrel=1
+pkgdesc='P2P screen sharing over iroh — no port forwarding, no signup'
+arch=('x86_64')
+url='file:///home/mollusk/git/butter/pixelpass'
+license=('MIT' 'Apache-2.0')
+depends=(
+  'gstreamer'          # gst-launch-1.0 / gst-inspect-1.0
+  'gst-plugins-base'   # videoscale (quality-preset downscale)
+  'gst-plugins-good'   # ximagesrc (X11 capture) + pulsesrc
+  'gst-plugins-bad'    # h264parse, mpegtsmux, aacparse
+  'gst-libav'          # avenc_aac (audio encode)
+  'gst-plugin-va'      # vah264enc (default hardware H.264 encoder)
+  'libpulse'           # pactl (audio routing / device control)
+  'hicolor-icon-theme' # owns the scalable icon dir
+  'libglvnd'           # libGL for the egui (glow) GUI
+  'libxkbcommon'       # GUI keyboard handling (winit)
+  'wayland'            # GUI Wayland backend libs
+)
+optdepends=(
+  'mpv: recommended stream viewer (the GUI launches mpv)'
+  'vlc: alternative stream viewer'
+  'gst-plugins-ugly: software x264 encoding for `pixelpass --no-hwencode`'
+  'gst-plugin-pipewire: screen capture on Wayland sessions'
+  'xorg-xwininfo: share a single window on X11 (`pixelpass --window`)'
+)
+makedepends=('cargo' 'git')
+options=('!lto')
+_branch='main'
+source=("$pkgname::git+file:///home/mollusk/git/butter/pixelpass#branch=$_branch")
+sha256sums=('SKIP')
+
+prepare() {
+  cd "$srcdir/$pkgname"
+  export RUSTUP_TOOLCHAIN=stable
+  cargo fetch --locked --target "$(rustc -vV | sed -n 's/host: //p')"
+}
+
+build() {
+  cd "$srcdir/$pkgname"
+  export RUSTUP_TOOLCHAIN=stable
+  export CARGO_TARGET_DIR=target
+  # --features gui so the .desktop launcher (pixelpass --gui) works.
+  cargo build --frozen --release --features gui
+}
+
+package() {
+  cd "$srcdir/$pkgname"
+  install -Dm0755 "target/release/$pkgname" "$pkgdir/usr/bin/$pkgname"
+  install -Dm0644 assets/pixelpass.desktop \
+    "$pkgdir/usr/share/applications/$pkgname.desktop"
+  install -Dm0644 assets/pixelpass.svg \
+    "$pkgdir/usr/share/icons/hicolor/scalable/apps/$pkgname.svg"
+  install -Dm0644 README.md "$pkgdir/usr/share/doc/$pkgname/README.md"
+  install -Dm0644 LICENSE-MIT "$pkgdir/usr/share/licenses/$pkgname/LICENSE-MIT"
+  install -Dm0644 LICENSE-APACHE "$pkgdir/usr/share/licenses/$pkgname/LICENSE-APACHE"
+}

src/common/config.rs

@@ -1,8 +1,7 @@
 //! Persistent user-level config at `~/.config/pixelpass/config.toml`.
 //!
-//! Right now this only tracks the bandwidth pre-flight result. Future
+//! It tracks the bandwidth pre-flight result and the GUI's preferences.
-//! preferences (default player, default bitrate, etc.) can hang off the
+//! Further settings can hang off the same file under their own `[section]`.
-//! same file under their own `[section]`.
 
 use anyhow::{Context, Result};
 use chrono::{DateTime, Utc};
@@ -16,6 +15,18 @@ use std::path::PathBuf;
 pub struct Config {
     #[serde(default)]
     pub bandwidth: BandwidthEntry,
+    #[serde(default)]
+    pub gui: GuiSettings,
+}
+
+/// Preferences for the `pixelpass --gui` front-end.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct GuiSettings {
+    /// When true, the window's close button hides the app to the system tray
+    /// (keeping any live stream running) instead of quitting. Defaults to
+    /// false — closing quits, which is what people expect.
+    #[serde(default)]
+    pub close_to_tray: bool,
 }
 
 /// Result of the first-run upstream measurement.

src/gui/mod.rs

@@ -10,26 +10,42 @@
 //! 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.
 pub fn run() -> anyhow::Result<()> {
+    // `app_id` must match the installed `pixelpass.desktop`: on Wayland the
+    // compositor sources the titlebar/taskbar icon from that desktop file's
+    // `Icon=` keyed by app_id — not from any pixels the app sets.
+    let mut viewport = egui::ViewportBuilder::default()
+        .with_app_id("pixelpass")
+        .with_inner_size([520.0, 480.0])
+        .with_min_inner_size([460.0, 380.0])
+        .with_title("PixelPass");
+
+    // Pixel icon for X11 titlebars (`_NET_WM_ICON`), embedded at compile time
+    // so the single binary stays self-contained. Non-fatal on failure: Wayland
+    // already has its icon via app_id, and X11 just keeps the generic fallback.
+    match eframe::icon_data::from_png_bytes(include_bytes!("../../assets/pixelpass-256.png")) {
+        Ok(icon) => viewport = viewport.with_icon(icon),
+        Err(e) => tracing::warn!("could not load embedded window icon: {e}"),
+    }
+
     let options = eframe::NativeOptions {
-        viewport: egui::ViewportBuilder::default()
+        viewport,
-            .with_inner_size([520.0, 480.0])
-            .with_min_inner_size([460.0, 380.0])
-            .with_title("PixelPass"),
         ..Default::default()
     };
 
     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}"))
 }
@@ -95,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 {
@@ -102,6 +129,7 @@ enum Screen {
     Menu,
     Host,
     Viewer,
+    Settings,
 }
 
 /// Quality preset choices, mirroring `cli::Quality`. Map to the `--quality`
@@ -223,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);
@@ -269,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) {

src/gui/tray.rs

@@ -0,0 +1,234 @@
+//! System-tray (StatusNotifierItem) integration for the GUI.
+//!
+//! The tray runs on its **own dedicated thread** with its own current-thread
+//! tokio runtime, fully decoupled from the winit event loop (which owns the
+//! main thread) and from the process-wide `#[tokio::main]` runtime. It talks to
+//! the egui app purely over channels:
+//!
+//!   * tray → app: [`TrayAction`] (Show / Quit), polled each frame.
+//!   * app → tray: [`TrayStatus`] (idle / hosting / viewing), pushed on change.
+//!
+//! Why a separate thread instead of `Handle::current().spawn`: updating the
+//! tray from the egui thread would need `block_on`, which panics when called
+//! from inside the running runtime. Keeping ksni's async wholly on its own
+//! runtime sidesteps that and keeps the frame loop non-blocking.
+
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::mpsc::{Receiver, Sender};
+
+use eframe::egui;
+use ksni::TrayMethods;
+
+/// What the user picked from the tray icon or its menu (tray thread → app).
+pub enum TrayAction {
+    /// Left-click, or the "Show window" item: bring the window back.
+    Show,
+    /// The "Quit" item: really exit (the close button only hides to tray).
+    Quit,
+}
+
+/// What the tray icon's tooltip/menu reflect (app → tray thread).
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub enum TrayStatus {
+    Idle,
+    Hosting { active: u32, max: u32 },
+    Viewing,
+}
+
+fn status_text(status: TrayStatus) -> String {
+    match status {
+        TrayStatus::Idle => "Idle".to_string(),
+        TrayStatus::Hosting { active, max } => {
+            format!("Hosting — {active} of {max} viewer(s) connected")
+        }
+        TrayStatus::Viewing => "Viewing a stream".to_string(),
+    }
+}
+
+/// Handle held by the egui app for the lifetime of the window. Dropping it
+/// closes the app→tray channel, which ends the tray thread and removes the icon.
+pub struct TrayHandle {
+    /// Menu/icon actions to drain each frame.
+    pub actions: Receiver<TrayAction>,
+    status_tx: tokio::sync::mpsc::UnboundedSender<TrayStatus>,
+    /// Set true once the tray actually registered with a StatusNotifier host.
+    /// The app must not divert the window's close to a tray that never appeared.
+    registered: Arc<AtomicBool>,
+    /// Last status pushed, so we don't spam D-Bus with no-op updates.
+    last_sent: Option<TrayStatus>,
+}
+
+impl TrayHandle {
+    /// Whether a system tray is actually showing our icon. Until this is true,
+    /// hiding the window would strand it with no way back.
+    pub fn registered(&self) -> bool {
+        self.registered.load(Ordering::Acquire)
+    }
+
+    /// Push a status change to the tray, deduped against the last one sent.
+    pub fn set_status(&mut self, status: TrayStatus) {
+        if self.last_sent != Some(status) {
+            let _ = self.status_tx.send(status);
+            self.last_sent = Some(status);
+        }
+    }
+}
+
+struct PixelPassTray {
+    status: TrayStatus,
+    /// ARGB pixmap, so the icon shows even where the themed "pixelpass" name
+    /// can't be resolved (e.g. running the dev binary before `make install`).
+    icon: Vec<ksni::Icon>,
+    actions: Sender<TrayAction>,
+    /// Repaint the (possibly hidden/minimized) window so it wakes to act on a
+    /// tray click — otherwise an idle, hidden window never processes the action.
+    ctx: egui::Context,
+}
+
+impl PixelPassTray {
+    fn notify(&self, action: TrayAction) {
+        let _ = self.actions.send(action);
+        self.ctx.request_repaint();
+    }
+}
+
+impl ksni::Tray for PixelPassTray {
+    fn id(&self) -> String {
+        "pixelpass".to_string()
+    }
+
+    fn title(&self) -> String {
+        "PixelPass".to_string()
+    }
+
+    // Themed icon (matches the installed hicolor/scalable/apps/pixelpass.svg);
+    // icon_pixmap below is the always-works fallback.
+    fn icon_name(&self) -> String {
+        "pixelpass".to_string()
+    }
+
+    fn icon_pixmap(&self) -> Vec<ksni::Icon> {
+        self.icon.clone()
+    }
+
+    fn status(&self) -> ksni::Status {
+        ksni::Status::Active
+    }
+
+    fn tool_tip(&self) -> ksni::ToolTip {
+        ksni::ToolTip {
+            title: "PixelPass".to_string(),
+            description: status_text(self.status),
+            icon_name: "pixelpass".to_string(),
+            icon_pixmap: Vec::new(),
+        }
+    }
+
+    fn activate(&mut self, _x: i32, _y: i32) {
+        self.notify(TrayAction::Show);
+    }
+
+    fn menu(&self) -> Vec<ksni::MenuItem<Self>> {
+        use ksni::menu::{MenuItem, StandardItem};
+        vec![
+            // Non-clickable status line.
+            StandardItem {
+                label: status_text(self.status),
+                enabled: false,
+                ..Default::default()
+            }
+            .into(),
+            MenuItem::Separator,
+            StandardItem {
+                label: "Show window".to_string(),
+                activate: Box::new(|t: &mut Self| t.notify(TrayAction::Show)),
+                ..Default::default()
+            }
+            .into(),
+            StandardItem {
+                label: "Quit PixelPass".to_string(),
+                icon_name: "application-exit".to_string(),
+                activate: Box::new(|t: &mut Self| t.notify(TrayAction::Quit)),
+                ..Default::default()
+            }
+            .into(),
+        ]
+    }
+}
+
+/// Decode the embedded PNG (RGBA) and convert to the ARGB pixmap ksni wants.
+/// Reuses eframe's PNG decoder so we don't take a direct `image` dependency.
+fn load_icon() -> Option<Vec<ksni::Icon>> {
+    let icon =
+        eframe::icon_data::from_png_bytes(include_bytes!("../../assets/pixelpass-256.png")).ok()?;
+    let mut data = icon.rgba; // RGBA8, row-major
+    for px in data.chunks_exact_mut(4) {
+        px.rotate_right(1); // [r,g,b,a] -> [a,r,g,b], network byte order
+    }
+    Some(vec![ksni::Icon {
+        width: icon.width as i32,
+        height: icon.height as i32,
+        data,
+    }])
+}
+
+/// Start the tray on its own thread. Returns a handle for the app to drive it,
+/// or `None` if the icon couldn't be decoded or the thread couldn't spawn (in
+/// which case the GUI simply runs without a tray — close behaves as before).
+pub fn start(ctx: egui::Context) -> Option<TrayHandle> {
+    let icon = load_icon()?;
+    let (action_tx, action_rx) = std::sync::mpsc::channel();
+    let (status_tx, mut status_rx) = tokio::sync::mpsc::unbounded_channel::<TrayStatus>();
+    let registered = Arc::new(AtomicBool::new(false));
+    let registered_thread = registered.clone();
+
+    std::thread::Builder::new()
+        .name("pixelpass-tray".to_string())
+        .spawn(move || {
+            let rt = match tokio::runtime::Builder::new_current_thread()
+                .enable_all()
+                .build()
+            {
+                Ok(rt) => rt,
+                Err(e) => {
+                    tracing::warn!("tray: could not build runtime: {e}");
+                    return;
+                }
+            };
+            rt.block_on(async move {
+                let tray = PixelPassTray {
+                    status: TrayStatus::Idle,
+                    icon,
+                    actions: action_tx,
+                    ctx,
+                };
+                let handle = match tray.spawn().await {
+                    Ok(handle) => handle,
+                    Err(e) => {
+                        // No StatusNotifier host (no system tray) — degrade
+                        // gracefully: the window keeps its normal close.
+                        tracing::warn!("tray: not available, running without it: {e}");
+                        return;
+                    }
+                };
+                registered_thread.store(true, Ordering::Release);
+
+                // Apply status changes until the app drops its sender (on quit),
+                // which ends this loop, the runtime, the thread, and the icon.
+                while let Some(status) = status_rx.recv().await {
+                    let _ = handle
+                        .update(move |t: &mut PixelPassTray| t.status = status)
+                        .await;
+                }
+            });
+        })
+        .ok()?;
+
+    Some(TrayHandle {
+        actions: action_rx,
+        status_tx,
+        registered,
+        last_sent: None,
+    })
+}