feat(clients): tiered stats overlay everywhere — Compact/Normal/Detailed on every platform

Ship the Android client's 3-tier stats-overlay semantics in every other client
(design/stats-unification.md vocabulary): Off → Compact (one line: fps · e2e ms ·
Mb/s + loss flag) → Normal (mode + e2e p50/p95 + loss counters) → Detailed
(decoder path, HDR tag, per-stage latency equation).

Apple: new StatsVerbosity in PunktfunkKit persisted under punktfunk.statsVerbosity
(migrates the legacy hudEnabled bool: explicit off → Off, else Normal). The
existing three-finger tap (TouchMouse, trackpad/pointer modes only — touch
passthrough untouched) now cycles the tiers instead of toggling, matching
Android; ⌃⌥⇧S (menu + captured-state monitor) cycles the same ladder. Tiered
StreamHUDView (compact glass pill / headline HUD / full equation HUD); the iOS
corner disconnect also shows in Compact (the pill carries no button). Tier
pickers on iOS, macOS, tvOS and the gamepad settings UI.

Session stack (Linux + Windows + Deck share punktfunk-session): shared
pf_client_core::trust::StatsVerbosity; Settings grows stats_verbosity with a
show_stats fallback, and writes keep the legacy bool in sync so pre-tier
binaries reading the same JSON agree on off vs on. Ctrl+Alt+Shift+S cycles the
tier and re-renders the OSD immediately from the last stats window; the stdout
stats: line always carries the full Detailed text so the shell status card and
scripts keep a stable shape; --stats bumps Off → Normal without demoting a
richer tier. Tier pickers in the GTK dialog, the WinUI settings page and the
console-UI settings row; shortcut copy updated (GTK shortcuts window, Windows
help, session README). The Windows legacy builtin path keeps its bool HUD.

Tests: tier migration/round-trip in trust.rs, tiered stats_text output in
pf-presenter.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

crates/pf-client-core/src/trust.rs

@@ -254,6 +254,50 @@ pub fn probe_reachable_many(
         .collect()
 }
 
+/// How much the on-stream statistics overlay shows — the Android client's tiers, shared
+/// across every client (design/stats-unification.md): each tier is a strict superset of
+/// the previous. Ctrl+Alt+Shift+S cycles Off → Compact → Normal → Detailed live.
+#[derive(Clone, Copy, PartialEq, Eq, Debug, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum StatsVerbosity {
+    Off,
+    /// One glanceable line: fps · end-to-end ms · Mb/s.
+    Compact,
+    /// Stream mode plus the end-to-end latency percentiles and loss counters.
+    Normal,
+    /// Everything: decoder path, HDR tags, and the per-stage latency equation.
+    Detailed,
+}
+
+impl StatsVerbosity {
+    /// Cycle order (also the settings pickers' option order).
+    pub const ALL: [StatsVerbosity; 4] = [
+        StatsVerbosity::Off,
+        StatsVerbosity::Compact,
+        StatsVerbosity::Normal,
+        StatsVerbosity::Detailed,
+    ];
+
+    /// The next tier in the live cycle, wrapping back to Off.
+    pub fn next(self) -> StatsVerbosity {
+        match self {
+            StatsVerbosity::Off => StatsVerbosity::Compact,
+            StatsVerbosity::Compact => StatsVerbosity::Normal,
+            StatsVerbosity::Normal => StatsVerbosity::Detailed,
+            StatsVerbosity::Detailed => StatsVerbosity::Off,
+        }
+    }
+
+    pub fn label(self) -> &'static str {
+        match self {
+            StatsVerbosity::Off => "Off",
+            StatsVerbosity::Compact => "Compact",
+            StatsVerbosity::Normal => "Normal",
+            StatsVerbosity::Detailed => "Detailed",
+        }
+    }
+}
+
 /// App settings, persisted as JSON. Stringly-typed gamepad/compositor prefs so the file
 /// stays readable; parsed with `*Pref::from_name` at connect time.
 #[derive(Clone, Serialize, Deserialize)]
