docs(readme): document --relay / PIXELPASS_RELAY

Add a Relay section covering the flag and env-var forms, precedence,
the GUI-child forwarding, and the same-relay-on-both-ends requirement.

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

Cargo.toml

@@ -34,9 +34,32 @@ ureq = { version = "3", default-features = false, features = ["rustls"] }
 toml = "1"
 chrono = { version = "0.4", default-features = false, features = ["clock", "serde"] }
 eframe = { version = "0.34.2", default-features = false, features = ["glow", "default_fonts", "wayland", "x11"], optional = true }
-tray-icon = { version = "0.24.0", optional = true }
-notify-rust = { version = "4.17.0", optional = true }
-gtk = { version = "0.18.2", optional = true }
+# 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 }
+# Hand-rolled windowing stack for the GUI (replaces eframe::run_native) so we
+# can drop the OS window on "hide to tray" — the only way to truly hide a
+# toplevel on Wayland — and recreate it on Show. All of these are already pulled
+# in transitively by eframe; making them direct adds no new crates to vet.
+# eframe is kept for its egui re-export + icon_data PNG decoder. egui_glow needs
+# its (non-default) `winit` feature for the `EguiGlow` integration type; eframe
+# pulls egui_glow but without that feature, so we enable it here.
+egui_glow = { version = "0.34.2", default-features = false, features = ["winit", "wayland", "x11"], optional = true }
+# winit's default set minus `wayland-csd-adwaita`: KWin (and most desktop
+# compositors) draw server-side decorations, and eframe never enabled CSD
+# either, so dropping it keeps the dependency tree identical to before (no
+# sctk-adwaita / tiny-skia / ttf-parser pulled in just for a fallback titlebar).
+winit = { version = "0.30", default-features = false, features = ["rwh_06", "x11", "wayland", "wayland-dlopen"], optional = true }
+glutin = { version = "0.32", optional = true }
+glutin-winit = { version = "0.5", optional = true }
+# QR-encode the host ticket so a phone (or a second laptop with a webcam) can
+# pick it up without typing 140 chars. default-features = false to skip the
+# `image` crate dep tree — we render the modules to an `egui::ColorImage`
+# directly.
+qrcode = { version = "0.14", default-features = false, optional = true }
 
 [profile.release]
 lto = "thin"
@@ -46,4 +69,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:tray-icon", "dep:notify-rust", "dep:gtk"]
+gui = ["dep:eframe", "dep:notify-rust", "dep:ksni", "dep:egui_glow", "dep:winit", "dep:glutin", "dep:glutin-winit", "dep:qrcode"]

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.

README.md

