fix(kwin): select the custom mode KWin actually built, not the one we asked for

A KDE host streaming to a phone-shaped client fell back to 60 Hz even though the
120 Hz mode was sitting right there in KDE's display list, one manual click away.

KWin generates every custom mode's timing with libxcvt, whose first step is
`hdisplay_rnd = hdisplay - (hdisplay % 8)`. A 2868x1320@120 request (iPhone 16
Pro Max) therefore becomes 2864x1320@119.92 — 4 px narrower, fractional refresh.
We then asked kscreen-doctor for `mode.2868x1320@120`; its `findMode` matches a
mode's id or its own `WxH@qRound(Hz)` name, so that string matched nothing, the
select silently no-op'd, the output stayed on its sacrificial birth mode, and
`size_applied` came back false → "KWin rejected the custom mode" → 60 Hz.
Widths like 1920/2560/3840 are all multiples of 8, which is why only clients with
phone-shaped panels ever hit this.

Resolve the mode out of the output's OWN list instead and address it by kscreen
mode id: exact height, width at most one cell narrower than asked, refresh within
1 Hz (which excludes the native 60 Hz entry). `set_custom_refresh` now returns the
whole achieved mode, and `create` reports that as the output's `preferred_mode` —
so the capturer's renegotiation gate waits for the size KWin will actually deliver
and the encoder opens against it, rather than starving on the requested one.

Also skip `addCustomMode` when a usable mode is already installed: kscreen-doctor
APPENDS to the list and KWin persists it per output name, so the old code grew the
user's display list by one entry per connect.

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

clients/apple/Sources/PunktfunkClient/Session/DisplaySleepGuard.swift

@@ -0,0 +1,97 @@
+// Keeps the local display awake for the duration of a streaming session.
+//
+// A stream is not "user activity" to the OS: the pixels arrive over the network and the input that
+// drives them is often a game controller, which does NOT feed the HID idle timer on any Apple
+// platform. So a controller-only session reliably idles the panel out from under the user — the
+// same reason the Android client holds FLAG_KEEP_SCREEN_ON while streaming (StreamScreen.kt).
+//
+// Held by SessionModel from `beginStreaming` to `disconnect`, so it is scoped to the session and
+// never leaks past it (including a host-ended or timed-out background session, which both land in
+// `disconnect`).
+
+import Foundation
+
+#if os(macOS)
+    import IOKit.pwr_mgt
+#else
+    import UIKit
+#endif
+
+@MainActor
+final class DisplaySleepGuard {
+    #if os(macOS)
+        /// The `beginActivity` token; non-nil exactly while held.
+        private var activity: NSObjectProtocol?
+        /// Re-used across heartbeats so the whole session shares one assertion instead of
+        /// accumulating one per tick.
+        private var userActivityAssertion: IOPMAssertionID = IOPMAssertionID(0)
+        private var heartbeat: Timer?
+
+        /// The power assertion defers DISPLAY SLEEP but not the screen saver — that runs off the
+        /// HID idle timer, which a controller-only session never touches. Declaring user activity
+        /// on an interval well under the shortest selectable screen-saver delay (1 minute) keeps
+        /// that timer from ever reaching it. Side effect, and the intended one: an idle-lock
+        /// configured to follow the screen saver is deferred too, for the session only.
+        private static let heartbeatInterval: TimeInterval = 30
+    #endif
+
+    private(set) var isHeld = false
+
+    /// Idempotent — a second acquire while held is a no-op.
+    func acquire() {
+        guard !isHeld else { return }
+        isHeld = true
+        #if os(macOS)
+            // The high-level Foundation API over IOKit power assertions: `.idleDisplaySleepDisabled`
+            // is the panel, `.userInitiated` also holds off idle SYSTEM sleep and sudden termination
+            // for a session the user is watching in real time.
+            activity = ProcessInfo.processInfo.beginActivity(
+                options: [.userInitiated, .idleDisplaySleepDisabled],
+                reason: "Punktfunk streaming session")
+            declareUserActivity()
+            let timer = Timer.scheduledTimer(withTimeInterval: Self.heartbeatInterval, repeats: true) {
+                [weak self] _ in
+                MainActor.assumeIsolated { self?.declareUserActivity() }
+            }
+            // The stream runs under a tracking run-loop mode while a menu or a window resize is up;
+            // .common keeps the heartbeat ticking through those.
+            RunLoop.main.add(timer, forMode: .common)
+            heartbeat = timer
+        #else
+            // iOS/iPadOS/tvOS: app-wide, and ignored while backgrounded — the background keep-alive
+            // (audio-only, video dropped) correctly lets the device sleep without touching this.
+            UIApplication.shared.isIdleTimerDisabled = true
+        #endif
+    }
+
+    /// Idempotent — safe to call when not held (`disconnect` runs on paths that never streamed).
+    func release() {
+        guard isHeld else { return }
+        isHeld = false
+        #if os(macOS)
+            heartbeat?.invalidate()
+            heartbeat = nil
+            if let activity {
+                ProcessInfo.processInfo.endActivity(activity)
+                self.activity = nil
+            }
+            if userActivityAssertion != IOPMAssertionID(0) {
+                IOPMAssertionRelease(userActivityAssertion)
+                userActivityAssertion = IOPMAssertionID(0)
+            }
+        #else
+            UIApplication.shared.isIdleTimerDisabled = false
+        #endif
+    }
+
+    #if os(macOS)
+        /// Resets the HID idle timer (see `heartbeatInterval`). `kIOPMUserActiveLocal` = activity at
+        /// this Mac's own display, which is what a stream being watched here is.
+        private func declareUserActivity() {
+            IOPMAssertionDeclareUserActivity(
+                "Punktfunk streaming session" as CFString,
+                kIOPMUserActiveLocal,
+                &userActivityAssertion)
+        }
+    #endif
+}

clients/apple/Sources/PunktfunkClient/Session/SessionModel.swift

