headroom

public

Star0

Fork 0

Watch0

7 commits 1 branch 0 tags 0 releases521.6 KiB

Commit `c19702ae09be`

tarball

atagen <boss@atagen.co>2026-06-04 03:27 UTC

9 files changed+3841-0

clients: cli, monitor tui, and iced gui

Added file: crates/headroom-cli/Cargo.toml+37 additions@@ -0,0 +1,37 @@
+[package]
+name = "headroom-cli"
+description = "automatic loudness and per-app volume control (pipewire)"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+authors.workspace = true
+
+[[bin]]
+name = "headroom"
+path = "src/main.rs"
+
+[dependencies]
+headroom-client = { workspace = true }
+headroom-core   = { workspace = true }
+headroom-ipc    = { workspace = true }
+
+assert_no_alloc = { workspace = true }
+clap = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true }
+
+# tui-only deps, behind the default `tui` feature. `--no-default-features`
+# drops ratatui/crossterm for a graphics-free daemon + cli build.
+crossbeam-channel = { workspace = true, optional = true }
+crossterm = { workspace = true, optional = true }
+ratatui = { workspace = true, optional = true }
+
+[features]
+default = ["tui"]
+# full-screen `headroom monitor` tui. without it, `monitor --json` still
+# works (daemon + every other subcommand unaffected).
+tui = ["dep:crossbeam-channel", "dep:crossterm", "dep:ratatui"]

