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/PunktfunkKit/Video/SessionPresenter.swift

@@ -22,6 +22,30 @@ public final class DisplayLinkProxy: NSObject {
     @objc public func tick(_ link: CADisplayLink) { onTick(link) }
 }
 
+/// Which presenter a session runs. Stage-2/stage-3 are the same Metal pipeline with arrival vs
+/// glass-gated present pacing (`PresentPacing` — see Stage2Pipeline for the tradeoff, and why
+/// stage-3 exists: stage-2's present-on-arrival saturates the layer's FIFO image queue on panels
+/// running near the stream rate). Stage-1 (compressed video straight to the system layer) is a
+/// DEBUG-only diagnostic. Internal (not private) for unit tests.
+enum PresenterChoice: Equatable {
+    case stage1
+    case stage2
+    case stage3
+
+    /// Resolve from the `PUNKTFUNK_PRESENTER` env override (A/B without touching settings) first,
+    /// then the persisted `DefaultsKey.presenter` setting; anything unknown (or an empty env var)
+    /// falls back to stage-2. `allowStage1` is false in release builds, where a leftover DEBUG
+    /// "stage1" value silently maps to stage-2 rather than reviving the freeze-prone fallback.
+    static func resolve(setting: String?, env: String?, allowStage1: Bool) -> PresenterChoice {
+        let raw = env.flatMap { $0.isEmpty ? nil : $0 } ?? setting
+        switch raw {
+        case "stage1": return allowStage1 ? .stage1 : .stage2
+        case "stage3": return .stage3
+        default: return .stage2
+        }
+    }
+}
+
 final class SessionPresenter {
     private var pump: StreamPump?
     private var stage2: Stage2Pipeline?
@@ -50,18 +74,24 @@ final class SessionPresenter {
 
         // Presenter choice — stage-2 is the DEFAULT (explicit VTDecompressionSession decode + a
         // CAMetalLayer/display-link present): it can detect + recover a wedged decoder where
-        // stage-1's AVSampleBufferDisplayLayer freezes hard on a lost HEVC reference. Stage-1 is
-        // reachable only via the DEBUG presenter toggle; release always takes stage-2 (the stage-1
-        // pump below stays the automatic fallback if Metal is missing).
+        // stage-1's AVSampleBufferDisplayLayer freezes hard on a lost HEVC reference. Stage-3 is
+        // the same pipeline with glass-gated present pacing (the settings picker's live A/B — see
+        // PresentPacing). Stage-1 is reachable only via the DEBUG presenter value; release maps it
+        // back to stage-2 (the stage-1 pump below stays the automatic fallback if Metal is missing).
         #if DEBUG
-        let forceStage1 = UserDefaults.standard.string(forKey: DefaultsKey.presenter) == "stage1"
+        let allowStage1 = true
         #else
-        let forceStage1 = false
+        let allowStage1 = false
         #endif
-        if !forceStage1,
+        let choice = PresenterChoice.resolve(
+            setting: UserDefaults.standard.string(forKey: DefaultsKey.presenter),
+            env: ProcessInfo.processInfo.environment["PUNKTFUNK_PRESENTER"],
+            allowStage1: allowStage1)
+        if choice != .stage1,
            let pipeline = Stage2Pipeline(
                endToEndMeter: endToEndMeter, decodeMeter: decodeMeter,
-               displayMeter: displayMeter) {
+               displayMeter: displayMeter,
+               pacing: choice == .stage3 ? .glass : .arrival) {
             let metal = pipeline.layer
             // The opaque metal layer composites OVER the AVSampleBufferDisplayLayer base, which
             // sits idle (un-enqueued) in stage-2. contentsScale + frame are set in layout().