fix(apple): default iOS to glass-gated present pacing with a depth-2 gate — the 23 ms display-stage fix

Field report (iPad Pro 13" M4, 2752x2064@120): display 23.1 ms on the default
arrival pacing vs 14 ms glass-gated, dominating an otherwise ~14 ms pipeline.
On iOS the layer ALWAYS vsync-latches (displaySyncEnabled is macOS-only API)
and default-on VRR steers the panel to the stream rate, so arrival pacing's
sticky-FIFO saturation (~2-3 refreshes of queue) is the common case, not the
corner — the exact regime that made tvOS default to glass.

- PresenterChoice.platformDefault -> stage3 on iOS/iPadOS (joins tvOS);
  explicit stage-2 stays the honest arrival A/B; macOS unchanged.
- PresentGate generalized to a capacity: depth 1 is bit-identical to before;
  iOS runs depth 2 (one flip scanning out + one queued for the next latch),
  so a decoded frame presents immediately and latches the very next vsync
  instead of serializing on the previous flip's on-glass callback — expected
  ~5-8 ms at 120 Hz. tvOS keeps depth 1 (proven; A/B first), macOS is pinned
  to 1 (glass there is the DCP swapID-panic mitigation — serialization is
  its point). PUNKTFUNK_GATE_DEPTH (1-3) is the on-device A/B lever.
- Settings picker derives its "(default)" marker from presenterDefault
  instead of hardcoding stage-2 as default / stage-3 as experimental.

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

clients/apple/Tests/PunktfunkKitTests/PresentPacingTests.swift

@@ -4,13 +4,14 @@ import XCTest
 import QuartzCore
 @testable import PunktfunkKit
 
-/// Stage-3 present pacing: the one-in-flight `PresentGate` and the stage-1/2/3 `PresenterChoice`
-/// resolution (setting + PUNKTFUNK_PRESENTER env override + the release-build stage-1 gate).
+/// Stage-3 present pacing: the bounded in-flight `PresentGate` (depth 1 + depth 2), the
+/// stage-1/2/3 `PresenterChoice` resolution (setting + PUNKTFUNK_PRESENTER env override + the
+/// release-build stage-1 gate), and the per-platform glass-gate depth.
 final class PresentPacingTests: XCTestCase {
     // MARK: - PresentGate
 
-    /// The core invariant: one present in flight. A second acquire while pending must fail (the
-    /// frame stays in the ring for the presented handler's re-signal); release reopens.
+    /// The depth-1 invariant: one present in flight. A second acquire while pending must fail
+    /// (the frame stays in the ring for the presented handler's re-signal); release reopens.
     func testGateAdmitsOneInFlightPresent() {
         let gate = PresentGate()
         XCTAssertTrue(gate.tryAcquire(now: 0), "an idle gate must admit the first present")
@@ -20,6 +21,32 @@ final class PresentPacingTests: XCTestCase {
         XCTAssertEqual(gate.drainForced(), 0, "no stale present was force-cleared")
     }
 
+    /// Depth 2 (the iOS default): a second present may queue behind the flip scanning out — the
+    /// bound only bites at the THIRD. One release (a glass callback) reopens exactly one slot.
+    func testGateDepthTwoAdmitsTwoInFlightPresents() {
+        let gate = PresentGate(capacity: 2)
+        XCTAssertTrue(gate.tryAcquire(now: 0))
+        XCTAssertTrue(gate.tryAcquire(now: 0.001), "depth 2 must admit a queued second flip")
+        XCTAssertFalse(gate.tryAcquire(now: 0.002), "the third present must wait for glass")
+        gate.release()
+        XCTAssertTrue(gate.tryAcquire(now: 0.003), "one glass callback frees one slot")
+        XCTAssertFalse(gate.tryAcquire(now: 0.004))
+        XCTAssertEqual(gate.drainForced(), 0)
+    }
+
+    /// Depth 2 staleness anchors to the OLDEST in-flight present: a full gate stays closed while
+    /// the oldest is live, force-opens once it ages out, and the younger present keeps its slot.
+    func testGateDepthTwoForceOpensOnTheOldestStalePresent() {
+        let gate = PresentGate(capacity: 2)
+        XCTAssertTrue(gate.tryAcquire(now: 10))
+        XCTAssertTrue(gate.tryAcquire(now: 10.05))
+        XCTAssertFalse(gate.tryAcquire(now: 10 + PresentGate.staleAfter - 0.01))
+        XCTAssertTrue(gate.tryAcquire(now: 10 + PresentGate.staleAfter + 0.01))
+        XCTAssertEqual(gate.drainForced(), 1)
+        // The 10.05 present is still live, so the gate is full again right after the force-open.
+        XCTAssertFalse(gate.tryAcquire(now: 10 + PresentGate.staleAfter + 0.02))
+    }
+
     /// The lost-handler insurance: a present whose handler never fires (the macOS "presents
     /// aren't damage" hazard class) must not freeze the stream — past `staleAfter` the gate
     /// force-opens and counts the event for the PUNKTFUNK_PRESENT_DEBUG `forced` stat.
@@ -47,11 +74,21 @@ final class PresentPacingTests: XCTestCase {
 
     // MARK: - PresenterChoice
 
-    func testPresenterChoiceDefaultsToStage2() {
+    /// The platform default: glass-paced stage-3 where the layer always vsync-latches (iOS,
+    /// tvOS — arrival pacing saturates the FIFO image queue there), arrival stage-2 on macOS
+    /// (sync-off presents don't queue). No selection / garbage falls back to it.
+    func testPresenterChoiceFallsBackToPlatformDefault() {
+        #if os(macOS)
+        XCTAssertEqual(PresenterChoice.platformDefault, .stage2)
+        #else
+        XCTAssertEqual(PresenterChoice.platformDefault, .stage3)
+        #endif
         XCTAssertEqual(
-            PresenterChoice.resolve(setting: nil, env: nil, allowStage1: true), .stage2)
+            PresenterChoice.resolve(setting: nil, env: nil, allowStage1: true),
+            PresenterChoice.platformDefault)
         XCTAssertEqual(
-            PresenterChoice.resolve(setting: "garbage", env: nil, allowStage1: true), .stage2)
+            PresenterChoice.resolve(setting: "garbage", env: nil, allowStage1: true),
+            PresenterChoice.platformDefault)
         XCTAssertEqual(
             PresenterChoice.resolve(setting: "stage2", env: nil, allowStage1: true), .stage2)
     }
@@ -70,14 +107,16 @@ final class PresentPacingTests: XCTestCase {
     }
 
     /// Stage-1 (the freeze-prone system-layer diagnostic) resolves only where allowed (DEBUG
-    /// builds); a leftover "stage1" value in a release build maps back to stage-2.
+    /// builds); a leftover "stage1" value in a release build maps back to the platform default.
     func testPresenterChoiceGatesStage1() {
         XCTAssertEqual(
             PresenterChoice.resolve(setting: "stage1", env: nil, allowStage1: true), .stage1)
         XCTAssertEqual(
-            PresenterChoice.resolve(setting: "stage1", env: nil, allowStage1: false), .stage2)
+            PresenterChoice.resolve(setting: "stage1", env: nil, allowStage1: false),
+            PresenterChoice.platformDefault)
         XCTAssertEqual(
-            PresenterChoice.resolve(setting: nil, env: "stage1", allowStage1: false), .stage2)
+            PresenterChoice.resolve(setting: nil, env: "stage1", allowStage1: false),
+            PresenterChoice.platformDefault)
     }
 
     /// `explicit` is nil exactly when `resolve` would fall back to the platform default — the
@@ -118,5 +157,30 @@ final class PresentPacingTests: XCTestCase {
         XCTAssertEqual(
             SessionPresenter.pacing(for: .stage3, explicit: nil, codec: .pyrowave), .glass)
     }
+
+    // MARK: - Glass-gate depth
+
+    /// The per-platform in-flight present budget: 2 on iOS/iPadOS (one flip scanning out + one
+    /// queued — the display-latency fix), 1 on tvOS (proven config), 1 pinned on macOS (glass
+    /// there is the swapID-panic mitigation — strict serialization is its point, so the env
+    /// lever must not widen it). PUNKTFUNK_GATE_DEPTH A/Bs iOS/tvOS; out-of-range/garbage
+    /// values are ignored.
+    func testGateDepthPlatformDefaultsAndEnvOverride() {
+        #if os(macOS)
+        XCTAssertEqual(SessionPresenter.gateDepth(env: nil), 1)
+        XCTAssertEqual(SessionPresenter.gateDepth(env: "2"), 1, "macOS is pinned to 1")
+        #elseif os(tvOS)
+        XCTAssertEqual(SessionPresenter.gateDepth(env: nil), 1)
+        XCTAssertEqual(SessionPresenter.gateDepth(env: "2"), 2, "the on-device A/B lever")
+        #else
+        XCTAssertEqual(SessionPresenter.gateDepth(env: nil), 2)
+        XCTAssertEqual(SessionPresenter.gateDepth(env: "1"), 1, "the on-device A/B lever")
+        #endif
+        XCTAssertEqual(
+            SessionPresenter.gateDepth(env: "0"), SessionPresenter.gateDepth(env: nil),
+            "out-of-range env values fall back to the platform depth")
+        XCTAssertEqual(
+            SessionPresenter.gateDepth(env: "garbage"), SessionPresenter.gateDepth(env: nil))
+    }
 }
 #endif