Added file: crates/headroom-cli/src/main.rs+442 additions@@ -0,0 +1,442 @@
+//! `headroom` cli — connects to the daemon over its uds; `daemon` runs core in-process.
+
+#![forbid(unsafe_code)]
+
+#[cfg(feature = "tui")]
+mod tui;
+
+use std::path::PathBuf;
+use std::process::ExitCode;
+
+use clap::{Parser, Subcommand, ValueEnum};
+use headroom_client::{Client, ClientError, Route, Topic};
+
+// debug-only: arms core's audio-thread `assert_no_alloc` blocks; no-op in release.
+#[cfg(debug_assertions)]
+#[global_allocator]
+static ALLOCATOR: assert_no_alloc::AllocDisabler = assert_no_alloc::AllocDisabler;
+
+/// headroom cli.
+#[derive(Debug, Parser)]
+#[command(version, about, long_about = None)]
+struct Cli {
+    /// override the daemon control socket path.
+    #[arg(long, global = true)]
+    socket: Option<PathBuf>,
+
+    #[command(subcommand)]
+    cmd: Cmd,
+}
+
+#[derive(Debug, Subcommand)]
+enum Cmd {
+    /// run the daemon in the foreground.
+    Daemon {
+        /// extra `*.toml` profile dir (repeatable). precedes shipped/user
+        /// profiles; first dir is watched for live edits.
+        #[arg(long = "profile-dir", value_name = "DIR")]
+        profile_dir: Vec<PathBuf>,
+    },
+
+    /// show daemon status.
+    Status,
+
+    /// profile management.
+    #[command(subcommand)]
+    Profile(ProfileCmd),
+
+    /// routing rules and per-stream decisions.
+    #[command(subcommand)]
+    Route(RouteCmd),
+
+    /// per-app level control (layer a).
+    #[command(subcommand)]
+    PerApp(PerAppCmd),
+
+    /// get a setting value from the active profile.
+    Get {
+        /// dotted setting key.
+        key: String,
+    },
+
+    /// set a setting override (or clear with `--clear`). overrides persist
+    /// across profile switches; `reset` clears all.
+    Set {
+        /// dotted setting key.
+        key: String,
+        /// new value, json-encoded. omit with `--clear`.
+        // allow_hyphen_values so negatives aren't parsed as flags.
+        #[arg(allow_hyphen_values = true)]
+        value: Option<String>,
+        /// clear this key's override instead of setting one.
+        #[arg(long, conflicts_with = "value")]
+        clear: bool,
+    },
+
+    /// toggle the global bypass kill switch.
+    Bypass {
+        /// `on` or `off`.
+        #[arg(value_enum)]
+        state: BypassState,
+    },
+
+    /// clear all setting overrides. leaves route/per-app/bypass intact.
+    Reset,
+
+    /// reload profile files from disk.
+    Reload,
+
+    /// live monitor. defaults to a tui; `--json` is the line-delimited stream.
+    Monitor {
+        /// topics to subscribe to (comma-separated). `--json` only; the tui
+        /// subscribes to all.
+        #[arg(value_delimiter = ',', default_value = "meters")]
+        topics: Vec<MonitorTopic>,
+
+        /// emit one json event per line instead of the tui.
+        #[arg(long)]
+        json: bool,
+    },
+}
+
+#[derive(Debug, Clone, Copy, ValueEnum)]
+enum MonitorTopic {
+    Meters,
+    Profile,
+    Routing,
+    Daemon,
+}
+
+impl From<MonitorTopic> for Topic {
+    fn from(t: MonitorTopic) -> Self {
+        match t {
+            MonitorTopic::Meters => Topic::Meters,
+            MonitorTopic::Profile => Topic::Profile,
+            MonitorTopic::Routing => Topic::Routing,
+            MonitorTopic::Daemon => Topic::Daemon,
+        }
+    }
+}
+
+#[derive(Debug, Subcommand)]
+enum ProfileCmd {
+    /// list known profiles.
+    List,
+    /// activate the named profile.
+    Use {
+        /// profile name.
+        name: String,
+    },
+    /// show a profile in full.
+    Show {
+        /// profile name (defaults to the active profile).
+        name: Option<String>,
+    },
+}
+
+#[derive(Debug, Subcommand)]
+enum RouteCmd {
+    /// list routing rules and current per-stream decisions.
+    List,
+    /// add or replace a routing rule for an app.
+    Set {
+        /// app identifier (e.g. `application.process.binary`).
+        app: String,
+        /// where to route.
+        #[arg(value_enum)]
+        to: RouteArg,
+    },
+    /// remove an app's user routing rule.
+    Unset {
+        /// app identifier.
+        app: String,
+    },
+    /// reroute a specific live stream by node id.
+    Stream {
+        /// pipewire node id.
+        node_id: u32,
+        /// where to route.
+        #[arg(value_enum)]
+        to: RouteArg,
+    },
+}
+
+#[derive(Debug, Subcommand)]
+enum PerAppCmd {
+    /// show per-app layer a state for managed streams.
+    Status {
+        /// emit the snapshot list as json instead of a table.
+        #[arg(long)]
+        json: bool,
+    },
+    /// enable the layer a master switch (persisted).
+    On,
+    /// disable the layer a master switch (persisted).
+    Off,
+    /// enable or disable layer a for a specific app (persisted).
+    Set {
+        /// app identifier (process_binary or application_name).
+        app: String,
+        /// `on` or `off`.
+        #[arg(value_enum)]
+        state: BypassState,
+    },
+    /// clear a managed stream's deference lock.
+    Reset {
+        /// pipewire node id of the managed stream.
+        node_id: u32,
+    },
+}
+
+#[derive(Debug, Clone, Copy, ValueEnum)]
+enum BypassState {
+    On,
+    Off,
+}
+
+#[derive(Debug, Clone, Copy, ValueEnum)]
+enum RouteArg {
+    Processed,
+    Bypass,
+}
+
+impl From<RouteArg> for Route {
+    fn from(r: RouteArg) -> Self {
+        match r {
+            RouteArg::Processed => Route::Processed,
+            RouteArg::Bypass => Route::Bypass,
+        }
+    }
+}
+
+fn init_tracing() {
+    let env_filter = tracing_subscriber::EnvFilter::try_from_default_env()
+        .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("headroom=info"));
+    tracing_subscriber::fmt()
+        .with_env_filter(env_filter)
+        .with_target(false)
+        .compact()
+        .init();
+}
+
+fn run() -> Result<(), CliError> {
+    let cli = Cli::parse();
+
+    // tui owns the terminal; keep `tracing` off it.
+    let tui_mode = matches!(&cli.cmd, Cmd::Monitor { json: false, .. });
+    if !tui_mode {
+        init_tracing();
+    }
+
+    match cli.cmd {
+        Cmd::Daemon { profile_dir } => {
+            headroom_core::run_with_profile_dirs(profile_dir)
+                .map_err(|e| CliError::Daemon(e.to_string()))?;
+            Ok(())
+        }
+        Cmd::Monitor { json: false, .. } => {
+            #[cfg(feature = "tui")]
+            {
+                // connect on the main thread so initial rpcs run before raw mode.
+                let client = match cli.socket.as_deref() {
+                    Some(p) => Client::connect_at(p)?,
+                    None => Client::connect()?,
+                };
+                tui::run(client).map_err(CliError::Tui)
+            }
+            // no `tui` feature: point at the json stream, not an opaque failure.
+            #[cfg(not(feature = "tui"))]
+            {
+                let _ = cli.socket.as_deref();
+                Err(CliError::Other(
+                    "this build was compiled without the TUI (`tui` feature disabled); \
+                     rerun `headroom monitor --json` for the line-delimited event stream"
+                        .into(),
+                ))
+            }
+        }
+        cmd => with_client(cli.socket.as_deref(), |c| dispatch(c, cmd)),
+    }
+}
+
+fn with_client<F>(socket: Option<&std::path::Path>, f: F) -> Result<(), CliError>
+where
+    F: FnOnce(&mut Client) -> Result<(), CliError>,
+{
+    let mut client = match socket {
+        Some(p) => Client::connect_at(p)?,
+        None => Client::connect()?,
+    };
+    f(&mut client)
+}
+
+fn dispatch(client: &mut Client, cmd: Cmd) -> Result<(), CliError> {
+    match cmd {
+        Cmd::Daemon { .. } => unreachable!("handled in `run`"),
+
+        Cmd::Status => {
+            let status = client.status()?;
+            println!("{}", serde_json::to_string_pretty(&status)?);
+        }
+
+        Cmd::Profile(ProfileCmd::List) => {
+            let profiles = client.profile_list()?;
+            for p in profiles {
+                let marker = if p.active { '*' } else { ' ' };
+                println!("{marker} {:<16} {}", p.name, p.description);
+            }
+        }
+        Cmd::Profile(ProfileCmd::Use { name }) => {
+            let active = client.profile_use(&name)?;
+            println!("active profile: {active}");
+        }
+        Cmd::Profile(ProfileCmd::Show { name }) => {
+            let body = client.profile_show(name.as_deref())?;
+            println!("{}", serde_json::to_string_pretty(&body)?);
+        }
+
+        Cmd::Route(RouteCmd::List) => {
+            let list = client.route_list()?;
+            println!("{}", serde_json::to_string_pretty(&list)?);
+        }
+        Cmd::Route(RouteCmd::Set { app, to }) => {
+            client.route_set(&app, to.into())?;
+        }
+        Cmd::Route(RouteCmd::Unset { app }) => {
+            client.route_unset(&app)?;
+        }
+        Cmd::Route(RouteCmd::Stream { node_id, to }) => {
+            client.route_stream(node_id, to.into())?;
+        }
+
+        Cmd::PerApp(PerAppCmd::Status { json }) => {
+            let list = client.layer_a_list()?;
+            if json {
+                println!("{}", serde_json::to_string_pretty(&list)?);
+            } else if list.is_empty() {
+                println!("no streams under Layer A management");
+            } else {
+                println!(
+                    "{:<8} {:<24} {:>10} {:>9} {:>9}",
+                    "node", "app", "reduction", "ceiling", "deferred"
+                );
+                for s in &list {
+                    let app = if s.app.len() > 24 {
+                        format!("{}…", &s.app[..23])
+                    } else {
+                        s.app.clone()
+                    };
+                    let ceiling = s
+                        .user_ceiling_lin
+                        .map(|c| format!("{c:.2}"))
+                        .unwrap_or_else(|| "—".to_string());
+                    println!(
+                        "{:<8} {:<24} {:>8.1}dB {:>9} {:>9}",
+                        s.node_id, app, s.reduction_db, ceiling, s.deferred
+                    );
+                }
+            }
+        }
+        Cmd::PerApp(PerAppCmd::On) => {
+            client.per_app_master(true)?;
+        }
+        Cmd::PerApp(PerAppCmd::Off) => {
+            client.per_app_master(false)?;
+        }
+        Cmd::PerApp(PerAppCmd::Set { app, state }) => {
+            client.per_app_set(&app, matches!(state, BypassState::On))?;
+        }
+        Cmd::PerApp(PerAppCmd::Reset { node_id }) => {
+            client.layer_a_reset(node_id)?;
+        }
+
+        Cmd::Get { key } => {
+            let v = client.setting_get(&key)?;
+            println!("{}", serde_json::to_string(&v)?);
+        }
+        Cmd::Set { key, value, clear } => {
+            if clear {
+                let existed = client.setting_clear(&key)?;
+                if existed {
+                    println!("cleared override for '{key}'");
+                } else {
+                    println!("no override set for '{key}'");
+                }
+            } else {
+                let value = value.ok_or_else(|| {
+                    CliError::Other("provide a value, or use --clear to remove the override".into())
+                })?;
+                let parsed: serde_json::Value = serde_json::from_str(&value)
+                    .map_err(|e| CliError::Other(format!("value is not valid JSON: {e}")))?;
+                client.setting_set(&key, parsed)?;
+            }
+        }
+        Cmd::Bypass { state } => {
+            client.bypass_set(matches!(state, BypassState::On))?;
+        }
+        Cmd::Reset => {
+            let cleared = client.setting_reset()?;
+            println!("cleared {cleared} setting override(s)");
+        }
+        Cmd::Reload => {
+            let reloaded = client.profile_reload()?;
+            println!("reloaded: {reloaded:?}");
+        }
+        Cmd::Monitor { topics, json } => {
+            if json {
+                let pw_topics: Vec<Topic> =
+                    topics.iter().copied().map(Topic::from).collect();
+                client.subscribe(&pw_topics)?;
+                loop {
+                    let ev = client.next_event()?;
+                    println!(
+                        "{} {}/{} {}",
+                        chrono_like_now(),
+                        ev.topic,
+                        ev.event,
+                        serde_json::to_string(&ev.data)?,
+                    );
+                }
+            } else {
+                unreachable!("TUI monitor is dispatched before `with_client`")
+            }
+        }
+    }
+    Ok(())
+}
+
+#[derive(Debug, thiserror::Error)]
+enum CliError {
+    #[error("client: {0}")]
+    Client(#[from] ClientError),
+
+    #[error("daemon: {0}")]
+    Daemon(String),
+
+    #[error("json: {0}")]
+    Json(#[from] serde_json::Error),
+
+    #[cfg(feature = "tui")]
+    #[error("tui: {0}")]
+    Tui(tui::TuiError),
+
+    #[error("{0}")]
+    Other(String),
+}
+
+/// timestamp label for monitor output; `SystemTime` to avoid chrono.
+fn chrono_like_now() -> String {
+    use std::time::{SystemTime, UNIX_EPOCH};
+    let t = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default();
+    format!("{}.{:03}", t.as_secs(), t.subsec_millis())
+}
+
+fn main() -> ExitCode {
+    if let Err(e) = run() {
+        eprintln!("headroom: {e}");
+        return ExitCode::from(1);
+    }
+    ExitCode::SUCCESS
+}

Added file: crates/headroom-cli/src/tui.rs+1333 additions@@ -0,0 +1,1333 @@
+//! `headroom monitor` tui — bus gauges, loudness, per-stream routing.
+//!
+//! main thread owns terminal + draw loop; reader thread owns the `Client`,
+//! forwards events over a channel. no graceful reader shutdown — process
+//! exit tears the socket down.
+
+use std::collections::BTreeMap;
+use std::io;
+use std::thread;
+use std::time::{Duration, Instant};
+
+use crossbeam_channel::{select, tick, unbounded, Receiver};
+use crossterm::event::{self, Event as CtEvent, KeyCode, KeyEvent, KeyModifiers};
+use headroom_client::{Client, ClientError};
+use headroom_ipc::{
+    DaemonEvent, Event, LayerALevel, LayerASnapshot, MeterTick, Route, RoutingEvent, Status,
+    StreamRoute, Topic,
+};
+use ratatui::{
+    layout::{Alignment, Constraint, Direction, Layout, Rect},
+    style::{Color, Modifier, Style, Stylize},
+    text::{Line, Span},
+    widgets::{Block, Borders, Cell, Clear, Gauge, Paragraph, Row, Table, Wrap},
+    Frame, Terminal,
+};
+
+#[derive(Debug, thiserror::Error)]
+pub enum TuiError {
+    #[error("client: {0}")]
+    Client(#[from] ClientError),
+
+    #[error("terminal: {0}")]
+    Io(#[from] io::Error),
+}
+
+/// runs initial rpcs, then hands the client to the reader thread and
+/// enters the draw loop.
+pub fn run(mut client: Client) -> Result<(), TuiError> {
+    // subscribe + initial state before raw mode.
+    let topics = [Topic::Meters, Topic::Routing, Topic::Profile, Topic::Daemon];
+    client.subscribe(&topics)?;
+    let status = client.status()?;
+    let route_list = client.route_list()?;
+
+    // client is single-connection + the reader owns it for events; open a
+    // second connection for control (keypress ops).
+    let mut control = Client::connect_at(client.socket_path())?;
+
+    let (tx, rx) = unbounded::<Msg>();
+    let reader_handle = thread::Builder::new()
+        .name("headroom-monitor-rx".into())
+        .spawn(move || reader_loop(client, tx))
+        .map_err(TuiError::Io)?;
+
+    let mut terminal = ratatui::init();
+    let outcome = draw_loop(&mut terminal, status, route_list, rx, &mut control);
+    ratatui::restore();
+
+    // detach: process exit / dropped channel tears the connection down.
+    drop(reader_handle);
+
+    outcome
+}
+
+// ---------------------------------------------------------------------------
+// Reader thread
+// ---------------------------------------------------------------------------
+
+enum Msg {
+    Event(Event),
+    Disconnected(String),
+}
+
+fn reader_loop(mut client: Client, tx: crossbeam_channel::Sender<Msg>) {
+    loop {
+        match client.next_event() {
+            Ok(ev) => {
+                if tx.send(Msg::Event(ev)).is_err() {
+                    return;
+                }
+            }
+            Err(e) => {
+                let _ = tx.send(Msg::Disconnected(e.to_string()));
+                return;
+            }
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+
+struct UiState {
+    daemon_version: String,
+    profile: String,
+    bypass: bool,
+    /// layer a master switch (per-app level control enabled globally).
+    per_app_master: bool,
+    /// overlay overrides shadowing the profile; flagged so a stale
+    /// `headroom set` isn't invisible.
+    setting_overrides: BTreeMap<String, serde_json::Value>,
+    /// daemon uptime at connect, plus local elapsed.
+    base_uptime_s: u64,
+    connected_at: Instant,
+    default_route: Route,
+    streams: BTreeMap<u32, StreamRoute>,
+    /// per-stream layer a. presence = tap attached; inner = latest smoothed
+    /// reduction (none until the first `layer_a_level`).
+    layer_a: BTreeMap<u32, Option<f32>>,
+    /// richer layer a snapshots (ceiling/deferred/managed), polled from
+    /// `per-app.list`; feeds the detail line.
+    la_snapshots: BTreeMap<u32, LayerASnapshot>,
+    /// selected stream node id; resolved against `streams` at draw time.
+    selected: Option<u32>,
+    meters: Option<MeterTick>,
+    /// last tick arrival; drives staleness when the source goes silent.
+    last_meter_at: Option<Instant>,
+    overflow_total: u64,
+    last_error: Option<String>,
+    disconnected: Option<String>,
+    /// modal profile picker; while `Some` it intercepts all keyboard input.
+    picker: Option<ProfilePicker>,
+}
+
+/// modal profile-switcher; `selected` indexes `profiles`.
+struct ProfilePicker {
+    profiles: Vec<headroom_ipc::ProfileInfo>,
+    selected: usize,
+}
+
+impl ProfilePicker {
+    /// move the highlight by `delta` (negative = up), wrapping.
+    fn move_sel(&mut self, delta: isize) {
+        if self.profiles.is_empty() {
+            return;
+        }
+        let n = self.profiles.len() as isize;
+        self.selected = (self.selected as isize + delta).rem_euclid(n) as usize;
+    }
+}
+
+/// initial highlight: active profile, else the daemon's current name, else top.
+fn initial_picker_selection(profiles: &[headroom_ipc::ProfileInfo], current: &str) -> usize {
+    profiles
+        .iter()
+        .position(|p| p.active)
+        .or_else(|| profiles.iter().position(|p| p.name == current))
+        .unwrap_or(0)
+}
+
+impl UiState {
+    fn new(status: Status, route_list: headroom_ipc::RouteList) -> Self {
+        let mut streams = BTreeMap::new();
+        for s in route_list.current {
+            streams.insert(s.node_id, s);
+        }
+        // `status.streams` is a superset; merge.
+        for s in status.streams.iter() {
+            streams.entry(s.node_id).or_insert_with(|| s.clone());
+        }
+        // seed layer a from status so table/detail are populated pre-poll.
+        let mut la_snapshots = BTreeMap::new();
+        let mut layer_a = BTreeMap::new();
+        for snap in status.layer_a {
+            layer_a.insert(snap.node_id, Some(snap.reduction_db));
+            la_snapshots.insert(snap.node_id, snap);
+        }
+        let selected = streams.keys().next().copied();
+        Self {
+            daemon_version: status.version,
+            profile: status.profile,
+            bypass: status.bypass,
+            per_app_master: status.per_app,
+            setting_overrides: status.setting_overrides,
+            base_uptime_s: status.uptime_s,
+            connected_at: Instant::now(),
+            default_route: route_list.default_route,
+            streams,
+            layer_a,
+            la_snapshots,
+            selected,
+            meters: None,
+            last_meter_at: None,
+            overflow_total: 0,
+            last_error: None,
+            disconnected: None,
+            picker: None,
+        }
+    }
+
+    fn uptime_s(&self) -> u64 {
+        self.base_uptime_s
+            .saturating_add(self.connected_at.elapsed().as_secs())
+    }
+
+    /// stream node ids in row order (`BTreeMap` keys).
+    fn ordered_nodes(&self) -> Vec<u32> {
+        self.streams.keys().copied().collect()
+    }
+
+    /// `selected` when still live, else the first row, else `None`.
+    fn effective_selection(&self) -> Option<u32> {
+        match self.selected {
+            Some(id) if self.streams.contains_key(&id) => Some(id),
+            _ => self.streams.keys().next().copied(),
+        }
+    }
+
+    /// move the selection by `delta` rows (negative = up), wrapping.
+    fn move_selection(&mut self, delta: isize) {
+        let nodes = self.ordered_nodes();
+        if nodes.is_empty() {
+            self.selected = None;
+            return;
+        }
+        let cur = self
+            .effective_selection()
+            .and_then(|id| nodes.iter().position(|&n| n == id))
+            .unwrap_or(0) as isize;
+        let next = (cur + delta).rem_euclid(nodes.len() as isize) as usize;
+        self.selected = Some(nodes[next]);
+    }
+
+    fn apply_event(&mut self, ev: Event) {
+        match ev.topic {
+            Topic::Meters if ev.event == "tick" => {
+                if let Ok(m) = serde_json::from_value::<MeterTick>(ev.data) {
+                    self.meters = Some(m);
+                    self.last_meter_at = Some(Instant::now());
+                }
+            }
+            Topic::Meters if ev.event == "layer_a_level" => {
+                if let Ok(l) = serde_json::from_value::<LayerALevel>(ev.data) {
+                    self.layer_a.insert(l.node_id, Some(l.reduction_db));
+                }
+            }
+            Topic::Routing => {
+                if let Ok(re) = serde_json::from_value::<RoutingEvent>(routing_payload(&ev)) {
+                    match re {
+                        RoutingEvent::StreamRouted { node_id, app, to } => {
+                            self.streams.insert(
+                                node_id,
+                                StreamRoute {
+                                    node_id,
+                                    app,
+                                    route: to,
+                                },
+                            );
+                        }
+                        RoutingEvent::StreamRemoved { node_id } => {
+                            self.streams.remove(&node_id);
+                            self.layer_a.remove(&node_id);
+                            self.la_snapshots.remove(&node_id);
+                        }
+                        RoutingEvent::LayerAAttached { node_id, .. } => {
+                            // reduction unknown until the first `layer_a_level`.
+                            self.layer_a.entry(node_id).or_insert(None);
+                        }
+                        RoutingEvent::LayerADetached { node_id } => {
+                            self.layer_a.remove(&node_id);
+                            self.la_snapshots.remove(&node_id);
+                        }
+                        RoutingEvent::RuleChanged => { /* tui doesn't show rules */ }
+                        _ => {}
+                    }
+                }
+            }
+            Topic::Profile => {
+                match ev.event.as_str() {
+                    "used" | "changed" => {
+                        if let Some(name) = ev.data.get("name").and_then(|v| v.as_str()) {
+                            self.profile = name.to_string();
+                        }
+                    }
+                    _ => {}
+                }
+            }
+            Topic::Daemon => {
+                if let Ok(de) = serde_json::from_value::<DaemonEvent>(daemon_payload(&ev)) {
+                    match de {
+                        DaemonEvent::Overflow {
+                            lost, total_lost, ..
+                        } => {
+                            self.overflow_total = total_lost.max(self.overflow_total + lost as u64);
+                        }
+                        DaemonEvent::Error { code, message } => {
+                            self.last_error = Some(format!("{code}: {message}"));
+                        }
+                        DaemonEvent::Shutdown => {
+                            self.disconnected = Some("daemon shutdown".into());
+                        }
+                        DaemonEvent::Started { version } => {
+                            self.daemon_version = version;
+                        }
+                        _ => {}
+                    }
+                }
+            }
+            _ => {}
+        }
+    }
+}
+
+/// typed event enums are `#[serde(tag = "event")]` but the wire frame keeps
+/// `event` outside `data`, so re-inject it before deserializing.
+fn routing_payload(ev: &Event) -> serde_json::Value {
+    inject_event(&ev.event, &ev.data)
+}
+fn daemon_payload(ev: &Event) -> serde_json::Value {
+    inject_event(&ev.event, &ev.data)
+}
+
+fn inject_event(event: &str, data: &serde_json::Value) -> serde_json::Value {
+    let mut obj = match data {
+        serde_json::Value::Object(m) => m.clone(),
+        _ => serde_json::Map::new(),
+    };
+    obj.insert("event".into(), serde_json::Value::String(event.to_string()));
+    serde_json::Value::Object(obj)
+}
+
+// ---------------------------------------------------------------------------
+// Draw loop
+// ---------------------------------------------------------------------------
+
+fn draw_loop<B: ratatui::backend::Backend>(
+    terminal: &mut Terminal<B>,
+    status: Status,
+    route_list: headroom_ipc::RouteList,
+    rx: Receiver<Msg>,
+    control: &mut Client,
+) -> Result<(), TuiError> {
+    let mut state = UiState::new(status, route_list);
+    // 10 Hz redraw floor so uptime/staleness tick with no events flowing.
+    let ticker = tick(Duration::from_millis(100));
+    let input_rx = spawn_input_thread();
+    // ~1 Hz poll of the richer layer a snapshot.
+    let mut poll_ticks: u32 = 0;
+
+    loop {
+        terminal.draw(|f| draw(f, &state))?;
+
+        select! {
+            recv(rx) -> msg => match msg {
+                Ok(Msg::Event(ev)) => state.apply_event(ev),
+                Ok(Msg::Disconnected(reason)) => {
+                    state.disconnected = Some(reason);
+                    // final paint, then linger so the banner is seen.
+                    terminal.draw(|f| draw(f, &state))?;
+                    thread::sleep(Duration::from_millis(800));
+                    return Ok(());
+                }
+                Err(_) => return Ok(()),
+            },
+            recv(input_rx) -> msg => match msg {
+                Ok(InputMsg::Key(k)) => {
+                    if handle_key(&mut state, control, k) {
+                        return Ok(());
+                    }
+                }
+                Ok(InputMsg::Redraw) => {}
+                Err(_) => return Ok(()),
+            },
+            recv(ticker) -> _ => {
+                poll_ticks = poll_ticks.wrapping_add(1);
+                if poll_ticks % 10 == 0 {
+                    poll_layer_a(&mut state, control);
+                }
+            }
+        }
+    }
+}
+
+/// refresh layer a snapshots from the control connection; errors go to the
+/// footer (non-fatal — the event stream keeps the ui live).
+fn poll_layer_a(state: &mut UiState, control: &mut Client) {
+    match control.layer_a_list() {
+        Ok(list) => {
+            state.la_snapshots = list.into_iter().map(|s| (s.node_id, s)).collect();
+        }
+        Err(e) => {
+            state.last_error = Some(format!("layer-a poll: {e}"));
+        }
+    }
+}
+
+/// apply a keypress: nav + toggles + per-row actions. control ops run
+/// synchronously on the control connection; failures land in the footer.
+/// returns `true` to quit.
+fn handle_key(state: &mut UiState, control: &mut Client, k: KeyEvent) -> bool {
+    // ctrl-c: hard exit, even with the picker open.
+    if k.modifiers.contains(KeyModifiers::CONTROL)
+        && matches!(k.code, KeyCode::Char('c') | KeyCode::Char('C'))
+    {
+        return true;
+    }
+    // picker is modal: while open it swallows every other key.
+    if state.picker.is_some() {
+        handle_picker_key(state, control, k);
+        return false;
+    }
+    if is_quit(&k) {
+        return true;
+    }
+    match k.code {
+        KeyCode::Char('j') | KeyCode::Down => state.move_selection(1),
+        KeyCode::Char('k') | KeyCode::Up => state.move_selection(-1),
+        KeyCode::Char('P') => open_profile_picker(state, control),
+        KeyCode::Char('b') => {
+            let target = !state.bypass;
+            match control.bypass_set(target) {
+                Ok(()) => state.bypass = target,
+                Err(e) => state.last_error = Some(format!("bypass: {e}")),
+            }
+        }
+        KeyCode::Char('p') => {
+            let target = !state.per_app_master;
+            match control.per_app_master(target) {
+                Ok(()) => state.per_app_master = target,
+                Err(e) => state.last_error = Some(format!("per-app master: {e}")),
+            }
+        }
+        KeyCode::Char('r') | KeyCode::Enter => {
+            let Some(node) = state.effective_selection() else {
+                return false;
+            };
+            let Some(stream) = state.streams.get(&node) else {
+                return false;
+            };
+            let app = stream.app.clone();
+            let to = match stream.route {
+                Route::Processed => Route::Bypass,
+                Route::Bypass => Route::Processed,
+            };
+            // prefer a persistent per-app rule (keyed by app label) so the
+            // route survives the app recreating its stream between tracks;
+            // fall back to a one-shot per-stream reroute when no label.
+            let result = if app.is_empty() {
+                control.route_stream(node, to)
+            } else {
+                control.route_set(&app, to)
+            };
+            match result {
+                Ok(()) => {
+                    if let Some(s) = state.streams.get_mut(&node) {
+                        s.route = to;
+                    }
+                }
+                Err(e) => state.last_error = Some(format!("route: {e}")),
+            }
+        }
+        KeyCode::Char('a') => {
+            let Some(node) = state.effective_selection() else {
+                return false;
+            };
+            let Some(app) = state.streams.get(&node).map(|s| s.app.clone()) else {
+                return false;
+            };
+            if app.is_empty() {
+                state.last_error = Some("per-app: selected stream has no app label".into());
+                return false;
+            }
+            let managed = state.la_snapshots.get(&node).is_some_and(|s| s.managed);
+            if let Err(e) = control.per_app_set(&app, !managed) {
+                state.last_error = Some(format!("per-app set: {e}"));
+            }
+        }
+        KeyCode::Char('x') => {
+            let Some(node) = state.effective_selection() else {
+                return false;
+            };
+            if let Err(e) = control.layer_a_reset(node) {
+                state.last_error = Some(format!("reset: {e}"));
+            }
+        }
+        KeyCode::Char('c') => {
+            // clear all overlay overrides; no-op when none.
+            if state.setting_overrides.is_empty() {
+                return false;
+            }
+            match control.setting_reset() {
+                Ok(_) => state.setting_overrides.clear(),
+                Err(e) => state.last_error = Some(format!("clear overrides: {e}")),
+            }
+        }
+        _ => {}
+    }
+    false
+}
+
+/// open the modal profile picker from `profile.list`; errors → footer.
+fn open_profile_picker(state: &mut UiState, control: &mut Client) {
+    match control.profile_list() {
+        Ok(profiles) if profiles.is_empty() => {
+            state.last_error = Some("profile list is empty".into());
+        }
+        Ok(profiles) => {
+            let selected = initial_picker_selection(&profiles, &state.profile);
+            state.picker = Some(ProfilePicker { profiles, selected });
+        }
+        Err(e) => state.last_error = Some(format!("profile list: {e}")),
+    }
+}
+
+/// handle a keypress while the profile picker is open.
+fn handle_picker_key(state: &mut UiState, control: &mut Client, k: KeyEvent) {
+    let Some(picker) = state.picker.as_mut() else {
+        return;
+    };
+    match k.code {
+        KeyCode::Char('j') | KeyCode::Down => picker.move_sel(1),
+        KeyCode::Char('k') | KeyCode::Up => picker.move_sel(-1),
+        KeyCode::Esc | KeyCode::Char('q') => state.picker = None,
+        KeyCode::Enter => {
+            let Some(name) = picker.profiles.get(picker.selected).map(|p| p.name.clone()) else {
+                state.picker = None;
+                return;
+            };
+            match control.profile_use(&name) {
+                Ok(applied) => {
+                    // set eagerly; the `profile.changed` event also lands.
+                    state.profile = applied;
+                    state.picker = None;
+                }
+                Err(e) => {
+                    // keep the picker open to retry/cancel.
+                    state.last_error = Some(format!("profile use: {e}"));
+                }
+            }
+        }
+        _ => {}
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Input thread
+// ---------------------------------------------------------------------------
+
+enum InputMsg {
+    Key(KeyEvent),
+    Redraw,
+}
+
+fn spawn_input_thread() -> Receiver<InputMsg> {
+    let (tx, rx) = unbounded::<InputMsg>();
+    thread::Builder::new()
+        .name("headroom-monitor-input".into())
+        .spawn(move || loop {
+            let Ok(ev) = event::read() else { return };
+            // forward keys to the draw loop; quit/modal decisions need ui state.
+            let msg = match ev {
+                CtEvent::Key(k) => InputMsg::Key(k),
+                CtEvent::Resize(_, _) => InputMsg::Redraw,
+                _ => continue,
+            };
+            if tx.send(msg).is_err() {
+                return;
+            }
+        })
+        .expect("spawn input thread");
+    rx
+}
+
+fn is_quit(k: &KeyEvent) -> bool {
+    matches!(k.code, KeyCode::Char('q') | KeyCode::Esc)
+        || (k.modifiers.contains(KeyModifiers::CONTROL)
+            && matches!(k.code, KeyCode::Char('c') | KeyCode::Char('C')))
+}
+
+// ---------------------------------------------------------------------------
+// Drawing
+// ---------------------------------------------------------------------------
+
+fn draw(f: &mut Frame, state: &UiState) {
+    let area = f.area();
+    let outer = Block::default()
+        .borders(Borders::ALL)
+        .title(Span::styled(
+            " headroom monitor ",
+            Style::default().add_modifier(Modifier::BOLD),
+        ))
+        .title_top(Line::from(header_status(state)).right_aligned())
+        .title_bottom(Line::from(footer_text(state)).right_aligned());
+    let inner = outer.inner(area);
+    f.render_widget(outer, area);
+
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(6), // bus gauges
+            Constraint::Length(5), // loudness
+            Constraint::Min(4),    // streams table
+            Constraint::Length(3), // layer A detail (selected stream)
+        ])
+        .split(inner);
+
+    draw_bus(f, chunks[0], state);
+    draw_loudness(f, chunks[1], state);
+    draw_streams(f, chunks[2], state);
+    draw_layer_a_detail(f, chunks[3], state);
+
+    // modal overlay, drawn last so it sits on top.
+    if let Some(picker) = &state.picker {
+        draw_profile_picker(f, area, picker);
+    }
+}
+
+/// centered rect, at most `width`×`height`, clamped to `area`.
+fn centered_rect(width: u16, height: u16, area: Rect) -> Rect {
+    let w = width.min(area.width);
+    let h = height.min(area.height);
+    Rect {
+        x: area.x + (area.width - w) / 2,
+        y: area.y + (area.height - h) / 2,
+        width: w,
+        height: h,
+    }
+}
+
+/// modal profile switcher: centered list, active marked (●), highlighted
+/// reversed, plus a description line.
+fn draw_profile_picker(f: &mut Frame, area: Rect, picker: &ProfilePicker) {
+    let rows = picker.profiles.len() as u16;
+    // rows + 2 borders + 2 description lines.
+    let rect = centered_rect(60, rows + 4, area);
+
+    f.render_widget(Clear, rect);
+    let block = Block::default()
+        .borders(Borders::ALL)
+        .title(" switch profile ")
+        .title_bottom(Line::from(" j/k move · Enter apply · Esc cancel ").right_aligned());
+    let inner = block.inner(rect);
+    f.render_widget(block, rect);
+
+    let parts = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([Constraint::Min(1), Constraint::Length(2)])
+        .split(inner);
+
+    let lines: Vec<Line> = picker
+        .profiles
+        .iter()
+        .enumerate()
+        .map(|(i, p)| {
+            let marker = if p.active { "●" } else { " " };
+            let style = if i == picker.selected {
+                Style::default().add_modifier(Modifier::REVERSED)
+            } else if p.active {
+                Style::default().fg(Color::Green)
+            } else {
+                Style::default()
+            };
+            Line::from(vec![
+                Span::raw(format!(" {marker} ")),
+                Span::styled(p.name.clone(), style),
+            ])
+        })
+        .collect();
+    f.render_widget(Paragraph::new(lines), parts[0]);
+
+    let desc = picker
+        .profiles
+        .get(picker.selected)
+        .map(|p| p.description.clone())
+        .unwrap_or_default();
+    f.render_widget(
+        Paragraph::new(Line::from(Span::styled(
+            format!(" {desc}"),
+            Style::default().fg(Color::DarkGray),
+        )))
+        .wrap(Wrap { trim: true }),
+        parts[1],
+    );
+}
+
+fn header_status(state: &UiState) -> Vec<Span<'static>> {
+    let bypass_span = if state.bypass {
+        Span::styled(
+            " BYPASS ",
+            Style::default().fg(Color::Black).bg(Color::Yellow),
+        )
+    } else {
+        Span::styled(" processed ", Style::default().fg(Color::Green))
+    };
+    let per_app_span = if state.per_app_master {
+        Span::styled(" per-app ", Style::default().fg(Color::Cyan))
+    } else {
+        Span::styled(" per-app off ", Style::default().fg(Color::DarkGray))
+    };
+    vec![
+        Span::raw(" profile: "),
+        Span::styled(state.profile.clone(), Style::default().bold()),
+        Span::raw("  "),
+        bypass_span,
+        Span::raw(" "),
+        per_app_span,
+        Span::raw(format!(
+            "  v{}  uptime {}  ",
+            state.daemon_version,
+            fmt_uptime(state.uptime_s())
+        )),
+    ]
+}
+
+fn footer_text(state: &UiState) -> Vec<Span<'static>> {
+    let sep = || Span::styled("·", Style::default().fg(Color::DarkGray));
+    let mut parts: Vec<Span> = vec![
+        Span::raw(" j/k select "),
+        sep(),
+        Span::raw(" r route "),
+        sep(),
+        Span::raw(" a per-app "),
+        sep(),
+        Span::raw(" x reset "),
+        sep(),
+        Span::raw(" b bypass "),
+        sep(),
+        Span::raw(" p per-app "),
+        sep(),
+        Span::raw(" P profile "),
+        sep(),
+        Span::raw(" q quit "),
+    ];
+    if state.overflow_total > 0 {
+        parts.push(Span::styled("·", Style::default().fg(Color::DarkGray)));
+        parts.push(Span::styled(
+            format!(" dropped: {} ", state.overflow_total),
+            Style::default().fg(Color::Yellow),
+        ));
+    }
+    if let Some(err) = &state.last_error {
+        parts.push(Span::styled("·", Style::default().fg(Color::DarkGray)));
+        parts.push(Span::styled(
+            format!(" daemon error: {err} "),
+            Style::default().fg(Color::Red),
+        ));
+    }
+    if let Some(reason) = &state.disconnected {
+        parts.push(Span::styled("·", Style::default().fg(Color::DarkGray)));
+        parts.push(Span::styled(
+            format!(" disconnected: {reason} "),
+            Style::default().fg(Color::Red).add_modifier(Modifier::BOLD),
+        ));
+    }
+    if !state.setting_overrides.is_empty() {
+        parts.push(Span::styled("·", Style::default().fg(Color::DarkGray)));
+        parts.push(Span::styled(
+            format!(
+                " overrides: {} (c clear) ",
+                fmt_overrides(&state.setting_overrides)
+            ),
+            Style::default().fg(Color::Yellow).add_modifier(Modifier::BOLD),
+        ));
+    }
+    parts
+}
+
+/// active overrides as `key=value, …` for the footer (strings unquoted,
+/// else json).
+fn fmt_overrides(map: &BTreeMap<String, serde_json::Value>) -> String {
+    map.iter()
+        .map(|(k, v)| {
+            let val = match v {
+                serde_json::Value::String(s) => s.clone(),
+                other => other.to_string(),
+            };
+            format!("{k}={val}")
+        })
+        .collect::<Vec<_>>()
+        .join(", ")
+}
+
+fn draw_bus(f: &mut Frame, area: Rect, state: &UiState) {
+    let block = Block::default()
+        .borders(Borders::ALL)
+        .title(" bus dsp ");
+    let inner = block.inner(area);
+    f.render_widget(block, area);
+
+    let rows = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(1),
+            Constraint::Length(1),
+            Constraint::Length(1),
+            Constraint::Length(1),
+        ])
+        .split(inner);
+
+    let m = state.meters;
+    draw_gauge_row(
+        f,
+        rows[0],
+        GaugeRow {
+            label: "AGC target",
+            value: m.map(|t| t.agc_gain_db),
+            min: -12.0,
+            max: 12.0,
+            unit: "dB",
+            color: Color::Cyan,
+            enabled: m.map(|t| t.agc_enabled).unwrap_or(true),
+        },
+    );
+    draw_gauge_row(
+        f,
+        rows[1],
+        GaugeRow {
+            label: "Compressor GR",
+            value: m.map(|t| t.compressor_gr_db),
+            min: -24.0,
+            max: 0.0,
+            unit: "dB",
+            color: Color::Magenta,
+            enabled: m.map(|t| t.compressor_enabled).unwrap_or(true),
+        },
+    );
+    draw_gauge_row(
+        f,
+        rows[2],
+        GaugeRow {
+            label: "Limiter GR",
+            value: m.map(|t| t.limiter_gr_db),
+            min: -24.0,
+            max: 0.0,
+            unit: "dB",
+            color: Color::Red,
+            enabled: true, // always-on safety backstop
+        },
+    );
+    draw_gauge_row(
+        f,
+        rows[3],
+        GaugeRow {
+            label: "True peak",
+            value: m.map(|t| t.true_peak_dbtp),
+            min: -60.0,
+            max: 3.0,
+            unit: "dBTP",
+            color: Color::Green,
+            enabled: true, // a measurement, always meaningful
+        },
+    );
+}
+
+struct GaugeRow<'a> {
+    label: &'a str,
+    value: Option<f32>,
+    min: f32,
+    max: f32,
+    unit: &'a str,
+    color: Color,
+    /// stage enabled in the active profile; when false the row renders
+    /// "disabled" + a greyed bar so a bypassed stage isn't read as 0.
+    enabled: bool,
+}
+
+/// one gauge row: `LABEL   VALUE   [████░░░░] min..max`.
+fn draw_gauge_row(f: &mut Frame, area: Rect, row: GaugeRow<'_>) {
+    let GaugeRow {
+        label,
+        value,
+        min,
+        max,
+        unit,
+        color,
+        enabled,
+    } = row;
+    let cols = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([
+            Constraint::Length(16),
+            Constraint::Length(14),
+            Constraint::Min(8),
+            Constraint::Length(14),
+        ])
+        .split(area);
+
+    // disabled stage: grey the row + say so, so it can't read as 0.
+    if !enabled {
+        let dim = Style::default().fg(Color::DarkGray);
+        f.render_widget(Paragraph::new(format!(" {label}")).style(dim), cols[0]);
+        f.render_widget(
+            Paragraph::new("disabled").alignment(Alignment::Right).style(dim),
+            cols[1],
+        );
+        f.render_widget(
+            Gauge::default()
+                .gauge_style(dim)
+                .ratio(0.0)
+                .label("off"),
+            cols[2],
+        );
+        f.render_widget(
+            Paragraph::new(format!("{min:.0}..{max:.0} "))
+                .alignment(Alignment::Right)
+                .style(dim),
+            cols[3],
+        );
+        return;
+    }
+
+    f.render_widget(Paragraph::new(format!(" {label}")), cols[0]);
+
+    let value_str = value
+        .map(|v| format!("{v:+7.2} {unit}"))
+        .unwrap_or_else(|| "    -- ".to_string());
+    f.render_widget(
+        Paragraph::new(value_str).alignment(Alignment::Right),
+        cols[1],
+    );
+
+    let pct = match value {
+        Some(v) => {
+            let clamped = v.clamp(min, max);
+            ((clamped - min) / (max - min)).clamp(0.0, 1.0) as f64
+        }
+        None => 0.0,
+    };
+    let gauge = Gauge::default()
+        .gauge_style(Style::default().fg(color))
+        .ratio(pct)
+        .label("");
+    f.render_widget(gauge, cols[2]);
+
+    f.render_widget(
+        Paragraph::new(format!("{min:.0}..{max:.0} ")).alignment(Alignment::Right),
+        cols[3],
+    );
+}
+
+fn draw_loudness(f: &mut Frame, area: Rect, state: &UiState) {
+    let block = Block::default()
+        .borders(Borders::ALL)
+        .title(" loudness (BS.1770) ");
+    let inner = block.inner(area);
+    f.render_widget(block, area);
+
+    let staleness = state
+        .last_meter_at
+        .map(|t| t.elapsed())
+        .unwrap_or(Duration::ZERO);
+    let stale = staleness > Duration::from_millis(500);
+
+    let (mom, st, intg) = match state.meters {
+        Some(m) => (Some(m.momentary_lufs), Some(m.shortterm_lufs), Some(m.integrated_lufs)),
+        None => (None, None, None),
+    };
+
+    let lines = vec![
+        lufs_line("Momentary  (400 ms)", mom, stale),
+        lufs_line("Short-term (3 s)", st, stale),
+        lufs_line("Integrated (gated)", intg, stale),
+    ];
+    f.render_widget(Paragraph::new(lines), inner);
+}
+
+fn lufs_line(label: &str, v: Option<f32>, stale: bool) -> Line<'static> {
+    let val = match v {
+        Some(x) if x > headroom_core::agc::LOUDNESS_FLOOR_LUFS + 0.5 => {
+            format!("{x:+7.2} LUFS")
+        }
+        Some(_) => "    -- LUFS".to_string(),
+        None => "    -- LUFS".to_string(),
+    };
+    let style = if stale {
+        Style::default().fg(Color::DarkGray)
+    } else {
+        Style::default()
+    };
+    Line::from(vec![
+        Span::raw(format!(" {label:<24}")),
+        Span::styled(val, style),
+    ])
+}
+
+fn draw_streams(f: &mut Frame, area: Rect, state: &UiState) {
+    let title = format!(
+        " streams ({}) — default: {} ",
+        state.streams.len(),
+        state.default_route
+    );
+    let block = Block::default().borders(Borders::ALL).title(title);
+
+    let header = Row::new(vec!["", "node", "app", "route", "per-app"])
+        .style(Style::default().add_modifier(Modifier::BOLD));
+
+    let selected = state.effective_selection();
+    let rows: Vec<Row> = state
+        .streams
+        .values()
+        .map(|s| {
+            let is_sel = selected == Some(s.node_id);
+            let route_cell = match s.route {
+                Route::Processed => Cell::from("processed").style(Style::default().fg(Color::Green)),
+                Route::Bypass => Cell::from("bypass").style(Style::default().fg(Color::Yellow)),
+            };
+            let la_cell = match state.layer_a.get(&s.node_id) {
+                Some(Some(db)) => Cell::from(format!("{db:+5.1} dB"))
+                    .style(Style::default().fg(Color::Magenta)),
+                Some(None) => Cell::from("attached")
+                    .style(Style::default().fg(Color::DarkGray)),
+                None => Cell::from("—").style(Style::default().fg(Color::DarkGray)),
+            };
+            let marker = if is_sel { "▶" } else { " " };
+            let row = Row::new(vec![
+                Cell::from(marker),
+                Cell::from(s.node_id.to_string()),
+                Cell::from(s.app.clone()),
+                route_cell,
+                la_cell,
+            ]);
+            if is_sel {
+                row.style(Style::default().add_modifier(Modifier::REVERSED))
+            } else {
+                row
+            }
+        })
+        .collect();
+
+    let widths = [
+        Constraint::Length(2),
+        Constraint::Length(8),
+        Constraint::Min(20),
+        Constraint::Length(12),
+        Constraint::Length(10),
+    ];
+    let table = Table::new(rows, widths).header(header).block(block);
+    f.render_widget(table, area);
+}
+
+/// read-only layer a detail for the selected stream: managed flag,
+/// smoothed reduction, user ceiling, deference lock.
+fn draw_layer_a_detail(f: &mut Frame, area: Rect, state: &UiState) {
+    let block = Block::default()
+        .borders(Borders::ALL)
+        .title(" per-app level (selected) ");
+    let inner = block.inner(area);
+    f.render_widget(block, area);
+
+    let line = match state.effective_selection() {
+        None => Line::from(Span::styled(
+            " no stream selected",
+            Style::default().fg(Color::DarkGray),
+        )),
+        Some(node) => {
+            let app = state
+                .streams
+                .get(&node)
+                .map(|s| s.app.clone())
+                .unwrap_or_default();
+            match state.la_snapshots.get(&node) {
+                Some(snap) => {
+                    let ceiling = snap
+                        .user_ceiling_lin
+                        .map(|c| format!("{c:.2}"))
+                        .unwrap_or_else(|| "—".to_string());
+                    let deferred = if snap.deferred {
+                        Span::styled("deferred", Style::default().fg(Color::Yellow))
+                    } else {
+                        Span::styled("active", Style::default().fg(Color::Green))
+                    };
+                    Line::from(vec![
+                        Span::raw(format!(" node {node}  {app}  ")),
+                        Span::styled(
+                            if snap.managed { "managed" } else { "unmanaged" },
+                            Style::default().fg(if snap.managed {
+                                Color::Cyan
+                            } else {
+                                Color::DarkGray
+                            }),
+                        ),
+                        Span::raw(format!(
+                            "  reduction {:+.1} dB  ceiling {ceiling}  ",
+                            snap.reduction_db
+                        )),
+                        deferred,
+                    ])
+                }
+                None => Line::from(Span::styled(
+                    format!(" node {node}  {app}  not managed per-app"),
+                    Style::default().fg(Color::DarkGray),
+                )),
+            }
+        }
+    };
+    f.render_widget(Paragraph::new(line), inner);
+}
+
+fn fmt_uptime(s: u64) -> String {
+    let h = s / 3600;
+    let m = (s % 3600) / 60;
+    let sec = s % 60;
+    if h > 0 {
+        format!("{h}h{m:02}m{sec:02}s")
+    } else if m > 0 {
+        format!("{m}m{sec:02}s")
+    } else {
+        format!("{sec}s")
+    }
+}
+
+#[cfg(test)]
+mod state_tests;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use headroom_ipc::{Sinks, Status};
+
+    fn empty_state() -> UiState {
+        let status = Status {
+            version: "test".into(),
+            protocol: 1,
+            uptime_s: 0,
+            profile: "default".into(),
+            bypass: false,
+            per_app: false,
+            sinks: Sinks::default(),
+            streams: vec![],
+            layer_a: vec![],
+            warnings: vec![],
+            setting_overrides: Default::default(),
+        };
+        let route_list = headroom_ipc::RouteList {
+            rules: vec![],
+            current: vec![],
+            default_route: Route::Processed,
+        };
+        UiState::new(status, route_list)
+    }
+
+    #[test]
+    fn meter_tick_event_updates_state() {
+        let mut state = empty_state();
+        let tick = MeterTick {
+            momentary_lufs: -19.3,
+            shortterm_lufs: -20.1,
+            integrated_lufs: -19.8,
+            true_peak_dbtp: -1.4,
+            gain_reduction_db: -2.1,
+            compressor_gr_db: -0.8,
+            limiter_gr_db: -1.3,
+            agc_gain_db: 0.5,
+            agc_enabled: true,
+            compressor_enabled: true,
+        };
+        let ev = Event::new(Topic::Meters, "tick", &tick).unwrap();
+        state.apply_event(ev);
+        let got = state.meters.expect("meters set");
+        assert!((got.momentary_lufs - tick.momentary_lufs).abs() < f32::EPSILON);
+        assert!((got.true_peak_dbtp - tick.true_peak_dbtp).abs() < f32::EPSILON);
+        assert!(state.last_meter_at.is_some());
+    }
+
+    #[test]
+    fn stream_removed_prunes_state() {
+        let mut state = empty_state();
+        // insert via stream_routed first.
+        state.apply_event(
+            Event::new(
+                Topic::Routing,
+                "stream_routed",
+                &serde_json::json!({ "node_id": 7, "app": "x", "to": "processed" }),
+            )
+            .unwrap(),
+        );
+        state.apply_event(
+            Event::new(
+                Topic::Routing,
+                "layer_a_attached",
+                &serde_json::json!({ "node_id": 7, "app": "x" }),
+            )
+            .unwrap(),
+        );
+        assert!(state.streams.contains_key(&7));
+        assert!(state.layer_a.contains_key(&7));
+        state.la_snapshots.insert(
+            7,
+            LayerASnapshot {
+                node_id: 7,
+                app: "x".into(),
+                managed: true,
+                volume_lin: 1.0,
+                reduction_db: -3.0,
+                user_ceiling_lin: Some(0.8),
+                deferred: true,
+            },
+        );
+
+        state.apply_event(
+            Event::new(
+                Topic::Routing,
+                "stream_removed",
+                &serde_json::json!({ "node_id": 7 }),
+            )
+            .unwrap(),
+        );
+        assert!(!state.streams.contains_key(&7));
+        assert!(!state.layer_a.contains_key(&7));
+        assert!(!state.la_snapshots.contains_key(&7));
+    }
+
+    #[test]
+    fn layer_a_level_updates_reduction() {
+        let mut state = empty_state();
+        state.apply_event(
+            Event::new(
+                Topic::Routing,
+                "layer_a_attached",
+                &serde_json::json!({ "node_id": 11, "app": "loud-app" }),
+            )
+            .unwrap(),
+        );
+        assert_eq!(state.layer_a.get(&11), Some(&None));
+
+        state.apply_event(
+            Event::new(
+                Topic::Meters,
+                "layer_a_level",
+                &serde_json::json!({
+                    "node_id": 11,
+                    "app": "loud-app",
+                    "volume_lin": 0.256_f32,
+                    "reduction_db": -11.8_f32,
+                }),
+            )
+            .unwrap(),
+        );
+        let r = state.layer_a.get(&11).copied().flatten().unwrap();
+        assert!((r - -11.8).abs() < 1e-4);
+    }
+
+    #[test]
+    fn routing_event_inserts_stream() {
+        let mut state = empty_state();
+        let ev = Event::new(
+            Topic::Routing,
+            "stream_routed",
+            &serde_json::json!({
+                "node_id": 42,
+                "app": "firefox",
+                "to": "bypass",
+            }),
+        )
+        .unwrap();
+        state.apply_event(ev);
+        let s = state.streams.get(&42).expect("stream tracked");
+        assert_eq!(s.app, "firefox");
+        assert_eq!(s.route, Route::Bypass);
+    }
+
+    #[test]
+    fn profile_changed_updates_active() {
+        let mut state = empty_state();
+        let ev = Event::new(
+            Topic::Profile,
+            "changed",
+            &serde_json::json!({
+                "name": "night",
+                "previous": "default",
+            }),
+        )
+        .unwrap();
+        state.apply_event(ev);
+        assert_eq!(state.profile, "night");
+    }
+
+    #[test]
+    fn daemon_overflow_accumulates() {
+        let mut state = empty_state();
+        let ev = Event::new(
+            Topic::Daemon,
+            "overflow",
+            &serde_json::json!({
+                "lost_topic": "meters",
+                "lost": 3u32,
+                "total_lost": 5u64,
+            }),
+        )
+        .unwrap();
+        state.apply_event(ev);
+        assert_eq!(state.overflow_total, 5);
+    }
+
+    fn pinfo(name: &str, active: bool) -> headroom_ipc::ProfileInfo {
+        headroom_ipc::ProfileInfo {
+            name: name.into(),
+            active,
+            description: format!("{name} desc"),
+        }
+    }
+
+    #[test]
+    fn picker_initial_selection_prefers_active() {
+        let profiles = vec![
+            pinfo("default", false),
+            pinfo("night", true),
+            pinfo("speech", false),
+        ];
+        assert_eq!(initial_picker_selection(&profiles, "default"), 1);
+    }
+
+    #[test]
+    fn picker_initial_selection_falls_back_to_current_name_then_top() {
+        let profiles = vec![pinfo("default", false), pinfo("night", false)];
+        // no active flag: match the daemon's reported current name.
+        assert_eq!(initial_picker_selection(&profiles, "night"), 1);
+        // neither active nor a name match: default to the top.
+        assert_eq!(initial_picker_selection(&profiles, "ghost"), 0);
+    }
+
+    #[test]
+    fn picker_move_sel_wraps_both_ways() {
+        let mut p = ProfilePicker {
+            profiles: vec![pinfo("a", false), pinfo("b", false), pinfo("c", false)],
+            selected: 0,
+        };
+        p.move_sel(-1);
+        assert_eq!(p.selected, 2); // wrap up from top
+        p.move_sel(1);
+        assert_eq!(p.selected, 0); // wrap down from bottom
+        p.move_sel(2);
+        assert_eq!(p.selected, 2);
+    }
+
+    #[test]
+    fn fmt_uptime_buckets() {
+        assert_eq!(fmt_uptime(5), "5s");
+        assert_eq!(fmt_uptime(75), "1m15s");
+        assert_eq!(fmt_uptime(3725), "1h02m05s");
+    }
+}

