feat(client/present): the display stat splits, and the intent reaches the settings UI

WP4 + WP5 of design/desktop-presentation-rebuild.md, on top of the WP1/WP2
engine. The engine shipped with no way to choose it and no way to see what it
cost; this closes both.

WP4 — the display stage splits into `pace` (decoded → present-submit, our own
pipeline) + `latch` (submit → on-glass, the presentation queue and the vblank
wait), off the `submitted_ns` stamp WP2 already carried. That split is what
makes a high `display` self-diagnosing: latch dominating is the vsync floor or
a standing queue, pace dominating is us. A `present:` line joins the Detailed
tier naming the live swapchain mode — the answer to most "why is my latch a
whole refresh" questions, since a MAILBOX request silently lands on FIFO
wherever the driver has no mailbox — plus the engine's counters, rendered only
when they are non-zero so a healthy latency session shows just the mode.

Deviation from the plan: the planned `display_adj` twin is NOT here. It was
specified as `display − latch_p50` for parity with the Apple HUD's shaved
figure, but with a real per-sample `pace` percentile that twin is the same
quantity derived worse (subtracting percentiles). `pace` IS the
Apple-comparable number — Apple subtracts its OS present floor, the latch is
ours — and the user docs now say exactly that.

WP5 — Prioritize + Smoothness buffer on all three surfaces: the GTK dialog (a
new Presentation group on the Display page), the WinUI settings page, and the
console settings screen, which is the ONLY editor reachable in Gaming Mode and
so the one that decides whether Deck users can reach this at all. The buffer
control follows the intent the way echo cancellation follows the mic: hidden on
the desktop shells, dimmed and inert on the console, where a row that vanished
mid-list would shift everything under the cursor.

The V-Sync and VRR rows are deliberately NOT here. Their settings exist and are
profile-routed, but the swapchain does not honour them until WP3, and a toggle
that does nothing is exactly how "Full chroma (4:4:4)" shipped inert on desktop
for three releases after being announced.

Buffer labels carry no millisecond hints (Apple/Android derive them from the
session refresh): under a Native mode the shells do not know the refresh at
settings time, so the captions state the cost as one refresh per frame rather
than a confident wrong number.

Docs: the stats page documents the split and the `present:` line, and stops
claiming Linux/Windows measure to the present instant (untrue since
present_wait); client-settings documents both new rows and drops the stale
claim that the desktop 4:4:4 toggle has no effect (it was wired to
VIDEO_CAP_444); configuration documents PUNKTFUNK_PRESENTER and
PUNKTFUNK_PRESENT_DEBUG.

Gates: punktfunk-rust-ci linux/amd64 — fmt, clippy -D warnings over
pf-client-core, pf-presenter, pf-console-ui, the session binary and the GTK
client, 158 tests. The WinUI leg cannot be reached by any Linux or macOS check,
so it was compiled on the Windows runner .133: clippy -D warnings and tests
both exit 0, against a tree proven by content to contain the edit. ⚠ The first
run there reported a false pass — the script printed its done-marker while the
log carried a test failure (a STATUS_DLL_NOT_FOUND launch failure, ffmpeg's
DLLs missing from PATH); the harness now echoes each phase's exit code so the
verdict is a fact in the log rather than an inference from a marker.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

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