@@ -301,10 +345,16 @@ pub struct Settings {
     /// `default = true`: the Linux stores never carried this and always advertised.
     #[serde(default = "default_true")]
     pub hdr_enabled: bool,
-    /// Show the on-stream statistics overlay (toggle live with Ctrl+Alt+Shift+S).
-    /// `alias`: the pre-unification WinUI shell (≤ 0.8.4) persisted this as `show_hud`.
+    /// Legacy on/off for the stats overlay — superseded by `stats_verbosity` but kept
+    /// written in sync (`set_stats_verbosity`) so pre-tier binaries reading the same
+    /// file keep working. `alias`: the pre-unification WinUI shell (≤ 0.8.4) persisted
+    /// this as `show_hud`.
     #[serde(alias = "show_hud")]
     pub show_stats: bool,
+    /// Stats overlay tier. `None` = a pre-tier store; resolve through
+    /// [`Settings::stats_verbosity`], which falls back to `show_stats`.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub stats_verbosity: Option<StatsVerbosity>,
     /// Enter fullscreen when a stream starts (F11 / the controller chord / the top-edge
     /// header reveal exit it). Gaming-Mode launches (`--fullscreen`) fullscreen regardless.
     pub fullscreen_on_stream: bool,
@@ -322,6 +372,23 @@ fn default_true() -> bool {
 }
 
 impl Settings {
+    /// The stats-overlay tier, resolving pre-tier stores: an old `show_stats = false`
+    /// reads as Off, everything else as Normal (≈ what the pre-tier overlay showed).
+    pub fn stats_verbosity(&self) -> StatsVerbosity {
+        self.stats_verbosity.unwrap_or(if self.show_stats {
+            StatsVerbosity::Normal
+        } else {
+            StatsVerbosity::Off
+        })
+    }
+
+    /// Set the tier, keeping the legacy `show_stats` bool coherent for pre-tier
+    /// binaries that read the same settings file.
+    pub fn set_stats_verbosity(&mut self, v: StatsVerbosity) {
+        self.stats_verbosity = Some(v);
+        self.show_stats = v != StatsVerbosity::Off;
+    }
+
     /// The `codec` setting as a `quic::CODEC_*` preference bit (`0` = auto).
     pub fn preferred_codec(&self) -> u8 {
         match self.codec.as_str() {
@@ -351,6 +418,7 @@ impl Default for Settings {
             adapter: String::new(),
             hdr_enabled: true,
             show_stats: true,
+            stats_verbosity: None,
             fullscreen_on_stream: true,
             library_enabled: false,
         }
@@ -432,6 +500,28 @@ mod tests {
         assert!(!s.library_enabled);
     }
 
+    /// Stats-tier resolution: a pre-tier store falls back to `show_stats` (off → Off,
+    /// on/absent → Normal), an explicit tier wins, and setting a tier keeps the legacy
+    /// bool in sync so pre-tier binaries reading the same file agree on off vs on.
+    #[test]
+    fn stats_verbosity_migrates_and_round_trips() {
+        let mut s: Settings = serde_json::from_str("{}").unwrap();
+        assert_eq!(s.stats_verbosity(), StatsVerbosity::Normal);
+        let off: Settings = serde_json::from_str(r#"{"show_stats":false}"#).unwrap();
+        assert_eq!(off.stats_verbosity(), StatsVerbosity::Off);
+
+        s.set_stats_verbosity(StatsVerbosity::Compact);
+        assert!(s.show_stats);
+        s.set_stats_verbosity(StatsVerbosity::Off);
+        assert!(!s.show_stats);
+
+        s.set_stats_verbosity(StatsVerbosity::Detailed);
+        let round: Settings = serde_json::from_str(&serde_json::to_string(&s).unwrap()).unwrap();
+        assert_eq!(round.stats_verbosity(), StatsVerbosity::Detailed);
+        // The tier serializes lowercase — the file stays human-readable.
+        assert!(serde_json::to_string(&s).unwrap().contains("\"detailed\""));
+    }
+
     /// The WinUI shell's known-hosts shape (no `last_used` field) loads losslessly — same
     /// filename, same directory, so on Windows the two clients genuinely share the store.
     #[test]

crates/pf-console-ui/src/screens/settings.rs

@@ -10,6 +10,7 @@ use crate::screens::{Ctx, Outbox};
 use crate::theme::{Fonts, DIM, W};
 use crate::widgets::{ListMsg, MenuList, RowSpec};
 use pf_client_core::gamepad::{MenuEvent, MenuPulse};
+use pf_client_core::trust::StatsVerbosity;
 use skia_safe::{Canvas, Rect};
 
 /// Stable row identity — adjust/activate dispatch by id so nothing acts on a stale
@@ -241,7 +242,7 @@ fn row_spec(id: RowId, ctx: &Ctx) -> RowSpec {
         RowId::Stats => (
             Some("Interface"),
             "Statistics overlay",
-            on_off(s.show_stats).into(),
+            s.stats_verbosity().label().into(),
         ),
     };
     RowSpec {
@@ -274,7 +275,10 @@ fn detail(id: RowId) -> &'static str {
         RowId::Mic => "Send this device's microphone to the host's virtual mic.",
         RowId::Pad => "Which pad is forwarded to the host, as player 1.",
         RowId::PadType => "The virtual pad the host creates — Automatic matches this controller.",
-        RowId::Stats => "Resolution, frame rate, throughput and latency while streaming.",
+        RowId::Stats => {
+            "How much the overlay shows: Compact (one line) → Normal → Detailed. \
+             Ctrl+Alt+Shift+S cycles it live while streaming."
+        }
     }
 }
 
@@ -332,7 +336,13 @@ fn adjust(id: RowId, delta: i32, wrap: bool, ctx: &mut Ctx) -> bool {
             step_option(cur, keys.len(), delta, wrap).map(|i| s.forward_pad = keys[i].clone())
         }
         RowId::PadType => step_str(&PAD_TYPES, &mut s.gamepad, delta, wrap),
-        RowId::Stats => toggle(&mut s.show_stats, delta, wrap),
+        RowId::Stats => {
+            let cur = StatsVerbosity::ALL
+                .iter()
+                .position(|v| *v == s.stats_verbosity());
+            step_option(cur, StatsVerbosity::ALL.len(), delta, wrap)
+                .map(|i| s.set_stats_verbosity(StatsVerbosity::ALL[i]))
+        }
     }
     .is_some()
 }

crates/pf-presenter/src/run.rs

@@ -8,8 +8,10 @@
 //! library; the app quits only on B/window-close).
 //!
 //! Stdout is the machine interface (the shell↔session contract): one `{"ready":true}`
-//! line after the first presented frame, `stats: …` lines once per window while enabled
-//! (Ctrl+Alt+Shift+S toggles). Logs go to stderr (the binary configures tracing so).
+//! line after the first presented frame, `stats: …` lines once per window while the
+//! overlay tier isn't Off (Ctrl+Alt+Shift+S cycles Off → Compact → Normal → Detailed;
+//! the stdout line always carries the full Detailed text so parsers see a stable
+//! shape). Logs go to stderr (the binary configures tracing so).
 
 use crate::input::Capture;
 use crate::overlay::{FrameCtx, Overlay, OverlayAction, OverlayFrame, SessionPhase};
@@ -17,6 +19,7 @@ use crate::vk::{FrameInput, Presenter};
 use anyhow::{Context as _, Result};
 use pf_client_core::gamepad::GamepadService;
 use pf_client_core::session::{self, SessionEvent, SessionHandle, SessionParams, Stats};
+use pf_client_core::trust::StatsVerbosity;
 use pf_client_core::video::VulkanDecodeDevice;
 use pf_client_core::video::{DecodedFrame, DecodedImage};
 use punktfunk_core::client::NativeClient;
@@ -37,8 +40,9 @@ pub struct SessionOpts {
     /// changing content, not a window jumping displays). Fullscreen follows the display
     /// this lands on.
     pub window_pos: Option<(i32, i32)>,
-    /// Print `stats:` lines (Ctrl+Alt+Shift+S toggles live).
-    pub print_stats: bool,
+    /// Stats overlay tier at start — gates the OSD panel AND the stdout `stats:` lines
+    /// (Ctrl+Alt+Shift+S cycles Off → Compact → Normal → Detailed live).
+    pub stats_verbosity: StatsVerbosity,
     /// Emit the `{"ready":true}` stdout line after the first presented frame.
     pub json_status: bool,
     /// Called once on `Connected` with the host's fingerprint (trust persistence is the
@@ -162,8 +166,11 @@ struct StreamState {
     // all) demotes the decoder to software via the shared flag — once per session.
     dmabuf_demoted: bool,
     hw_fails: u32,
-    /// The OSD's text (multi-line; rebuilt each Stats window).
+    /// The OSD's text (multi-line; rebuilt each Stats window and on a live tier cycle).
     osd_text: String,
+    /// The last pump window, kept so a Ctrl+Alt+Shift+S tier cycle can re-render the
+    /// OSD immediately instead of waiting up to 1 s for the next Stats event.
+    last_stats: Option<Stats>,
 }
 
 impl StreamState {
@@ -207,6 +214,7 @@ impl StreamState {
             dmabuf_demoted: false,
             hw_fails: 0,
             osd_text: String::new(),
+            last_stats: None,
         }
     }
 
@@ -351,7 +359,7 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
     let mouse = sdl.mouse();
 
     let mut fullscreen = opts.fullscreen;
-    let mut print_stats = opts.print_stats;
+    let mut stats_verbosity = opts.stats_verbosity;
     let mut overlay_frame: Option<OverlayFrame> = None;
     // SDL text input tracks the overlay's editing state (started = IME/`TextInput`
     // events on desktop, and the door Steam's on-screen keyboard types through under
@@ -452,7 +460,24 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                         continue;
                     }
                     if chord && sc == Scancode::S {
-                        print_stats = !print_stats;
+                        stats_verbosity = stats_verbosity.next();
+                        tracing::info!(tier = ?stats_verbosity, "chord: stats verbosity");
+                        // Re-render the OSD from the last window immediately — waiting
+                        // for the next Stats event would lag the keypress by up to 1 s.
+                        if let Some(st) = &mut stream {
+                            let text = match &st.last_stats {
+                                Some(s) => stats_text(
+                                    stats_verbosity,
+                                    &st.mode_line,
+                                    s,
+                                    &st.presented,
+                                    st.hdr,
+                                    presenter.hdr_active(),
+                                ),
+                                None => String::new(),
+                            };
+                            st.osd_text = text;
+                        }
                         continue;
                     }
                     // F11 or Alt+Enter (some keyboards' Fn layer sends a media key for
@@ -647,15 +672,27 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                 }
                 SessionEvent::Stats(s) => {
                     st.osd_text = stats_text(
+                        stats_verbosity,
                         &st.mode_line,
                         &s,
                         &st.presented,
                         st.hdr,
                         presenter.hdr_active(),
                     );
-                    if print_stats {
-                        println!("stats: {}", st.osd_text.replace('\n', " | "));
+                    if stats_verbosity != StatsVerbosity::Off {
+                        // The stdout line is the machine interface (shell status card,
+                        // scripts) — always the full Detailed text, whatever the OSD tier.
+                        let full = stats_text(
+                            StatsVerbosity::Detailed,
+                            &st.mode_line,
+                            &s,
+                            &st.presented,
+                            st.hdr,
+                            presenter.hdr_active(),
+                        );
+                        println!("stats: {}", full.replace('\n', " | "));
                     }
+                    st.last_stats = Some(s);
                 }
                 SessionEvent::Failed {
                     msg,
@@ -728,7 +765,8 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                         _ => None,
                     };
                     (
-                        (print_stats && !st.osd_text.is_empty()).then_some(st.osd_text.as_str()),
+                        (stats_verbosity != StatsVerbosity::Off && !st.osd_text.is_empty())
+                            .then_some(st.osd_text.as_str()),
                         hint,
                     )
                 }
@@ -996,45 +1034,138 @@ const HINT_KEYBOARD: &str = "Click the stream to capture input · Ctrl+Alt+Shift
 const HINT_WITH_PAD: &str = "Click the stream to capture input · Ctrl+Alt+Shift+Q releases · \
      Ctrl+Alt+Shift+D disconnects · hold L1 + R1 + Start + Select to leave";
 
-/// The unified stats window (design/stats-unification.md) as OSD text — multi-line for
-/// the console-UI panel; the stdout `stats:` line joins it with `|`.
+/// The unified stats window (design/stats-unification.md) as OSD text at the given tier
+/// (the Android client's vocabulary, each a strict superset of the previous):
+/// Compact = one glanceable line, Normal = mode + end-to-end percentiles + loss,
+/// Detailed = decoder path, HDR tag and the per-stage equation on top. Off reads empty.
+/// Multi-line for the console-UI panel; the stdout `stats:` line joins Detailed with `|`.
 ///
 /// The HDR tag is honest about the display path: `HDR` only when the swapchain actually
 /// runs HDR10 (`hdr_display`); a PQ stream tone-mapped onto an SDR surface (no HDR10
 /// format offered, HDR off in the compositor) shows `HDR→SDR` instead.
 fn stats_text(
+    verbosity: StatsVerbosity,
     mode_line: &str,
     s: &Stats,
     p: &PresentedWindow,
     hdr_stream: bool,
     hdr_display: bool,
 ) -> String {
-    let mut text = format!(
-        "{mode_line} · {:.0} fps · {:.1} Mb/s · {}{}",
-        s.fps,
-        s.mbps,
-        if s.decoder.is_empty() { "-" } else { s.decoder },
-        match (hdr_stream, hdr_display) {
-            (true, true) => " · HDR",
-            (true, false) => " · HDR→SDR",
-            _ => "",
-        },
-    );
+    match verbosity {
+        StatsVerbosity::Off => return String::new(),
+        StatsVerbosity::Compact => {
+            // fps · e2e ms · Mb/s — the latency term waits for the first presenter
+            // window (0 = no capture→displayed samples yet).
+            let mut text = format!("{:.0} fps", s.fps);
+            if p.e2e_p50_ms > 0.0 {
+                text.push_str(&format!(" · {:.1} ms", p.e2e_p50_ms));
+            }
+            text.push_str(&format!(" · {:.0} Mb/s", s.mbps));
+            if s.lost > 0 {
+                text.push_str(&format!(" · lost {}", s.lost));
+            }
+            return text;
+        }
+        StatsVerbosity::Normal | StatsVerbosity::Detailed => {}
+    }
+    let detailed = verbosity == StatsVerbosity::Detailed;
+    let mut text = if detailed {
+        format!(
+            "{mode_line} · {:.0} fps · {:.1} Mb/s · {}{}",
+            s.fps,
+            s.mbps,
+            if s.decoder.is_empty() { "-" } else { s.decoder },
+            match (hdr_stream, hdr_display) {
+                (true, true) => " · HDR",
+                (true, false) => " · HDR→SDR",
+                _ => "",
+            },
+        )
+    } else {
+        format!("{mode_line} · {:.0} fps · {:.1} Mb/s", s.fps, s.mbps)
+    };
     text.push_str(&format!(
         "\ne2e {:.1}/{:.1} ms (p50/p95)",
         p.e2e_p50_ms, p.e2e_p95_ms
     ));
-    if s.split {
-        text.push_str(&format!(" · host {:.1} · net {:.1}", s.host_ms, s.net_ms));
-    } else {
-        text.push_str(&format!(" · host+net {:.1}", s.host_net_ms));
+    if detailed {
+        if s.split {
+            text.push_str(&format!(" · host {:.1} · net {:.1}", s.host_ms, s.net_ms));
+        } else {
+            text.push_str(&format!(" · host+net {:.1}", s.host_net_ms));
+        }
+        text.push_str(&format!(
+            " · decode {:.1} · display {:.1} ms",
+            s.decode_ms, p.display_ms
+        ));
     }
-    text.push_str(&format!(
-        " · decode {:.1} · display {:.1} ms",
-        s.decode_ms, p.display_ms
-    ));
     if s.lost > 0 {
         text.push_str(&format!("\nlost {} ({:.1}%)", s.lost, s.lost_pct));
     }
     text
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn sample() -> (Stats, PresentedWindow) {
+        (
+            Stats {
+                fps: 119.6,
+                mbps: 24.3,
+                host_net_ms: 2.1,
+                host_ms: 1.2,
+                net_ms: 0.9,
+                split: true,
+                decode_ms: 1.8,
+                lost: 3,
+                lost_pct: 0.4,
+                decoder: "vulkan",
+            },
+            PresentedWindow {
+                e2e_p50_ms: 6.4,
+                e2e_p95_ms: 9.1,
+                display_ms: 1.1,
+            },
+        )
+    }
+
+    /// The tier ladder: Off is empty, Compact is one line, Normal adds the mode + e2e
+    /// lines but no stage terms or decoder tag, Detailed carries everything.
+    #[test]
+    fn stats_text_tiers() {
+        let (s, p) = sample();
+        let text = |v| stats_text(v, "1920×1080@120", &s, &p, true, false);
+
+        assert_eq!(text(StatsVerbosity::Off), "");
+
+        let compact = text(StatsVerbosity::Compact);
+        assert_eq!(compact, "120 fps · 6.4 ms · 24 Mb/s · lost 3");
+        assert_eq!(compact.lines().count(), 1);
+
+        let normal = text(StatsVerbosity::Normal);
+        assert!(normal.starts_with("1920×1080@120 · 120 fps · 24.3 Mb/s\n"));
+        assert!(normal.contains("e2e 6.4/9.1 ms (p50/p95)"));
+        assert!(normal.contains("lost 3 (0.4%)"));
+        assert!(!normal.contains("vulkan"), "decoder tag is Detailed-only");
+        assert!(!normal.contains("decode"), "stage terms are Detailed-only");
+
+        let detailed = text(StatsVerbosity::Detailed);
+        assert!(detailed.contains("vulkan · HDR→SDR"));
+        assert!(detailed.contains("host 1.2 · net 0.9 · decode 1.8 · display 1.1 ms"));
+        assert!(detailed.contains("lost 3 (0.4%)"));
+    }
+
+    /// Compact omits the latency term until the presenter's first e2e window lands.
+    #[test]
+    fn compact_waits_for_e2e() {
+        let (mut s, _) = sample();
+        s.lost = 0;
+        let p = PresentedWindow::default();
+        assert_eq!(
+            stats_text(StatsVerbosity::Compact, "m", &s, &p, false, false),
+            "120 fps · 24 Mb/s"
+        );
+    }
+}