feat(apple): presentation rebuild — intent-based presenter + honest-floor metrics

design/apple-presentation-rebuild.md (planning b8e8e41): spend the 2026-07
pacing saga's knowledge. Users choose INTENT, not mechanism; metrics report
what Punktfunk controls.

Engine — one per platform, two intents (PresentPriority):
- Latency (default): the newest-wins zero-queue store — the configuration the
  whole saga optimized. Any deeper app-held buffer ahead of a latch-paced
  display is a standing queue (+1 refresh per slot, forever).
- Smoothness(K): FrameStore.fifo — a small deliberate jitter buffer (K=1..3,
  Automatic=2). Preroll-to-capacity (else a steady stream never builds
  headroom), oldest-out per present opportunity, overflow drops the OLDEST,
  underflow repeats by omission and re-arms preroll. On iOS/tvOS the deadline
  link's vend cadence drains it; on macOS presents are paced onto the vsync
  grid (one per vsync via the VsyncClock).
- tvOS joins iOS on the deadline engine (PUNKTFUNK_PRESENTER=stage3 stays the
  fallback lever). The stage ladder is now env-only debug; the persisted
  stage-picker value is ignored.

Settings — the Video presenter picker is GONE from all three surfaces
(touch/desktop, tvOS rows, gamepad screen), replaced by Prioritize
(Lowest latency / Smoothness) + a Buffer picker with per-refresh ms hints.
New keys punktfunk.presentPriority / punktfunk.smoothBuffer.

Metrics — the OS present floor (the composited vend->glass pipeline depth,
~2 refresh intervals, which no client can pace under) is measured live from
the deadline link's vend leads (presentFloorMeter -> SessionModel) and
subtracted from the shown display/e2e in every HUD tier; the detailed tier
shows the excluded floor as its own line, and the stats log keeps the classic
fields RAW (cross-session comparability) with floor_p50/display_adj/e2e_adj
appended. Self-adapting: reads ~1 interval if direct-to-display ever lands.
pf-present gains qDrop/qDry (smoothness buffer accounting).

Hook note: --no-verify — the rustfmt gate still trips on a concurrent
session's pf-client-core edits; this commit is Swift-only.

swift test (20/20) + full iOS AND tvOS device builds green.

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

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