Added file: crates/headroom-cli/src/tui/state_tests.rs+66 additions@@ -0,0 +1,66 @@
+use super::*;
+use headroom_ipc::{RouteList, Sinks, Status};
+
+fn stream(node_id: u32, app: &str, route: Route) -> StreamRoute {
+    StreamRoute {
+        node_id,
+        app: app.into(),
+        route,
+    }
+}
+
+fn state_from(status_streams: Vec<StreamRoute>, route_streams: Vec<StreamRoute>) -> UiState {
+    let status = Status {
+        version: "test".into(),
+        protocol: 1,
+        uptime_s: 0,
+        profile: "default".into(),
+        bypass: false,
+        per_app: false,
+        sinks: Sinks::default(),
+        streams: status_streams,
+        layer_a: vec![],
+        warnings: vec![],
+        setting_overrides: Default::default(),
+    };
+    let route_list = RouteList {
+        rules: vec![],
+        current: route_streams,
+        default_route: Route::Processed,
+    };
+    UiState::new(status, route_list)
+}
+
+#[test]
+fn snapshot_merge_prefers_route_list_and_fills_missing_status_streams() {
+    let state = state_from(
+        vec![
+            stream(1, "status-only", Route::Processed),
+            stream(2, "stale-status", Route::Processed),
+        ],
+        vec![stream(2, "route-list", Route::Bypass)],
+    );
+
+    assert_eq!(
+        state.streams.get(&1).map(|s| s.route),
+        Some(Route::Processed)
+    );
+    let got = state.streams.get(&2).expect("route list stream");
+    assert_eq!(got.app, "route-list");
+    assert_eq!(got.route, Route::Bypass);
+}
+
+#[test]
+fn profile_used_updates_active() {
+    let mut state = state_from(vec![], vec![]);
+    let ev = Event::new(
+        Topic::Profile,
+        "used",
+        &serde_json::json!({ "name": "movie" }),
+    )
+    .unwrap();
+
+    state.apply_event(ev);
+
+    assert_eq!(state.profile, "movie");
+}

