feat(gui): auto-copy the host ticket on start, with a copied indicator

The CLI/interactive host auto-copies the ticket to the clipboard and says so;
the GUI host only offered a manual Copy button. Users conditioned by the CLI
assumed the GUI auto-copied too, didn't click Copy, and pasted whatever stale
ticket was already in the clipboard — then dialed a dead host and saw an
unexplained "can't connect". (Compounded by flaky Wayland clipboard / KDE
Connect sync.)

Now the ticket is copied the moment it arrives (same arboard path as the
manual button), with a green "✓ Copied to clipboard" confirmation. Auto-copy
failure is non-fatal: the code stays visible, is now selectable for manual
copy, and a hint tells the user to click Copy. Verified: clicking only Start
lands a fresh ticket in the clipboard (wl-paste).

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

Cargo.toml

@@ -33,8 +33,14 @@ arboard = { version = "3", default-features = false, features = ["wayland-data-c
 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 }
 
 [profile.release]
 lto = "thin"
 codegen-units = 1
 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"]

README.md

@@ -73,6 +73,24 @@ pixelpass <ticket>
 # then run the printed mpv command in another terminal
 ```
 
+### Graphical (optional)
+
+A small window front-end is available in builds compiled with the `gui`
+feature (see [Build](#build)):
+
+```sh
+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.
+
+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
+the capture machinery is untouched by it. On a build without the feature,
+`--gui` prints a hint to rebuild with it.
+
 ## Requirements
 
 - Linux (Wayland or X11; the backend is autodetected)
@@ -119,6 +137,14 @@ cargo build --release
 
 `rustc` 1.95+ / edition 2024.
 
+The optional graphical front-end (`pixelpass --gui`) is behind a default-off
+cargo feature so the headless build stays lean (it pulls the egui/eframe
+windowing stack). Build it with:
+
+```sh
+cargo build --release --features gui
+```
+
 ## How it works
 
 ```

src/cli.rs

@@ -13,6 +13,12 @@ pub struct Cli {
     pub ticket: Option<String>,
 
     // ── host options ──────────────────────────────────────────────────
+    /// Run as host without the interactive menu. Equivalent to picking
+    /// "Host" in the menu, but headless — for scripting and the --gui
+    /// front-end, which drives this binary as a child process.
+    #[arg(long)]
+    pub host: bool,
+
     /// Pick a single window instead of the whole screen.
     #[arg(long)]
     pub window: bool,
@@ -62,6 +68,17 @@ pub struct Cli {
     pub port: u16,
 
     // ── global ────────────────────────────────────────────────────────
+    /// Launch the graphical front-end (a window with Host/View controls)
+    /// instead of the terminal menu. Requires a build with `--features gui`.
+    #[arg(long)]
+    pub gui: bool,
+
+    /// Emit machine-readable events on stdout (one JSON object per line)
+    /// alongside the human banner on stderr. For scripts and the --gui
+    /// front-end. Currently only `json` is supported.
+    #[arg(long, value_enum, value_name = "FORMAT")]
+    pub output: Option<OutputFormat>,
+
     /// Trace-level logging.
     #[arg(long, short)]
     pub verbose: bool,
@@ -83,6 +100,12 @@ pub enum DisplayServerArg {
     X11,
 }
 
+#[derive(ValueEnum, Clone, Copy, Debug, PartialEq, Eq)]
+pub enum OutputFormat {
+    /// One JSON object per line on stdout.
+    Json,
+}
+
 /// Quality preset. Each fixed preset bundles a (max-height, bitrate, fps)
 /// tuple — resolution is a quality-per-bitrate knob, so the three only make
 /// sense together. `Auto` has no fixed tuple; it picks one of the others from

src/common/mod.rs

@@ -3,6 +3,7 @@ pub mod bandwidth;
 pub mod config;
 pub mod deps;
 pub mod display;
+pub mod output;
 pub mod process;
 pub mod signal;
 pub mod tunnel;

src/common/output.rs

@@ -0,0 +1,79 @@
+//! Machine-readable event stream for non-interactive front-ends.
+//!
+//! When enabled with `--output json`, the host and viewer emit one JSON
+//! object per line on **stdout**. The human banner and `tracing` logs stay
+//! on **stderr**, so the two streams never interleave and a parser reading
+//! stdout sees only events. Each line is flushed immediately so a front-end
+//! reading the pipe gets events live rather than in block-buffered chunks.
+//!
+//! This is the shell-out counterpart to an in-process event channel: the
+//! `--gui` front-end re-execs this binary as `pixelpass --host --output json`
+//! and parses these lines to drive its window.
+
+use std::io::Write;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use serde::Serialize;
+
+static JSON_ENABLED: AtomicBool = AtomicBool::new(false);
+
+/// Turn JSON event output on. Called once at startup from `--output json`.
+pub fn set_json(enabled: bool) {
+    JSON_ENABLED.store(enabled, Ordering::Relaxed);
+}
+
+fn json_enabled() -> bool {
+    JSON_ENABLED.load(Ordering::Relaxed)
+}
+
+/// One event in the stdout stream. Serialized as `{"event":"<tag>", ...}`.
+#[derive(Serialize)]
+#[serde(tag = "event", rename_all = "snake_case")]
+pub enum Event<'a> {
+    /// The relay-only ticket the viewer needs. Emitted once at host startup.
+    Ticket { value: &'a str },
+    /// One-shot host configuration summary, mirroring the banner fields.
+    HostInfo {
+        display_server: &'a str,
+        capture: &'a str,
+        quality: &'a str,
+        dimensions: &'a str,
+        hw_encode: bool,
+        max_viewers: u32,
+        max_viewers_source: &'a str,
+    },
+    /// Active viewer count changed.
+    ViewerCount { active: u32, max: u32 },
+    /// Capture pipeline lifecycle (spawned on first viewer, torn down on last).
+    Capture { state: CaptureState },
+    /// A viewer was turned away (host full, or capture spawn failed).
+    ViewerRefused { reason: &'a str },
+    /// Viewer-side: the local player URL is ready to open.
+    Connected { url: &'a str },
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CaptureState {
+    Started,
+    Stopped,
+}
+
+/// Emit one event as a JSON line on stdout, flushed. No-op unless JSON
+/// output was enabled with [`set_json`], so call sites can sprinkle these
+/// unconditionally without branching.
+pub fn emit(event: Event) {
+    if !json_enabled() {
+        return;
+    }
+    match serde_json::to_string(&event) {
+        Ok(line) => {
+            let mut out = std::io::stdout().lock();
+            // Best-effort: a closed pipe (front-end gone) shouldn't crash the
+            // host — it keeps streaming to any viewers already connected.
+            let _ = writeln!(out, "{line}");
+            let _ = out.flush();
+        }
+        Err(e) => tracing::warn!("failed to serialize event: {e}"),
+    }
+}

src/gui/child.rs

@@ -0,0 +1,238 @@
+//! Drives a headless `pixelpass` child process for the GUI.
+//!
+//! The GUI re-execs this same binary (via [`std::env::current_exe`]) in
+//! headless mode with `--output json`, then reads the child's JSON event
+//! stream on a background thread and forwards parsed events over a channel the
+//! 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::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;
+
+/// 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.
+#[derive(Deserialize, Debug)]
+#[serde(tag = "event", rename_all = "snake_case")]
+pub enum ChildEvent {
+    Ticket {
+        value: String,
+    },
+    HostInfo {
+        display_server: String,
+        capture: String,
+        quality: String,
+        dimensions: String,
+        hw_encode: bool,
+        max_viewers: u32,
+        max_viewers_source: String,
+    },
+    ViewerCount {
+        active: u32,
+        max: u32,
+    },
+    Capture {
+        state: CaptureState,
+    },
+    ViewerRefused {
+        reason: String,
+    },
+    Connected {
+        url: String,
+    },
+}
+
+#[derive(Deserialize, Debug, Clone, Copy, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum CaptureState {
+    Started,
+    Stopped,
+}
+
+const STDERR_TAIL_MAX: usize = 60;
+
+pub struct ChildProc {
+    child: Child,
+    pub rx: Receiver<ChildEvent>,
+    stderr_tail: Arc<Mutex<Vec<String>>>,
+}
+
+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> {
+        let exe = std::env::current_exe()?;
+        let mut child = Command::new(exe)
+            .args(args)
+            .stdin(Stdio::null())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped())
+            .spawn()?;
+
+        let (tx, rx) = std::sync::mpsc::channel();
+        let stdout = child.stdout.take().expect("stdout piped");
+        std::thread::spawn(move || {
+            let reader = BufReader::new(stdout);
+            for line in reader.lines().map_while(Result::ok) {
+                if line.trim().is_empty() {
+                    continue;
+                }
+                // Ignore any non-event line rather than dropping the stream.
+                if let Ok(ev) = serde_json::from_str::<ChildEvent>(&line) {
+                    if tx.send(ev).is_err() {
+                        break; // app gone
+                    }
+                    ctx.request_repaint();
+                }
+            }
+        });
+
+        let stderr_tail = Arc::new(Mutex::new(Vec::<String>::new()));
+        let stderr = child.stderr.take().expect("stderr piped");
+        let tail = stderr_tail.clone();
+        std::thread::spawn(move || {
+            let reader = BufReader::new(stderr);
+            for line in reader.lines().map_while(Result::ok) {
+                let mut t = tail.lock().unwrap();
+                t.push(line);
+                let overflow = t.len().saturating_sub(STDERR_TAIL_MAX);
+                if overflow > 0 {
+                    t.drain(0..overflow);
+                }
+            }
+        });
+
+        Ok(Self {
+            child,
+            rx,
+            stderr_tail,
+        })
+    }
+
+    /// Whether the child is still running.
+    pub fn is_alive(&mut self) -> bool {
+        matches!(self.child.try_wait(), Ok(None))
+    }
+
+    /// The last captured stderr lines, joined — for error display.
+    pub fn stderr_tail(&self) -> String {
+        self.stderr_tail.lock().unwrap().join("\n")
+    }
+
+    /// 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();
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::common::output::{CaptureState as EmitState, Event};
+
+    // The GUI parses what the headless child emits. These round-trip the
+    // emitter's own types (`common::output::Event`) through the parser
+    // (`ChildEvent`) so a rename on either side of the wire fails here rather
+    // than silently breaking the GUI at runtime.
+    fn parse(emit: Event) -> ChildEvent {
+        let line = serde_json::to_string(&emit).unwrap();
+        serde_json::from_str::<ChildEvent>(&line).unwrap()
+    }
+
+    #[test]
+    fn ticket_round_trips() {
+        assert!(matches!(
+            parse(Event::Ticket { value: "endpointXYZ" }),
+            ChildEvent::Ticket { value } if value == "endpointXYZ"
+        ));
+    }
+
+    #[test]
+    fn host_info_round_trips() {
+        let ev = parse(Event::HostInfo {
+            display_server: "Wayland",
+            capture: "fullscreen + system-audio",
+            quality: "Medium",
+            dimensions: "≤720p / 2500 kbps / 30 fps",
+            hw_encode: true,
+            max_viewers: 3,
+            max_viewers_source: "user-specified",
+        });
+        match ev {
+            ChildEvent::HostInfo {
+                display_server,
+                quality,
+                hw_encode,
+                max_viewers,
+                ..
+            } => {
+                assert_eq!(display_server, "Wayland");
+                assert_eq!(quality, "Medium");
+                assert!(hw_encode);
+                assert_eq!(max_viewers, 3);
+            }
+            other => panic!("expected HostInfo, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn viewer_count_round_trips() {
+        assert!(matches!(
+            parse(Event::ViewerCount { active: 2, max: 4 }),
+            ChildEvent::ViewerCount { active: 2, max: 4 }
+        ));
+    }
+
+    #[test]
+    fn capture_state_round_trips() {
+        assert!(matches!(
+            parse(Event::Capture { state: EmitState::Started }),
+            ChildEvent::Capture { state: CaptureState::Started }
+        ));
+        assert!(matches!(
+            parse(Event::Capture { state: EmitState::Stopped }),
+            ChildEvent::Capture { state: CaptureState::Stopped }
+        ));
+    }
+
+    #[test]
+    fn refused_and_connected_round_trip() {
+        assert!(matches!(
+            parse(Event::ViewerRefused { reason: "host is full" }),
+            ChildEvent::ViewerRefused { reason } if reason == "host is full"
+        ));
+        assert!(matches!(
+            parse(Event::Connected { url: "http://127.0.0.1:5000" }),
+            ChildEvent::Connected { url } if url == "http://127.0.0.1:5000"
+        ));
+    }
+}

src/gui/mod.rs

@@ -0,0 +1,650 @@
+//! Graphical front-end (`pixelpass --gui`), compiled only with the `gui`
+//! feature.
+//!
+//! Architecture: this window is a thin **shell-out** driver. It never touches
+//! the capture / portal / gst / iroh machinery directly — instead it re-execs
+//! this same binary in headless mode (`pixelpass --host --output json …` or
+//! `pixelpass <ticket> --output json`) as a child process and parses the
+//! child's JSON event stream (see [`crate::common::output`]) to drive what it
+//! shows. That keeps the fragile capture stack sealed in a separate process:
+//! the GUI can be closed or crash without taking a live stream down.
+
+mod child;
+
+use eframe::egui;
+
+use self::child::{ChildEvent, ChildProc};
+
+/// 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<()> {
+    let options = eframe::NativeOptions {
+        viewport: egui::ViewportBuilder::default()
+            .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()))),
+    )
+    .map_err(|e| anyhow::anyhow!("GUI failed to start: {e}"))
+}
+
+/// Best-effort clipboard write. Returns whether it succeeded so callers can
+/// show an honest "✓ Copied" / fallback hint (the clipboard can be flaky on
+/// Wayland, and a silent miss is what left users pasting stale tickets).
+fn set_clipboard(text: &str) -> bool {
+    arboard::Clipboard::new()
+        .and_then(|mut cb| cb.set_text(text.to_owned()))
+        .is_ok()
+}
+
+/// Which screen the single window is currently showing.
+#[derive(Default, PartialEq)]
+enum Screen {
+    #[default]
+    Menu,
+    Host,
+    Viewer,
+}
+
+/// Quality preset choices, mirroring `cli::Quality`. Map to the `--quality`
+/// argument value passed to the child.
+#[derive(Default, PartialEq, Clone, Copy)]
+enum QualitySel {
+    #[default]
+    Auto,
+    Source,
+    High,
+    Medium,
+    Low,
+}
+
+impl QualitySel {
+    fn as_arg(self) -> &'static str {
+        match self {
+            QualitySel::Auto => "auto",
+            QualitySel::Source => "source",
+            QualitySel::High => "high",
+            QualitySel::Medium => "medium",
+            QualitySel::Low => "low",
+        }
+    }
+
+    fn label(self) -> &'static str {
+        match self {
+            QualitySel::Auto => "Auto — pick from my upload speed",
+            QualitySel::Source => "Source — native resolution",
+            QualitySel::High => "High — up to 1080p",
+            QualitySel::Medium => "Medium — up to 720p",
+            QualitySel::Low => "Low — up to 480p",
+        }
+    }
+
+    const ALL: [QualitySel; 5] = [
+        QualitySel::Auto,
+        QualitySel::Source,
+        QualitySel::High,
+        QualitySel::Medium,
+        QualitySel::Low,
+    ];
+}
+
+/// Player choices for the viewer screen.
+#[derive(Default, PartialEq, Clone, Copy)]
+enum PlayerSel {
+    #[default]
+    Mpv,
+    Vlc,
+}
+
+impl PlayerSel {
+    fn to_player(self) -> crate::interactive::Player {
+        match self {
+            PlayerSel::Mpv => crate::interactive::Player::Mpv,
+            PlayerSel::Vlc => crate::interactive::Player::Vlc,
+        }
+    }
+}
+
+/// Host-screen state: the config form fields plus, once started, the running
+/// child and the latest values parsed from its event stream.
+struct HostState {
+    // form
+    quality: QualitySel,
+    max_viewers: u32, // 0 = let the host auto-size from the bandwidth preflight
+    no_hwencode: bool,
+    window: bool,
+    // running session + accumulated live state
+    proc: Option<ChildProc>,
+    ticket: Option<String>,
+    info: Option<HostInfo>,
+    active: u32,
+    max: u32,
+    capturing: bool,
+    /// Whether the current ticket made it onto the clipboard (auto-copy on
+    /// arrival, or a manual Copy click). Drives the "✓ Copied" hint so the
+    /// user isn't left guessing whether to click Copy — the trap that had
+    /// people pasting a stale clipboard ticket.
+    copied: bool,
+    last_refusal: Option<String>,
+    error: Option<String>,
+}
+
+impl Default for HostState {
+    fn default() -> Self {
+        Self {
+            quality: QualitySel::default(),
+            max_viewers: 0,
+            no_hwencode: false,
+            window: false,
+            proc: None,
+            ticket: None,
+            info: None,
+            active: 0,
+            max: 0,
+            capturing: false,
+            copied: false,
+            last_refusal: None,
+            error: None,
+        }
+    }
+}
+
+/// The host config summary echoed back by the child's `host_info` event.
+struct HostInfo {
+    display: String,
+    capture: String,
+    quality: String,
+    dimensions: String,
+    hw_encode: bool,
+    cap_source: String,
+}
+
+/// Viewer-screen state.
+#[derive(Default)]
+struct ViewerState {
+    ticket_input: String,
+    player: PlayerSel,
+    proc: Option<ChildProc>,
+    url: Option<String>,
+    launched: bool,
+    error: Option<String>,
+}
+
+#[derive(Default)]
+struct PixelPassApp {
+    screen: Screen,
+    host: HostState,
+    viewer: ViewerState,
+}
+
+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) {
+        // Drain any pending child events before drawing this frame.
+        self.pump_host_events();
+        self.pump_viewer_events();
+
+        match self.screen {
+            Screen::Menu => self.menu(ui),
+            Screen::Host => self.host(ui),
+            Screen::Viewer => self.viewer(ui),
+        }
+    }
+}
+
+impl PixelPassApp {
+    fn menu(&mut self, ui: &mut egui::Ui) {
+        ui.vertical_centered(|ui| {
+            ui.add_space(24.0);
+            ui.heading("PixelPass");
+            ui.label("P2P screen sharing");
+            ui.add_space(32.0);
+            if ui
+                .add_sized([260.0, 40.0], egui::Button::new("Host — share my screen"))
+                .clicked()
+            {
+                self.screen = Screen::Host;
+            }
+            ui.add_space(8.0);
+            if ui
+                .add_sized(
+                    [260.0, 40.0],
+                    egui::Button::new("View — watch someone's screen"),
+                )
+                .clicked()
+            {
+                self.screen = Screen::Viewer;
+            }
+        });
+    }
+
+    // ── Host screen ──────────────────────────────────────────────────────
+
+    fn host(&mut self, ui: &mut egui::Ui) {
+        let running = self.host.proc.is_some();
+        ui.horizontal(|ui| {
+            // Leaving the host screen stops the session (Drop on the child).
+            if ui.button("← Menu").clicked() {
+                self.stop_host();
+                self.screen = Screen::Menu;
+            }
+            ui.heading("Host");
+        });
+        ui.separator();
+
+        if running {
+            self.host_running(ui);
+        } else {
+            self.host_form(ui);
+        }
+    }
+
+    fn host_form(&mut self, ui: &mut egui::Ui) {
+        if let Some(err) = &self.host.error {
+            ui.colored_label(egui::Color32::LIGHT_RED, err);
+            ui.add_space(8.0);
+        }
+
+        egui::Grid::new("host_form")
+            .num_columns(2)
+            .spacing([12.0, 10.0])
+            .show(ui, |ui| {
+                ui.label("Quality");
+                egui::ComboBox::from_id_salt("quality")
+                    .selected_text(self.host.quality.label())
+                    .show_ui(ui, |ui| {
+                        for q in QualitySel::ALL {
+                            ui.selectable_value(&mut self.host.quality, q, q.label());
+                        }
+                    });
+                ui.end_row();
+
+                ui.label("Max viewers");
+                ui.horizontal(|ui| {
+                    ui.add(egui::DragValue::new(&mut self.host.max_viewers).range(0..=16));
+                    if self.host.max_viewers == 0 {
+                        ui.label("(auto from upload speed)");
+                    }
+                });
+                ui.end_row();
+
+                ui.label("Options");
+                ui.vertical(|ui| {
+                    ui.checkbox(&mut self.host.window, "Share a single window");
+                    ui.checkbox(
+                        &mut self.host.no_hwencode,
+                        "Software encoding (no GPU / VAAPI)",
+                    );
+                });
+                ui.end_row();
+            });
+
+        ui.add_space(16.0);
+        if ui
+            .add_sized([160.0, 36.0], egui::Button::new("Start hosting"))
+            .clicked()
+        {
+            self.start_host(ui.ctx().clone());
+        }
+        ui.add_space(8.0);
+        ui.label(
+            egui::RichText::new(
+                "On Wayland a \"Share Screen?\" dialog appears when the first \
+                 viewer connects.",
+            )
+            .small()
+            .weak(),
+        );
+    }
+
+    fn host_running(&mut self, ui: &mut egui::Ui) {
+        if self.host.capturing {
+            ui.colored_label(egui::Color32::LIGHT_GREEN, "● Streaming");
+        } else if self.host.ticket.is_some() {
+            ui.colored_label(egui::Color32::YELLOW, "● Waiting for viewers…");
+        } else {
+            ui.label("Starting…");
+        }
+
+        ui.add_space(6.0);
+        ui.label(format!("Viewers: {} / {}", self.host.active, self.host.max));
+
+        if let Some(info) = &self.host.info {
+            ui.label(
+                egui::RichText::new(format!("{} · {}", info.display, info.capture))
+                    .small()
+                    .weak(),
+            );
+            ui.label(
+                egui::RichText::new(format!(
+                    "{} · {} · {} · cap {}",
+                    info.quality,
+                    info.dimensions,
+                    if info.hw_encode {
+                        "HW encode"
+                    } else {
+                        "software encode"
+                    },
+                    info.cap_source
+                ))
+                .small()
+                .weak(),
+            );
+        }
+
+        ui.add_space(12.0);
+
+        if let Some(ticket) = self.host.ticket.clone() {
+            ui.label("Share this code with your viewer(s):");
+            ui.add_space(4.0);
+            egui::Frame::group(ui.style()).show(ui, |ui| {
+                ui.add(
+                    egui::Label::new(egui::RichText::new(&ticket).monospace().small())
+                        .wrap()
+                        .selectable(true),
+                );
+            });
+            ui.add_space(4.0);
+            ui.horizontal(|ui| {
+                if ui.button("📋 Copy code").clicked() {
+                    self.copy_to_clipboard(&ticket);
+                }
+                if self.host.copied {
+                    ui.colored_label(egui::Color32::LIGHT_GREEN, "✓ Copied to clipboard");
+                }
+            });
+            if !self.host.copied {
+                ui.label(
+                    egui::RichText::new(
+                        "Couldn't auto-copy — click Copy, or select the code above.",
+                    )
+                    .small()
+                    .weak(),
+                );
+            }
+        }
+
+        if let Some(reason) = &self.host.last_refusal {
+            ui.add_space(8.0);
+            ui.colored_label(
+                egui::Color32::from_rgb(220, 160, 60),
+                format!("⚠ {reason}"),
+            );
+        }
+
+        ui.add_space(16.0);
+        if ui
+            .add_sized([140.0, 36.0], egui::Button::new("Stop hosting"))
+            .clicked()
+        {
+            self.stop_host();
+        }
+    }
+
+    fn start_host(&mut self, ctx: egui::Context) {
+        self.host.error = None;
+        self.host.last_refusal = None;
+        self.host.ticket = None;
+        self.host.info = None;
+        self.host.active = 0;
+        self.host.max = 0;
+        self.host.capturing = false;
+        self.host.copied = false;
+
+        let mut args = vec![
+            "--host".to_string(),
+            "--output".to_string(),
+            "json".to_string(),
+            "--quality".to_string(),
+            self.host.quality.as_arg().to_string(),
+        ];
+        if self.host.max_viewers > 0 {
+            args.push("--max-viewers".to_string());
+            args.push(self.host.max_viewers.to_string());
+        }
+        if self.host.no_hwencode {
+            args.push("--no-hwencode".to_string());
+        }
+        if self.host.window {
+            args.push("--window".to_string());
+        }
+
+        match ChildProc::spawn(&args, ctx) {
+            Ok(p) => self.host.proc = Some(p),
+            Err(e) => self.host.error = Some(format!("Couldn't start host: {e}")),
+        }
+    }
+
+    fn stop_host(&mut self) {
+        // Dropping the ChildProc SIGINTs the child and reaps it.
+        self.host.proc = None;
+        self.host.capturing = false;
+        self.host.ticket = None;
+        self.host.copied = false;
+    }
+
+    /// Drain the host child's event channel into state, and detect an
+    /// unexpected child exit (e.g. a failed dependency check) so it surfaces
+    /// in the form instead of leaving a dead "running" view.
+    fn pump_host_events(&mut self) {
+        let events: Vec<ChildEvent> = match &self.host.proc {
+            Some(p) => std::iter::from_fn(|| p.rx.try_recv().ok()).collect(),
+            None => return,
+        };
+        for ev in events {
+            self.apply_host_event(ev);
+        }
+
+        if let Some(p) = &mut self.host.proc
+            && !p.is_alive()
+        {
+            if self.host.ticket.is_none() {
+                let tail = p.stderr_tail();
+                self.host.error = Some(if tail.trim().is_empty() {
+                    "Host exited before it could start.".to_string()
+                } else {
+                    format!("Host exited before it could start:\n{tail}")
+                });
+            }
+            self.host.proc = None;
+            self.host.capturing = false;
+        }
+    }
+
+    fn apply_host_event(&mut self, ev: ChildEvent) {
+        match ev {
+            ChildEvent::Ticket { value } => {
+                // Auto-copy on arrival, mirroring the CLI/interactive host
+                // (which copies the ticket and prints "copied to your
+                // clipboard"). A failure here is non-fatal: the ticket stays
+                // visible for manual copy, and `copied` stays false so the UI
+                // doesn't falsely claim success.
+                self.host.copied = set_clipboard(&value);
+                self.host.ticket = Some(value);
+            }
+            ChildEvent::HostInfo {
+                display_server,
+                capture,
+                quality,
+                dimensions,
+                hw_encode,
+                max_viewers,
+                max_viewers_source,
+            } => {
+                self.host.max = max_viewers;
+                self.host.info = Some(HostInfo {
+                    display: display_server,
+                    capture,
+                    quality,
+                    dimensions,
+                    hw_encode,
+                    cap_source: max_viewers_source,
+                });
+            }
+            ChildEvent::ViewerCount { active, max } => {
+                self.host.active = active;
+                self.host.max = max;
+            }
+            ChildEvent::Capture { state } => {
+                self.host.capturing = matches!(state, child::CaptureState::Started);
+            }
+            ChildEvent::ViewerRefused { reason } => self.host.last_refusal = Some(reason),
+            ChildEvent::Connected { .. } => {} // viewer-side; not used on the host screen
+        }
+    }
+
+    /// Manual Copy-button handler: copy and reflect success in the UI, or
+    /// surface a clear error if the clipboard rejected it.
+    fn copy_to_clipboard(&mut self, text: &str) {
+        if set_clipboard(text) {
+            self.host.copied = true;
+            self.host.error = None;
+        } else {
+            self.host.copied = false;
+            self.host.error = Some(
+                "Couldn't write to the clipboard. Select the code above and copy it manually."
+                    .to_string(),
+            );
+        }
+    }
+
+    // ── Viewer screen ─────────────────────────────────────────────────────
+
+    fn viewer(&mut self, ui: &mut egui::Ui) {
+        let running = self.viewer.proc.is_some();
+        ui.horizontal(|ui| {
+            if ui.button("← Menu").clicked() {
+                self.stop_viewer();
+                self.screen = Screen::Menu;
+            }
+            ui.heading("View");
+        });
+        ui.separator();
+
+        if running {
+            self.viewer_running(ui);
+        } else {
+            self.viewer_form(ui);
+        }
+    }
+
+    fn viewer_form(&mut self, ui: &mut egui::Ui) {
+        if let Some(err) = &self.viewer.error {
+            ui.colored_label(egui::Color32::LIGHT_RED, err);
+            ui.add_space(8.0);
+        }
+
+        ui.label("Paste the share code you received:");
+        ui.add_space(4.0);
+        ui.add(
+            egui::TextEdit::singleline(&mut self.viewer.ticket_input)
+                .desired_width(f32::INFINITY)
+                .hint_text("endpoint…"),
+        );
+
+        ui.add_space(10.0);
+        ui.horizontal(|ui| {
+            ui.label("Player");
+            egui::ComboBox::from_id_salt("player")
+                .selected_text(match self.viewer.player {
+                    PlayerSel::Mpv => "mpv",
+                    PlayerSel::Vlc => "VLC",
+                })
+                .show_ui(ui, |ui| {
+                    ui.selectable_value(&mut self.viewer.player, PlayerSel::Mpv, "mpv");
+                    ui.selectable_value(&mut self.viewer.player, PlayerSel::Vlc, "VLC");
+                });
+        });
+
+        ui.add_space(16.0);
+        let can_connect = !self.viewer.ticket_input.trim().is_empty();
+        if ui
+            .add_enabled(
+                can_connect,
+                egui::Button::new("Connect").min_size(egui::vec2(140.0, 36.0)),
+            )
+            .clicked()
+        {
+            self.start_viewer(ui.ctx().clone());
+        }
+    }
+
+    fn viewer_running(&mut self, ui: &mut egui::Ui) {
+        if self.viewer.launched {
+            ui.colored_label(egui::Color32::LIGHT_GREEN, "● Streaming");
+            ui.label("Player launched. Close it or disconnect to stop.");
+        } else if self.viewer.url.is_some() {
+            ui.label("Connected — launching player…");
+        } else {
+            ui.colored_label(egui::Color32::YELLOW, "● Connecting…");
+        }
+
+        ui.add_space(16.0);
+        if ui
+            .add_sized([140.0, 36.0], egui::Button::new("Disconnect"))
+            .clicked()
+        {
+            self.stop_viewer();
+        }
+    }
+
+    fn start_viewer(&mut self, ctx: egui::Context) {
+        self.viewer.error = None;
+        self.viewer.url = None;
+        self.viewer.launched = false;
+
+        let ticket = self.viewer.ticket_input.trim().to_string();
+        let args = vec![ticket, "--output".to_string(), "json".to_string()];
+        match ChildProc::spawn(&args, ctx) {
+            Ok(p) => self.viewer.proc = Some(p),
+            Err(e) => self.viewer.error = Some(format!("Couldn't connect: {e}")),
+        }
+    }
+
+    fn stop_viewer(&mut self) {
+        self.viewer.proc = None;
+        self.viewer.url = None;
+        self.viewer.launched = false;
+    }
+
+    fn pump_viewer_events(&mut self) {
+        let events: Vec<ChildEvent> = match &self.viewer.proc {
+            Some(p) => std::iter::from_fn(|| p.rx.try_recv().ok()).collect(),
+            None => return,
+        };
+        for ev in events {
+            if let ChildEvent::Connected { url } = ev {
+                self.viewer.url = Some(url.clone());
+                if !self.viewer.launched {
+                    match self.viewer.player.to_player().spawn(&url) {
+                        Ok(()) => self.viewer.launched = true,
+                        Err(e) => self.viewer.error = Some(format!("Couldn't launch player: {e}")),
+                    }
+                }
+            }
+        }
+
+        if let Some(p) = &mut self.viewer.proc
+            && !p.is_alive()
+        {
+            // Bridge ended (player closed) or the connection failed.
+            if self.viewer.url.is_none() {
+                let tail = p.stderr_tail();
+                self.viewer.error = Some(if tail.trim().is_empty() {
+                    "Couldn't connect to the host (check the code).".to_string()
+                } else {
+                    format!("Connection ended:\n{tail}")
+                });
+            }
+            self.viewer.proc = None;
+            self.viewer.launched = false;
+            self.viewer.url = None;
+        }
+    }
+}

src/host/mod.rs

@@ -16,8 +16,8 @@ use tokio_util::sync::CancellationToken;
 
 use crate::cli::HostOpts;
 use crate::common::{
-    alpn::ALPN, bandwidth, config, config::BandwidthStatus, deps, display::DisplayServer, signal,
-    tunnel,
+    alpn::ALPN, bandwidth, config, config::BandwidthStatus, deps, display::DisplayServer, output,
+    signal, tunnel,
 };
 
 use self::pipeline::CaptureHandle;
@@ -85,9 +85,25 @@ pub async fn run(opts: HostOpts) -> Result<()> {
     let relay_only =
         EndpointAddr::new(addr.id).with_addrs(addr.addrs.iter().filter(|a| a.is_relay()).cloned());
     let ticket = EndpointTicket::new(relay_only);
-    let clipboard_ok = opts.interactive && copy_to_clipboard(&ticket.to_string());
+    let ticket_str = ticket.to_string();
+    let clipboard_ok = opts.interactive && copy_to_clipboard(&ticket_str);
     print_host_banner(&ticket, display, &opts, &quality, &resolution, clipboard_ok);
 
+    output::emit(output::Event::Ticket { value: &ticket_str });
+    let display_str = format!("{display:?}");
+    let capture = capture_summary(&opts);
+    let dims = quality.dimensions_summary();
+    let cap_source = resolution.source.label();
+    output::emit(output::Event::HostInfo {
+        display_server: &display_str,
+        capture: &capture,
+        quality: &quality.label,
+        dimensions: &dims,
+        hw_encode: !opts.no_hwencode,
+        max_viewers: resolution.value,
+        max_viewers_source: &cap_source,
+    });
+
     let (sup_tx, sup_rx) = mpsc::channel::<SupervisorMsg>(16);
     let supervisor = tokio::spawn(supervise(
         opts.clone(),
@@ -215,16 +231,22 @@ async fn supervise(
         match msg {
             SupervisorMsg::AddViewer(reply) => {
                 if count >= max_viewers {
-                    let _ = reply.send(Err(format!(
-                        "host is full ({count} of {max_viewers} viewers connected)"
-                    )));
+                    let reason =
+                        format!("host is full ({count} of {max_viewers} viewers connected)");
+                    output::emit(output::Event::ViewerRefused { reason: &reason });
+                    let _ = reply.send(Err(reason));
                     continue;
                 }
 
                 if handle.is_none() {
                     tracing::info!("first viewer arriving — spawning capture");
                     match capture::spawn(display, &opts, &quality).await {
-                        Ok(h) => handle = Some(h),
+                        Ok(h) => {
+                            handle = Some(h);
+                            output::emit(output::Event::Capture {
+                                state: output::CaptureState::Started,
+                            });
+                        }
                         Err(e) => {
                             let _ = reply.send(Err(format!("capture spawn failed: {e:#}")));
                             continue;
@@ -235,16 +257,21 @@ async fn supervise(
                 let port = handle.as_ref().expect("handle was just set").local_port();
                 count += 1;
                 let _ = reply.send(Ok(port));
+                output::emit(output::Event::ViewerCount { active: count, max: max_viewers });
                 tracing::info!(active = count, cap = max_viewers, "viewer joined");
             }
             SupervisorMsg::RemoveViewer => {
                 count = count.saturating_sub(1);
+                output::emit(output::Event::ViewerCount { active: count, max: max_viewers });
                 tracing::info!(active = count, cap = max_viewers, "viewer left");
                 if count == 0
                     && let Some(h) = handle.take()
                 {
                     tracing::info!("last viewer left — tearing down capture");
                     h.shutdown().await;
+                    output::emit(output::Event::Capture {
+                        state: output::CaptureState::Stopped,
+                    });
                 }
             }
         }
@@ -253,6 +280,9 @@ async fn supervise(
     if let Some(h) = handle.take() {
         tracing::info!("host shutdown — tearing down capture");
         h.shutdown().await;
+        output::emit(output::Event::Capture {
+            state: output::CaptureState::Stopped,
+        });
     }
 }
 

src/main.rs

@@ -1,5 +1,7 @@
 mod cli;
 mod common;
+#[cfg(feature = "gui")]
+mod gui;
 mod host;
 mod interactive;
 mod repair;
@@ -16,6 +18,24 @@ async fn main() -> Result<()> {
     let cli = Cli::parse();
     init_tracing(cli.verbose);
 
+    if matches!(cli.output, Some(cli::OutputFormat::Json)) {
+        common::output::set_json(true);
+    }
+
+    if cli.gui {
+        #[cfg(feature = "gui")]
+        {
+            return gui::run();
+        }
+        #[cfg(not(feature = "gui"))]
+        {
+            anyhow::bail!(
+                "this binary was built without GUI support. Rebuild with \
+                 `cargo build --release --features gui` to use --gui."
+            );
+        }
+    }
+
     // libpipewire requires global init before any pw_* call. Idempotent;
     // safe to call even when the per-app audio thread never spawns.
     pipewire::init();
@@ -28,6 +48,16 @@ async fn main() -> Result<()> {
         return interactive::run_reconfigure().await;
     }
 
+    if cli.host {
+        if cli.ticket.is_some() {
+            anyhow::bail!(
+                "--host and a ticket argument are mutually exclusive: --host shares your \
+                 screen, a ticket views someone else's."
+            );
+        }
+        return host::run(cli.into_host_opts(false)).await;
+    }
+
     match cli.ticket.as_deref() {
         Some(s) => {
             let ticket: EndpointTicket = s.parse().map_err(|e| {
@@ -45,5 +75,14 @@ async fn main() -> Result<()> {
 fn init_tracing(verbose: bool) {
     let default = if verbose { "pixelpass=trace,iroh=info" } else { "pixelpass=info,iroh=warn" };
     let filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new(default));
-    tracing_subscriber::fmt().with_env_filter(filter).with_target(false).init();
+    // Tracing MUST write to stderr. `tracing_subscriber::fmt()` defaults its
+    // writer to stdout, but with `--output json` stdout carries the JSON event
+    // stream the `--gui` front-end parses (see `common::output`) — logging there
+    // interleaves log lines into that stream (corrupting events and starving the
+    // GUI's stderr-tail diagnostics). Pin it to stderr to honor that contract.
+    tracing_subscriber::fmt()
+        .with_writer(std::io::stderr)
+        .with_env_filter(filter)
+        .with_target(false)
+        .init();
 }

src/viewer/mod.rs

@@ -1,11 +1,18 @@
-use anyhow::{Context, Result};
+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, signal};
+use crate::common::{alpn::ALPN, output, signal};
+
+/// Cap on the initial QUIC connect. `endpoint.connect()` has no built-in
+/// deadline, so an offline host / stale code / unreachable relay otherwise
+/// hangs forever with no feedback (the silent "connecting…" failure mode).
+/// Matches the host's 15s `online()` cap.
+const CONNECT_TIMEOUT: Duration = Duration::from_secs(15);
 
 pub async fn run(ticket: EndpointTicket, opts: ViewerOpts) -> Result<()> {
     let cancel = signal::install_ctrl_c();
@@ -17,12 +24,38 @@ pub async fn run(ticket: EndpointTicket, opts: ViewerOpts) -> Result<()> {
 
     let addr = ticket.endpoint_addr().clone();
     tracing::info!(remote = %addr.id, "connecting to host");
-    let conn = endpoint.connect(addr, ALPN).await?;
+
+    // Bound the connect attempt and let ctrl-c abort it, so the viewer fails
+    // loud (and the GUI surfaces the error) instead of spinning indefinitely.
+    let conn = tokio::select! {
+        _ = cancel.cancelled() => {
+            tracing::info!("ctrl-c received before the connection was established");
+            endpoint.close().await;
+            return Ok(());
+        }
+        result = tokio::time::timeout(CONNECT_TIMEOUT, endpoint.connect(addr, ALPN)) => match result {
+            Ok(Ok(conn)) => conn,
+            Ok(Err(e)) => {
+                endpoint.close().await;
+                bail!("failed to connect to the host: {e:#}");
+            }
+            Err(_) => {
+                endpoint.close().await;
+                bail!(
+                    "couldn't reach the host within {}s — it may be offline, the share \
+                     code may be stale, or the relay may be unreachable. Check that the \
+                     host is running, then re-copy the code and try again.",
+                    CONNECT_TIMEOUT.as_secs()
+                );
+            }
+        },
+    };
     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 });
 
     if opts.interactive {
         let player = crate::interactive::prompt_player()?;