@@ -196,6 +196,11 @@ final class SessionModel: ObservableObject {
     /// Bounded auto-disconnect for a backgrounded keep-alive session. Fires on `.main`.
     private var backgroundTimer: DispatchSourceTimer?
 
+    /// Holds off display sleep (and, on macOS, the screen saver) for the life of a session —
+    /// nothing about watching a stream looks like user activity to the OS, least of all a
+    /// controller-only session. Acquired in `beginStreaming`, released in `disconnect`.
+    private let displaySleepGuard = DisplaySleepGuard()
+
     /// `allowTofu` gates the trust-on-first-use prompt for an unpinned host: it is only true
     /// when the host EXPLICITLY advertised `pair=optional` (rule 3a). For any other unpinned host
     /// — `pair=required`, a manually-typed host, or a discovered host with no/unknown `pair`
@@ -455,6 +460,8 @@ final class SessionModel: ObservableObject {
     func disconnect(deliberate: Bool = true) {
         statsTimer?.invalidate()
         statsTimer = nil
+        // No-op when this session never reached `.streaming` (a refused/aborted connect).
+        displaySleepGuard.release()
         // Drop any armed background keep-alive (incl. the timeout that just fired us).
         backgroundTimer?.cancel()
         backgroundTimer = nil
@@ -550,6 +557,7 @@ final class SessionModel: ObservableObject {
         // Input capture itself is owned by StreamView (engaged by the captureEnabled
         // flip this phase change causes, released/re-engaged by the user from there).
         phase = .streaming
+        displaySleepGuard.acquire()
         // Audio starts with streaming, not during the trust prompt — no host sound (or
         // mic uplink!) before the user trusted the host. Devices come from Settings;
         // "" = system default.

crates/pf-capture/src/linux/xfixes_cursor.rs

@@ -10,20 +10,31 @@
 //!
 //! **Multiple Xwaylands.** gamescope runs one Xwayland per `--xwayland-count` (Steam Gaming Mode
 //! uses 2: one for Big Picture, one for the game). The pointer lives on whichever is FOCUSED — an
-//! inactive display's pointer is frozen. So the source connects to ALL of them and each tick
+//! inactive display's pointer is frozen. So the source connects to ALL of them and publishes from
-//! follows the one whose pointer actually moved (gamescope routes input to the focused surface, so
+//! the one gamescope is actually drawing the pointer on; it reads that display's shape too, since
-//! exactly one moves at a time). It reads that display's shape too, since each Xwayland has its own
+//! each Xwayland has its own current cursor. This is why a single-display read froze the pointer
-//! current cursor. This is why a single-display read froze the pointer the moment a game on the
+//! the moment a game on the OTHER Xwayland took focus.
-//! OTHER Xwayland took focus.
 //!
-//! Two X sources per display, split by cost (Sunshine's split):
+//! Three X sources per display, split by cost (Sunshine's split, plus gamescope's own verdict):
 //! * **Position** — core `QueryPointer` on the root, polled fast. Cheap (a few-byte reply, no
-//!   bitmap), so it can out-pace the stream fps and keep the composited pointer smooth. It also
+//!   bitmap), so it can out-pace the stream fps and keep the composited pointer smooth.
-//!   doubles as the focus signal (the display whose pointer moves is the active one).
+//! * **Shape / hotspot** — `XFixesGetCursorImage`, refreshed only after an XFixes `CursorNotify`
-//! * **Shape / hotspot / visibility** — `XFixesGetCursorImage`, refreshed only after an XFixes
+//!   (a real cursor change). A fully-transparent image reads as hidden.
-//!   `CursorNotify` (a real cursor change). A game hiding the pointer IS a cursor change → the
+//! * **Visibility + focus** — [`GAMESCOPE_CURSOR_VISIBLE_FEEDBACK`](GS_CURSOR_FEEDBACK) on the
-//!   image comes back fully transparent → `visible: false`, which the encode loop strips before
+//!   root, read at connect and re-read on its `PropertyNotify`.
-//!   any blend path draws it (so a grabbed pointer shows nothing, matching native gamescope).
+//!
+//! **Why the feedback atom and not pointer motion.** gamescope hides its pointer by WARPING the X
+//! pointer to the root's bottom-right corner pixel — it does NOT swap in a transparent X cursor, so
+//! `XFixesGetCursorImage` keeps handing back the last opaque arrow. The original "follow whichever
+//! display's pointer moved" heuristic therefore stuck to the parked display (a parked pointer never
+//! moves again) and composited that arrow at `(w-1, h-1)`: a sliver of cursor welded to the corner
+//! of the stream for the rest of the session, while the real pointer went undrawn. Reported
+//! on-glass as "part of cursor shows up on bottom right … isn't where it really is", in every game
+//! (a game grabs the pointer, so the hide is permanent). Measured on a live 1920x1080 Gaming Mode
+//! session: real motion ⇒ pointer live + feedback `1`; 3 s idle (`--hide-cursor-delay 3000`) ⇒
+//! pointer `(1919, 1079)` + feedback `0`. The atom answers BOTH questions correctly for a static
+//! pointer, which motion cannot: which Xwayland owns it, and whether to draw it at all — so
+//! honouring it also gives the stream gamescope's own idle auto-hide, which this source never had.
 
 use std::sync::{
     atomic::{AtomicBool, Ordering},
@@ -35,7 +46,11 @@ use pf_frame::CursorOverlay;
 use x11rb::connection::Connection;
 use x11rb::errors::ReplyError;
 use x11rb::protocol::xfixes::{self, ConnectionExt as _, GetCursorImageReply};
-use x11rb::protocol::xproto::{ConnectionExt as _, QueryPointerReply, Window};
+use x11rb::protocol::xproto::{
+    Atom, AtomEnum, ChangeWindowAttributesAux, ConnectionExt as _, EventMask, QueryPointerReply,
+    Window,
+};
+use x11rb::protocol::Event;
 use x11rb::rust_connection::RustConnection;
 
 /// Serializes the brief `XAUTHORITY` env swap around a connect (the var is process-global). Only
@@ -47,6 +62,17 @@ static XAUTH_LOCK: Mutex<()> = Mutex::new(());
 /// and must out-run a 240 fps session or the pointer stutters.
 const POLL: Duration = Duration::from_millis(4);
 
+/// gamescope's own pointer verdict, published on EVERY nested Xwayland's root: `1` on the server
+/// whose pointer gamescope is currently drawing, `0` on the others — and `0` on all of them once
+/// the pointer is hidden (a game grabbed it, or `--hide-cursor-delay` fired). See the module docs
+/// for why this, and not pointer motion, is the signal this source follows.
+const GS_CURSOR_FEEDBACK: &str = "GAMESCOPE_CURSOR_VISIBLE_FEEDBACK";
+
+/// Self-heal cadence for the feedback re-read: `PropertyNotify` drives it, this only covers a
+/// missed/coalesced event (and a gamescope that publishes the atom after we connected). One
+/// `GetProperty` per display per interval is nothing next to the 250 Hz pointer poll.
+const FEEDBACK_RESYNC: Duration = Duration::from_millis(250);
+
 /// A running XFixes cursor reader. Dropping it stops the worker thread and joins it, releasing the
 /// X connections — so it lives exactly as long as the capturer that owns it.
 pub(super) struct XFixesCursorSource {
@@ -68,7 +94,9 @@ impl XFixesCursorSource {
         let mut displays = Vec::new();
         for (dpy, xauth) in targets {
             match connect(&dpy, xauth.as_deref()) {
-                Ok((conn, root)) => displays.push(XDisplay::new(dpy, conn, root)),
+                Ok((conn, root, feedback)) => {
+                    displays.push(XDisplay::new(dpy, conn, root, feedback))
+                }
                 Err(e) => tracing::warn!(
                     dpy = %dpy,
                     error = %e,
@@ -84,9 +112,13 @@ impl XFixesCursorSource {
             return None;
         }
         let names: Vec<&str> = displays.iter().map(|d| d.name.as_str()).collect();
+        let feedback = displays.iter().any(|d| d.gs_visible.is_some());
         tracing::info!(
             displays = ?names,
-            "gamescope cursor: XFixes source live — following the focused Xwayland's pointer"
+            cursor_feedback = feedback,
+            "gamescope cursor: XFixes source live — following the Xwayland gamescope draws the \
+             pointer on (cursor_feedback=false ⇒ this gamescope publishes no \
+             GAMESCOPE_CURSOR_VISIBLE_FEEDBACK, degrading to the pointer-motion heuristic)"
         );
 
         let stop = Arc::new(AtomicBool::new(false));
@@ -111,10 +143,15 @@ impl Drop for XFixesCursorSource {
     }
 }
 
-/// Open the X connection, negotiate XFixes, and select cursor-change events — returning the
+/// Open the X connection, negotiate XFixes, and select cursor-change + root-property events —
-/// connection + root window. `RustConnection` reads `XAUTHORITY` from the env at connect time only,
+/// returning the connection, root window and this display's initial
-/// so set it under the lock (the host isn't a gamescope child), connect, then restore.
+/// [`GAMESCOPE_CURSOR_FEEDBACK`](GS_CURSOR_FEEDBACK) reading (`(atom, value)`; the value is `None`
-fn connect(dpy: &str, xauthority: Option<&str>) -> Result<(RustConnection, Window), String> {
+/// when gamescope publishes no such property here). `RustConnection` reads `XAUTHORITY` from the
+/// env at connect time only, so set it under the lock (the host isn't a gamescope child), connect,
+/// then restore.
+type Connected = (RustConnection, Window, (Atom, Option<bool>));
+
+fn connect(dpy: &str, xauthority: Option<&str>) -> Result<Connected, String> {
     let (conn, screen_num) = {
         let _g = XAUTH_LOCK.lock().unwrap_or_else(|e| e.into_inner());
         let prev = std::env::var_os("XAUTHORITY");
@@ -148,8 +185,41 @@ fn connect(dpy: &str, xauthority: Option<&str>) -> Result<(RustConnection, Windo
         .map_err(ReplyError::from)
         .and_then(|c| c.check())
         .map_err(|e| format!("SelectCursorInput: {e}"))?;
+
+    // …and whenever gamescope republishes its cursor verdict. Interned with `only_if_exists=false`
+    // so we hold a matchable atom id even on a gamescope that sets the property later; a failure to
+    // select PROPERTY_CHANGE is NOT fatal — the resync re-read still tracks it, just at 250 ms.
+    let feedback_atom = conn
+        .intern_atom(false, GS_CURSOR_FEEDBACK.as_bytes())
+        .map_err(ReplyError::from)
+        .and_then(|c| c.reply())
+        .map(|r| r.atom)
+        .unwrap_or(0);
+    if let Ok(c) = conn.change_window_attributes(
+        root,
+        &ChangeWindowAttributesAux::new().event_mask(EventMask::PROPERTY_CHANGE),
+    ) {
+        let _ = c.check();
+    }
     let _ = conn.flush();
-    Ok((conn, root))
+    let feedback = read_cursor_feedback(&conn, root, feedback_atom);
+    Ok((conn, root, (feedback_atom, feedback)))
+}
+
+/// Read `GAMESCOPE_CURSOR_VISIBLE_FEEDBACK` off `root`. `None` = the property is absent or
+/// unreadable (not a gamescope that publishes it) — the caller then falls back to the pointer-motion
+/// heuristic rather than blanking the cursor, so an older gamescope keeps today's behaviour.
+fn read_cursor_feedback(conn: &RustConnection, root: Window, atom: Atom) -> Option<bool> {
+    if atom == 0 {
+        return None;
+    }
+    let reply = conn
+        .get_property(false, root, atom, AtomEnum::CARDINAL, 0, 1)
+        .ok()?
+        .reply()
+        .ok()?;
+    let value = reply.value32()?.next()?;
+    Some(value != 0)
 }
 
 /// One gamescope Xwayland the source tracks.
@@ -163,12 +233,22 @@ struct XDisplay {
     shape: Shape,
     /// A `CursorNotify` (or first read) is pending — fetch the shape when this display is active.
     need_shape: bool,
+    /// Interned [`GS_CURSOR_FEEDBACK`] atom (`0` = intern failed — treated as absent).
+    feedback_atom: Atom,
+    /// gamescope's verdict for THIS display: `Some(true)` = it is drawing the pointer here,
+    /// `Some(false)` = it is not, `None` = this gamescope publishes no verdict at all.
+    gs_visible: Option<bool>,
     /// The X connection died (game/Xwayland exited) — skip it.
     dead: bool,
 }
 
 impl XDisplay {
-    fn new(name: String, conn: RustConnection, root: Window) -> Self {
+    fn new(
+        name: String,
+        conn: RustConnection,
+        root: Window,
+        (feedback_atom, gs_visible): (Atom, Option<bool>),
+    ) -> Self {
         XDisplay {
             name,
             conn,
@@ -176,9 +256,20 @@ impl XDisplay {
             last_pos: None,
             shape: Shape::default(),
             need_shape: true,
+            feedback_atom,
+            gs_visible,
             dead: false,
         }
     }
+
+    /// Re-read gamescope's verdict, keeping a previously-seen one if the read fails (a transient
+    /// failure must not look like "this gamescope has no feedback" and re-arm the motion heuristic).
+    fn resync_feedback(&mut self) {
+        let fresh = read_cursor_feedback(&self.conn, self.root, self.feedback_atom);
+        if fresh.is_some() || self.gs_visible.is_none() {
+            self.gs_visible = fresh;
+        }
+    }
 }
 
 /// Cached cursor shape for one display.
@@ -209,20 +300,35 @@ fn run(
     let mut out_serial = 0u64;
     let mut last_key = (usize::MAX, u64::MAX);
     let mut warned_image = false;
+    let mut last_resync = std::time::Instant::now();
 
     while !stop.load(Ordering::Relaxed) {
-        // 1) Poll every display's pointer; note which moved since last tick (the focus signal).
+        // A missed/coalesced PropertyNotify would otherwise strand the verdict — re-read on a slow
+        // cadence so the source always converges (also picks the atom up if gamescope adds it late).
+        let resync = last_resync.elapsed() >= FEEDBACK_RESYNC;
+        if resync {
+            last_resync = std::time::Instant::now();
+        }
+
+        // 1) Poll every display's pointer; note which moved since last tick (the fallback focus
+        //    signal, used only when this gamescope publishes no cursor verdict).
         let mut active_moved = false;
         let mut other_moved: Option<usize> = None;
         for (i, d) in displays.iter_mut().enumerate() {
             if d.dead {
                 continue;
             }
-            // Drain pending events; the only ones selected are CursorNotify, so ANY event means
+            // Drain pending events. Two kinds are selected: XFixes CursorNotify (the shape
-            // "re-read this display's shape". poll_for_event never blocks.
+            // changed) and root PropertyNotify (gamescope republished its cursor verdict, among
+            // the many other properties it keeps on the root — hence the atom match).
+            let mut need_feedback = resync;
             loop {
                 match d.conn.poll_for_event() {
-                    Ok(Some(_)) => d.need_shape = true,
+                    Ok(Some(Event::XfixesCursorNotify(_))) => d.need_shape = true,
+                    Ok(Some(Event::PropertyNotify(ev))) => {
+                        need_feedback |= d.feedback_atom != 0 && ev.atom == d.feedback_atom;
+                    }
+                    Ok(Some(_)) => {}
                     Ok(None) => break,
                     Err(_) => {
                         d.dead = true;
@@ -230,6 +336,9 @@ fn run(
                     }
                 }
             }
+            if need_feedback && !d.dead {
+                d.resync_feedback();
+            }
             match fetch_pointer(&d.conn, d.root) {
                 Ok(p) if p.same_screen => {
                     let pos = (i32::from(p.root_x), i32::from(p.root_y));
@@ -248,13 +357,11 @@ fn run(
             }
         }
 
-        // 2) Switch focus: sticky to the active display while it moves (no flapping); otherwise
+        // 2) Pick the display to publish from, and decide whether a pointer should be drawn at all.
-        //    follow another display that moved. If the active one died, fall to any live display.
+        let states: Vec<(bool, Option<bool>)> =
-        if !active_moved {
+            displays.iter().map(|d| (d.dead, d.gs_visible)).collect();
-            if let Some(j) = other_moved {
+        let hidden_by_gamescope;
-                active = j;
+        (active, hidden_by_gamescope) = pick_active(&states, active, active_moved, other_moved);
-            }
-        }
         if displays.get(active).is_none_or(|d| d.dead) {
             match displays.iter().position(|d| !d.dead) {
                 Some(k) => active = k,
@@ -283,7 +390,11 @@ fn run(
 
         // 4) Publish the ACTIVE display's pointer + shape (or clear the slot when it has no cursor
         //    of its own — so a focus switch never leaves the other display's stale pointer showing).
+        //    A pointer gamescope is not drawing is published `visible: false`, NOT dropped: the
+        //    encode loop overwrites the frame's overlay from this slot and strips invisible ones, so
+        //    a `None` here would leave the last visible overlay standing on repeat frames.
         let d = &displays[active];
+        let drawn = d.shape.visible && !hidden_by_gamescope;
         let overlay = match (d.last_pos, d.shape.rgba.is_empty()) {
             (Some((px, py)), false) => {
                 let key = (active, d.shape.serial);
@@ -301,7 +412,7 @@ fn run(
                     serial: out_serial,
                     hot_x: d.shape.hot_x,
                     hot_y: d.shape.hot_y,
-                    visible: d.shape.visible,
+                    visible: drawn,
                 })
             }
             _ => None,
@@ -314,6 +425,39 @@ fn run(
     }
 }
 
+/// Which display to publish from, and whether gamescope is drawing NO pointer right now —
+/// `(active, hidden)`. `states` is one `(dead, gs_visible)` per display, in `displays` order.
+///
+/// PREFERRED: gamescope's own verdict. It is authoritative for a STATIC pointer, which is exactly
+/// the case motion cannot read — a game grabs the pointer, gamescope parks it in the bottom-right
+/// corner, and "follow whichever moved" then never switches again (see the module docs).
+///
+/// FALLBACK, only when NO live display publishes the verdict: the original motion heuristic —
+/// sticky to the active display while its pointer moves (no flapping), else follow another that
+/// moved. `hidden` is never asserted on this path, so an older gamescope keeps today's behaviour.
+fn pick_active(
+    states: &[(bool, Option<bool>)],
+    active: usize,
+    active_moved: bool,
+    other_moved: Option<usize>,
+) -> (usize, bool) {
+    let live = |&(dead, _): &(bool, Option<bool>)| !dead;
+    if states.iter().filter(|s| live(s)).any(|(_, v)| v.is_some()) {
+        return match states.iter().position(|s| live(s) && s.1 == Some(true)) {
+            // gamescope is drawing the pointer here — publish from it.
+            Some(i) => (i, false),
+            // Drawing none of them (a game grabbed it, or the idle auto-hide fired). Keep `active`
+            // so the shape cache and last position stay warm for the re-show; the caller publishes
+            // the overlay `visible: false` instead of dropping it.
+            None => (active, true),
+        };
+    }
+    match other_moved {
+        Some(j) if !active_moved => (j, false),
+        _ => (active, false),
+    }
+}
+
 /// Update `shape` from a fresh `GetCursorImage` reply. A hidden pointer (all-transparent) keeps the
 /// last bitmap (instant re-show) but flips visibility; the serial still bumps so the change shows.
 fn update_shape(shape: &mut Shape, img: &GetCursorImageReply) {
@@ -364,3 +508,60 @@ fn argb_premul_to_straight_rgba(argb: &[u32]) -> Vec<u8> {
     }
     out
 }
+
+#[cfg(test)]
+mod tests {
+    use super::pick_active;
+
+    /// Steam Gaming Mode shape: display 0 = Big Picture's Xwayland, 1 = the game's.
+    const BPM: usize = 0;
+    const GAME: usize = 1;
+
+    #[test]
+    fn follows_the_display_gamescope_draws_on() {
+        // Verdict beats motion: gamescope says the game's Xwayland owns the pointer, so we publish
+        // from it even though only BPM's (parked) pointer looks like it moved.
+        let states = [(false, Some(false)), (false, Some(true))];
+        assert_eq!(pick_active(&states, BPM, false, Some(BPM)), (GAME, false));
+    }
+
+    /// THE REGRESSION: gamescope hides the pointer by warping it to the root's bottom-right corner
+    /// and leaves the opaque arrow as the X cursor. Nothing moves ever again, so the motion
+    /// heuristic stayed on the parked display and composited that arrow at (w-1, h-1) — a sliver of
+    /// cursor welded to the corner of the stream for the whole session, in every game.
+    #[test]
+    fn a_pointer_gamescope_draws_nowhere_is_hidden_not_parked() {
+        let states = [(false, Some(false)), (false, Some(false))];
+        // `active` is kept (shape cache + last position stay warm for the re-show) but hidden.
+        assert_eq!(pick_active(&states, GAME, false, None), (GAME, true));
+    }
+
+    #[test]
+    fn re_show_returns_to_the_drawing_display() {
+        let states = [(false, Some(true)), (false, Some(false))];
+        assert_eq!(pick_active(&states, GAME, false, None), (BPM, false));
+    }
+
+    #[test]
+    fn a_dead_displays_verdict_is_ignored() {
+        // The game's Xwayland exited mid-session with a stale `Some(true)`; BPM is the live one.
+        let states = [(false, Some(true)), (true, Some(true))];
+        assert_eq!(pick_active(&states, GAME, false, None), (BPM, false));
+        // …and a dead display's `Some` must not count as "this gamescope publishes a verdict",
+        // which would blank the cursor forever on a gamescope that publishes none.
+        let states = [(false, None), (true, Some(false))];
+        assert_eq!(pick_active(&states, BPM, false, Some(GAME)), (GAME, false));
+    }
+
+    #[test]
+    fn no_verdict_falls_back_to_the_motion_heuristic() {
+        let none = [(false, None), (false, None)];
+        // Sticky while the active display's own pointer moves…
+        assert_eq!(pick_active(&none, BPM, true, Some(GAME)), (BPM, false));
+        // …otherwise follow the one that moved…
+        assert_eq!(pick_active(&none, BPM, false, Some(GAME)), (GAME, false));
+        // …and never assert `hidden` on this path (that would regress an older gamescope to a
+        // cursorless stream).
+        assert_eq!(pick_active(&none, BPM, false, None), (BPM, false));
+    }
+}

crates/pf-inject/src/inject/windows/pointer_windows.rs

@@ -26,6 +26,11 @@ use punktfunk_core::quic::{
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex};
 use windows::Win32::Foundation::POINT;
+use windows::Win32::System::StationsAndDesktops::{
+    CloseDesktop, GetThreadDesktop, OpenInputDesktop, SetThreadDesktop, DESKTOP_ACCESS_FLAGS,
+    DESKTOP_CONTROL_FLAGS, HDESK,
+};
+use windows::Win32::System::Threading::GetCurrentThreadId;
 use windows::Win32::UI::Controls::{
     CreateSyntheticPointerDevice, DestroySyntheticPointerDevice, HSYNTHETICPOINTERDEVICE,
     POINTER_FEEDBACK_DEFAULT, POINTER_TYPE_INFO, POINTER_TYPE_INFO_0,
@@ -46,6 +51,101 @@ use windows::Win32::UI::WindowsAndMessaging::{
 /// 50 ms against the ~100 ms staleness window; 40 ms keeps two refreshes inside it.
 const REFRESH_MS: u64 = 40;
 
+/// `GENERIC_ALL` for the desktop open — the `windows` crate models desktop rights as their own
+/// flag type and doesn't re-export the generic ones (same constant `sendinput.rs` uses).
+const DESKTOP_GENERIC_ALL: u32 = 0x1000_0000;
+
+/// This thread's binding to the input desktop, restored on drop.
+///
+/// `SendInput` (`sendinput.rs`) solves the same problem by binding its DEDICATED injector thread
+/// once and keeping it. That can't be borrowed here: `inject_pen`/`inject_touch_frame` are driven
+/// from TWO threads — the caller's `apply_batch` and the `pf-pen-refresh`/`pf-touch-refresh`
+/// staleness threads — and the batch caller is a shared task thread, which must not be left parked
+/// on a `Winlogon` desktop that disappears when the prompt is dismissed. So the binding is scoped
+/// to the retry: `GetThreadDesktop` hands back a BORROWED handle (never closed), and only the
+/// `OpenInputDesktop` handle is closed, after the thread has moved back off it.
+struct InputDesktopBinding {
+    previous: HDESK,
+    input: HDESK,
+}
+
+impl InputDesktopBinding {
+    fn bind() -> Option<Self> {
+        // SAFETY: FFI calls taking by-value args only. `OpenInputDesktop` yields an owned `HDESK`
+        // solely on `Ok`; it is either installed by `SetThreadDesktop` (then owned by this guard,
+        // closed exactly once in `Drop`) or closed here on failure — closed once on every path,
+        // never used after. `SetThreadDesktop` rebinds only the calling thread, which owns no
+        // windows or hooks, so it cannot fail on that account.
+        unsafe {
+            let previous = GetThreadDesktop(GetCurrentThreadId()).ok()?;
+            let input = OpenInputDesktop(
+                DESKTOP_CONTROL_FLAGS(0),
+                false,
+                DESKTOP_ACCESS_FLAGS(DESKTOP_GENERIC_ALL),
+            )
+            .ok()?;
+            if SetThreadDesktop(input).is_err() {
+                let _ = CloseDesktop(input);
+                return None;
+            }
+            Some(Self { previous, input })
+        }
+    }
+}
+
+impl Drop for InputDesktopBinding {
+    fn drop(&mut self) {
+        // SAFETY: `previous` is the borrowed desktop this thread started on, `input` the handle
+        // this guard uniquely owns. The thread moves back FIRST, so the handle is not the thread's
+        // desktop when closed — closed exactly once, never used after.
+        unsafe {
+            let _ = SetThreadDesktop(self.previous);
+            let _ = CloseDesktop(self.input);
+        }
+    }
+}
+
+/// Inject one synthetic-pointer frame, following the input desktop if Windows refuses it.
+///
+/// While a UAC consent prompt (or the lock / logon screen) owns input, the secure desktop does, and
+/// injection from the host's own `WinSta0\Default` thread comes back `ERROR_ACCESS_DENIED` — which
+/// is why pen and touch went dead on a prompt a user could SEE in the stream (capture already
+/// renders it, and `SendInput` mouse/keyboard already followed the switch, so only these two were
+/// left behind). Field-reported 2026-07-23; the exact rc reproduced in a probe the same night.
+///
+/// Measured then, with a real consent prompt up and a SYSTEM host in the console session:
+///
+/// ```text
+/// device created on Default, thread on Default        -> 0x80070005  (the field failure)
+/// device created on Default, thread on INPUT desktop   -> OK
+/// device created on INPUT,   thread on INPUT desktop   -> OK
+/// ```
+///
+/// The middle row is the load-bearing one: the synthetic pointer device is NOT desktop-affine, so
+/// rebinding the THREAD is sufficient and the device never has to be destroyed and recreated
+/// across a desktop switch (which would drop in-flight contacts and the pen's in-range state).
+///
+/// # Safety
+/// `dev` must be a live synthetic-pointer device and `frame` a live slice for the call.
+unsafe fn inject_following_desktop(
+    dev: HSYNTHETICPOINTERDEVICE,
+    frame: &[POINTER_TYPE_INFO],
+) -> windows::core::Result<()> {
+    // SAFETY: per this fn's contract — `dev` is live and `frame` outlives the call, which only
+    // reads it. Best-effort, exactly as the direct call was.
+    match InjectSyntheticPointerInput(dev, frame) {
+        Ok(()) => Ok(()),
+        Err(first) => {
+            // Only a desktop switch is worth a rebind; anything else would just fail identically.
+            let Some(_binding) = InputDesktopBinding::bind() else {
+                return Err(first);
+            };
+            // SAFETY: same live `dev`/`frame`, re-issued with this thread on the input desktop.
+            InjectSyntheticPointerInput(dev, frame)
+        }
+    }
+}
+
 /// Windows pen pressure is 0..1024 (vs the wire's full-scale u16).
 const WIN_PEN_PRESSURE_MAX: u32 = 1024;
 
@@ -340,10 +440,22 @@ fn inject_pen(sh: &mut PenShared, edge: POINTER_FLAGS, is_new: bool) {
     // SAFETY: `sh.dev.0` is the live device this wrapper owns; the one-element array is a live
     // stack value the call only reads. Best-effort like every injector write — a transient
     // failure (desktop switch) is healed by the next refresh tick re-asserting state.
-    if let Err(e) = unsafe { InjectSyntheticPointerInput(sh.dev.0, &[info]) } {
+    if let Err(e) = unsafe { inject_following_desktop(sh.dev.0, &[info]) } {
         if !sh.fail_warned {
             sh.fail_warned = true;
-            tracing::warn!(error = %e, "pen inject failed");
+            tracing::warn!(
+                error = %e,
+                flags = format!("{:#x}", flags.0),
+                pen_flags = format!("{pen_flags:#x}"),
+                pen_mask = format!("{pen_mask:#x}"),
+                pressure,
+                rotation,
+                tilt_x,
+                tilt_y,
+                x = pt.x,
+                y = pt.y,
+                "pen inject failed"
+            );
         } else {
             tracing::trace!(error = %e, "pen inject failed (transient)");
         }
@@ -543,7 +655,7 @@ fn inject_touch_frame(sh: &mut TouchShared, edge: Option<(u32, POINTER_FLAGS)>)
     }
     // SAFETY: `sh.dev.0` is the live owned device; `frame` is a live Vec the call only reads.
     // Best-effort — a transient failure heals on the next event/refresh re-assertion.
-    if let Err(e) = unsafe { InjectSyntheticPointerInput(sh.dev.0, &frame) } {
+    if let Err(e) = unsafe { inject_following_desktop(sh.dev.0, &frame) } {
         if !sh.fail_warned {
             sh.fail_warned = true;
             tracing::warn!(error = %e, contacts = frame.len(), "touch inject failed");

crates/pf-vdisplay/src/vdisplay/linux/kwin.rs

@@ -210,14 +210,16 @@ impl VirtualDisplay for KwinDisplay {
         // resize handling: when the source's texture size changes while recording, KWin re-runs
         // `buildFormats` — picking up the output's CURRENT refresh — and renegotiates the live
         // stream via `pw_stream_update_params`. So above 60 Hz the output is born at a
-        // SACRIFICIAL height: installing + selecting the real `WxH@hz` custom mode (supported on
+        // SACRIFICIAL height: installing + selecting the real high-refresh custom mode (supported
-        // virtual outputs since KWin 6.6) then changes the SIZE, and the first buffers recorded
+        // on virtual outputs since KWin 6.6) then changes the SIZE, and the first buffers recorded
-        // after the consumer connects trigger KWin's resize → a renegotiation to `WxH@hz`. The
+        // after the consumer connects trigger KWin's resize → a renegotiation to that mode. The
         // capturer holds frames until that lands (`expect_exact_dims`), so the pipeline never
         // builds against the birth mode. First cut shells out to kscreen-doctor; the in-process
         // kde_output_management_v2 client is a follow-up. `set_custom_refresh` reads back what
-        // KWin *actually* gave so the encoder paces to the real source rate. At ≤60 Hz there's
+        // KWin *actually* gave — both the rate (so the encoder paces to the real source) and the
-        // nothing to install — the output is born at the real size and 60 Hz is the offer anyway.
+        // size, which KWin's CVT generator may have aligned down (see `CVT_H_GRANULARITY`). At
+        // ≤60 Hz there's nothing to install — the output is born at the real size and 60 Hz is the
+        // offer anyway.
         let want_high = mode.refresh_hz > 60;
         let birth_h = if want_high { height + 16 } else { height };
         let (mut node_id, mut stop) = spawn_vout(width, birth_h)?;
@@ -241,36 +243,52 @@ impl VirtualDisplay for KwinDisplay {
         let mut addr = resolve_kscreen_addr(&name, width, birth_h);
         self.last_name = Some(addr.clone()); // for apply_position (registry-driven §6.2 layout)
         let mut expect_exact_dims = false;
+        // The size the output actually ENDS UP at — the request, unless KWin's CVT generator had to
+        // shrink the width to the cell grain (see `CVT_H_GRANULARITY`). Reported as the output's
+        // `preferred_mode`, which is what the capturer's renegotiation gate waits for and what the
+        // encoder opens against, so a CVT-aligned mode flows end-to-end instead of starving.
+        let mut final_dims = (width, height);
         let achieved_hz = if want_high {
-            let (achieved, size_applied) =
+            let active = set_custom_refresh(width, height, mode.refresh_hz, &addr);
-                set_custom_refresh(width, height, mode.refresh_hz, &addr);
+            // Accept only an active mode that IS our custom one: the exact requested height, and a
-            if size_applied {
+            // width at or just below the request (a CVT alignment). That also proves the output
-                // Real mode selected: the recording stream will renegotiate to it (see above).
+            // left the sacrificial birth size, so the recording stream will renegotiate to it.
-                expect_exact_dims = true;
+            match active {
-                achieved
+                Some((aw, ah, ahz))
-            } else {
+                    if ah == height && aw <= width && width - aw < CVT_H_GRANULARITY =>
-                // Custom-mode install/select rejected (pre-6.6 KWin / stale kscreen-doctor): the
+                {
-                // output is STUCK at the sacrificial birth size — unusable. Recreate plain at the
+                    expect_exact_dims = true;
-                // real size (the pre-sacrifice behavior: correct size, KWin's native 60 Hz).
+                    final_dims = (aw, ah);
-                tracing::warn!(
+                    ahz
-                    "KWin rejected the custom mode — recreating the virtual output at the real \
+                }
-                     size (60 Hz ceiling on this KWin)"
+                other => {
-                );
+                    // Custom-mode install/select rejected (pre-6.6 KWin / stale kscreen-doctor): the
-                stop.store(true, Ordering::Relaxed);
+                    // output is STUCK at the sacrificial birth size — unusable. Recreate plain at the
-                // Let KWin retire the doomed output before re-using its name.
+                    // real size (the pre-sacrifice behavior: correct size, KWin's native 60 Hz).
-                std::thread::sleep(Duration::from_millis(300));
+                    tracing::warn!(
-                let (nid, st) = spawn_vout(width, height)?;
+                        active = ?other,
-                node_id = nid;
+                        requested_w = width,
-                stop = st;
+                        requested_h = height,
-                addr = resolve_kscreen_addr(&name, width, height);
+                        requested_hz = mode.refresh_hz,
-                self.last_name = Some(addr.clone());
+                        "KWin rejected the custom mode — recreating the virtual output at the real \
-                tracing::info!(
+                         size (60 Hz ceiling on this KWin)"
-                    node_id,
+                    );
-                    width,
+                    stop.store(true, Ordering::Relaxed);
-                    height,
+                    // Let KWin retire the doomed output before re-using its name.
-                    "KWin virtual output ready (fallback)"
+                    std::thread::sleep(Duration::from_millis(300));
-                );
+                    let (nid, st) = spawn_vout(width, height)?;
-                60
+                    node_id = nid;
+                    stop = st;
+                    addr = resolve_kscreen_addr(&name, width, height);
+                    self.last_name = Some(addr.clone());
+                    tracing::info!(
+                        node_id,
+                        width,
+                        height,
+                        "KWin virtual output ready (fallback)"
+                    );
+                    60
+                }
             }
         } else {
             mode.refresh_hz
@@ -302,7 +320,7 @@ impl VirtualDisplay for KwinDisplay {
         // (it owns the display group, so it computes auto-row / manual placement over the whole group).
         let mut out = VirtualOutput::owned(
             node_id,
-            Some((mode.width, mode.height, achieved_hz)),
+            Some((final_dims.0, final_dims.1, achieved_hz)),
             Box::new(StopGuard { stop }),
         );
         out.expect_exact_dims = expect_exact_dims;
@@ -415,16 +433,116 @@ fn output_active_size(o: &serde_json::Value) -> Option<(u32, u32)> {
     ))
 }
 
-/// Best-effort: install + select the `width`x`height`@`hz` custom mode on the just-created
+/// CVT's horizontal cell granularity. KWin generates every custom mode's timing with **libxcvt**,
-/// virtual output via `kscreen-doctor` (`output` is the RESOLVED kscreen address — numeric id or
+/// whose first step is `hdisplay_rnd = hdisplay - (hdisplay % 8)` — so a width that isn't a multiple
-/// name, see [`resolve_kscreen_addr`] — refresh given in mHz), then **read back the active mode**
+/// of 8 comes back NARROWER than asked, and the clock-step rounding that follows lands a fractional
-/// and return `(achieved_hz, size_applied)`. The apply command can report success yet leave the
+/// refresh. A 2868x1320@120 request (an iPhone 16 Pro Max panel) becomes **2864x1320@119.92**.
-/// output on its old mode (rejected), and a silent rate mismatch surfaces downstream as judder /
+///
-/// duplicated frames — so the caller paces the encoder to the *achieved* rate, not the requested
+/// That is why a custom mode must never be selected by the `WxH@Hz` string we *requested*:
-/// one. `size_applied` tells the sacrificial-birth caller (see `create`) whether the SIZE half of
+/// kscreen-doctor's `findMode` matches a mode's id or its own `WxH@qRound(Hz)` name, so
-/// the mode actually landed — that, not the refresh, is what triggers KWin's stream
+/// `2868x1320@120` matches nothing, the select silently no-ops, the output stays on its sacrificial
-/// renegotiation.
+/// birth mode, and the caller falls back to 60 Hz — while KDE's display list shows the perfectly
-fn set_custom_refresh(width: u32, height: u32, hz: u32, output: &str) -> (u32, bool) {
+/// good 2864x1320@119.92 mode sitting there unselected. Widths like 1920/2560/3840 are all
+/// multiples of 8, which is why only phone-shaped clients ever hit it.
+const CVT_H_GRANULARITY: u32 = 8;
+
+/// One row of an output's mode list, as parsed from `kscreen-doctor -j`.
+#[derive(Clone, Debug, PartialEq)]
+struct KModeRow {
+    /// kscreen's mode id — what we address the mode by (never the requested `WxH@Hz` string).
+    id: String,
+    w: u32,
+    h: u32,
+    hz: f64,
+}
+
+/// A kscreen JSON id, which is a string on some KWin versions and a number on others.
+fn json_id(v: &serde_json::Value) -> Option<String> {
+    v.as_str()
+        .map(|s| s.to_string())
+        .or_else(|| v.as_u64().map(|n| n.to_string()))
+}
+
+/// The full mode list of `output` (a RESOLVED kscreen address — numeric id or name) from a parsed
+/// `kscreen-doctor -j` document. Split from the process call so the picker can be tested on
+/// captured JSON.
+fn modes_from_json(doc: &serde_json::Value, output: &str) -> Vec<KModeRow> {
+    let Some(o) = doc
+        .get("outputs")
+        .and_then(|v| v.as_array())
+        .and_then(|outs| {
+            outs.iter().find(|o| {
+                o.get("name").and_then(|n| n.as_str()) == Some(output)
+                    || o.get("id").and_then(json_id).as_deref() == Some(output)
+            })
+        })
+    else {
+        return Vec::new();
+    };
+    o.get("modes")
+        .and_then(|m| m.as_array())
+        .map(|ms| {
+            ms.iter()
+                .filter_map(|m| {
+                    let size = m.get("size")?;
+                    Some(KModeRow {
+                        id: m.get("id").and_then(json_id)?,
+                        w: size.get("width").and_then(|v| v.as_u64())? as u32,
+                        h: size.get("height").and_then(|v| v.as_u64())? as u32,
+                        hz: m.get("refreshRate").and_then(|r| r.as_f64())?,
+                    })
+                })
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+/// [`modes_from_json`] against a live `kscreen-doctor -j`.
+fn output_modes(output: &str) -> Vec<KModeRow> {
+    kscreen_json()
+        .map(|doc| modes_from_json(&doc, output))
+        .unwrap_or_default()
+}
+
+/// The mode in `modes` that actually fulfils a `width`x`height`@`hz` request, tolerating the CVT
+/// alignment KWin applies when it generates the timing (see [`CVT_H_GRANULARITY`]): the height must
+/// match exactly (CVT never touches the vertical active), the width may be up to one cell narrower
+/// than asked (never wider — that would be a different mode), and the refresh must land within 1 Hz
+/// of the request (which excludes the output's native 60 Hz entry for every rate we install a custom
+/// mode for). Widest wins, then fastest — so an exact-width mode always beats an aligned one, and a
+/// list carrying duplicate custom modes from earlier sessions still resolves.
+fn pick_custom_mode<'a>(
+    modes: &'a [KModeRow],
+    width: u32,
+    height: u32,
+    hz: u32,
+) -> Option<&'a KModeRow> {
+    modes
+        .iter()
+        .filter(|m| {
+            m.h == height
+                && m.w <= width
+                && width - m.w < CVT_H_GRANULARITY
+                && (m.hz - f64::from(hz)).abs() < 1.0
+        })
+        .max_by(|a, b| {
+            a.w.cmp(&b.w)
+                .then(a.hz.partial_cmp(&b.hz).unwrap_or(std::cmp::Ordering::Equal))
+        })
+}
+
+/// Best-effort: install + select the `width`x`height`@`hz` custom mode on the just-created virtual
+/// output via `kscreen-doctor` (`output` is the RESOLVED kscreen address — numeric id or name, see
+/// [`resolve_kscreen_addr`] — refresh given in mHz), then **read back the active mode** and return
+/// it as `(width, height, refresh_hz)`. `None` if the read-back failed entirely.
+///
+/// The apply command can report success yet leave the output on its old mode (rejected), and a
+/// silent size/rate mismatch surfaces downstream as a starved capture gate or judder — so the
+/// caller drives the pipeline off the *achieved* mode, not the requested one. The mode is selected
+/// by kscreen **mode id** resolved from the output's own list, never by the requested `WxH@Hz`
+/// string, because KWin's CVT generator may hand back a slightly different one
+/// ([`CVT_H_GRANULARITY`]).
+fn set_custom_refresh(width: u32, height: u32, hz: u32, output: &str) -> Option<(u32, u32, u32)> {
     let output = output.to_string();
     let mhz = hz.saturating_mul(1000);
     let run = |arg: String| {
@@ -434,21 +552,71 @@ fn set_custom_refresh(width: u32, height: u32, hz: u32, output: &str) -> (u32, b
             .map(|s| s.success())
             .unwrap_or(false)
     };
-    // Add the custom mode (a fresh output has none), then select it.
+    // Install the mode only if the output doesn't already carry a usable one: kscreen-doctor
-    let _ = run(format!(
+    // APPENDS to the output's custom-mode list and KWin PERSISTS that list per output name
-        "output.{output}.addCustomMode.{width}.{height}.{mhz}.full"
+    // (`kwinoutputconfig.json`, which is why the same per-slot name is reused across sessions) — so
-    ));
+    // re-adding on every connect would grow the user's display list without bound.
-    let applied = run(format!("output.{output}.mode.{width}x{height}@{hz}"));
+    let mut modes = output_modes(&output);
+    if pick_custom_mode(&modes, width, height, hz).is_none() {
+        let _ = run(format!(
+            "output.{output}.addCustomMode.{width}.{height}.{mhz}.full"
+        ));
+        modes = output_modes(&output);
+    }
+    let applied = match pick_custom_mode(&modes, width, height, hz) {
+        Some(target) => {
+            if (target.w, target.h) != (width, height) {
+                tracing::info!(
+                    output,
+                    requested_w = width,
+                    requested_h = height,
+                    mode_w = target.w,
+                    mode_h = target.h,
+                    mode_hz = target.hz,
+                    "KWin aligned the custom mode to the CVT cell grain — streaming at its size"
+                );
+            }
+            // By id first; the human `WxH@Hz` form (built from the mode's OWN size/refresh, not the
+            // request) is the fallback for builds whose ids don't round-trip through the CLI.
+            run(format!("output.{output}.mode.{}", target.id))
+                || run(format!(
+                    "output.{output}.mode.{}x{}@{}",
+                    target.w,
+                    target.h,
+                    target.hz.round() as u32
+                ))
+        }
+        None => {
+            tracing::warn!(
+                output,
+                requested_w = width,
+                requested_h = height,
+                requested_hz = hz,
+                offered = ?modes,
+                "KWin offers no mode matching the request after addCustomMode — is kscreen-doctor \
+                 up to date, and KWin ≥ 6.6 (custom modes on virtual outputs)?"
+            );
+            false
+        }
+    };
     match read_active_mode(&output) {
         Some((w, h, achieved)) => {
-            let size_applied = (w, h) == (width, height);
+            if achieved >= hz && (w, h) == (width, height) {
-            if achieved >= hz && size_applied {
                 tracing::info!(
                     output,
                     requested = hz,
                     achieved,
                     "KWin virtual output: custom refresh applied"
                 );
+            } else if achieved >= hz {
+                tracing::info!(
+                    output,
+                    requested = hz,
+                    achieved,
+                    active_w = w,
+                    active_h = h,
+                    "KWin virtual output: custom refresh applied at a CVT-aligned size"
+                );
             } else {
                 tracing::warn!(
                     output,
@@ -461,7 +629,7 @@ fn set_custom_refresh(width: u32, height: u32, hz: u32, output: &str) -> (u32, b
                      achieved rate (custom-mode install rejected? is kscreen-doctor up to date?)"
                 );
             }
-            (achieved.max(1), size_applied)
+            Some((w, h, achieved.max(1)))
         }
         None => {
             tracing::warn!(
@@ -471,7 +639,7 @@ fn set_custom_refresh(width: u32, height: u32, hz: u32, output: &str) -> (u32, b
                 "could not read back KWin virtual output refresh — assuming 60 Hz (is \
                  kscreen-doctor installed?)"
             );
-            (60, false)
+            None
         }
     }
 }
@@ -884,7 +1052,88 @@ fn run(
 
 #[cfg(test)]
 mod tests {
-    use super::MANAGED_PREFIX;
+    use super::{modes_from_json, pick_custom_mode, KModeRow, MANAGED_PREFIX};
+
+    fn row(id: &str, w: u32, h: u32, hz: f64) -> KModeRow {
+        KModeRow {
+            id: id.to_string(),
+            w,
+            h,
+            hz,
+        }
+    }
+
+    /// The reported regression: an iPhone 16 Pro Max asks for 2868x1320@120; libxcvt rounds the
+    /// width down to the 8-pixel cell grain and the clock step lands 119.92, so KWin's list holds
+    /// 2864x1320@119.92. Selecting by the REQUESTED `2868x1320@120` string matched nothing — the
+    /// output stayed on its birth mode and the session fell back to 60 Hz. The picker must find it.
+    #[test]
+    fn picks_the_cvt_aligned_mode() {
+        let modes = [
+            row("1", 2868, 1320, 60.0),   // the virtual output's native/birth mode
+            row("2", 2864, 1320, 119.92), // the custom mode KWin actually generated
+        ];
+        let got = pick_custom_mode(&modes, 2868, 1320, 120).expect("CVT-aligned mode");
+        assert_eq!((got.id.as_str(), got.w, got.h), ("2", 2864, 1320));
+    }
+
+    /// A width already on the cell grain (every PC resolution: 1920/2560/3840) round-trips exactly,
+    /// and an exact-width mode outranks an aligned one when both are offered.
+    #[test]
+    fn exact_width_outranks_an_aligned_one() {
+        let modes = [
+            row("1", 2560, 1440, 60.0),
+            row("2", 2552, 1440, 119.93), // a stale narrower custom mode from an earlier session
+            row("3", 2560, 1440, 119.98),
+        ];
+        let got = pick_custom_mode(&modes, 2560, 1440, 120).expect("exact mode");
+        assert_eq!(got.id, "3");
+    }
+
+    /// The picker must never wander onto an unrelated mode: not the 60 Hz native entry (the old
+    /// fallback the reporter got stuck on), not a different height, not a wider width, and not a
+    /// mode more than one cell narrower than asked.
+    #[test]
+    fn rejects_modes_that_are_not_the_request() {
+        let modes = [
+            row("1", 2868, 1320, 60.0),   // native — refresh too far off
+            row("2", 2868, 1080, 119.92), // wrong height
+            row("3", 2880, 1320, 119.92), // wider than requested
+            row("4", 2856, 1320, 119.92), // two cells narrower — not a CVT alignment of 2868
+            row("5", 1920, 1080, 120.0),  // unrelated
+        ];
+        assert!(pick_custom_mode(&modes, 2868, 1320, 120).is_none());
+    }
+
+    /// Mode + output ids come through as JSON strings on some KWin versions and numbers on others;
+    /// both must parse, and a mode row missing its size/refresh is skipped rather than poisoning
+    /// the list.
+    #[test]
+    fn parses_both_id_encodings() {
+        let doc: serde_json::Value = serde_json::from_str(
+            r#"{"outputs":[
+                 {"id":7,"name":"Virtual-punktfunk","modes":[
+                   {"id":"m1","size":{"width":2868,"height":1320},"refreshRate":60.0},
+                   {"id":42,"size":{"width":2864,"height":1320},"refreshRate":119.92},
+                   {"id":"broken","size":{"width":800}}
+                 ]},
+                 {"id":1,"name":"eDP-1","modes":[
+                   {"id":"x","size":{"width":2864,"height":1320},"refreshRate":119.92}
+                 ]}
+               ]}"#,
+        )
+        .expect("fixture parses");
+        // Addressable by numeric id (how `resolve_kscreen_addr` returns it) and by name.
+        for addr in ["7", "Virtual-punktfunk"] {
+            let modes = modes_from_json(&doc, addr);
+            assert_eq!(modes.len(), 2, "the malformed row is dropped ({addr})");
+            assert_eq!(modes[1].id, "42", "numeric mode ids stringify ({addr})");
+            let got = pick_custom_mode(&modes, 2868, 1320, 120).expect("aligned mode");
+            assert_eq!(got.id, "42");
+        }
+        // Never reads another output's list (the eDP-1 entry carries a matching mode).
+        assert!(modes_from_json(&doc, "Virtual-nope").is_empty());
+    }
 
     /// Group-aware exclusive (§6.1): with two managed group members + a physical panel enabled,
     /// exclusive disables ONLY the non-managed panel — never a sibling session's per-slot output

crates/pf-win-display/Cargo.toml

@@ -31,5 +31,8 @@ windows = { version = "0.62", features = [
     "Win32_System_LibraryLoader",
     # console_session_mismatch: WTSGetActiveConsoleSessionId + ProcessIdToSessionId + GetCurrentProcessId.
     "Win32_System_RemoteDesktop",
+    # input_desktop: OpenInputDesktop/SetThreadDesktop/GetUserObjectInformationW — display writes
+    # follow the input desktop so a UAC/lock screen can't refuse them.
+    "Win32_System_StationsAndDesktops",
     "Win32_System_Threading",
 ] }

crates/pf-win-display/src/input_desktop.rs

@@ -0,0 +1,200 @@
+//! Make display-config writes follow the INPUT desktop.
+//!
+//! Windows refuses `ChangeDisplaySettingsEx` / `SetDisplayConfig` issued from a thread that is not
+//! on the desktop currently receiving input. While a UAC consent prompt (or the lock / logon
+//! screen) is up, the input desktop is `Winlogon`; a host thread sitting on `WinSta0\Default` — the
+//! desktop the service explicitly launches it onto — then gets `DISP_CHANGE_FAILED` /
+//! `ERROR_ACCESS_DENIED` for EVERY write. A session starting in that window can never set its
+//! virtual display's mode, so the capturer sizes its ring to a stale mode, every composed frame is
+//! dropped for a size mismatch, and the client sits on a black screen until bring-up runs out of
+//! retries. Field-reported 2026-07-23: a consent prompt left up on an unattended host made the box
+//! unreachable until someone walked over to it.
+//!
+//! Measured on-glass that same day (RTX 4090 box, SYSTEM host in console session 2, a real
+//! interactive consent prompt up, virtual display `\\.\DISPLAY42` active):
+//!
+//! ```text
+//! INPUT desktop = Winlogon
+//! UNBOUND  CDS_TEST      -> -1 (DISP_CHANGE_FAILED)      <- the field failure, reproduced
+//! UNBOUND  SDC_VALIDATE  -> 0x5 (ERROR_ACCESS_DENIED)    <- the field failure, reproduced
+//! bound thread desktop -> Winlogon
+//! BOUND    CDS_TEST      ->  0 (DISP_CHANGE_SUCCESSFUL)
+//! BOUND    SDC_VALIDATE  -> 0x0 (ERROR_SUCCESS)
+//! ```
+//!
+//! The retry model mirrors `pf-inject`'s `sendinput.rs`: do NOT pay
+//! `OpenInputDesktop`/`SetThreadDesktop` on every write — issue the write, and only when it fails
+//! the way a wrong-desktop write fails do we rebind and retry once. That keeps the normal path
+//! byte-for-byte as it was (a working write is never touched) and makes this strictly additive.
+//!
+//! Unlike sendinput's injector — a dedicated thread that KEEPS its binding — these helpers run on
+//! shared/task threads, so the binding here is SCOPED: [`InputDesktopBinding`] restores the
+//! thread's original desktop on drop. A thread left bound to a `Winlogon` desktop that is later
+//! destroyed (prompt dismissed) would fail every subsequent display write for the life of the
+//! process — the exact wedge this module exists to remove, so it must not be introduced here.
+
+use windows::Win32::Foundation::HANDLE;
+use windows::Win32::System::StationsAndDesktops::{
+    CloseDesktop, GetThreadDesktop, GetUserObjectInformationW, OpenInputDesktop, SetThreadDesktop,
+    DESKTOP_ACCESS_FLAGS, DESKTOP_CONTROL_FLAGS, HDESK, UOI_NAME,
+};
+use windows::Win32::System::Threading::GetCurrentThreadId;
+
+/// `GENERIC_ALL` for the desktop open. The `windows` crate models desktop access as its own flag
+/// type and doesn't export the generic rights, so spell it out (same constant `sendinput.rs` and
+/// the cursor poller use).
+const GENERIC_ALL: u32 = 0x1000_0000;
+
+/// This thread's binding to the input desktop, restored on drop.
+///
+/// `GetThreadDesktop` returns a BORROWED handle (documented: it creates no new handle and must not
+/// be closed), so only the handle `OpenInputDesktop` produced is closed here — and only after the
+/// thread has been moved back off it.
+pub(crate) struct InputDesktopBinding {
+    previous: HDESK,
+    input: HDESK,
+    /// `UOI_NAME` of the desktop bound to, for the "this write only landed because we rebound"
+    /// log. Read once at bind time (the failure path only), never in steady state.
+    name: String,
+}
+
+impl InputDesktopBinding {
+    /// Bind the calling thread to the desktop currently receiving input. `None` when there is no
+    /// reachable input desktop (not privileged for `Winlogon` — a host that is not SYSTEM) or the
+    /// rebind is refused, in which case the caller keeps whatever result it already had rather than
+    /// changing behaviour.
+    pub(crate) fn bind() -> Option<Self> {
+        // SAFETY: all four are FFI calls taking by-value args only. `GetThreadDesktop` yields a
+        // borrowed handle for THIS thread (never closed here). `OpenInputDesktop` yields an owned
+        // `HDESK` only on `Ok`; it is either installed by `SetThreadDesktop` (and then owned by the
+        // returned guard, which closes it exactly once in `Drop`) or closed right here on failure —
+        // so it is closed exactly once on every path and never used after close. `SetThreadDesktop`
+        // rebinds only the calling thread, which owns no windows or hooks (these are display-config
+        // worker threads), so it cannot fail on that account.
+        unsafe {
+            let previous = GetThreadDesktop(GetCurrentThreadId()).ok()?;
+            let input = OpenInputDesktop(
+                DESKTOP_CONTROL_FLAGS(0),
+                false,
+                DESKTOP_ACCESS_FLAGS(GENERIC_ALL),
+            )
+            .ok()?;
+            let name = desktop_name(input).unwrap_or_else(|| "<unnamed>".into());
+            if SetThreadDesktop(input).is_err() {
+                let _ = CloseDesktop(input);
+                return None;
+            }
+            Some(Self {
+                previous,
+                input,
+                name,
+            })
+        }
+    }
+}
+
+impl Drop for InputDesktopBinding {
+    fn drop(&mut self) {
+        // SAFETY: `self.previous` is the borrowed desktop this thread started on and `self.input`
+        // is the handle this guard uniquely owns. The thread is moved back FIRST, so the handle is
+        // no longer the thread's desktop when it is closed — closed exactly once, never used after.
+        unsafe {
+            let _ = SetThreadDesktop(self.previous);
+            let _ = CloseDesktop(self.input);
+        }
+    }
+}
+
+/// `UOI_NAME` of the current input desktop — `Some("Winlogon")` while a UAC consent prompt, the
+/// lock screen or the logon screen owns input, `Some("Default")` in normal operation, `None` when
+/// it cannot be opened at all.
+pub(crate) fn input_desktop_name() -> Option<String> {
+    // SAFETY: `OpenInputDesktop` yields an owned handle only on `Ok`, which is closed exactly once
+    // below and not used after.
+    unsafe {
+        let h = OpenInputDesktop(
+            DESKTOP_CONTROL_FLAGS(0),
+            false,
+            DESKTOP_ACCESS_FLAGS(GENERIC_ALL),
+        )
+        .ok()?;
+        let name = desktop_name(h);
+        let _ = CloseDesktop(h);
+        name
+    }
+}
+
+/// `UOI_NAME` of an already-open desktop handle. Borrows `h` — closing it stays the caller's job.
+///
+/// # Safety
+/// `h` must be a live desktop handle for the duration of the call.
+unsafe fn desktop_name(h: HDESK) -> Option<String> {
+    let mut name = [0u16; 64]; // "Default"/"Winlogon"/"Screen-saver" all fit with room to spare
+    let mut needed = 0u32;
+    // SAFETY: `h` is live per this fn's contract; `name`/`needed` are live out-params and the call
+    // writes at most `nlength` bytes, exactly the size passed.
+    GetUserObjectInformationW(
+        HANDLE(h.0),
+        UOI_NAME,
+        Some(name.as_mut_ptr().cast()),
+        (name.len() * 2) as u32,
+        Some(&mut needed),
+    )
+    .ok()?;
+    let len = name.iter().position(|&c| c == 0).unwrap_or(name.len());
+    Some(String::from_utf16_lossy(&name[..len]))
+}
+
+/// `true` when the input desktop is a SECURE one (`UOI_NAME` != `Default`: `Winlogon` for UAC
+/// consent / lock / logon, or a screen-saver desktop) — i.e. when display writes from the host's
+/// own desktop are being refused for that reason. `false` when it is normal OR unreadable: this
+/// only ever phrases a diagnostic, so an unknown desktop must not claim the secure one is up.
+pub(crate) fn input_desktop_is_secure() -> bool {
+    input_desktop_name().is_some_and(|n| !n.eq_ignore_ascii_case("Default"))
+}
+
+/// `ERROR_ACCESS_DENIED` — exactly how Windows refuses a `SetDisplayConfig` issued from a thread
+/// that is not on the input desktop (measured, see the module header). Narrower than "any error" on
+/// purpose: the CCD path also returns `ERROR_INVALID_PARAMETER` (0x57) for the unrelated
+/// exclusive-mode topology bug, and re-issuing THAT on another desktop would only confuse its
+/// diagnosis.
+const SDC_ACCESS_DENIED: i32 = 5;
+
+/// [`retry_on_input_desktop`] specialised for the CCD writes, which all return a Win32 error code.
+pub(crate) fn retry_set_display_config(write: impl FnMut() -> i32) -> i32 {
+    retry_on_input_desktop(|rc| *rc == SDC_ACCESS_DENIED, write)
+}
+
+/// Run a display-config write; if it comes back the way a write from the wrong desktop comes back,
+/// bind this thread to the CURRENT input desktop and run it exactly once more.
+///
+/// `denied` decides which results are worth a retry — keep it NARROW (the specific
+/// wrong-desktop verdict), so a genuinely bad mode or a driver-level refusal is not re-issued and
+/// mis-attributed. The binding is dropped before returning, so the calling thread always leaves on
+/// the desktop it arrived on.
+pub(crate) fn retry_on_input_desktop<T>(
+    denied: impl Fn(&T) -> bool,
+    mut write: impl FnMut() -> T,
+) -> T {
+    let first = write();
+    if !denied(&first) {
+        return first;
+    }
+    // Only worth the rebind when the input desktop is genuinely elsewhere; on a normal desktop the
+    // refusal means something else entirely and a retry would just repeat it.
+    let Some(binding) = InputDesktopBinding::bind() else {
+        return first;
+    };
+    let second = write();
+    if !denied(&second) {
+        // Say so. A silent save is indistinguishable in a log from a write that never needed
+        // saving, which makes "did the fix fire?" unanswerable in the field — and made the first
+        // on-glass verification of this very change inconclusive.
+        tracing::info!(
+            desktop = %binding.name,
+            "display write was refused off the input desktop — retried bound to it and it applied \
+             (a UAC prompt / lock screen owns input; the session continues normally)"
+        );
+    }
+    second
+}

crates/pf-win-display/src/lib.rs

@@ -11,6 +11,9 @@
 
 #[cfg(target_os = "windows")]
 pub mod display_events;
+/// Bind display-config writes to the input desktop so a UAC / lock screen can't refuse them.
+#[cfg(target_os = "windows")]
+mod input_desktop;
 #[cfg(target_os = "windows")]
 pub mod monitor_devnode;
 #[cfg(target_os = "windows")]

crates/pf-win-display/src/win_display.rs

@@ -44,8 +44,8 @@ use windows::Win32::Devices::Display::{
 use windows::Win32::Foundation::POINTL;
 use windows::Win32::Graphics::Gdi::{
     ChangeDisplaySettingsExW, EnumDisplaySettingsW, CDS_TEST, CDS_UPDATEREGISTRY, DEVMODEW,
-    DISP_CHANGE_SUCCESSFUL, DM_BITSPERPEL, DM_DISPLAYFREQUENCY, DM_PELSHEIGHT, DM_PELSWIDTH,
+    DISP_CHANGE_FAILED, DISP_CHANGE_SUCCESSFUL, DM_BITSPERPEL, DM_DISPLAYFREQUENCY, DM_PELSHEIGHT,
-    ENUM_CURRENT_SETTINGS, ENUM_DISPLAY_SETTINGS_MODE,
+    DM_PELSWIDTH, ENUM_CURRENT_SETTINGS, ENUM_DISPLAY_SETTINGS_MODE,
 };
 
 use punktfunk_core::Mode;
@@ -62,7 +62,9 @@ use punktfunk_core::Mode;
 pub unsafe fn force_extend_topology() {
     // A topology flag with no supplied path/mode arrays tells the OS to recompute + apply that preset
     // for the currently-connected displays (the same code path DisplaySwitch.exe drives).
-    let rc = SetDisplayConfig(None, None, SDC_APPLY | SDC_TOPOLOGY_EXTEND);
+    let rc = crate::input_desktop::retry_set_display_config(|| {
+        SetDisplayConfig(None, None, SDC_APPLY | SDC_TOPOLOGY_EXTEND)
+    });
     if rc == 0 {
         tracing::info!(
             "display topology forced to EXTEND (a new IddCx monitor would otherwise be CLONED onto the \
@@ -152,11 +154,13 @@ pub unsafe fn activate_target_path(target_id: u32) -> bool {
     // SAVE_TO_DATABASE so Windows remembers the arrangement — the next same-identity ADD (the driver
     // reuses the slot's EDID serial/ConnectorIndex) then auto-activates from the persistence DB and
     // skips this whole fallback ladder.
-    let rc = SetDisplayConfig(
+    let rc = crate::input_desktop::retry_set_display_config(|| {
-        Some(supplied.as_slice()),
+        SetDisplayConfig(
-        Some(modes.as_slice()),
+            Some(supplied.as_slice()),
-        SDC_APPLY | SDC_USE_SUPPLIED_DISPLAY_CONFIG | SDC_ALLOW_CHANGES | SDC_SAVE_TO_DATABASE,
+            Some(modes.as_slice()),
-    );
+            SDC_APPLY | SDC_USE_SUPPLIED_DISPLAY_CONFIG | SDC_ALLOW_CHANGES | SDC_SAVE_TO_DATABASE,
+        )
+    });
     if rc == 0 {
         tracing::info!(
             target_id,
@@ -273,14 +277,16 @@ pub unsafe fn force_mode_reenumeration() -> bool {
     let Some((paths, modes)) = query_active_config() else {
         return false;
     };
-    let rc = SetDisplayConfig(
+    let rc = crate::input_desktop::retry_set_display_config(|| {
-        Some(paths.as_slice()),
+        SetDisplayConfig(
-        Some(modes.as_slice()),
+            Some(paths.as_slice()),
-        SDC_APPLY
+            Some(modes.as_slice()),
-            | SDC_USE_SUPPLIED_DISPLAY_CONFIG
+            SDC_APPLY
-            | SDC_ALLOW_CHANGES
+                | SDC_USE_SUPPLIED_DISPLAY_CONFIG
-            | SDC_FORCE_MODE_ENUMERATION,
+                | SDC_ALLOW_CHANGES
-    );
+                | SDC_FORCE_MODE_ENUMERATION,
+        )
+    });
     if rc != 0 {
         tracing::debug!("force mode re-enumeration: SetDisplayConfig rc={rc:#x}");
     }
@@ -625,9 +631,15 @@ pub fn set_active_mode(gdi_name: &str, mode: Mode) {
     // SAFETY: `wname` is a live NUL-terminated UTF-16 device name and `&dm` is a live DEVMODEW describing
     // the requested mode; both outlive the call. CDS_TEST only validates the mode (no apply), the two
     // trailing args are null, and the API only reads its inputs.
-    let test = unsafe {
+    // A CDS write from a thread that is not on the input desktop is refused with DISP_CHANGE_FAILED
-        ChangeDisplaySettingsExW(PCWSTR(wname.as_ptr()), Some(&dm), None, CDS_TEST, None)
+    // (UAC consent / lock screen up) — retry it bound to that desktop rather than declaring the mode
-    };
+    // unsupported, which is what stranded sessions on a black screen for a whole bring-up.
+    let test = crate::input_desktop::retry_on_input_desktop(
+        |rc| *rc == DISP_CHANGE_FAILED,
+        || unsafe {
+            ChangeDisplaySettingsExW(PCWSTR(wname.as_ptr()), Some(&dm), None, CDS_TEST, None)
+        },
+    );
     if test != DISP_CHANGE_SUCCESSFUL {
         tracing::warn!(
             result = test.0,
@@ -642,15 +654,20 @@ pub fn set_active_mode(gdi_name: &str, mode: Mode) {
     // SAFETY: same inputs as the CDS_TEST call above — `wname` (live NUL-terminated device name) and
     // `&dm` (live DEVMODEW) both outlive the call; CDS_UPDATEREGISTRY applies the already-validated mode,
     // and the API only reads its inputs.
-    let apply = unsafe {
+    // Same wrong-desktop retry as the validate above: the two calls bind independently, so an apply
-        ChangeDisplaySettingsExW(
+    // still lands even when the secure desktop came up between them.
-            PCWSTR(wname.as_ptr()),
+    let apply = crate::input_desktop::retry_on_input_desktop(
-            Some(&dm),
+        |rc| *rc == DISP_CHANGE_FAILED,
-            None,
+        || unsafe {
-            CDS_UPDATEREGISTRY,
+            ChangeDisplaySettingsExW(
-            None,
+                PCWSTR(wname.as_ptr()),
-        )
+                Some(&dm),
-    };
+                None,
+                CDS_UPDATEREGISTRY,
+                None,
+            )
+        },
+    );
     if apply == DISP_CHANGE_SUCCESSFUL {
         tracing::info!(
             "{gdi_name}: active mode set to {}x{}@{}",
@@ -672,12 +689,20 @@ pub fn set_active_mode(gdi_name: &str, mode: Mode) {
 
 /// Human decode for a failed `ChangeDisplaySettingsExW` result. The two codes worth telling apart
 /// in a field log: `BADMODE` (the display's mode list genuinely lacks the mode) vs `FAILED` (the
-/// write itself was rejected — on a healthy driver that is the signature of a host process without
+/// write itself was rejected). An earlier revision printed "mode not advertised?" for BOTH, which
-/// console-session access, e.g. one trapped in a disconnected RDP session). An earlier revision
+/// sent a lid-closed field report chasing the wrong cause.
-/// printed "mode not advertised?" for BOTH, which sent a lid-closed field report chasing the wrong
+///
-/// cause.
+/// `FAILED` itself has two causes needing opposite fixes — no console-session access (disconnected
+/// RDP) versus the right session but the wrong desktop (UAC / lock / logon screen owns input) — so
+/// it asks which before naming one. See [`sdc_access_denied_hint`] for the same split on the CCD
+/// side.
 fn disp_change_reason(rc: i32) -> &'static str {
     match rc {
+        -1 if crate::input_desktop::input_desktop_is_secure() => {
+            "DISP_CHANGE_FAILED: the SECURE desktop owns input — a UAC consent prompt, the lock \
+             screen or the logon screen is up, and display writes are refused off it. Dismiss the \
+             prompt on the host"
+        }
         -1 => {
             "DISP_CHANGE_FAILED: the display write was rejected — a host without console-session \
              access (disconnected RDP session / non-console session) fails ALL display writes \
@@ -691,15 +716,28 @@ fn disp_change_reason(rc: i32) -> &'static str {
     }
 }
 
-/// Appended to `SetDisplayConfig` failure logs when rc is `ERROR_ACCESS_DENIED` (0x5) — per MS
+/// Appended to `SetDisplayConfig` failure logs when rc is `ERROR_ACCESS_DENIED` (0x5). Every other
-/// docs "the caller does not have access to the console session", the field signature of a host
+/// rc gets no hint.
-/// running in a disconnected RDP / non-console session. Every other rc gets no hint.
+///
+/// `ERROR_ACCESS_DENIED` has TWO field causes and they need opposite fixes, so ask which one before
+/// naming it. MS docs say only "the caller does not have access to the console session", which is
+/// the disconnected-RDP / non-console case — but the SAME rc comes back when the host IS in the
+/// console session and merely off the input desktop (UAC consent, lock or logon screen up). Naming
+/// only the first sent a 2026-07-23 investigation chasing a phantom RDP session while a consent
+/// prompt was the actual cause, on a host the message told to "run via the installed service" —
+/// which it already was. [`crate::input_desktop`] now retries these bound to the input desktop, so
+/// seeing this at all means even that did not help.
 fn sdc_access_denied_hint(rc: i32) -> &'static str {
-    if rc == 5 {
+    if rc != 5 {
+        return "";
+    }
+    if crate::input_desktop::input_desktop_is_secure() {
+        " (ERROR_ACCESS_DENIED: the SECURE desktop owns input — a UAC consent prompt, the lock \
+         screen or the logon screen is up, and display writes are refused off it. Dismiss the \
+         prompt on the host)"
+    } else {
         " (ERROR_ACCESS_DENIED: the host has no console-session access — disconnected RDP \
          session? run via the installed service so it tracks the console session)"
-    } else {
-        ""
     }
 }
 
@@ -928,7 +966,9 @@ pub unsafe fn isolate_displays_ccd(keep_target_ids: &[u32]) -> Option<SavedConfi
         // never calls ASSIGN_SWAPCHAIN, so the driver receives no frames. SDC_FORCE_MODE_ENUMERATION
         // forces the re-commit; SAVE_TO_DATABASE only in the sole-path case (matches prior behavior —
         // don't permanently rewrite the user's multi-display layout; the teardown restore handles it).
-        let rc = if others > 0 && attempt >= 2 {
+        // The supplied shape is decided (and its escalation announced) ONCE, outside the write, so a
+        // wrong-desktop retry re-issues the identical config instead of logging the escalation twice.
+        let keep_only = (others > 0 && attempt >= 2).then(|| {
             // ESCALATION (attempt 2+): supply ONLY the keep paths. Field-reported (AMD +
             // pf-vdisplay): carrying the doomed path in the array — inactive, modes unpinned —
             // gets the whole config rejected 0x57 on EVERY retry, so the loop alone never
@@ -946,17 +986,21 @@ pub unsafe fn isolate_displays_ccd(keep_target_ids: &[u32]) -> Option<SavedConfi
                 "display isolate (CCD): escalating to a keep-only supplied config (attempt {attempt}/4, paths {}→{}, modes {}→{})",
                 paths.len(), kp.len(), modes.len(), km.len()
             );
-            SetDisplayConfig(Some(kp.as_slice()), Some(km.as_slice()), esc)
+            (kp, km, esc)
-        } else {
+        });
-            let mut flags = SDC_APPLY
+        let rc = crate::input_desktop::retry_set_display_config(|| match &keep_only {
-                | SDC_USE_SUPPLIED_DISPLAY_CONFIG
+            Some((kp, km, esc)) => SetDisplayConfig(Some(kp.as_slice()), Some(km.as_slice()), *esc),
-                | SDC_ALLOW_CHANGES
+            None => {
-                | SDC_FORCE_MODE_ENUMERATION;
+                let mut flags = SDC_APPLY
-            if others == 0 {
+                    | SDC_USE_SUPPLIED_DISPLAY_CONFIG
-                flags |= SDC_SAVE_TO_DATABASE;
+                    | SDC_ALLOW_CHANGES
+                    | SDC_FORCE_MODE_ENUMERATION;
+                if others == 0 {
+                    flags |= SDC_SAVE_TO_DATABASE;
+                }
+                SetDisplayConfig(Some(paths.as_slice()), Some(modes.as_slice()), flags)
             }
-            SetDisplayConfig(Some(paths.as_slice()), Some(modes.as_slice()), flags)
+        });
-        };
         // A failed apply must be VISIBLE even when the verification below passes vacuously (nothing
         // else was active to deactivate — the lid-closed laptop case, where the success INFO used to
         // swallow rc=0x5): the re-commit above is load-bearing (COMMIT_MODES → ASSIGN_SWAPCHAIN),
@@ -1134,14 +1178,16 @@ pub unsafe fn apply_source_positions(positions: &[(u32, i32, i32)]) {
     if moved == 0 {
         return;
     }
-    let rc = SetDisplayConfig(
+    let rc = crate::input_desktop::retry_set_display_config(|| {
-        Some(paths.as_slice()),
+        SetDisplayConfig(
-        Some(modes.as_slice()),
+            Some(paths.as_slice()),
-        SDC_APPLY
+            Some(modes.as_slice()),
-            | SDC_USE_SUPPLIED_DISPLAY_CONFIG
+            SDC_APPLY
-            | SDC_ALLOW_CHANGES
+                | SDC_USE_SUPPLIED_DISPLAY_CONFIG
-            | SDC_FORCE_MODE_ENUMERATION,
+                | SDC_ALLOW_CHANGES
-    );
+                | SDC_FORCE_MODE_ENUMERATION,
+        )
+    });
     if rc == 0 {
         tracing::info!(
             ?positions,
@@ -1226,14 +1272,16 @@ pub unsafe fn set_virtual_primary_ccd(keep_target_id: u32) -> Option<SavedConfig
         }
     }
 
-    let rc = SetDisplayConfig(
+    let rc = crate::input_desktop::retry_set_display_config(|| {
-        Some(paths.as_slice()),
+        SetDisplayConfig(
-        Some(modes.as_slice()),
+            Some(paths.as_slice()),
-        SDC_APPLY
+            Some(modes.as_slice()),
-            | SDC_USE_SUPPLIED_DISPLAY_CONFIG
+            SDC_APPLY
-            | SDC_ALLOW_CHANGES
+                | SDC_USE_SUPPLIED_DISPLAY_CONFIG
-            | SDC_FORCE_MODE_ENUMERATION,
+                | SDC_ALLOW_CHANGES
-    );
+                | SDC_FORCE_MODE_ENUMERATION,
+        )
+    });
     if rc == 0 {
         tracing::info!("display primary (CCD): virtual target {keep_target_id} set PRIMARY at (0,0); {others} other display(s) kept ACTIVE + packed to its right");
     } else {
@@ -1253,11 +1301,13 @@ pub unsafe fn restore_displays_ccd(saved: &SavedConfig) {
     if paths.is_empty() {
         return;
     }
-    let rc = SetDisplayConfig(
+    let rc = crate::input_desktop::retry_set_display_config(|| {
-        Some(paths.as_slice()),
+        SetDisplayConfig(
-        Some(modes.as_slice()),
+            Some(paths.as_slice()),
-        SDC_APPLY | SDC_USE_SUPPLIED_DISPLAY_CONFIG | SDC_ALLOW_CHANGES,
+            Some(modes.as_slice()),
-    );
+            SDC_APPLY | SDC_USE_SUPPLIED_DISPLAY_CONFIG | SDC_ALLOW_CHANGES,
+        )
+    });
     if rc == 0 {
         tracing::info!("display isolate (CCD): restored original topology");
     } else {

docs-site/content/docs/bazzite.md

@@ -85,11 +85,10 @@ cp /usr/share/punktfunk/host.env.bazzite ~/.config/punktfunk/host.env
 
 The template is deliberately minimal — it does **not** force a compositor, because the host
 auto-detects Gaming Mode (gamescope) vs Desktop (KWin) on every connect and follows the switch
-mid-stream. The only settings that matter are the session anchors (GPU zero-copy is on by default):
+mid-stream. No session anchors are needed either (a user service inherits the right runtime dir).
+The only settings that matter (GPU zero-copy is on by default):
 
 ```sh
-XDG_RUNTIME_DIR=/run/user/1000
-DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
 PUNKTFUNK_VIDEO_SOURCE=virtual
 # GPU zero-copy (dmabuf → CUDA → NVENC) is ON by default; auto-falls back to CPU. Set =0 to force CPU.
 PUNKTFUNK_GAMESCOPE_ATTACH=1    # Gaming Mode = attach to the box's own session (see below)
@@ -99,12 +98,13 @@ PUNKTFUNK_GAMESCOPE_ATTACH=1    # Gaming Mode = attach to the box's own session
 
 For Gaming Mode there are two models (pick one; the shipped default is **attach**):
 
-- **Attach** (`PUNKTFUNK_GAMESCOPE_ATTACH=1`, the default) — the **box** owns its gamescope session,
+- **Attach** (`PUNKTFUNK_GAMESCOPE_ATTACH=1`, the template's default) — the **box** owns its
-  the host attaches to whatever's live and never tears it down, and the streamed game-mode resolution
+  gamescope session on its own display, and the host attaches to whatever's live without ever
-  is the box's own gamescope mode. Switching Desktop ↔ Game is rock-solid.
+  tearing it down (a box-owned autologin session is restarted at the client's resolution on a
-- **Managed** (`PUNKTFUNK_GAMESCOPE_MANAGED=1`, and remove the attach line) — the host launches its
+  mismatch). Switching Desktop ↔ Game is rock-solid.
-  **own** gamescope at the *client's* exact resolution and refresh. Client-mode-following, but there
+- **Managed** (`PUNKTFUNK_GAMESCOPE_MANAGED=1`, and remove the attach line) — the host takes the
-  must be no physical gaming session already running.
+  box's gamescope over and relaunches it **headless** at the *client's* exact resolution and
+  refresh — Game Mode on the virtual screen — restoring the box on idle.
 
 Full treatment: [Steam / gamescope → Attach vs managed](/docs/gamescope#attach-vs-managed).
 

docs-site/content/docs/configuration.md

@@ -4,7 +4,8 @@ description: Every host.env setting and PUNKTFUNK_* environment variable — com
 ---
 
 The host reads its settings from **`~/.config/punktfunk/host.env`** (a simple `KEY=value` file, `#`
-starts a comment). On Windows the service reads **`%ProgramData%\punktfunk\host.env`** instead. Your
+starts a comment; keys are **case-sensitive** — `punktfunk_compositor` sets nothing, use the exact
+uppercase names). On Windows the service reads **`%ProgramData%\punktfunk\host.env`** instead. Your
 [setup guide](/docs/requirements) gives you a starting `host.env` for your desktop; this page is the
 full reference for every setting.
 
@@ -16,25 +17,24 @@ full reference for every setting.
 
 ## Session anchors
 
-These tell the host which desktop session to attach to. Your setup guide sets them for you; they're
+**Leave these unset on a normal setup.** Running as a `systemctl --user` service the host inherits
-required when the host runs outside your interactive session (e.g. as a service).
+the correct `XDG_RUNTIME_DIR` from systemd, derives the session bus from it, and **rewrites
+`WAYLAND_DISPLAY` / `XDG_CURRENT_DESKTOP` / `XDG_RUNTIME_DIR` / `DBUS_SESSION_BUS_ADDRESS` on every
+connect** to follow the active session (Gaming ↔ Desktop) — a value written here can only be
+redundant or stale.
 
-| Setting | What it does |
+| Setting | When to set it |
 |---|---|
-| `XDG_RUNTIME_DIR` | Your session's runtime dir (e.g. `/run/user/1000`). Always needed for a service. |
+| `XDG_RUNTIME_DIR` | Only when the host runs **outside** a user service (ssh, cron): `/run/user/<your uid>` — check `id -u`. A copy-pasted `1000` on a box where that isn't your uid points the host at another user's (nonexistent) PipeWire/D-Bus, and **everything** fails (audio `Creation failed`, no capture, clients report the host unreachable). |
-| `DBUS_SESSION_BUS_ADDRESS` | Your session bus (e.g. `unix:path=/run/user/1000/bus`). Always needed for a service. |
+| `DBUS_SESSION_BUS_ADDRESS` | Same cases only: `unix:path=/run/user/<your uid>/bus`. Otherwise derived automatically. |
-| `WAYLAND_DISPLAY` | The Wayland socket of your session (`wayland-0` for a normal desktop, `wayland-kde` for the headless-KDE unit). |
+| `WAYLAND_DISPLAY` | Only the dedicated [headless-KDE appliance](/docs/kde#headless-session) (`wayland-kde`, set by its shipped `host.env.kde`). |
-| `XDG_CURRENT_DESKTOP` | Your desktop (`GNOME`, `KDE`). |
+| `XDG_CURRENT_DESKTOP` | Same — appliance-only. |
-
-On Linux the host **rewrites `WAYLAND_DISPLAY` / `XDG_CURRENT_DESKTOP` / `XDG_RUNTIME_DIR` /
-`DBUS_SESSION_BUS_ADDRESS` on every connect** to follow the active session (Gaming ↔ Desktop). Only
-`XDG_RUNTIME_DIR` and `DBUS_SESSION_BUS_ADDRESS` need to be pinned as trustworthy anchors.
 
 ## Core
 
 | Setting | Values | Meaning |
 |---|---|---|
-| `PUNKTFUNK_COMPOSITOR` | `kwin` · `mutter` · `gamescope` · `wlroots` · `hyprland` (aliases: `kde`/`plasma`, `gnome`, `sway`/`wlr`) | Which backend creates the virtual display. `wlroots` is sway/River; `hyprland` is its own backend. **Leave unset to auto-detect;** set only to force one. |
+| `PUNKTFUNK_COMPOSITOR` | `kwin` · `mutter` · `gamescope` · `wlroots` · `hyprland` (aliases: `kde`/`plasma`, `gnome`, `sway`/`wlr`) | Which backend creates the virtual display. `wlroots` is sway/River; `hyprland` is its own backend. **Leave unset.** Setting it **pins** the backend and turns session-following **off** — per connect *and* mid-stream, so a Desktop ↔ Gaming switch kills the stream instead of being followed. For CI/tests and dedicated single-session appliances only. |
 | `PUNKTFUNK_VIDEO_SOURCE` | `virtual` · `portal` | `virtual` creates a per-client display at the client's exact mode (the normal choice). `portal` captures an existing monitor instead. |
 | `PUNKTFUNK_ZEROCOPY` | `1` · `0` *(default on)* | GPU zero-copy capture→encode (dmabuf → CUDA → NVENC, or D3D11 on Windows). **On by default** — no need to set it; it falls back to a CPU path automatically. Set `0` to force the CPU path. One exception: Windows **Intel/QSV** keeps the CPU path by default until zero-copy is validated on Intel hardware — set `1` to try it there. |
 | `PUNKTFUNK_INPUT_BACKEND` | `libei` · `gamescope` · `wlr` · `uinput` | How input is injected. `libei` for GNOME/KDE, `gamescope` for Bazzite/gamescope, `wlr` for Sway/wlroots **and Hyprland**. Auto-detected with the compositor. |
@@ -53,8 +53,8 @@ the full picture (and [Bazzite](/docs/bazzite) for that distro's specifics).
 
 | Setting | Values | Meaning |
 |---|---|---|
-| `PUNKTFUNK_GAMESCOPE_ATTACH` | `1` | **Attach** model: the box owns its gamescope session (you switch Gaming ↔ Desktop with the Steam UI); the host just captures whatever's live and never tears it down. Rock-solid; streamed resolution is the box's gamescope mode. |
+| `PUNKTFUNK_GAMESCOPE_ATTACH` | `1` | **Attach** model: the box owns its gamescope session on its own display (you switch Gaming ↔ Desktop with the Steam UI); the host just captures whatever's live and never tears it down. A box-owned autologin session is restarted at the client's resolution on a mismatch; a foreign/bare gamescope streams at its own mode. |
-| `PUNKTFUNK_GAMESCOPE_MANAGED` | `1` | **Managed** model: the host tears the box's gamescope down on connect and launches its **own** at the *client's* exact resolution, restoring on idle. Client-mode-following, but doesn't coexist with a box-owned game-mode session. |
+| `PUNKTFUNK_GAMESCOPE_MANAGED` | `1` | **Managed** model (the default where session infra is detected): the host takes the box's gamescope over and relaunches it **headless** at the *client's* exact resolution — Game Mode on the virtual screen — restoring the box on idle. |
 | `PUNKTFUNK_GAMESCOPE_SESSION` | `steam` | The host owns a `gamescope-session-plus` (Steam) session at the client's mode (headless appliance; no physical session running). |
 | `PUNKTFUNK_GAMESCOPE_NODE` | `auto` · node id | Discover + capture a **running** gamescope's PipeWire node at a fixed mode. Do **not** combine with `SESSION`. |
 | `PUNKTFUNK_GAMESCOPE_APP` | command | For an ad-hoc bare-gamescope session, the nested command to run (e.g. `vkcube`). |

docs-site/content/docs/gamescope.md

@@ -17,18 +17,20 @@ from the install guide for your OS: [Bazzite](/docs/bazzite) or [SteamOS (Host)]
 
 ## Attach vs managed
 
-There are two mutually-exclusive models for a gamescope box; pick one. The shipped default is
+There are two mutually-exclusive models for a gamescope box; pick one. With **nothing set**, a box
-**attach**.
+that has gamescope session infrastructure (Bazzite, SteamOS, Nobara) gets **managed**; the
+[Bazzite template](/docs/bazzite) ships with **attach** chosen instead.
 
-- **Attach** (`PUNKTFUNK_GAMESCOPE_ATTACH=1`, the default) — the **box** owns its gamescope session
+- **Attach** (`PUNKTFUNK_GAMESCOPE_ATTACH=1`) — the **box** owns its gamescope session and decides
-  and decides Gaming vs Desktop via the normal Steam UI. The host just attaches to whatever's live
+  Gaming vs Desktop via the normal Steam UI. Game Mode stays on the box's own (physical) display;
-  and never tears it down, so switching Desktop ↔ Game is rock-solid and disconnecting leaves the box
+  the host attaches to whatever's live and never tears it down, so switching Desktop ↔ Game is
-  where it was. The streamed game-mode resolution is the box's gamescope mode
+  rock-solid and disconnecting leaves the box where it was. When the session is the box's own
-  (`SCREEN_WIDTH/HEIGHT` in `/etc/gamescope-session-plus/sessions.d/steam`), not the client's.
+  autologin unit, the host restarts it at the **client's** resolution on a mismatch; a foreign or
-- **Managed** (`PUNKTFUNK_GAMESCOPE_MANAGED=1`, and remove the attach line) — the host tears the
+  bare gamescope is streamed at its own mode.
-  box's gamescope down on connect and launches its **own** at the *client's* exact resolution and
+- **Managed** (the infra-detected default; force with `PUNKTFUNK_GAMESCOPE_MANAGED=1`) — the host
-  refresh, restoring on idle. Client-mode-following, but it can't coexist with a box-owned game-mode
+  takes the box's gamescope session over and relaunches it **headless** at the *client's* exact
-  session, and there must be **no physical gaming session already running**.
+  resolution and refresh — Game Mode runs on the virtual screen, physical displays drop out of it —
+  restoring the box on idle after disconnect.
 
 ## Session following
 
@@ -40,8 +42,8 @@ over its own compositor, and re-targets whichever is live on each switch.
 ## Start the host
 
 On an appliance box (Bazzite, SteamOS) the install guide already enables the host service for you. On
-any other distro running a gamescope session, start it from your session — the default attach model
+any other distro running a gamescope session, just start it — the host auto-detects the live
-just latches onto whatever gamescope session is live:
+gamescope session and picks the model for it:
 
 ```sh
 systemctl --user enable --now punktfunk-host
@@ -56,8 +58,8 @@ a model. See the full [Configuration reference](/docs/configuration) for every o
 
 | Setting | Values | Meaning |
 |---|---|---|
-| `PUNKTFUNK_GAMESCOPE_ATTACH` | `1` | **Attach** model: the box owns its gamescope session; the host captures whatever's live and never tears it down. Streamed resolution is the box's gamescope mode. The default. |
+| `PUNKTFUNK_GAMESCOPE_ATTACH` | `1` | **Attach** model: the box owns its gamescope session (on its own display); the host captures whatever's live and never tears it down. A box-owned autologin session is restarted at the client's resolution on a mismatch; a foreign/bare gamescope streams at its own mode. |
-| `PUNKTFUNK_GAMESCOPE_MANAGED` | `1` | **Managed** model: the host tears the box's gamescope down on connect and launches its own at the client's exact mode, restoring on idle. Doesn't coexist with a box-owned game-mode session. |
+| `PUNKTFUNK_GAMESCOPE_MANAGED` | `1` | **Managed** model (the default where session infra is detected): the host takes the box's gamescope over and relaunches it headless at the client's exact mode, restoring on idle. |
 | `PUNKTFUNK_GAMESCOPE_SESSION` | `steam` | The host owns a `gamescope-session-plus` (Steam) session at the client's mode — a headless appliance with no physical session running. |
 | `PUNKTFUNK_GAMESCOPE_NODE` | `auto` · node id | Discover and capture a **running** gamescope's PipeWire node at a fixed mode. Do **not** combine with `SESSION`. |
 | `PUNKTFUNK_GAMESCOPE_APP` | command | For an ad-hoc bare-gamescope session, the nested command to run (e.g. `vkcube`). |

docs-site/content/docs/gnome.md

@@ -12,19 +12,20 @@ installed — see [Ubuntu](/docs/ubuntu), [Fedora](/docs/fedora), or [Arch](/doc
 
 ## host.env
 
-Write `~/.config/punktfunk/host.env` with the GNOME settings. The host auto-detects the compositor
+The host auto-detects the compositor from your live session on every connect, so the starter
-from your session, so the explicit `PUNKTFUNK_COMPOSITOR` is belt-and-braces:
+`~/.config/punktfunk/host.env` is one line:
 
 ```ini
-# ~/.config/punktfunk/host.env
+# ~/.config/punktfunk/host.env  (keys are case-sensitive)
-WAYLAND_DISPLAY=wayland-0
-XDG_CURRENT_DESKTOP=GNOME
-PUNKTFUNK_COMPOSITOR=mutter
 PUNKTFUNK_VIDEO_SOURCE=virtual
 # GPU zero-copy (dmabuf → CUDA → NVENC) is ON by default; auto-falls back to CPU. Set =0 to force CPU.
-PUNKTFUNK_INPUT_BACKEND=libei
 ```
 
+> **Don't set `PUNKTFUNK_COMPOSITOR`, `WAYLAND_DISPLAY`, or `XDG_CURRENT_DESKTOP` here.** Pinning
+> the compositor turns auto-detection **off** — per connect *and* mid-stream — so the host stops
+> following session switches, and stale session values point it at dead sockets. Forcing a backend
+> is a CI / dedicated-appliance posture, not desktop configuration.
+
 You must be on a **Wayland** session (not X11), and Mutter must be **≥ 48**. See the
 [Configuration reference](/docs/configuration) for every option.
 

docs-site/content/docs/hyprland.md

@@ -19,14 +19,19 @@ or [Fedora](/docs/fedora).
 
 ## host.env
 
-The host auto-detects a Hyprland session, so you usually need nothing here. To force the backend, set
+The host auto-detects a Hyprland session, so the starter `~/.config/punktfunk/host.env` is one line:
-these in `~/.config/punktfunk/host.env`:
+
+```ini
+PUNKTFUNK_VIDEO_SOURCE=virtual
+# GPU zero-copy capture→encode is ON by default; auto-falls back to CPU. Set PUNKTFUNK_ZEROCOPY=0 to force CPU.
+```
+
+To force the backend (CI/testing — note that pinning turns live-session auto-detection **off**, so
+the host stops following session switches):
 
 ```ini
 PUNKTFUNK_COMPOSITOR=hyprland
 PUNKTFUNK_INPUT_BACKEND=wlr
-PUNKTFUNK_VIDEO_SOURCE=virtual
-# GPU zero-copy capture→encode is ON by default; auto-falls back to CPU. Set PUNKTFUNK_ZEROCOPY=0 to force CPU.
 ```
 
 See [Configuration](/docs/configuration) for the full reference.

docs-site/content/docs/kde.md

@@ -13,20 +13,30 @@ installed — see [Ubuntu](/docs/ubuntu), [Fedora](/docs/fedora), [Arch](/docs/a
 
 ## host.env
 
-A KDE starter `~/.config/punktfunk/host.env`:
+The host auto-detects your KWin session on every connect — including a box that switches between
+the Plasma desktop and Steam Game Mode — so the starter `~/.config/punktfunk/host.env` is one line:
 
 ```ini
-WAYLAND_DISPLAY=wayland-0
+# ~/.config/punktfunk/host.env  (keys are case-sensitive)
-XDG_CURRENT_DESKTOP=KDE
-PUNKTFUNK_COMPOSITOR=kwin
 PUNKTFUNK_VIDEO_SOURCE=virtual
 # GPU zero-copy (dmabuf → CUDA → NVENC) is ON by default; auto-falls back to CPU. Set =0 to force CPU.
-PUNKTFUNK_INPUT_BACKEND=libei
 ```
 
-The host auto-detects the running compositor on every connect, so most of this is optional — the
+> **Don't set `PUNKTFUNK_COMPOSITOR`, `WAYLAND_DISPLAY`, or `XDG_CURRENT_DESKTOP` here.** Pinning
-values above are just what it resolves to on a KWin session. See the
+> the compositor turns auto-detection **off** — per connect *and* mid-stream — so a switch to Game
-[Configuration reference](/docs/configuration) for every option.
+> Mode then kills the stream instead of being followed, and stale session values point the host at
+> dead sockets. Forcing a backend is for CI and dedicated appliances (the
+> [headless session](#headless-session) below ships a `host.env.kde` that pins on purpose).
+
+If the box switches between the desktop and Game Mode, also enable lingering — the host is a user
+service, and without linger the logout moment of a session switch tears it (and PipeWire) down
+mid-stream:
+
+```sh
+sudo loginctl enable-linger "$USER"
+```
+
+See the [Configuration reference](/docs/configuration) for every option.
 
 ## Use a Wayland session
 

docs-site/content/docs/sway.md

@@ -23,16 +23,21 @@ or [Fedora](/docs/fedora).
 
 ## host.env
 
-The host auto-detects a wlroots session, so you usually need nothing here. To force the backend, set
+The host auto-detects a wlroots session, so the starter `~/.config/punktfunk/host.env` is one line:
-these in `~/.config/punktfunk/host.env`:
 
 ```ini
-PUNKTFUNK_COMPOSITOR=wlroots      # aliases: sway, wlr, hyprland (all the wlroots family; the exact backend is auto-detected)
-PUNKTFUNK_INPUT_BACKEND=wlr
 PUNKTFUNK_VIDEO_SOURCE=virtual
 # GPU zero-copy capture→encode is ON by default; auto-falls back to CPU. Set PUNKTFUNK_ZEROCOPY=0 to force CPU.
 ```
 
+To force the backend (CI/testing — note that pinning turns live-session auto-detection **off**, so
+the host stops following session switches):
+
+```ini
+PUNKTFUNK_COMPOSITOR=wlroots      # aliases: sway, wlr (the wlroots-proper family)
+PUNKTFUNK_INPUT_BACKEND=wlr
+```
+
 See [Configuration](/docs/configuration) for the full reference.
 
 ## How it works

docs-site/content/docs/troubleshooting.md

@@ -103,7 +103,22 @@ See [GNOME](/docs/gnome) for the GL/EGL userspace details.
 - KWin must be **≥ 6.5.6** (`kwin_wayland --version`); GNOME **≥ 48**; gamescope **≥ 3.16.22**. See
   [KDE](/docs/kde) for the KWin/Wayland requirement and [gamescope](/docs/gamescope) for the
   gamescope one.
-- Confirm `PUNKTFUNK_COMPOSITOR` in [`host.env`](/docs/configuration) matches your desktop.
+- If [`host.env`](/docs/configuration) sets `PUNKTFUNK_COMPOSITOR`, **remove it** — the host
+  auto-detects the live compositor, and the pin points it at one backend even when a different
+  session is live (it also disables Gaming ↔ Desktop following).
+
+## Session fails right after editing host.env
+
+- Keys are **case-sensitive**: `punktfunk_gamescope_attach=1` sets nothing — use the exact
+  uppercase names.
+- Hardcoded session anchors with the wrong uid (`XDG_RUNTIME_DIR=/run/user/1000` when `id -u`
+  isn't 1000) point the host at another user's PipeWire/D-Bus: audio errors like
+  `pw audio connect … Creation failed`, no capture, and clients reporting the host as
+  unreachable or asleep. **Delete both anchor lines** — a `systemctl --user` service doesn't need
+  them — or fix the uid.
+- `PUNKTFUNK_COMPOSITOR` pins the backend and disables Gaming ↔ Desktop following — remove it on
+  any box that switches sessions.
+- The env file is read at service start: `systemctl --user restart punktfunk-host` after edits.
 
 ## Capture fails: "Session creation inhibited" (GNOME)
 

docs/releases/README.md

@@ -31,15 +31,28 @@ even across a tag re-point.
 Canary / `-rc` builds have **no** file here on purpose: they get no curated body and are not
 announced.
 
-## Format
+## Voice & format
 
-Match the house style (see any recent `vX.Y.Z.md`):
+**Write for the people who USE Punktfunk to stream their games and desktops — not for the people who
+build it.** A non-engineer should finish knowing what's new and whether it affects them; an engineer
+should never be confused or forced to decode internals. (See any recent `vX.Y.Z.md` for the target.)
 
-- Open with a **wire-compatibility** line — *"Wire-compatible with X.Y.x — existing pairings and
+1. **Lead with the benefit.** Each entry = what the user can now *do*, what now *works*, or what
-  clients keep working."* — plus a one-sentence fallback/negotiation note. This lead-in (all text
+   stopped *going wrong* — in their words. Implementation is not the story.
-  before the first `##` header) is what the Discord embed shows, so make it a real summary.
+2. **No internal vocabulary in the body.** No protocol/message names, code type names, hex codes or
-- Then `## Section` headers grouping the changes, with **bold lead-in** bullets.
+   hardware IDs, crate/component names, or API symbols. Translate any essential detail to plain
-- Be concrete: env vars, ABI/protocol versions, on-glass-verified hardware, platform scope.
+   language. Name things users recognize (iPad, Apple Pencil, Steam Deck, Android TV, the Windows
+   sign-in screen) — not subsystems.
+3. **Group as New / Improved / Fixed**, each a bold one-line lead-in + a tight plain explanation.
+   Skimmable. The lead-in text before the first `##` is what the Discord announcement shows, so make
+   it a real, plain-language summary.
+4. **Be specific and honest** — no vague "various improvements"; a reader should know exactly what
+   changed.
+5. **Compatibility line up top, in plain terms:** can they update one side at a time? does their
+   existing setup keep working? No version numbers in the lead.
+6. **All protocol / ABI / driver / embedder detail goes in ONE `## Under the hood (for developers)`
+   section at the very bottom** — the only place internal names and version numbers belong, clearly
+   optional. The old dense engineering style survives only there.
 
 The short annotated-**tag** message stays separate and short (a headline + a paragraph); it is the
 tag object's message, not this file.

docs/releases/v0.19.0.md

@@ -1,47 +1,33 @@
-Wire-compatible with 0.18.x — existing pairings and clients keep working. The new stylus plane is capability-negotiated (`HOST_CAP_PEN`) and rides an additive datagram that older peers never send and never have to parse, so a 0.18 host and a 0.19 client (or the reverse) pair exactly as before and simply fall back to pen-as-touch. WIRE_VERSION stays **2**; the embeddable C ABI moves to **13** for one new entry point (`punktfunk_connection_send_pen`); the Windows display-driver protocol is unchanged at **6** (compat floor **3**).
+Update whenever it suits you — you can update your app and the machine you stream from one at a time, the new and old versions work together, and everything you've already paired stays paired. The new pen features simply switch on once both ends are updated. Nothing you already use changes.
 
-## Pen, stylus & tablet — a whole new input plane
+## New: draw and write with a pen or stylus
 
-Punktfunk streams now carry a first-class, pressure-sensitive stylus, end to end and on every platform. It is its own wire plane — not mouse events in disguise — so pressure, tilt, hover and barrel buttons survive the trip from glass to host.
+You can now use a real stylus while streaming, and it behaves like a real pen on the machine you're controlling — **pressure, tilt, and the pen's side buttons all come through**, not just a plain tap. Use your **iPad's Apple Pencil** (including Pencil Pro), an **Android phone or tablet's S Pen** or other active stylus, or a pen from a Moonlight app.
 
-- **The wire (P0).** A state-full `RICH_PEN` datagram carries batches of up to 8 samples — sub-pixel `f32` position, `u16` pressure, hover distance, tilt + azimuth, an eraser tool, and two barrel buttons — ordered by a wrapping sequence number and dropped whole when stale, so a late batch never rewrites the present. A `PenTracker` coalesces the stream and `HOST_CAP_PEN` advertises the plane; toward a host without the bit the client keeps its pen-as-touch fallback.
+It's great for drawing apps, handwriting and note-taking, signing documents, and photo editing over the stream. Windows and Linux hosts receive it as genuine pen input. If the machine you're streaming from is still on an older version, your pen keeps working as an ordinary touch.
-- **Linux host (P1).** A per-session uinput virtual graphics tablet injects the full stylus — pressure and tilt included — and tears down with the session. `HOST_CAP_PEN` goes live wherever uinput is available.
-- **GameStream / Moonlight (P2).** The host ingests Moonlight's `SS_PEN`/`SS_TOUCH` pointer packets and advertises the matching `featureFlags`, so a capable Moonlight client sends real stylus onto the same plane.
-- **Windows host (P3).** `PT_PEN` + `PT_TOUCH` synthetic pointer injection drives the Windows pen stack directly — pressure and barrel buttons reach applications as genuine pen input.
-- **iPad (P4).** Apple Pencil (including Pencil Pro) capture maps onto the stylus plane — pressure and tilt from the panel, with the cursor-capability fix so the pencil and the pointer coexist.
-- **Android (P5).** Active-stylus capture (S Pen and friends) forwards onto the pen plane with pressure and tilt.
 
-## Touch injection, fixed
+## Fixed: your Steam Deck controller shows up as the right controller
 
-- **Windows native touch actually injects now.** `PT_TOUCH` pointer ids must be contiguous injector slots, but the host was passing the raw wire touch ids straight through — Windows rejected them **silently** and Moonlight-native multitouch landed nothing. Wire ids are now compacted into slots, and the first rejection is surfaced with a warning instead of vanishing.
+If a Steam controller was plugged into the computer you stream from, a streamed **Steam Deck** controller could be misread by games as a **PlayStation (DualSense)** controller — so button prompts and layouts came out wrong. It now stays a Steam Deck. Punktfunk only steps in to avoid a clash when two genuinely identical controllers are present.
-- **NaN pressure no longer drops a finger.** VoidLink's finger touches arrive with a NaN `pressureOrDistance`; the GameStream path discarded the whole packet. It now tolerates NaN and injects the touch.
 
-## Cursor & pointer polish
+## Improved: a sharper, correctly-sized mouse pointer
 
-- **The forwarded cursor is scaled to the video fit** on the SDL/Linux and Apple/macOS clients. A high-DPI host pointer was drawn against the client's own backing scale and came out roughly 2× too large; it now renders true-size against the streamed video.
+- **Right-sized pointer on high-resolution screens.** On Linux and Mac, a pointer coming from a high-resolution host could show up about twice as big as it should. It now matches the video exactly.
+- **Cleaner pointer on Windows security screens.** The mouse pointer no longer duplicates or gets stuck on Windows sign-in and User Account Control (admin permission) prompts.
+- **More reliable multi-monitor streaming on Windows.** Switching between monitor layouts on the host could occasionally drop the stream — that's fixed.
 
-## Windows host fixes
+## Fixed: touch input
 
-- **No more `0x57` on display-config isolate.** When a supplied CCD path is doomed (a Steam Deck's live-deactivate always is), the isolate escalates to a keep-only supplied config instead of failing the whole apply with `0x57`.
+- **Multi-touch from Moonlight apps now works on Windows hosts.** It previously registered nothing; pinch, zoom, and multi-finger gestures now come through.
-- **Cursor exclusion is reported adapter-wide.** The IddCx declare's cursor exclusion is not a per-target property; the virtual-display driver now reports `cursor_excluded` across the adapter.
+- **Touch is no longer silently dropped** from some devices that report finger pressure in an unusual way.
-- **Secure-desktop cursor stood down.** The IddCx hardware cursor is held down while the Windows secure desktop (UAC / Winlogon) is up, ending the duplicated/stuck pointer there.
 
-## Gamepad
+## Fixed: Android (and Android TV)
 
-- **A virtual Steam Deck pad no longer degrades to a DualSense because of an unrelated Steam controller.** To stop Steam Input from double-driving two *identical* controllers, the host downgrades a requested virtual Steam pad to a DualSense when a matching physical Valve controller is present — but the gate matched *any* `28DE` (Valve) device. So plugging a physical Steam Controller 2 (`28DE:1302`) into the host dropped a client's virtual Steam Deck (`28DE:1205`) to the wrong pad — the passthrough came up as a DualSense. The gate now keys on the exact VID+PID: distinct Steam controllers coexist (Steam Input drives them side by side fine), and only a genuine same-identity duplicate — a physical Deck alongside a virtual Deck — still degrades.
+- **Your mouse's back/forward buttons stay in the stream** instead of bouncing you out to the Android home screen — a relief on Android TV in particular.
+- **The on-screen keyboard stays out of the way** when you're typing on a physical keyboard.
 
-## Android input — mouse & keyboard regressions
+## Under the hood (for developers)
 
-Two regressions from 0.18.0's mouse-&-keyboard overhaul, felt most on Android TV boxes:
+- The streaming protocol is unchanged, so 0.18 and 0.19 hosts and apps mix freely; the pen is negotiated and older peers simply fall back to touch.
-
+- The embeddable core library adds one new call for sending pen input (the C ABI moves to **13**) — rebuild any embedders against 0.19. The Windows virtual-display driver is unchanged: pen goes through Windows' normal pen system, not the display driver.
-- **Mouse back/forward stays in the stream.** A mouse's back/forward buttons were synthesized by the reader as `SOURCE_MOUSE` key events and leaked into Android navigation (yanking you out of the stream on a TV); they're now swallowed while streaming.
+- iOS builds are now attached to each release as a downloadable file (for TestFlight/archival).
-- **Hardware typing no longer pops the IME.** The soft keyboard is gated on `imeShown`, so typing on a physical keyboard against a text-input host doesn't summon the on-screen IME.
-
-## Release & CI
-
-- **Release notes now ship with the release.** Notes are authored in-repo at `docs/releases/vX.Y.Z.md` and seeded into the release body at creation, and stable releases announce to the Discord `#releases` channel. This file is the first of them.
-- **iOS `.ipa` attached.** The iOS build exports an App Store-signed `.ipa` to the unified release and to the run artifacts (archival/TestFlight, not a direct sideload).
-
-## Versions
-
-WIRE_VERSION **2** (unchanged — 0.18.x hosts and clients interoperate) · C ABI **13** (adds `punktfunk_connection_send_pen`; embedders recompile) · Windows display driver protocol **6**, compat floor **3** (unchanged — pen injects through the Windows pen stack, not the display driver). Windows drivers ship separately, as always.

packaging/bazzite/README.md

@@ -234,33 +234,25 @@ cp /usr/share/punktfunk/host.env.bazzite ~/.config/punktfunk/host.env
 The Bazzite template (`packaging/bazzite/host.env`) contains:
 
 ```sh
-XDG_RUNTIME_DIR=/run/user/1000
-DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
-
-# gamescope backend: spawned per session, no compositor login required.
-PUNKTFUNK_COMPOSITOR=gamescope
 PUNKTFUNK_VIDEO_SOURCE=virtual
-PUNKTFUNK_GAMESCOPE_APP=steam -gamepadui
-
-# gamescope hosts its own EIS input socket — input lands in the nested session.
-PUNKTFUNK_INPUT_BACKEND=gamescope
 
 # GPU zero-copy capture (dmabuf -> CUDA -> NVENC) is ON by default and auto-falls back to CPU if
 # unavailable. No need to set it. Set to 0 only to force the CPU path.
 # PUNKTFUNK_ZEROCOPY=0
 
 #RUST_LOG=info
+
+# Gaming Mode = ATTACH: the box owns its gamescope session; the host captures + follows it.
+PUNKTFUNK_GAMESCOPE_ATTACH=1
 ```
 
 **What each knob means and why these are the Bazzite defaults:**
 
 | Knob | Value | Meaning |
 |---|---|---|
-| `XDG_RUNTIME_DIR` / `DBUS_SESSION_BUS_ADDRESS` | `…/user/1000` | Session bus / runtime dir. **`1000` assumes your user is UID 1000** — change both if `id -u` says otherwise. |
+| *(no compositor / no anchors)* | — | The host **auto-detects** the live session per connect (Gaming Mode gamescope vs the KDE desktop) and follows switches mid-stream; a `systemctl --user` service inherits the right `XDG_RUNTIME_DIR` and the host derives the bus itself. Pinning `PUNKTFUNK_COMPOSITOR` or hardcoding uid-1000 anchors only breaks this — leave them out. |
-| `PUNKTFUNK_COMPOSITOR` | `gamescope` | **The Bazzite default.** The host spawns a **headless gamescope per session** at the client's exact resolution/refresh and captures its PipeWire node — so you need **no graphical desktop login** to stream. Bazzite ships gamescope, so this "just works." |
 | `PUNKTFUNK_VIDEO_SOURCE` | `virtual` | Create a per-client virtual output at the client's exact WxH@Hz (the flagship "native resolution, no scaling" mode), vs. `portal` which captures an existing monitor. |
-| `PUNKTFUNK_GAMESCOPE_APP` | `steam -gamepadui` | The command launched **inside** the nested gamescope — here, a SteamOS-style couch UI. Set it to whatever you want the session to run. |
+| `PUNKTFUNK_GAMESCOPE_ATTACH` | `1` | Gaming Mode model: the **box** owns its gamescope session; the host attaches to whatever's live and never tears it down. Swap for `PUNKTFUNK_GAMESCOPE_MANAGED=1` to have the host relaunch the gaming session headless at the **client's** exact mode instead (see the template's comments). |
-| `PUNKTFUNK_INPUT_BACKEND` | `gamescope` | Inject mouse/keyboard/gamepad into the nested gamescope via its own EIS socket. |
 | `PUNKTFUNK_ZEROCOPY` | `on` *(default)* | GPU zero-copy capture (dmabuf → CUDA → NVENC), on by default. Falls back to CPU automatically if unavailable; set `0` to force the CPU path. |
 | `RUST_LOG` | (commented) | Uncomment `RUST_LOG=info` for verbose logs while debugging. |
 
@@ -268,16 +260,14 @@ PUNKTFUNK_INPUT_BACKEND=gamescope
 games a virtual Sony DualSense (lightbar, adaptive triggers, touchpad, motion) instead of the
 default X-Box-360 pad. The feedback flows back to a real DualSense on the client.
 
-**Alternative — drive the full Plasma/GNOME desktop** instead of a nested gamescope (per the
+**The Plasma desktop needs no extra config:** the same auto-detection streams the KDE Desktop
-template's footer comment): switch to `PUNKTFUNK_COMPOSITOR=kwin` and
+session whenever that's what's live — no compositor pin, no `WAYLAND_DISPLAY` /
-`PUNKTFUNK_INPUT_BACKEND=libei`, and run the host **inside** a KDE session with `WAYLAND_DISPLAY` /
+`XDG_CURRENT_DESKTOP` (the host retargets those per connect). The full knob list (FEC %, per-stage
-`XDG_CURRENT_DESKTOP` set. The full knob list (FEC %, per-stage timing, etc.) is in
+timing, etc.) is in `scripts/host.env.example` / `/usr/share/punktfunk/host.env.example`.
-`scripts/host.env.example` / `/usr/share/punktfunk/host.env.example`.
 
-> The gamescope default is what makes Bazzite the easy path: it's a **headless, per-session**
+> Auto-detection is what makes Bazzite the easy path: the host follows the box between Gaming Mode
-> compositor — no desktop login, no display manager, no `--drm` scanout. You don't need any of the
+> and the Desktop — even mid-stream — with a one-line config. You don't need any of the
-> headless-KDE bring-up scripts (`scripts/headless/run-headless-kde.sh`) on Bazzite unless you
+> headless-KDE bring-up scripts (`scripts/headless/run-headless-kde.sh`) on Bazzite.
-> deliberately switch to the KWin backend.
 
 ---
 
@@ -474,8 +464,11 @@ desktop viewer.
   NVIDIA driver. The code falls back to CPU automatically; check the log for the fallback line and
   verify the `-nvidia` image / driver is healthy.
 
-- **Wrong UID in `host.env`.** `XDG_RUNTIME_DIR=/run/user/1000` and the bus path assume UID 1000. Run
+- **Session anchors in `host.env`.** The template no longer sets `XDG_RUNTIME_DIR` /
-  `id -u`; if it's different, fix both lines or the host can't reach your session's PipeWire/D-Bus.
+  `DBUS_SESSION_BUS_ADDRESS` — a `systemctl --user` service inherits the right values. If an older
+  config hardcodes them with the wrong uid (`/run/user/1000` when `id -u` isn't 1000), the host
+  points at another user's PipeWire/D-Bus and everything fails (`pw audio connect … Creation
+  failed`, no capture). Delete both lines, or fix the uid.
 
 - **Service `ExecStart` points at a missing path in `$HOME`.** The dev unit references
   `%h/punktfunk/target/release/...`. The RPM binary is `/usr/bin/punktfunk-host`. Override

packaging/bazzite/host.env

@@ -3,10 +3,9 @@
 # The compositor + input backend are AUTO-DETECTED per connect from the ACTIVE session: the host
 # follows the box as you flip between Steam Gaming Mode (gamescope — a managed session at the
 # CLIENT's resolution) and a KDE/GNOME Desktop (KWin/Mutter virtual output at the client's mode).
-# So nothing here forces a backend — only the trustworthy anchors stay.
+# So nothing here forces a backend, and no session anchors are needed: a `systemctl --user`
-
+# service inherits the correct XDG_RUNTIME_DIR and the host derives the bus from it. (Keys are
-XDG_RUNTIME_DIR=/run/user/1000
+# CASE-SENSITIVE — use the exact uppercase names.)
-DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
 
 PUNKTFUNK_VIDEO_SOURCE=virtual
 
@@ -23,10 +22,11 @@ PUNKTFUNK_VIDEO_SOURCE=virtual
 #
 # GAME MODE = ATTACH (the box owns its session; the host follows). The box decides whether it's in
 # Steam Gaming Mode or a Desktop — you switch with the normal Steam UI / "Switch to Desktop". The
-# host just ATTACHES to whatever's live and captures it; it never tears the session down or relaunches
+# host just ATTACHES to whatever's live and captures it; it never tears the session down. So
-# it. So switching Desktop<->Game is rock-solid, and when you disconnect the box STAYS in its current
+# switching Desktop<->Game is rock-solid, and when you disconnect the box STAYS in its current
-# mode — reconnecting drops you right back where you were. The streamed resolution in game mode is the
+# mode — reconnecting drops you right back where you were. On a resolution mismatch the host
-# box's gamescope mode (see SCREEN_WIDTH/HEIGHT in /etc/gamescope-session-plus/sessions.d/steam).
+# restarts the box's own game-mode session at the CLIENT's resolution (a foreign/bare gamescope
+# instead streams at its own mode).
 PUNKTFUNK_GAMESCOPE_ATTACH=1
 #
 # Opt OUT to the MANAGED model instead (host tears the box's gamescope down on connect and launches

packaging/kde/host.env

@@ -1,4 +1,11 @@
 # punktfunk host config for a Fedora/Ubuntu KDE Plasma appliance (kwin backend).
+#
+# APPLIANCE-ONLY: this file deliberately PINS the backend (PUNKTFUNK_COMPOSITOR) and the session
+# env (WAYLAND_DISPLAY/XDG_CURRENT_DESKTOP) at the dedicated headless KWin session — which also
+# turns OFF the host's live-session auto-detection and Desktop<->Game following. On a normal
+# desktop (or any box that switches to Steam Game Mode) do NOT use this file; start from
+# host.env.example instead, whose defaults auto-detect and follow the live session.
+#
 # Copy to ~/.config/punktfunk/host.env. Pairs with punktfunk-kde-session.service, which brings
 # up a headless `kwin --virtual` on wayland-kde (with KWIN_WAYLAND_NO_PERMISSION_CHECKS=1 so the
 # host can bind KWin's privileged zkde_screencast protocol — an interactive Plasma session will

packaging/nix/README.md

@@ -168,14 +168,16 @@ Everything the RPM's `%install` + `%post` do, declaratively:
 
 ### Headless / appliance
 
-Set `autoStart = true`, enable lingering, and pick a backend in `settings`:
+Set `autoStart = true`, enable lingering, and — for a **dedicated single-session appliance** —
+pin a backend in `settings` (pinning `PUNKTFUNK_COMPOSITOR` disables live-session auto-detection,
+so leave it out on any box that switches between a desktop and Game Mode):
 
 ```nix
 services.punktfunk.host = {
   enable = true;
   autoStart = true;
   users = [ "streamer" ];
-  settings = { PUNKTFUNK_COMPOSITOR = "gamescope"; };  # or kwin/mutter/wlroots
+  settings = { PUNKTFUNK_COMPOSITOR = "gamescope"; };  # appliance-only; omit to auto-detect
 };
 users.users.streamer.linger = true;
 # For the gamescope/KWin backends extend the service PATH, e.g.:

scripts/host.env.example

@@ -1,16 +1,17 @@
 # punktfunk host configuration (~/.config/punktfunk/host.env) — consumed by punktfunk-host.service.
 #
-# The compositor + input backend are AUTO-DETECTED per connect from the live session (the host
+# YOU BARELY NEED THIS FILE. The host AUTO-DETECTS the live session per connect — which compositor
-# probes which compositor is actually running and retargets WAYLAND_DISPLAY/XDG_CURRENT_DESKTOP/
+# is running (KWin / Mutter / sway / Hyprland / gamescope), its Wayland socket, session bus, and the
-# DBUS at it), so a box that flips between Steam Gaming Mode and a KDE/GNOME desktop is followed
+# matching input backend — and FOLLOWS the box when it switches between a desktop and Steam Gaming
-# automatically. The blocks below are OPTIONAL OVERRIDES — uncomment one only to force a backend
+# Mode, even mid-stream. Everything below except PUNKTFUNK_VIDEO_SOURCE is an optional override.
-# (this also skips the per-connect env retargeting). The anchors XDG_RUNTIME_DIR + DBUS stay.
+#
-
+# Two rules that save debugging sessions:
-# Session / compositor environment (headless KWin example).
+#   * Keys are CASE-SENSITIVE. `punktfunk_gamescope_attach=1` sets nothing — use the exact
-XDG_RUNTIME_DIR=/run/user/1000
+#     uppercase names.
-DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
+#   * On a desktop you actually use, do NOT set PUNKTFUNK_COMPOSITOR / WAYLAND_DISPLAY /
-WAYLAND_DISPLAY=wayland-kde
+#     XDG_CURRENT_DESKTOP. Pinning the compositor DISABLES session-following (a switch to Game
-XDG_CURRENT_DESKTOP=KDE
+#     Mode mid-stream then kills the stream instead of being followed), and stale session vars
+#     point detection at dead sockets. Those knobs are for CI and dedicated appliances (below).
 
 # Video source: `virtual` creates a per-client virtual output at the client's exact
 # resolution+refresh (the flagship mode); `portal` captures an existing monitor.
@@ -20,33 +21,41 @@ PUNKTFUNK_VIDEO_SOURCE=virtual
 # CPU automatically. No need to set it. Set to 0 only to force the CPU path.
 # PUNKTFUNK_ZEROCOPY=0
 
-# --- Bazzite / SteamOS-like host: host-managed Steam-Deck-UI session -----------------------
+# --- Session anchors (rarely needed) -------------------------------------------------------
-# The host LAUNCHES gamescope-session-plus headless AT THE CLIENT'S mode (so games see the
+# As a `systemctl --user` service the host inherits the correct XDG_RUNTIME_DIR from systemd and
-# client's exact resolution + refresh, not the box's TV), and relaunches it when the mode
+# derives the bus (`unix:path=$XDG_RUNTIME_DIR/bus`) itself. Set these ONLY when running the host
-# changes. Requires the headless-appliance prereqs (linger + multi-user.target — see
+# outside a user service (ssh, cron) — and with YOUR uid (`id -u`), never a copy-pasted 1000: a
-# punktfunk-steam-session.service header) and NO physical gaming session running.
+# wrong uid points the host at another user's (nonexistent) PipeWire/D-Bus, and every session
-#PUNKTFUNK_COMPOSITOR=gamescope
+# fails with errors like "pw audio connect … Creation failed".
-#PUNKTFUNK_GAMESCOPE_SESSION=steam   # host owns a gamescope-session-plus session at the client mode
+#XDG_RUNTIME_DIR=/run/user/<uid>
-#PUNKTFUNK_INPUT_BACKEND=gamescope
+#DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/<uid>/bus
-# Mutually exclusive with the above: ATTACH to a gamescope session something ELSE owns (fixed mode):
-#PUNKTFUNK_GAMESCOPE_NODE=auto       # discover + capture a running gamescope (do NOT combine with SESSION)
 
-# --- GNOME / Mutter host (e.g. an Ubuntu desktop) -----------------------------------------
+# --- Steam Gaming Mode (Linux boxes with gamescope session infra: Bazzite/SteamOS/Nobara) ---
-# Attach to a running GNOME (Wayland) session — its default socket is wayland-0, not wayland-kde.
+# Game Mode is auto-handled; two models decide WHERE it runs when a client streams:
-# Mutter creates the per-client virtual output via its `RecordVirtual` D-Bus API (a virtual
+#   * MANAGED (the default where session infra is detected) — the host relaunches the gaming
-# monitor alongside any real one), and input goes through the RemoteDesktop portal (libei). On a
+#     session HEADLESS at the CLIENT's exact mode ("game mode on the virtual screen"); physical
-# real desktop the host runs as the logged-in user; headless GNOME also works (gnome-shell
+#     displays drop out of it, and the box is restored on a debounced idle after disconnect.
-# --headless). Needs GNOME ≥ 48 for the zero-copy RecordVirtual path.
+#   * ATTACH — the BOX owns its session: Game Mode stays on the physical screen and the host
-#WAYLAND_DISPLAY=wayland-0
+#     captures/follows it, never tearing it down. Reconnects land wherever the box is.
-#XDG_CURRENT_DESKTOP=GNOME
+#PUNKTFUNK_GAMESCOPE_ATTACH=1        # pick the ATTACH model
-#PUNKTFUNK_COMPOSITOR=mutter
+#PUNKTFUNK_GAMESCOPE_MANAGED=1      # force MANAGED even where infra detection wouldn't pick it
-#PUNKTFUNK_VIDEO_SOURCE=virtual
+#PUNKTFUNK_GAMESCOPE_SESSION=steam  # host owns a gamescope-session-plus session at the client mode
-#PUNKTFUNK_INPUT_BACKEND=libei
+#PUNKTFUNK_GAMESCOPE_NODE=auto      # raw attach: discover + capture a running gamescope's node
+#                                   # (do NOT combine with SESSION)
+#PUNKTFUNK_GAMESCOPE_APP=vkcube     # nested command for ad-hoc bare-gamescope sessions
+#PUNKTFUNK_SESSION_WATCH=0          # disable mid-stream Desktop<->Game following (on by default
+#                                   # on gamescope-infra boxes)
+
+# --- Force a backend (CI / tests / dedicated single-session appliances ONLY) ---------------
+# PINS the backend: the host stops following the live session entirely — per connect AND
+# mid-stream. Fine for a dedicated headless appliance (punktfunk-kde-session.service, a pure
+# gamescope box) or a CI run; wrong for any box that switches sessions.
+#PUNKTFUNK_COMPOSITOR=kwin          # kwin | mutter | gamescope | wlroots | hyprland
+#PUNKTFUNK_INPUT_BACKEND=libei      # wlr | libei | gamescope | uinput (auto-routed per connect)
+#WAYLAND_DISPLAY=wayland-kde        # headless-KDE appliance socket; retargeted per connect otherwise
+#XDG_CURRENT_DESKTOP=KDE
 
 # Optional overrides (apps.json is the primary mechanism for per-app settings):
-#PUNKTFUNK_COMPOSITOR=kwin          # kwin | mutter | gamescope | wlroots
-#PUNKTFUNK_GAMESCOPE_APP=vkcube     # nested command for ad-hoc bare-gamescope sessions
-#PUNKTFUNK_INPUT_BACKEND=libei      # wlr | libei | gamescope | uinput
 #PUNKTFUNK_FEC_PCT=20               # video FEC overhead percent
 #PUNKTFUNK_PERF=1                   # per-stage timing logs
 #PUNKTFUNK_MDNS=0                   # disable the mDNS adverts (native + GameStream) — for multicast-

scripts/punktfunk-host.service

@@ -2,15 +2,18 @@
 # GameStream/Moonlight-compat planes). For a SECURE native-only host (no plain-HTTP pairing / legacy
 # GCM nonce reuse — security-review #5/#9; native clients only), drop `--gamestream` from ExecStart.
 #
-# Install (against an already-running compositor session):
+# Install (against an already-running compositor session — the host auto-detects and follows it,
+# so host.env needs no backend config):
 #   mkdir -p ~/.config/systemd/user && cp scripts/punktfunk-host.service ~/.config/systemd/user/
-#   cp scripts/host.env.example ~/.config/punktfunk/host.env   # then edit for your backend
+#   cp scripts/host.env.example ~/.config/punktfunk/host.env   # defaults are right for a desktop
 #   systemctl --user daemon-reload && systemctl --user enable --now punktfunk-host
 #
-# Self-contained boot appliance (no login, no manual steps after boot):
+# Self-contained boot appliance (no login, no manual steps after boot). These routes PIN the
+# backend via PUNKTFUNK_COMPOSITOR — correct for a dedicated single-session box, but it turns off
+# live-session auto-detection, so never do it on a desktop that switches sessions (Game Mode etc.):
 #   - kwin backend (stream the Plasma desktop): also install + enable
-#     punktfunk-kde-session.service (it brings up the headless KWin session this After=s), and set
+#     punktfunk-kde-session.service (it brings up the headless KWin session this After=s), and use
-#     PUNKTFUNK_COMPOSITOR=kwin + WAYLAND_DISPLAY=wayland-kde in host.env.
+#     the shipped packaging/kde/host.env (pins kwin + WAYLAND_DISPLAY=wayland-kde on purpose).
 #   - gamescope backend (stream a nested app, no desktop): set PUNKTFUNK_COMPOSITOR=gamescope in
 #     host.env — the host spawns gamescope per session, so no kde-session unit is needed.
 #   Then `sudo loginctl enable-linger "$USER"` so user units start at boot, and reboot.