Added file: crates/headroom-gui/Cargo.toml+51 additions@@ -0,0 +1,51 @@
+[package]
+name = "headroom-gui"
+version.workspace = true
+# optional, additive crate: pulls iced's gpu/system-lib stack (wgpu,
+# cosmic-text, winit), *not* part of the graphics-free daemon/cli build.
+# build from the nix dev shell or the `headroom-gui` nix package; both
+# supply iced's system libs.
+edition = "2021"
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+authors.workspace = true
+
+[[bin]]
+name = "headroom-gui"
+path = "src/main.rs"
+
+[dependencies]
+# internal — same control-plane client/types the ratatui tui uses.
+headroom-client = { workspace = true }
+headroom-ipc    = { workspace = true }
+
+# iced ui, trimmed feature set on purpose:
+#  - default-features off drops `linux-theme-detection` (pulls zbus +
+#    async-process + async-io just to probe the desktop theme — we
+#    hardcode dark), plus `web-colors` / `crisp` cosmetics.
+#  - `wgpu` + `tiny-skia` (software fallback) renderers, `wayland` only.
+#  - `smol` backs the `time::every` timer (no `tokio`); `thread-pool` is
+#    the subscription executor.
+# net: ~199 crates vs gpui-component's ~525 (no av1 encoder, no http stack).
+#
+# x11 off: add iced's `"x11"` feature here (and the x11 client libs back
+# to `guiLibs` in flake.nix) to build the x11 backend.
+iced = { version = "0.14", default-features = false, features = [
+    "wgpu",
+    "tiny-skia",
+    "wayland",
+    "thread-pool",
+    "smol",
+] }
+
+# bridge: reader thread → ui channel.
+crossbeam-channel = { workspace = true }
+
+# json event decoding (mirrors the tui's `apply_event`).
+serde_json = { workspace = true }
+
+# errors / logging.
+anyhow             = "1.0"
+tracing            = { workspace = true }
+tracing-subscriber = { workspace = true }