@@ -83,8 +83,15 @@ pixelpass --gui
 ```
 
 Host: pick quality / max-viewers / options, click **Start hosting**, and the
-share code appears with a copy button alongside a live viewer count. View:
-paste a code, pick mpv or VLC, click **Connect** and the player launches.
+share code appears with a copy button. Connected viewers are listed with a
+**Kick** button each, and a desktop notification fires as they join or leave.
+View: paste a code, pick mpv or VLC, click **Connect** and the player launches.
+
+A system-tray icon shows current status. **Settings → "Keep running in the
+tray when I close the window"** (off by default) makes the close button hide
+the window — truly, by dropping it — while any active stream keeps running in
+the child; reopen it from the tray. (Plain close still quits when the option is
+off, or when no system tray is present.)
 
 The window is a thin driver — it runs the same headless `pixelpass` as a
 child process and reads its event stream, so the GUI is purely additive and
@@ -216,6 +223,25 @@ measured_at = "2026-05-21T20:41:16Z"
 - Skip is sticky — once you skip the test, pixelpass won't ask again
   unless you reconfigure.
 
+## Relay
+
+By default pixelpass uses iroh's bundled relay servers to coordinate the
+P2P connection (peers still hole-punch a direct UDP path when they can; the
+relay is the fallback and the rendezvous point). You can point it at a
+different relay — a self-hosted one, or n0's staging/production servers —
+with either:
+
+```bash
+pixelpass --relay https://relay.example/            # host or viewer
+PIXELPASS_RELAY=https://relay.example/ pixelpass …  # env-var form
+```
+
+The flag applies to both host and viewer and takes precedence over the
+environment variable. The env-var form is handy for the `--gui` front-end,
+since the GUI's child host/viewer processes inherit it; the `--gui --relay`
+flag form is forwarded to them too. Both ends must use the same relay to
+find each other.
+
 ## Audio
 
 By default pixelpass captures the default sink's monitor — the viewer

assets/NotoSans-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2022 The Noto Project Authors (https://github.com/notofonts/latin-greek-cyrillic)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT 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/appimage/.gitignore

@@ -0,0 +1,3 @@
+.tools/
+AppDir/
+*.AppImage

packaging/appimage/AppRun

@@ -0,0 +1,20 @@
+#!/bin/sh
+# AppRun for the PixelPass AppImage.
+#
+# PixelPass is an orchestrator: it shells out to gst-launch-1.0, pactl, and a
+# player (mpv/vlc) found on the host PATH. We prepend our own usr/bin so any
+# bundled helpers win, but the host's tools remain reachable — that's why this
+# app suits AppImage (no sandbox) better than a Flatpak.
+HERE="$(dirname "$(readlink -f "$0")")"
+export PATH="$HERE/usr/bin:$PATH"
+
+BIN="$HERE/usr/bin/pixelpass"
+
+# With no arguments and no controlling terminal — i.e. launched from a file
+# manager or the .desktop entry — open the GUI. From a terminal, or with any
+# argument (a ticket, --host, --gui, --repair, …), pass through so the CLI and
+# the interactive menu both work.
+if [ "$#" -eq 0 ] && [ ! -t 0 ]; then
+  exec "$BIN" --gui
+fi
+exec "$BIN" "$@"

packaging/appimage/README.md

@@ -0,0 +1,72 @@
+# PixelPass AppImage
+
+A "thin" AppImage: the gui-enabled `pixelpass` binary, a launcher (`AppRun`),
+and the desktop entry + icon. Run `./build-appimage.sh` to produce
+`pixelpass-<version>-x86_64.AppImage`.
+
+## Why thin
+
+`pixelpass` is an orchestrator — it links almost nothing (only `libpipewire`,
+which is excludelisted because it must match the host daemon) and instead
+**shells out** to `gst-launch-1.0`, `pactl`, and a player (`mpv`/`vlc`) found on
+the host `PATH`. The GUI's graphics libraries (`libGL`, `libwayland-*`,
+`libxkbcommon`, X11) are dlopen'd at runtime and are likewise on the AppImage
+excludelist — every desktop already has a matching set. So there is nothing
+useful to bundle, and bundling the graphics stack would only risk driver
+mismatches. The AppImage therefore carries just the binary.
+
+This also explains why PixelPass suits AppImage better than Flatpak: the
+no-sandbox model lets the bundled binary freely spawn the host's `gst-launch`,
+`pactl`, and player, which a Flatpak sandbox would block.
+
+## Host requirements
+
+The AppImage runs on any reasonably current glibc-based distro that has:
+
+- **GStreamer + plugins** — `gst-launch-1.0`/`gst-inspect-1.0` plus base,
+  good/bad/ugly, libav, and the PipeWire plugin (the binary tells you the exact
+  package names for your distro if something is missing).
+- **PipeWire** (with the PulseAudio shim, for `pactl`).
+- **A player** — `mpv` (preferred) or `vlc` — for the viewer side.
+- For X11 single-window capture: `xwininfo`.
+
+These are the same dependencies the Arch package lists; the AppImage just spares
+you the Rust toolchain.
+
+## Building for broad compatibility (lower glibc baseline)
+
+An AppImage requires a host glibc **at least as new** as the build host's. Built
+straight on a rolling distro (e.g. CachyOS, glibc 2.43) the AppImage only runs
+on equally-new systems. Build inside an older base for wider reach. The script
+honours `CARGO_TARGET_DIR`, so an isolated toolchain won't clobber your host's
+`target/`:
+
+```sh
+# One-time: an Ubuntu 24.04 distrobox (docker or podman backend).
+distrobox create --yes --image ubuntu:24.04 --name pixelpass-build
+distrobox enter pixelpass-build -- sudo apt-get update
+distrobox enter pixelpass-build -- sudo apt-get install -y \
+  build-essential cmake clang libclang-dev pkg-config \
+  libpipewire-0.3-dev libspa-0.2-dev curl ca-certificates file
+# Install rustup inside the box (edition 2024 needs rustc >= 1.85), then:
+distrobox enter pixelpass-build -- env \
+  CARGO_TARGET_DIR=~/.cache/pixelpass-ubuntu/target \
+  ./packaging/appimage/build-appimage.sh
+```
+
+**Why Ubuntu 24.04 and not something older:** PixelPass's `pipewire` crate
+binds the system's PipeWire headers via bindgen, and anything older than ~PW 1.0
+(e.g. Ubuntu 22.04's 0.3.48) fails to compile (missing struct fields / wrong
+types). And since PixelPass *is* a PipeWire/portal/Wayland app, it can only run
+on distros new enough to have modern PipeWire anyway — so an ancient glibc base
+buys nothing. 24.04 (glibc 2.39, PW 1.0.5) is the sweet spot.
+
+The 24.04-built binary's baseline is **glibc 2.39** — and the only 2.39 symbols
+are two *weak* `pidfd_*` references from Rust std's process spawning (everything
+else is ≤ 2.35). That covers Ubuntu 24.04+, Debian 13+, Fedora 40+, and current
+rolling distros.
+
+## Caveats
+
+- **Hardware encode (VAAPI `vah264enc`)** uses the host GPU driver; it can't be
+  bundled. The software path (`--no-hwencode`, x264) always works.

packaging/appimage/build-appimage.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Build a "thin" PixelPass AppImage: the gui-enabled release binary plus only
+# its non-excludelisted shared libraries. The graphics stack (libGL, wayland,
+# xkbcommon, X11) is intentionally left to the host — those libs are on the
+# AppImage excludelist because they must match the host driver — and the
+# runtime tools PixelPass shells out to (gst-launch-1.0, pactl, mpv/vlc) are
+# expected on the host PATH, the same contract the Arch package documents.
+#
+# Usage: packaging/appimage/build-appimage.sh
+# Output: packaging/appimage/pixelpass-x86_64.AppImage
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo="$(cd "$here/../.." && pwd)"
+tools="$here/.tools"
+appdir="$here/AppDir"
+mkdir -p "$tools"
+
+# linuxdeploy is itself an AppImage; run it without FUSE so this works on hosts
+# (and CI) that lack libfuse2.
+export APPIMAGE_EXTRACT_AND_RUN=1
+# Embed the version from Cargo.toml into the AppImage filename metadata.
+VERSION="$(grep -m1 '^version' "$repo/Cargo.toml" | sed -E 's/.*"(.*)".*/\1/')"
+export VERSION
+
+echo ">> building release binary (--features gui)"
+( cd "$repo" && cargo build --release --features gui )
+# Honour CARGO_TARGET_DIR so an isolated build (e.g. inside an old-glibc
+# distrobox) doesn't have to clobber the host's target/.
+bin="${CARGO_TARGET_DIR:-$repo/target}/release/pixelpass"
+
+echo ">> fetching linuxdeploy"
+ld="$tools/linuxdeploy-x86_64.AppImage"
+if [ ! -x "$ld" ]; then
+  curl -fL --retry 3 -o "$ld" \
+    "https://github.com/linuxdeploy/linuxdeploy/releases/download/continuous/linuxdeploy-x86_64.AppImage"
+  chmod +x "$ld"
+fi
+
+echo ">> assembling AppDir"
+rm -rf "$appdir"
+mkdir -p "$appdir/usr/bin"
+install -m755 "$bin" "$appdir/usr/bin/pixelpass"
+
+echo ">> running linuxdeploy (bundles libs, builds the AppImage)"
+# -e: analyse this binary for libraries to bundle (only libpipewire et al. that
+#     aren't excludelisted will be copied; glibc + graphics libs are skipped).
+# -d/-i: desktop entry + icon for desktop integration.
+# --custom-apprun: our launcher that opens --gui from a file manager.
+( cd "$here" && OUTPUT="pixelpass-${VERSION}-x86_64.AppImage" "$ld" \
+    --appdir "$appdir" \
+    -e "$bin" \
+    -d "$repo/assets/pixelpass.desktop" \
+    -i "$repo/assets/pixelpass-256.png" \
+    --icon-filename pixelpass \
+    --custom-apprun "$here/AppRun" \
+    --output appimage )
+
+echo ">> done: $here/pixelpass-${VERSION}-x86_64.AppImage"

packaging/arch/.gitignore

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

packaging/arch/PKGBUILD

@@ -0,0 +1,65 @@
+# 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' 'OFL-1.1')
+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"
+  install -Dm0644 assets/NotoSans-OFL.txt \
+    "$pkgdir/usr/share/licenses/$pkgname/NotoSans-OFL.txt"
+}

src/cli.rs

@@ -68,6 +68,13 @@ pub struct Cli {
     pub port: u16,
 
     // ── global ────────────────────────────────────────────────────────
+    /// Relay server URL to use instead of the bundled defaults, e.g.
+    /// `https://relay.example/`. Applies to both host and viewer. Falls back
+    /// to the `PIXELPASS_RELAY` environment variable. Use this to get off the
+    /// pre-release default relays or to point at a self-hosted relay.
+    #[arg(long, value_name = "URL")]
+    pub relay: Option<String>,
+
     /// Launch the graphical front-end (a window with Host/View controls)
     /// instead of the terminal menu. Requires a build with `--features gui`.
     #[arg(long)]