@@ -175,6 +175,46 @@ public final class StreamViewController: StreamViewControllerBase {
     /// renegotiates the host mode (1:1, no presenter resample). iOS only (iPhone naturally no-ops
     /// its fixed full-screen scene; tvOS drives display modes via AVDisplayManager instead).
     private var matchFollower: MatchWindowFollower?
+    // MARK: Escape-drop re-lock
+    //
+    // iPadOS releases the pointer lock BY ITSELF when the user presses Escape — the platform's
+    // built-in "let me out", mirroring the web Pointer Lock API's default unlock gesture. Nothing
+    // in our code does it: a bare Esc never touches `captured`, so it keeps forwarding to the host
+    // as the game key it is. But the lock going away flips the mouse onto the absolute UIKit path
+    // and un-hides the iPadOS cursor, so hitting Esc for an in-game menu silently costs the capture
+    // until the user clicks to win it back. Esc is a GAME key here, not a request to hand the
+    // pointer back to iPadOS, so an unwanted drop is re-requested below. The DELIBERATE releases
+    // (⌘⎋, ⌃⌥⇧Q, the Stream menu, backgrounding) all clear `captured` first, so `wantsPointerLock`
+    // is already false when their drop is observed and none of them are fought here.
+    /// Whether this capture ever actually held the lock. Only a lock we HELD is worth winning back
+    /// — never having been granted one means the scene doesn't qualify, not that Esc took it.
+    /// Cleared when capture ends, so each capture starts from a clean slate.
+    private var pointerLockWasEngaged = false
+    /// Attempts spent in the current re-lock burst, and when the burst began.
+    private var pointerRelockAttempt = 0
+    private var pointerRelockBurstStart: CFTimeInterval = 0
+    /// True from an unwanted drop until the lock is back (or the burst gives up). While pending,
+    /// the local cursor stays hidden and absolute pointer MOTION stays muted, so a re-lock that
+    /// lands a frame or two later is invisible instead of flashing the iPadOS cursor and
+    /// teleporting the host's to the pointer's absolute position.
+    private var pointerRelockPending = false
+    /// Forces `prefersPointerLocked` to report false for one resolve pass, so the escalated attempt
+    /// presents the system with a genuine false→true transition instead of re-asserting a value it
+    /// already holds. See `requestPointerRelock()`.
+    private var pointerLockForcedOff = false
+    /// A burst is 3 attempts, and a burst can't restart inside 2 s. A scene the system will never
+    /// lock (Stage Manager, Split View) therefore costs three cheap re-resolves and then falls back
+    /// to today's click-to-recapture, rather than retrying forever.
+    private static let pointerRelockAttemptLimit = 3
+    private static let pointerRelockBurstWindow: CFTimeInterval = 2
+    /// Gap between attempts in a burst — long enough for the system to answer the previous
+    /// re-resolve, short enough that the whole burst fits in ~0.6 s. Must exceed
+    /// `pointerLockForcedOffHold` so an escalated attempt is back to preferring the lock before the
+    /// next attempt evaluates.
+    private static let pointerRelockRetryDelay: TimeInterval = 0.2
+    /// How long an escalated attempt reports `prefersPointerLocked == false` before flipping back,
+    /// so the system observes a real transition instead of coalescing the flip away.
+    private static let pointerLockForcedOffHold: TimeInterval = 0.05
     #endif
 
     /// Reads whether the scene's pointer is actually locked right now; nil = state
@@ -260,7 +300,7 @@ public final class StreamViewController: StreamViewControllerBase {
         captured && pointerCaptureEnabled && UIDevice.current.userInterfaceIdiom == .pad
     }
 
-    public override var prefersPointerLocked: Bool { wantsPointerLock }
+    public override var prefersPointerLocked: Bool { wantsPointerLock && !pointerLockForcedOff }
     public override var prefersHomeIndicatorAutoHidden: Bool { true }
 
     // NOTE: we deliberately do NOT override `childViewControllerForPointerLock`. The default
@@ -383,6 +423,11 @@ public final class StreamViewController: StreamViewControllerBase {
         // is the exact mirror of the GCMouse handlers, which fire only while locked.
         streamView.onPointerMoveAbs = { [weak self] p in
             guard let self, self.inputCapture?.gcMouseForwarding == false else { return }
+            // A re-lock is in flight after an Esc-drop: the absolute path would teleport the host
+            // cursor to wherever the local pointer sits, undoing the relative aiming we're about to
+            // resume. Motion only — BUTTONS still forward (they carry no position, so a click during
+            // the couple of frames a re-lock takes must not be swallowed mid-firefight).
+            guard !self.pointerRelockPending else { return }
             self.inputCapture?.sendMouseAbs(
                 x: p.x, y: p.y, surfaceWidth: p.w, surfaceHeight: p.h)
         }
@@ -693,6 +738,24 @@ public final class StreamViewController: StreamViewControllerBase {
     /// change and capture toggle. Main queue.
     private func syncPointerLock() {
         let locked = pointerLockEngaged() == true
+        // Wanted, previously HELD, and now gone is the Esc-drop signature. The "previously held"
+        // half matters: a lock that was never granted is a scene that doesn't qualify (Stage
+        // Manager, Split View), and burst-requesting there would hide the cursor for the burst's
+        // duration to win a lock that isn't coming. A first grant is already driven by the chain
+        // engage in setCaptured/viewDidAppear.
+        if locked {
+            pointerLockWasEngaged = true
+            pointerRelockPending = false
+            pointerRelockAttempt = 0
+        } else if wantsPointerLock, pointerLockWasEngaged {
+            requestPointerRelock()
+        } else {
+            // Capture is gone (or the lock was never ours) — settle, and let the next capture
+            // start from a clean "never held" slate.
+            if !wantsPointerLock { pointerLockWasEngaged = false }
+            pointerRelockPending = false
+            pointerRelockAttempt = 0
+        }
         let useGCMouse = captured && locked
         // Lock dropped (or capture ended) while the GCMouse path held a button down: once
         // gcMouseForwarding flips false its release handler is gated off, so flush any held
@@ -704,7 +767,83 @@ public final class StreamViewController: StreamViewControllerBase {
         pointerInteraction?.invalidate() // re-resolve the hidden/visible cursor for the state
         if iosInputDebug {
             iosInputLog.debug(
-                "pointer lock isLocked=\(locked, privacy: .public) captured=\(self.captured, privacy: .public)")
+                """
+                pointer lock isLocked=\(locked, privacy: .public) \
+                captured=\(self.captured, privacy: .public) \
+                relockPending=\(self.pointerRelockPending, privacy: .public) \
+                relockAttempt=\(self.pointerRelockAttempt, privacy: .public)
+                """)
+        }
+    }
+
+    /// Ask the system for the lock back after it dropped one we still want (see the Escape-drop
+    /// note on the state above). Bounded to a short burst; idempotent within it. Main queue.
+    private func requestPointerRelock() {
+        // Only a frontmost scene can hold the lock at all. Anywhere else the drop is the system
+        // saying we don't qualify, not the Esc key — re-asking would be noise, and the qualifying
+        // states (foreground, appearance, reparent) each re-resolve on their own already.
+        guard view.window?.windowScene?.activationState == .foregroundActive else {
+            pointerRelockPending = false
+            return
+        }
+        let now = CACurrentMediaTime()
+        // attempt == 0 is a fresh burst (first drop, or one the settle branch cleared); the window
+        // is the backstop for the pathological case where a grant is immediately revoked again and
+        // re-arms us. Even then this stays timer-driven at a few Hz — never a spin.
+        if pointerRelockAttempt == 0 || now - pointerRelockBurstStart > Self.pointerRelockBurstWindow {
+            pointerRelockBurstStart = now
+            pointerRelockAttempt = 0
+        }
+        guard pointerRelockAttempt < Self.pointerRelockAttemptLimit else {
+            // Out of budget: fall back to exactly today's behavior — the iPadOS cursor comes back
+            // and a click into the video re-captures. The caller invalidates the interaction, so
+            // the cursor can never stay hidden on a lock the system won't grant.
+            pointerRelockPending = false
+            return
+        }
+        pointerRelockAttempt += 1
+        pointerRelockPending = true
+        let escalate = pointerRelockAttempt > 1
+        // Deferred a turn so a ⌘⎋ whose GC keystroke lands after the system's unlock notification
+        // has already cleared `captured` — then the guard below drops this attempt instead of
+        // fighting the user's own release.
+        DispatchQueue.main.async { [weak self] in
+            guard let self, self.pointerRelockPending else { return }
+            guard self.wantsPointerLock, self.pointerLockEngaged() != true else {
+                // The grant landed, or the capture went away under us (⌘⎋ / ⌃⌥⇧Q / resign).
+                // Settle through the one decision point rather than returning with `pending` still
+                // set — that flag hides the cursor, so it must never outlive the burst.
+                self.syncPointerLock()
+                return
+            }
+            if escalate {
+                // Re-asserting a value the system already holds didn't take. Present a real
+                // false→true transition instead — the documented way to change your mind about the
+                // lock — and re-anchor the chain in case a reparent broke the downward walk to us.
+                // Held for a beat rather than cleared on the next turn: the system resolves the
+                // property asynchronously, and a same-turn flip back to true can be coalesced into
+                // no transition at all. We are already unlocked, so the false pass costs nothing.
+                self.pointerLockForcedOff = true
+                self.setNeedsUpdateOfPrefersPointerLocked()
+                self.updatePointerLockChain()
+                DispatchQueue.main.asyncAfter(deadline: .now() + Self.pointerLockForcedOffHold) {
+                    [weak self] in
+                    guard let self else { return }
+                    self.pointerLockForcedOff = false
+                    self.setNeedsUpdateOfPrefersPointerLocked()
+                }
+            } else {
+                self.setNeedsUpdateOfPrefersPointerLocked()
+            }
+            // A GRANT arrives as a didChange → syncPointerLock, which settles the burst and makes
+            // this retry a no-op. Routed back through syncPointerLock (not straight into another
+            // requestPointerRelock) so the give-up path re-resolves the cursor through the one
+            // place that does it.
+            DispatchQueue.main.asyncAfter(deadline: .now() + Self.pointerRelockRetryDelay) {
+                [weak self] in
+                guard let self, self.pointerRelockPending else { return }
+                self.syncPointerLock()
+            }
         }
     }
     #endif
@@ -724,7 +863,11 @@ extension StreamViewController: UIPointerInteractionDelegate {
         // host renders its own cursor from GCMouse deltas and a visible local one would just
         // diverge. When the lock isn't held the cursor stays VISIBLE so the user can aim; the
         // pointer is forwarded as an absolute position, both cursors tracking together.
-        captured && pointerLockEngaged() == true ? .hidden() : nil
+        // …except across an Esc-drop we're actively re-locking (`pointerRelockPending`): staying
+        // hidden for those couple of frames is what turns the fix into "Esc did nothing to my
+        // mouse" rather than a cursor that blinks in and out. The burst is bounded and clears
+        // itself on give-up, so the cursor can never stay hidden on a lock that isn't coming.
+        captured && (pointerLockEngaged() == true || pointerRelockPending) ? .hidden() : nil
     }
 }
 #endif

clients/linux/src/ui_settings.rs

@@ -156,6 +156,20 @@ mod index {
     pub fn gamepad(s: &Settings) -> u32 {
         GAMEPADS.iter().position(|&g| g == s.gamepad).unwrap_or(0) as u32
     }
+
+    pub fn present_priority(s: &Settings) -> u32 {
+        // Unknown values (a newer client's intent) read as the default, exactly as
+        // `PresentPriority::resolve` treats them.
+        PRESENT_PRIORITIES
+            .iter()
+            .position(|&p| p == s.present_priority)
+            .unwrap_or(0) as u32
+    }
+
+    pub fn smooth_buffer(s: &Settings) -> u32 {
+        // The index IS the stored value: 0 = Automatic, 1..3 = frames.
+        u32::from(s.smooth_buffer).min(SMOOTH_BUFFER_LABELS.len() as u32 - 1)
+    }
 }
 
 /// The chip palette a profile can carry (`StreamProfile.accent`). Eight entries rather than a
@@ -631,6 +645,12 @@ fn commit_profile(active: &StreamProfile, touched: &Touched, values: &Settings)
     if touched.has("fullscreen_on_stream") {
         o.fullscreen_on_stream = Some(values.fullscreen_on_stream);
     }
+    if touched.has("present_priority") {
+        o.present_priority = Some(values.present_priority.clone());
+    }
+    if touched.has("smooth_buffer") {
+        o.smooth_buffer = Some(values.smooth_buffer);
+    }
     // Resets are not handled here: they clear the field and re-seed their row the moment the
     // user asks, so by the time this runs the catalog already reflects them and the row is no
     // longer marked touched.
@@ -684,6 +704,20 @@ const TOUCH_MODE_CAPTIONS: &[&str] = &[
     "The cursor jumps to your finger — a tap clicks there",
     "Real multi-touch reaches the host — for touch-native apps",
 ];
+/// Presentation-intent values (persisted under the `present_priority` key the Apple and
+/// Android clients share) + labels + dynamic captions. Captions stay ONE line, like the
+/// touch/mouse rows.
+const PRESENT_PRIORITIES: &[&str] = &["latency", "smooth"];
+const PRESENT_PRIORITY_LABELS: &[&str] = &["Lowest latency", "Smoothness"];
+const PRESENT_PRIORITY_CAPTIONS: &[&str] = &[
+    "Each frame shows the moment the display can take it",
+    "Buffers a little to even out network hiccups",
+];
+/// Smoothness buffer depth, in frames — the index IS the stored `smooth_buffer` value
+/// (0 = Automatic, which resolves to 2). No millisecond hints: the cost is one refresh
+/// per frame, and the session's refresh isn't known here when the mode is Native.
+const SMOOTH_BUFFER_LABELS: &[&str] = &["Automatic", "1 frame", "2 frames", "3 frames"];
+
 /// Physical-mouse model values (persisted) + labels + dynamic captions — same idiom as
 /// the touch rows. Ctrl+Alt+Shift+M flips the model live in-stream.
 const MOUSE_MODES: &[&str] = &["capture", "desktop"];
@@ -1213,6 +1247,34 @@ pub fn show_scoped(
         row
     });
 
+    // ---- Display: Presentation ----
+    // The intent pair the Apple and Android clients already carry. The buffer row only
+    // means anything under Smoothness, so it hides itself the rest of the time rather
+    // than sitting there inert.
+    let present_row = ChoiceRow::new(
+        &dialog,
+        inline,
+        "Prioritize",
+        PRESENT_PRIORITY_CAPTIONS[0],
+        PRESENT_PRIORITY_LABELS,
+    );
+    let buffer_row = ChoiceRow::new(
+        &dialog,
+        inline,
+        "Smoothness buffer",
+        "Each frame held absorbs one refresh of hiccup and adds one of delay",
+        SMOOTH_BUFFER_LABELS,
+    );
+    {
+        let w = present_row.widget().clone();
+        let buffer = buffer_row.widget().clone();
+        present_row.connect_changed(move |i| {
+            let i = (i as usize).min(PRESENT_PRIORITY_CAPTIONS.len() - 1);
+            set_row_subtitle(&w, PRESENT_PRIORITY_CAPTIONS[i]);
+            buffer.set_visible(PRESENT_PRIORITIES[i] == "smooth");
+        });
+    }
+
     // ---- Display: Host output ----
     let compositor_row = ChoiceRow::new(
         &dialog,
@@ -1479,6 +1541,17 @@ pub fn show_scoped(
         let codec_i = index::codec(s);
         codec_row.set_selected(codec_i);
         set_row_subtitle(codec_row.widget(), codec_caption(codec_i));
+        let present_i = index::present_priority(s);
+        present_row.set_selected(present_i);
+        set_row_subtitle(
+            present_row.widget(),
+            PRESENT_PRIORITY_CAPTIONS[present_i as usize],
+        );
+        buffer_row.set_selected(index::smooth_buffer(s));
+        // `set_selected` never fires the changed hook, so mirror its visibility rule here.
+        buffer_row
+            .widget()
+            .set_visible(PRESENT_PRIORITIES[present_i as usize] == "smooth");
     }
 
     // ---- Override markers, per-row reset, and the touch that creates an override ----
@@ -1671,6 +1744,18 @@ pub fn show_scoped(
             index::surround
         );
         choice!(pad_row, "gamepad", o.gamepad.is_some(), index::gamepad);
+        choice!(
+            present_row,
+            "present_priority",
+            o.present_priority.is_some(),
+            index::present_priority
+        );
+        choice!(
+            buffer_row,
+            "smooth_buffer",
+            o.smooth_buffer.is_some(),
+            index::smooth_buffer
+        );
         toggle!(hdr_row, "hdr_enabled", o.hdr_enabled.is_some(), hdr_enabled);
         toggle!(chroma_row, "enable_444", o.enable_444.is_some(), enable_444);
         toggle!(
@@ -1775,6 +1860,9 @@ pub fn show_scoped(
     if let (Some(r), false) = (&gpu_row, profile_mode) {
         quality_group.add(r.widget());
     }
+    let presentation_group = group("Presentation", "");
+    presentation_group.add(present_row.widget());
+    presentation_group.add(buffer_row.widget());
     // The one form-level note (deliberately not repeated on every row).
     let output_group = group(
         "Host output",
@@ -1783,6 +1871,7 @@ pub fn show_scoped(
     output_group.add(compositor_row.widget());
     display.add(&resolution_group);
     display.add(&quality_group);
+    display.add(&presentation_group);
     display.add(&output_group);
 
     let input = page("Input", "input-keyboard-symbolic");
@@ -1925,6 +2014,12 @@ pub fn show_scoped(
                 _ => 2,
             };
             s.codec = CODECS[(codec_row.selected() as usize).min(CODECS.len() - 1)].to_string();
+            s.present_priority = PRESENT_PRIORITIES
+                [(present_row.selected() as usize).min(PRESENT_PRIORITIES.len() - 1)]
+            .to_string();
+            // The index IS the value (0 = Automatic).
+            s.smooth_buffer =
+                (buffer_row.selected() as u8).min(SMOOTH_BUFFER_LABELS.len() as u8 - 1);
             s.library_enabled = library_row.is_active();
         };
 

clients/session/src/console.rs

@@ -169,6 +169,9 @@ pub fn run(target: Option<&str>) -> u8 {
         mouse_mode: settings_at_start.mouse_mode(),
         invert_scroll: settings_at_start.invert_scroll,
         inhibit_shortcuts: settings_at_start.inhibit_shortcuts,
+        // Presentation-tier like the rows above: latched at console start, a per-host
+        // profile cannot move it in this mode (the documented P4 gap).
+        present_priority: settings_at_start.present_priority(),
         json_status,
         on_connected: Some(Box::new(move |fingerprint: [u8; 32]| {
             let fp_hex = trust::hex(&fingerprint);

clients/session/src/main.rs

@@ -617,6 +617,7 @@ mod session_main {
             mouse_mode: settings.mouse_mode(),
             invert_scroll: settings.invert_scroll,
             inhibit_shortcuts: settings.inhibit_shortcuts,
+            present_priority: settings.present_priority(),
             json_status: true,
             on_connected: Some(Box::new(|fingerprint: [u8; 32]| {
                 // This host's card carries the accent bar in the desktop client now.

clients/windows/src/app/settings.rs

@@ -101,6 +101,19 @@ const MOUSE_MODES: &[(&str, &str)] = &[
     ("capture", "Capture (games)"),
     ("desktop", "Desktop (absolute)"),
 ];
+/// Presentation intent: `(stored value, display label)` — the `present_priority` key the
+/// Apple and Android clients share, so one profile means the same thing everywhere.
+const PRESENT_PRIORITIES: &[(&str, &str)] =
+    &[("latency", "Lowest latency"), ("smooth", "Smoothness")];
+/// Smoothness buffer depth in frames: `(stored value, display label)`. `0` = Automatic,
+/// which resolves to 2 (`PresentPriority::resolve`). No millisecond hints — the cost is
+/// one refresh per frame, and the refresh isn't known here when the mode is Native.
+const SMOOTH_BUFFERS: &[(u8, &str)] = &[
+    (0, "Automatic"),
+    (1, "1 frame"),
+    (2, "2 frames"),
+    (3, "3 frames"),
+];
 /// Host compositor presets: `(stored value, display label)`. Advisory — the host falls back to
 /// auto-detect when the choice is unavailable. Only meaningful against a Linux host.
 const COMPOSITORS: &[(&str, &str)] = &[
@@ -447,6 +460,8 @@ struct OverrideFlags {
     gamepad: bool,
     stats_verbosity: bool,
     fullscreen_on_stream: bool,
+    present_priority: bool,
+    smooth_buffer: bool,
 }
 
 impl OverrideFlags {
@@ -475,6 +490,8 @@ impl OverrideFlags {
             gamepad: o.gamepad.is_some(),
             stats_verbosity: o.stats_verbosity.is_some(),
             fullscreen_on_stream: o.fullscreen_on_stream.is_some(),
+            present_priority: o.present_priority.is_some(),
+            smooth_buffer: o.smooth_buffer.is_some(),
         }
     }
 }
@@ -851,6 +868,28 @@ pub(crate) fn settings_page(
     let chroma_toggle = setting_toggle(ctx, scope, (rev, set_rev), s.enable_444, |s, on| {
         s.enable_444 = on
     });
+    // Presentation intent (design/desktop-presentation-rebuild.md). The buffer row is
+    // rendered only under Smoothness — `commit` bumps the revision, so flipping the
+    // intent re-renders the section and the row appears/disappears with it.
+    let (present_names, present_i) = presets(PRESENT_PRIORITIES, |v| *v == s.present_priority);
+    let present_combo = setting_combo(
+        ctx,
+        scope,
+        (rev, set_rev),
+        present_names,
+        present_i,
+        |s, i| s.present_priority = PRESENT_PRIORITIES[i].0.to_string(),
+    );
+    let smoothing = s.present_priority == "smooth";
+    let (buffer_names, buffer_i) = presets(SMOOTH_BUFFERS, |v| *v == s.smooth_buffer);
+    let buffer_combo = setting_combo(
+        ctx,
+        scope,
+        (rev, set_rev),
+        buffer_names,
+        buffer_i,
+        |s, i| s.smooth_buffer = SMOOTH_BUFFERS[i].0,
+    );
 
     // --- Input -----------------------------------------------------------------------------
     // Controller forwarding: Automatic forwards EVERY real controller, each as its own pad;
@@ -1105,6 +1144,37 @@ pub(crate) fn settings_page(
                 },
                 None,
             ));
+            out.extend(group(
+                Some("Presentation"),
+                {
+                    let mut fields = vec![described_overridable(
+                        (rev, set_rev),
+                        scope,
+                        "present_priority",
+                        "Prioritize",
+                        over.present_priority,
+                        present_combo,
+                        "Lowest latency shows each frame the moment the display can take \
+                         it \u{2014} a network hiccup becomes an occasional repeated or \
+                         skipped frame. Smoothness buffers a little to even those out.",
+                    )];
+                    if smoothing {
+                        fields.push(described_overridable(
+                            (rev, set_rev),
+                            scope,
+                            "smooth_buffer",
+                            "Smoothness buffer",
+                            over.smooth_buffer,
+                            buffer_combo,
+                            "Frames held back before showing. Each one absorbs about a \
+                             refresh of network hiccup and adds a refresh of delay. \
+                             Automatic holds two.",
+                        ));
+                    }
+                    fields
+                },
+                None,
+            ));
             out.extend(group(
                 Some("Host output"),
                 vec![described_overridable(
@@ -1727,5 +1797,16 @@ mod tests {
         let f3 = OverrideFlags::of(Some(&p3));
         assert!(f3.echo_cancel);
         assert!(!f3.mic_enabled);
+
+        // The presentation pair, likewise independent: pinning the intent doesn't claim
+        // the buffer (a "Smoothness, whatever the global buffer is" profile is valid).
+        let mut p4 = StreamProfile::new("t4".to_string());
+        p4.overrides = SettingsOverlay {
+            present_priority: Some("smooth".into()),
+            ..Default::default()
+        };
+        let f4 = OverrideFlags::of(Some(&p4));
+        assert!(f4.present_priority);
+        assert!(!f4.smooth_buffer);
     }
 }

crates/pf-client-core/src/orchestrate.rs

@@ -982,6 +982,10 @@ mod tests {
                 height: 1440,
                 bitrate_kbps: 55000,
                 codec: "av1".into(),
+                present_priority: "smooth".into(),
+                smooth_buffer: 2,
+                vsync: false,
+                allow_vrr: false,
                 ..Default::default()
             },
             clipboard: true,

crates/pf-client-core/src/profiles.rs

@@ -77,6 +77,18 @@ pub struct SettingsOverlay {
     pub stats_verbosity: Option<StatsVerbosity>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub fullscreen_on_stream: Option<bool>,
+    /// The presentation cluster — the keys the Apple client already writes into this
+    /// same catalog shape (`present_priority`/`smooth_buffer`/`vsync`/`allow_vrr`;
+    /// Android carries the first two). First-class here so a profile authored on any
+    /// client applies on all of them instead of riding `extra` unapplied.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub present_priority: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub smooth_buffer: Option<u8>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub vsync: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub allow_vrr: Option<bool>,
     /// Overlay keys a newer client wrote and this one doesn't model — carried through a
     /// load→save round-trip untouched.
     #[serde(flatten)]
@@ -150,6 +162,18 @@ impl SettingsOverlay {
         if let Some(v) = self.fullscreen_on_stream {
             s.fullscreen_on_stream = v;
         }
+        if let Some(v) = &self.present_priority {
+            s.present_priority = v.clone();
+        }
+        if let Some(v) = self.smooth_buffer {
+            s.smooth_buffer = v;
+        }
+        if let Some(v) = self.vsync {
+            s.vsync = v;
+        }
+        if let Some(v) = self.allow_vrr {
+            s.allow_vrr = v;
+        }
         s
     }
 
@@ -226,6 +250,18 @@ impl SettingsOverlay {
         if after.fullscreen_on_stream != before.fullscreen_on_stream {
             self.fullscreen_on_stream = Some(after.fullscreen_on_stream);
         }
+        if after.present_priority != before.present_priority {
+            self.present_priority = Some(after.present_priority.clone());
+        }
+        if after.smooth_buffer != before.smooth_buffer {
+            self.smooth_buffer = Some(after.smooth_buffer);
+        }
+        if after.vsync != before.vsync {
+            self.vsync = Some(after.vsync);
+        }
+        if after.allow_vrr != before.allow_vrr {
+            self.allow_vrr = Some(after.allow_vrr);
+        }
     }
 
     /// Drop one override by its overlay field name, putting the row back to inheriting. The
@@ -259,6 +295,10 @@ impl SettingsOverlay {
             "gamepad" => self.gamepad = None,
             "stats_verbosity" => self.stats_verbosity = None,
             "fullscreen_on_stream" => self.fullscreen_on_stream = None,
+            "present_priority" => self.present_priority = None,
+            "smooth_buffer" => self.smooth_buffer = None,
+            "vsync" => self.vsync = None,
+            "allow_vrr" => self.allow_vrr = None,
             _ => return false,
         }
         true
@@ -455,6 +495,10 @@ mod tests {
             match_window: Some(true),
             fullscreen_on_stream: Some(false),
             stats_verbosity: Some(StatsVerbosity::Detailed),
+            present_priority: Some("smooth".into()),
+            smooth_buffer: Some(3),
+            vsync: Some(false),
+            allow_vrr: Some(false),
             ..Default::default()
         };
         assert!(!overlay.is_empty());
@@ -476,6 +520,10 @@ mod tests {
         assert!(out.match_window);
         assert!(!out.fullscreen_on_stream);
         assert_eq!(out.stats_verbosity(), StatsVerbosity::Detailed);
+        assert_eq!(out.present_priority, "smooth");
+        assert_eq!(out.smooth_buffer, 3);
+        assert!(!out.vsync);
+        assert!(!out.allow_vrr);
         // The tier goes through the setter, so the legacy bool a pre-tier binary reads
         // stays coherent with it.
         assert!(out.show_stats);
@@ -573,6 +621,59 @@ mod tests {
         assert!(o.is_empty());
     }
 
+    /// The presentation cluster is first-class, not `extra` passengers: it applies,
+    /// absorbs, clears, and serialises under the exact keys the Apple client already
+    /// writes (`present_priority`/`smooth_buffer`/`vsync`/`allow_vrr`) — one catalog
+    /// has to round-trip through every platform, and a mismatched key would be carried
+    /// but never applied.
+    #[test]
+    fn presentation_cluster_is_first_class() {
+        let base = Settings::default();
+        let mut o = SettingsOverlay::default();
+        let before = o.apply(&base);
+        let mut after = before.clone();
+        after.present_priority = "smooth".into();
+        o.absorb(&before, &after);
+        let before = o.apply(&base);
+        let mut after = before.clone();
+        after.smooth_buffer = 1;
+        o.absorb(&before, &after);
+        assert_eq!(o.present_priority.as_deref(), Some("smooth"));
+        assert_eq!(o.smooth_buffer, Some(1));
+        assert!(
+            o.extra.is_empty(),
+            "modelled fields must never land in the passthrough"
+        );
+        let out = o.apply(&base);
+        assert_eq!(
+            out.present_priority(),
+            crate::trust::PresentPriority::Smooth { buffer: 1 }
+        );
+
+        // Serialised under the shared keys, and read back from a foreign client's file.
+        let text = serde_json::to_string(&o).unwrap();
+        assert!(text.contains("\"present_priority\":\"smooth\""), "{text}");
+        assert!(text.contains("\"smooth_buffer\":1"), "{text}");
+        let from_apple: SettingsOverlay = serde_json::from_str(
+            r#"{"present_priority":"latency","smooth_buffer":2,"vsync":true,"allow_vrr":false}"#,
+        )
+        .unwrap();
+        assert_eq!(from_apple.present_priority.as_deref(), Some("latency"));
+        assert_eq!(from_apple.smooth_buffer, Some(2));
+        assert_eq!(from_apple.vsync, Some(true));
+        assert_eq!(from_apple.allow_vrr, Some(false));
+        assert!(from_apple.extra.is_empty());
+
+        assert!(o.clear("present_priority"));
+        assert!(o.clear("smooth_buffer"));
+        assert_eq!(o.present_priority, None);
+        assert!(o.is_empty());
+        let mut vrr = from_apple;
+        assert!(vrr.clear("vsync"));
+        assert!(vrr.clear("allow_vrr"));
+        assert_eq!((vrr.vsync, vrr.allow_vrr), (None, None));
+    }
+
     /// `clear` is the explicit way back to inheriting, including the resolution tri-state.
     #[test]
     fn clear_drops_one_override() {

crates/pf-client-core/src/trust.rs

@@ -787,6 +787,45 @@ impl MouseMode {
     }
 }
 
+/// Presentation intent — what the presenter optimizes for
+/// (design/desktop-presentation-rebuild.md; the Apple/Android clients' shared
+/// `present_priority`/`smooth_buffer` pair). Stored stringly in
+/// [`Settings::present_priority`] + [`Settings::smooth_buffer`]; resolved with
+/// [`PresentPriority::resolve`], whose rules match the Android reference
+/// (`decode/presenter.rs`): anything but an explicit `"smooth"` is latency, and a
+/// smooth buffer outside 1..=3 (including 0 = Automatic) becomes 2.
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub enum PresentPriority {
+    /// Every frame presents the moment the display can take it; a network hiccup is an
+    /// occasional repeated or skipped frame. The default.
+    Latency,
+    /// A small frame buffer (1–3 frames) evens out network/decode jitter, at the
+    /// buffer's worth of added display latency.
+    Smooth { buffer: u8 },
+}
+
+impl PresentPriority {
+    /// The shared cross-client resolution rule — pure, so every embedder agrees on what
+    /// a foreign profile's values mean.
+    pub fn resolve(name: &str, buffer: u8) -> PresentPriority {
+        if name == "smooth" {
+            PresentPriority::Smooth {
+                buffer: if (1..=3).contains(&buffer) { buffer } else { 2 },
+            }
+        } else {
+            PresentPriority::Latency
+        }
+    }
+
+    /// Frames the smoothing store holds; `0` = newest-wins (the latency intent).
+    pub fn fifo_capacity(self) -> u8 {
+        match self {
+            PresentPriority::Latency => 0,
+            PresentPriority::Smooth { buffer } => buffer,
+        }
+    }
+}
+
 /// App settings, persisted as JSON. Stringly-typed gamepad/compositor prefs so the file
 /// stays readable; parsed with `*Pref::from_name` at connect time.
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
@@ -874,6 +913,32 @@ pub struct Settings {
     /// `default = true`: the Linux stores never carried this and always advertised.
     #[serde(default = "default_true")]
     pub hdr_enabled: bool,
+    /// Presentation intent: `"latency"` (default) or `"smooth"` — the Apple/Android
+    /// clients' shared `present_priority` profile key, resolved with
+    /// [`PresentPriority::resolve`] (via [`Settings::present_priority`]). Anything
+    /// unknown reads as latency, so a newer client's future value degrades safely.
+    #[serde(default = "default_present_priority")]
+    pub present_priority: String,
+    /// Smoothness buffer size in frames: `0` = Automatic (resolves to 2), else 1–3.
+    /// Only meaningful under `present_priority = "smooth"` (the shared `smooth_buffer`
+    /// key). Each buffered frame absorbs about one refresh of jitter and adds one
+    /// refresh of display latency.
+    #[serde(default)]
+    pub smooth_buffer: u8,
+    /// Tear-free presentation (default ON = today's behavior: MAILBOX, FIFO fallback).
+    /// Off asks for a tearing present mode (IMMEDIATE) for the lowest possible latch
+    /// latency — best-effort: platforms/drivers without tearing silently stay tear-free
+    /// and the active mode is visible in the detailed stats. The shared `vsync` profile
+    /// key; the desktop default differs from macOS's (`false` there) deliberately —
+    /// sync-off means something different on each platform, the key is the contract.
+    #[serde(default = "default_true")]
+    pub vsync: bool,
+    /// Let a variable-refresh display follow the stream cadence: prefers the present
+    /// mode that drives VRR panels directly when fullscreen. Inert on fixed-refresh
+    /// displays (detection is measured from on-glass timestamps, not queried). The
+    /// shared `allow_vrr` profile key. Default ON, like the Apple client.
+    #[serde(default = "default_true")]
+    pub allow_vrr: bool,
     /// Legacy on/off for the stats overlay — superseded by `stats_verbosity` but kept
     /// written in sync (`set_stats_verbosity`) so pre-tier binaries reading the same
     /// file keep working. `alias`: the pre-unification WinUI shell (≤ 0.8.4) persisted
@@ -939,6 +1004,10 @@ fn default_mouse_mode() -> String {
     "capture".into()
 }
 
+fn default_present_priority() -> String {
+    "latency".into()
+}
+
 fn default_true() -> bool {
     true
 }
@@ -970,6 +1039,12 @@ impl Settings {
         MouseMode::from_name(&self.mouse_mode)
     }
 
+    /// The presentation intent for this session (the resolved
+    /// `present_priority` × `smooth_buffer` pair).
+    pub fn present_priority(&self) -> PresentPriority {
+        PresentPriority::resolve(&self.present_priority, self.smooth_buffer)
+    }
+
     /// The `codec` setting as a `quic::CODEC_*` preference bit (`0` = auto).
     pub fn preferred_codec(&self) -> u8 {
         match self.codec.as_str() {
@@ -1007,6 +1082,10 @@ impl Default for Settings {
             adapter: String::new(),
             enable_444: false,
             hdr_enabled: true,
+            present_priority: "latency".into(),
+            smooth_buffer: 0,
+            vsync: true,
+            allow_vrr: true,
             show_stats: true,
             stats_verbosity: None,
             fullscreen_on_stream: true,
@@ -1144,6 +1223,43 @@ mod tests {
         }
     }
 
+    /// A settings file predating the presentation cluster loads with the shipped
+    /// defaults (latency intent, Automatic buffer, tear-free, VRR allowed), and the
+    /// resolution rules match the Apple/Android reference: anything but an explicit
+    /// `"smooth"` is latency, and a smooth buffer outside 1..=3 becomes 2.
+    #[test]
+    fn settings_presentation_defaults_and_resolution() {
+        let old = r#"{"width":1280,"height":720,"gamepad":"auto","compositor":"auto"}"#;
+        let s: Settings = serde_json::from_str(old).unwrap();
+        assert_eq!(s.present_priority, "latency");
+        assert_eq!(s.smooth_buffer, 0);
+        assert!(s.vsync);
+        assert!(s.allow_vrr);
+        assert_eq!(s.present_priority(), PresentPriority::Latency);
+
+        assert_eq!(
+            PresentPriority::resolve("smooth", 0),
+            PresentPriority::Smooth { buffer: 2 },
+            "Automatic resolves to 2"
+        );
+        assert_eq!(
+            PresentPriority::resolve("smooth", 3),
+            PresentPriority::Smooth { buffer: 3 }
+        );
+        assert_eq!(
+            PresentPriority::resolve("smooth", 9),
+            PresentPriority::Smooth { buffer: 2 },
+            "out-of-range pins to the Automatic resolution"
+        );
+        assert_eq!(
+            PresentPriority::resolve("balanced-from-the-future", 2),
+            PresentPriority::Latency,
+            "unknown intents degrade to latency"
+        );
+        assert_eq!(PresentPriority::Latency.fifo_capacity(), 0);
+        assert_eq!(PresentPriority::Smooth { buffer: 3 }.fifo_capacity(), 3);
+    }
+
     /// A pre-`forward_pad` settings file (≤ 0.5.0) loads with the pin on automatic.
     #[test]
     fn settings_forward_pad_defaults_empty() {

crates/pf-console-ui/src/screens/settings.rs

@@ -26,6 +26,8 @@ enum RowId {
     Decoder,
     Hdr,
     Chroma444,
+    PresentPriority,
+    SmoothBuffer,
     Audio,
     Mic,
     EchoCancel,
@@ -46,7 +48,7 @@ enum RowId {
 // scroll/shortcut behavior, fullscreen-on-stream, auto-wake, the library toggle and echo
 // cancellation all were). Still deliberately smaller than the desktop dialogs — device
 // pickers (GPU/speaker/mic) and the profile catalog stay desktop-only.
-const ROWS: [RowId; 22] = [
+const ROWS: [RowId; 24] = [
     RowId::Resolution,
     RowId::Refresh,
     RowId::RenderScale,
@@ -56,6 +58,8 @@ const ROWS: [RowId; 22] = [
     RowId::Decoder,
     RowId::Hdr,
     RowId::Chroma444,
+    RowId::PresentPriority,
+    RowId::SmoothBuffer,
     RowId::Audio,
     RowId::Mic,
     RowId::EchoCancel,
@@ -117,6 +121,17 @@ const DECODERS: [(&str, &str); 4] = [
     ("software", "Software"),
 ];
 const AUDIO: [(u8, &str); 3] = [(2, "Stereo"), (6, "5.1"), (8, "7.1")];
+/// Presentation intent — the `present_priority` key shared with the Apple and Android
+/// clients, so one profile reads the same on every device.
+const PRESENT_PRIORITIES: [(&str, &str); 2] =
+    [("latency", "Lowest latency"), ("smooth", "Smoothness")];
+/// Smoothness buffer depth in frames; `0` = Automatic (resolves to 2).
+const SMOOTH_BUFFERS: [(u8, &str); 4] = [
+    (0, "Automatic"),
+    (1, "1 frame"),
+    (2, "2 frames"),
+    (3, "3 frames"),
+];
 const PAD_TYPES: [(&str, &str); 6] = [
     ("auto", "Automatic"),
     ("xbox360", "Xbox 360"),
@@ -222,9 +237,16 @@ impl SettingsScreen {
 
 fn row_spec(id: RowId, ctx: &Ctx) -> RowSpec {
     let s = &ctx.settings;
-    // Echo cancellation only means anything while the mic streams — dimmed and inert while it
-    // doesn't, the same relationship the desktop shells draw with a greyed-out row.
-    let enabled = !matches!(id, RowId::EchoCancel) || s.mic_enabled;
+    // Two rows follow another: echo cancellation only means anything while the mic
+    // streams, and the smoothness buffer only while that intent is chosen. Both go dim
+    // and inert otherwise — the same relationship the desktop shells draw by greying a
+    // row out (they hide the buffer row entirely; a fixed row list can't, and a row that
+    // vanished mid-list would move everything under the cursor).
+    let enabled = match id {
+        RowId::EchoCancel => s.mic_enabled,
+        RowId::SmoothBuffer => s.present_priority == "smooth",
+        _ => true,
+    };
     let (header, label, value): (Option<&'static str>, &str, String) = match id {
         RowId::Resolution => (
             Some("Stream"),
@@ -279,6 +301,20 @@ fn row_spec(id: RowId, ctx: &Ctx) -> RowSpec {
         RowId::Decoder => (None, "Decoder", label_for(&DECODERS, &s.decoder).into()),
         RowId::Hdr => (None, "10-bit HDR", on_off(s.hdr_enabled).into()),
         RowId::Chroma444 => (None, "Full chroma (4:4:4)", on_off(s.enable_444).into()),
+        RowId::PresentPriority => (
+            Some("Presentation"),
+            "Prioritize",
+            label_for(&PRESENT_PRIORITIES, &s.present_priority).into(),
+        ),
+        RowId::SmoothBuffer => (
+            None,
+            "Smoothness buffer",
+            SMOOTH_BUFFERS
+                .iter()
+                .find(|(v, _)| *v == s.smooth_buffer)
+                .map_or("Automatic", |(_, l)| l)
+                .into(),
+        ),
         RowId::Audio => (
             Some("Audio"),
             "Audio channels",
@@ -368,6 +404,15 @@ fn detail(id: RowId) -> &'static str {
              Needs an NVIDIA host (NVENC) or the PyroWave codec — other encoders \
              stream 4:2:0 and the session falls back silently."
         }
+        RowId::PresentPriority => {
+            "Lowest latency shows each frame the moment the display can take it — a \
+             network hiccup becomes an occasional repeated or skipped frame. Smoothness \
+             buffers a little to even those out."
+        }
+        RowId::SmoothBuffer => {
+            "Frames held back before showing. Each one absorbs about a refresh of network \
+             hiccup and adds a refresh of delay. Automatic holds two."
+        }
         RowId::Audio => "The speaker layout requested from the host.",
         RowId::Mic => {
             "Send this device's microphone to the host's virtual mic. \
@@ -463,6 +508,25 @@ fn adjust(id: RowId, delta: i32, wrap: bool, ctx: &mut Ctx) -> bool {
         RowId::Decoder => step_str(&DECODERS, &mut s.decoder, delta, wrap),
         RowId::Hdr => toggle(&mut s.hdr_enabled, delta, wrap),
         RowId::Chroma444 => toggle(&mut s.enable_444, delta, wrap),
+        RowId::PresentPriority => {
+            let cur = PRESENT_PRIORITIES
+                .iter()
+                .position(|(v, _)| *v == s.present_priority);
+            step_option(cur, PRESENT_PRIORITIES.len(), delta, wrap)
+                .map(|i| s.present_priority = PRESENT_PRIORITIES[i].0.to_string())
+        }
+        // Inert unless smoothness is chosen — a boundary thud, matching the dimmed row.
+        RowId::SmoothBuffer => {
+            if s.present_priority == "smooth" {
+                let cur = SMOOTH_BUFFERS
+                    .iter()
+                    .position(|(v, _)| *v == s.smooth_buffer);
+                step_option(cur, SMOOTH_BUFFERS.len(), delta, wrap)
+                    .map(|i| s.smooth_buffer = SMOOTH_BUFFERS[i].0)
+            } else {
+                None
+            }
+        }
         RowId::Audio => {
             let cur = AUDIO.iter().position(|(v, _)| *v == s.audio_channels);
             step_option(cur, AUDIO.len(), delta, wrap).map(|i| s.audio_channels = AUDIO[i].0)
@@ -648,6 +712,45 @@ mod tests {
         assert!(ctx.settings.echo_cancel);
     }
 
+    /// The smoothness buffer follows the presentation intent, exactly as echo cancellation
+    /// follows the mic: dimmed and inert under Lowest latency (where holding frames means
+    /// nothing), live under Smoothness. The desktop shells hide the row instead; a fixed
+    /// row list dims it, because a row vanishing mid-list would shift everything under the
+    /// cursor.
+    #[test]
+    fn smoothness_buffer_follows_the_intent() {
+        let (mut settings, pads) = ctx_parts();
+        assert_eq!(settings.present_priority, "latency", "the shipped default");
+        let library = crate::library::LibraryShared::default();
+        let mut ctx = Ctx {
+            hosts: &[],
+            library: &library,
+            settings: &mut settings,
+            pads: &pads,
+            deck: false,
+            device_name: "t",
+            t: 0.0,
+        };
+        assert!(!row_spec(RowId::SmoothBuffer, &ctx).enabled);
+        assert!(
+            !adjust(RowId::SmoothBuffer, 1, false, &mut ctx),
+            "latency intent = thud"
+        );
+        assert_eq!(ctx.settings.smooth_buffer, 0, "and nothing was written");
+
+        // Stepping the intent to Smoothness brings the buffer row to life.
+        assert!(adjust(RowId::PresentPriority, 1, false, &mut ctx));
+        assert_eq!(ctx.settings.present_priority, "smooth");
+        assert!(row_spec(RowId::SmoothBuffer, &ctx).enabled);
+        assert!(adjust(RowId::SmoothBuffer, 1, false, &mut ctx));
+        assert_eq!(ctx.settings.smooth_buffer, 1);
+
+        // The intent wraps back and the row goes inert again.
+        assert!(adjust(RowId::PresentPriority, -1, false, &mut ctx));
+        assert_eq!(ctx.settings.present_priority, "latency");
+        assert!(!row_spec(RowId::SmoothBuffer, &ctx).enabled);
+    }
+
     #[test]
     fn touch_mode_steps_and_wraps() {
         let (mut settings, pads) = ctx_parts();

crates/pf-presenter/src/lib.rs

@@ -52,6 +52,8 @@ pub mod keymap_sdl;
 #[cfg(any(target_os = "linux", windows))]
 pub mod overlay;
 #[cfg(any(target_os = "linux", windows))]
+mod present_pace;
+#[cfg(any(target_os = "linux", windows))]
 mod run;
 #[cfg(any(target_os = "linux", windows))]
 pub mod touch;

crates/pf-presenter/src/present_pace.rs

@@ -0,0 +1,406 @@
+//! The presentation intent engine (design/desktop-presentation-rebuild.md WP2): the
+//! store, clock, and gate the run loop composes into the two intents.
+//!
+//! * [`FrameStore`] — newest-wins slot (latency) or smoothing FIFO with preroll
+//!   (smoothness), ported from the Apple `FrameStore` / Android `presenter.rs` so all
+//!   three clients agree on what the intents mean.
+//! * [`LatchClock`] — the panel latch grid, learned from `VK_KHR_present_wait` on-glass
+//!   stamps (measured, never queried — the Android refresh-rate lie and VRR both punish
+//!   trusting a reported rate). Without present-wait it degrades to a grid rooted at the
+//!   last submit on the mode's refresh period.
+//! * [`PresentGate`] — the FIFO glass budget: one undisplayed present in flight, so the
+//!   swapchain's own queue can never become a standing queue (+1 refresh per slot,
+//!   forever — the law every bounded-FIFO pacing rediscovered on Apple). MAILBOX cannot
+//!   queue and never needs it.
+//!
+//! Everything here is pure state + arithmetic on `CLOCK_REALTIME` ns (the
+//! `pf_client_core::session::now_ns` domain the on-glass stamps live in); the run loop
+//! owns all clocks and Vulkan calls, which is what keeps this testable.
+
+use std::collections::VecDeque;
+
+/// Stale-present force-open: an undisplayed present older than this is presumed lost
+/// (occluded window, wedged compositor) and the gate opens anyway, counted as `forced`
+/// — reads 0 on healthy systems. The Apple/Android presenters use the same 100 ms.
+const STALE_REOPEN_NS: u64 = 100_000_000;
+
+/// The adaptive slot-pick margin's ceiling and step (Android's measured values: start
+/// at 0 — a fixed lead was pure display tax on the reference device — and widen only
+/// when measured misses demand it).
+pub(crate) const MARGIN_STEP_NS: u64 = 500_000;
+pub(crate) const MARGIN_MAX_NS: u64 = 2_500_000;
+
+/// The decoded-frame store between the wake channel and the present call.
+///
+/// `capacity == 0` = newest-wins (latency intent): `submit` replaces, `take` clears.
+/// `capacity 1..=3` = smoothing FIFO: preroll-to-capacity, drop-oldest on overflow,
+/// an underflow after preroll re-arms the preroll (the previous frame persists on
+/// glass — a repeat by omission) while headroom rebuilds.
+pub(crate) struct FrameStore<T> {
+    capacity: usize,
+    frames: VecDeque<T>,
+    prerolled: bool,
+    /// Newest-wins displacements (normal operation under latency, not a fault signal).
+    replaced: u32,
+    /// FIFO drop-oldest evictions — the Apple debug line's `qDrop`.
+    overflow_drops: u32,
+    /// FIFO dry-after-preroll events — `qDry`.
+    underflows: u32,
+}
+
+impl<T> FrameStore<T> {
+    pub(crate) fn new(capacity: usize) -> FrameStore<T> {
+        FrameStore {
+            capacity,
+            frames: VecDeque::with_capacity(capacity.max(1) + 1),
+            prerolled: false,
+            replaced: 0,
+            overflow_drops: 0,
+            underflows: 0,
+        }
+    }
+
+    pub(crate) fn is_smoothing(&self) -> bool {
+        self.capacity > 0
+    }
+
+    pub(crate) fn is_empty(&self) -> bool {
+        self.frames.is_empty()
+    }
+
+    pub(crate) fn submit(&mut self, f: T) {
+        if self.capacity == 0 {
+            if self.frames.pop_front().is_some() {
+                self.replaced += 1;
+            }
+            self.frames.push_back(f);
+        } else {
+            self.frames.push_back(f);
+            // Drop the OLDEST past capacity: bounded added latency, the newest keeps
+            // flowing. Also trims a transient capacity+1 a put_back left behind.
+            while self.frames.len() > self.capacity {
+                self.frames.pop_front();
+                self.overflow_drops += 1;
+            }
+        }
+    }
+
+    pub(crate) fn take(&mut self) -> Option<T> {
+        if self.capacity == 0 {
+            return self.frames.pop_front();
+        }
+        if !self.prerolled {
+            // Preroll gate: without it a steady stream drains every frame on arrival
+            // and jitter headroom never builds (the Apple store's lesson).
+            if self.frames.len() < self.capacity {
+                return None;
+            }
+            self.prerolled = true;
+        }
+        match self.frames.pop_front() {
+            Some(f) => Some(f),
+            None => {
+                self.underflows += 1;
+                self.prerolled = false;
+                None
+            }
+        }
+    }
+
+    /// A frame taken but not presented (gate closed, present failed before consuming
+    /// it). Newest-wins reinserts only into an empty slot — a fresher decode wins;
+    /// FIFO puts it back at the front (it is the oldest).
+    pub(crate) fn put_back(&mut self, f: T) {
+        if self.capacity == 0 {
+            if self.frames.is_empty() {
+                self.frames.push_back(f);
+            }
+        } else {
+            self.frames.push_front(f);
+        }
+    }
+
+    /// Collapse to newest-wins for the rest of the stream (PyroWave: its plane-ring
+    /// retirement accounting assumes the depth-2 newest-wins hand-off, and its all-intra
+    /// frames make buffering pointless anyway).
+    pub(crate) fn force_latency(&mut self) {
+        if self.capacity == 0 {
+            return;
+        }
+        self.capacity = 0;
+        self.prerolled = false;
+        while self.frames.len() > 1 {
+            self.frames.pop_front();
+        }
+    }
+
+    /// Drain the window's counters: `(replaced, overflow_drops, underflows)`.
+    pub(crate) fn take_counters(&mut self) -> (u32, u32, u32) {
+        let c = (self.replaced, self.overflow_drops, self.underflows);
+        self.replaced = 0;
+        self.overflow_drops = 0;
+        self.underflows = 0;
+        c
+    }
+}
+
+/// The panel latch grid: a recent on-glass instant + the latch period, extrapolated
+/// forward for slot targeting. Fed per sample batch; the period is the min positive
+/// spacing of consecutive stamps (< 1 ms apart = a queued pair, not a grid step),
+/// capped by the display mode's refresh — under arrival-paced MAILBOX a stream running
+/// below the panel rate spaces its presents at k×period, and the cap keeps a 30 fps
+/// stream from claiming a 30 Hz panel grid. Same rule as the host-facing `LatchGrid`
+/// fold this clock also feeds, so the phase-lock report and the local scheduler can
+/// never disagree about the grid.
+pub(crate) struct LatchClock {
+    anchor_ns: u64,
+    period_ns: u64,
+    fallback_period_ns: u64,
+}
+
+impl LatchClock {
+    pub(crate) fn new(refresh_hz: u32) -> LatchClock {
+        LatchClock {
+            anchor_ns: 0,
+            period_ns: 0,
+            fallback_period_ns: 1_000_000_000 / u64::from(refresh_hz.max(1)),
+        }
+    }
+
+    /// Fold a batch of on-glass stamps (ascending submission order). A single stamp
+    /// re-anchors without touching the learned period — that is also the no-present-wait
+    /// degradation, where each submit stamp anchors an approximate grid on the mode's
+    /// refresh period.
+    pub(crate) fn note_batch(&mut self, stamps: &[u64]) {
+        if let Some(&last) = stamps.last() {
+            self.anchor_ns = last;
+        }
+        let min_delta = stamps
+            .windows(2)
+            .map(|w| w[1].saturating_sub(w[0]))
+            .filter(|&d| d > 1_000_000)
+            .min();
+        if let Some(d) = min_delta {
+            self.period_ns = d.min(self.fallback_period_ns);
+        }
+    }
+
+    pub(crate) fn period_ns(&self) -> u64 {
+        if self.period_ns > 0 {
+            self.period_ns
+        } else {
+            self.fallback_period_ns
+        }
+    }
+
+    pub(crate) fn anchor_ns(&self) -> u64 {
+        self.anchor_ns
+    }
+
+    /// The first predicted latch strictly after `after_ns` (`anchor + k·period`). With
+    /// no anchor yet: one period out — callers get a usable, if unanchored, deadline.
+    pub(crate) fn next_slot_after(&self, after_ns: u64) -> u64 {
+        let p = self.period_ns();
+        if self.anchor_ns == 0 || after_ns < self.anchor_ns {
+            return after_ns.saturating_add(p);
+        }
+        let k = (after_ns - self.anchor_ns) / p + 1;
+        self.anchor_ns + k * p
+    }
+}
+
+/// The FIFO glass budget: at most one undisplayed present in flight, measured by the
+/// present-wait waiter's outstanding count. Never consulted under MAILBOX/IMMEDIATE
+/// (they cannot queue) or without present-wait (nothing to count with — behavior is
+/// then exactly the shipped arrival pacing).
+#[derive(Default)]
+pub(crate) struct PresentGate {
+    /// Submit stamp of the newest tracked present; 0 = none yet.
+    last_present_ns: u64,
+    gated: u32,
+    forced: u32,
+}
+
+impl PresentGate {
+    /// May a new present go out? Open when nothing undisplayed is in flight; a stale
+    /// in-flight present (occlusion, wedged compositor) force-opens after 100 ms so the
+    /// stream survives, counted as `forced`.
+    pub(crate) fn open(&mut self, outstanding: usize, now_ns: u64) -> bool {
+        if outstanding == 0 {
+            return true;
+        }
+        if self.last_present_ns != 0
+            && now_ns.saturating_sub(self.last_present_ns) > STALE_REOPEN_NS
+        {
+            self.forced += 1;
+            return true;
+        }
+        self.gated += 1;
+        false
+    }
+
+    pub(crate) fn note_present(&mut self, now_ns: u64) {
+        self.last_present_ns = now_ns;
+    }
+
+    /// Drain the window's counters: `(gated, forced)`.
+    pub(crate) fn take_counters(&mut self) -> (u32, u32) {
+        let c = (self.gated, self.forced);
+        self.gated = 0;
+        self.forced = 0;
+        c
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Newest-wins: submit replaces, take clears, put_back only fills an empty slot.
+    #[test]
+    fn newest_wins_replaces_and_putback_never_clobbers() {
+        let mut s: FrameStore<u32> = FrameStore::new(0);
+        assert!(!s.is_smoothing());
+        assert_eq!(s.take(), None);
+        s.submit(1);
+        s.submit(2);
+        s.submit(3);
+        assert_eq!(s.take(), Some(3), "only the newest survives");
+        assert_eq!(s.take(), None);
+        // A taken-but-unpresented frame returns — unless a fresher one arrived.
+        s.submit(4);
+        let f = s.take().unwrap();
+        s.put_back(f);
+        assert_eq!(s.take(), Some(4));
+        let f = s.take();
+        assert_eq!(f, None);
+        s.submit(5);
+        let f = s.take().unwrap();
+        s.submit(6);
+        s.put_back(f); // 6 arrived while 5 was out — 6 wins
+        assert_eq!(s.take(), Some(6));
+        assert_eq!(
+            s.take_counters(),
+            (2, 0, 0),
+            "two displacements, no fifo counters"
+        );
+    }
+
+    /// FIFO: preroll to capacity, drop-oldest overflow, underflow re-arms the preroll.
+    #[test]
+    fn fifo_prerolls_overflows_oldest_and_rearms_on_dry() {
+        let mut s: FrameStore<u32> = FrameStore::new(2);
+        assert!(s.is_smoothing());
+        s.submit(1);
+        assert_eq!(s.take(), None, "prerolling: below capacity, nothing vends");
+        s.submit(2);
+        assert_eq!(s.take(), Some(1), "preroll reached — FIFO order");
+        assert_eq!(
+            s.take(),
+            Some(2),
+            "once prerolled the buffer drains normally"
+        );
+        // Dry after preroll = one underflow, preroll re-arms.
+        assert_eq!(s.take(), None);
+        s.submit(3);
+        assert_eq!(s.take(), None, "re-armed preroll holds again");
+        s.submit(4);
+        assert_eq!(s.take(), Some(3));
+        // Overflow drops the OLDEST: [4] → [4,5] → 6 evicts 4 → 7 evicts 5.
+        s.submit(5);
+        s.submit(6);
+        s.submit(7);
+        assert_eq!(s.take(), Some(6));
+        assert_eq!(s.take(), Some(7));
+        let (replaced, drops, dry) = s.take_counters();
+        assert_eq!(replaced, 0);
+        assert_eq!(drops, 2, "6 evicted 4, 7 evicted 5");
+        assert_eq!(dry, 1);
+    }
+
+    /// put_back under FIFO goes to the FRONT (it is the oldest), and the transient
+    /// capacity+1 is trimmed by the next submit.
+    #[test]
+    fn fifo_putback_restores_order() {
+        let mut s: FrameStore<u32> = FrameStore::new(2);
+        s.submit(1);
+        s.submit(2);
+        let f = s.take().unwrap();
+        s.put_back(f);
+        assert_eq!(s.take(), Some(1), "the put-back frame is still first");
+    }
+
+    /// force_latency collapses a smoothing store to a newest-wins slot mid-stream.
+    #[test]
+    fn force_latency_collapses_to_one_slot() {
+        let mut s: FrameStore<u32> = FrameStore::new(3);
+        s.submit(1);
+        s.submit(2);
+        s.submit(3);
+        s.force_latency();
+        assert!(!s.is_smoothing());
+        assert_eq!(s.take(), Some(3), "only the newest survives the collapse");
+        s.submit(4);
+        s.submit(5);
+        assert_eq!(s.take(), Some(5));
+    }
+
+    /// The clock learns the min positive spacing (capped at the mode refresh), anchors
+    /// on the newest stamp, and extrapolates the next slot; sub-ms pairs (a queued
+    /// double-present) never become the period.
+    #[test]
+    fn latch_clock_learns_and_extrapolates() {
+        const P: u64 = 16_666_666; // 60 Hz
+        let mut c = LatchClock::new(60);
+        assert_eq!(c.period_ns(), P, "fallback = the mode refresh");
+        // No anchor: a usable deadline one period out.
+        assert_eq!(c.next_slot_after(1_000), 1_000 + P);
+
+        c.note_batch(&[1_000_000_000, 1_000_000_000 + P, 1_000_000_000 + 2 * P]);
+        assert_eq!(c.period_ns(), P);
+        assert_eq!(c.anchor_ns(), 1_000_000_000 + 2 * P);
+        let next = c.next_slot_after(c.anchor_ns());
+        assert_eq!(next, 1_000_000_000 + 3 * P);
+        // Mid-slot query lands on the same boundary; a later one steps whole periods.
+        assert_eq!(c.next_slot_after(next - 1), next);
+        assert_eq!(c.next_slot_after(next), next + P);
+
+        // A queued pair (< 1 ms apart) must not poison the period.
+        c.note_batch(&[2_000_000_000, 2_000_000_500]);
+        assert_eq!(c.period_ns(), P);
+        assert_eq!(c.anchor_ns(), 2_000_000_500, "the anchor still advances");
+
+        // A stream presenting every OTHER refresh spaces its glass stamps at 2×P — the
+        // panel grid is still P, so the mode-refresh cap holds the learned period down
+        // (this is what keeps a 30 fps stream from claiming a 30 Hz panel).
+        c.note_batch(&[3_000_000_000, 3_000_000_000 + 2 * P]);
+        assert_eq!(c.period_ns(), P, "capped at the mode refresh");
+
+        // A single stamp re-anchors without touching the period.
+        c.note_batch(&[5_000_000_000]);
+        assert_eq!(c.anchor_ns(), 5_000_000_000);
+        assert_eq!(c.period_ns(), P);
+
+        // A faster panel learns its own finer grid.
+        let mut fast = LatchClock::new(120);
+        fast.note_batch(&[1_000_000_000, 1_008_333_333]);
+        assert_eq!(fast.period_ns(), 8_333_333);
+    }
+
+    /// Gate: open at zero outstanding, closed at one, force-open past the stale bound.
+    #[test]
+    fn gate_budgets_one_undisplayed_present() {
+        let mut g = PresentGate::default();
+        let t0 = 1_000_000_000u64;
+        assert!(g.open(0, t0));
+        g.note_present(t0);
+        assert!(!g.open(1, t0 + 8_000_000), "one in flight — hold");
+        assert!(
+            g.open(1, t0 + STALE_REOPEN_NS + 1),
+            "stale in-flight present force-opens"
+        );
+        let (gated, forced) = g.take_counters();
+        assert_eq!((gated, forced), (1, 1));
+        assert_eq!(g.take_counters(), (0, 0), "counters drain");
+    }
+}

crates/pf-presenter/src/run.rs

@@ -18,12 +18,13 @@
 
 use crate::input::{Capture, FingerPhase};
 use crate::overlay::{FrameCtx, Overlay, OverlayAction, OverlayFrame, SessionPhase};
+use crate::present_pace::{FrameStore, LatchClock, PresentGate, MARGIN_MAX_NS, MARGIN_STEP_NS};
 use crate::touch::Abs;
 use crate::vk::{FrameInput, Presenter};
 use anyhow::{Context as _, Result};
 use pf_client_core::gamepad::GamepadService;
 use pf_client_core::session::{self, SessionEvent, SessionHandle, SessionParams, Stats};
-use pf_client_core::trust::{MouseMode, StatsVerbosity, TouchMode};
+use pf_client_core::trust::{MouseMode, PresentPriority, StatsVerbosity, TouchMode};
 use pf_client_core::video::VulkanDecodeDevice;
 use pf_client_core::video::{DecodedFrame, DecodedImage};
 use punktfunk_core::client::NativeClient;
@@ -63,6 +64,12 @@ pub struct SessionOpts {
     /// work profile that streams on a second screen and still Alt-Tabs here. Never applies
     /// under the `desktop` mouse model, which is something you Alt-Tab *away* from.
     pub inhibit_shortcuts: bool,
+    /// Presentation intent ([`Settings::present_priority`] resolved): `Latency` keeps the
+    /// shipped arrival pacing (newest-wins, present the moment a frame can go out);
+    /// `Smooth { buffer }` runs the smoothing FIFO drained one frame per latch slot
+    /// (design/desktop-presentation-rebuild.md). `PUNKTFUNK_PRESENTER=arrival` overrides
+    /// the whole engine back to the legacy drain for field A/B without a rebuild.
+    pub present_priority: PresentPriority,
     /// Emit the `{"ready":true}` stdout line after the first presented frame.
     pub json_status: bool,
     /// Called once on `Connected` with the host's fingerprint (trust persistence is the
@@ -213,8 +220,40 @@ struct StreamState {
     // capture→displayed (host-clock corrected) p50+p95, display = decoded→displayed p50.
     win_e2e_us: Vec<u64>,
     win_disp_us: Vec<u64>,
+    /// The display stage's two halves (present-timing sessions only): decoded→submit and
+    /// submit→on-glass. See [`PresentedWindow::pace_ms`].
+    win_pace_us: Vec<u64>,
+    win_latch_us: Vec<u64>,
     win_start: Instant,
     presented: PresentedWindow,
+    /// The intent engine (design/desktop-presentation-rebuild.md WP2): the decoded-frame
+    /// store between the wake channel and the present call — a newest-wins slot under
+    /// the latency intent (behaviorally the shipped drain), the smoothing FIFO under
+    /// smoothness. NOTE: a smoothing store holds decoder-pool frames (Vulkan-Video
+    /// AVFrames) up to `buffer` deep on top of the depth-2 wake channels — within pool
+    /// headroom for 1..=3, but any deeper store must revisit pool sizing.
+    store: FrameStore<DecodedFrame>,
+    /// The panel latch grid (present-wait glass stamps; submit-anchored fallback) — the
+    /// smoothness slot clock, and the values published to the host-facing `latch_grid`.
+    clock: LatchClock,
+    /// The FIFO glass budget (one undisplayed present in flight) — inert off FIFO modes
+    /// or without present timing.
+    gate: PresentGate,
+    /// The latch slot the last smoothness present served (one present per slot); 0 =
+    /// none yet.
+    last_target_ns: u64,
+    /// Smoothness slot-pick margin: starts 0 (a fixed lead is pure display tax —
+    /// measured on Android), widens +500 µs per >2-miss window toward 2.5 ms.
+    margin_ns: u64,
+    /// This window's latch misses (a present that reached glass > 1.5 latch periods
+    /// after submit) — the adaptive margin's error signal.
+    win_misses: u32,
+    /// This window's peak undisplayed-presents-in-flight (present timing only).
+    win_out_max: usize,
+    /// One-shot log latch: smoothness was requested but a PyroWave stream collapsed the
+    /// store to latency (its plane-ring retirement assumes the newest-wins hand-off).
+    #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
+    pyro_latency_forced: bool,
     // Hardware-path health: a failure streak (or a device with no import support at
     // all) demotes the decoder to software via the shared flag — once per session.
     dmabuf_demoted: bool,
@@ -279,6 +318,8 @@ impl StreamState {
         params: SessionParams,
         force_software: Arc<AtomicBool>,
         wake: sdl3::event::EventSender,
+        priority: PresentPriority,
+        native_refresh_hz: u32,
     ) -> StreamState {
         let profile = params.profile.clone();
         // The presenter's half of phase-locked capture: it writes the latch grid the
@@ -316,8 +357,19 @@ impl StreamState {
             hdr_untonemapped: false,
             win_e2e_us: Vec::with_capacity(256),
             win_disp_us: Vec::with_capacity(256),
+            win_pace_us: Vec::with_capacity(256),
+            win_latch_us: Vec::with_capacity(256),
             win_start: Instant::now(),
             presented: PresentedWindow::default(),
+            store: FrameStore::new(usize::from(priority.fifo_capacity())),
+            clock: LatchClock::new(native_refresh_hz),
+            gate: PresentGate::default(),
+            last_target_ns: 0,
+            margin_ns: 0,
+            win_misses: 0,
+            win_out_max: 0,
+            #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
+            pyro_latency_forced: false,
             dmabuf_demoted: false,
             #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
             pyro_present_warned: false,
@@ -356,6 +408,25 @@ impl StreamState {
         }
         self.handle.stop.store(true, Ordering::SeqCst);
     }
+
+    /// The event-loop wait bound: a smoothness stream with buffered frames sleeps only
+    /// to its next latch-slot deadline; everything else keeps the 15 ms housekeeping
+    /// tick (frames, input, and present completions all wake the loop early anyway).
+    fn wake_timeout(&self) -> Duration {
+        const TICK: Duration = Duration::from_millis(15);
+        if !self.store.is_smoothing() || self.store.is_empty() {
+            return TICK;
+        }
+        let now = session::now_ns();
+        let mut target = self
+            .clock
+            .next_slot_after(now.saturating_add(self.margin_ns));
+        if target == self.last_target_ns {
+            // This slot is already served — the next boundary is the deadline.
+            target += self.clock.period_ns();
+        }
+        Duration::from_nanos(target.saturating_sub(now)).clamp(Duration::from_millis(1), TICK)
+    }
 }
 
 /// Whether a present error is `VK_ERROR_DEVICE_LOST` anywhere in its chain. A lost
@@ -441,6 +512,26 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
     let mut presenter = Presenter::new(&window, &instance_exts).context("vulkan presenter")?;
     // A valid black frame immediately — the window is honest while the connect runs.
     presenter.present(&window, FrameInput::Redraw, None)?;
+
+    // `PUNKTFUNK_PRESENTER=arrival` — the legacy drain, the intent engine's field-A/B
+    // kill switch (the Android sysprop pattern: no rebuild to bisect a pacing suspicion).
+    let arrival_override = std::env::var("PUNKTFUNK_PRESENTER").ok().as_deref() == Some("arrival");
+    let present_priority = if arrival_override {
+        tracing::info!("PUNKTFUNK_PRESENTER=arrival — presentation pacing disabled");
+        PresentPriority::Latency
+    } else {
+        opts.present_priority
+    };
+    let pacing_active = !arrival_override;
+    let present_debug = std::env::var_os("PUNKTFUNK_PRESENT_DEBUG").is_some();
+    // Present completions wake the loop exactly like decoded frames: a glass-gate
+    // reopen or a smoothness slot must not wait out the event timeout.
+    {
+        let sender = events.event_sender();
+        presenter.set_present_wake(Box::new(move || {
+            let _ = sender.push_custom_event(FrameWake);
+        }));
+    }
     // Browse mode is "ready" the moment the library window presents — there may never be
     // a stream. (Single mode announces on the first VIDEO frame instead, further down, so
     // a shell only yields to a window that actually shows the stream.)
@@ -517,6 +608,8 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                 params,
                 force_software,
                 events.event_sender(),
+                present_priority,
+                native.refresh_hz,
             ))
         }
         ModeCtl::Browse(_) => None,
@@ -544,8 +637,11 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
         // forwarder's FrameWake) all land in this one queue, so the loop wakes exactly
         // when there is work — a short-timeout poll here burned a full core (measured;
         // the timeout only bounds stop-flag/pump-tick latency now). In browse-idle the
-        // per-iteration FIFO present vsync-throttles the loop anyway.
-        let timeout = Duration::from_millis(15);
+        // per-iteration FIFO present vsync-throttles the loop anyway. A smoothness
+        // stream tightens the bound to its next latch-slot deadline.
+        let timeout = stream
+            .as_ref()
+            .map_or(Duration::from_millis(15), |st| st.wake_timeout());
         let first = event_pump.wait_event_timeout(timeout);
         let mut queued: Vec<Event> = Vec::new();
         if let Some(e) = first {
@@ -1032,6 +1128,8 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                                     *params,
                                     force_software,
                                     events.event_sender(),
+                                    present_priority,
+                                    native.refresh_hz,
                                 ));
                                 if let Some(o) = overlay.as_mut() {
                                     o.session_phase(SessionPhase::Connecting);
@@ -1279,11 +1377,116 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                     presenter.set_hdr_metadata(m);
                 }
             }
-            let mut newest: Option<DecodedFrame> = None;
-            while let Ok(f) = st.frames.try_recv() {
-                newest = Some(f);
+            // Present-wait completions drive the latch clock, the glass gate, and the
+            // host-facing grid — drained every pass (a 1 Hz batch would starve all
+            // three; the waiter's SDL wake pairs with this so completions never wait
+            // out the event timeout).
+            if presenter.present_timing_active() {
+                let samples = presenter.take_presented_samples();
+                if !samples.is_empty() {
+                    let clock_offset_ns = st
+                        .clock_offset
+                        .as_ref()
+                        .map_or(0, |o| o.load(Ordering::Relaxed));
+                    let period = st.clock.period_ns();
+                    let mut stamps = Vec::with_capacity(samples.len());
+                    for s in &samples {
+                        let e2e = (s.displayed_ns as i128 + clock_offset_ns as i128
+                            - s.pts_ns as i128)
+                            .max(0) as u64;
+                        if e2e > 0 && e2e < 10_000_000_000 {
+                            st.win_e2e_us.push(e2e / 1000);
+                        }
+                        st.win_disp_us
+                            .push(s.displayed_ns.saturating_sub(s.decoded_ns) / 1000);
+                        // The display split (WP4): our pipeline vs the vsync latch. Only
+                        // meaningful with true glass stamps, which is exactly when this
+                        // branch runs.
+                        st.win_pace_us
+                            .push(s.submitted_ns.saturating_sub(s.decoded_ns) / 1000);
+                        st.win_latch_us
+                            .push(s.displayed_ns.saturating_sub(s.submitted_ns) / 1000);
+                        // Latch miss (the adaptive margin's error signal): glass more
+                        // than 1.5 latch periods after submit = the intended slot was
+                        // overshot.
+                        if st.store.is_smoothing()
+                            && s.displayed_ns.saturating_sub(s.submitted_ns) > period + period / 2
+                        {
+                            st.win_misses += 1;
+                        }
+                        stamps.push(s.displayed_ns);
+                    }
+                    st.clock.note_batch(&stamps);
+                    // Phase-locked capture, the presenter's half: publish the grid the
+                    // local clock just learned — a recent TRUE on-glass instant plus
+                    // the latch period — for the pump's ~1 Hz PhaseReport. One learner
+                    // feeds both, so the report and the scheduler cannot disagree.
+                    if let Some(grid) = &st.latch_grid {
+                        grid.period_ns
+                            .store(st.clock.period_ns(), Ordering::Relaxed);
+                        grid.anchor_ns
+                            .store(st.clock.anchor_ns(), Ordering::Relaxed);
+                    }
+                }
             }
-            if let Some(f) = newest {
+
+            // Intake into the intent store: a newest-wins slot under latency (the
+            // shipped drain, now with displacement counters), the smoothing FIFO under
+            // smoothness. PyroWave collapses smoothness to latency for the stream: its
+            // plane-ring retirement accounting assumes the newest-wins hand-off
+            // (`video_pyrowave::RETIRE_HANDOVERS`), and all-intra frames make
+            // buffering moot anyway.
+            while let Ok(f) = st.frames.try_recv() {
+                #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
+                if st.store.is_smoothing() && matches!(f.image, DecodedImage::PyroWave(_)) {
+                    st.store.force_latency();
+                    if !st.pyro_latency_forced {
+                        st.pyro_latency_forced = true;
+                        tracing::info!(
+                            "PyroWave stream — smoothness buffering does not apply \
+                             (latency pacing)"
+                        );
+                    }
+                }
+                st.store.submit(f);
+            }
+
+            // One frame out, by intent: latency takes the newest whenever the glass
+            // gate allows; smoothness serves at most one frame per latch slot (the
+            // preroll/underflow behavior lives in the store).
+            let now_ns = session::now_ns();
+            let mut slot_target = 0u64;
+            let mut to_present = if st.store.is_smoothing() {
+                let target = st
+                    .clock
+                    .next_slot_after(now_ns.saturating_add(st.margin_ns));
+                if target != st.last_target_ns {
+                    slot_target = target;
+                    st.store.take()
+                } else {
+                    None
+                }
+            } else {
+                st.store.take()
+            };
+            // The FIFO glass budget: one undisplayed present in flight, so the
+            // swapchain's own FIFO can never become a standing queue (a measured
+            // 11-13 ms at 60 Hz on MAILBOX-less drivers). Only FIFO modes queue and
+            // only present timing can count, so everywhere else this stays inert and
+            // behavior is the shipped arrival pacing.
+            if pacing_active && presenter.fifo_present_mode() && presenter.present_timing_active() {
+                if let Some(f) = to_present.take() {
+                    if st.gate.open(presenter.presents_outstanding(), now_ns) {
+                        to_present = Some(f);
+                    } else {
+                        // Parked: a newest-wins store replaces it if a fresher frame
+                        // lands; the waiter's wake (or the 100 ms stale force-open)
+                        // retries.
+                        st.store.put_back(f);
+                    }
+                }
+            }
+            if let Some(f) = to_present {
                 // Resize END: a frame at the steered target size means the sharp new-mode
                 // picture is here — lift the scrim. A no-op unless a switch is in flight.
                 let (fw, fh) = f.image.dimensions();
@@ -1472,6 +1675,12 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                 };
                 if did_present {
                     presented_video = true;
+                    // Smoothness: this latch slot is served — one present per slot.
+                    // (Set only on success: a gated or failed present leaves the slot
+                    // open for the retry.)
+                    if slot_target != 0 {
+                        st.last_target_ns = slot_target;
+                    }
                     if opts.json_status && !st.ready_announced {
                         st.ready_announced = true;
                         println!("{{\"ready\":true}}");
@@ -1481,6 +1690,8 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                         // e2e/display samples arrive via `take_presented_samples` with a
                         // TRUE on-glass stamp instead of the submit-time one below.
                         presenter.note_presented(pts_ns, decoded_ns);
+                        st.gate.note_present(now_ns);
+                        st.win_out_max = st.win_out_max.max(presenter.presents_outstanding());
                     } else {
                         let displayed_ns = session::now_ns();
                         // The `displayed` stamp (same clamp rules as the pump's windows).
@@ -1495,59 +1706,79 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                         }
                         st.win_disp_us
                             .push(displayed_ns.saturating_sub(decoded_ns) / 1000);
+                        // No glass stamps on this stack: the submit instant anchors an
+                        // approximate grid on the mode's refresh period, so smoothness
+                        // still drains one frame per (approximate) slot.
+                        st.clock.note_batch(&[displayed_ns]);
                     }
                 }
             }
 
             // Fold the presenter window into the shared stats line once per second.
+            // (The on-glass samples themselves are drained every pass above — they
+            // drive the latch clock and glass gate, not just this fold.)
             if st.win_start.elapsed() >= Duration::from_secs(1) {
-                // On-glass samples the present-wait waiter completed this window (empty
-                // when timing is inactive — the legacy submit-time pushes fill in then).
-                let clock_offset_ns = st
-                    .clock_offset
-                    .as_ref()
-                    .map_or(0, |o| o.load(Ordering::Relaxed));
-                let samples = presenter.take_presented_samples();
-                // Phase-locked capture, the presenter's half: publish this window's latch
-                // grid — a recent TRUE on-glass instant plus the panel period — for the
-                // pump's ~1 Hz PhaseReport. The period is the min positive spacing of
-                // consecutive on-glass stamps (Apple's method: honest under VRR), capped
-                // by the display mode's refresh — under arrival-paced MAILBOX a stream
-                // running below the panel rate spaces its presents at k×period, and the
-                // cap keeps a 30 fps stream from claiming a 30 Hz panel grid.
-                if let Some(grid) = &st.latch_grid {
-                    if let Some(last) = samples.last() {
-                        let refresh_period = 1_000_000_000u64 / u64::from(native.refresh_hz.max(1));
-                        let min_delta = samples
-                            .windows(2)
-                            .map(|w| w[1].displayed_ns.saturating_sub(w[0].displayed_ns))
-                            .filter(|&d| d > 1_000_000) // < 1 ms apart = queued pair, not a grid step
-                            .min()
-                            .unwrap_or(refresh_period);
-                        grid.period_ns
-                            .store(min_delta.min(refresh_period), Ordering::Relaxed);
-                        grid.anchor_ns.store(last.displayed_ns, Ordering::Relaxed);
-                    }
-                }
-                for s in samples {
-                    let e2e = (s.displayed_ns as i128 + clock_offset_ns as i128 - s.pts_ns as i128)
-                        .max(0) as u64;
-                    if e2e > 0 && e2e < 10_000_000_000 {
-                        st.win_e2e_us.push(e2e / 1000);
-                    }
-                    st.win_disp_us
-                        .push(s.displayed_ns.saturating_sub(s.decoded_ns) / 1000);
-                }
                 let (e2e_p50, e2e_p95) = session::window_percentiles(&mut st.win_e2e_us);
                 let (disp_p50, _) = session::window_percentiles(&mut st.win_disp_us);
+                let (pace_p50, _) = session::window_percentiles(&mut st.win_pace_us);
+                let (latch_p50, _) = session::window_percentiles(&mut st.win_latch_us);
+                // Drained ONCE per window and shared by the HUD and the log line below —
+                // a second `take_counters` would read zeros.
+                let (replaced, q_drop, q_dry) = st.store.take_counters();
+                let (gated, forced) = st.gate.take_counters();
                 st.presented = PresentedWindow {
                     e2e_p50_ms: e2e_p50 as f32 / 1000.0,
                     e2e_p95_ms: e2e_p95 as f32 / 1000.0,
                     display_ms: disp_p50 as f32 / 1000.0,
+                    pace_ms: pace_p50 as f32 / 1000.0,
+                    latch_ms: latch_p50 as f32 / 1000.0,
+                    mode: presenter.present_mode_name(),
+                    smoothing: st.store.is_smoothing(),
+                    q_drop,
+                    q_dry,
+                    gated,
+                    forced,
                 };
                 st.win_e2e_us.clear();
                 st.win_disp_us.clear();
+                st.win_pace_us.clear();
+                st.win_latch_us.clear();
                 st.win_start = Instant::now();
+                // Adaptive slot margin (the Android presenter's measured recipe):
+                // start at 0 — a fixed lead is pure display tax — and widen one step
+                // per window whose measured latch misses demand it. One-way per
+                // stream; the next stream restarts at 0.
+                if st.store.is_smoothing() && st.win_misses > 2 && st.margin_ns < MARGIN_MAX_NS {
+                    st.margin_ns = (st.margin_ns + MARGIN_STEP_NS).min(MARGIN_MAX_NS);
+                    tracing::info!(
+                        margin_us = st.margin_ns / 1000,
+                        misses = st.win_misses,
+                        "smoothness slot margin widened (measured latch misses)"
+                    );
+                }
+                // The 1 Hz presenter line (the Apple `pf-present` analogue): emitted
+                // when anything moved, or always under PUNKTFUNK_PRESENT_DEBUG=1 —
+                // the field-triage instrument for the intent engine.
+                if pacing_active && (present_debug || q_drop + q_dry + gated + forced > 0) {
+                    tracing::info!(
+                        smoothing = st.presented.smoothing,
+                        mode = st.presented.mode,
+                        replaced,
+                        q_drop,
+                        q_dry,
+                        gated,
+                        forced,
+                        misses = st.win_misses,
+                        out_max = st.win_out_max,
+                        pace_ms = st.presented.pace_ms,
+                        latch_ms = st.presented.latch_ms,
+                        period_us = st.clock.period_ns() / 1000,
+                        margin_us = st.margin_ns / 1000,
+                        "presenter window"
+                    );
+                }
+                st.win_misses = 0;
+                st.win_out_max = 0;
             }
         }
 
@@ -2007,6 +2238,30 @@ struct PresentedWindow {
     e2e_p50_ms: f32,
     e2e_p95_ms: f32,
     display_ms: f32,
+    /// The display stage split (design/desktop-presentation-rebuild.md WP4):
+    /// `pace` = decoded → present-submit (our own pipeline), `latch` = submit → on-glass
+    /// (the presentation engine's queue + the vblank wait). Both `0` without
+    /// `VK_KHR_present_wait`, where the two are not separable — the HUD then shows the
+    /// unsplit figure rather than inventing a zero latch.
+    ///
+    /// This split is what makes a high `display` self-diagnosing: latch dominating means
+    /// the vsync/queue floor (or a standing queue), pace dominating means us.
+    /// `pace` is also the honest cross-platform twin of the Apple client's shaved
+    /// number — Apple subtracts its measured OS present floor, and the latch IS our
+    /// floor, so `pace` is what remains on both sides of that comparison.
+    pace_ms: f32,
+    latch_ms: f32,
+    /// The live swapchain present mode (`mailbox`/`fifo`/…). Shown because a mode is
+    /// chosen from what the surface offers, so "why is my latch a refresh long" is
+    /// usually answered by a MAILBOX request having landed on FIFO.
+    mode: &'static str,
+    /// Presenter-engine counters for the window: the smoothing FIFO's overflow drops and
+    /// post-preroll underflows, and the FIFO glass gate's holds/stale force-opens.
+    smoothing: bool,
+    q_drop: u32,
+    q_dry: u32,
+    gated: u32,
+    forced: u32,
 }
 
 /// The capture hints (`ui_stream` parity — the words the user reads while released).
@@ -2112,6 +2367,15 @@ fn stats_text(
             " · decode {:.1} · display {:.1} ms",
             s.decode_ms, p.display_ms
         ));
+        // The display split (WP4). Only with true on-glass stamps — without them the
+        // two halves are not separable and the unsplit figure stands alone rather than
+        // implying a zero latch.
+        if p.latch_ms > 0.0 || p.pace_ms > 0.0 {
+            text.push_str(&format!(
+                " (pace {:.1} + latch {:.1})",
+                p.pace_ms, p.latch_ms
+            ));
+        }
         // Extended 0xCF host-stage split (T0.1): its own line so the per-stage attribution
         // (queue → encode → seal/xfer → pace) reads as the host pipeline in order.
         if s.staged {
@@ -2120,6 +2384,28 @@ fn stats_text(
                 s.host_queue_ms, s.host_encode_ms, s.host_xfer_ms, s.host_pace_ms
             ));
         }
+        // The presenter line: the swapchain mode that is actually live, the chosen
+        // intent, and the engine's own counters. Present-mode alone answers most
+        // "why is my latch a whole refresh" questions; the counters only render when
+        // they are non-zero, so a healthy latency session shows just the mode.
+        if !p.mode.is_empty() {
+            text.push_str(&format!("\npresent: {}", p.mode));
+            if p.smoothing {
+                text.push_str(" · smoothing");
+            }
+            if p.q_drop > 0 {
+                text.push_str(&format!(" · qdrop {}", p.q_drop));
+            }
+            if p.q_dry > 0 {
+                text.push_str(&format!(" · qdry {}", p.q_dry));
+            }
+            if p.gated > 0 {
+                text.push_str(&format!(" · gated {}", p.gated));
+            }
+            if p.forced > 0 {
+                text.push_str(&format!(" · forced {}", p.forced));
+            }
+        }
     }
     if s.lost > 0 {
         text.push_str(&format!("\nlost {} ({:.1}%)", s.lost, s.lost_pct));
@@ -2393,6 +2679,7 @@ mod tests {
                 e2e_p50_ms: 6.4,
                 e2e_p95_ms: 9.1,
                 display_ms: 1.1,
+                ..Default::default()
             },
         )
     }
@@ -2430,6 +2717,70 @@ mod tests {
             !normal.contains("queue"),
             "host-stage split is Detailed-only"
         );
+        assert!(
+            !detailed.contains("pace 1.1"),
+            "no glass stamps in this sample — the display stage stays unsplit"
+        );
+    }
+
+    /// WP4: with true on-glass stamps the display stage reads as its two halves, the
+    /// live present mode is named, and the engine counters render only when non-zero —
+    /// so a healthy latency session shows the mode and nothing else. Without glass
+    /// stamps (no `VK_KHR_present_wait`) the split is absent rather than a zero latch.
+    #[test]
+    fn detailed_splits_display_into_pace_and_latch() {
+        let (s, mut p) = sample();
+        p.display_ms = 12.4;
+        p.pace_ms = 1.1;
+        p.latch_ms = 11.3;
+        p.mode = "fifo";
+        let split = stats_text(
+            StatsVerbosity::Detailed,
+            "m",
+            &s,
+            &p,
+            false,
+            false,
+            false,
+            None,
+        );
+        assert!(split.contains("display 12.4 ms (pace 1.1 + latch 11.3)"));
+        assert!(split.contains("\npresent: fifo"));
+        assert!(
+            !split.contains("qdrop") && !split.contains("gated") && !split.contains("smoothing"),
+            "quiet counters stay off the HUD: {split}"
+        );
+
+        // The smoothing FIFO and the glass gate surface once they actually do something.
+        p.smoothing = true;
+        p.q_drop = 2;
+        p.q_dry = 1;
+        p.gated = 7;
+        p.forced = 1;
+        let busy = stats_text(
+            StatsVerbosity::Detailed,
+            "m",
+            &s,
+            &p,
+            false,
+            false,
+            false,
+            None,
+        );
+        assert!(busy.contains("present: fifo · smoothing · qdrop 2 · qdry 1 · gated 7 · forced 1"));
+
+        // A tier below Detailed never carries any of it.
+        let normal = stats_text(
+            StatsVerbosity::Normal,
+            "m",
+            &s,
+            &p,
+            false,
+            false,
+            false,
+            None,
+        );
+        assert!(!normal.contains("present:") && !normal.contains("pace"));
     }
 
     /// The honest HDR badges: a PQ stream on the software-decode lane is shown WITHOUT

crates/pf-presenter/src/vk/mod.rs

@@ -247,10 +247,56 @@ impl Presenter {
     /// (the presenter itself never sees them). No-op when timing is inactive.
     pub(crate) fn note_presented(&mut self, pts_ns: u64, decoded_ns: u64) {
         if let (Some(t), Some((sc, id))) = (&self.present_timer, self.last_presented.take()) {
-            t.enqueue(sc, id, pts_ns, decoded_ns);
+            // The submit stamp: `present()` already returned, so "now" is within the
+            // present-call tail — the pace/latch split point.
+            t.enqueue(
+                sc,
+                id,
+                pts_ns,
+                decoded_ns,
+                pf_client_core::session::now_ns(),
+            );
         }
     }
 
+    /// Undisplayed id-carrying presents in flight (0 when timing is inactive) — the
+    /// FIFO glass gate's budget count.
+    pub(crate) fn presents_outstanding(&self) -> usize {
+        self.present_timer.as_ref().map_or(0, |t| t.outstanding())
+    }
+
+    /// Install the run loop's wake for present completions (an SDL event push). No-op
+    /// without present timing — there is nothing to wake on then.
+    pub(crate) fn set_present_wake(&self, cb: Box<dyn Fn() + Send>) {
+        if let Some(t) = &self.present_timer {
+            t.set_wake(cb);
+        }
+    }
+
+    /// The live swapchain present mode, for the stats overlay: a mode is picked from
+    /// what the surface actually offers, so the requested one and this can differ (a
+    /// MAILBOX request lands on FIFO wherever the driver has no mailbox — AMD's Windows
+    /// driver, notably). Showing it is what makes that visible instead of puzzling.
+    pub(crate) fn present_mode_name(&self) -> &'static str {
+        match self.present_mode {
+            vk::PresentModeKHR::MAILBOX => "mailbox",
+            vk::PresentModeKHR::FIFO => "fifo",
+            vk::PresentModeKHR::FIFO_RELAXED => "fifo-relaxed",
+            vk::PresentModeKHR::IMMEDIATE => "immediate",
+            _ => "other",
+        }
+    }
+
+    /// The active present mode queues presents (FIFO family): the only modes where the
+    /// swapchain itself can become a standing queue, and so the only ones the glass
+    /// gate governs. MAILBOX/IMMEDIATE replace/flip and never queue.
+    pub(crate) fn fifo_present_mode(&self) -> bool {
+        matches!(
+            self.present_mode,
+            vk::PresentModeKHR::FIFO | vk::PresentModeKHR::FIFO_RELAXED
+        )
+    }
+
     /// Take the window's completed on-glass samples (empty when timing is inactive).
     pub(crate) fn take_presented_samples(&self) -> Vec<present_timing::PresentedSample> {
         self.present_timer

crates/pf-presenter/src/vk/present_timing.rs

@@ -26,6 +26,9 @@ pub(crate) struct PresentedSample {
     pub pts_ns: u64,
     /// Decode-complete stamp (client clock) — the display-stage anchor.
     pub decoded_ns: u64,
+    /// `vkQueuePresentKHR`-return stamp (client clock) — the pace/latch split point:
+    /// `submitted − decoded` is our pipeline, `displayed − submitted` the vsync latch.
+    pub submitted_ns: u64,
     /// `vkWaitForPresentKHR` completion = the image is visible (client clock).
     pub displayed_ns: u64,
 }
@@ -35,15 +38,24 @@ struct Job {
     present_id: u64,
     pts_ns: u64,
     decoded_ns: u64,
+    submitted_ns: u64,
 }
 
+/// The run loop's wake callback (an SDL event push), shared with the waiter thread.
+type WakeSlot = Arc<Mutex<Option<Box<dyn Fn() + Send>>>>;
+
 /// The waiter: a channel-fed thread turning (swapchain, present-id) pairs into
 /// [`PresentedSample`]s. One frame in flight upstream keeps the queue depth ~1.
 pub(crate) struct PresentTimer {
     tx: Option<mpsc::Sender<Job>>,
-    /// Jobs enqueued but not yet finished — the drain barrier for swapchain teardown.
+    /// Jobs enqueued but not yet finished — the drain barrier for swapchain teardown,
+    /// and the glass gate's "undisplayed presents in flight" count.
     pending: Arc<AtomicUsize>,
     results: Arc<Mutex<Vec<PresentedSample>>>,
+    /// Called by the waiter after each completed wait (sample or not) — the run loop
+    /// installs an SDL wake here so a gate reopen / smoothness slot never waits out the
+    /// event-loop timeout.
+    wake: WakeSlot,
     join: Option<std::thread::JoinHandle<()>>,
 }
 
@@ -52,7 +64,8 @@ impl PresentTimer {
         let (tx, rx) = mpsc::channel::<Job>();
         let pending = Arc::new(AtomicUsize::new(0));
         let results = Arc::new(Mutex::new(Vec::with_capacity(256)));
-        let (pending_t, results_t) = (pending.clone(), results.clone());
+        let wake: WakeSlot = Arc::new(Mutex::new(None));
+        let (pending_t, results_t, wake_t) = (pending.clone(), results.clone(), wake.clone());
         let join = std::thread::Builder::new()
             .name("pf-present-wait".into())
             .spawn(move || {
@@ -69,12 +82,20 @@ impl PresentTimer {
                         results_t.lock().unwrap().push(PresentedSample {
                             pts_ns: job.pts_ns,
                             decoded_ns: job.decoded_ns,
+                            submitted_ns: job.submitted_ns,
                             displayed_ns,
                         });
                     }
                     // SUBOPTIMAL/TIMEOUT/DEVICE_LOST: no sample; the frame still showed
                     // (or the loop is about to find out) — never poison the window.
                     pending_t.fetch_sub(1, Ordering::AcqRel);
+                    // Wake the run loop AFTER the count dropped: what it observes on
+                    // wake is the post-completion state (the gate may now be open).
+                    // Called under the slot lock — the callback is a bare SDL event
+                    // push and never reenters this type.
+                    if let Some(cb) = wake_t.lock().unwrap().as_ref() {
+                        cb();
+                    }
                 }
             })
             .expect("spawn pf-present-wait");
@@ -82,10 +103,23 @@ impl PresentTimer {
             tx: Some(tx),
             pending,
             results,
+            wake,
             join: Some(join),
         }
     }
 
+    /// Install the run loop's wake callback (an SDL event push — thread-safe by design).
+    pub(crate) fn set_wake(&self, cb: Box<dyn Fn() + Send>) {
+        *self.wake.lock().unwrap() = Some(cb);
+    }
+
+    /// Presents handed to the waiter and not yet resolved to glass — the glass gate's
+    /// budget count. (Also counts a wait that will end SUBOPTIMAL/TIMEOUT; those resolve
+    /// within the 250 ms cap, far past the gate's own 100 ms stale force-open.)
+    pub(crate) fn outstanding(&self) -> usize {
+        self.pending.load(Ordering::Acquire)
+    }
+
     /// Hand a successfully submitted present to the waiter.
     pub(crate) fn enqueue(
         &self,
@@ -93,6 +127,7 @@ impl PresentTimer {
         present_id: u64,
         pts_ns: u64,
         decoded_ns: u64,
+        submitted_ns: u64,
     ) {
         if let Some(tx) = &self.tx {
             self.pending.fetch_add(1, Ordering::AcqRel);
@@ -102,6 +137,7 @@ impl PresentTimer {
                     present_id,
                     pts_ns,
                     decoded_ns,
+                    submitted_ns,
                 })
                 .is_err()
             {

docs-site/content/docs/client-settings.md

@@ -82,9 +82,20 @@ Full detail: [HDR](/docs/hdr).
 **Full chroma (4:4:4)** — *default: off.* Crisp small text and thin lines, at more bandwidth. It
 needs HEVC or PyroWave, the host's own 4:4:4 policy left on, a capture path that delivers full
 chroma, and a GPU that can encode it; if any gate fails the host says 4:2:0 before your decoder is
-built. **Today only the Apple app actually advertises 4:4:4**, and only when its hardware decode
-probe passes — the Linux and Windows apps store the toggle but their session doesn't advertise the
-capability yet, so it has no effect there. Android, Decky and the console home don't offer it.
+built. The Apple, Linux and Windows apps all advertise it (Apple additionally requires its hardware
+decode probe to pass). Android, Decky and the console home don't offer it.
+
+**Prioritize** — *default: Lowest latency.* What the client optimizes for when a decoded frame is
+ready. **Lowest latency** shows every frame the moment the display can take it, so a network hiccup
+becomes an occasional repeated or skipped frame. **Smoothness** holds a small buffer that evens
+those hiccups out, at that buffer's worth of added delay. Linux and Windows apps; the Apple and
+Android apps have carried the same setting for a while, and it is stored under the same name, so a
+[profile](/docs/profiles-and-links) means the same thing on every device.
+
+**Smoothness buffer** — *default: Automatic (two frames).* Only shown under **Smoothness**. How
+many frames are held back before showing. Each frame absorbs roughly one screen refresh of network
+hiccup and costs one refresh of delay — so on a 120 Hz screen, two frames is about 17 ms of extra
+delay bought against 17 ms of jitter. If you never see stutter, you don't need this.
 
 **Host compositor** — *default: Automatic.* Which backend a **Linux** host uses to drive the virtual
 output. Advisory: a host without that backend quietly auto-detects instead.

docs-site/content/docs/configuration.md

@@ -242,6 +242,8 @@ A few knobs are read by the native **clients**, not the host:
 | `PUNKTFUNK_OSD_SCALE` | multiplier, e.g. `1.5` *(default `1`)* | Size of the in-stream overlay — the stats OSD, the capture hint and the start banner. They already follow your display's scaling setting (200 % display → twice the pixels), so set this only to nudge that: bigger for a TV across the room, smaller if your compositor reports an aggressive scale. Clamped to 0.5×–4×, and a line that would run off the screen is shrunk to fit. |
 | `PUNKTFUNK_NO_AEC` | `1` | Turn the microphone's echo cancellation off for this run, whatever **Echo cancellation** says in [client settings](/docs/client-settings#audio). One-way: it can only switch the processing off, never back on, and the setting is the normal way to control it. Linux and Windows clients. |
 | `PUNKTFUNK_PRESENT_MODE` | `mailbox` *(default)* · `fifo` · `immediate` · `fifo_relaxed` | How decoded frames meet the display (the Vulkan present mode). The default prefers MAILBOX — tear-free without queueing behind the vertical refresh — and falls back to FIFO (classic vsync) where the driver doesn't offer it. **AMD's Windows driver offers no MAILBOX**, so those clients run FIFO, which adds a standing frame-pacing wait (up to one refresh interval). `immediate` removes that wait but can tear; `fifo_relaxed` only tears when a frame is late. If your latency floor matters more than tearing, try `immediate` and judge by eye. |
+| `PUNKTFUNK_PRESENTER` | `arrival` | Turn the frame-pacing engine off for this run: frames present the instant they decode, exactly as they did before the **Prioritize** setting existed. A diagnostic — if a pacing change is suspected of causing judder or added delay, this switches it off without reinstalling anything. Linux and Windows clients. |
+| `PUNKTFUNK_PRESENT_DEBUG` | `1` | Log the presenter's own 1-second summary (display mode, buffer drops, pacing counters) every second, even when nothing is going wrong. Without it the line appears only when there is something to report. |
 | `PUNKTFUNK_ABR_PROBE_KBPS` | kbps, e.g. `900000` | The startup link-capacity probe's burst target (default 2 Gbps — deliberately above any plausible link so the burst measures the link, not itself). Lower it on links the burst shouldn't slam, or when the measured ceiling comes out wrong for your setup. |
 | `PUNKTFUNK_ABR_PROBE` | `0` | Skip the startup link-capacity probe entirely. The adaptive-bitrate climb ceiling then stays at the negotiated starting rate — a blunt instrument; prefer `PUNKTFUNK_ABR_MAX_MBPS`. |
 | `PUNKTFUNK_ABR_MAX_MBPS` | Mbps, e.g. `300` | Hard cap on the adaptive bitrate's climb ceiling, whatever the startup probe measured. The escape hatch when adaptive sessions keep climbing past what your client's **decoder** can sustain (periodic hitch + "receive backlog stopped draining" in the client log). An explicit bitrate setting still bypasses ABR entirely. |

docs-site/content/docs/stats.md

@@ -62,8 +62,9 @@ differently. Linux · Windows · Steam Deck:
 
 ```
 1920×1080@120 · 120 fps · 24.3 Mb/s · target 30 Mb/s (auto) · vulkan · HDR
-e2e 14.2/19.8 ms (p50/p95) · host 3.1 · net 6.7 · decode 2.1 · display 2.3 ms
+e2e 14.2/19.8 ms (p50/p95) · host 3.1 · net 6.7 · decode 2.1 · display 2.3 ms (pace 0.6 + latch 1.7)
 host: queue 0.6 · encode 1.8 · xfer 0.2 · pace 0.5 ms
+present: mailbox
 lost 3 (2.4%)
 ```
 
@@ -109,10 +110,11 @@ lost 3 (2.4%)
   which otherwise reads as inexplicable judder plus a refresh of extra latency.
 - **Line 2 — the headline.** `end-to-end` (`e2e` on Linux/Windows) is the *directly
   measured* time from host capture to the endpoint named at the end of the line —
-  `capture→on-glass` or `capture→displayed`. Linux/Windows don't spell the endpoint out,
-  because their presenter always measures to the present instant. `p50` = the typical
-  frame (median), `p95` = the slow outliers. This is the one number that summarizes your
-  stream.
+  `capture→on-glass` or `capture→displayed`. On Linux/Windows the endpoint is the moment
+  the frame is genuinely **visible** wherever the GPU driver can report it (most can);
+  where it can't, the measurement stops at the instant the frame is handed to the display
+  and so reads slightly optimistic. `p50` = the typical frame (median), `p95` = the slow
+  outliers. This is the one number that summarizes your stream.
 - **Line 3 — where the time goes.** The first four stages **tile the end-to-end interval** —
   each starts where the previous one ends, so they add up to the headline. The two extra
   terms under them are not extra time: one is excluded from the total, the other sits inside a
@@ -123,7 +125,12 @@ lost 3 (2.4%)
     reassembly on your device.
   - `decode` — received → decoded, on your device.
   - `display` — decoded → displayed: waiting for the right screen refresh, rendering,
-    and vsync.
+    and vsync. On Linux/Windows it splits into `(pace + latch)` when your driver reports
+    true on-glass timing: **pace** is Punktfunk's own work — getting the decoded frame
+    submitted — and **latch** is the wait for the display to take it. A large `latch` is
+    the screen's refresh cycle, not the stream; a large `pace` is us. (`pace` is also the
+    fair number to compare against an iPhone or iPad, whose figure already has its
+    equivalent of `latch` removed.)
   - `os present` *(iOS and tvOS)* — the fixed depth of the OS present pipeline, which is
     excluded from both the headline and `display` and printed here so you can add it
     back.
@@ -143,6 +150,13 @@ lost 3 (2.4%)
   encode … · xfer … · pace …` — splitting the host's own share into its stages, when the
   host reports them.
 
+  Linux/Windows Detailed also carries a **`present:`** line naming how frames are reaching
+  your screen: the display mode in use (`mailbox`, `fifo`, …) and, when the
+  [presentation setting](/docs/client-settings#video) is *Smoothness*, the word
+  `smoothing`. Counters join it only when they're doing something — `qdrop`/`qdry` mean
+  the smoothing buffer overflowed or ran dry (a jittery link), and `gated`/`forced`
+  belong to the pacing that keeps frames from stacking up behind the display.
+
   (Stage values are per-stage medians, so they sum only *approximately* to the
   headline median — percentiles aren't perfectly additive. The headline is measured
   directly, never computed as a sum.)