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>
2026-07-10 01:42:46 +02:00
parent 7b25868a19
commit 38b9f310e2
23 changed files with 528 additions and 119 deletions
@@ -31,8 +31,15 @@ struct ContentView: View {
    @AppStorage(DefaultsKey.codec) private var codec = "auto"
    @AppStorage(DefaultsKey.hdrEnabled) private var hdrEnabled = true
    @AppStorage(DefaultsKey.fullscreenWhileStreaming) private var fullscreenWhileStreaming = true
-    @AppStorage(DefaultsKey.hudEnabled) private var hudEnabled = true
+    // The raw string is what @AppStorage observes (so cycles from any surface re-render this
+    // view); the absent-key default runs the legacy-hudEnabled migration once per init.
+    @AppStorage(DefaultsKey.statsVerbosity) private var statsVerbosityRaw
+        = StatsVerbosity.current.rawValue
    @AppStorage(DefaultsKey.hudPlacement) private var hudPlacement = HUDPlacement.topTrailing.rawValue
+    /// The persisted overlay tier (unknown raw falls back to .normal, like the migration).
+    private var statsVerbosity: StatsVerbosity {
+        StatsVerbosity(rawValue: statsVerbosityRaw) ?? .normal
+    }
    /// The `codec` setting as a `PUNKTFUNK_CODEC_*` soft-preference byte (`0` = auto).
    private var preferredCodecByte: UInt8 {
        switch codec {
@@ -393,8 +400,10 @@ struct ContentView: View {
                    displayMeter: model.displayStage
                )
                .overlay(alignment: placement.alignment) {
-                    if captureEnabled && hudEnabled {
-                        StreamHUDView(model: model, connection: conn, placement: placement)
+                    if captureEnabled && statsVerbosity != .off {
+                        StreamHUDView(
+                            model: model, connection: conn, placement: placement,
+                            verbosity: statsVerbosity)
                    }
                }
                #if os(macOS)
@@ -422,17 +431,18 @@ struct ContentView: View {
                }
                #endif
                #if os(iOS)
-                // Touch users have no menu / ⌘D, so when the HUD (and its Disconnect button)
-                // is hidden, keep a minimal always-reachable exit in a corner. It rides a
-                // material disc (like the HUD) so the glyph stays legible over a bright frame
-                // — this is the sole touch disconnect path when stats are off.
+                // Touch users have no menu / ⌘D, so when the HUD's Disconnect button isn't on
+                // screen — the overlay off, or the compact pill (which carries no button) —
+                // keep a minimal always-reachable exit in a corner. It rides a material disc
+                // (like the HUD) so the glyph stays legible over a bright frame — this is the
+                // sole touch disconnect path in those tiers.
                .overlay(alignment: .topLeading) {
-                    if captureEnabled && !hudEnabled {
+                    if captureEnabled && (statsVerbosity == .off || statsVerbosity == .compact) {
                        Button { model.disconnect() } label: {
                            Image(systemName: "xmark")
                                .font(.headline.weight(.semibold))
                                .frame(width: 36, height: 36)
-                                // Sole touch exit when the HUD is off — a floating glass disc
+                                // Sole touch exit in the off/compact tiers — a floating glass disc
                                // over the frame (26+, material fallback). interactive: the disc
                                // IS the tap target, so the glass reacts to press.
                                .glassBackground(Circle(), interactive: true)
@@ -5,8 +5,9 @@
 // (the Linux client has its GTK Shortcuts window, Windows its start-of-stream banner). While
 // input is CAPTURED these key equivalents never reach the menu (the stream view swallows
 // keys); InputCapture's monitor detects the same combos there and performs the same actions —
-// the menu covers the released state and discoverability. The stats toggle just flips the
-// shared `hudEnabled` setting; ContentView reads the same @AppStorage and reacts.
+// the menu covers the released state and discoverability. The stats item cycles the shared
+// `statsVerbosity` tier (off → compact → normal → detailed → off); ContentView reads the same
+// @AppStorage and reacts.
 //
 // tvOS has no menu bar / hardware-keyboard command surface (disconnect there is the Siri
 // Remote's Menu button, handled by ContentView's `.onExitCommand`), so this whole file is
@@ -36,12 +37,16 @@ extension FocusedValues {

 struct StreamCommands: Commands {
    @FocusedValue(\.sessionFocus) private var session
-    @AppStorage(DefaultsKey.hudEnabled) private var hudEnabled = true
+    // The raw string so @AppStorage observes the shared key; the absent-key default runs the
+    // legacy-hudEnabled migration (same pattern as ContentView/SettingsView).
+    @AppStorage(DefaultsKey.statsVerbosity) private var statsVerbosityRaw
+        = StatsVerbosity.current.rawValue

    var body: some Commands {
        CommandMenu("Stream") {
-            Button(hudEnabled ? "Hide Statistics" : "Show Statistics") {
-                hudEnabled.toggle()
+            Button("Cycle Statistics") {
+                let current = StatsVerbosity(rawValue: statsVerbosityRaw) ?? .normal
+                statsVerbosityRaw = current.next().rawValue
            }
            .keyboardShortcut("s", modifiers: [.control, .option, .shift])
            // Reaches the key window's stream view via NotificationCenter — capture is view
@@ -1,7 +1,10 @@
-// The streaming overlay HUD: mode + fps/throughput, the unified latency lines
-// (design/stats-unification.md — end-to-end headline + the stage equation under stage-2, the
-// capture→received headline under the stage-1 fallback), the loss counter, the platform input
-// hint, and disconnect.
+// The streaming overlay HUD, tiered by StatsVerbosity (the Android client's 3-tier semantics):
+//  * compact — one glass-pill line: fps · end-to-end p50 · throughput (+ loss when lossy);
+//  * normal — mode + fps/throughput, the unified latency HEADLINE (design/stats-unification.md
+//    — end-to-end under stage-2, capture→received under the stage-1 fallback), the loss
+//    counter, the platform input hint, and disconnect;
+//  * detailed — everything normal has plus the stage equation line(s) under the headline.
+// `.off` never reaches this view (ContentView gates the overlay on the tier).

 import PunktfunkKit
 import SwiftUI
@@ -10,8 +13,56 @@ struct StreamHUDView: View {
    @ObservedObject var model: SessionModel
    let connection: PunktfunkConnection
    var placement: HUDPlacement = .topTrailing
+    let verbosity: StatsVerbosity

    var body: some View {
+        // .off is gated upstream (ContentView only mounts the HUD when the tier is on) —
+        // render nothing if it ever slips through.
+        if verbosity == .compact {
+            compactPill
+        } else if verbosity != .off {
+            fullHUD
+        }
+    }
+
+    // MARK: - Compact tier
+
+    /// One line on the glass pill: `{fps} fps · {e2e p50} ms · {mbps} Mb/s`. The ms segment is
+    /// the best available latency headline (stage-2 end-to-end, else the stage-1
+    /// capture→received) and is omitted until either is valid. Loss appends in the same quiet
+    /// styling the full HUD's lost line uses.
+    private var compactPill: some View {
+        HStack(spacing: 6) {
+            Circle()
+                .fill(Color.accentColor)
+                .frame(width: 7, height: 7)
+            Text(compactLine)
+                .font(.system(.caption, design: .monospaced))
+            if model.lostFrames > 0 {
+                Text("· lost \(model.lostFrames)")
+                    .font(.system(.caption2, design: .monospaced))
+                    .foregroundStyle(.secondary)
+            }
+        }
+        .padding(10)
+        .glassBackground(RoundedRectangle(cornerRadius: 10))
+        .padding(10)
+    }
+
+    private var compactLine: String {
+        var parts = ["\(model.fps) fps"]
+        if model.endToEndValid {
+            parts.append(String(format: "%.1f ms", model.endToEndP50Ms))
+        } else if model.hostNetworkValid {
+            parts.append(String(format: "%.1f ms", model.hostNetworkP50Ms))
+        }
+        parts.append(String(format: "%.1f Mb/s", model.mbps))
+        return parts.joined(separator: " · ")
+    }
+
+    // MARK: - Normal / detailed tiers
+
+    private var fullHUD: some View {
        VStack(alignment: placement.isTrailing ? .trailing : .leading, spacing: 4) {
            HStack(spacing: 6) {
                Circle()
@@ -26,11 +77,11 @@ struct StreamHUDView: View {
                Text("end-to-end \(model.endToEndP50Ms, specifier: "%.1f") ms p50 · \(model.endToEndP95Ms, specifier: "%.1f") p95 · capture→on-glass\(model.endToEndSkewCorrected ? "" : " (same-host clock)")")
                    .font(.system(.caption2, design: .monospaced))
                    .foregroundStyle(.secondary)
-                // The equation: the stages tiling the headline interval (per-window p50s —
-                // they only approximately sum to the directly-measured total). With a host
-                // that reports per-AU timings (0xCF) the first term splits into host + network
-                // (phase 2); an old host keeps the combined term.
-                if model.hostNetworkValid && model.decodeValid && model.displayValid {
+                // The equation (detailed tier only): the stages tiling the headline interval
+                // (per-window p50s — they only approximately sum to the directly-measured
+                // total). With a host that reports per-AU timings (0xCF) the first term splits
+                // into host + network (phase 2); an old host keeps the combined term.
+                if verbosity == .detailed && model.hostNetworkValid && model.decodeValid && model.displayValid {
                    if model.splitValid {
                        Text("= host \(model.hostP50Ms, specifier: "%.1f") + network \(model.networkP50Ms, specifier: "%.1f") + decode \(model.decodeP50Ms, specifier: "%.1f") + display \(model.displayP50Ms, specifier: "%.1f")")
                            .font(.system(.caption2, design: .monospaced))
@@ -45,11 +96,12 @@ struct StreamHUDView: View {
                // Stage-1 fallback presenter: the layer decodes + presents internally with no
                // per-frame stamp, so the honest headline ends at receipt. The host/network
                // split still applies there (receipt is presenter-independent) — it becomes the
-                // only equation line; without it, host+network IS the whole measured interval.
+                // only equation line (detailed tier); without it, host+network IS the whole
+                // measured interval.
                Text("capture→received \(model.hostNetworkP50Ms, specifier: "%.1f") ms p50 · \(model.hostNetworkP95Ms, specifier: "%.1f") p95\(model.hostNetworkSkewCorrected ? "" : " (same-host clock)")")
                    .font(.system(.caption2, design: .monospaced))
                    .foregroundStyle(.secondary)
-                if model.splitValid {
+                if verbosity == .detailed && model.splitValid {
                    Text("= host \(model.hostP50Ms, specifier: "%.1f") + network \(model.networkP50Ms, specifier: "%.1f")")
                        .font(.system(.caption2, design: .monospaced))
                        .foregroundStyle(.secondary)
@@ -29,7 +29,10 @@ struct GamepadSettingsView: View {
    @AppStorage(DefaultsKey.enable444) private var enable444 = true
    @AppStorage(DefaultsKey.codec) private var codec = "auto"
    @AppStorage(DefaultsKey.micEnabled) private var micEnabled = true
-    @AppStorage(DefaultsKey.hudEnabled) private var hudEnabled = true
+    // The overlay tier's raw string (rows tag by rawValue); the absent-key default runs the
+    // legacy-hudEnabled migration (same pattern as ContentView/SettingsView).
+    @AppStorage(DefaultsKey.statsVerbosity) private var statsVerbosityRaw
+        = StatsVerbosity.current.rawValue
    @AppStorage(DefaultsKey.hudPlacement) private var hudPlacement = HUDPlacement.topTrailing.rawValue
    @AppStorage(DefaultsKey.libraryEnabled) private var libraryEnabled = false
    @AppStorage(DefaultsKey.gamepadUIEnabled) private var gamepadUIEnabled = true
@@ -271,10 +274,12 @@ struct GamepadSettingsView: View {
                options: SettingsOptions.padTypes, current: gamepadType
            ) { gamepadType = $0 },

-            toggleRow(
+            choiceRow(
                id: "hud", header: "Interface", icon: "chart.bar", label: "Statistics overlay",
-                detail: "Resolution, frame rate, throughput and latency while streaming.",
-                value: $hudEnabled),
+                detail: "How much to show while streaming — Compact is a one-line pill, "
+                    + "Detailed adds the latency stage breakdown.",
+                options: SettingsOptions.statsVerbosities, current: statsVerbosityRaw
+            ) { statsVerbosityRaw = $0 },
            choiceRow(
                id: "hudPlacement", icon: "rectangle.inset.topright.filled", label: "Overlay position",
                detail: "Which corner the statistics overlay sits in.",
@@ -37,6 +37,10 @@ enum SettingsOptions {
    static let hudPlacements: [(label: String, tag: String)] =
        HUDPlacement.allCases.map { ($0.label, $0.rawValue) }

+    /// Stats-overlay tiers (`DefaultsKey.statsVerbosity`) — the `tag` is the raw value.
+    static let statsVerbosities: [(label: String, tag: String)] =
+        StatsVerbosity.allCases.map { ($0.label, $0.rawValue) }
+
    /// Video-codec preference (`DefaultsKey.codec`) — a soft preference the host falls back from.
    /// AV1 appears only on devices with an AV1 hardware decoder (the same
    /// `AV1.hardwareDecodeSupported` gate SessionModel advertises by) — elsewhere it would be a
@@ -385,13 +385,17 @@ extension SettingsView {

    @ViewBuilder var statisticsSection: some View {
        Section {
-            Toggle("Show statistics overlay", isOn: $hudEnabled)
+            Picker("Statistics overlay", selection: $statsVerbosityRaw) {
+                ForEach(StatsVerbosity.allCases, id: \.rawValue) { tier in
+                    Text(tier.label).tag(tier.rawValue)
+                }
+            }
            Picker("Position", selection: $hudPlacement) {
                ForEach(HUDPlacement.allCases) { placement in
                    Text(placement.label).tag(placement.rawValue)
                }
            }
-            .disabled(!hudEnabled)
+            .disabled(statsVerbosityRaw == StatsVerbosity.off.rawValue)
        } header: {
            Text("Statistics")
        } footer: {
@@ -54,10 +54,14 @@ extension SettingsView {
    // MARK: - Statistics

    static var statisticsFooter: String {
-        let base = "Shows resolution, frame rate, throughput and latency in the chosen "
-            + "corner while streaming."
-        #if os(macOS) || os(iOS)
-        return base + " Toggle it any time with ⌃⌥⇧S."
+        let base = "Shows streaming statistics in the chosen corner — Compact is a one-line "
+            + "pill, Normal adds resolution and latency, Detailed adds the latency stage "
+            + "breakdown."
+        #if os(macOS)
+        return base + " ⌃⌥⇧S cycles Off → Compact → Normal → Detailed any time."
+        #elseif os(iOS)
+        return base + " ⌃⌥⇧S or a three-finger tap cycles Off → Compact → Normal → Detailed "
+            + "any time."
        #else
        return base
        #endif
@@ -38,7 +38,9 @@ struct SettingsView: View {
    @AppStorage(DefaultsKey.micEnabled) var micEnabled = true
    @AppStorage(DefaultsKey.audioChannels) var audioChannels = 2
    @AppStorage(DefaultsKey.codec) var codec = "auto"
-    @AppStorage(DefaultsKey.hudEnabled) var hudEnabled = true
+    // The overlay tier's raw string (the pickers tag by rawValue); the absent-key default runs
+    // the legacy-hudEnabled migration (same pattern as ContentView/StreamCommands).
+    @AppStorage(DefaultsKey.statsVerbosity) var statsVerbosityRaw = StatsVerbosity.current.rawValue
    @AppStorage(DefaultsKey.hudPlacement) var hudPlacement = HUDPlacement.topTrailing.rawValue
    @ObservedObject var gamepads = GamepadManager.shared
    #if !os(tvOS)
@@ -294,10 +296,6 @@ struct SettingsView: View {
            })
    }

-    private var hudEnabledTag: Binding<String> {
-        Binding(get: { hudEnabled ? "on" : "off" }, set: { hudEnabled = $0 == "on" })
-    }
-
    private var hdrEnabledTag: Binding<String> {
        Binding(get: { hdrEnabled ? "on" : "off" }, set: { hdrEnabled = $0 == "on" })
    }
@@ -352,7 +350,7 @@ struct SettingsView: View {
                    .padding(.top, 8)
                TVSelectionRow(
                    title: "Statistics overlay",
-                    options: [("On", "on"), ("Off", "off")], selection: hudEnabledTag)
+                    options: SettingsOptions.statsVerbosities, selection: $statsVerbosityRaw)
                TVSelectionRow(
                    title: "Statistics position", options: SettingsOptions.hudPlacements,
                    selection: $hudPlacement)