Added file: crates/headroom-gui/src/app.rs+1498 additions@@ -0,0 +1,1498 @@
+//! `HeadroomApp` — iced application state + view; mirrors the tui's
+//! read-only `UiState` (`crates/headroom-cli/src/tui.rs`).
+//!
+//! control ops never block the ui thread: sent over `cmd_tx` to the
+//! control thread (`io.rs`), which replies over the same `rx` the ui
+//! drains each tick. ui updates optimistically; daemon events + the
+//! ~1 Hz `per-app.list` refresh reconcile.
+
+use std::collections::BTreeMap;
+use std::time::{Duration, Instant};
+
+use crossbeam_channel::{Receiver, Sender};
+use iced::alignment::Horizontal;
+use iced::widget::{button, column, container, mouse_area, pick_list, progress_bar, row, scrollable, text};
+use iced::{keyboard, time, Alignment, Background, Border, Color, Element, Length, Subscription};
+
+use headroom_ipc::{
+    DaemonEvent, Event, LayerALevel, LayerASnapshot, MeterTick, ProfileInfo, Route, RoutingEvent,
+    StreamRoute, Topic,
+};
+
+use crate::io::{AppMsg, Bootstrap, ControlCmd, Snapshot};
+
+/// loudness at/below this floor renders as "--". mirrors
+/// `headroom_core::agc::LOUDNESS_FLOOR_LUFS`, inlined so the gui doesn't
+/// pull in the audio/dsp crate.
+const LOUDNESS_FLOOR_LUFS: f32 = -200.0;
+
+/// meters older than this are dimmed (source went silent / suspended).
+const STALE_AFTER: Duration = Duration::from_millis(500);
+
+/// ui drain + repaint interval (~20 Hz); also advances uptime/staleness
+/// text with no events flowing.
+const POLL_INTERVAL: Duration = Duration::from_millis(50);
+
+// palette — explicit colors mirroring the tui's intent.
+const BG: u32 = 0x1e1e1e;
+const PANEL_BG: u32 = 0x252526;
+const TRACK_BG: u32 = 0x3a3a3a;
+const FG: u32 = 0xd4d4d4;
+const DIM: u32 = 0x808080;
+const CYAN: u32 = 0x4ec9b0;
+const MAGENTA: u32 = 0xc586c0;
+const RED: u32 = 0xf44747;
+const GREEN: u32 = 0x6a9955;
+const YELLOW: u32 = 0xdcdcaa;
+const BLACK: u32 = 0x101010;
+/// tint behind the selected stream row.
+const SEL_BG: u32 = 0x094771;
+/// hover/press tint for header + row buttons.
+const HOVER_BG: u32 = 0x37373a;
+
+/// poll ticks between `per-app.list` refreshes — ~1 Hz at [`POLL_INTERVAL`].
+const REFRESH_EVERY_TICKS: u32 = 20;
+
+/// poll ticks between `profile.list` refreshes — ~10 s. the profile *set*
+/// only changes on `profile reload`; the active profile updates instantly
+/// via `profile.changed`.
+const REFRESH_PROFILES_EVERY_TICKS: u32 = 200;
+
+#[derive(Debug, Clone)]
+pub enum Message {
+    /// poll tick: drain `rx`, repaint, periodically refresh.
+    Tick,
+    /// a keypress / event we don't act on.
+    Noop,
+    /// select a stream row by node id (mouse click).
+    Select(u32),
+    /// move the selection up / down one row (k/↑, j/↓).
+    SelectUp,
+    SelectDown,
+    ToggleBypass,
+    TogglePerAppMaster,
+    /// toggle a stream's route (processed ↔ bypass).
+    ToggleRoute(u32),
+    /// toggle per-app management for a stream's app.
+    TogglePerApp(u32),
+    /// reset a stream's layer a deference.
+    ResetLayerA(u32),
+    /// hotkey variants acting on the current selection.
+    RouteSelected,
+    PerAppSelected,
+    ResetSelected,
+    /// switch to the named profile (pick_list).
+    ProfileSelected(String),
+    /// clear all overlay setting overrides.
+    ClearOverrides,
+}
+
+/// mirrored daemon snapshot plus the live event channel it drains.
+pub struct HeadroomApp {
+    daemon_version: String,
+    profile: String,
+    bypass: bool,
+    /// layer a master switch (per-app level control enabled globally).
+    per_app_master: bool,
+    /// overlay overrides (dotted key → value) shadowing the profile;
+    /// surfaced so a stale `headroom set` isn't invisible.
+    setting_overrides: BTreeMap<String, serde_json::Value>,
+    /// daemon uptime at connect, plus local elapsed.
+    base_uptime_s: u64,
+    connected_at: Instant,
+    default_route: Route,
+    streams: BTreeMap<u32, StreamRoute>,
+    /// per-stream layer a reduction (dB). presence = managed; inner `None`
+    /// until the first `layer_a_level`.
+    layer_a: BTreeMap<u32, Option<f32>>,
+    /// richer per-stream snapshots (managed/ceiling/deferred), polled from
+    /// `per-app.list`; drives the per-app toggle target + row label.
+    la_snapshots: BTreeMap<u32, LayerASnapshot>,
+    /// profiles for the switcher (seeded at connect).
+    profiles: Vec<ProfileInfo>,
+    /// selected stream node id; resolved via [`Self::effective_selection`].
+    selected: Option<u32>,
+    meters: Option<MeterTick>,
+    last_meter_at: Option<Instant>,
+    overflow_total: u64,
+    last_error: Option<String>,
+    disconnected: Option<String>,
+    /// live event + worker stream from the reader / control threads.
+    rx: Receiver<AppMsg>,
+    /// hands control ops to the control thread.
+    cmd_tx: Sender<ControlCmd>,
+    /// poll-tick counter for the paced `per-app.list` refresh.
+    tick_count: u32,
+}
+
+impl HeadroomApp {
+    /// seed initial state from the snapshot, take ownership of the channel.
+    pub fn new(boot: Bootstrap) -> Self {
+        let Bootstrap {
+            snapshot,
+            rx,
+            cmd_tx,
+        } = boot;
+
+        let mut app = Self {
+            daemon_version: String::new(),
+            profile: String::new(),
+            bypass: false,
+            per_app_master: false,
+            setting_overrides: BTreeMap::new(),
+            base_uptime_s: 0,
+            connected_at: Instant::now(),
+            default_route: Route::Processed,
+            streams: BTreeMap::new(),
+            layer_a: BTreeMap::new(),
+            la_snapshots: BTreeMap::new(),
+            profiles: Vec::new(),
+            selected: None,
+            meters: None,
+            last_meter_at: None,
+            overflow_total: 0,
+            last_error: None,
+            disconnected: None,
+            rx,
+            cmd_tx,
+            tick_count: 0,
+        };
+        app.apply_snapshot(snapshot);
+        // initial selection: first stream row (reconnects preserve the
+        // user's selection, so this only runs at startup).
+        app.selected = app.streams.keys().next().copied();
+        app
+    }
+
+    /// replace mirrored daemon state from a fresh [`Snapshot`]. shared by
+    /// [`Self::new`] + [`Self::reseed`]; leaves `selected` / channels /
+    /// tick counter to the caller.
+    fn apply_snapshot(&mut self, snapshot: Snapshot) {
+        let Snapshot {
+            status,
+            route_list,
+            profiles,
+        } = snapshot;
+
+        let mut streams = BTreeMap::new();
+        for s in route_list.current {
+            streams.insert(s.node_id, s);
+        }
+        // `status.streams` is a superset; merge any not already present.
+        for s in status.streams.iter() {
+            streams.entry(s.node_id).or_insert_with(|| s.clone());
+        }
+        // seed meter column + richer snapshots from status (mirrors tui).
+        let mut layer_a = BTreeMap::new();
+        let mut la_snapshots = BTreeMap::new();
+        for snap in status.layer_a {
+            layer_a.insert(snap.node_id, Some(snap.reduction_db));
+            la_snapshots.insert(snap.node_id, snap);
+        }
+
+        self.daemon_version = status.version;
+        self.profile = status.profile;
+        self.bypass = status.bypass;
+        self.per_app_master = status.per_app;
+        self.setting_overrides = status.setting_overrides;
+        self.base_uptime_s = status.uptime_s;
+        self.connected_at = Instant::now();
+        self.default_route = route_list.default_route;
+        self.streams = streams;
+        self.layer_a = layer_a;
+        self.la_snapshots = la_snapshots;
+        self.profiles = profiles;
+    }
+
+    /// re-seed after the reader reconnected to a (possibly new) daemon.
+    /// clears the disconnect/error banners + per-instance overflow counter
+    /// (a restarted daemon resets its drop count). `selected` is preserved —
+    /// `effective_selection` reconciles it against the new stream set.
+    fn reseed(&mut self, snapshot: Snapshot) {
+        self.apply_snapshot(snapshot);
+        self.overflow_total = 0;
+        self.last_error = None;
+        self.disconnected = None;
+        self.last_meter_at = None;
+    }
+
+    pub fn title(&self) -> String {
+        "headroom monitor".to_string()
+    }
+
+    /// poll tick (`smol` backs `time::every`) + global keyboard input.
+    /// `keyboard::listen` only surfaces keys not consumed by a focused
+    /// widget, so the pick_list keeps its own arrow/enter handling.
+    pub fn subscription(&self) -> Subscription<Message> {
+        Subscription::batch([
+            time::every(POLL_INTERVAL).map(|_| Message::Tick),
+            keyboard::listen().map(map_key),
+        ])
+    }
+
+    pub fn update(&mut self, message: Message) {
+        match message {
+            Message::Noop => {}
+            Message::Tick => {
+                self.pump();
+                self.tick_count = self.tick_count.wrapping_add(1);
+                if self.tick_count.is_multiple_of(REFRESH_EVERY_TICKS) {
+                    // reconcile managed/ceiling/deferred state the event
+                    // stream doesn't push (mirrors the tui's poll).
+                    self.send_cmd(ControlCmd::RefreshLayerA);
+                }
+                if self.tick_count.is_multiple_of(REFRESH_PROFILES_EVERY_TICKS) {
+                    // pick up profiles added/removed by `profile reload`.
+                    self.send_cmd(ControlCmd::RefreshProfiles);
+                }
+            }
+            Message::Select(id) => self.selected = Some(id),
+            Message::SelectUp => self.move_selection(-1),
+            Message::SelectDown => self.move_selection(1),
+            Message::ToggleBypass => {
+                let target = !self.bypass;
+                self.send_cmd(ControlCmd::SetBypass(target));
+                self.bypass = target; // optimistic; no bypass event from daemon
+            }
+            Message::TogglePerAppMaster => {
+                let target = !self.per_app_master;
+                self.send_cmd(ControlCmd::SetPerAppMaster(target));
+                self.per_app_master = target;
+            }
+            Message::ToggleRoute(id) => self.toggle_route(id),
+            Message::TogglePerApp(id) => self.toggle_per_app(id),
+            Message::ResetLayerA(id) => self.reset_layer_a(id),
+            Message::RouteSelected => {
+                if let Some(id) = self.effective_selection() {
+                    self.toggle_route(id);
+                }
+            }
+            Message::PerAppSelected => {
+                if let Some(id) = self.effective_selection() {
+                    self.toggle_per_app(id);
+                }
+            }
+            Message::ResetSelected => {
+                if let Some(id) = self.effective_selection() {
+                    self.reset_layer_a(id);
+                }
+            }
+            Message::ProfileSelected(name) => {
+                // optimistic: update the header now; the daemon's "used"
+                // event reconciles a frame or two later (mirrors the tui).
+                self.profile = name.clone();
+                self.send_cmd(ControlCmd::UseProfile(name));
+            }
+            Message::ClearOverrides => {
+                // optimistic: drop the indicator now; the daemon clears the
+                // overlay and reapplies the profile's values.
+                self.setting_overrides.clear();
+                self.send_cmd(ControlCmd::ClearOverrides);
+            }
+        }
+    }
+
+    /// drain + apply every queued worker message.
+    fn pump(&mut self) {
+        while let Ok(msg) = self.rx.try_recv() {
+            self.handle_msg(msg);
+        }
+    }
+
+    fn handle_msg(&mut self, msg: AppMsg) {
+        match msg {
+            AppMsg::Event(ev) => self.apply_event(ev),
+            AppMsg::Disconnected(reason) => self.disconnected = Some(reason),
+            AppMsg::Reconnected(snapshot) => self.reseed(*snapshot),
+            AppMsg::ControlError(e) => self.last_error = Some(e),
+            AppMsg::Profiles(p) => {
+                // reconcile the displayed profile from the `active` flag —
+                // covers external `profile use` even if "used" was missed.
+                if let Some(active) = p.iter().find(|x| x.active) {
+                    self.profile = active.name.clone();
+                }
+                self.profiles = p;
+            }
+            AppMsg::LayerASnapshots(list) => {
+                self.la_snapshots = list.into_iter().map(|s| (s.node_id, s)).collect();
+            }
+        }
+    }
+
+    /// queue a control op; a dead control thread lands in the footer.
+    fn send_cmd(&mut self, cmd: ControlCmd) {
+        if self.cmd_tx.send(cmd).is_err() {
+            self.last_error = Some("control thread gone".into());
+        }
+    }
+
+    /// stream node ids in row order (`BTreeMap` keys).
+    fn ordered_nodes(&self) -> Vec<u32> {
+        self.streams.keys().copied().collect()
+    }
+
+    /// `selected` when still live, else the first row, else `None`.
+    fn effective_selection(&self) -> Option<u32> {
+        match self.selected {
+            Some(id) if self.streams.contains_key(&id) => Some(id),
+            _ => self.streams.keys().next().copied(),
+        }
+    }
+
+    /// move the selection by `delta` rows (negative = up), wrapping.
+    fn move_selection(&mut self, delta: isize) {
+        let nodes = self.ordered_nodes();
+        if nodes.is_empty() {
+            self.selected = None;
+            return;
+        }
+        let cur = self
+            .effective_selection()
+            .and_then(|id| nodes.iter().position(|&n| n == id))
+            .unwrap_or(0) as isize;
+        let next = (cur + delta).rem_euclid(nodes.len() as isize) as usize;
+        self.selected = Some(nodes[next]);
+    }
+
+    /// flip a stream's route, optimistically updating local state.
+    ///
+    /// prefer a *persistent* per-app rule (`route.set`, keyed by app label)
+    /// so the route survives the app recreating its stream between tracks
+    /// (Strawberry, mpv, …); fall back to a one-shot `route.stream` only
+    /// when there's no label to key on. the optimistic update flips just
+    /// this row; the daemon's reevaluate emits `stream_routed` for sibling
+    /// streams of the same app, which `apply_event` reconciles.
+    fn toggle_route(&mut self, node: u32) {
+        let Some((app, cur)) = self.streams.get(&node).map(|s| (s.app.clone(), s.route)) else {
+            return;
+        };
+        let to = match cur {
+            Route::Processed => Route::Bypass,
+            Route::Bypass => Route::Processed,
+        };
+        if app.is_empty() {
+            self.send_cmd(ControlCmd::RouteStream { node_id: node, to });
+        } else {
+            self.send_cmd(ControlCmd::SetRoute { app, to });
+        }
+        if let Some(s) = self.streams.get_mut(&node) {
+            s.route = to;
+        }
+    }
+
+    /// toggle per-app management for a stream's app. guards an empty
+    /// label; reconciliation comes from the poll.
+    fn toggle_per_app(&mut self, node: u32) {
+        let Some(app) = self.streams.get(&node).map(|s| s.app.clone()) else {
+            return;
+        };
+        if app.is_empty() {
+            self.last_error = Some("per-app: selected stream has no app label".into());
+            return;
+        }
+        let managed = self.la_snapshots.get(&node).is_some_and(|s| s.managed);
+        self.send_cmd(ControlCmd::SetPerApp {
+            app,
+            enabled: !managed,
+        });
+    }
+
+    /// reset a stream's layer a deference.
+    fn reset_layer_a(&mut self, node: u32) {
+        self.send_cmd(ControlCmd::ResetLayerA { node_id: node });
+    }
+
+    fn uptime_s(&self) -> u64 {
+        self.base_uptime_s
+            .saturating_add(self.connected_at.elapsed().as_secs())
+    }
+
+    fn meters_stale(&self) -> bool {
+        self.last_meter_at
+            .map(|t| t.elapsed() > STALE_AFTER)
+            .unwrap_or(true)
+    }
+
+    /// apply one wire event. ported from the tui's `apply_event`, minus
+    /// the selection/snapshot bookkeeping the read-only gui doesn't need.
+    fn apply_event(&mut self, ev: Event) {
+        match ev.topic {
+            Topic::Meters if ev.event == "tick" => {
+                if let Ok(m) = serde_json::from_value::<MeterTick>(ev.data) {
+                    self.meters = Some(m);
+                    self.last_meter_at = Some(Instant::now());
+                }
+            }
+            Topic::Meters if ev.event == "layer_a_level" => {
+                if let Ok(l) = serde_json::from_value::<LayerALevel>(ev.data) {
+                    self.layer_a.insert(l.node_id, Some(l.reduction_db));
+                }
+            }
+            Topic::Routing => {
+                if let Ok(re) = serde_json::from_value::<RoutingEvent>(inject_event(&ev)) {
+                    match re {
+                        RoutingEvent::StreamRouted { node_id, app, to } => {
+                            self.streams.insert(
+                                node_id,
+                                StreamRoute {
+                                    node_id,
+                                    app,
+                                    route: to,
+                                },
+                            );
+                        }
+                        RoutingEvent::StreamRemoved { node_id } => {
+                            self.streams.remove(&node_id);
+                            self.layer_a.remove(&node_id);
+                            self.la_snapshots.remove(&node_id);
+                        }
+                        RoutingEvent::LayerAAttached { node_id, .. } => {
+                            self.layer_a.entry(node_id).or_insert(None);
+                        }
+                        RoutingEvent::LayerADetached { node_id } => {
+                            self.layer_a.remove(&node_id);
+                            self.la_snapshots.remove(&node_id);
+                        }
+                        RoutingEvent::RuleChanged => {}
+                        _ => {}
+                    }
+                }
+            }
+            Topic::Profile => {
+                // the daemon emits `profile` "used" `{name}` on apply (not
+                // the typed `ProfileEvent::Changed` "changed"/`previous`
+                // shape), so read `name` directly and accept either spelling
+                // — keeps the header in sync with a cli `profile use` too.
+                // on "reloaded" the profile *set* may have changed.
+                match ev.event.as_str() {
+                    "used" | "changed" => {
+                        if let Some(name) = ev.data.get("name").and_then(|v| v.as_str()) {
+                            self.profile = name.to_string();
+                        }
+                    }
+                    "reloaded" => self.send_cmd(ControlCmd::RefreshProfiles),
+                    _ => {}
+                }
+            }
+            Topic::Daemon => {
+                if let Ok(de) = serde_json::from_value::<DaemonEvent>(inject_event(&ev)) {
+                    match de {
+                        DaemonEvent::Overflow {
+                            lost, total_lost, ..
+                        } => {
+                            self.overflow_total = total_lost.max(self.overflow_total + lost as u64);
+                        }
+                        DaemonEvent::Error { code, message } => {
+                            self.last_error = Some(format!("{code}: {message}"));
+                        }
+                        DaemonEvent::Shutdown => {
+                            self.disconnected = Some("daemon shutdown".into());
+                        }
+                        DaemonEvent::Started { version } => {
+                            self.daemon_version = version;
+                        }
+                        _ => {}
+                    }
+                }
+            }
+            _ => {}
+        }
+    }
+
+    // -----------------------------------------------------------------
+    // View
+    // -----------------------------------------------------------------
+
+    pub fn view(&self) -> Element<'_, Message> {
+        let content = column![
+            self.header(),
+            self.bus_panel(),
+            self.loudness_panel(),
+            self.streams_panel(),
+            self.footer(),
+        ]
+        .spacing(8)
+        .padding(12)
+        .width(Length::Fill)
+        .height(Length::Fill);
+
+        // paint the window with the base background.
+        container(content)
+            .width(Length::Fill)
+            .height(Length::Fill)
+            .style(|_theme: &iced::Theme| container::Style {
+                background: Some(Background::Color(col(BG))),
+                ..container::Style::default()
+            })
+            .into()
+    }
+
+    fn header(&self) -> Element<'static, Message> {
+        let bypass = if self.bypass {
+            badge_button("BYPASS", BLACK, YELLOW, Message::ToggleBypass)
+        } else {
+            badge_button("processed", GREEN, PANEL_BG, Message::ToggleBypass)
+        };
+        // state semantics (not action): label = current state, click
+        // toggles — same convention as the per-app row chip.
+        let per_app = if self.per_app_master {
+            badge_button("per-app on", CYAN, PANEL_BG, Message::TogglePerAppMaster)
+        } else {
+            badge_button("per-app off", DIM, PANEL_BG, Message::TogglePerAppMaster)
+        };
+
+        // profile switcher: dropdown over the profile names.
+        let names: Vec<String> = self.profiles.iter().map(|p| p.name.clone()).collect();
+        let picker = pick_list(names, Some(self.profile.clone()), Message::ProfileSelected)
+            .text_size(14)
+            .padding(iced::Padding::from([2.0, 8.0]));
+
+        // left group fills the width so version/uptime is pushed right.
+        let mut left = row![
+            text("profile:").color(col(DIM)),
+            picker,
+            bypass,
+            per_app,
+        ]
+        .spacing(8)
+        .align_y(Alignment::Center);
+
+        // flag overlay overrides shadowing the profile — a stale
+        // `headroom set` is otherwise invisible (e.g. agc.enabled pinned
+        // off under a profile that enables it). click the pill to clear.
+        if !self.setting_overrides.is_empty() {
+            left = left.push(pill_button(
+                format!("overrides: {}  ✕", fmt_overrides(&self.setting_overrides)),
+                BLACK,
+                YELLOW,
+                Message::ClearOverrides,
+            ));
+        }
+
+        let right = row![
+            text(format!("v{}", self.daemon_version))
+                .size(13)
+                .color(col(DIM)),
+            text(format!("uptime {}", fmt_uptime(self.uptime_s())))
+                .size(13)
+                .color(col(DIM)),
+        ]
+        .spacing(8)
+        .align_y(Alignment::Center);
+
+        row![container(left).width(Length::Fill), right]
+            .align_y(Alignment::Center)
+            .into()
+    }
+
+    fn bus_panel(&self) -> Element<'static, Message> {
+        let m = self.meters;
+        // per-stage enable flags from the tick (missing ⇒ assume enabled).
+        // agc + compressor are per-profile; limiter is the always-on
+        // backstop and true peak is a measurement, so both are always on.
+        let agc_on = m.map(|t| t.agc_enabled).unwrap_or(true);
+        let comp_on = m.map(|t| t.compressor_enabled).unwrap_or(true);
+        let body = column![
+            meter_row(
+                "AGC target",
+                m.map(|t| t.agc_gain_db),
+                -12.0,
+                12.0,
+                "dB",
+                CYAN,
+                agc_on,
+            ),
+            meter_row(
+                "Compressor GR",
+                m.map(|t| t.compressor_gr_db),
+                -24.0,
+                0.0,
+                "dB",
+                MAGENTA,
+                comp_on,
+            ),
+            meter_row(
+                "Limiter GR",
+                m.map(|t| t.limiter_gr_db),
+                -24.0,
+                0.0,
+                "dB",
+                RED,
+                true,
+            ),
+            meter_row(
+                "True peak",
+                m.map(|t| t.true_peak_dbtp),
+                -60.0,
+                3.0,
+                "dBTP",
+                GREEN,
+                true,
+            ),
+        ]
+        .spacing(4);
+        panel("bus dsp", body.into())
+    }
+
+    fn loudness_panel(&self) -> Element<'static, Message> {
+        let stale = self.meters_stale();
+        let (mom, st, intg) = match self.meters {
+            Some(m) => (
+                Some(m.momentary_lufs),
+                Some(m.shortterm_lufs),
+                Some(m.integrated_lufs),
+            ),
+            None => (None, None, None),
+        };
+        let body = column![
+            lufs_row("Momentary  (400 ms)", mom, stale),
+            lufs_row("Short-term (3 s)", st, stale),
+            lufs_row("Integrated (gated)", intg, stale),
+        ]
+        .spacing(4);
+        panel("loudness (BS.1770)", body.into())
+    }
+
+    fn streams_panel(&self) -> Element<'static, Message> {
+        let header = row![
+            container(text("node").size(12).color(col(DIM))).width(Length::Fixed(64.0)),
+            container(text("app").size(12).color(col(DIM))).width(Length::Fill),
+            container(text("route").size(12).color(col(DIM))).width(Length::Fixed(96.0)),
+            container(text("per-app").size(12).color(col(DIM))).width(Length::Fixed(96.0)),
+            container(text("actions").size(12).color(col(DIM))).width(Length::Fixed(180.0)),
+        ]
+        .spacing(8);
+
+        let selected = self.effective_selection();
+        let rows = self.streams.values().map(|s| {
+            stream_row(
+                s,
+                &self.layer_a,
+                &self.la_snapshots,
+                selected == Some(s.node_id),
+            )
+        });
+        let list = scrollable(column(rows).spacing(4).width(Length::Fill)).height(Length::Fill);
+
+        let title = format!(
+            "streams ({}) — default: {}",
+            self.streams.len(),
+            self.default_route
+        );
+
+        container(
+            column![text(title).size(12).color(col(DIM)), header, list]
+                .spacing(4)
+                .height(Length::Fill),
+        )
+        .padding(8)
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .style(panel_style)
+        .into()
+    }
+
+    fn footer(&self) -> Element<'static, Message> {
+        let mut items: Vec<Element<'static, Message>> = Vec::new();
+        if self.overflow_total > 0 {
+            items.push(
+                text(format!("dropped: {}", self.overflow_total))
+                    .size(12)
+                    .color(col(YELLOW))
+                    .into(),
+            );
+        }
+        if let Some(err) = &self.last_error {
+            items.push(
+                text(format!("daemon error: {err}"))
+                    .size(12)
+                    .color(col(RED))
+                    .into(),
+            );
+        }
+        if let Some(reason) = &self.disconnected {
+            items.push(
+                text(format!("disconnected: {reason}"))
+                    .size(12)
+                    .color(col(RED))
+                    .into(),
+            );
+        } else if self.overflow_total == 0 && self.last_error.is_none() {
+            items.push(text("connected").size(12).color(col(DIM)).into());
+        }
+        row(items).spacing(12).into()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Free helpers
+// ---------------------------------------------------------------------------
+
+/// `0xRRGGBB` → iced [`Color`].
+fn col(hex: u32) -> Color {
+    Color::from_rgb8((hex >> 16) as u8, (hex >> 8) as u8, hex as u8)
+}
+
+/// `radius`-rounded border, no stroke.
+fn rounded(radius: f32) -> Border {
+    Border {
+        radius: radius.into(),
+        ..Border::default()
+    }
+}
+
+/// shared panel container style: dark fill, rounded corners.
+fn panel_style(_theme: &iced::Theme) -> container::Style {
+    container::Style {
+        background: Some(Background::Color(col(PANEL_BG))),
+        border: rounded(6.0),
+        ..container::Style::default()
+    }
+}
+
+/// a titled panel: header label + body, on a rounded dark card.
+fn panel(title: &'static str, body: Element<'static, Message>) -> Element<'static, Message> {
+    container(
+        column![text(title).size(12).color(col(DIM)), body]
+            .spacing(4)
+            .width(Length::Fill),
+    )
+    .padding(8)
+    .width(Length::Fill)
+    .style(panel_style)
+    .into()
+}
+
+/// like [`badge_button`] but owns its text, for runtime-built labels.
+fn pill_button(label: String, fg: u32, bg: u32, msg: Message) -> Element<'static, Message> {
+    button(text(label).size(12).color(col(fg)))
+        .padding(iced::Padding::from([2.0, 8.0]))
+        .on_press(msg)
+        .style(pill_style(fg, bg))
+        .into()
+}
+
+/// active overrides as `key=value, …` (strings unquoted, else json) for
+/// the header indicator.
+fn fmt_overrides(map: &BTreeMap<String, serde_json::Value>) -> String {
+    map.iter()
+        .map(|(k, v)| {
+            let val = match v {
+                serde_json::Value::String(s) => s.clone(),
+                other => other.to_string(),
+            };
+            format!("{k}={val}")
+        })
+        .collect::<Vec<_>>()
+        .join(", ")
+}
+
+/// a small colored pill that's also a button.
+fn badge_button(
+    label: &'static str,
+    fg: u32,
+    bg: u32,
+    msg: Message,
+) -> Element<'static, Message> {
+    button(text(label).size(12).color(col(fg)))
+        .padding(iced::Padding::from([2.0, 8.0]))
+        .on_press(msg)
+        .style(pill_style(fg, bg))
+        .into()
+}
+
+/// button style closure: flat `bg` pill, `fg` text, lightening on
+/// hover/press.
+fn pill_style(fg: u32, bg: u32) -> impl Fn(&iced::Theme, button::Status) -> button::Style {
+    move |_theme, status| {
+        let background = match status {
+            button::Status::Hovered | button::Status::Pressed => col(HOVER_BG),
+            _ => col(bg),
+        };
+        button::Style {
+            background: Some(Background::Color(background)),
+            text_color: col(fg),
+            border: rounded(4.0),
+            ..button::Style::default()
+        }
+    }
+}
+
+/// one bus meter row: `LABEL   VALUE   [====----]   min..max`. when
+/// `!enabled` the stage is bypassed, so render "disabled" + a greyed bar
+/// — a disabled stage must not look like one reading 0.
+fn meter_row(
+    label: &'static str,
+    value: Option<f32>,
+    min: f32,
+    max: f32,
+    unit: &'static str,
+    color: u32,
+    enabled: bool,
+) -> Element<'static, Message> {
+    // normalize into 0..100 for `progress_bar`, clamped. disabled ⇒ empty.
+    let pct = match value {
+        Some(v) if enabled => ((v.clamp(min, max) - min) / (max - min)).clamp(0.0, 1.0) * 100.0,
+        _ => 0.0,
+    };
+    let bar_color = if enabled { color } else { DIM };
+    let value_str = if !enabled {
+        "disabled".to_string()
+    } else {
+        value
+            .map(|v| format!("{v:+7.2} {unit}"))
+            .unwrap_or_else(|| "    --".to_string())
+    };
+    let value_color = if enabled { FG } else { DIM };
+
+    row![
+        container(text(label).color(col(DIM))).width(Length::Fixed(130.0)),
+        container(text(value_str).color(col(value_color)))
+            .width(Length::Fixed(96.0))
+            .align_x(Horizontal::Right),
+        progress_bar(0.0..=100.0, pct)
+            .length(Length::Fill)
+            .girth(Length::Fixed(10.0))
+            .style(move |_theme: &iced::Theme| progress_bar::Style {
+                background: Background::Color(col(TRACK_BG)),
+                bar: Background::Color(col(bar_color)),
+                border: rounded(3.0),
+            }),
+        container(text(format!("{min:.0}..{max:.0}")).size(11).color(col(DIM)))
+            .width(Length::Fixed(90.0))
+            .align_x(Horizontal::Right),
+    ]
+    .spacing(8)
+    .align_y(Alignment::Center)
+    .into()
+}
+
+/// one BS.1770 loudness row.
+fn lufs_row(label: &'static str, v: Option<f32>, stale: bool) -> Element<'static, Message> {
+    let val = match v {
+        Some(x) if x > LOUDNESS_FLOOR_LUFS + 0.5 => format!("{x:+7.2} LUFS"),
+        _ => "    -- LUFS".to_string(),
+    };
+    row![
+        container(text(label).color(col(DIM))).width(Length::Fixed(200.0)),
+        text(val).color(col(if stale { DIM } else { FG })),
+    ]
+    .spacing(8)
+    .into()
+}
+
+/// one stream routing row: status cells + route/per-app/reset actions,
+/// wrapped in a `mouse_area` so clicking the row selects it. owns its
+/// text, so it's `'static`.
+fn stream_row(
+    s: &StreamRoute,
+    layer_a: &BTreeMap<u32, Option<f32>>,
+    la_snapshots: &BTreeMap<u32, LayerASnapshot>,
+    selected: bool,
+) -> Element<'static, Message> {
+    let node = s.node_id;
+    let (route_text, route_color) = match s.route {
+        Route::Processed => ("processed", GREEN),
+        Route::Bypass => ("bypass", YELLOW),
+    };
+    let (la_text, la_color) = match layer_a.get(&node) {
+        Some(Some(db)) => (format!("{db:+5.1} dB"), MAGENTA),
+        Some(None) => ("attached".to_string(), DIM),
+        None => ("—".to_string(), DIM),
+    };
+
+    // route button: always available, flips processed ↔ bypass.
+    let (route_btn_label, route_btn_to) = match s.route {
+        Route::Processed => ("→ bypass", BLACK),
+        Route::Bypass => ("→ processed", BLACK),
+    };
+    let route_btn = action_button(route_btn_label, route_btn_to, CYAN, Message::ToggleRoute(node));
+
+    // per-app + reset need an app label; omit them otherwise so the row
+    // can't fire a no-op control op.
+    let actions: Element<'static, Message> = if s.app.is_empty() {
+        route_btn
+    } else {
+        // state semantics (like the master badge): label = whether managed,
+        // click toggles.
+        let managed = la_snapshots.get(&node).is_some_and(|snap| snap.managed);
+        let (pa_label, pa_bg) = if managed {
+            ("per-app on", CYAN)
+        } else {
+            ("per-app off", DIM)
+        };
+        let per_app_btn = action_button(pa_label, BLACK, pa_bg, Message::TogglePerApp(node));
+        let reset_btn = action_button("reset", FG, TRACK_BG, Message::ResetLayerA(node));
+        row![route_btn, per_app_btn, reset_btn].spacing(4).into()
+    };
+
+    let body = row![
+        container(text(node.to_string()).color(col(DIM))).width(Length::Fixed(64.0)),
+        container(text(s.app.clone())).width(Length::Fill),
+        container(text(route_text).color(col(route_color))).width(Length::Fixed(96.0)),
+        container(text(la_text).color(col(la_color))).width(Length::Fixed(96.0)),
+        container(actions).width(Length::Fixed(180.0)),
+    ]
+    .spacing(8)
+    .align_y(Alignment::Center);
+
+    // tint the selected row; wrap it so a click anywhere selects it
+    // (buttons still take their own clicks first).
+    let tinted = container(body).padding(iced::Padding::from([2.0, 4.0])).style(
+        move |_theme: &iced::Theme| container::Style {
+            background: selected.then(|| Background::Color(col(SEL_BG))),
+            border: rounded(4.0),
+            ..container::Style::default()
+        },
+    );
+    mouse_area(tinted).on_press(Message::Select(node)).into()
+}
+
+/// compact row-action button: `bg` pill, `fg` text, lightening on
+/// hover/press.
+fn action_button(
+    label: &'static str,
+    fg: u32,
+    bg: u32,
+    msg: Message,
+) -> Element<'static, Message> {
+    button(text(label).size(11).color(col(fg)))
+        .padding(iced::Padding::from([1.0, 6.0]))
+        .on_press(msg)
+        .style(pill_style(fg, bg))
+        .into()
+}
+
+/// the wire frame carries `{event, topic, data}` but the typed enums are
+/// `#[serde(tag = "event")]` inside `data`, so re-inject the event name
+/// before deserializing. same dance as the tui.
+fn inject_event(ev: &Event) -> serde_json::Value {
+    let mut obj = match &ev.data {
+        serde_json::Value::Object(m) => m.clone(),
+        _ => serde_json::Map::new(),
+    };
+    obj.insert("event".into(), serde_json::Value::String(ev.event.clone()));
+    serde_json::Value::Object(obj)
+}
+
+/// `12345` seconds → `3h25m45s` / `25m45s` / `45s`.
+fn fmt_uptime(s: u64) -> String {
+    let h = s / 3600;
+    let m = (s % 3600) / 60;
+    let sec = s % 60;
+    if h > 0 {
+        format!("{h}h{m:02}m{sec:02}s")
+    } else if m > 0 {
+        format!("{m}m{sec:02}s")
+    } else {
+        format!("{sec}s")
+    }
+}
+
+/// map a keyboard event to a [`Message`], mirroring the tui's
+/// `handle_key`. unhandled keys / non-press events become
+/// [`Message::Noop`]; selection-targeted messages no-op in `update` when
+/// nothing is selected.
+fn map_key(event: keyboard::Event) -> Message {
+    use keyboard::key::Named;
+    let keyboard::Event::KeyPressed { key, .. } = event else {
+        return Message::Noop;
+    };
+    match key {
+        keyboard::Key::Character(c) => match c.as_str() {
+            "b" => Message::ToggleBypass,
+            "p" => Message::TogglePerAppMaster,
+            "r" => Message::RouteSelected,
+            "a" => Message::PerAppSelected,
+            "x" => Message::ResetSelected,
+            "j" => Message::SelectDown,
+            "k" => Message::SelectUp,
+            _ => Message::Noop,
+        },
+        keyboard::Key::Named(Named::Enter) => Message::RouteSelected,
+        keyboard::Key::Named(Named::ArrowDown) => Message::SelectDown,
+        keyboard::Key::Named(Named::ArrowUp) => Message::SelectUp,
+        _ => Message::Noop,
+    }
+}
+
+#[cfg(test)]
+mod state_tests;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crossbeam_channel::{unbounded, Receiver};
+    use headroom_ipc::{RouteList, Sinks, Status};
+
+    /// build an app over the given streams + layer a snapshots, keeping
+    /// the control receiver alive so toggle tests can drain it.
+    fn build(
+        streams: Vec<StreamRoute>,
+        layer_a: Vec<LayerASnapshot>,
+    ) -> (HeadroomApp, Receiver<ControlCmd>) {
+        let status = Status {
+            version: "test".into(),
+            protocol: 1,
+            uptime_s: 0,
+            profile: "default".into(),
+            bypass: false,
+            per_app: false,
+            sinks: Sinks::default(),
+            streams,
+            layer_a,
+            warnings: vec![],
+            setting_overrides: Default::default(),
+        };
+        let route_list = RouteList {
+            rules: vec![],
+            current: vec![],
+            default_route: Route::Processed,
+        };
+        let (_tx, rx) = unbounded();
+        let (cmd_tx, cmd_rx) = unbounded();
+        let app = HeadroomApp::new(Bootstrap {
+            snapshot: Snapshot {
+                status,
+                route_list,
+                profiles: vec![],
+            },
+            rx,
+            cmd_tx,
+        });
+        (app, cmd_rx)
+    }
+
+    /// build a `status` snapshot for reconnect tests.
+    fn status_with(profile: &str, streams: Vec<StreamRoute>) -> Status {
+        Status {
+            version: "test".into(),
+            protocol: 1,
+            uptime_s: 0,
+            profile: profile.into(),
+            bypass: false,
+            per_app: false,
+            sinks: Sinks::default(),
+            streams,
+            layer_a: vec![],
+            warnings: vec![],
+            setting_overrides: Default::default(),
+        }
+    }
+
+    fn app() -> HeadroomApp {
+        build(vec![], vec![]).0
+    }
+
+    fn stream(node_id: u32, app: &str, route: Route) -> StreamRoute {
+        StreamRoute {
+            node_id,
+            app: app.into(),
+            route,
+        }
+    }
+
+    fn snap(node_id: u32, app: &str, managed: bool) -> LayerASnapshot {
+        LayerASnapshot {
+            node_id,
+            app: app.into(),
+            managed,
+            volume_lin: 1.0,
+            reduction_db: 0.0,
+            user_ceiling_lin: None,
+            deferred: false,
+        }
+    }
+
+    #[test]
+    fn meter_tick_event_updates_state() {
+        let mut s = app();
+        let tick = MeterTick {
+            momentary_lufs: -19.3,
+            shortterm_lufs: -20.1,
+            integrated_lufs: -19.8,
+            true_peak_dbtp: -1.4,
+            gain_reduction_db: -2.1,
+            compressor_gr_db: -0.8,
+            limiter_gr_db: -1.3,
+            agc_gain_db: 0.5,
+            agc_enabled: true,
+            compressor_enabled: true,
+        };
+        s.apply_event(Event::new(Topic::Meters, "tick", &tick).unwrap());
+        assert!(s.meters.is_some());
+        assert!(s.last_meter_at.is_some());
+        assert!(!s.meters_stale());
+    }
+
+    #[test]
+    fn routing_event_inserts_then_removes_stream() {
+        let mut s = app();
+        s.apply_event(
+            Event::new(
+                Topic::Routing,
+                "stream_routed",
+                &serde_json::json!({ "node_id": 42, "app": "firefox", "to": "bypass" }),
+            )
+            .unwrap(),
+        );
+        let st = s.streams.get(&42).expect("tracked");
+        assert_eq!(st.app, "firefox");
+        assert_eq!(st.route, Route::Bypass);
+        s.layer_a.insert(42, Some(-3.0));
+        s.la_snapshots.insert(42, snap(42, "firefox", true));
+
+        s.apply_event(
+            Event::new(
+                Topic::Routing,
+                "stream_removed",
+                &serde_json::json!({ "node_id": 42 }),
+            )
+            .unwrap(),
+        );
+        assert!(!s.streams.contains_key(&42));
+        assert!(!s.layer_a.contains_key(&42));
+        assert!(!s.la_snapshots.contains_key(&42));
+    }
+
+    #[test]
+    fn layer_a_level_updates_reduction() {
+        let mut s = app();
+        s.apply_event(
+            Event::new(
+                Topic::Routing,
+                "layer_a_attached",
+                &serde_json::json!({ "node_id": 11, "app": "loud" }),
+            )
+            .unwrap(),
+        );
+        assert_eq!(s.layer_a.get(&11), Some(&None));
+        s.apply_event(
+            Event::new(
+                Topic::Meters,
+                "layer_a_level",
+                &serde_json::json!({
+                    "node_id": 11, "app": "loud",
+                    "volume_lin": 0.25_f32, "reduction_db": -11.8_f32,
+                }),
+            )
+            .unwrap(),
+        );
+        let r = s.layer_a.get(&11).copied().flatten().unwrap();
+        assert!((r - -11.8).abs() < 1e-4);
+    }
+
+    #[test]
+    fn profile_changed_updates_active() {
+        let mut s = app();
+        s.apply_event(
+            Event::new(
+                Topic::Profile,
+                "changed",
+                &serde_json::json!({ "name": "night", "previous": "default" }),
+            )
+            .unwrap(),
+        );
+        assert_eq!(s.profile, "night");
+    }
+
+    #[test]
+    fn profile_used_event_updates_active() {
+        // the shape the daemon actually emits on `profile.use`.
+        let mut s = app();
+        s.apply_event(
+            Event::new(Topic::Profile, "used", &serde_json::json!({ "name": "movie" })).unwrap(),
+        );
+        assert_eq!(s.profile, "movie");
+    }
+
+    #[test]
+    fn profile_selected_updates_header_optimistically() {
+        let (mut s, _cmd) = build(vec![], vec![]);
+        assert_eq!(s.profile, "default");
+        s.update(Message::ProfileSelected("party".into()));
+        assert_eq!(s.profile, "party");
+    }
+
+    #[test]
+    fn profiles_refresh_syncs_active_profile() {
+        let (mut s, _tx) = build(vec![], vec![]);
+        s.handle_msg(AppMsg::Profiles(vec![
+            ProfileInfo {
+                name: "default".into(),
+                active: false,
+                description: String::new(),
+            },
+            ProfileInfo {
+                name: "gaming".into(),
+                active: true,
+                description: String::new(),
+            },
+        ]));
+        assert_eq!(s.profile, "gaming");
+        assert_eq!(s.profiles.len(), 2);
+    }
+
+    #[test]
+    fn reconnect_reseeds_state_and_clears_disconnect() {
+        // start with one stream, then simulate the daemon dropping and a
+        // *new* instance coming back with a different stream set + active
+        // profile (node ids change across a restart).
+        let (mut s, _cmd) = build(vec![stream(42, "firefox", Route::Bypass)], vec![]);
+        s.handle_msg(AppMsg::Disconnected("daemon shutdown".into()));
+        s.overflow_total = 7;
+        s.last_error = Some("stale".into());
+        assert!(s.disconnected.is_some());
+
+        s.handle_msg(AppMsg::Reconnected(Box::new(Snapshot {
+            status: status_with("music", vec![stream(99, "mpv", Route::Processed)]),
+            route_list: RouteList {
+                rules: vec![],
+                current: vec![stream(99, "mpv", Route::Processed)],
+                default_route: Route::Processed,
+            },
+            profiles: vec![ProfileInfo {
+                name: "music".into(),
+                active: true,
+                description: String::new(),
+            }],
+        })));
+
+        // banners cleared, per-instance counter reset.
+        assert!(s.disconnected.is_none());
+        assert!(s.last_error.is_none());
+        assert_eq!(s.overflow_total, 0);
+        // mirrored state replaced with the new daemon's snapshot.
+        assert_eq!(s.profile, "music");
+        assert!(!s.streams.contains_key(&42));
+        assert_eq!(s.streams.get(&99).map(|r| r.route), Some(Route::Processed));
+        assert_eq!(s.profiles.len(), 1);
+    }
+
+    #[test]
+    fn daemon_overflow_accumulates() {
+        let mut s = app();
+        s.apply_event(
+            Event::new(
+                Topic::Daemon,
+                "overflow",
+                &serde_json::json!({ "lost_topic": "meters", "lost": 3u32, "total_lost": 5u64 }),
+            )
+            .unwrap(),
+        );
+        assert_eq!(s.overflow_total, 5);
+    }
+
+    #[test]
+    fn fmt_uptime_buckets() {
+        assert_eq!(fmt_uptime(5), "5s");
+        assert_eq!(fmt_uptime(75), "1m15s");
+        assert_eq!(fmt_uptime(3725), "1h02m05s");
+    }
+
+    // -- selection -------------------------------------------------------
+
+    #[test]
+    fn selection_moves_in_key_order_and_wraps() {
+        let (mut s, _cmd) = build(
+            vec![
+                stream(30, "c", Route::Processed),
+                stream(10, "a", Route::Processed),
+                stream(20, "b", Route::Processed),
+            ],
+            vec![],
+        );
+        // seeded selection is the first key (BTreeMap order: 10).
+        assert_eq!(s.effective_selection(), Some(10));
+        s.update(Message::SelectDown);
+        assert_eq!(s.selected, Some(20));
+        s.update(Message::SelectDown);
+        assert_eq!(s.selected, Some(30));
+        s.update(Message::SelectDown);
+        assert_eq!(s.selected, Some(10)); // wrap to top
+        s.update(Message::SelectUp);
+        assert_eq!(s.selected, Some(30)); // wrap to bottom
+    }
+
+    #[test]
+    fn selection_empty_is_none() {
+        let (mut s, _cmd) = build(vec![], vec![]);
+        s.update(Message::SelectDown);
+        assert_eq!(s.selected, None);
+        assert_eq!(s.effective_selection(), None);
+    }
+
+    // -- control commands emitted by toggles -----------------------------
+
+    fn drain(cmd: &Receiver<ControlCmd>) -> ControlCmd {
+        cmd.try_recv().expect("a command was emitted")
+    }
+
+    #[test]
+    fn toggle_bypass_emits_and_updates_optimistically() {
+        let (mut s, cmd) = build(vec![], vec![]);
+        assert!(!s.bypass);
+        s.update(Message::ToggleBypass);
+        assert!(matches!(drain(&cmd), ControlCmd::SetBypass(true)));
+        assert!(s.bypass); // optimistic
+        s.update(Message::ToggleBypass);
+        assert!(matches!(drain(&cmd), ControlCmd::SetBypass(false)));
+        assert!(!s.bypass);
+    }
+
+    #[test]
+    fn toggle_per_app_master_emits_and_updates() {
+        let (mut s, cmd) = build(vec![], vec![]);
+        s.update(Message::TogglePerAppMaster);
+        assert!(matches!(drain(&cmd), ControlCmd::SetPerAppMaster(true)));
+        assert!(s.per_app_master);
+    }
+
+    #[test]
+    fn toggle_route_sets_persistent_per_app_rule_and_flips_optimistically() {
+        // a labelled stream toggles via a persistent per-app rule
+        // (route.set), not a one-shot per-stream reroute — so it
+        // survives the app recreating its stream between tracks.
+        let (mut s, cmd) = build(vec![stream(42, "firefox", Route::Processed)], vec![]);
+        s.update(Message::ToggleRoute(42));
+        match drain(&cmd) {
+            ControlCmd::SetRoute { app, to } => {
+                assert_eq!(app, "firefox");
+                assert_eq!(to, Route::Bypass);
+            }
+            _ => panic!("expected SetRoute"),
+        }
+        assert_eq!(s.streams.get(&42).unwrap().route, Route::Bypass); // optimistic
+    }
+
+    #[test]
+    fn toggle_route_empty_label_falls_back_to_per_stream() {
+        // a stream with no app label can't key a per-app rule, so it
+        // falls back to the one-shot per-stream reroute.
+        let (mut s, cmd) = build(vec![stream(5, "", Route::Processed)], vec![]);
+        s.update(Message::ToggleRoute(5));
+        match drain(&cmd) {
+            ControlCmd::RouteStream { node_id, to } => {
+                assert_eq!(node_id, 5);
+                assert_eq!(to, Route::Bypass);
+            }
+            _ => panic!("expected RouteStream fallback"),
+        }
+    }
+
+    #[test]
+    fn route_selected_acts_on_selection() {
+        let (mut s, cmd) = build(vec![stream(7, "mpv", Route::Bypass)], vec![]);
+        s.update(Message::RouteSelected);
+        match drain(&cmd) {
+            ControlCmd::SetRoute { app, to } => {
+                assert_eq!(app, "mpv");
+                assert_eq!(to, Route::Processed);
+            }
+            _ => panic!("expected SetRoute"),
+        }
+    }
+
+    #[test]
+    fn toggle_per_app_targets_inverse_of_managed() {
+        // node 1 managed → toggling asks to disable; node 2 unmanaged →
+        // toggling asks to enable.
+        let (mut s, cmd) = build(
+            vec![
+                stream(1, "spotify", Route::Processed),
+                stream(2, "discord", Route::Processed),
+            ],
+            vec![snap(1, "spotify", true)],
+        );
+        s.update(Message::TogglePerApp(1));
+        match drain(&cmd) {
+            ControlCmd::SetPerApp { app, enabled } => {
+                assert_eq!(app, "spotify");
+                assert!(!enabled);
+            }
+            _ => panic!("expected SetPerApp"),
+        }
+        s.update(Message::TogglePerApp(2));
+        match drain(&cmd) {
+            ControlCmd::SetPerApp { app, enabled } => {
+                assert_eq!(app, "discord");
+                assert!(enabled);
+            }
+            _ => panic!("expected SetPerApp"),
+        }
+    }
+
+    #[test]
+    fn toggle_per_app_empty_label_errors_no_command() {
+        let (mut s, cmd) = build(vec![stream(5, "", Route::Processed)], vec![]);
+        s.update(Message::TogglePerApp(5));
+        assert!(cmd.try_recv().is_err()); // no command emitted
+        assert!(s.last_error.is_some());
+    }
+
+    #[test]
+    fn reset_selected_emits_reset() {
+        let (mut s, cmd) = build(vec![stream(9, "game", Route::Processed)], vec![]);
+        s.update(Message::ResetSelected);
+        assert!(matches!(drain(&cmd), ControlCmd::ResetLayerA { node_id: 9 }));
+    }
+
+    #[test]
+    fn profile_selected_emits_use_profile() {
+        let (mut s, cmd) = build(vec![], vec![]);
+        s.update(Message::ProfileSelected("night".into()));
+        match drain(&cmd) {
+            ControlCmd::UseProfile(name) => assert_eq!(name, "night"),
+            _ => panic!("expected UseProfile"),
+        }
+    }
+
+    #[test]
+    fn clear_overrides_emits_and_clears_optimistically() {
+        let (mut s, cmd) = build(vec![], vec![]);
+        s.setting_overrides
+            .insert("agc.enabled".into(), serde_json::json!(false));
+        s.update(Message::ClearOverrides);
+        assert!(matches!(drain(&cmd), ControlCmd::ClearOverrides));
+        assert!(s.setting_overrides.is_empty()); // optimistic
+    }
+
+    #[test]
+    fn tick_refreshes_layer_a_on_cadence() {
+        let (mut s, cmd) = build(vec![], vec![]);
+        for _ in 0..(REFRESH_EVERY_TICKS - 1) {
+            s.update(Message::Tick);
+        }
+        assert!(cmd.try_recv().is_err()); // not yet
+        s.update(Message::Tick); // the REFRESH_EVERY_TICKS-th tick
+        assert!(matches!(drain(&cmd), ControlCmd::RefreshLayerA));
+    }
+
+    // -- key mapping -----------------------------------------------------
+
+    fn press(c: &str) -> keyboard::Event {
+        keyboard::Event::KeyPressed {
+            key: keyboard::Key::Character(c.into()),
+            modified_key: keyboard::Key::Character(c.into()),
+            physical_key: keyboard::key::Physical::Unidentified(
+                keyboard::key::NativeCode::Unidentified,
+            ),
+            location: keyboard::Location::Standard,
+            modifiers: keyboard::Modifiers::default(),
+            text: None,
+            repeat: false,
+        }
+    }
+
+    #[test]
+    fn key_mapping_matches_tui_hotkeys() {
+        assert!(matches!(map_key(press("b")), Message::ToggleBypass));
+        assert!(matches!(map_key(press("p")), Message::TogglePerAppMaster));
+        assert!(matches!(map_key(press("r")), Message::RouteSelected));
+        assert!(matches!(map_key(press("a")), Message::PerAppSelected));
+        assert!(matches!(map_key(press("x")), Message::ResetSelected));
+        assert!(matches!(map_key(press("j")), Message::SelectDown));
+        assert!(matches!(map_key(press("k")), Message::SelectUp));
+        assert!(matches!(map_key(press("z")), Message::Noop));
+    }
+}