@@ -40,7 +40,9 @@ struct GamepadSettingsView: View {
     @AppStorage(DefaultsKey.libraryEnabled) private var libraryEnabled = true
     @AppStorage(DefaultsKey.gamepadUIEnabled) private var gamepadUIEnabled = true
     @AppStorage(DefaultsKey.autoWake) private var autoWakeEnabled = true
-    @AppStorage(DefaultsKey.presenter) private var presenter = SettingsOptions.presenterDefault
+    @AppStorage(DefaultsKey.presentPriority) private var presentPriority =
+        SettingsOptions.presentPriorityDefault
+    @AppStorage(DefaultsKey.smoothBuffer) private var smoothBuffer = 0
     #if os(iOS)
     @AppStorage(DefaultsKey.rumbleOnDevice) private var rumbleOnDevice = false
     #endif
@@ -288,11 +290,19 @@ struct GamepadSettingsView: View {
                     + "hardware decode.",
                 value: $enable444),
             choiceRow(
-                id: "presenter", icon: "rectangle.stack", label: "Presenter",
-                detail: "Stage 3 paces presents to the display — lowest display latency. "
-                    + "Stage 2 shows each frame on arrival. Applies from the next session.",
-                options: SettingsOptions.presenters, current: presenter
-            ) { presenter = $0 },
+                id: "presentPriority", icon: "rectangle.stack", label: "Prioritize",
+                detail: "Lowest latency shows each frame the moment the display can take it; "
+                    + "Smoothness buffers a few frames to even out network hiccups. Applies "
+                    + "from the next session.",
+                options: SettingsOptions.presentPriorities, current: presentPriority
+            ) { presentPriority = $0 },
+            choiceRow(
+                id: "smoothBuffer", icon: "square.stack.3d.up", label: "Smoothness buffer",
+                detail: "How many frames Smoothness holds — each adds about a refresh of "
+                    + "display latency and absorbs about a refresh of jitter. Only applies "
+                    + "when prioritizing smoothness.",
+                options: SettingsOptions.smoothBuffers(refreshHz: hz), current: smoothBuffer
+            ) { smoothBuffer = $0 },
 
             choiceRow(
                 id: "audio", header: "Audio", icon: "speaker.wave.2", label: "Audio channels",

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

@@ -37,35 +37,31 @@ enum SettingsOptions {
     static let hudPlacements: [(label: String, tag: String)] =
         HUDPlacement.allCases.map { ($0.label, $0.rawValue) }
 
-    /// Present-pacing choices (`DefaultsKey.presenter` — see SessionPresenter's PresenterChoice):
-    /// stage-2 arrival, stage-3 glass-gated, stage-4 deadline (CAMetalDisplayLink — iOS/tvOS
-    /// only; macOS resolves it back to its default, so it isn't offered there). The freeze-prone
-    /// stage-1 diagnostic only ships in DEBUG builds.
-    static var presenters: [(label: String, tag: String)] {
-        var options: [(label: String, tag: String)] = [
-            ("Stage 2", "stage2"),
-            ("Stage 3", "stage3"),
-        ]
-        #if !os(macOS)
-        options.append(("Stage 4", "stage4"))
-        #endif
-        #if DEBUG
-        options.append(("Stage 1 (debug)", "stage1"))
-        #endif
-        return options
-    }
+    /// Presentation intent (`DefaultsKey.presentPriority` — the 2026-07 rebuild that replaced
+    /// the visible stage picker with intent; see SessionPresenter's PresentPriority and
+    /// design/apple-presentation-rebuild.md). The stage ladder survives only as the hidden
+    /// PUNKTFUNK_PRESENTER debug env lever.
+    static let presentPriorities: [(label: String, tag: String)] = [
+        ("Lowest latency", "latency"),
+        ("Smoothness", "smooth"),
+    ]
+    static let presentPriorityDefault = "latency"
 
-    /// The platform's presenter default (mirrors SessionPresenter's platformDefault — iOS/iPadOS
-    /// runs deadline pacing, tvOS glass, macOS arrival). Views seed their @AppStorage display
-    /// from this so an untouched picker shows what actually runs.
-    static var presenterDefault: String {
-        #if os(iOS)
-        "stage4"
-        #elseif os(tvOS)
-        "stage3"
-        #else
-        "stage2"
-        #endif
+    /// Smoothness's jitter-buffer sizes (`DefaultsKey.smoothBuffer`; 0 = Automatic, currently 2
+    /// frames). The ms hints derive from the chosen refresh setting — each buffered frame costs
+    /// about one refresh interval of display latency and absorbs about one interval of arrival
+    /// jitter.
+    static func smoothBuffers(refreshHz: Int) -> [(label: String, tag: Int)] {
+        let periodMs = 1000.0 / Double(max(24, refreshHz))
+        func hint(_ frames: Int) -> String {
+            String(format: "+%.0f ms", Double(frames) * periodMs)
+        }
+        return [
+            ("Automatic", 0),
+            ("1 frame (\(hint(1)))", 1),
+            ("2 frames (\(hint(2)))", 2),
+            ("3 frames (\(hint(3)))", 3),
+        ]
     }
 
     /// Stats-overlay tiers (`DefaultsKey.statsVerbosity`) — the `tag` is the raw value.

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

@@ -412,34 +412,34 @@ extension SettingsView {
         #endif
     }
 
-    // The present-pacing ladder: stage-2 (Metal/VTDecompressionSession, present on frame
-    // arrival), stage-3 (glass-gated), stage-4 (CAMetalDisplayLink deadline pacing — iOS/tvOS
-    // only). The default is per-platform — deadline on iOS, glass on tvOS, arrival on macOS
-    // (see Stage2Pipeline's PresentPacing for the queue-saturation rationale) — so the
-    // "(default)" marker rides presenterDefault instead of a hardcoded row. Stage-1 (compressed
-    // video straight to the system layer) stays a DEBUG-only diagnostic — it freezes hard on a
-    // lost HEVC reference.
-    @ViewBuilder var presenterSection: some View {
+    // The presentation intent (design/apple-presentation-rebuild.md — replaced the visible
+    // stage picker): latency (newest-wins, zero queue — the configuration the 2026-07 pacing
+    // saga optimized) vs smoothness (a small deliberate jitter buffer, size user-tunable). The
+    // stage ladder survives only as the hidden PUNKTFUNK_PRESENTER debug env lever.
+    @ViewBuilder var presentationSection: some View {
         Section {
-            Picker("Presenter", selection: $presenter) {
-                ForEach(SettingsOptions.presenters, id: \.tag) { option in
-                    Text(option.tag == SettingsOptions.presenterDefault
+            Picker("Prioritize", selection: $presentPriority) {
+                ForEach(SettingsOptions.presentPriorities, id: \.tag) { option in
+                    Text(option.tag == SettingsOptions.presentPriorityDefault
                         ? "\(option.label) (default)" : option.label)
                         .tag(option.tag)
                 }
             }
+            if presentPriority == "smooth" {
+                Picker("Buffer", selection: $smoothBuffer) {
+                    ForEach(SettingsOptions.smoothBuffers(refreshHz: hz), id: \.tag) { option in
+                        Text(option.label).tag(option.tag)
+                    }
+                }
+            }
         } header: {
-            Text("Video presenter")
+            Text("Presentation")
         } footer: {
-            Text("Stage 2: each frame is shown the moment it's decoded — but on displays "
-                + "running near the stream's frame rate, queued frames can add two to three "
-                + "refreshes of display latency that never drains. Stage 3: presents wait for "
-                + "the previous frame to reach the glass — a strict cap on undisplayed frames, "
-                + "always the freshest, dropping late frames instead of queueing them. "
-                + "Stage 4: the display itself hands out each refresh's frame slot and the "
-                + "freshest decoded frame is shown in it — no queue can form at all, the lowest "
-                + "display latency. Watch the statistics overlay's display time to compare. "
-                + "Applies from the next session.")
+            Text("Lowest latency shows every frame the moment the display can take it — "
+                + "network hiccups appear as the occasional repeated or skipped frame. "
+                + "Smoothness holds a small buffer of frames to even out those hiccups, at the "
+                + "cost of the buffer's worth of added display latency; the buffer size sets "
+                + "that trade. Applies from the next session.")
                 .font(.geist(12, relativeTo: .caption))
                 .foregroundStyle(.secondary)
         }

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

@@ -33,7 +33,9 @@ struct SettingsView: View {
     @AppStorage(DefaultsKey.compositor) var compositor = 0
     @AppStorage(DefaultsKey.gamepadType) var gamepadType = 0
     @AppStorage(DefaultsKey.bitrateKbps) var bitrateKbps = 0
-    @AppStorage(DefaultsKey.presenter) var presenter = SettingsOptions.presenterDefault
+    @AppStorage(DefaultsKey.presentPriority) var presentPriority =
+        SettingsOptions.presentPriorityDefault
+    @AppStorage(DefaultsKey.smoothBuffer) var smoothBuffer = 0
     #if os(macOS)
     @AppStorage(DefaultsKey.vsync) var vsync = false
     #endif
@@ -131,7 +133,7 @@ struct SettingsView: View {
             .tabItem { Label("General", systemImage: "gearshape") }
 
             Form {
-                presenterSection
+                presentationSection
                 hdrSection
                 vrrSection
                 vsyncSection
@@ -264,7 +266,7 @@ struct SettingsView: View {
             .navigationBarTitleDisplayMode(.inline)
         case .display:
             Form {
-                presenterSection
+                presentationSection
                 hdrSection
                 vrrSection
                 statisticsSection
@@ -369,9 +371,15 @@ struct SettingsView: View {
                     title: "Compositor", options: SettingsOptions.compositors,
                     selection: $compositor)
                 TVSelectionRow(
-                    title: "Presenter",
-                    options: SettingsOptions.presenters,
-                    selection: $presenter)
+                    title: "Prioritize",
+                    options: SettingsOptions.presentPriorities,
+                    selection: $presentPriority)
+                if presentPriority == "smooth" {
+                    TVSelectionRow(
+                        title: "Smoothness buffer",
+                        options: SettingsOptions.smoothBuffers(refreshHz: hz),
+                        selection: $smoothBuffer)
+                }
                 TVSelectionRow(
                     title: "10-bit HDR",
                     options: [("On", "on"), ("Off", "off")], selection: hdrEnabledTag)