@@ -140,12 +147,16 @@ pub struct HostOpts {
     pub no_hwencode: bool,
     pub max_viewers: Option<u32>,
     pub interactive: bool,
+    /// Relay override (resolved from `--relay` / `PIXELPASS_RELAY`); None = defaults.
+    pub relay: Option<String>,
 }
 
 #[derive(Debug, Clone)]
 pub struct ViewerOpts {
     pub port: u16,
     pub interactive: bool,
+    /// Relay override (resolved from `--relay` / `PIXELPASS_RELAY`); None = defaults.
+    pub relay: Option<String>,
 }
 
 impl Cli {
@@ -163,10 +174,15 @@ impl Cli {
             no_hwencode: self.no_hwencode,
             max_viewers: self.max_viewers,
             interactive,
+            relay: crate::common::endpoint::relay_override(self.relay.as_deref()),
         }
     }
 
     pub fn into_viewer_opts(self, interactive: bool) -> ViewerOpts {
-        ViewerOpts { port: self.port, interactive }
+        ViewerOpts {
+            port: self.port,
+            interactive,
+            relay: crate::common::endpoint::relay_override(self.relay.as_deref()),
+        }
     }
 }

src/common/bandwidth.rs

@@ -65,9 +65,41 @@ pub fn measure_upstream_blocking() -> Result<Measurement> {
 /// via SAFETY_FACTOR) into a recommended viewer count. Floors to at least 1.
 pub fn recommended_max_viewers(safe_mbps: f64, bitrate_kbps: u32) -> u32 {
     let per_viewer_mbps = (bitrate_kbps as f64) / 1000.0;
-    if per_viewer_mbps <= 0.0 {
+    // Guard non-finite / non-positive inputs (only reachable from a corrupted
+    // config): a NaN safe_mbps would cast to 0 and an infinite one to u32::MAX,
+    // both of which break the "at least 1" contract.
+    if !safe_mbps.is_finite() || safe_mbps <= 0.0 || per_viewer_mbps <= 0.0 {
         return 1;
     }
     let n = (safe_mbps / per_viewer_mbps).floor();
     if n < 1.0 { 1 } else { n as u32 }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::recommended_max_viewers;
+
+    #[test]
+    fn divides_bandwidth_by_per_viewer_bitrate() {
+        // 8 Mbps safe / 2 Mbps each = 4 viewers.
+        assert_eq!(recommended_max_viewers(8.0, 2000), 4);
+        // Floors the fractional part: 7.9 / 2 = 3.95 -> 3.
+        assert_eq!(recommended_max_viewers(7.9, 2000), 3);
+    }
+
+    #[test]
+    fn floors_to_at_least_one() {
+        // Not even enough for one viewer still allows one (best effort).
+        assert_eq!(recommended_max_viewers(0.5, 2000), 1);
+        // Zero / unknown bitrate can't size a budget; floor to one.
+        assert_eq!(recommended_max_viewers(8.0, 0), 1);
+    }
+
+    #[test]
+    fn degenerate_inputs_floor_to_one() {
+        // A corrupted config must not yield 0 (NaN) or u32::MAX (Inf).
+        assert_eq!(recommended_max_viewers(f64::NAN, 2000), 1);
+        assert_eq!(recommended_max_viewers(f64::INFINITY, 2000), 1);
+        assert_eq!(recommended_max_viewers(-5.0, 2000), 1);
+    }
+}

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
-//! preferences (default player, default bitrate, etc.) can hang off the
-//! same file under their own `[section]`.
+//! It tracks the bandwidth pre-flight result and the GUI's preferences.
+//! Further settings can hang off the same file under their own `[section]`.
 
 use anyhow::{Context, Result};
 use chrono::{DateTime, Utc};
@@ -16,6 +15,36 @@ 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, 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,
+    /// When true, the host screen renders a QR-code panel for the ticket.
+    /// Defaults to true; the toggle exists for users who prefer the plain
+    /// text-only host screen.
+    #[serde(default = "default_true")]
+    pub show_qr: bool,
+}
+
+impl Default for GuiSettings {
+    fn default() -> Self {
+        Self {
+            close_to_tray: false,
+            show_qr: true,
+        }
+    }
+}
+
+fn default_true() -> bool {
+    true
 }
 
 /// Result of the first-run upstream measurement.
@@ -37,18 +66,15 @@ pub struct BandwidthEntry {
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "lowercase")]
+#[derive(Default)]
 pub enum BandwidthStatus {
+    #[default]
     Unmeasured,
     Measured,
     Skipped,
     Failed,
 }
 
-impl Default for BandwidthStatus {
-    fn default() -> Self {
-        Self::Unmeasured
-    }
-}
 
 fn default_status() -> BandwidthStatus {
     BandwidthStatus::Unmeasured

src/common/deps.rs

@@ -85,20 +85,20 @@ fn install_hint_for_bin(bin: &str) -> String {
     let distro = detect_distro();
     let pkg = match bin {
         "gst-launch-1.0" | "gst-inspect-1.0" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "gstreamer gst-plugins-base",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "gstreamer gst-plugins-base",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "gstreamer1.0-tools",
             Some("fedora" | "nobara") => "gstreamer1 gstreamer1-plugins-base-tools",
             _ => "gstreamer + tools",
         },
         "pactl" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "libpulse",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "libpulse",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "pulseaudio-utils",
             Some("fedora" | "nobara") => "pulseaudio-utils",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "pulseaudio-utils",
             _ => "pulseaudio-utils (provides `pactl`)",
         },
         "xwininfo" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "xorg-xwininfo",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "xorg-xwininfo",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "x11-utils",
             Some("fedora" | "nobara") => "xorg-x11-utils",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "xwininfo",
@@ -113,56 +113,56 @@ fn install_hint_for_gst_element(name: &str) -> String {
     let distro = detect_distro();
     let pkg = match name {
         "pipewiresrc" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "gst-plugin-pipewire",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "gst-plugin-pipewire",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "gstreamer1.0-pipewire",
             Some("fedora" | "nobara") => "pipewire-gstreamer",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "pipewire-gstreamer",
             _ => "the GStreamer PipeWire plugin",
         },
         "vah264enc" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "gst-plugin-va",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "gst-plugin-va",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "gstreamer1.0-plugins-bad",
             Some("fedora" | "nobara") => "gstreamer1-plugins-bad-free",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "gstreamer-plugins-bad",
             _ => "the GStreamer VA-API plugin (requires an H.264-capable GPU; almost all modern GPUs)",
         },
         "x264enc" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "gst-plugins-ugly",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "gst-plugins-ugly",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "gstreamer1.0-plugins-ugly",
             Some("fedora" | "nobara") => "gstreamer1-plugins-ugly",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "gstreamer-plugins-ugly",
             _ => "the GStreamer x264 plugin (plugins-ugly)",
         },
         "ximagesrc" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "gst-plugins-good",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "gst-plugins-good",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "gstreamer1.0-plugins-good",
             Some("fedora" | "nobara") => "gstreamer1-plugins-good",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "gstreamer-plugins-good",
             _ => "the GStreamer X11 plugin (plugins-good)",
         },
         "videoscale" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "gst-plugins-base",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "gst-plugins-base",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "gstreamer1.0-plugins-base",
             Some("fedora" | "nobara") => "gstreamer1-plugins-base",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "gstreamer-plugins-base",
             _ => "the GStreamer plugins-base set",
         },
         "h264parse" | "mpegtsmux" | "aacparse" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "gst-plugins-bad",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "gst-plugins-bad",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "gstreamer1.0-plugins-bad",
             Some("fedora" | "nobara") => "gstreamer1-plugins-bad-free",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "gstreamer-plugins-bad",
             _ => "the GStreamer plugins-bad set",
         },
         "pulsesrc" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "gst-plugins-good",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "gst-plugins-good",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "gstreamer1.0-pulseaudio",
             Some("fedora" | "nobara") => "gstreamer1-plugins-good",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "gstreamer-plugins-good",
             _ => "the GStreamer PulseAudio plugin",
         },
         "avenc_aac" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "gst-libav",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "gst-libav",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "gstreamer1.0-libav",
             Some("fedora" | "nobara") => "gstreamer1-libav",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "gstreamer-libav",