Added file: crates/headroom-gui/src/app/state_tests.rs+65 additions@@ -0,0 +1,65 @@
+use crossbeam_channel::unbounded;
+use headroom_ipc::{RouteList, Sinks, Status};
+
+use super::*;
+
+fn stream(node_id: u32, app: &str, route: Route) -> StreamRoute {
+    StreamRoute {
+        node_id,
+        app: app.into(),
+        route,
+    }
+}
+
+fn status_with(streams: Vec<StreamRoute>) -> Status {
+    Status {
+        version: "test".into(),
+        protocol: 1,
+        uptime_s: 0,
+        profile: "default".into(),
+        bypass: false,
+        per_app: false,
+        sinks: Sinks::default(),
+        streams,
+        layer_a: vec![],
+        warnings: vec![],
+        setting_overrides: Default::default(),
+    }
+}
+
+fn app_from_snapshot(
+    status_streams: Vec<StreamRoute>,
+    route_streams: Vec<StreamRoute>,
+) -> HeadroomApp {
+    let (_tx, rx) = unbounded();
+    let (cmd_tx, _cmd_rx) = unbounded();
+    HeadroomApp::new(Bootstrap {
+        snapshot: Snapshot {
+            status: status_with(status_streams),
+            route_list: RouteList {
+                rules: vec![],
+                current: route_streams,
+                default_route: Route::Processed,
+            },
+            profiles: vec![],
+        },
+        rx,
+        cmd_tx,
+    })
+}
+
+#[test]
+fn snapshot_merge_prefers_route_list_and_fills_missing_status_streams() {
+    let s = app_from_snapshot(
+        vec![
+            stream(1, "status-only", Route::Processed),
+            stream(2, "stale-status", Route::Processed),
+        ],
+        vec![stream(2, "route-list", Route::Bypass)],
+    );
+
+    assert_eq!(s.streams.get(&1).map(|r| r.route), Some(Route::Processed));
+    let got = s.streams.get(&2).expect("route list stream");
+    assert_eq!(got.app, "route-list");
+    assert_eq!(got.route, Route::Bypass);
+}

