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>
2026-08-02 19:57:08 +02:00
parent 732b3587a6
commit 28c6f752d0
8 changed files with 487 additions and 19 deletions
@@ -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();
        };

@@ -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);
    }
 }
@@ -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();
@@ -220,6 +220,10 @@ 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
@@ -353,6 +357,8 @@ 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())),
@@ -1393,6 +1399,13 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                        }
                        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.
@@ -1707,13 +1720,29 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
            if st.win_start.elapsed() >= Duration::from_secs(1) {
                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
@@ -1730,13 +1759,10 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                // 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.
-                let (replaced, q_drop, q_dry) = st.store.take_counters();
-                let (gated, forced) = st.gate.take_counters();
-                if pacing_active
-                    && (present_debug || replaced + q_drop + q_dry + gated + forced > 0)
-                {
+                if pacing_active && (present_debug || q_drop + q_dry + gated + forced > 0) {
                    tracing::info!(
-                        smoothing = st.store.is_smoothing(),
+                        smoothing = st.presented.smoothing,
+                        mode = st.presented.mode,
                        replaced,
                        q_drop,
                        q_dry,
@@ -1744,6 +1770,8 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                        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"
@@ -2210,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).
@@ -2315,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 {
@@ -2323,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));
@@ -2596,6 +2679,7 @@ mod tests {
                e2e_p50_ms: 6.4,
                e2e_p95_ms: 9.1,
                display_ms: 1.1,
+                ..Default::default()
            },
        )
    }
@@ -2633,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
@@ -273,6 +273,20 @@ impl Presenter {
        }
    }

+    /// 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.
@@ -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.
@@ -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. |
@@ -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.)