@@ -175,7 +175,7 @@ fn install_hint_for_gst_element(name: &str) -> String {
 
 fn install_command(distro: &Option<String>, pkg: &str) -> String {
     let cmd = match distro.as_deref() {
-        Some("arch" | "cachyos" | "manjaro" | "endeavouros") => format!("sudo pacman -S {pkg}"),
+        Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => format!("sudo pacman -S {pkg}"),
         Some("debian" | "ubuntu" | "pop" | "linuxmint") => format!("sudo apt install {pkg}"),
         Some("fedora" | "nobara") => format!("sudo dnf install {pkg}"),
         Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => format!("sudo zypper install {pkg}"),

src/common/endpoint.rs

@@ -0,0 +1,42 @@
+//! Shared iroh endpoint construction for the host and viewer.
+//!
+//! Both sides bind an endpoint with the same ALPN; the only knob is the relay.
+
+use std::str::FromStr;
+
+use anyhow::{Context, Result};
+use iroh::endpoint::presets;
+use iroh::{Endpoint, RelayMap, RelayMode, RelayUrl};
+
+use super::alpn::ALPN;
+
+/// Environment variable consulted when `--relay` isn't passed. Lets the GUI's
+/// child processes and scripted runs inherit a relay choice without a flag.
+pub const RELAY_ENV: &str = "PIXELPASS_RELAY";
+
+/// Resolve the relay override: explicit `--relay` wins, else `PIXELPASS_RELAY`,
+/// else `None` (use the bundled defaults).
+pub fn relay_override(flag: Option<&str>) -> Option<String> {
+    flag.map(str::to_owned)
+        .or_else(|| std::env::var(RELAY_ENV).ok().filter(|s| !s.trim().is_empty()))
+}
+
+/// Bind the iroh endpoint with our ALPN.
+///
+/// With no `relay` override we use [`presets::N0`] — n0 DNS discovery, the
+/// library's default relays, and the chosen crypto provider. With an override
+/// we keep all of that but swap in a single custom relay via
+/// [`RelayMode::Custom`]; this is how a user gets off the rc's bundled
+/// (canary-grade) relays or points at a self-hosted one. Discovery is
+/// unchanged, so peers still resolve each other by endpoint id.
+pub async fn bind(relay: Option<&str>) -> Result<Endpoint> {
+    let mut builder = Endpoint::builder(presets::N0).alpns(vec![ALPN.to_vec()]);
+
+    if let Some(url) = relay {
+        let url = RelayUrl::from_str(url)
+            .with_context(|| format!("invalid relay URL {url:?} (expected e.g. https://relay.example/)"))?;
+        builder = builder.relay_mode(RelayMode::Custom(RelayMap::from(url)));
+    }
+
+    builder.bind().await.context("failed to bind the iroh endpoint")
+}

src/common/mod.rs

@@ -2,6 +2,7 @@ pub mod alpn;
 pub mod bandwidth;
 pub mod config;
 pub mod deps;
+pub mod endpoint;
 pub mod display;
 pub mod output;
 pub mod process;

src/common/output.rs

@@ -22,7 +22,11 @@ pub fn set_json(enabled: bool) {
     JSON_ENABLED.store(enabled, Ordering::Relaxed);
 }
 
-fn json_enabled() -> bool {
+/// Whether the JSON event stream is on — i.e. we're being driven by a
+/// machine front-end (the `--gui` shell-out) rather than a human terminal.
+/// Gates features that only make sense under that front-end, like the
+/// stdin command channel the host reads `kick` requests from.
+pub fn json_enabled() -> bool {
     JSON_ENABLED.load(Ordering::Relaxed)
 }
 
@@ -42,9 +46,11 @@ pub enum Event<'a> {
         max_viewers: u32,
         max_viewers_source: &'a str,
     },
-    /// A new viewer joined.
+    /// A viewer joined. `id` is the viewer's endpoint id; `active` is the new
+    /// total after the join.
     ViewerJoined { id: &'a str, active: u32, max: u32 },
-    /// A viewer disconnected.
+    /// A viewer left — disconnected on their own or kicked by the host. `id`
+    /// is the viewer's endpoint id; `active` is the new total after.
     ViewerLeft { id: &'a str, active: u32, max: u32 },
     /// Capture pipeline lifecycle (spawned on first viewer, torn down on last).
     Capture { state: CaptureState },

src/common/signal.rs

@@ -7,10 +7,17 @@ pub fn install_ctrl_c() -> CancellationToken {
     let token = CancellationToken::new();
     let trigger = token.clone();
     tokio::spawn(async move {
-        if tokio::signal::ctrl_c().await.is_ok() {
-            tracing::info!("ctrl-c received, shutting down");
-            trigger.cancel();
+        if let Err(e) = tokio::signal::ctrl_c().await {
+            // Installing the handler failed — ctrl-c won't trigger a graceful
+            // shutdown. Say so instead of failing silently; the user can still
+            // kill the process, and the second-ctrl-c arm below would only fail
+            // the same way, so bail out of the task.
+            tracing::warn!("could not install ctrl-c handler: {e}; ctrl-c won't shut down cleanly");
+            return;
         }
+        tracing::info!("ctrl-c received, shutting down");
+        trigger.cancel();
+
         if tokio::signal::ctrl_c().await.is_ok() {
             tracing::warn!("second ctrl-c — exiting now");
             std::process::exit(130);

src/gui/child.rs

@@ -6,17 +6,18 @@
 //! egui app drains each frame. stderr is captured into a small ring so a
 //! failed launch (e.g. a missing gst plugin) can be surfaced in the window.
 
-use std::io::{BufRead, BufReader};
-use std::process::{Child, Command, Stdio};
+use std::io::{BufRead, BufReader, Write};
+use std::process::{Child, ChildStdin, Command, Stdio};
 use std::sync::mpsc::Receiver;
 use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
-use eframe::egui;
 use nix::sys::signal::{Signal, kill};
 use nix::unistd::Pid;
 use serde::Deserialize;
 
+use super::Waker;
+
 /// One parsed event from the child's stdout. Owned mirror of
 /// [`crate::common::output::Event`] (which borrows for emit); kept separate so
 /// the wire format and the parser can evolve independently.
@@ -66,26 +67,36 @@ pub enum CaptureState {
 const STDERR_TAIL_MAX: usize = 60;
 
 pub struct ChildProc {
-    child: Child,
+    /// `Some` while the child is owned here; `Drop` takes it to hand off to a
+    /// detached reaper thread (see the `Drop` impl).
+    child: Option<Child>,
     pub rx: Receiver<ChildEvent>,
     stderr_tail: Arc<Mutex<Vec<String>>>,
-    stdin: std::process::ChildStdin,
+    /// Write end of the child's stdin, for the line-based command channel
+    /// (see [`ChildProc::send_command`]). `None` once it's been closed.
+    stdin: Option<ChildStdin>,
 }
 
 impl ChildProc {
-    /// Spawn `pixelpass <args>` as a child, wiring up the event reader. `ctx`
-    /// is repainted whenever an event arrives so the UI updates live.
-    pub fn spawn(args: &[String], ctx: egui::Context) -> std::io::Result<Self> {
+    /// Spawn `pixelpass <args>` as a child, wiring up the event reader. The
+    /// `waker` is pinged whenever an event arrives so the UI thread wakes to
+    /// drain it — this wakes the winit event loop directly (via an
+    /// `EventLoopProxy`), so it works even when the window is hidden to the tray
+    /// and no frames are running (egui's own repaint callback would not fire
+    /// repeatedly in that idle state — see [`super::Waker`]).
+    pub fn spawn(args: &[String], waker: Waker) -> std::io::Result<Self> {
         let exe = std::env::current_exe()?;
         let mut child = Command::new(exe)
             .args(args)
+            // Piped so we can send line commands (e.g. `kick <id>`); the host
+            // only reads it when driven this way (`--output json`).
             .stdin(Stdio::piped())
             .stdout(Stdio::piped())
             .stderr(Stdio::piped())
             .spawn()?;
 
+        let stdin = child.stdin.take();
         let (tx, rx) = std::sync::mpsc::channel();
-        let stdin = child.stdin.take().expect("stdin piped");
         let stdout = child.stdout.take().expect("stdout piped");
         std::thread::spawn(move || {
             let reader = BufReader::new(stdout);
@@ -98,9 +109,14 @@ impl ChildProc {
                     if tx.send(ev).is_err() {
                         break; // app gone
                     }
-                    ctx.request_repaint();
+                    waker.wake();
                 }
             }
+            // stdout closed → the child has exited (player closed, connection
+            // ended, or a failed launch). Wake once more so the UI reaps it and
+            // clears the "running" view, even if no final event was emitted and
+            // the window is hidden to the tray.
+            waker.wake();
         });
 
         let stderr_tail = Arc::new(Mutex::new(Vec::<String>::new()));
@@ -119,55 +135,64 @@ impl ChildProc {
         });
 
         Ok(Self {
-            child,
+            child: Some(child),
             rx,
             stderr_tail,
             stdin,
         })
     }
 
+    /// Send one newline-terminated command to the child over its stdin (the
+    /// host parses these as `kick <endpoint-id>`). Best-effort: a closed pipe
+    /// (child already gone) just drops the command.
+    pub fn send_command(&mut self, cmd: &str) {
+        let Some(stdin) = self.stdin.as_mut() else {
+            return;
+        };
+        if let Err(e) = writeln!(stdin, "{cmd}") {
+            tracing::warn!("failed to send command to host child: {e}");
+            self.stdin = None; // pipe is dead; stop trying
+        }
+    }
+
     /// Whether the child is still running.
     pub fn is_alive(&mut self) -> bool {
-        matches!(self.child.try_wait(), Ok(None))
+        matches!(self.child.as_mut().map(Child::try_wait), Some(Ok(None)))
     }
 
     /// The last captured stderr lines, joined — for error display.
     pub fn stderr_tail(&self) -> String {
         self.stderr_tail.lock().unwrap().join("\n")
     }
-
-    /// Send a newline-terminated command to the child.
-    pub fn send_command(&mut self, cmd: &str) {
-        use std::io::Write;
-        if let Err(e) = writeln!(self.stdin, "{cmd}") {
-            tracing::warn!("failed to send command to child: {e}");
-        }
-    }
-
-    /// Gracefully stop the child: SIGINT (so the host runs its ctrl-c teardown
-    /// — tears down capture, closes the endpoint), with a ~2 s grace period
-    /// before a hard kill. Idempotent.
-    pub fn stop(&mut self) {
-        if matches!(self.child.try_wait(), Ok(Some(_))) {
-            return; // already exited
-        }
-        let _ = kill(Pid::from_raw(self.child.id() as i32), Signal::SIGINT);
-        for _ in 0..40 {
-            if matches!(self.child.try_wait(), Ok(Some(_))) {
-                return;
-            }
-            std::thread::sleep(Duration::from_millis(50));
-        }
-        let _ = self.child.kill();
-        let _ = self.child.wait();
-    }
 }
 
 impl Drop for ChildProc {
     fn drop(&mut self) {
-        // Closing the window (dropping the app, hence the session) must not
-        // orphan a live host child streaming to viewers.
-        self.stop();
+        // Leaving a host/viewer screen, or closing the window, must not orphan
+        // a live child — but it must also not *block*. eframe runs this drop
+        // synchronously while it destroys the window, so a grace-period wait
+        // here freezes the window mid-close: the first click looks like it did
+        // nothing (the stream just drops) and the window only goes away on a
+        // second click. So SIGINT now — synchronously, so the host always gets
+        // its ctrl-c teardown (capture down, endpoint closed) even if we exit
+        // right after — then reap on a detached thread instead of waiting.
+        let Some(mut child) = self.child.take() else {
+            return;
+        };
+        if matches!(child.try_wait(), Ok(Some(_))) {
+            return; // already exited; nothing to signal or reap
+        }
+        let _ = kill(Pid::from_raw(child.id() as i32), Signal::SIGINT);
+        std::thread::spawn(move || {
+            for _ in 0..40 {
+                if matches!(child.try_wait(), Ok(Some(_))) {
+                    return;
+                }
+                std::thread::sleep(Duration::from_millis(50));
+            }
+            let _ = child.kill();
+            let _ = child.wait();
+        });
     }
 }
 
@@ -222,7 +247,7 @@ mod tests {
     }
 
     #[test]
-    fn viewer_events_round_trips() {
+    fn viewer_join_leave_round_trip() {
         assert!(matches!(
             parse(Event::ViewerJoined { id: "nodeXYZ", active: 2, max: 4 }),
             ChildEvent::ViewerJoined { id, active: 2, max: 4 } if id == "nodeXYZ"

src/gui/tray.rs

@@ -0,0 +1,257 @@
+//! 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 winit's event channel and a status channel:
+//!
+//!   * tray → app: a [`super::UserEvent::Tray`] carrying a [`TrayAction`]
+//!     (Show / Quit), pushed through the [`winit::event_loop::EventLoopProxy`].
+//!     Using the proxy (not egui's repaint) is essential: a tray click must
+//!     wake the winit loop even when the window has been **dropped** (hidden to
+//!     tray), so the loop can recreate it.
+//!   * 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 ksni::TrayMethods;
+use winit::event_loop::EventLoopProxy;
+
+use super::UserEvent;
+
+/// What the user picked from the tray icon or its menu (tray thread → app),
+/// delivered as a [`UserEvent::Tray`].
+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 {
+    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>,
+    /// Wakes the winit loop and delivers the action — works even when the
+    /// window has been dropped to the tray (no egui frame is running then).
+    proxy: EventLoopProxy<UserEvent>,
+    /// Shared with [`TrayHandle`]; kept in sync with the watcher's presence via
+    /// the `watcher_online`/`watcher_offline` callbacks so the app never diverts
+    /// a close to a tray that has since disappeared.
+    registered: Arc<AtomicBool>,
+}
+
+impl PixelPassTray {
+    fn notify(&self, action: TrayAction) {
+        let _ = self.proxy.send_event(UserEvent::Tray(action));
+    }
+}
+
+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);
+    }
+
+    /// The StatusNotifierWatcher came back (e.g. the panel restarted). Mark the
+    /// tray live again so close-to-tray can resume hiding the window.
+    fn watcher_online(&self) {
+        self.registered.store(true, Ordering::Release);
+    }
+
+    /// The watcher went away (panel restart, tray plugin disabled, …). Clear the
+    /// flag so a subsequent close quits normally instead of destroying the window
+    /// into a tray that no longer exists, and force the window back now in case
+    /// it was already hidden (otherwise it'd be stranded with no way to restore).
+    /// Returning `true` keeps the service alive so it re-registers if the watcher
+    /// returns.
+    fn watcher_offline(&self, reason: ksni::OfflineReason) -> bool {
+        tracing::warn!("tray: StatusNotifierWatcher offline ({reason:?}); restoring window");
+        self.registered.store(false, Ordering::Release);
+        self.notify(TrayAction::Show);
+        true
+    }
+
+    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(proxy: EventLoopProxy<UserEvent>) -> Option<TrayHandle> {
+    let icon = load_icon()?;
+    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,
+                    proxy,
+                    registered: registered_thread.clone(),
+                };
+                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 {
+        status_tx,
+        registered,
+        last_sent: None,
+    })
+}

src/host/audio.rs

@@ -141,7 +141,10 @@ impl Routing {
     /// Stop the stream router (if any), then unload loopback (if still
     /// loaded), then unload the null-sink. Order matters: PipeWire can
     /// leave zombie links if you destroy a sink with active inputs.
-    pub fn shutdown(mut self) {
+    ///
+    /// Every step is a `take()`, so this is idempotent — `Drop` calls it again
+    /// as a backstop and the second run is a no-op.
+    fn cleanup(&mut self) {
         if let Some(router) = self.stream_router.take() {
             router.shutdown();
         }
@@ -155,22 +158,17 @@ impl Routing {
             unload_module(id);
         }
     }
+
+    /// Consume the routing and tear it all down now. `Drop` is the backstop;
+    /// the real work lives in [`cleanup`](Self::cleanup).
+    pub fn shutdown(mut self) {
+        self.cleanup();
+    }
 }
 
 impl Drop for Routing {
     fn drop(&mut self) {
-        if let Some(router) = self.stream_router.take() {
-            router.shutdown();
-        }
-        if let Some(task) = self.event_task.take() {
-            task.abort();
-        }
-        if let Some(id) = self.loopback_module.lock().unwrap().take() {
-            unload_module(id);
-        }
-        if let Some(id) = self.sink_module.take() {
-            unload_module(id);
-        }
+        self.cleanup();
     }
 }
 

src/host/mod.rs

@@ -7,29 +7,33 @@ mod wayland;
 mod x11;
 
 use anyhow::{Result, bail};
-use iroh::endpoint::{Connection, presets};
+use iroh::endpoint::Connection;
 use iroh::{Endpoint, EndpointAddr};
 use iroh_tickets::endpoint::EndpointTicket;
 use std::collections::HashMap;
 use std::time::Duration;
-use tokio::io::{AsyncBufReadExt, BufReader};
 use tokio::sync::{mpsc, oneshot};
 use tokio_util::sync::CancellationToken;
 
 use crate::cli::HostOpts;
 use crate::common::{
-    alpn::ALPN, bandwidth, config, config::BandwidthStatus, deps, display::DisplayServer, output,
+    bandwidth, config, config::BandwidthStatus, deps, display::DisplayServer, endpoint, output,
     signal, tunnel,
 };
 
 use self::pipeline::CaptureHandle;
 use self::quality::EffectiveQuality;
 
-/// Messages from per-viewer tasks to the capture supervisor.
+/// Messages from per-viewer tasks (and the GUI command channel) to the
+/// capture supervisor.
+// The shared `Viewer` suffix is the point — these are all viewer lifecycle
+// messages — so keep the descriptive names.
+#[allow(clippy::enum_variant_names)]
 enum SupervisorMsg {
-    /// A new viewer wants in. Supervisor replies with the local capture
-    /// HTTP port to connect to, or an error string if the host is full or
-    /// capture spawn failed.
+    /// A new viewer wants in. Supervisor replies with the local capture HTTP
+    /// port to connect to, or an error string if the host is full or capture
+    /// spawn failed. `cancel` is the viewer's own token — the supervisor keeps
+    /// it so a later `KickViewer` can tear this viewer's stream down.
     AddViewer {
         id: String,
         cancel: CancellationToken,
@@ -38,7 +42,9 @@ enum SupervisorMsg {
     /// A viewer's session ended. Supervisor decrements the count and tears
     /// down capture if it just hit zero.
     RemoveViewer { id: String },
-    /// Request to kick a specific viewer.
+    /// Host asked (via the GUI command channel) to disconnect a viewer by
+    /// endpoint id. Cancels that viewer's token; the normal teardown path then
+    /// emits the `ViewerLeft`.
     KickViewer { id: String },
 }
 
@@ -68,10 +74,7 @@ pub async fn run(opts: HostOpts) -> Result<()> {
 
     let cancel = signal::install_ctrl_c();
 
-    let endpoint = Endpoint::builder(presets::N0)
-        .alpns(vec![ALPN.to_vec()])
-        .bind()
-        .await?;
+    let endpoint = endpoint::bind(opts.relay.as_deref()).await?;
 
     // Relay-only ticket: wait for the home relay to connect, then keep only
     // the endpoint id + relay URL and drop the direct IP candidates. The relay
@@ -121,16 +124,14 @@ pub async fn run(opts: HostOpts) -> Result<()> {
         sup_rx,
     ));
 
-    // Stdin listener for "kick <id>"
-    let stdin_sup_tx = sup_tx.clone();
-    tokio::spawn(async move {
-        let mut lines = BufReader::new(tokio::io::stdin()).lines();
-        while let Ok(Some(line)) = lines.next_line().await {
-            if let Some(id) = line.strip_prefix("kick ") {
-                let _ = stdin_sup_tx.send(SupervisorMsg::KickViewer { id: id.trim().to_string() }).await;
-            }
-        }
-    });
+    // Command channel for the GUI front-end: read `kick <endpoint-id>` lines
+    // off stdin. Only when machine-driven (`--output json`) — a human host has
+    // nothing to type here, and we don't want to swallow terminal input. Runs
+    // on a plain OS thread (not a tokio task) so a read parked on stdin can't
+    // hold up runtime shutdown on Ctrl+C; the thread dies with the process.
+    if output::json_enabled() {
+        spawn_kick_listener(sup_tx.clone());
+    }
 
     accept_loop(&endpoint, sup_tx.clone(), cancel.clone()).await;
 
@@ -178,11 +179,18 @@ async fn handle_peer(
     cancel: CancellationToken,
 ) {
     let remote = conn.remote_id();
-    let id_str = remote.to_string();
+    let id = remote.to_string();
+    // This viewer's own kill switch: the supervisor holds a clone so a `kick`
+    // can cancel it, and the stream select! below watches it.
     let peer_cancel = CancellationToken::new();
 
     let (reply_tx, reply_rx) = oneshot::channel();
-    if sup_tx.send(SupervisorMsg::AddViewer { id: id_str.clone(), cancel: peer_cancel.clone(), reply: reply_tx }).await.is_err() {
+    let add = SupervisorMsg::AddViewer {
+        id: id.clone(),
+        cancel: peer_cancel.clone(),
+        reply: reply_tx,
+    };
+    if sup_tx.send(add).await.is_err() {
         tracing::warn!(%remote, "supervisor channel closed; dropping peer");
         return;
     }
@@ -203,7 +211,7 @@ async fn handle_peer(
         Ok(s) => s,
         Err(e) => {
             tracing::warn!(%remote, "accept_bi failed: {e:#}");
-            let _ = sup_tx.send(SupervisorMsg::RemoveViewer { id: id_str }).await;
+            let _ = sup_tx.send(SupervisorMsg::RemoveViewer { id }).await;
             return;
         }
     };
@@ -214,7 +222,7 @@ async fn handle_peer(
         Ok(t) => t,
         Err(e) => {
             tracing::warn!(%remote, "connect_to_capture failed: {e:#}");
-            let _ = sup_tx.send(SupervisorMsg::RemoveViewer { id: id_str }).await;
+            let _ = sup_tx.send(SupervisorMsg::RemoveViewer { id }).await;
             return;
         }
     };
@@ -234,7 +242,28 @@ async fn handle_peer(
     }
 
     eprintln!("[pixelpass] viewer disconnected: {remote}");
-    let _ = sup_tx.send(SupervisorMsg::RemoveViewer { id: id_str }).await;
+    let _ = sup_tx.send(SupervisorMsg::RemoveViewer { id }).await;
+}
+
+/// Read `kick <endpoint-id>` lines off stdin and forward them to the
+/// supervisor. Runs on a detached OS thread (see the call site for why). Ends
+/// when stdin hits EOF (the GUI closed the pipe) or the supervisor is gone.
+fn spawn_kick_listener(sup_tx: mpsc::Sender<SupervisorMsg>) {
+    use std::io::BufRead;
+    std::thread::spawn(move || {
+        let stdin = std::io::stdin();
+        for line in stdin.lock().lines().map_while(Result::ok) {
+            let Some(id) = line.trim().strip_prefix("kick ") else {
+                continue;
+            };
+            let msg = SupervisorMsg::KickViewer { id: id.trim().to_string() };
+            // blocking_send is valid here: this is a plain thread, not inside
+            // the tokio runtime. An Err means the supervisor closed — stop.
+            if sup_tx.blocking_send(msg).is_err() {
+                break;
+            }
+        }
+    });
 }
 
 /// Owns the single shared CaptureHandle and the active viewer count. Spawns
@@ -249,12 +278,15 @@ async fn supervise(
     mut rx: mpsc::Receiver<SupervisorMsg>,
 ) {
     let mut handle: Option<CaptureHandle> = None;
-    let mut count: u32 = 0;
+    // Active viewers, keyed by endpoint id, holding each one's kill switch.
+    // The count is just `viewers.len()`. (A given endpoint connecting twice is
+    // a non-case here: each viewer process uses a fresh ephemeral identity.)
     let mut viewers: HashMap<String, CancellationToken> = HashMap::new();
 
     while let Some(msg) = rx.recv().await {
         match msg {
             SupervisorMsg::AddViewer { id, cancel, reply } => {
+                let count = viewers.len() as u32;
                 if count >= max_viewers {
                     let reason =
                         format!("host is full ({count} of {max_viewers} viewers connected)");
@@ -280,18 +312,22 @@ async fn supervise(
                 }
 
                 let port = handle.as_ref().expect("handle was just set").local_port();
-                count += 1;
                 viewers.insert(id.clone(), cancel);
+                let active = viewers.len() as u32;
                 let _ = reply.send(Ok(port));
-                output::emit(output::Event::ViewerJoined { id: &id, active: count, max: max_viewers });
-                tracing::info!(active = count, cap = max_viewers, "viewer joined");
+                output::emit(output::Event::ViewerJoined { id: &id, active, max: max_viewers });
+                tracing::info!(active, cap = max_viewers, "viewer joined");
             }
             SupervisorMsg::RemoveViewer { id } => {
-                viewers.remove(&id);
-                count = count.saturating_sub(1);
-                output::emit(output::Event::ViewerLeft { id: &id, active: count, max: max_viewers });
-                tracing::info!(active = count, cap = max_viewers, "viewer left");
-                if count == 0
+                // A given viewer task only ever sends RemoveViewer once, but the
+                // map remove is the source of truth either way.
+                if viewers.remove(&id).is_none() {
+                    continue;
+                }
+                let active = viewers.len() as u32;
+                output::emit(output::Event::ViewerLeft { id: &id, active, max: max_viewers });
+                tracing::info!(active, cap = max_viewers, "viewer left");
+                if active == 0
                     && let Some(h) = handle.take()
                 {
                     tracing::info!("last viewer left — tearing down capture");
@@ -302,9 +338,14 @@ async fn supervise(
                 }
             }
             SupervisorMsg::KickViewer { id } => {
-                if let Some(cancel) = viewers.get(&id) {
-                    tracing::info!(%id, "kicking viewer");
-                    cancel.cancel();
+                match viewers.get(&id) {
+                    // Cancel the viewer's token; its handle_peer select! wakes,
+                    // sends RemoveViewer, and the leave is emitted there.
+                    Some(cancel) => {
+                        tracing::info!(%id, "kicking viewer");
+                        cancel.cancel();
+                    }
+                    None => tracing::debug!(%id, "kick for unknown/already-gone viewer"),
                 }
             }
         }

src/host/quality.rs

@@ -189,6 +189,7 @@ mod tests {
             no_hwencode: false,
             max_viewers,
             interactive: false,
+            relay: None,
         }
     }
 

src/host/serve.rs

@@ -130,8 +130,11 @@ async fn run_accept_loop(listener: TcpListener, tx: broadcast::Sender<Arc<Vec<u8
         let sock = match listener.accept().await {
             Ok((s, _)) => s,
             Err(e) => {
-                tracing::warn!("capture HTTP accept failed: {e}");
-                return;
+                // Most accept errors are transient (EMFILE from a brief FD spike,
+                // EINTR, etc.). Bailing on the first one would kill the entire
+                // viewer fanout for the rest of the session.
+                tracing::warn!("capture HTTP accept failed (continuing): {e}");
+                continue;
             }
         };
         let rx = tx.subscribe();

src/interactive.rs

@@ -13,7 +13,7 @@ pub async fn run(cli: Cli) -> Result<()> {
     let theme = ColorfulTheme::default();
     let choice = Select::with_theme(&theme)
         .with_prompt("What do you want to do?")
-        .items(&[
+        .items([
             "Host (share my screen)",
             "View (watch someone else's screen)",
         ])
@@ -112,7 +112,7 @@ fn pick_quality(theme: &ColorfulTheme) -> Result<Quality> {
 
     let choice = Select::with_theme(theme)
         .with_prompt("What quality should the viewer(s) get?")
-        .items(&items)
+        .items(items)
         .default(0)
         .interact()?;
 
@@ -138,7 +138,7 @@ pub async fn run_reconfigure() -> Result<()> {
 async fn preflight_if_needed(theme: &ColorfulTheme) {
     let mut cfg = config::load().unwrap_or_default();
     match cfg.bandwidth.status {
-        config::BandwidthStatus::Measured | config::BandwidthStatus::Skipped => return,
+        config::BandwidthStatus::Measured | config::BandwidthStatus::Skipped => (),
         config::BandwidthStatus::Unmeasured => {
             eprintln!();
             eprintln!("First-time setup");
@@ -154,7 +154,7 @@ async fn preflight_if_needed(theme: &ColorfulTheme) {
 
             let Ok(choice) = Select::with_theme(theme)
                 .with_prompt("What would you like to do?")
-                .items(&[
+                .items([
                     "Run the bandwidth test (recommended)",
                     "Skip — use the conservative default",
                 ])
@@ -180,7 +180,7 @@ async fn preflight_if_needed(theme: &ColorfulTheme) {
             eprintln!();
             let Ok(choice) = Select::with_theme(theme)
                 .with_prompt("Last bandwidth test failed. Try again?")
-                .items(&[
+                .items([
                     "Yes — retry now",
                     "No — use the conservative default",
                 ])
@@ -341,7 +341,7 @@ pub fn prompt_player() -> Result<Player> {
     let theme = ColorfulTheme::default();
     let choice = Select::with_theme(&theme)
         .with_prompt("Connected. Pick a player to launch")
-        .items(&["mpv", "VLC"])
+        .items(["mpv", "VLC"])
         .default(0)
         .interact()?;
     Ok(if choice == 0 { Player::Mpv } else { Player::Vlc })

src/main.rs

@@ -25,7 +25,7 @@ async fn main() -> Result<()> {
     if cli.gui {
         #[cfg(feature = "gui")]
         {
-            return gui::run();
+            return gui::run(cli.relay);
         }
         #[cfg(not(feature = "gui"))]
         {

src/viewer/mod.rs

@@ -1,12 +1,10 @@
 use anyhow::{Context, Result, bail};
-use iroh::Endpoint;
-use iroh::endpoint::presets;
 use iroh_tickets::endpoint::EndpointTicket;
 use std::time::Duration;
 use tokio::net::TcpListener;
 
 use crate::cli::ViewerOpts;
-use crate::common::{alpn::ALPN, output, signal};
+use crate::common::{alpn::ALPN, endpoint, output, signal};
 
 /// Cap on the initial QUIC connect. `endpoint.connect()` has no built-in
 /// deadline, so an offline host / stale code / unreachable relay otherwise
@@ -17,10 +15,7 @@ const CONNECT_TIMEOUT: Duration = Duration::from_secs(15);
 pub async fn run(ticket: EndpointTicket, opts: ViewerOpts) -> Result<()> {
     let cancel = signal::install_ctrl_c();
 
-    let endpoint = Endpoint::builder(presets::N0)
-        .alpns(vec![ALPN.to_vec()])
-        .bind()
-        .await?;
+    let endpoint = endpoint::bind(opts.relay.as_deref()).await?;
 
     let addr = ticket.endpoint_addr().clone();
     tracing::info!(remote = %addr.id, "connecting to host");
@@ -50,34 +45,41 @@ pub async fn run(ticket: EndpointTicket, opts: ViewerOpts) -> Result<()> {
             }
         },
     };
-    let (quic_send, quic_recv) = conn.open_bi().await?;
+    // Everything past the established connection runs in one block so any error
+    // (open_bi, bind, local_addr, accept) is captured rather than `?`-propagated
+    // straight out of the function — that would skip the close below and leak the
+    // endpoint. The connect-phase arms above close explicitly for the same reason.
+    let result = async {
+        let (quic_send, quic_recv) = conn.open_bi().await?;
 
-    let listener = TcpListener::bind(("127.0.0.1", opts.port)).await?;
-    let port = listener.local_addr()?.port();
-    let url = format!("http://127.0.0.1:{port}");
-    output::emit(output::Event::Connected { url: &url });
+        let listener = TcpListener::bind(("127.0.0.1", opts.port)).await?;
+        let port = listener.local_addr()?.port();
+        let url = format!("http://127.0.0.1:{port}");
+        output::emit(output::Event::Connected { url: &url });
 
-    if opts.interactive {
-        let player = crate::interactive::prompt_player()?;
-        player
-            .spawn(&url)
-            .with_context(|| "failed to launch player")?;
-        print_viewer_banner_interactive();
-    } else {
-        print_viewer_banner(&url);
+        if opts.interactive {
+            let player = crate::interactive::prompt_player()?;
+            player
+                .spawn(&url)
+                .with_context(|| "failed to launch player")?;
+            print_viewer_banner_interactive();
+        } else {
+            print_viewer_banner(&url);
+        }
+
+        tokio::select! {
+            accepted = listener.accept() => {
+                let (tcp, peer) = accepted?;
+                tracing::info!(%peer, "local viewer connected");
+                crate::common::tunnel::bridge(quic_send, quic_recv, tcp).await
+            }
+            _ = cancel.cancelled() => {
+                tracing::info!("ctrl-c received before local viewer connected");
+                Ok(())
+            }
+        }
     }
-
-    let result = tokio::select! {
-        accepted = listener.accept() => {
-            let (tcp, peer) = accepted?;
-            tracing::info!(%peer, "local viewer connected");
-            crate::common::tunnel::bridge(quic_send, quic_recv, tcp).await
-        }
-        _ = cancel.cancelled() => {
-            tracing::info!("ctrl-c received before local viewer connected");
-            Ok(())
-        }
-    };
+    .await;
 
     endpoint.close().await;
     result