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>

clients/apple/Sources/PunktfunkClient/ContentView.swift

@@ -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)

clients/apple/Sources/PunktfunkClient/Session/StreamCommands.swift

@@ -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

clients/apple/Sources/PunktfunkClient/Session/StreamHUDView.swift

@@ -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)

clients/apple/Sources/PunktfunkClient/Settings/GamepadSettingsView.swift

@@ -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.",

clients/apple/Sources/PunktfunkClient/Settings/SettingsOptions.swift

@@ -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

clients/apple/Sources/PunktfunkClient/Settings/SettingsView+Sections.swift

@@ -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: {

clients/apple/Sources/PunktfunkClient/Settings/SettingsView+Support.swift

@@ -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

clients/apple/Sources/PunktfunkClient/Settings/SettingsView.swift

@@ -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)

clients/apple/Sources/PunktfunkKit/Input/InputCapture.swift

@@ -113,11 +113,11 @@ public final class InputCapture {
     /// keyDown monitor only WHILE FORWARDING — that's the state in which the app's menu (which
     /// carries the same key equivalents for discoverability) can't see them, so the monitor is the
     /// captured-state delivery path; released, the events pass through and the menu handles them.
-    /// ⌃⌥⇧Q releases the captured mouse/keyboard; ⌃⌥⇧D disconnects; ⌃⌥⇧S toggles the stats
-    /// overlay. Main queue.
+    /// ⌃⌥⇧Q releases the captured mouse/keyboard; ⌃⌥⇧D disconnects; ⌃⌥⇧S cycles the stats
+    /// overlay tier (off → compact → normal → detailed). Main queue.
     public var onReleaseCapture: (() -> Void)?
     public var onDisconnect: (() -> Void)?
-    public var onToggleStats: (() -> Void)?
+    public var onCycleStats: (() -> Void)?
 
     /// Fired when a newer InputCapture takes the process-global GC handler slots (the
     /// singletons hold ONE handler each): the preempted owner must drop its capture
@@ -246,7 +246,7 @@ public final class InputCapture {
                     return nil
                 case 1 /* S */:
                     self.suppressedVK = 0x53
-                    self.onToggleStats?()
+                    self.onCycleStats?()
                     return nil
                 default:
                     break

clients/apple/Sources/PunktfunkKit/Input/TouchMouse.swift

@@ -2,7 +2,8 @@
 // touch gesture model (clients/android .../TouchInput.kt) so the two touch clients feel
 // identical. Two mouse modes share one gesture vocabulary — tap = left click · two-finger
 // tap = right click · two-finger drag = scroll · tap-then-press-and-drag = held left drag
-// (text selection / window moves) · three-finger tap = stats-HUD toggle:
+// (text selection / window moves) · three-finger tap = cycles the stats overlay tiers
+// (off → compact → normal → detailed, matching Android):
 //
 //  * trackpad (default): the cursor STAYS PUT on touch-down and moves by the finger's
 //    relative delta with mild acceleration — swipe to nudge, lift and re-swipe to walk it
@@ -164,7 +165,7 @@ final class TouchMouse {
         } else if !moved {
             switch maxFingers {
             case 3...:
-                Self.toggleHUD() // in-stream stats-overlay toggle, same as Android
+                Self.cycleStats() // in-stream stats-tier cycle, same as Android
             case 2: // two-finger tap → right click
                 send?(.mouseButton(Button.right, down: true))
                 send?(.mouseButton(Button.right, down: false))
@@ -274,12 +275,11 @@ final class TouchMouse {
         }
     }
 
-    /// Three-finger tap toggles the stats overlay — through the shared `hudEnabled` default,
-    /// which the app's HUD views observe via @AppStorage (so this needs no wiring to them).
-    private static func toggleHUD() {
-        let defaults = UserDefaults.standard
-        let on = defaults.object(forKey: DefaultsKey.hudEnabled) as? Bool ?? true
-        defaults.set(!on, forKey: DefaultsKey.hudEnabled)
+    /// Three-finger tap cycles the stats overlay tiers (off → compact → normal → detailed) —
+    /// through the shared `statsVerbosity` default, which the app's HUD views observe via
+    /// @AppStorage (so this needs no wiring to them). Same cycle as Android's triple-tap.
+    private static func cycleStats() {
+        StatsVerbosity.store(StatsVerbosity.current.next())
     }
 }
 #endif

clients/apple/Sources/PunktfunkKit/Support/DefaultsKeys.swift

@@ -67,9 +67,15 @@ public enum DefaultsKey {
     public static let libraryEnabled = "punktfunk.libraryEnabled"
     /// macOS: take the window fullscreen while streaming and restore it on the host list. On by default.
     public static let fullscreenWhileStreaming = "punktfunk.fullscreenWhileStreaming"
-    /// Show the streaming statistics overlay (mode/fps/throughput/latency). On by default; toggle
-    /// while streaming with ⌃⌥⇧S (the cross-client Ctrl+Alt+Shift+S; macOS / hardware keyboard).
+    /// LEGACY (pre-tiered overlay): the old boolean stats-overlay toggle. Kept ONLY as the
+    /// migration fallback `StatsVerbosity.current` reads when `statsVerbosity` was never
+    /// written (absent-or-true → .normal, explicit false → .off). Never written anymore.
     public static let hudEnabled = "punktfunk.hudEnabled"
+    /// The statistics overlay tier — a `StatsVerbosity` raw value ("off"/"compact"/"normal"/
+    /// "detailed"). Absent → migrated from the legacy `hudEnabled` bool (see above). Cycle it
+    /// while streaming with ⌃⌥⇧S (the cross-client Ctrl+Alt+Shift+S; macOS / hardware
+    /// keyboard) or a three-finger tap (touch), matching the Android client.
+    public static let statsVerbosity = "punktfunk.statsVerbosity"
     /// Which corner the statistics overlay sits in — a `HUDPlacement` raw value
     /// ("topLeading"/"topTrailing"/"bottomLeading"/"bottomTrailing"). Default top-trailing.
     public static let hudPlacement = "punktfunk.hudPlacement"

clients/apple/Sources/PunktfunkKit/Support/StatsVerbosity.swift

@@ -0,0 +1,58 @@
+// The stats overlay's verbosity tier — a port of the Android client's 3-tier overlay semantics
+// so the two clients feel identical: Off → Compact (one-line pill) → Normal (headline stats) →
+// Detailed (plus the latency stage equation). Persisted under `DefaultsKey.statsVerbosity`;
+// the in-stream cycle surfaces (⌃⌥⇧S, the three-finger tap) advance it with
+// `store(current.next())`, and every UI reader observes the same default via @AppStorage.
+//
+// Lives in PunktfunkKit (not the app) because the kit's input paths (TouchMouse's three-finger
+// tap, InputCapture's captured-state ⌃⌥⇧S) cycle it directly.
+
+import Foundation
+
+/// How much of the streaming statistics overlay to show. The raw values are stable on disk —
+/// rename the cases freely, never the strings.
+public enum StatsVerbosity: String, CaseIterable, Sendable {
+    case off, compact, normal, detailed
+
+    /// User-facing tier label (Settings pickers, the gamepad settings row).
+    public var label: String {
+        switch self {
+        case .off: return "Off"
+        case .compact: return "Compact"
+        case .normal: return "Normal"
+        case .detailed: return "Detailed"
+        }
+    }
+
+    /// The next tier in the cycle: off → compact → normal → detailed → off (wrapping) —
+    /// the ⌃⌥⇧S / three-finger-tap order, same as Android.
+    public func next() -> StatsVerbosity {
+        switch self {
+        case .off: return .compact
+        case .compact: return .normal
+        case .normal: return .detailed
+        case .detailed: return .off
+        }
+    }
+
+    /// The persisted tier. When `statsVerbosity` has never been written, migrates from the
+    /// legacy `hudEnabled` bool the pre-tiered clients stored: absent-or-true → `.normal`
+    /// (the old "on" look minus the equation lines), explicit false → `.off`.
+    public static var current: StatsVerbosity {
+        let defaults = UserDefaults.standard
+        if let raw = defaults.string(forKey: DefaultsKey.statsVerbosity),
+           let tier = StatsVerbosity(rawValue: raw) {
+            return tier
+        }
+        if let legacy = defaults.object(forKey: DefaultsKey.hudEnabled) as? Bool, !legacy {
+            return .off
+        }
+        return .normal
+    }
+
+    /// Persist a tier (the cycle surfaces write through here; the Settings pickers write the
+    /// same key via @AppStorage).
+    public static func store(_ tier: StatsVerbosity) {
+        UserDefaults.standard.set(tier.rawValue, forKey: DefaultsKey.statsVerbosity)
+    }
+}

clients/apple/Sources/PunktfunkKit/Views/StreamView.swift

@@ -594,13 +594,12 @@ public final class StreamLayerView: NSView {
             guard let self, self.window?.isKeyWindow == true else { return }
             self.onDisconnectRequest?()
         }
-        capture.onToggleStats = { [weak self] in
+        capture.onCycleStats = { [weak self] in
             guard self?.window?.isKeyWindow == true else { return }
-            // Flip the shared setting directly — every @AppStorage reader (the HUD's visibility,
-            // the menu item's title) observes UserDefaults, so this is the same as the menu path.
-            let defaults = UserDefaults.standard
-            let current = defaults.object(forKey: DefaultsKey.hudEnabled) as? Bool ?? true
-            defaults.set(!current, forKey: DefaultsKey.hudEnabled)
+            // Advance the shared tier setting directly — every @AppStorage reader (the HUD's
+            // visibility/content, the Settings pickers) observes UserDefaults, so this is the
+            // same as the menu path.
+            StatsVerbosity.store(StatsVerbosity.current.next())
         }
         capture.start()
         inputCapture = capture