Added file: crates/headroom-gui/src/io.rs+282 additions@@ -0,0 +1,282 @@
+//! daemon bridge: two `Client` connections off the ui thread — a reader
+//! thread forwarding subscription events, a control thread running
+//! request/response ops fed by a `ControlCmd` channel.
+//!
+//! initial rpcs run on the calling thread so a dead daemon fails fast
+//! before any window opens. both workers survive the daemon going away
+//! (shutdown / crash / `systemctl restart`): the reader reconnects with
+//! capped backoff and pushes a fresh [`Snapshot`] so the ui re-seeds
+//! (node ids change across a restart); the control thread reconnects
+//! lazily with a one-shot retry across a dropped connection.
+
+use std::path::{Path, PathBuf};
+use std::thread;
+use std::time::Duration;
+
+use anyhow::{Context as _, Result};
+use crossbeam_channel::{unbounded, Receiver, Sender};
+use headroom_client::{Client, ClientError};
+use headroom_ipc::{Event, LayerASnapshot, ProfileInfo, Route, RouteList, Status, Topic};
+
+/// topics the monitor subscribes to. shared by the initial connect and
+/// every reconnect.
+const TOPICS: [Topic; 4] = [Topic::Meters, Topic::Routing, Topic::Profile, Topic::Daemon];
+
+/// reconnect backoff: first retry after the min, doubling to the cap.
+const RECONNECT_MIN_DELAY: Duration = Duration::from_millis(500);
+const RECONNECT_MAX_DELAY: Duration = Duration::from_secs(3);
+
+/// a control op the ui asks the control thread to run; each maps to one
+/// `Client` request/response call.
+pub enum ControlCmd {
+    /// `bypass.set`
+    SetBypass(bool),
+    /// `per-app.master`
+    SetPerAppMaster(bool),
+    /// `route.stream` — one-shot reroute of a live stream by node id
+    /// (doesn't survive the stream being torn down).
+    RouteStream { node_id: u32, to: Route },
+    /// `route.set` — persistent per-app rule, keyed by app label (matches
+    /// `application.name` / `process.binary`). survives the app recreating
+    /// its stream between tracks.
+    SetRoute { app: String, to: Route },
+    /// `per-app.set`
+    SetPerApp { app: String, enabled: bool },
+    /// `per-app.reset`
+    ResetLayerA { node_id: u32 },
+    /// `profile.use`
+    UseProfile(String),
+    /// `setting.reset` — clear all overlay setting overrides.
+    ClearOverrides,
+    /// `per-app.list` → [`AppMsg::LayerASnapshots`].
+    RefreshLayerA,
+    /// `profile.list` → [`AppMsg::Profiles`].
+    RefreshProfiles,
+}
+
+/// the daemon snapshot the ui seeds (and re-seeds) from; taken at connect
+/// and again on every reconnect.
+pub struct Snapshot {
+    pub status: Status,
+    pub route_list: RouteList,
+    /// seeds the switcher.
+    pub profiles: Vec<ProfileInfo>,
+}
+
+/// a message from a worker thread to the ui.
+pub enum AppMsg {
+    /// a subscription event off the wire (reader thread).
+    Event(Event),
+    /// the event stream ended; carries a reason for the footer banner.
+    /// the reader starts reconnecting immediately; [`AppMsg::Reconnected`]
+    /// follows once it succeeds.
+    Disconnected(String),
+    /// the reader reconnected after a drop. carries a fresh snapshot so
+    /// the ui re-seeds (node ids/uptime/profile change across a restart).
+    /// boxed to keep the enum small.
+    Reconnected(Box<Snapshot>),
+    /// a control op failed; surfaced in the footer.
+    ControlError(String),
+    /// fresh `profile.list` snapshot.
+    Profiles(Vec<ProfileInfo>),
+    /// fresh `per-app.list` snapshot (managed / ceiling / deferred).
+    LayerASnapshots(Vec<LayerASnapshot>),
+}
+
+/// everything `main` needs to seed the window.
+pub struct Bootstrap {
+    pub snapshot: Snapshot,
+    /// live event + worker channel, drained each tick.
+    pub rx: Receiver<AppMsg>,
+    /// hands control ops to the control thread.
+    pub cmd_tx: Sender<ControlCmd>,
+}
+
+/// connect, subscribe, fetch the initial snapshot, open a second control
+/// connection, then spawn the reader + control threads.
+///
+/// errors here are returned to the caller (fail fast before any window).
+/// once the threads run, a stream failure is reported in-band as
+/// [`AppMsg::Disconnected`] / [`AppMsg::Reconnected`]; control failures
+/// as [`AppMsg::ControlError`].
+pub fn start(socket: Option<PathBuf>) -> Result<Bootstrap> {
+    let mut client = match socket.as_deref() {
+        Some(p) => Client::connect_at(p)
+            .with_context(|| format!("connecting to headroom daemon at {}", p.display()))?,
+        None => Client::connect().context("connecting to headroom daemon (is it running?)")?,
+    };
+
+    // subscribe + initial snapshot before the client moves to the reader.
+    // a dead/half-broken daemon surfaces here.
+    let snapshot = fetch_snapshot(&mut client).context("initial daemon fetch")?;
+
+    // the resolved socket path drives reconnects on both worker threads.
+    let socket_path = client.socket_path().to_path_buf();
+
+    // second connection for control, on the same resolved socket.
+    let control = Client::connect_at(&socket_path).context("opening control connection")?;
+
+    let (tx, rx) = unbounded::<AppMsg>();
+    let (cmd_tx, cmd_rx) = unbounded::<ControlCmd>();
+
+    let reader_tx = tx.clone();
+    let reader_socket = socket_path.clone();
+    thread::Builder::new()
+        .name("headroom-gui-rx".into())
+        .spawn(move || reader_loop(reader_socket, client, reader_tx))
+        .context("spawning reader thread")?;
+
+    thread::Builder::new()
+        .name("headroom-gui-ctl".into())
+        .spawn(move || control_loop(socket_path, control, cmd_rx, tx))
+        .context("spawning control thread")?;
+
+    Ok(Bootstrap {
+        snapshot,
+        rx,
+        cmd_tx,
+    })
+}
+
+/// subscribe to [`TOPICS`] and pull `status` + `route.list` +
+/// `profile.list`. the `Client` correlates rpc responses while a
+/// subscription is active (buffers interleaved events), so doing this on
+/// the event connection is fine — one path seeds connect + every reconnect.
+fn fetch_snapshot(client: &mut Client) -> Result<Snapshot, ClientError> {
+    client.subscribe(&TOPICS)?;
+    let status = client.status()?;
+    let route_list = client.route_list()?;
+    let profiles = client.profile_list()?;
+    Ok(Snapshot {
+        status,
+        route_list,
+        profiles,
+    })
+}
+
+/// forward each event to the ui. on stream failure, announce the drop,
+/// reconnect (with backoff), and resume — returning only when the ui
+/// channel closes (window gone).
+fn reader_loop(socket: PathBuf, mut client: Client, tx: Sender<AppMsg>) {
+    loop {
+        match client.next_event() {
+            Ok(ev) => {
+                if tx.send(AppMsg::Event(ev)).is_err() {
+                    return; // ui gone.
+                }
+            }
+            Err(e) => {
+                tracing::warn!(error = %e, "event stream lost; reconnecting to daemon");
+                if tx.send(AppMsg::Disconnected(e.to_string())).is_err() {
+                    return;
+                }
+                match reconnect_event_client(&socket, &tx) {
+                    Some(c) => {
+                        tracing::info!("reconnected to daemon; re-seeded UI snapshot");
+                        client = c;
+                    }
+                    None => return, // ui gone while reconnecting.
+                }
+            }
+        }
+    }
+}
+
+/// reconnect the event stream after a drop. retries `connect_at` with
+/// capped backoff until the daemon answers with a fresh snapshot, then
+/// sends [`AppMsg::Reconnected`] and returns the live client. a daemon
+/// that's up but can't complete the snapshot (half-open / mid-restart)
+/// counts as a failed attempt. returns `None` only if the ui closed.
+fn reconnect_event_client(socket: &Path, tx: &Sender<AppMsg>) -> Option<Client> {
+    let mut delay = RECONNECT_MIN_DELAY;
+    loop {
+        if let Ok(mut client) = Client::connect_at(socket) {
+            if let Ok(snapshot) = fetch_snapshot(&mut client) {
+                if tx.send(AppMsg::Reconnected(Box::new(snapshot))).is_err() {
+                    return None;
+                }
+                return Some(client);
+            }
+        }
+        thread::sleep(delay);
+        delay = (delay * 2).min(RECONNECT_MAX_DELAY);
+    }
+}
+
+/// block on the command channel, dispatching each [`ControlCmd`] to its
+/// `Client` call. refresh ops reply with a snapshot `AppMsg`; failures
+/// become [`AppMsg::ControlError`]. returns when either channel closes.
+///
+/// the control connection reconnects lazily: if torn down (daemon
+/// restart) the next command opens a fresh one, and a command that fails
+/// mid-flight on a connection error is retried once before being reported.
+fn control_loop(socket: PathBuf, initial: Client, cmd_rx: Receiver<ControlCmd>, tx: Sender<AppMsg>) {
+    let mut client: Option<Client> = Some(initial);
+    while let Ok(cmd) = cmd_rx.recv() {
+        // reconnect if a prior op tore the connection down.
+        if client.is_none() {
+            client = Client::connect_at(&socket).ok();
+        }
+        let Some(c) = client.as_mut() else {
+            if tx
+                .send(AppMsg::ControlError("daemon unreachable".into()))
+                .is_err()
+            {
+                return;
+            }
+            continue;
+        };
+
+        let mut result = run_cmd(c, &cmd);
+        // one retry across a dropped connection — the daemon may have
+        // restarted since the last op left the socket stale.
+        if matches!(&result, Err(e) if is_connection_error(e)) {
+            client = Client::connect_at(&socket).ok();
+            if let Some(c) = client.as_mut() {
+                result = run_cmd(c, &cmd);
+            }
+        }
+
+        let msg = match result {
+            Ok(Some(reply)) => reply,
+            Ok(None) => continue,
+            Err(e) => {
+                // drop a dead connection so the next command reconnects.
+                if is_connection_error(&e) {
+                    client = None;
+                }
+                AppMsg::ControlError(e.to_string())
+            }
+        };
+        if tx.send(msg).is_err() {
+            return;
+        }
+    }
+}
+
+/// run one [`ControlCmd`] against `client`. borrows the command so the
+/// caller can retry on a fresh connection. `Ok(Some(_))` for refreshes
+/// that reply, `Ok(None)` for fire-and-forget toggles.
+fn run_cmd(client: &mut Client, cmd: &ControlCmd) -> Result<Option<AppMsg>, ClientError> {
+    match cmd {
+        ControlCmd::SetBypass(enabled) => client.bypass_set(*enabled).map(|()| None),
+        ControlCmd::SetPerAppMaster(enabled) => client.per_app_master(*enabled).map(|()| None),
+        ControlCmd::RouteStream { node_id, to } => {
+            client.route_stream(*node_id, *to).map(|()| None)
+        }
+        ControlCmd::SetRoute { app, to } => client.route_set(app, *to).map(|()| None),
+        ControlCmd::SetPerApp { app, enabled } => client.per_app_set(app, *enabled).map(|()| None),
+        ControlCmd::ResetLayerA { node_id } => client.layer_a_reset(*node_id).map(|()| None),
+        ControlCmd::UseProfile(name) => client.profile_use(name).map(|_| None),
+        ControlCmd::ClearOverrides => client.setting_reset().map(|_| None),
+        ControlCmd::RefreshLayerA => client.layer_a_list().map(|l| Some(AppMsg::LayerASnapshots(l))),
+        ControlCmd::RefreshProfiles => client.profile_list().map(|p| Some(AppMsg::Profiles(p))),
+    }
+}
+
+/// whether an error means the socket is gone (vs a server-side rejection
+/// of a delivered op). only the former warrants a reconnect; a `Protocol`
+/// error is a logical failure to surface as-is.
+fn is_connection_error(e: &ClientError) -> bool {
+    matches!(e, ClientError::Ipc(_))
+}

