feat(apple): stage-3 presenter — glass-gated present pacing as a live A/B

Stage-2's present-on-arrival saturates CAMetalLayer's FIFO image queue
whenever the stream rate runs at the panel's refresh (iOS always
vsync-latches; the macOS 26 compositor latch-paces our out-of-band
presents the same way): one early burst fills the queue to
maximumDrawableCount and — arrivals then matching latches one-for-one —
it never drains. That sticky depth is the measured 29-30 ms display
stage on the 120 Hz ProMotion devices, and the full-queue regime is
where host<->panel clock drift turns into the reported fixed-interval
repeats/drops. The 240 Hz Studio never saturates, which is why it never
showed either symptom.

Stage-3 is the same pipeline with a PresentGate: at most ONE
presented-but-undisplayed drawable in flight; the drawable's presented
handler reopens the gate and re-signals the render thread, so the next
present always takes the freshest newest-wins ring frame — the hidden
queue latency becomes explicit, correct frame drops. A 100 ms stale
fallback force-opens a gate whose handler never fires (the "presents
aren't damage" hazard class) so a pathological system degrades visibly
instead of freezing; the PUNKTFUNK_PRESENT_DEBUG `forced` counter
exposes it (0 on healthy systems).

Selection: the Settings > Display presenter picker now ships in release
builds (stage 2 default / stage 3 experimental; the freeze-prone
stage-1 diagnostic stays DEBUG-only), resolved per session with a
PUNKTFUNK_PRESENTER=stage1|stage2|stage3 env override for CLI A/B. The
pf-present debug line gains gated/forced/inflightMax — inflightMax is
the direct image-queue-depth measurement for the A/B.

Live-verified both ways against a real host at 1080p120: stage-3 holds
120/120 fps with inflightMax=1, forced=0, glass deltas p50 8.33 ms;
stage-2 is behaviorally unchanged (120/120 fps, inflightMax=2 even on
the wired 240 Hz setup — the saturation signal in miniature). Unit
tests cover the gate (one-in-flight, stale force-open, idempotent
release) and the presenter resolution (env override, release stage-1
gating); macOS tests green, iOS/tvOS xcodebuild clean.

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

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

@@ -337,28 +337,32 @@ extension SettingsView {
         #endif
     }
 
-    // Stage-2 (Metal/VTDecompressionSession) is the default and only user-visible presenter — it
-    // recovers from a wedged decoder, where stage-1's AVSampleBufferDisplayLayer freezes hard on a
-    // lost HEVC reference. Stage-1 is kept reachable as a DEBUG-only override for diagnostics, like
-    // the controller test. Empty in release builds (no presenter UI; stage-2 always).
+    // Stage-2 (Metal/VTDecompressionSession, present on frame arrival) is the proven default;
+    // stage-3 is the same pipeline with glass-gated present pacing — a user-visible A/B while the
+    // pacing work settles (see Stage2Pipeline's PresentPacing for the queue-saturation rationale).
+    // 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 {
-        #if DEBUG
         Section {
             Picker("Presenter", selection: $presenter) {
                 Text("Stage 2 (default)").tag("stage2")
+                Text("Stage 3 (experimental)").tag("stage3")
+                #if DEBUG
                 Text("Stage 1 (debug)").tag("stage1")
+                #endif
             }
         } header: {
-            Text("Video presenter · debug")
+            Text("Video presenter")
         } footer: {
-            Text("Stage 2 (default): explicit decode + Metal present — full HUD latency "
-                + "breakdown and self-recovery from decode stalls. Stage 1: compressed video "
-                + "straight to the system layer; freezes on a lost HEVC reference, so it's a "
-                + "debug fallback only. Applies from the next session.")
+            Text("Stage 2: each frame is shown the moment it's decoded — proven, 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 are paced "
+                + "to the display — at most one undisplayed frame in flight, always the freshest, "
+                + "dropping late frames instead of queueing them. Watch the statistics overlay's "
+                + "display time to compare. Applies from the next session.")
                 .font(.geist(12, relativeTo: .caption))
                 .foregroundStyle(.secondary)
         }
-        #endif
     }
 
     @ViewBuilder var hdrSection: some View {