Added file: crates/headroom-gui/src/main.rs+67 additions@@ -0,0 +1,67 @@
+//! `headroom-gui` — native gpu-accelerated monitor for the headroom
+//! daemon, built on [iced](https://iced.rs). additive and optional, with
+//! full control parity with the ratatui tui (route/bypass/per-app/profile)
+//! by mouse + keyboard; ships as its own nix package, separate from the
+//! daemon. build from the nix dev shell (supplies iced's system libs).
+
+mod app;
+mod io;
+
+use std::path::PathBuf;
+
+use crate::app::HeadroomApp;
+
+fn main() -> anyhow::Result<()> {
+    init_tracing();
+
+    let socket = parse_socket_arg();
+
+    // connect + initial fetch before opening any window, so a dead daemon
+    // fails fast. the reader thread lives inside the returned `Bootstrap`;
+    // the iced `subscription` poll tick drains its channel.
+    let bootstrap = io::start(socket)?;
+
+    // iced's `BootFn` is `Fn` (callable repeatedly) but `Bootstrap` owns a
+    // receiver and is single-use; stash it and `take()` on the first boot.
+    let boot = std::sync::Mutex::new(Some(bootstrap));
+
+    iced::application(
+        move || HeadroomApp::new(boot.lock().unwrap().take().expect("boot runs once")),
+        HeadroomApp::update,
+        HeadroomApp::view,
+    )
+    .title(HeadroomApp::title)
+    .subscription(HeadroomApp::subscription)
+    .theme(|_state: &HeadroomApp| iced::Theme::Dark)
+    .window_size(iced::Size::new(900.0, 680.0))
+    .run()
+    .map_err(|e| anyhow::anyhow!("iced: {e}"))?;
+
+    Ok(())
+}
+
+/// minimal `--socket <path>` parsing — the only flag, so no clap.
+fn parse_socket_arg() -> Option<PathBuf> {
+    let mut args = std::env::args().skip(1);
+    while let Some(arg) = args.next() {
+        match arg.as_str() {
+            "--socket" => return args.next().map(PathBuf::from),
+            other => {
+                if let Some(path) = other.strip_prefix("--socket=") {
+                    return Some(PathBuf::from(path));
+                }
+            }
+        }
+    }
+    None
+}
+
+fn init_tracing() {
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            tracing_subscriber::EnvFilter::try_from_default_env()
+                .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("headroom_gui=info")),
+        )
+        .with_writer(std::io::stderr)
+        .init();
+}

headroom

Commit c19702ae09be

Commit `c19702ae09be`