feat(tools/display-disturb): adl-emul — AMD connector-emulation probe (software HPD dummy)

The standby-sink stall program's §3 dead-end list marked ADL EmulationMode
'likely Pro-gated' on field hearsay, with 'probe once, log rc' as the owed
falsification — never run. Three RX 9070 XT field cases later (ASUS
VG32VQ1B/DP, Odyssey G60SD/DP, LG UltraGear 32GS95UE/HDMI), this is that
probe, shippable to reporters: read-only caps/board-layout/connection-state
walk by default, --lock pins the live EDID + ADL_EMUL_MODE_ALWAYS on
occupied connectors (the software HPD-holding dummy), --unlock restores.
Every call prints the bench's epoch_ms correlation line with the decoded
ADL rc — ADL_ERR_NOT_SUPPORTED(-8) vs ADL_OK on consumer Adrenalin is the
Pro-gating answer, and a --lock run during a stream with the sink asleep
is the direct A/B for the metronomic stall class.

atiadlxx.dll is bound dynamically (absent = clean exit 2), structs mirror
adl_structures.h verbatim, and the probe touches only connectors the
board-layout walk enumerated. Gates: check/clippy -D warnings (msvc
cross-target) + fmt clean; native stub unaffected.

.gitea/workflows/android.yml

@@ -160,6 +160,14 @@ jobs:
           key: gradle-${{ hashFiles('clients/android/**/*.gradle.kts', 'clients/android/gradle/wrapper/gradle-wrapper.properties') }}
           restore-keys: gradle-
 
+      # The kit's JVM unit tests — the pure parsers, migrations and feedback policies. They were
+      # running nowhere: this workflow only assembled, and android-screenshots.yml runs the :app
+      # module's tests, so nothing enforced :kit's. Cheap (a couple of seconds against an already
+      # built module) and it is the only automated cover those behaviours have.
+      - name: kit unit tests
+        working-directory: clients/android
+        run: ./gradlew :kit:testDebugUnitTest --stacktrace
+
       - name: assembleDebug (cargo-ndk → jniLibs → APK)
         working-directory: clients/android
         env:

clients/android/app/src/main/kotlin/io/unom/punktfunk/GamepadSettingsScreen.kt

@@ -65,7 +65,7 @@ import io.unom.punktfunk.kit.security.KnownHostStore
 // a controller: up/down moves the focus bar, left/right steps the focused value, A cycles/toggles it,
 // B closes. Both write the same SharedPreferences, so values round-trip with the touch settings.
 
-private class GpRow(
+internal class GpRow(
     val id: String,
     val header: String?,
     val label: String,
@@ -78,6 +78,15 @@ private class GpRow(
     val enabled: Boolean = true,    // dimmed + inert when false (still focusable, for its detail)
 )
 
+/**
+ * The row at [index], or null when it is dimmed. The single place the "disabled ⇒ inert" half of
+ * [GpRow.enabled] is enforced, so the three input paths (pad left/right, A, and a tap on the
+ * already-focused row) cannot drift apart — before this, `enabled` dimmed the label and nothing
+ * else, and every dimmed row still stepped its setting.
+ */
+internal fun liveRow(rows: List<GpRow>, index: Int): GpRow? =
+    rows.getOrNull(index)?.takeIf { it.enabled }
+
 @Composable
 fun GamepadSettingsScreen(
     initial: Settings,
@@ -144,11 +153,13 @@ fun GamepadSettingsScreen(
             when (dir) {
                 NavDir.UP -> if (focus > 0) focus--
                 NavDir.DOWN -> if (focus < rows.lastIndex) focus++
-                NavDir.LEFT -> { adjustDir = -1; rows.getOrNull(focus)?.adjust(-1) }
-                NavDir.RIGHT -> { adjustDir = 1; rows.getOrNull(focus)?.adjust(1) }
+                // A disabled row is INERT, not just dim — the step is refused instead of writing a
+                // setting that has nothing to act on (see `liveRow`).
+                NavDir.LEFT -> { adjustDir = -1; liveRow(rows, focus)?.adjust(-1) }
+                NavDir.RIGHT -> { adjustDir = 1; liveRow(rows, focus)?.adjust(1) }
             }
         },
-        onActivate = { adjustDir = 1; rows.getOrNull(focus)?.activate() },
+        onActivate = { adjustDir = 1; liveRow(rows, focus)?.activate() },
     )
     // Keep the focused row on screen, but only SCROLL when it's actually off-screen — so entering the
     // screen (focus on the first row) leaves the "Settings" heading visible instead of jumping past it.
@@ -186,7 +197,10 @@ fun GamepadSettingsScreen(
             }
             itemsIndexed(rows, key = { _, r -> r.id }) { index, row ->
                 SettingRowView(row, focused = index == focus, adjustDir = adjustDir, onClick = {
-                    if (focus == index) { adjustDir = 1; row.activate() } else focus = index
+                    // Same inertness as the pad path above — tapping a dimmed row focuses it (so
+                    // its detail explains itself) but never flips it.
+                    if (focus != index) focus = index
+                    else if (row.enabled) { adjustDir = 1; row.activate() }
                 })
             }
             }
@@ -340,7 +354,7 @@ private fun SettingRowView(row: GpRow, focused: Boolean, adjustDir: Int, onClick
 /** Build the console settings rows from the current [Settings], writing through [update].
  * [hasBodyVibrator] gates the "Rumble on this phone" row (absent on TVs); [av1Capable] gates the
  * AV1 codec entry (see `codecOptionsFor`). */
-private fun buildSettingsRows(
+internal fun buildSettingsRows(
     s: Settings,
     hasBodyVibrator: Boolean,
     av1Capable: Boolean,
@@ -348,13 +362,14 @@ private fun buildSettingsRows(
 ): List<GpRow> {
     fun <T> choice(
         id: String, header: String?, label: String, detail: String,
-        options: List<Pair<T, String>>, current: T, write: (T) -> Unit,
+        options: List<Pair<T, String>>, current: T, enabled: Boolean = true, write: (T) -> Unit,
     ): GpRow {
         val idx = options.indexOfFirst { it.first == current }
         return GpRow(
             id, header, label,
             value = options.getOrNull(idx)?.second ?: "—",
             detail = detail,
+            enabled = enabled,
             adjust = { delta ->
                 if (idx < 0) {
                     options.firstOrNull()?.let { write(it.first) } != null
@@ -371,11 +386,12 @@ private fun buildSettingsRows(
     }
     fun toggle(
         id: String, header: String?, label: String, detail: String,
-        value: Boolean, write: (Boolean) -> Unit,
+        value: Boolean, enabled: Boolean = true, write: (Boolean) -> Unit,
     ): GpRow = GpRow(
         id, header, label,
         value = if (value) "On" else "Off",
         detail = detail,
+        enabled = enabled,
         adjust = { delta -> val target = delta > 0; if (value != target) { write(target); true } else false },
         activate = { write(!value) },
         toggled = value,
@@ -478,11 +494,27 @@ private fun buildSettingsRows(
                 "so games don't see two of them.",
             s.gamepadForwarding,
         ) { update(s.copy(gamepadForwarding = it)) },
+        // Everything below the master switch follows it — dim and inert while nothing is being
+        // forwarded, the same relationship the touch settings draw with `enabled =`. This screen
+        // had the capability (`GpRow.enabled`) and used it only for the profiles placeholder, so
+        // the pad rows kept stepping settings that had nothing to act on.
         choice(
             "padType", null, "Controller type",
             "The virtual pad the host creates — Automatic matches this controller.",
-            GAMEPAD_OPTIONS, s.gamepad,
+            GAMEPAD_OPTIONS, s.gamepad, enabled = s.gamepadForwarding,
         ) { update(s.copy(gamepad = it)) },
+        choice(
+            "systemButtons", null, "Guide button",
+            "Where the guide (Xbox/PS) and share presses go while streaming — Automatic " +
+                "sends them to the host whenever this device delivers them.",
+            SYSTEM_BUTTON_OPTIONS, s.systemButtons, enabled = s.gamepadForwarding,
+        ) { update(s.copy(systemButtons = it)) },
+        choice(
+            "guideGesture", null, "Hold Select for guide",
+            "Hold Select alone to press the host's guide button — keep holding for a " +
+                "Gaming-Mode host's quick-access menu. A Select tap still goes through.",
+            GUIDE_GESTURE_OPTIONS, s.guideGesture, enabled = s.gamepadForwarding,
+        ) { update(s.copy(guideGesture = it)) },
     ) + listOfNotNull(
         if (hasBodyVibrator) {
             toggle(
@@ -501,8 +533,18 @@ private fun buildSettingsRows(
             "sc2", null, "Steam Controller 2 passthrough",
             "Capture a Steam Controller 2 (wired, Puck dongle, or paired Bluetooth) and stream " +
                 "it as-is — Steam on the host drives it like the physical pad.",
-            s.sc2Capture,
+            s.sc2Capture, enabled = s.gamepadForwarding,
         ) { update(s.copy(sc2Capture = it)) },
+        // The SC2 row's twin, and missing here until now: the touch settings have carried both
+        // side by side, so a couch user on a TV box — where there IS no touch interface to fall
+        // back to — could turn on SC2 passthrough but not the Sony one. Same no-vibrator-gate
+        // reasoning: this capture renders feedback on the CONTROLLER's motors, not this device's.
+        toggle(
+            "dsCapture", null, "DualSense / DualShock passthrough (USB)",
+            "Drive a USB-connected Sony pad directly — rumble on any phone, plus adaptive " +
+                "triggers, lightbar and gyro.",
+            s.dsCapture, enabled = s.gamepadForwarding,
+        ) { update(s.copy(dsCapture = it)) },
     )
 }
 

clients/android/app/src/main/kotlin/io/unom/punktfunk/Profiles.kt

@@ -44,6 +44,8 @@ data class SettingsOverlay(
     val invertScroll: Boolean? = null,
     val gamepad: Int? = null,
     val gamepadForwarding: Boolean? = null,
+    val systemButtons: String? = null,
+    val guideGesture: String? = null,
     val statsVerbosity: StatsVerbosity? = null,
     /**
      * Android-only tier-P addition (design §3): the decode pipeline is a device fact everywhere
@@ -78,6 +80,8 @@ data class SettingsOverlay(
         invertScroll = invertScroll ?: base.invertScroll,
         gamepad = gamepad ?: base.gamepad,
         gamepadForwarding = gamepadForwarding ?: base.gamepadForwarding,
+        systemButtons = systemButtons ?: base.systemButtons,
+        guideGesture = guideGesture ?: base.guideGesture,
         statsVerbosity = statsVerbosity ?: base.statsVerbosity,
         lowLatencyMode = lowLatencyMode ?: base.lowLatencyMode,
         presentPriority = presentPriority ?: base.presentPriority,
@@ -115,6 +119,8 @@ data class SettingsOverlay(
         gamepadForwarding =
             if (after.gamepadForwarding != before.gamepadForwarding) after.gamepadForwarding
             else gamepadForwarding,
+        systemButtons = if (after.systemButtons != before.systemButtons) after.systemButtons else systemButtons,
+        guideGesture = if (after.guideGesture != before.guideGesture) after.guideGesture else guideGesture,
         statsVerbosity = if (after.statsVerbosity != before.statsVerbosity) after.statsVerbosity else statsVerbosity,
         lowLatencyMode = if (after.lowLatencyMode != before.lowLatencyMode) after.lowLatencyMode else lowLatencyMode,
         presentPriority = if (after.presentPriority != before.presentPriority) after.presentPriority else presentPriority,
@@ -142,6 +148,8 @@ data class SettingsOverlay(
         "invert_scroll" -> copy(invertScroll = null)
         "gamepad" -> copy(gamepad = null)
         "gamepad_forwarding" -> copy(gamepadForwarding = null)
+        "system_buttons" -> copy(systemButtons = null)
+        "guide_gesture" -> copy(guideGesture = null)
         "stats_verbosity" -> copy(statsVerbosity = null)
         "low_latency_mode" -> copy(lowLatencyMode = null)
         "present_priority" -> copy(presentPriority = null)
@@ -166,6 +174,8 @@ data class SettingsOverlay(
         if (invertScroll != null) add("invert_scroll")
         if (gamepad != null) add("gamepad")
         if (gamepadForwarding != null) add("gamepad_forwarding")
+        if (systemButtons != null) add("system_buttons")
+        if (guideGesture != null) add("guide_gesture")
         if (statsVerbosity != null) add("stats_verbosity")
         if (lowLatencyMode != null) add("low_latency_mode")
         if (presentPriority != null) add("present_priority")
@@ -198,6 +208,8 @@ data class SettingsOverlay(
         invertScroll?.let { j.put("invert_scroll", it) }
         gamepad?.let { j.put("gamepad", it) }
         gamepadForwarding?.let { j.put("gamepad_forwarding", it) }
+        systemButtons?.let { j.put("system_buttons", it) }
+        guideGesture?.let { j.put("guide_gesture", it) }
         statsVerbosity?.let { j.put("stats_verbosity", it.name) }
         lowLatencyMode?.let { j.put("low_latency_mode", it) }
         presentPriority?.let { j.put("present_priority", it) }
@@ -214,6 +226,7 @@ data class SettingsOverlay(
             "width", "height", "refresh_hz", "bitrate_kbps", "render_scale", "codec",
             "hdr_enabled", "compositor", "audio_channels", "mic_enabled", "echo_cancel",
             "touch_mode", "mouse_mode", "invert_scroll", "gamepad", "gamepad_forwarding",
+            "system_buttons", "guide_gesture",
             "stats_verbosity",
             "low_latency_mode", "present_priority", "smooth_buffer",
         )
@@ -237,6 +250,8 @@ data class SettingsOverlay(
             invertScroll = j.optBooleanOrNull("invert_scroll"),
             gamepad = j.optIntOrNull("gamepad"),
             gamepadForwarding = j.optBooleanOrNull("gamepad_forwarding"),
+            systemButtons = j.optStringOrNull("system_buttons"),
+            guideGesture = j.optStringOrNull("guide_gesture"),
             statsVerbosity = j.optStringOrNull("stats_verbosity")
                 ?.let { n -> StatsVerbosity.entries.firstOrNull { it.name == n } },
             lowLatencyMode = j.optBooleanOrNull("low_latency_mode"),

clients/android/app/src/main/kotlin/io/unom/punktfunk/Settings.kt

@@ -45,6 +45,20 @@ data class Settings(
      * bind — which is why it gates the USB capture paths, not just the wire sends.
      */
     val gamepadForwarding: Boolean = true,
+    /**
+     * Where the guide (Xbox/PS) and misc/share presses land while streaming — the
+     * cross-client `system_buttons` key: `"auto"` (forward on Android — the press reaches
+     * the app on most devices) | `"forward"` | `"local"`.
+     */
+    val systemButtons: String = "auto",
+    /**
+     * The hold-Select guide gesture — the cross-client `guide_gesture` key: `"auto"` (off
+     * on Android) | `"on"` | `"off"`. On: holding Select alone ≥350 ms sends the HOST's
+     * guide, down until release (long hold = the host's long-press → a Gaming-Mode host's
+     * QAM); a Select tap is delivered on release, slightly delayed. For devices whose
+     * shell intercepts the physical guide button.
+     */
+    val guideGesture: String = "auto",
     /** Requested audio channel count: 2 (stereo), 6 (5.1) or 8 (7.1). The host clamps to what it
      * can capture; the resolved count drives the decoder + AAudio layout. */
     val audioChannels: Int = 2,
@@ -228,6 +242,8 @@ class SettingsStore(context: Context) {
         compositor = prefs.getInt(K_COMPOSITOR, 0),
         gamepad = prefs.getInt(K_GAMEPAD, 0),
         gamepadForwarding = prefs.getBoolean(K_GAMEPAD_FORWARDING, true),
+        systemButtons = prefs.getString(K_SYSTEM_BUTTONS, "auto") ?: "auto",
+        guideGesture = prefs.getString(K_GUIDE_GESTURE, "auto") ?: "auto",
         audioChannels = prefs.getInt(K_AUDIO_CH, 2),
         codec = prefs.getString(K_CODEC, "auto") ?: "auto",
         micEnabled = prefs.getBoolean(K_MIC, false),
@@ -275,6 +291,8 @@ class SettingsStore(context: Context) {
             .putInt(K_COMPOSITOR, s.compositor)
             .putInt(K_GAMEPAD, s.gamepad)
             .putBoolean(K_GAMEPAD_FORWARDING, s.gamepadForwarding)
+            .putString(K_SYSTEM_BUTTONS, s.systemButtons)
+            .putString(K_GUIDE_GESTURE, s.guideGesture)
             .putInt(K_AUDIO_CH, s.audioChannels)
             .putString(K_CODEC, s.codec)
             .putBoolean(K_MIC, s.micEnabled)
@@ -305,6 +323,8 @@ class SettingsStore(context: Context) {
         const val K_COMPOSITOR = "compositor"
         const val K_GAMEPAD = "gamepad"
         const val K_GAMEPAD_FORWARDING = "gamepad_forwarding"
+        const val K_SYSTEM_BUTTONS = "system_buttons"
+        const val K_GUIDE_GESTURE = "guide_gesture"
         const val K_AUDIO_CH = "audio_channels"
         const val K_CODEC = "codec"
         const val K_MIC = "mic_enabled"
@@ -539,6 +559,15 @@ fun codecOptionsFor(stored: String, av1Capable: Boolean): List<Pair<String, Stri
         }
     }
 
+/** Resolved [Settings.systemButtons]: forward the raw guide/misc presses? Auto = forward on
+ * Android — the press reaches the app on most devices, and where the shell shows its own UI
+ * for it that's the shell's business. */
+fun Settings.systemButtonsForward(): Boolean = systemButtons != "local"
+
+/** Resolved [Settings.guideGesture]: auto = OFF on Android (the raw press already reaches the
+ * host); "on" is for devices whose shell intercepts the physical guide button. */
+fun Settings.guideGestureEnabled(): Boolean = guideGesture == "on"
+
 /** The [Settings.codec] string as a `quic::CODEC_*` preference byte (`0` = auto). H264=1, HEVC=2,
  * AV1=4, PyroWave=8 (never decodable here, but the byte is the shared contract). */
 fun Settings.preferredCodec(): Int = when (codec) {
@@ -621,3 +650,17 @@ val GAMEPAD_OPTIONS = listOf(
     io.unom.punktfunk.kit.Gamepad.PREF_DUALSHOCK4 to "DualShock 4",
     io.unom.punktfunk.kit.Gamepad.PREF_STEAMDECK to "Steam Deck",
 )
+
+/** (stored `system_buttons` value, label) — where the guide/share presses land while streaming. */
+val SYSTEM_BUTTON_OPTIONS = listOf(
+    "auto" to "Automatic",
+    "forward" to "Send to host",
+    "local" to "This device",
+)
+
+/** (stored `guide_gesture` value, label) — the hold-Select guide gesture. */
+val GUIDE_GESTURE_OPTIONS = listOf(
+    "auto" to "Automatic",
+    "on" to "On",
+    "off" to "Off",
+)

clients/android/app/src/main/kotlin/io/unom/punktfunk/SettingsScreen.kt

@@ -838,6 +838,25 @@ private fun ControllerSettings(s: Settings, update: (Settings) -> Unit, onOpenCo
             caption = "The virtual pad the host creates. Automatic matches your controller; " +
                 "every connected one is forwarded as its own player.",
         ) { g -> update(s.copy(gamepad = g)) }
+        SettingDropdown(
+            label = "Guide button",
+            options = SYSTEM_BUTTON_OPTIONS,
+            selected = s.systemButtons,
+            field = "system_buttons",
+            enabled = s.gamepadForwarding,
+            caption = "Where the guide (Xbox/PS) and share presses go while streaming. " +
+                "Automatic sends them to the host whenever this device delivers them.",
+        ) { v -> update(s.copy(systemButtons = v)) }
+        SettingDropdown(
+            label = "Hold Select for guide",
+            options = GUIDE_GESTURE_OPTIONS,
+            selected = s.guideGesture,
+            field = "guide_gesture",
+            enabled = s.gamepadForwarding,
+            caption = "Hold Select alone to press the host's guide button — keep holding for a " +
+                "Gaming-Mode host's quick-access menu. A Select tap still goes through, " +
+                "slightly delayed. For devices that intercept the real guide button.",
+        ) { v -> update(s.copy(guideGesture = v)) }
         DeviceScopeOnly {
             ClickableRow(
                 title = "Connected controllers",

clients/android/app/src/main/kotlin/io/unom/punktfunk/StreamScreen.kt

@@ -323,6 +323,7 @@ fun StreamScreen(session: ActiveSession, onDisconnect: () -> Unit) {
         // controller (Automatic). Built here, released on dispose.
         val router = GamepadRouter(
             context, handle, initialSettings.gamepad, initialSettings.gamepadForwarding,
+            initialSettings.systemButtonsForward(), initialSettings.guideGestureEnabled(),
         )
         activity?.gamepadRouter = router
         // Select+Start+L1+R1 chord leaves the stream — a deliberate quit (signal it so the host skips

clients/android/app/src/test/kotlin/io/unom/punktfunk/GamepadSettingsRowsTest.kt

@@ -0,0 +1,97 @@
+package io.unom.punktfunk
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * The controller-navigable settings rows: what the master forwarding switch governs, and that a
+ * governed row is inert rather than merely dim.
+ *
+ * The touch settings and the desktop console have carried this relationship for a while (`enabled =
+ * s.gamepadForwarding` / `RowSpec.enabled`); this screen dimmed nothing and stepped everything, so
+ * these tests pin both halves — the flag AND the refusal to write.
+ */
+class GamepadSettingsRowsTest {
+
+    /** Rows for a given forwarding state, capturing whatever a row writes back. */
+    private fun rows(
+        forwarding: Boolean,
+        sink: MutableList<Settings> = mutableListOf(),
+    ): List<GpRow> = buildSettingsRows(
+        Settings(gamepadForwarding = forwarding),
+        hasBodyVibrator = true,
+        av1Capable = true,
+    ) { sink += it }
+
+    private fun row(rows: List<GpRow>, id: String): GpRow =
+        rows.first { it.id == id }
+
+    /** Every row that only means something while a controller is actually being forwarded. */
+    private val governed = listOf("padType", "systemButtons", "guideGesture", "sc2", "dsCapture")
+
+    @Test
+    fun `forwarding off dims every row that depends on it`() {
+        val off = rows(forwarding = false)
+        for (id in governed) {
+            assertFalse("$id should be dimmed with forwarding off", row(off, id).enabled)
+        }
+        // The master switch itself stays live — otherwise it could never be turned back on.
+        assertTrue(row(off, "padForward").enabled)
+    }
+
+    @Test
+    fun `forwarding on leaves them all live`() {
+        val on = rows(forwarding = true)
+        for (id in governed) {
+            assertTrue("$id should be live with forwarding on", row(on, id).enabled)
+        }
+    }
+
+    @Test
+    fun `a dimmed row is inert - liveRow withholds it and nothing is written`() {
+        val writes = mutableListOf<Settings>()
+        val off = rows(forwarding = false, sink = writes)
+        for (id in governed) {
+            val i = off.indexOfFirst { it.id == id }
+            assertNull("$id must not be reachable while dimmed", liveRow(off, i))
+            // What the screen actually does on left/right/A — the whole point is that it no-ops.
+            liveRow(off, i)?.adjust(1)
+            liveRow(off, i)?.adjust(-1)
+            liveRow(off, i)?.activate()
+        }
+        assertEquals("a dimmed row wrote a setting", emptyList<Settings>(), writes)
+    }
+
+    @Test
+    fun `the same rows do write once forwarding is on`() {
+        val writes = mutableListOf<Settings>()
+        val on = rows(forwarding = true, sink = writes)
+        val i = on.indexOfFirst { it.id == "sc2" }
+        assertNotNull(liveRow(on, i))
+        liveRow(on, i)?.activate()
+        assertEquals(1, writes.size)
+        assertFalse("activate flips the toggle", writes[0].sc2Capture)
+    }
+
+    /**
+     * R18: the Sony passthrough toggle the touch settings have always had. It matters most exactly
+     * where this screen is the only one reachable — a TV box has no touch interface to fall back to.
+     */
+    @Test
+    fun `the DualSense passthrough toggle is present, next to its SC2 twin`() {
+        val on = rows(forwarding = true)
+        val ids = on.map { it.id }
+        assertTrue("dsCapture row is missing", "dsCapture" in ids)
+        assertEquals(
+            "the two passthrough rows belong side by side",
+            ids.indexOf("sc2") + 1,
+            ids.indexOf("dsCapture"),
+        )
+        // Drawn as a switch, and reading the persisted default.
+        assertEquals(true, row(on, "dsCapture").toggled)
+    }
+}

clients/android/kit/src/main/kotlin/io/unom/punktfunk/kit/DsCapture.kt

@@ -116,7 +116,12 @@ class DsCapture(
             // The interfaces are about to release with the kernel driver still detached — a
             // mid-rumble teardown would leave the motors running with nobody to stop them.
             // EP0-direct (the reader thread is stopping; the queue would never drain).
-            usb.writeControl(stopReport(m))
+            // Nothing can retry after this point, so a failure is worth saying out loud: it is
+            // the difference between a quiet pad and one that buzzes until it is unplugged.
+            if (!usb.writeControl(stopReport(m))) Log.w(TAG, "teardown rumble stop was not written")
+            // Motors silenced above; this hands back the lightbar, player LEDs and adaptive
+            // triggers the game was holding, which outlive the link just as stubbornly.
+            resetRichFeedback(m)
         }
         disarmBackstop()
         usb.stop()
@@ -145,6 +150,9 @@ class DsCapture(
         val wasActive = model != null
         model = null
         releaseSlot()
+        // Release the transport too: the link only *signals* the drop, so without this an unplug
+        // left its connection open, its interfaces claimed and its detach receiver registered.
+        usb.stop()
         if (wasActive) onActiveChanged?.invoke(false)
     }
 
@@ -216,17 +224,20 @@ class DsCapture(
 
     override fun rumble(pad: Int, low: Int, high: Int, backstopMs: Long) {
         val m = model ?: return
-        if (low == 0 && high == 0) {
-            disarmBackstop()
-        } else {
-            armBackstop(backstopMs)
-        }
-        if (m == DsDevice.Model.DUALSHOCK4) {
+        val stop = low == 0 && high == 0
+        if (!stop) armBackstop(backstopMs)
+        val sent = if (m == DsDevice.Model.DUALSHOCK4) {
             ds4Low = low
             ds4High = high
             writeDs4()
         } else {
-            usb.writeRaw(0, DsDevice.ds5RumbleReport(m, low, high))
+            usb.writeRaw(0, DsDevice.ds5RumbleReport(m, low, high), OutReportQueue.KEY_RUMBLE)
+        }
+        if (stop) {
+            // Disarm only once the stop is actually on its way. Dropping the net *before* the
+            // write — as this used to — meant a discarded stop left the motors running with
+            // nothing scheduled to try again; a USB pad holds its last level until told zero.
+            if (sent) disarmBackstop() else armBackstop(STOP_RETRY_MS)
         }
     }
 
@@ -252,6 +263,9 @@ class DsCapture(
         usb.writeRaw(0, DsDevice.ds5TriggerReport(m, which, effect))
     }
 
+    // Coalescable: the DS4's write is full-state (motors AND lightbar, rebuilt from the current
+    // fields on every call), so a newer one supersedes an older one wholesale — nothing is lost by
+    // collapsing a backlog of them down to the last.
     private fun writeDs4() = usb.writeRaw(
         0,
         DsDevice.ds4Report(
@@ -261,8 +275,38 @@ class DsCapture(
             (ds4Rgb shr 8) and 0xFF,
             ds4Rgb and 0xFF,
         ),
+        OutReportQueue.KEY_RUMBLE,
     )
 
+    /**
+     * Hand the pad back neutral: adaptive triggers released, lightbar dark, player LEDs clear.
+     *
+     * Rumble stops the moment nothing renews it, but these are LATCHED in the controller's
+     * firmware — they outlive the stream, the app, and being unplugged. Ending a session while a
+     * game held a weapon's trigger resistance left the physical trigger stiff afterwards, with
+     * nothing to release it but another game that happens to set one.
+     *
+     * EP0-direct like the rumble stop above: the reader thread is stopping, so the interrupt-OUT
+     * queue would never drain. Writes are best-effort — the pad may already be gone.
+     */
+    private fun resetRichFeedback(m: DsDevice.Model) {
+        if (m == DsDevice.Model.DUALSHOCK4) {
+            // No adaptive triggers or player LEDs on a DS4, and its write is full-state, so
+            // blacking the lightbar is a single composed report.
+            ds4Rgb = 0
+            usb.writeControl(DsDevice.ds4Report(0, 0, 0, 0, 0))
+            return
+        }
+        // An all-zero effect block is mode 0x00 — no effect — which is what releases the trigger.
+        for (which in 0..1) {
+            usb.writeControl(
+                DsDevice.ds5TriggerReport(m, which, ByteArray(DsDevice.TRIGGER_EFFECT_LEN)),
+            )
+        }
+        usb.writeControl(DsDevice.ds5LightbarReport(m, 0, 0, 0))
+        usb.writeControl(DsDevice.ds5PlayerLedsReport(m, 0))
+    }
+
     /** The report that stops the motors. The DS4's is a full-state write, so it zeroes the
      *  composed motor state and carries the current lightbar rather than blacking it out. */
     private fun stopReport(m: DsDevice.Model): ByteArray = if (m == DsDevice.Model.DUALSHOCK4) {
@@ -284,7 +328,12 @@ class DsCapture(
         backstop?.let { mainHandler.removeCallbacks(it) }
         val r = Runnable {
             backstop = null
-            model?.let { usb.writeRaw(0, stopReport(it)) }
+            val m = model ?: return@Runnable
+            // The net itself can be refused (a full queue, a connection going away). Re-arm rather
+            // than give up: this is the last thing between a stalled poll thread and a pad that
+            // buzzes until it is unplugged. It stops re-arming as soon as the link closes, which
+            // clears `model` and disarms.
+            if (!usb.writeRaw(0, stopReport(m), OutReportQueue.KEY_RUMBLE)) armBackstop(STOP_RETRY_MS)
         }
         backstop = r
         mainHandler.postDelayed(r, ms.coerceAtLeast(1))
@@ -297,5 +346,9 @@ class DsCapture(
 
     private companion object {
         const val TAG = "DsCapture"
+
+        /** How soon to retry a rumble stop whose write was rejected. Short: the motors are running
+         *  and the host has already moved on, so nothing else is coming to silence them. */
+        const val STOP_RETRY_MS = 100L
     }
 }

clients/android/kit/src/main/kotlin/io/unom/punktfunk/kit/DsDevice.kt

@@ -279,8 +279,8 @@ object DsDevice {
     fun ds5RumbleReport(model: Model, low: Int, high: Int): ByteArray = newDs5(model).also {
         it[1] = (DS5_FLAG0_COMPAT_VIBRATION or DS5_FLAG0_HAPTICS_SELECT).toByte()
         it[39] = DS5_FLAG2_VIBRATION2.toByte()
-        it[3] = amp8(high).toByte()
-        it[4] = amp8(low).toByte()
+        it[3] = wireAmplitudeToByte(high).toByte()
+        it[4] = wireAmplitudeToByte(low).toByte()
     }
 
     /**
@@ -324,17 +324,11 @@ object DsDevice {
         ByteArray(Model.DUALSHOCK4.outputSize).also {
             it[0] = 0x05
             it[1] = (DS4_FLAG0_MOTORS or DS4_FLAG0_LED).toByte()
-            it[4] = amp8(high).toByte()
-            it[5] = amp8(low).toByte()
+            it[4] = wireAmplitudeToByte(high).toByte()
+            it[5] = wireAmplitudeToByte(low).toByte()
             it[6] = r.toByte()
             it[7] = g.toByte()
             it[8] = b.toByte()
         }
 
-    // Wire u16 amplitude → motor byte; a nonzero command never collapses to 0 (parity with the
-    // vibrator path's toAmplitude).
-    private fun amp8(v16: Int): Int {
-        val a = (v16 ushr 8) and 0xFF
-        return if (v16 != 0 && a == 0) 1 else a
-    }
 }

clients/android/kit/src/main/kotlin/io/unom/punktfunk/kit/GamepadFeedback.kt

@@ -88,6 +88,9 @@ class GamepadFeedback(
         const val TAG_PLAYER_LEDS: Byte = 0x02
         const val TAG_TRIGGER: Byte = 0x03
         const val TAG_HID_RAW: Byte = 0x05
+
+        /** Sparse-log cadence for swallowed render failures — see [noteRenderFailure]. */
+        const val LOG_EVERY = 128L
     }
 
     /** One controller's rumble binding — VibratorManager (API 31+) OR the legacy single Vibrator (API 28–30). */
@@ -125,37 +128,51 @@ class GamepadFeedback(
     fun start() {
         running = true
         rumbleThread = Thread({
+            var failures = 0L
             while (running) {
                 val ev = NativeBridge.nativeNextRumble(handle)
-                if (ev < 0L) continue // timeout / closed
-                // ev bits 49..52 = wire pad index; bits 32..47 = backstop duration (ms);
-                // 16..31 = low; 0..15 = high. These are EFFECTIVE commands from the core's shared
-                // rumble policy engine — it owns every lease/staleness/close decision (uniform
-                // across all clients; the old 60 s legacy-host exposure is gone) and emits
-                // explicit zeros, so apply verbatim: (0, 0) = cancel, non-zero = one-shot for
-                // the backstop (the hardware net under a stalled poll thread).
-                val pad = ((ev ushr 49) and 0xFL).toInt()
-                val backstopMs = ((ev ushr 32) and 0xFFFF)
-                renderRumble(
-                    pad,
-                    ((ev ushr 16) and 0xFFFF).toInt(),
-                    (ev and 0xFFFF).toInt(),
-                    backstopMs,
-                )
+                // Layout + semantics live in `unpackRumbleEvent` (RumbleWire.kt), tested there
+                // against the Rust packer.
+                val cmd = unpackRumbleEvent(ev) ?: continue // timeout / closed
+                // Rendering is binder calls into the vibrator service, and every one of them can
+                // throw unchecked — DeadSystemRuntimeException when system_server goes down, and
+                // the ordinary RuntimeException a dying service wraps its RemoteException in.
+                // Unguarded, ONE of those killed this thread outright: `running` stayed true, so
+                // nothing noticed and nothing restarted it, and rumble was gone for the rest of
+                // the session. Losing a single command is recoverable; losing the loop is not.
+                runCatching {
+                    renderRumble(cmd.pad, cmd.low, cmd.high, cmd.backstopMs)
+                }.onFailure { failures = noteRenderFailure("rumble", it, failures) }
             }
         }, "pf-rumble").apply { isDaemon = true; start() }
 
         hidoutThread = Thread({
             // 128: the raw as-is passthrough events are [pad][kind tag][report kind][≤64 bytes].
             val buf = ByteBuffer.allocateDirect(128)
+            var failures = 0L
             while (running) {
                 val n = NativeBridge.nativeNextHidout(handle, buf)
                 if (n < 0) continue // timeout / closed
-                dispatchHidout(buf, n)
+                // Same hazard as the rumble loop above: lights/trigger rendering is binder and USB
+                // calls, and an unchecked throw here would silently end the rich-feedback plane.
+                runCatching { dispatchHidout(buf, n) }
+                    .onFailure { failures = noteRenderFailure("hidout", it, failures) }
             }
         }, "pf-hidout").apply { isDaemon = true; start() }
     }
 
+    /**
+     * Record a render failure the poll loop swallowed, and return the updated count. Logged on the
+     * first occurrence and sparsely after: a genuinely dead vibrator service fails on *every*
+     * command, which at a rumble plane's rate would bury the log.
+     */
+    private fun noteRenderFailure(plane: String, t: Throwable, seen: Long): Long {
+        if (seen == 0L || seen % LOG_EVERY == 0L) {
+            Log.w(TAG, "$plane render failed (#${seen + 1}) — command dropped, poll loop alive", t)
+        }
+        return seen + 1
+    }
+
     /** Idempotent. Stops + joins the poll threads (must complete before the router is released / handle freed). */
     fun stop() {
         running = false
@@ -264,12 +281,12 @@ class GamepadFeedback(
             return
         }
         val bind = rumbleBindFor(pad) ?: return
-        val lo = toAmplitude(low)
-        val hi = toAmplitude(high)
+        val lo = wireAmplitudeToByte(low)
+        val hi = wireAmplitudeToByte(high)
         val m = bind.vm
         if (m != null) {
             if (lo == 0 && hi == 0) {
-                m.cancel() // (0,0) = stop
+                runCatching { m.cancel() } // (0,0) = stop
                 return
             }
             val combo = CombinedVibration.startParallel()
@@ -294,7 +311,7 @@ class GamepadFeedback(
         // API 28–30 legacy single-motor path: blend both motors into one effect.
         val lv = bind.legacy ?: return
         if (lo == 0 && hi == 0) {
-            lv.cancel() // (0,0) = stop
+            runCatching { lv.cancel() } // (0,0) = stop
             return
         }
         val a = (lo * 0.8 + hi * 0.33).toInt().coerceIn(1, 255)
@@ -314,8 +331,8 @@ class GamepadFeedback(
      */
     private fun renderDeviceRumble(low: Int, high: Int, durationMs: Long) {
         val v = deviceVibrator ?: return
-        val lo = toAmplitude(low)
-        val hi = toAmplitude(high)
+        val lo = wireAmplitudeToByte(low)
+        val hi = wireAmplitudeToByte(high)
         if (lo == 0 && hi == 0) {
             runCatching { v.cancel() } // (0,0) = stop
             return
@@ -329,12 +346,6 @@ class GamepadFeedback(
         }
     }
 
-    // 0..0xFFFF → 1..255 (high byte); a nonzero motor never collapses to 0.
-    private fun toAmplitude(v16: Int): Int {
-        val a = (v16 ushr 8) and 0xFF
-        return if (v16 != 0 && a == 0) 1 else a
-    }
-
     // One-shot held for `durationMs` — the host's v2 TTL (renewed while the level holds), so it
     // self-terminates on a lost stop; cancel on zero. Floor the duration at 1 ms: `createOneShot`
     // throws IllegalArgumentException on a non-positive duration, and a lease can carry ttl_ms==0

clients/android/kit/src/main/kotlin/io/unom/punktfunk/kit/GamepadRouter.kt

@@ -50,12 +50,35 @@ class GamepadRouter(
      * capture links, which `StreamScreen` does not start at all while this is off.
      */
     private val forwarding: Boolean = true,
+    /**
+     * Forward raw guide/QAM presses (`Settings.systemButtons` resolved — auto = forward on
+     * Android, where the press reaches the app on most devices; `local` exists for
+     * cross-client profile parity with the Gaming-Mode clients). Off keeps them entirely
+     * with this device.
+     */
+    private val systemForward: Boolean = true,
+    /**
+     * The hold-Select guide gesture (`Settings.guideGesture` resolved — auto = off on
+     * Android): holding Select ALONE ≥ [GUIDE_HOLD_MS] sends the HOST's guide button, down
+     * until release — so a long hold is the host's long-press, a Gaming-Mode host's QAM. A
+     * Select tap is delivered on release (delayed by up to the threshold); a Select pressed
+     * while other buttons are down passes through untouched, so the exit/mic chords keep
+     * working. pf-client-core's `SelectGesture`, on the main-thread handler.
+     */
+    private val guideGesture: Boolean = false,
 ) {
 
     /** One forwarded controller: its stable wire pad index, per-device axis state, and held buttons. */
     private class Slot(val index: Int, val mapper: Gamepad.AxisMapper) {
         /** Forwarded button bits currently held (Gamepad.BTN_*) — for release-on-close + chord detection. */
         var held = 0
+
+        // Hold-Select→guide gesture state ([guideGesture]): the pending Select's hold
+        // timer / a delivered tap's owed release (both on the main handler), and whether
+        // the held Select was transformed into a synthetic guide.
+        var pendingGuide: Runnable? = null
+        var pendingTapUp: Runnable? = null
+        var selectAsGuide = false
     }
 
     /** deviceId → slot. Concurrent: the feedback poll threads read it via [deviceForPad]. */
@@ -139,7 +162,24 @@ class GamepadRouter(
      * the mic-mute chord ([MIC_CHORD]).
      */
     private fun slotButton(slot: Slot, bit: Int, down: Boolean, send: Boolean) {
+        // Raw system buttons stay local under the "local" policy — no wire send and no held
+        // tracking, symmetric on both edges so nothing leaks into the chords either.
+        if (!systemForward && (bit == Gamepad.BTN_GUIDE || bit == Gamepad.BTN_MISC1)) return
         if (down) {
+            if (guideGesture && send) {
+                // A Select pressed ALONE is held back until it resolves: a tap (delivered
+                // on release), a combo member (the next button flushes it as a real
+                // press), or — past GUIDE_HOLD_MS — a synthetic guide. Held state records
+                // it either way, so the exit/mic chords read as if the gesture didn't
+                // exist (Select+Y still fires the mic toggle: the flush sends Select's
+                // down before Y's).
+                if (bit == Gamepad.BTN_BACK && slot.held == 0) {
+                    slot.held = slot.held or bit
+                    armGuide(slot)
+                    return
+                }
+                flushPendingSelect(slot)
+            }
             if (send && forwarding) {
                 NativeBridge.nativeSendGamepadButton(handle, bit, true, slot.index)
             }
@@ -155,7 +195,8 @@ class GamepadRouter(
                 onMicChord?.invoke()
             }
         } else {
-            if (send && forwarding) {
+            val owned = guideGesture && bit == Gamepad.BTN_BACK && consumeSelectRelease(slot)
+            if (!owned && send && forwarding) {
                 NativeBridge.nativeSendGamepadButton(handle, bit, false, slot.index)
             }
             slot.held = slot.held and bit.inv()
@@ -167,6 +208,61 @@ class GamepadRouter(
         }
     }
 
+    /** Start a pending Select's hold countdown ([GUIDE_HOLD_MS] → a synthetic guide, down until release). */
+    private fun armGuide(slot: Slot) {
+        val r = Runnable {
+            slot.pendingGuide = null
+            slot.selectAsGuide = true
+            if (forwarding) {
+                NativeBridge.nativeSendGamepadButton(handle, Gamepad.BTN_GUIDE, true, slot.index)
+            }
+        }
+        slot.pendingGuide = r
+        mainHandler.postDelayed(r, GUIDE_HOLD_MS)
+    }
+
+    /**
+     * A second button joined while Select was pending — it was a real Select after all; its
+     * deferred down goes out before the caller sends the new button's, preserving chronology.
+     */
+    private fun flushPendingSelect(slot: Slot) {
+        val r = slot.pendingGuide ?: return
+        mainHandler.removeCallbacks(r)
+        slot.pendingGuide = null
+        if (forwarding) {
+            NativeBridge.nativeSendGamepadButton(handle, Gamepad.BTN_BACK, true, slot.index)
+        }
+    }
+
+    /**
+     * Select released with gesture state outstanding — true when the gesture owned the
+     * release. A transformed hold lifts the synthetic guide; a pending tap delivers its
+     * held-back press now, with the release [TAP_PRESS_MS] behind it (a back-to-back pair
+     * can fold into nothing in the host's per-pad input fold).
+     */
+    private fun consumeSelectRelease(slot: Slot): Boolean {
+        if (slot.selectAsGuide) {
+            slot.selectAsGuide = false
+            if (forwarding) {
+                NativeBridge.nativeSendGamepadButton(handle, Gamepad.BTN_GUIDE, false, slot.index)
+            }
+            return true
+        }
+        val r = slot.pendingGuide ?: return false
+        mainHandler.removeCallbacks(r)
+        slot.pendingGuide = null
+        if (forwarding) {
+            NativeBridge.nativeSendGamepadButton(handle, Gamepad.BTN_BACK, true, slot.index)
+            val up = Runnable {
+                slot.pendingTapUp = null
+                NativeBridge.nativeSendGamepadButton(handle, Gamepad.BTN_BACK, false, slot.index)
+            }
+            slot.pendingTapUp = up
+            mainHandler.postDelayed(up, TAP_PRESS_MS)
+        }
+        return true
+    }
+
     /** Arm the exit-chord hold timer (once); on expiry, if the chord is still held, flush + leave. */
     private fun armExit() {
         if (pendingExit != null) return // already counting down
@@ -362,6 +458,24 @@ class GamepadRouter(
 
     /** Lift every held button + zero the axes/HAT dpad for [slot] (wire events only, all on its index). */
     private fun releaseHeld(slot: Slot) {
+        // Gesture first: a pending (never-sent) Select just drops its timer; an owed tap
+        // release goes out NOW (its down is already on the wire and the handle may not
+        // outlive this slot); a transformed guide — which is not in `held` — is lifted.
+        slot.pendingGuide?.let { mainHandler.removeCallbacks(it) }
+        slot.pendingGuide = null
+        slot.pendingTapUp?.let {
+            mainHandler.removeCallbacks(it)
+            slot.pendingTapUp = null
+            if (forwarding) {
+                NativeBridge.nativeSendGamepadButton(handle, Gamepad.BTN_BACK, false, slot.index)
+            }
+        }
+        if (slot.selectAsGuide) {
+            slot.selectAsGuide = false
+            if (forwarding) {
+                NativeBridge.nativeSendGamepadButton(handle, Gamepad.BTN_GUIDE, false, slot.index)
+            }
+        }
         var bits = slot.held
         while (bits != 0) {
             val bit = bits and -bits // lowest set bit
@@ -403,5 +517,14 @@ class GamepadRouter(
 
         /** Synthetic slot-key base for [ExternalPad]s — below every real (positive) InputDevice id. */
         const val EXTERNAL_ID_BASE = -1000
+
+        /** pf-client-core's `GUIDE_HOLD`: hold Select alone this long → the host's guide goes down. */
+        const val GUIDE_HOLD_MS = 350L
+
+        /**
+         * pf-client-core's `TAP_PRESS`: a held-back Select tap's release trails its press by
+         * this much, so the pair can't coalesce into no press at all.
+         */
+        const val TAP_PRESS_MS = 50L
     }
 }

clients/android/kit/src/main/kotlin/io/unom/punktfunk/kit/HidUsbLink.kt

@@ -14,8 +14,8 @@ import android.hardware.usb.UsbRequest
 import android.os.Build
 import android.util.Log
 import java.nio.ByteBuffer
-import java.util.concurrent.ConcurrentLinkedQueue
 import java.util.concurrent.TimeoutException
+import java.util.concurrent.atomic.AtomicBoolean
 
 /**
  * Generic USB transport for a client-captured HID controller — the device-agnostic half of what
@@ -81,14 +81,20 @@ class HidUsbLink(
 
     /** Pending OUT reports, submitted by the reader thread — only one thread may drive a
      *  connection's [UsbRequest]s ([UsbDeviceConnection.requestWait] returns ANY completed
-     *  request; a second waiter would steal the reader's completions). */
-    private val outQueue = ConcurrentLinkedQueue<ByteArray>()
+     *  request; a second waiter would steal the reader's completions). See [OutReportQueue] for
+     *  what gets discarded when it fills, and why that is not simply "the oldest". */
+    private val outQueue = OutReportQueue()
 
     private var reader: Thread? = null
     private var detachReceiver: BroadcastReceiver? = null
 
     @Volatile private var running = false
 
+    /** Latches on the first "this link is down" signal so [onClosed] fires exactly once, however
+     *  many of the racing detectors (detach broadcast, reader error streak, failed re-queue) see
+     *  it. Reset by [start]. */
+    private val down = AtomicBoolean(false)
+
     /** First attached matching device, or null. Does not need USB permission to enumerate. */
     fun findDevice(): UsbDevice? = usb.deviceList.values.firstOrNull(config.deviceMatch)
 
@@ -114,6 +120,7 @@ class HidUsbLink(
         connection = conn
         device = dev
         claims = claimed
+        down.set(false)
         running = true
         Log.i(
             config.tag,
@@ -134,10 +141,7 @@ class HidUsbLink(
                 val gone: UsbDevice? = intent.getParcelableExtra(UsbManager.EXTRA_DEVICE)
                 if (gone?.deviceName == dev.deviceName) {
                     Log.i(config.tag, "USB detached (${dev.deviceName})")
-                    if (running) {
-                        running = false
-                        onClosed()
-                    }
+                    linkDown()
                 }
             }
         }
@@ -221,6 +225,9 @@ class HidUsbLink(
         if (live.isEmpty()) {
             Log.e(config.tag, "no IN request could be queued")
             finishReader(claims)
+            // `start` already returned true, so without this the owner would sit waiting on a
+            // capture that never streams and never reports itself dead.
+            linkDown()
             return
         }
         val scratch = ByteArray(64)
@@ -295,10 +302,23 @@ class HidUsbLink(
         } finally {
             finishReader(claims)
         }
-        if (running) {
-            running = false
-            onClosed()
-        }
+        linkDown()
+    }
+
+    /**
+     * Report the link down, exactly once, from whichever detector noticed first — the detach
+     * broadcast (main thread) or the reader thread on its way out.
+     *
+     * This only *signals*; releasing the connection and the interfaces stays the owner's job, via
+     * the [stop] its `onClosed` handler calls. Previously nothing released them on this path: the
+     * detach receiver flipped a flag and fired the callback, so an unplug left the connection open,
+     * the interfaces claimed (the pad could not return to Android's own input stack) and the
+     * receiver still registered — and a re-plug overwrote the field holding it, leaking a receiver
+     * that stayed live for the process's lifetime.
+     */
+    private fun linkDown() {
+        running = false
+        if (down.compareAndSet(false, true)) onClosed()
     }
 
     private fun finishReader(claims: List<Claim>) {
@@ -314,28 +334,35 @@ class HidUsbLink(
      * Write one raw report to the device: kind 0 = output report (the active interface's
      * interrupt-OUT, else a `SET_REPORT(Output)` control transfer), kind 1 = feature report
      * (`SET_REPORT(Feature)`). [data] is the full report, id byte first, hidapi framing.
+     *
+     * [coalesce] tells the pending-OUT queue whether a newer report of the same kind may replace
+     * this one — [OutReportQueue.KEY_RUMBLE] for motor levels, the default [OutReportQueue.NO_COALESCE]
+     * for one-shots (lightbar, player LEDs, trigger effects) the sender will not repeat.
+     *
+     * Returns whether the report reached the device or is queued for it. A caller that is writing
+     * a **stop** needs this: a discarded stop has nothing behind it, so it must not be mistaken
+     * for one that landed.
      */
-    fun writeRaw(kind: Int, data: ByteArray) {
-        if (data.isEmpty()) return
-        when (kind) {
+    fun writeRaw(kind: Int, data: ByteArray, coalesce: Int = OutReportQueue.NO_COALESCE): Boolean {
+        if (data.isEmpty()) return false
+        return when (kind) {
             0 -> {
                 if ((activeClaim ?: claims.firstOrNull())?.outReq != null) {
-                    // Interrupt-OUT rides UsbRequests submitted by the reader thread. Bounded,
-                    // newest-wins: these are level-styled commands the sender re-sends anyway.
-                    while (outQueue.size >= 32) outQueue.poll()
-                    outQueue.offer(data)
+                    // Interrupt-OUT rides UsbRequests submitted by the reader thread.
+                    outQueue.offer(data, coalesce)
                 } else {
                     setReport(REPORT_TYPE_OUTPUT, data)
                 }
             }
             1 -> setReport(REPORT_TYPE_FEATURE, data)
+            else -> false
         }
     }
 
-    private fun setReport(type: Int, data: ByteArray) {
-        val conn = connection ?: return
-        val ifId = (activeClaim ?: claims.firstOrNull())?.iface?.id ?: return
-        sendReport(conn, ifId, type, data)
+    private fun setReport(type: Int, data: ByteArray): Boolean {
+        val conn = connection ?: return false
+        val ifId = (activeClaim ?: claims.firstOrNull())?.iface?.id ?: return false
+        return sendReport(conn, ifId, type, data)
     }
 
     /**
@@ -344,9 +371,8 @@ class HidUsbLink(
      * queue would never drain (e.g. a rumble stop before the interfaces release). Safe from any
      * thread: EP0 control transfers are independent of the reader's `requestWait`.
      */
-    fun writeControl(data: ByteArray) {
-        if (data.isNotEmpty()) setReport(REPORT_TYPE_OUTPUT, data)
-    }
+    fun writeControl(data: ByteArray): Boolean =
+        data.isNotEmpty() && setReport(REPORT_TYPE_OUTPUT, data)
 
     private fun sendKeepAlive(conn: UsbDeviceConnection, ifaceId: Int) {
         for (f in config.keepAliveFeatures) sendReport(conn, ifaceId, REPORT_TYPE_FEATURE, f)
@@ -358,27 +384,48 @@ class HidUsbLink(
      * "unnumbered" (id 0 in wValue, id byte stripped from the payload). EP0 is independent of
      * the interrupt endpoints, so this is safe alongside the reader thread's requestWait.
      */
-    private fun sendReport(conn: UsbDeviceConnection, ifaceId: Int, type: Int, data: ByteArray) {
+    private fun sendReport(
+        conn: UsbDeviceConnection,
+        ifaceId: Int,
+        type: Int,
+        data: ByteArray,
+    ): Boolean {
         val id = data[0].toInt() and 0xFF
         val payload = if (id == 0) data.copyOfRange(1, data.size) else data
-        conn.controlTransfer(
-            0x21, // host→device, class, interface
-            0x09, // SET_REPORT
-            (type shl 8) or id,
-            ifaceId,
-            payload,
-            payload.size,
-            WRITE_TIMEOUT_MS,
-        )
+        // controlTransfer returns the byte count, or a negative value on failure — a failed write
+        // must be reported as such, not swallowed (a dropped rumble stop has nothing behind it).
+        val n = runCatching {
+            conn.controlTransfer(
+                0x21, // host→device, class, interface
+                0x09, // SET_REPORT
+                (type shl 8) or id,
+                ifaceId,
+                payload,
+                payload.size,
+                WRITE_TIMEOUT_MS,
+            )
+        }.getOrDefault(-1)
+        return n >= 0
     }
 
-    /** Stop the read loop and release the interfaces. Idempotent; does not fire [onClosed]. */
+    /**
+     * Stop the read loop and release the interfaces. Idempotent; does not fire [onClosed].
+     *
+     * Safe to call from the `onClosed` handler itself — that is how an unplug now gets cleaned up,
+     * and it arrives on the reader thread, which must not try to join itself.
+     */
     fun stop() {
         running = false
+        // Claim the down-latch so the reader's own exit does not report a close the owner asked for.
+        down.set(true)
         detachReceiver?.let { runCatching { context.unregisterReceiver(it) } }
         detachReceiver = null
-        runCatching { reader?.join(1000) }
-        reader = null
+        if (reader !== Thread.currentThread()) {
+            runCatching { reader?.join(1000) }
+            // Only forget the thread once it is actually gone: clearing it while it still runs
+            // would let a later stop() skip the join and free the connection under it.
+            reader = null
+        }
         outQueue.clear()
         activeClaim = null
         for (c in claims) runCatching { connection?.releaseInterface(c.iface) }

clients/android/kit/src/main/kotlin/io/unom/punktfunk/kit/OutReportQueue.kt

@@ -0,0 +1,89 @@
+package io.unom.punktfunk.kit
+
+/**
+ * The pending interrupt-OUT reports for a captured controller: a bounded FIFO whose overflow
+ * policy knows which reports may be thrown away and which may not.
+ *
+ * The queue exists because only one thread may drive a connection's `UsbRequest`s, so writes from
+ * the feedback threads are handed to the reader thread rather than submitted directly. It has to
+ * be bounded — a stalled or unplugged device would otherwise grow it without limit — and the
+ * question is what to discard when it fills.
+ *
+ * The old policy was "newest wins": drop from the head until there is room. That is right for
+ * rumble, which is *level-styled* — the host re-sends it continuously, so a dropped frame is
+ * replaced milliseconds later and nothing is permanently lost. It is wrong for everything else.
+ * A lightbar colour, a player-LED mask and an adaptive-trigger effect are **one-shots**: the host
+ * sends them on change and never repeats them. Dropping one leaves the pad wrong until the next
+ * time that value happens to change, which may be never.
+ *
+ * So eviction is driven by an explicit [key] supplied by the caller, not by inspecting the bytes.
+ * That distinction cannot be recovered from the report itself: every DualSense output report
+ * carries the *same* report id and differs only in its `valid_flag` bytes, so an id-keyed policy
+ * would happily let a rumble supersede a lightbar — the very bug this replaces, relocated.
+ *
+ * Two rules:
+ *  - A report offered with a coalescing key **replaces** the pending report with that key, in
+ *    place. A burst of rumble collapses to its latest value and never displaces anything else.
+ *  - Only when the queue is full does anything get dropped, and then the oldest *coalescable*
+ *    report goes first. A one-shot is discarded only if the queue is full of nothing but
+ *    one-shots — which needs [cap] distinct one-shots outstanding, far beyond what a real pad
+ *    produces.
+ *
+ * Thread-safe: offered by the feedback threads, drained by the reader thread.
+ */
+internal class OutReportQueue(private val cap: Int = CAP) {
+    private class Entry(val key: Int, val data: ByteArray)
+
+    private val items = ArrayDeque<Entry>()
+
+    /**
+     * Queue [data] for submission. [key] is [NO_COALESCE] for a one-shot, or a caller-chosen
+     * constant identifying a level-styled stream whose newer values supersede older ones.
+     *
+     * Returns false only if the report had to be dropped outright — the caller can then treat the
+     * write as failed rather than assuming it is on its way.
+     */
+    fun offer(data: ByteArray, key: Int = NO_COALESCE): Boolean = synchronized(items) {
+        if (key != NO_COALESCE) {
+            val at = items.indexOfFirst { it.key == key }
+            if (at >= 0) {
+                // Supersede in place: keeping the queue position stops a fast rumble stream from
+                // repeatedly jumping the one-shots queued ahead of it.
+                items[at] = Entry(key, data)
+                return true
+            }
+        }
+        if (items.size >= cap) {
+            val victim = items.indexOfFirst { it.key != NO_COALESCE }
+            if (victim >= 0) {
+                items.removeAt(victim)
+            } else if (key != NO_COALESCE) {
+                // Nothing coalescable to sacrifice and this report is itself replaceable — drop it
+                // rather than a one-shot that will never come again.
+                return false
+            } else {
+                items.removeFirst()
+            }
+        }
+        items.addLast(Entry(key, data))
+        return true
+    }
+
+    /** The next report to submit, or null when nothing is pending. */
+    fun poll(): ByteArray? = synchronized(items) { items.removeFirstOrNull()?.data }
+
+    fun clear() = synchronized(items) { items.clear() }
+
+    val size: Int get() = synchronized(items) { items.size }
+
+    companion object {
+        /** This report is a one-shot: never superseded, evicted only as a last resort. */
+        const val NO_COALESCE = 0
+
+        /** Motor levels — re-sent continuously, so only the newest is worth keeping. */
+        const val KEY_RUMBLE = 1
+
+        /** Deep enough to absorb a burst, small enough that a stalled device cannot bloat us. */
+        const val CAP = 32
+    }
+}

clients/android/kit/src/main/kotlin/io/unom/punktfunk/kit/RumbleWire.kt

@@ -0,0 +1,47 @@
+package io.unom.punktfunk.kit
+
+/**
+ * The two conversions every rumble path in this module needs, in one place.
+ *
+ * Both used to be transcribed per call site: [wireAmplitudeToByte] existed twice, byte-identical,
+ * in `GamepadFeedback` and `DsDevice`; [unpackRumbleEvent] was inline bit-shifting in the poll loop
+ * with no test on either side of the JNI boundary. Neither is complicated — which is exactly why a
+ * silent divergence between copies would have been hard to notice.
+ */
+
+/**
+ * Wire amplitude (`0..0xFFFF`) → an 8-bit motor/vibrator level.
+ *
+ * The high byte, except that a **nonzero command never collapses to zero**: anything below 0x0100
+ * would otherwise round to silence, turning a weak-but-real rumble into no rumble at all. 1 is
+ * imperceptibly light, but it moves.
+ */
+internal fun wireAmplitudeToByte(v16: Int): Int {
+    val a = (v16 ushr 8) and 0xFF
+    return if (v16 != 0 && a == 0) 1 else a
+}
+
+/** One effective rumble command, as packed by the native side's `nativeNextRumble`. */
+internal data class RumbleCmd(val pad: Int, val low: Int, val high: Int, val backstopMs: Long)
+
+/**
+ * Unpack `NativeBridge.nativeNextRumble`'s `jlong`, or null for the timeout/closed sentinel.
+ *
+ * Layout, mirroring `clients/android/native/src/feedback.rs::pack_rumble`:
+ * bits 49..52 = wire pad index, 32..47 = backstop duration (ms), 16..31 = low, 0..15 = high.
+ * The pad field is 4 bits because `punktfunk_core::input::MAX_PADS` is 16 — the Rust side has a
+ * compile-time assertion tying the two together, so this can't silently start truncating.
+ *
+ * These are EFFECTIVE commands from the core's shared rumble policy engine: it owns every
+ * lease/staleness/close decision and emits explicit zeros, so apply them verbatim —
+ * `(0, 0)` = cancel, non-zero = one-shot for the backstop.
+ */
+internal fun unpackRumbleEvent(ev: Long): RumbleCmd? {
+    if (ev < 0L) return null // timeout / closed
+    return RumbleCmd(
+        pad = ((ev ushr 49) and 0xFL).toInt(),
+        low = ((ev ushr 16) and 0xFFFF).toInt(),
+        high = (ev and 0xFFFF).toInt(),
+        backstopMs = (ev ushr 32) and 0xFFFF,
+    )
+}

clients/android/kit/src/main/kotlin/io/unom/punktfunk/kit/Sc2Capture.kt

@@ -273,10 +273,20 @@ class Sc2Capture(
 
     private fun onLinkClosed() {
         Log.i(TAG, "SC2 link closed (unplug / power-off)")
+        // Both transports share this callback, so read which one was live BEFORE clearing it —
+        // releasing the other would tear down a link that never dropped.
+        val dropped = activeLink
         activeLink = LINK_NONE
         dongleLink = false
         releaseSlot()
         releaseUiKeys()
+        // Release the transport too — see the note in DsCapture.onLinkClosed. The Puck makes this
+        // worse than a single leak: it is the pad that gets power-cycled, so the same process can
+        // round-trip a link many times in one session.
+        when (dropped) {
+            LINK_USB -> usb.stop()
+            LINK_BLE -> ble.stop()
+        }
         onActiveChanged?.invoke(false)
     }
 

clients/android/kit/src/test/kotlin/io/unom/punktfunk/kit/OutReportQueueTest.kt

@@ -0,0 +1,102 @@
+package io.unom.punktfunk.kit
+
+import org.junit.Assert.assertArrayEquals
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * The pending-OUT queue's overflow policy. What is being pinned here is the distinction the old
+ * "drop from the head until there is room" policy did not make: rumble is re-sent continuously and
+ * may be thrown away, while a lightbar/player-LED/trigger report is sent once and never repeated.
+ */
+class OutReportQueueTest {
+    /** A report carrying a 0..255 marker so a test can tell which one came back out. */
+    private fun report(marker: Int) = byteArrayOf(0x02, marker.toByte())
+
+    // Masked: the marker rides in a Byte, and Byte.toInt() sign-extends.
+    private fun drain(q: OutReportQueue): List<Int> =
+        generateSequence { q.poll() }.map { it[1].toInt() and 0xFF }.toList()
+
+    @Test
+    fun `rumble supersedes the pending rumble instead of queueing another`() {
+        val q = OutReportQueue()
+        assertTrue(q.offer(report(1), OutReportQueue.KEY_RUMBLE))
+        assertTrue(q.offer(report(2), OutReportQueue.KEY_RUMBLE))
+        assertTrue(q.offer(report(3), OutReportQueue.KEY_RUMBLE))
+        assertEquals("a rumble burst must collapse to one entry", 1, q.size)
+        assertArrayEquals(report(3), q.poll())
+        assertNull(q.poll())
+    }
+
+    @Test
+    fun `superseding keeps the queue position so a rumble stream cannot jump one-shots`() {
+        val q = OutReportQueue()
+        q.offer(report(1), OutReportQueue.KEY_RUMBLE)
+        q.offer(report(10)) // a one-shot queued behind it
+        q.offer(report(2), OutReportQueue.KEY_RUMBLE)
+        // The newer rumble takes the OLD rumble's slot, so the one-shot does not get starved
+        // behind an endlessly-renewed entry.
+        assertEquals(listOf(2, 10), drain(q))
+    }
+
+    @Test
+    fun `a full queue sacrifices rumble, never a one-shot`() {
+        val q = OutReportQueue(cap = 4)
+        q.offer(report(1), OutReportQueue.KEY_RUMBLE)
+        q.offer(report(10))
+        q.offer(report(11))
+        q.offer(report(12))
+        assertEquals(4, q.size)
+        // Full. The old policy dropped the head — here that is a rumble, but only by luck of
+        // ordering; what matters is that the one-shots all survive.
+        assertTrue(q.offer(report(13)))
+        assertEquals(listOf(10, 11, 12, 13), drain(q))
+    }
+
+    @Test
+    fun `the one-shot the host never repeats survives a rumble storm`() {
+        val q = OutReportQueue(cap = 4)
+        // The exact regression: a lightbar colour queued once, then a flood of rumble. Under the
+        // old newest-wins eviction the colour was dropped from the head and never came back,
+        // leaving the pad lit wrong until the value next happened to change.
+        q.offer(report(200)) // lightbar
+        repeat(50) { q.offer(report(it), OutReportQueue.KEY_RUMBLE) }
+        val out = drain(q)
+        assertTrue("the lightbar report must still be queued, got $out", out.contains(200))
+        assertEquals("rumble must not have accumulated", listOf(200, 49), out)
+    }
+
+    @Test
+    fun `a queue full of one-shots refuses a rumble rather than dropping one`() {
+        val q = OutReportQueue(cap = 2)
+        q.offer(report(10))
+        q.offer(report(11))
+        assertFalse(
+            "with nothing coalescable to sacrifice, the replaceable report yields",
+            q.offer(report(1), OutReportQueue.KEY_RUMBLE),
+        )
+        assertEquals(listOf(10, 11), drain(q))
+    }
+
+    @Test
+    fun `only a queue of nothing but one-shots drops one, and it is the oldest`() {
+        val q = OutReportQueue(cap = 2)
+        q.offer(report(10))
+        q.offer(report(11))
+        assertTrue(q.offer(report(12)))
+        assertEquals(listOf(11, 12), drain(q))
+    }
+
+    @Test
+    fun `clear empties the queue`() {
+        val q = OutReportQueue()
+        q.offer(report(1), OutReportQueue.KEY_RUMBLE)
+        q.offer(report(10))
+        q.clear()
+        assertEquals(0, q.size)
+        assertNull(q.poll())
+    }
+}

clients/android/kit/src/test/kotlin/io/unom/punktfunk/kit/RumbleWireTest.kt

@@ -0,0 +1,79 @@
+package io.unom.punktfunk.kit
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+/**
+ * The Kotlin half of the rumble JNI boundary. The Rust half is pinned by `pack_rumble_tests` in
+ * `clients/android/native/src/feedback.rs`; the two suites describe the same layout from opposite
+ * sides, which is the only thing that catches one of them drifting.
+ */
+class RumbleWireTest {
+
+    /** `pack_rumble` from the native side, transcribed — the packer these tests unpack. */
+    private fun pack(pad: Int, low: Int, high: Int, backstopMs: Int): Long =
+        ((pad and 0xF).toLong() shl 49) or
+            ((backstopMs.coerceAtMost(0xFFFF)).toLong() shl 32) or
+            (low.toLong() shl 16) or
+            high.toLong()
+
+    @Test
+    fun `every field round-trips at its extremes`() {
+        val cases = listOf(
+            listOf(0, 0, 0, 0),
+            listOf(15, 0xFFFF, 0xFFFF, 0xFFFF),
+            listOf(1, 0x1234, 0x5678, 500),
+            listOf(7, 0, 0xFFFF, 2000),
+        )
+        for ((pad, low, high, backstop) in cases) {
+            val cmd = unpackRumbleEvent(pack(pad, low, high, backstop))!!
+            assertEquals("pad", pad, cmd.pad)
+            assertEquals("low", low, cmd.low)
+            assertEquals("high", high, cmd.high)
+            assertEquals("backstop", backstop.toLong(), cmd.backstopMs)
+        }
+    }
+
+    /** MAX_PADS is 16, so all 16 indices must survive the 4-bit field without aliasing. */
+    @Test
+    fun `all sixteen pad indices are distinct`() {
+        val seen = (0 until 16).map { unpackRumbleEvent(pack(it, 1, 2, 3))!!.pad }
+        assertEquals((0 until 16).toList(), seen)
+    }
+
+    @Test
+    fun `the negative sentinel is not a command`() {
+        assertNull(unpackRumbleEvent(-1L))
+        assertNull(unpackRumbleEvent(Long.MIN_VALUE))
+    }
+
+    @Test
+    fun `a stop is distinguishable from a hold`() {
+        val stop = unpackRumbleEvent(pack(2, 0, 0, 0))!!
+        val hold = unpackRumbleEvent(pack(2, 0x8000, 0x8000, 500))!!
+        assertEquals(0, stop.low)
+        assertEquals(0, stop.high)
+        assertNotEquals(stop, hold)
+    }
+
+    // --- wireAmplitudeToByte (was two byte-identical private copies) ---
+
+    @Test
+    fun `amplitude takes the high byte`() {
+        assertEquals(0xFF, wireAmplitudeToByte(0xFFFF))
+        assertEquals(0x80, wireAmplitudeToByte(0x8000))
+        assertEquals(0x12, wireAmplitudeToByte(0x1234))
+    }
+
+    @Test
+    fun `zero stays silent but a weak nonzero never does`() {
+        assertEquals("only a real zero may render as silence", 0, wireAmplitudeToByte(0))
+        // Everything below 0x0100 has a zero high byte — without the floor these all vanish.
+        for (v in listOf(1, 0x0042, 0x00FF)) {
+            assertEquals("wire $v collapsed to silence", 1, wireAmplitudeToByte(v))
+        }
+        assertEquals(1, wireAmplitudeToByte(0x0100)) // first value that reaches 1 on its own
+    }
+}

clients/android/native/src/feedback.rs

@@ -18,6 +18,29 @@ use std::time::Duration;
 /// observes its `running=false` flag promptly on teardown.
 const PULL_TIMEOUT: Duration = Duration::from_millis(100);
 
+/// Width of the packed `pad` field in [`pack_rumble`] — 4 bits, i.e. indices 0..15.
+const PAD_BITS: u32 = 4;
+/// The packing is only lossless while every representable pad index fits in [`PAD_BITS`]. This was
+/// a comment before; growing `MAX_PADS` past 16 would have silently aliased pad 16 onto pad 0
+/// rather than failing the build.
+const _: () = assert!(
+    punktfunk_core::input::MAX_PADS <= 1usize << PAD_BITS,
+    "MAX_PADS no longer fits the 4-bit pad field in the packed rumble long"
+);
+
+/// Pack one effective rumble command into the `jlong` `nativeNextRumble` returns.
+///
+/// Layout — mirrored by `unpackRumbleEvent` in `RumbleWire.kt`: bits 49..52 `pad`, 32..47
+/// `backstop_ms`, 16..31 `low`, 0..15 `high`. Always non-negative, so the `-1` timeout/closed
+/// sentinel stays unambiguous. Split out from the JNI entry point purely so it can be tested
+/// without a live session handle — the shift arithmetic is the part worth pinning.
+fn pack_rumble(pad: u16, low: u16, high: u16, backstop_ms: u32) -> jlong {
+    (jlong::from(pad & ((1 << PAD_BITS) - 1)) << 49)
+        | (jlong::from(backstop_ms.min(0xFFFF) as u16) << 32)
+        | (jlong::from(low) << 16)
+        | jlong::from(high)
+}
+
 // HID-output kind tags written into the returned ByteBuffer (Kotlin reads them back).
 const TAG_LED: u8 = 0x01;
 const TAG_PLAYER_LEDS: u8 = 0x02;
@@ -54,12 +77,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextRumble(
         // handle.
         let h = unsafe { &*(handle as *const SessionHandle) };
         match h.client.next_rumble_command(PULL_TIMEOUT) {
-            Ok(cmd) => {
-                (jlong::from(cmd.pad & 0xF) << 49)
-                    | (jlong::from(cmd.backstop_ms.min(0xFFFF) as u16) << 32)
-                    | (jlong::from(cmd.low) << 16)
-                    | jlong::from(cmd.high)
-            }
+            Ok(cmd) => pack_rumble(cmd.pad, cmd.low, cmd.high, cmd.backstop_ms),
             Err(_) => -1, // NoFrame (timeout) or Closed — Kotlin loops on its running flag
         }
     })
@@ -160,3 +178,65 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextHidout(
         n as jint
     })
 }
+
+#[cfg(test)]
+mod pack_rumble_tests {
+    use super::*;
+    use punktfunk_core::input::MAX_PADS;
+
+    /// Kotlin's `unpackRumbleEvent`, transcribed — if these two ever disagree the boundary is
+    /// broken, and nothing else in the build would say so.
+    fn unpack(ev: jlong) -> (u16, u16, u16, u32) {
+        let pad = ((ev >> 49) & 0xF) as u16;
+        let backstop = ((ev >> 32) & 0xFFFF) as u32;
+        let low = ((ev >> 16) & 0xFFFF) as u16;
+        let high = (ev & 0xFFFF) as u16;
+        (pad, low, high, backstop)
+    }
+
+    #[test]
+    fn round_trips_every_field_at_its_extremes() {
+        for &(pad, low, high, backstop) in &[
+            (0u16, 0u16, 0u16, 0u32),
+            (15, 0xFFFF, 0xFFFF, 0xFFFF),
+            (1, 0x1234, 0x5678, 500),
+            (7, 0, 0xFFFF, 2000),
+        ] {
+            let ev = pack_rumble(pad, low, high, backstop);
+            assert_eq!(unpack(ev), (pad, low, high, backstop), "pad {pad}");
+        }
+    }
+
+    #[test]
+    fn every_representable_pad_survives_the_four_bit_field() {
+        for pad in 0..MAX_PADS as u16 {
+            let (got, ..) = unpack(pack_rumble(pad, 1, 2, 3));
+            assert_eq!(got, pad, "pad {pad} aliased in the packed long");
+        }
+    }
+
+    #[test]
+    fn a_packed_command_is_never_negative() {
+        // `-1` is the timeout/closed sentinel; any packed value colliding with it would read as
+        // "no command" and the rumble would simply vanish.
+        assert!(pack_rumble(15, 0xFFFF, 0xFFFF, 0xFFFF) >= 0);
+        assert!(pack_rumble(0, 0, 0, 0) >= 0);
+    }
+
+    #[test]
+    fn an_oversized_backstop_saturates_instead_of_corrupting_the_pad_field() {
+        let ev = pack_rumble(3, 0, 0, u32::MAX);
+        let (pad, _, _, backstop) = unpack(ev);
+        assert_eq!(pad, 3, "a huge backstop must not bleed into the pad bits");
+        assert_eq!(backstop, 0xFFFF);
+    }
+
+    #[test]
+    fn a_stop_is_distinguishable_from_a_hold() {
+        let stop = pack_rumble(2, 0, 0, 0);
+        let hold = pack_rumble(2, 0x8000, 0x8000, 500);
+        assert_ne!(stop, hold);
+        assert_eq!(unpack(stop).1, 0);
+        assert_eq!(unpack(stop).2, 0);
+    }
+}

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

@@ -675,8 +675,13 @@ final class SessionModel: ObservableObject {
         // `gamepadForwarding` off means the host gets this device's pads from somewhere else
         // (USB passthrough, or a pad plugged into the host) — capture still runs, and still
         // watches for the escape chord, but puts nothing on the wire.
+        // System-button routing: whether raw guide/share presses ride the wire, and whether
+        // hold-Select arms as the alternate guide route (auto = on everywhere but macOS —
+        // iOS reserves the physical Home press, tvOS never delivers it).
         let capture = GamepadCapture(
-            connection: conn, manager: .shared, forwarding: settings.gamepadForwarding)
+            connection: conn, manager: .shared, forwarding: settings.gamepadForwarding,
+            systemForward: settings.systemButtonsForward,
+            guideGesture: settings.guideGestureEnabled)
         // The cross-client escape chord (hold L1+R1+Start+Select 1.5 s) — on tvOS the only
         // controller way out of a stream (B/Menu is swallowed during sessions; see ContentView).
         capture.onDisconnectRequest = { [weak self] in self?.disconnect() }

clients/apple/Sources/PunktfunkClient/Settings/GamepadSettingsView.swift

@@ -39,6 +39,8 @@ struct GamepadSettingsView: View {
     @AppStorage(DefaultsKey.compositor) private var compositor = 0
     @AppStorage(DefaultsKey.gamepadType) private var gamepadType = 0
     @AppStorage(DefaultsKey.gamepadForwarding) private var gamepadForwarding = true
+    @AppStorage(DefaultsKey.systemButtons) private var systemButtons = "auto"
+    @AppStorage(DefaultsKey.guideGesture) private var guideGesture = "auto"
     @AppStorage(DefaultsKey.bitrateKbps) private var bitrateKbps = 0
     @AppStorage(DefaultsKey.audioChannels) private var audioChannels = 2
     @AppStorage(DefaultsKey.hdrEnabled) private var hdrEnabled = true
@@ -164,6 +166,11 @@ struct GamepadSettingsView: View {
     /// layer" rule), and a hostless picker has nothing to pin, so only Back remains.
     private var hints: [GamepadHint] {
         guard pinTarget != nil else {
+            // A dimmed row takes neither, so offering them would be the same lie the row itself
+            // used to tell — only Done remains, and the detail line says what to turn on first.
+            guard rows.first(where: { $0.id == focusID })?.enabled ?? true else {
+                return [.init(glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Done")]
+            }
             return [
                 .init(glyph: "arrow.left.and.right", text: "Adjust"),
                 .init(glyph: buttonGlyph(\.buttonA, fallback: "a.circle"), text: "Change"),
@@ -216,7 +223,8 @@ struct GamepadSettingsView: View {
                 HStack(spacing: 9) {
                     Image(systemName: "chevron.left")
                         .font(.system(size: m.chevronFont, weight: .semibold))
-                        .foregroundStyle(.white.opacity(focused && row.adjustable ? 0.6 : 0))
+                        .foregroundStyle(
+                            .white.opacity(focused && row.adjustable && row.enabled ? 0.6 : 0))
                     // Keyed by the value so a change slides the new option in instead of
                     // hard-swapping the string — a QUIET horizontal slip following the user's
                     // motion (a right-step enters from the right), crossfading over ~14 pt.
@@ -237,9 +245,13 @@ struct GamepadSettingsView: View {
                     .animation(.smooth(duration: 0.22), value: row.value)
                     Image(systemName: "chevron.right")
                         .font(.system(size: m.chevronFont, weight: .semibold))
-                        .foregroundStyle(.white.opacity(focused && row.adjustable ? 0.6 : 0))
+                        .foregroundStyle(
+                            .white.opacity(focused && row.adjustable && row.enabled ? 0.6 : 0))
                 }
             }
+            // Contents only — the glass and border below stay at full strength, so a dimmed row
+            // still reads as a row you can sit on (which you can: its detail is the point).
+            .opacity(row.enabled ? 1 : 0.45)
             .padding(.horizontal, m.rowHPad)
             .padding(.vertical, m.rowVPad)
             // Every row is Liquid Glass; the focused one takes a brand wash and reacts to press.
@@ -274,6 +286,13 @@ struct GamepadSettingsView: View {
         /// Whether left/right means anything here — false hides the value's chevrons (the
         /// Profiles rows navigate, and the placeholder rows do nothing at all).
         var adjustable = true
+        /// Dimmed and inert when false: a row whose meaning depends on another setting that is
+        /// currently off. It stays in the list and stays FOCUSABLE — its `detail` is how the
+        /// user learns which switch to flip first, and a row that vanished mid-list would
+        /// shift everything under the cursor. Enforced centrally in `adjust(id:by:)` /
+        /// `activate(id:)`, not per closure, so no row builder can forget it.
+        /// (Android's `GpRow.enabled` and `pf-console-ui`'s `RowSpec.enabled` are the twins.)
+        var enabled = true
         /// Left/right step; returns whether the value actually changed (false ⇒ boundary thud).
         let adjust: (Int) -> Bool
         /// A — cycle forward (wrapping) / flip.
@@ -284,12 +303,14 @@ struct GamepadSettingsView: View {
     /// (never on state captured at wire time).
     private func adjust(id: String, by delta: Int) -> Bool {
         lastAdjustDelta = delta
-        return rows.first { $0.id == id }?.adjust(delta) ?? false
+        guard let row = rows.first(where: { $0.id == id }), row.enabled else { return false }
+        return row.adjust(delta)
     }
 
     private func activate(id: String) {
         lastAdjustDelta = 1 // A always cycles forward
-        rows.first { $0.id == id }?.activate()
+        guard let row = rows.first(where: { $0.id == id }), row.enabled else { return }
+        row.activate()
     }
 
     private var rows: [Row] {
@@ -389,16 +410,36 @@ struct GamepadSettingsView: View {
                     + "controller already reaches the host another way — USB passthrough such "
                     + "as VirtualHere — so games don't see two of them.",
                 value: $gamepadForwarding),
+            // The four rows below only mean something while something is being forwarded, so
+            // they follow the switch above — the same relationship the touch settings draw with
+            // `.disabled(!effective.gamepadForwarding)`. This screen could not express it until
+            // `Row.enabled` existed, so it alone left them live and steppable.
             choiceRow(
                 id: "pad", icon: "gamecontroller", label: "Use controller",
                 detail: "Which pad is forwarded to the host, as player 1.",
-                options: controllers, current: gamepads.preferredID
+                options: controllers, current: gamepads.preferredID,
+                enabled: gamepadForwarding
             ) { gamepads.preferredID = $0 },
             choiceRow(
                 id: "padType", icon: "dpad", label: "Controller type",
                 detail: "The virtual pad the host creates — Automatic matches this controller.",
-                options: SettingsOptions.padTypes, current: gamepadType
+                options: SettingsOptions.padTypes, current: gamepadType,
+                enabled: gamepadForwarding
             ) { gamepadType = $0 },
+            choiceRow(
+                id: "systemButtons", icon: "house.circle", label: "Guide button",
+                detail: "Where the guide (Xbox/PS) and share presses go while streaming — "
+                    + "Automatic sends them to the host whenever this device delivers them.",
+                options: SettingsOptions.systemButtons, current: systemButtons,
+                enabled: gamepadForwarding
+            ) { systemButtons = $0 },
+            choiceRow(
+                id: "guideGesture", icon: "hand.point.up.left", label: "Hold Select for guide",
+                detail: "Hold Select alone to press the host's guide button — keep holding "
+                    + "for a Gaming-Mode host's quick-access menu. A tap still goes through.",
+                options: SettingsOptions.guideGestures, current: guideGesture,
+                enabled: gamepadForwarding
+            ) { guideGesture = $0 },
 
             choiceRow(
                 id: "hud", header: "Interface", icon: "chart.bar", label: "Statistics overlay",
@@ -569,13 +610,15 @@ struct GamepadSettingsView: View {
 
     private func choiceRow<T: Equatable>(
         id: String, header: String? = nil, icon: String, label: String, detail: String,
-        options: [(label: String, tag: T)], current: T, write: @escaping (T) -> Void
+        options: [(label: String, tag: T)], current: T, enabled: Bool = true,
+        write: @escaping (T) -> Void
     ) -> Row {
         let index = options.firstIndex { $0.tag == current }
         return Row(
             id: id, header: header, icon: icon, label: label,
             value: index.map { options[$0].label } ?? "—",
             detail: detail,
+            enabled: enabled,
             adjust: { delta in
                 // Unknown current value: snap to the first option on any step.
                 guard let index else {
@@ -596,12 +639,13 @@ struct GamepadSettingsView: View {
 
     private func toggleRow(
         id: String, header: String? = nil, icon: String, label: String, detail: String,
-        value: Binding<Bool>
+        value: Binding<Bool>, enabled: Bool = true
     ) -> Row {
         Row(
             id: id, header: header, icon: icon, label: label,
             value: value.wrappedValue ? "On" : "Off",
             detail: detail,
+            enabled: enabled,
             adjust: { delta in
                 // Directional semantics: left = off, right = on; a no-op reads as a boundary.
                 let target = delta > 0

clients/apple/Sources/PunktfunkClient/Settings/SettingsOptions.swift

@@ -34,6 +34,22 @@ enum SettingsOptions {
         ("DualShock 4", 4),
     ]
 
+    /// System-button routing (the cross-client `system_buttons` key): where the guide
+    /// (Xbox/PS) and share presses land while streaming. Auto = forward on Apple.
+    static let systemButtons: [(label: String, tag: String)] = [
+        ("Automatic", "auto"),
+        ("Send to host", "forward"),
+        ("This device", "local"),
+    ]
+
+    /// The hold-Select guide gesture (the cross-client `guide_gesture` key). Auto = on
+    /// everywhere but macOS.
+    static let guideGestures: [(label: String, tag: String)] = [
+        ("Automatic", "auto"),
+        ("On", "on"),
+        ("Off", "off"),
+    ]
+
     static let hudPlacements: [(label: String, tag: String)] =
         HUDPlacement.allCases.map { ($0.label, $0.rawValue) }
 

clients/apple/Sources/PunktfunkClient/Settings/SettingsView+Scope.swift

@@ -126,6 +126,14 @@ enum SettingsFields {
         .init(name: "gamepad_forwarding", key: DefaultsKey.gamepadForwarding,
               overlay: \.gamepadForwarding, effective: \.gamepadForwarding)
     }
+    static var systemButtons: SettingsField<String> {
+        .init(name: "system_buttons", key: DefaultsKey.systemButtons,
+              overlay: \.systemButtons, effective: \.systemButtons)
+    }
+    static var guideGesture: SettingsField<String> {
+        .init(name: "guide_gesture", key: DefaultsKey.guideGesture,
+              overlay: \.guideGesture, effective: \.guideGesture)
+    }
     static var statsVerbosity: SettingsField<String> {
         .init(name: "stats_verbosity", key: DefaultsKey.statsVerbosity,
               overlay: \.statsVerbosity, effective: \.statsVerbosity)

clients/apple/Sources/PunktfunkClient/Settings/SettingsView+Sections.swift

@@ -681,6 +681,29 @@ extension SettingsView {
                 }
                 .disabled(!effective.gamepadForwarding)
             }
+            described("Where the guide (Xbox/PS) and share presses go while streaming. "
+                + "Automatic sends them to the host whenever this device delivers them "
+                + "— the hold-Select gesture below reaches the host regardless.",
+                field: "system_buttons") {
+                Picker("Guide button", selection: scoped(SettingsFields.systemButtons)) {
+                    Text("Automatic").tag("auto")
+                    Text("Send to host").tag("forward")
+                    Text("This device").tag("local")
+                }
+                .disabled(!effective.gamepadForwarding)
+            }
+            described("Hold Select on its own to press the host's guide button — keep "
+                + "holding for a Gaming-Mode host's quick-access menu. A Select tap still "
+                + "goes through, slightly delayed. Automatic arms it wherever the real "
+                + "button can't reach the host (this device reserves it).",
+                field: "guide_gesture") {
+                Picker("Hold Select for guide", selection: scoped(SettingsFields.guideGesture)) {
+                    Text("Automatic").tag("auto")
+                    Text("On").tag("on")
+                    Text("Off").tag("off")
+                }
+                .disabled(!effective.gamepadForwarding)
+            }
             #if os(iOS)
             // iPhone only in practice: hidden where the device itself can't play haptics (iPad).
             if !inProfileScope, CHHapticEngine.capabilitiesForHardware().supportsHaptics {

clients/apple/Sources/PunktfunkKit/Gamepad/ControllerTester.swift

@@ -12,7 +12,7 @@ import GameController
 public final class ControllerTester: ObservableObject {
     // `.manual`: the panel's toggles hold a level until changed — no session wire refreshes
     // exist here to keep the renderer's staleness watchdog fed.
-    private let renderer = RumbleRenderer(policy: .manual)
+    private let renderer = RumbleRenderer()
     private weak var controller: GCController?
 
     /// The rumble backend now in use — "DualSense HID · USB/Bluetooth", "CoreHaptics", or "—" —

clients/apple/Sources/PunktfunkKit/Gamepad/DualSenseHID.swift

@@ -21,8 +21,12 @@ import os
 
 private let log = Logger(subsystem: "io.unom.punktfunk", category: "gamepad")
 
-/// Opens the first connected Sony DualSense and forwards motor rumble to it over raw HID.
-/// Single-pad model (we forward exactly one controller), so the first match is the right one.
+/// Opens one connected Sony DualSense and forwards motor rumble to it over raw HID.
+///
+/// A caller that owns a particular pad passes the location id it wants (see
+/// `open(preferringLocationID:)`); the renderer takes that from the `GCController` it is bound to,
+/// so with two DualSenses attached each renderer drives its own device. Without a preference the
+/// lowest location id wins — an arbitrary but *stable* choice, where `Set.first` was neither.
 final class DualSenseHID {
     private let manager: IOHIDManager
     private var device: IOHIDDevice?
@@ -43,9 +47,57 @@ final class DualSenseHID {
 
     deinit { close() }
 
-    /// Find and open the first connected DualSense. Returns false if none is present or it can't
-    /// be opened (caller then falls back to CoreHaptics).
-    func open() -> Bool {
+    /// The IOKit location id of the device this instance opened — the handle a caller correlates
+    /// with its `GCController`. `nil` until a successful `open`.
+    private(set) var locationID: UInt32?
+
+    /// A device's location id, or `nil` if IOKit does not report one.
+    static func locationID(of dev: IOHIDDevice) -> UInt32? {
+        IOHIDDeviceGetProperty(dev, kIOHIDLocationIDKey as CFString) as? UInt32
+    }
+
+    /// Every connected DualSense/Edge, by location id — what a caller pairs against its controllers.
+    static func attachedLocationIDs() -> [UInt32] {
+        let mgr = IOHIDManagerCreate(kCFAllocatorDefault, IOOptionBits(kIOHIDOptionsTypeNone))
+        let matches = productIDs.map { pid in
+            [kIOHIDVendorIDKey: vendorSony, kIOHIDProductIDKey: pid] as CFDictionary
+        }
+        IOHIDManagerSetDeviceMatchingMultiple(mgr, matches as CFArray)
+        guard IOHIDManagerOpen(mgr, IOOptionBits(kIOHIDOptionsTypeNone)) == kIOReturnSuccess else {
+            return []
+        }
+        defer { IOHIDManagerClose(mgr, IOOptionBits(kIOHIDOptionsTypeNone)) }
+        let devices = IOHIDManagerCopyDevices(mgr) as? Set<IOHIDDevice> ?? []
+        return devices.compactMap(locationID(of:)).sorted()
+    }
+
+    /// Which attached device to drive, as an index into `ids` — the whole selection rule, pure so
+    /// it can be tested without an `IOHIDDevice` (which cannot be constructed).
+    ///
+    /// `IOHIDManagerCopyDevices` returns an unordered `Set`, so the previous `Set.first` was not
+    /// merely arbitrary — it can differ between two calls in one process. With two DualSenses that
+    /// made each renderer's pad→device binding a coin flip: both could land on the same device
+    /// (one pad's rumble coming out of the other, and the two per-instance write dedupes fighting
+    /// over it) or split by luck. An explicit location id makes the binding deterministic; the
+    /// lowest-id fallback at least makes it stable. `nil` ids sort last so a device IOKit cannot
+    /// place never displaces one it can.
+    static func preferredIndex(among ids: [UInt32?], preferring wanted: UInt32?) -> Int? {
+        if let wanted, let hit = ids.firstIndex(where: { $0 == wanted }) { return hit }
+        return ids.indices.min { (ids[$0] ?? .max) < (ids[$1] ?? .max) }
+    }
+
+    /// Pick the device to drive from everything attached (see [`preferredIndex`]).
+    static func pick(_ devices: Set<IOHIDDevice>, preferring wanted: UInt32?) -> IOHIDDevice? {
+        let ordered = Array(devices)
+        guard let i = preferredIndex(among: ordered.map(locationID(of:)), preferring: wanted) else {
+            return nil
+        }
+        return ordered[i]
+    }
+
+    /// Find and open a connected DualSense, preferring the one at `preferredLocationID`. Returns
+    /// false if none is present or it can't be opened (caller then falls back to CoreHaptics).
+    func open(preferringLocationID preferred: UInt32? = nil) -> Bool {
         let matches = Self.productIDs.map { pid in
             [kIOHIDVendorIDKey: Self.vendorSony, kIOHIDProductIDKey: pid] as CFDictionary
         }
@@ -55,13 +107,21 @@ final class DualSenseHID {
             return false
         }
         guard let devices = IOHIDManagerCopyDevices(manager) as? Set<IOHIDDevice>,
-              let dev = devices.first
+              let dev = Self.pick(devices, preferring: preferred)
         else {
             log.info("rumble: no DualSense HID device found — falling back to CoreHaptics")
             IOHIDManagerClose(manager, IOOptionBits(kIOHIDOptionsTypeNone))
             return false
         }
         device = dev
+        locationID = Self.locationID(of: dev)
+        if let preferred, locationID != preferred {
+            // Not fatal — one pad still gets rumble — but with two pads attached it means this
+            // renderer is driving the wrong one, and it is invisible without the log line.
+            log.error(
+                "rumble: wanted DualSense at location \(preferred, privacy: .public) but opened \(self.locationID.map(String.init) ?? "unknown", privacy: .public)"
+            )
+        }
         let transport = IOHIDDeviceGetProperty(dev, kIOHIDTransportKey as CFString) as? String
         bluetooth = transport?.lowercased().contains("bluetooth") ?? false
         log.info("rumble: DualSense raw-HID rumble active (transport=\(self.transport, privacy: .public))")
@@ -70,8 +130,16 @@ final class DualSenseHID {
 
     /// Drive the motors. `low` = left/heavy (low-frequency), `high` = right/light (high-frequency),
     /// each 0...255. (0, 0) stops.
-    func rumble(low: UInt8, high: UInt8) {
-        guard let dev = device else { return }
+    ///
+    /// Returns whether the write reached the device. The caller needs this: it used to be logged
+    /// and swallowed, so a failed write still counted as a successful render. That matters most
+    /// for a **stop**, which has nothing behind it — the renderer stamps its write clock even on
+    /// failure, the keepalive re-write only fires for non-zero levels, and the ticker is cancelled
+    /// once the target is `(0, 0)`. On USB there is no firmware timeout either, so a swallowed
+    /// stop left the motors running with nothing scheduled to try again.
+    @discardableResult
+    func rumble(low: UInt8, high: UInt8) -> Bool {
+        guard let dev = device else { return false }
         let report = bluetooth
             ? Self.bluetoothReport(low: low, high: high)
             : Self.usbReport(low: low, high: high)
@@ -81,7 +149,9 @@ final class DualSenseHID {
         }
         if rc != kIOReturnSuccess {
             log.error("rumble: IOHIDDeviceSetReport failed (0x\(String(format: "%08x", rc), privacy: .public))")
+            return false
         }
+        return true
     }
 
     func close() {

clients/apple/Sources/PunktfunkKit/Gamepad/GamepadCapture.swift

@@ -67,6 +67,17 @@ public final class GamepadCapture {
         var axes: [Int32] = [0, 0, 0, 0, 0, 0]
         var fingerActive: [Bool] = [false, false]
         var lastMotionNs: UInt64 = 0
+        // Hold-Select→guide gesture state (pf-client-core's `SelectGesture`, adapted to
+        // this class's mask-diff model): a Select pressed ALONE is held out of the mask
+        // until it resolves into a tap (delivered on release) or — past `guideHold` — a
+        // synthetic guide, down until release.
+        var selectPending = false
+        var selectAsGuide = false
+        /// A delivered tap's release is owed (`tapTimer` scheduled) — its down went out
+        /// outside `buttons`, so `flush` must know to lift it.
+        var tapReleaseOwed = false
+        var gestureTimer: Timer?
+        var tapTimer: Timer?
         init(controller: GCController, pad: UInt32, pref: PunktfunkConnection.GamepadType) {
             self.controller = controller
             self.pad = pad
@@ -87,10 +98,29 @@ public final class GamepadCapture {
     /// `onDisconnectRequest`; the chord keeps forwarding to the host meanwhile (the user is
     /// leaving anyway). The desktop clients' quick-press step (leave fullscreen / release
     /// capture) has no Apple equivalent worth wiring — macOS has ⌃⌥⇧Q/D, touch has the HUD.
-    private static let escapeChord: UInt32 =
+    /// Internal rather than private only so `GamepadEscapeChordTests` can pin it against
+    /// `escapeChordElements` below — the two must not drift.
+    static let escapeChord: UInt32 =
         GamepadWire.leftShoulder | GamepadWire.rightShoulder | GamepadWire.start | GamepadWire.back
+    /// `escapeChord`'s four elements by GameController alias — the ONLY system gestures claimed
+    /// while forwarding is off (see `openSlot`). Kept beside the mask it mirrors: change one and
+    /// change the other, or the chord silently stops reaching us on tvOS. A test asserts the two
+    /// agree, because the failure is invisible until someone is stuck in a stream on an Apple TV.
+    static let escapeChordElements = [
+        GCInputLeftShoulder, GCInputRightShoulder, GCInputButtonMenu, GCInputButtonOptions,
+    ]
     /// pf-client-core's `DISCONNECT_HOLD` — the same 1.5 s on every client.
     private static let disconnectHold: TimeInterval = 1.5
+    /// pf-client-core's `GUIDE_HOLD`: hold Select alone this long → the HOST's guide goes
+    /// down (until release, so a long hold is the host's long-press — a Gaming-Mode
+    /// host's QAM). The gesture exists because iOS reserves the physical Home press (the
+    /// Game Overlay; sanctioned opt-out only via the user's iOS 27+ Home-button setting)
+    /// and tvOS never delivers it at all.
+    private static let guideHold: TimeInterval = 0.35
+    /// pf-client-core's `TAP_PRESS`: a held-back Select tap is delivered as a press with
+    /// its release this far behind — back-to-back transitions can fold into nothing in
+    /// the host's per-pad input fold.
+    private static let tapPress: TimeInterval = 0.05
     private var chordTimer: Timer?
     /// Fired ON MAIN once the escape chord has been held `disconnectHold` — the session owner
     /// disconnects. On tvOS this (plus the Siri Remote's hold-Back) is the ONLY way out of a
@@ -115,10 +145,23 @@ public final class GamepadCapture {
     /// "don't forward" is one fact in one place rather than a condition at twelve call sites.
     private var wire: PunktfunkConnection? { forwarding ? connection : nil }
 
-    public init(connection: PunktfunkConnection, manager: GamepadManager, forwarding: Bool = true) {
+    /// Forward the raw guide + share/QAM presses (`EffectiveSettings.systemButtonsForward`,
+    /// default true on Apple — where the OS shows its own overlay for them, that's the OS's
+    /// business; local mode exists for profile parity with the Gaming-Mode clients).
+    public let systemForward: Bool
+    /// The hold-Select guide gesture (`EffectiveSettings.guideGestureEnabled` — auto = on
+    /// everywhere but macOS). See `guideHold`.
+    public let guideGesture: Bool
+
+    public init(
+        connection: PunktfunkConnection, manager: GamepadManager, forwarding: Bool = true,
+        systemForward: Bool = true, guideGesture: Bool = false
+    ) {
         self.connection = connection
         self.manager = manager
         self.forwarding = forwarding
+        self.systemForward = systemForward
+        self.guideGesture = guideGesture
     }
 
     public func start() {
@@ -202,11 +245,28 @@ public final class GamepadCapture {
         // gesture attached the press is the system's, not the game's. During capture the remote
         // session IS the game: the share button must reach the host (e.g. Steam screenshots),
         // the PS button must open the host's Steam overlay. Restored to .enabled on close.
-        for element in c.physicalInputProfile.elements.values {
+        //
+        // With forwarding OFF none of that applies — no press reaches the host, so taking the
+        // user's screenshot gesture away buys nothing. NARROWED, not skipped: the escape chord
+        // is still read off this slot, and on tvOS it is the only controller way out of a
+        // stream, so the chord's own four elements keep their claim. (Menu especially: leave
+        // its gesture attached on tvOS and the press is the system's — the chord would never
+        // complete and the session would have no controller exit at all.)
+        let claimed = forwarding
+            ? Array(c.physicalInputProfile.elements.values)
+            : Self.escapeChordElements.compactMap { c.physicalInputProfile.elements[$0] }
+        for element in claimed {
             element.preferredSystemGestureState = .disabled
         }
         // The Home/PS button (→ guide; the host maps it to the DualSense PS / Xbox guide bit,
-        // BTN_MODE on the virtual xpad — the Steam-overlay button). Driven DIRECTLY from this
+        // BTN_MODE on the virtual xpad — the Steam-overlay button). On iOS 26 the OS opens its
+        // Game Overlay for this press regardless of the gesture claim below (the app is
+        // LSApplicationCategoryType=games, which enrolls it); the sanctioned per-controller
+        // opt-out is the USER's iOS 27+ Home-button setting. TODO(iOS 27 SDK): read
+        // `GCControllerHomeButtonSettingsManager` and surface a one-time
+        // `openControllerHomeButtonSettings(for:)` deep-link so users can hand the button to
+        // the stream — the class is Swift-only and 27.0+, so it needs the Xcode 27 SDK to
+        // even compile. Until then hold-Select is the reliable route. Driven DIRECTLY from this
         // handler's pressed value (not via buttonMask), because the legacy
         // `extendedGamepad.buttonHome` is unreliable/often nil even when the physical element
         // exists. On tvOS the element is absent (reserved) → nil, the whole block no-ops.
@@ -235,7 +295,11 @@ public final class GamepadCapture {
                 MainActor.assumeIsolated { if let self, let slot { self.touch(slot, finger: 1, x: x, y: y) } }
             }
         }
-        if let motion = c.motion {
+        // Motion is wire-only — `forwardMotion` has nothing to do with forwarding off, and no
+        // local feature reads it. Powering the IMU anyway costs the pad real battery (it streams
+        // gyro + accel continuously over Bluetooth, which is why `closeSlot` is careful to power
+        // it back down), so with nothing to forward we simply never turn it on.
+        if forwarding, let motion = c.motion {
             if motion.sensorsRequireManualActivation { motion.sensorsActive = true }
             motion.valueChangedHandler = { [weak self, weak slot] m in
                 MainActor.assumeIsolated { if let self, let slot { self.forwardMotion(slot, m) } }
@@ -289,7 +353,14 @@ public final class GamepadCapture {
         // as "changed" — otherwise the first stick/button move after a guide press would emit a
         // spurious guide-UP while the button is still physically held (and drop the bit from
         // `slot.buttons`, swallowing the real release too). `flush`/`allButtons` still release it.
-        let newButtons = Self.buttonMask(g) | (slot.buttons & GamepadWire.guide)
+        var raw = Self.buttonMask(g)
+        // Raw system buttons stay local when passthrough is off: misc1 (share/QAM) is
+        // masked here, guide is gated at its own handler.
+        if !systemForward { raw &= ~GamepadWire.misc1 }
+        // The hold-Select gesture rewrites the mask: a Select pressed alone is held out
+        // until it resolves (tap on release / synthetic guide past the threshold).
+        if guideGesture { raw = gestureFiltered(slot, raw) }
+        let newButtons = raw | (slot.buttons & GamepadWire.guide)
         let changed = newButtons ^ slot.buttons
         if changed != 0 {
             for bit in GamepadWire.allButtons where changed & bit != 0 {
@@ -312,10 +383,106 @@ public final class GamepadCapture {
         updateEscapeChord()
     }
 
+    /// The hold-Select→guide state machine over one sync's raw mask (pf-client-core's
+    /// `SelectGesture` rules): Select pressed ALONE is suppressed while pending; another
+    /// button joining makes it real (unsuppressed — the diff sends its down); released
+    /// inside `guideHold` it's a tap, delivered out-of-band on release with the release
+    /// `tapPress` behind; past the threshold `gestureHoldFired` turned it into a synthetic
+    /// guide, lifted here when Select physically releases.
+    ///
+    /// One deliberate divergence from the Rust worker: while transformed into a guide the
+    /// Select stays OUT of `slot.buttons`, so the escape chord doesn't complete on top of
+    /// an in-flight guide-hold — release Select and press the chord plainly instead (the
+    /// chord's four-at-once press never lingers in pending long enough to be affected).
+    private func gestureFiltered(_ slot: Slot, _ raw: UInt32) -> UInt32 {
+        let back = GamepadWire.back
+        let backDown = raw & back != 0
+        let othersDown = raw & ~back != 0
+        if slot.selectAsGuide {
+            if backDown { return raw & ~back }
+            slot.selectAsGuide = false
+            sendGuide(slot, down: false, raw: false)
+            return raw
+        }
+        if slot.selectPending {
+            if !backDown {
+                endPending(slot)
+                deliverTap(slot)
+                return raw
+            }
+            if othersDown {
+                // A combo after all — Select unsuppresses and the diff sends its down.
+                endPending(slot)
+                return raw
+            }
+            return raw & ~back
+        }
+        if backDown, !othersDown, slot.buttons & back == 0 {
+            // Newly pressed, alone: hold it back. An owed tap release goes out first so
+            // the host never sees two downs in a row.
+            if slot.tapReleaseOwed { finishTap(slot) }
+            slot.selectPending = true
+            let timer = Timer(timeInterval: Self.guideHold, repeats: false) { [weak self, weak slot] _ in
+                Task { @MainActor in
+                    if let self, let slot { self.gestureHoldFired(slot) }
+                }
+            }
+            RunLoop.main.add(timer, forMode: .common)
+            slot.gestureTimer?.invalidate()
+            slot.gestureTimer = timer
+            return raw & ~back
+        }
+        return raw
+    }
+
+    /// The hold threshold passed with Select still pending → it IS the guide now, down
+    /// until the physical release (`gestureFiltered`'s `selectAsGuide` branch lifts it).
+    private func gestureHoldFired(_ slot: Slot) {
+        guard slot.selectPending else { return }
+        slot.selectPending = false
+        slot.gestureTimer = nil
+        slot.selectAsGuide = true
+        sendGuide(slot, down: true, raw: false)
+    }
+
+    private func endPending(_ slot: Slot) {
+        slot.selectPending = false
+        slot.gestureTimer?.invalidate()
+        slot.gestureTimer = nil
+    }
+
+    /// Deliver a held-back Select tap: the press now, its release `tapPress` behind. Both
+    /// sends bypass `slot.buttons` (the raw mask no longer carries Select, so the diff
+    /// stays consistent); `tapReleaseOwed` is what `flush` checks so the press can't
+    /// outlive the slot.
+    private func deliverTap(_ slot: Slot) {
+        wire?.send(.gamepadButton(GamepadWire.back, down: true, pad: slot.pad))
+        slot.tapReleaseOwed = true
+        let timer = Timer(timeInterval: Self.tapPress, repeats: false) { [weak self, weak slot] _ in
+            Task { @MainActor in
+                if let self, let slot { self.finishTap(slot) }
+            }
+        }
+        RunLoop.main.add(timer, forMode: .common)
+        slot.tapTimer?.invalidate()
+        slot.tapTimer = timer
+    }
+
+    private func finishTap(_ slot: Slot) {
+        guard slot.tapReleaseOwed else { return }
+        slot.tapReleaseOwed = false
+        slot.tapTimer?.invalidate()
+        slot.tapTimer = nil
+        wire?.send(.gamepadButton(GamepadWire.back, down: false, pad: slot.pad))
+    }
+
     /// Forward the guide (Home/PS) transition directly — it's kept out of `buttonMask` (the legacy
     /// `buttonHome` element is unreliable). Folds into the slot's `buttons` so a held PS button is
-    /// released by `flush` on focus loss / close just like the others.
-    private func sendGuide(_ slot: Slot, down: Bool) {
+    /// released by `flush` on focus loss / close just like the others. `raw: true` marks the
+    /// physical Home handler's calls, which the system-buttons policy can keep local; the
+    /// gesture's synthetic transitions pass `raw: false` and always go out.
+    private func sendGuide(_ slot: Slot, down: Bool, raw: Bool = true) {
+        if raw, !systemForward { return }
         guard !suspended else { return }
         let bit = GamepadWire.guide
         let now = down ? (slot.buttons | bit) : (slot.buttons & ~bit)
@@ -449,6 +616,12 @@ public final class GamepadCapture {
     /// (no GC calls) — safe against an already-removed device. Does NOT close the slot or send
     /// GamepadRemove (that's `closeSlot`).
     private func flush(_ slot: Slot) {
+        // Gesture first: a pending (never-sent) Select just drops, an owed tap release
+        // goes out, and a transformed guide's bit — folded into `buttons` by `sendGuide`
+        // — is lifted by the loop below like any held button.
+        endPending(slot)
+        slot.selectAsGuide = false
+        if slot.tapReleaseOwed { finishTap(slot) }
         for bit in GamepadWire.allButtons where slot.buttons & bit != 0 {
             wire?.send(.gamepadButton(bit, down: false, pad: slot.pad))
         }

clients/apple/Sources/PunktfunkKit/Gamepad/GamepadFeedback.swift

@@ -65,7 +65,7 @@ public final class GamepadFeedback {
         #if os(iOS)
         if UserDefaults.standard.bool(forKey: DefaultsKey.rumbleOnDevice),
             CHHapticEngine.capabilitiesForHardware().supportsHaptics {
-            deviceRumble = RumbleRenderer(policy: .session, actuator: .device)
+            deviceRumble = RumbleRenderer(actuator: .device)
         } else {
             deviceRumble = nil
         }
@@ -117,7 +117,15 @@ public final class GamepadFeedback {
             reset(slot.controller)
             slots[pad] = nil
             let renderer = withRouting { rumbleByPad.removeValue(forKey: pad) }
-            renderer?.stop()
+            // OFF the main actor. `RumbleRenderer.stop()` is a `queue.sync`, and its body is a
+            // per-motor `CHHapticEngine.stop()` — an XPC round trip to gamecontrollerd, which the
+            // renderer's own notes record as able to hang — plus `DualSenseHID.close()`, whose
+            // blocking `IOHIDDeviceSetReport` goes to a device that has just departed. It also
+            // queues behind any in-flight `setup()`. This runs on every unplug and every pin
+            // change, and the main thread is what drives the presenter's CADisplayLink, so
+            // blocking here hitches the picture mid-stream. The renderer is already detached from
+            // routing above, so nothing observes it after this point.
+            if let renderer { Task.detached { renderer.stop() } }
         }
         for (pad, controller) in want {
             if let slot = slots[pad] {
@@ -128,7 +136,7 @@ public final class GamepadFeedback {
                 replay(slot)
             } else {
                 slots[pad] = Slot(controller: controller)
-                let renderer = RumbleRenderer(policy: .session)
+                let renderer = RumbleRenderer()
                 renderer.retarget(controller)
                 withRouting { rumbleByPad[pad] = renderer }
             }
@@ -282,6 +290,12 @@ public final class GamepadFeedback {
     private func reset(_ controller: GCController?) {
         guard let c = controller else { return }
         c.playerIndex = .indexUnset
+        // Put the lightbar out too. This class is what turned it on (see the `Led` and
+        // `PlayerLeds` arms), and every DS write is valid-flag-selective, so a colour the game
+        // set stays lit in firmware after the stream ends — back at the launcher, or for a pad
+        // that merely left the forwarded set. A DS4 is cleared incidentally because its player
+        // indicator IS the lightbar; a DualSense is not.
+        c.light?.color = GCColor(red: 0, green: 0, blue: 0)
         if let ds = c.extendedGamepad as? GCDualSenseGamepad {
             ds.leftTrigger.setModeOff()
             ds.rightTrigger.setModeOff()

clients/apple/Sources/PunktfunkKit/Gamepad/RumbleRenderer.swift

@@ -43,8 +43,14 @@ enum RumbleTuning {
 
     /// Wire amplitude (0...0xFFFF) → CoreHaptics intensity (0...1).
     static func amplitude(_ wire: UInt16) -> Float { Float(wire) / 65535 }
-    /// Wire amplitude → DualSense HID motor byte.
-    static func hidByte(_ wire: UInt16) -> UInt8 { UInt8(wire >> 8) }
+    /// Wire amplitude → DualSense HID motor byte. A nonzero command never collapses to silence:
+    /// the top byte of anything below 0x0100 is 0, so a weak-but-real rumble used to render as
+    /// nothing at all on this path. Floored at 1 — imperceptibly light, but moving. (Android's
+    /// `toAmplitude` has always done this; this was the odd one out.)
+    static func hidByte(_ wire: UInt16) -> UInt8 {
+        let b = UInt8(wire >> 8)
+        return wire != 0 && b == 0 ? 1 : b
+    }
     /// Single-actuator pads render whichever motor is stronger.
     static func combined(low: UInt16, high: UInt16) -> UInt16 { max(low, high) }
     /// Are two baked levels the same (skip the rebuild)?
@@ -81,10 +87,11 @@ enum RumbleTuning {
 ///  4. **Escalating stop.** A throwing `player.stop` means the engine's state is unknown — the
 ///     whole engine is stopped (silencing every player it hosts) and lazily rebuilt behind the
 ///     exponential backoff.
-///  5. **Staleness watchdog** (`Policy.session`): audible with no wire command for
-///     `sessionStaleSeconds` → force silence. A lost stop can outlive the host's 500 ms heal
-///     only if the channel itself died, and then the pad must not buzz forever. `Policy.manual`
-///     (the settings test panel) instead holds a level until it is changed.
+///  5. **No staleness watchdog here.** There was one, keyed off a `Policy` type and a
+///     `sessionStaleSeconds`; both are gone. Every liveness decision — lease expiry, legacy-host
+///     staleness, session close — now belongs to punktfunk-core's shared policy engine
+///     (`client/rumble.rs`), which emits explicit zero commands, so this renderer applies what it
+///     is told and never decides on its own when a level should end.
 ///
 /// Engines are created lazily on the first nonzero amplitude and torn down on retarget;
 /// failures (pads without haptics, engine resets) downgrade to silence — rumble is best-effort
@@ -93,17 +100,6 @@ enum RumbleTuning {
 /// `@unchecked Sendable` is sound because every property is read and written only inside
 /// `queue` closures — the serial queue is the synchronization.
 final class RumbleRenderer: @unchecked Sendable {
-    /// Who ends an un-refreshed nonzero target. Session mode applies the core policy engine's
-    /// commands verbatim — the engine (punktfunk-core `client/rumble.rs`) owns every lease,
-    /// staleness, and close decision and emits explicit zeros, so the renderer keeps NO
-    /// staleness policy of its own anymore. The controller test panel (`manual`) holds a slider
-    /// level indefinitely; both are identical renderer-side today, the distinction is kept for
-    /// the call sites' intent.
-    struct Policy {
-        static let session = Policy()
-        static let manual = Policy()
-    }
-
     /// Which physical actuator this renderer drives: the forwarded controller's haptics engine
     /// (the default), or THIS device's own Taptic Engine (`CHHapticEngine()`) — the opt-in
     /// "rumble on this device" mirror for phone-clip pads that ship without rumble motors.
@@ -115,7 +111,6 @@ final class RumbleRenderer: @unchecked Sendable {
     }
 
     private let queue = DispatchQueue(label: "io.unom.punktfunk.haptics", qos: .userInteractive)
-    private let policy: Policy
     private let actuator: Actuator
 
     /// One finite haptic play on a motor: the player plus when (engine timeline) it expires.
@@ -190,8 +185,7 @@ final class RumbleRenderer: @unchecked Sendable {
         ((0, 0), DispatchTime(uptimeNanoseconds: 0))
     #endif
 
-    init(policy: Policy = .session, actuator: Actuator = .controller) {
-        self.policy = policy
+    init(actuator: Actuator = .controller) {
         self.actuator = actuator
     }
 
@@ -459,6 +453,18 @@ final class RumbleRenderer: @unchecked Sendable {
         if split {
             low = makeMotor(haptics, .leftHandle, sharpness: RumbleTuning.sharpnessLow)
             high = makeMotor(haptics, .rightHandle, sharpness: RumbleTuning.sharpnessHigh)
+            // HALF a split is worse than none, and it used to pass silently: only the all-nil case
+            // below counts as failure, so one surviving handle left `ok` true and `reportHealth(nil)`
+            // announced HEALTHY. What actually rendered was wrong in a direction that depends on
+            // which handle died — lose `high` and `render` falls to the combined branch (selected
+            // purely by `high != nil`), playing max(low, high) on the LEFT handle at the combined
+            // sharpness; lose `low` and the split branch's reconcile no-ops on the nil slot, so the
+            // heavy motor is discarded outright. Tear the survivor down and take the combined path,
+            // which at least renders both motors somewhere.
+            if low == nil || high == nil {
+                log.warning("rumble: only one split-handle engine came up — falling back to combined")
+                teardown() // disarms handlers, stops the survivor's players + engine, nils both
+            }
         } else {
             low = makeMotor(haptics, .default, sharpness: RumbleTuning.sharpnessCombined)
         }
@@ -587,7 +593,9 @@ final class RumbleRenderer: @unchecked Sendable {
         #if os(macOS)
         guard let c, c.extendedGamepad is GCDualSenseGamepad else { return false }
         let hid = DualSenseHID()
-        guard hid.open() else { return false }
+        // Ask for the device this renderer's controller actually is, so two attached DualSenses
+        // do not both get driven through whichever one an unordered Set happened to yield first.
+        guard hid.open(preferringLocationID: Self.hidLocationID(for: c)) else { return false }
         dualSenseHID = hid
         return true
         #else
@@ -595,6 +603,24 @@ final class RumbleRenderer: @unchecked Sendable {
         #endif
     }
 
+    #if os(macOS)
+    /// Correlate a `GCController` with an IOKit location id.
+    ///
+    /// GameController exposes no location id, so there is no direct mapping. What it does expose is
+    /// a stable per-controller ordering, and IOKit's location ids are stable per port: pairing the
+    /// two by rank makes each renderer pick a *distinct* device, which is the property that was
+    /// missing. With one pad attached this is the same device it always was.
+    static func hidLocationID(for c: GCController) -> UInt32? {
+        let ids = DualSenseHID.attachedLocationIDs()
+        guard ids.count > 1 else { return ids.first }
+        let peers = GCController.controllers().filter { $0.extendedGamepad is GCDualSenseGamepad }
+        guard let rank = peers.firstIndex(where: { $0 === c }), rank < ids.count else {
+            return ids.first
+        }
+        return ids[rank]
+    }
+    #endif
+
     /// Write the target to the DualSense over HID if that's the active backend; false → not a
     /// HID pad, so the caller renders via CoreHaptics. Deduped on the pad's 0...255 resolution,
     /// with a periodic keepalive re-write while nonzero (the ticker calls back in here).
@@ -605,8 +631,20 @@ final class RumbleRenderer: @unchecked Sendable {
         let keepalive = levels != (0, 0)
             && seconds(since: lastHidWrite.at) > RumbleTuning.hidKeepaliveSeconds
         if levels != lastHidWrite.levels || keepalive {
-            hid.rumble(low: levels.0, high: levels.1)
-            lastHidWrite = (levels, .now())
+            if hid.rumble(low: levels.0, high: levels.1) {
+                lastHidWrite = (levels, .now())
+            } else {
+                // The write did not reach the device. Do NOT stamp the clock — that would claim a
+                // render that never happened, and for a stop there is nothing behind it: the
+                // keepalive only re-writes non-zero levels and the ticker is cancelled once the
+                // target is (0, 0), so the motors would keep running with nothing scheduled.
+                // Drop the handle instead: the pad reverts to CoreHaptics, and a reconnect
+                // rebuilds it. Health is reported so the state is visible rather than silent.
+                log.error("rumble: HID write failed — dropping the handle, falling back")
+                closeHID()
+                reportHealth("Lost the direct connection to this DualSense; using the system path.")
+                return false
+            }
         }
         return true
         #else

clients/apple/Sources/PunktfunkShared/DefaultsKeys.swift

@@ -38,6 +38,17 @@ public enum DefaultsKey {
     /// host two pads for one pair of hands. Read at connect: `SessionModel` then never starts
     /// `GamepadCapture`, so no slot opens, no arrival is sent and no virtual pad is built.
     public static let gamepadForwarding = "punktfunk.gamepadForwarding"
+    /// Where a controller's SYSTEM buttons (guide + the share/QAM misc) land while streaming:
+    /// `"auto"` | `"forward"` | `"local"` — the cross-client `system_buttons` key. Auto
+    /// forwards on every Apple platform: the local Game Overlay is the OS's business (and on
+    /// iOS 27+ the user can hand the Home button to the app in Settings), so suppressing our
+    /// send would gain nothing.
+    public static let systemButtons = "punktfunk.systemButtons"
+    /// The hold-Select guide gesture: `"auto"` | `"on"` | `"off"` — the cross-client
+    /// `guide_gesture` key. Auto arms it everywhere but macOS: iOS reserves the physical Home
+    /// press for the Game Overlay (uncapturable pre-27) and tvOS never delivers it at all, so
+    /// holding Select is the controller route to the host's guide there.
+    public static let guideGesture = "punktfunk.guideGesture"
     public static let bitrateKbps = "punktfunk.bitrateKbps"
     /// Requested audio channel count: 2 (stereo), 6 (5.1) or 8 (7.1). The host clamps to what it
     /// can capture; the resolved count drives the in-core decode + AVAudioEngine layout.

clients/apple/Sources/PunktfunkShared/EffectiveSettings.swift

@@ -35,6 +35,10 @@ public struct EffectiveSettings: Equatable, Sendable {
     public var invertScroll = false
     public var gamepadType = 0
     public var gamepadForwarding = true
+    /// Cross-client `system_buttons`: "auto" | "forward" | "local".
+    public var systemButtons = "auto"
+    /// Cross-client `guide_gesture`: "auto" | "on" | "off".
+    public var guideGesture = "auto"
     /// A `StatsVerbosity` raw value; the enum lives in PunktfunkKit, which this module can't see.
     public var statsVerbosity = "normal"
     public var fullscreenWhileStreaming = true
@@ -95,6 +99,8 @@ public struct EffectiveSettings: Equatable, Sendable {
         invertScroll = bool(DefaultsKey.invertScroll, invertScroll)
         gamepadType = int(DefaultsKey.gamepadType, gamepadType)
         gamepadForwarding = bool(DefaultsKey.gamepadForwarding, gamepadForwarding)
+        systemButtons = str(DefaultsKey.systemButtons, systemButtons)
+        guideGesture = str(DefaultsKey.guideGesture, guideGesture)
         statsVerbosity = Self.storedStatsVerbosity(defaults)
         fullscreenWhileStreaming = bool(
             DefaultsKey.fullscreenWhileStreaming, fullscreenWhileStreaming)
@@ -121,6 +127,36 @@ public struct EffectiveSettings: Equatable, Sendable {
         return "normal"
     }
 
+    /// The `system_buttons` policy resolved for this platform: forward the raw guide (and
+    /// share/QAM misc) presses? Auto = forward on every Apple platform — where the OS shows
+    /// its own overlay for the press that is the OS's business, and suppressing our send
+    /// would only break users who handed the button to the app (iOS 27's Home-button
+    /// setting; macOS with the gestures claimed).
+    public var systemButtonsForward: Bool {
+        switch systemButtons {
+        case "local": return false
+        default: return true
+        }
+    }
+
+    /// The hold-Select guide gesture resolved for this platform ([`guideGesture`]). Auto =
+    /// on everywhere but macOS: iOS reserves the physical Home press (the Game Overlay,
+    /// uncapturable pre-27) and tvOS never delivers it, so holding Select is the controller
+    /// route to the host's guide — and, held on, to a Gaming-Mode host's QAM. On macOS the
+    /// raw press reaches the host, so auto stays off and Select keeps its exact timing.
+    public var guideGestureEnabled: Bool {
+        switch guideGesture {
+        case "on": return true
+        case "off": return false
+        default:
+            #if os(macOS)
+            return false
+            #else
+            return true
+            #endif
+        }
+    }
+
     /// The one resolution seam: this overlay on top of these settings. Pure — no store reads, no
     /// clock — so it is testable field by field. A `.some` that happens to equal the base is a
     /// legitimate PIN: it keeps its value when the global later moves.
@@ -143,6 +179,8 @@ public struct EffectiveSettings: Equatable, Sendable {
         if let v = overlay.invertScroll { s.invertScroll = v }
         if let v = overlay.gamepadType { s.gamepadType = v }
         if let v = overlay.gamepadForwarding { s.gamepadForwarding = v }
+        if let v = overlay.systemButtons { s.systemButtons = v }
+        if let v = overlay.guideGesture { s.guideGesture = v }
         if let v = overlay.statsVerbosity { s.statsVerbosity = v }
         if let v = overlay.fullscreenWhileStreaming { s.fullscreenWhileStreaming = v }
         if let v = overlay.enable444 { s.enable444 = v }

clients/apple/Sources/PunktfunkShared/StreamProfile.swift

@@ -111,6 +111,8 @@ public struct SettingsOverlay: Codable, Equatable, Sendable {
     public var invertScroll: Bool?
     public var gamepadType: Int?
     public var gamepadForwarding: Bool?
+    public var systemButtons: String?
+    public var guideGesture: String?
     /// A `StatsVerbosity` raw value ("off"/"compact"/"normal"/"detailed") — the enum lives in
     /// PunktfunkKit, which this module must not depend on.
     public var statsVerbosity: String?
@@ -153,6 +155,8 @@ public struct SettingsOverlay: Codable, Equatable, Sendable {
         case invertScroll = "invert_scroll"
         case gamepadType = "gamepad"
         case gamepadForwarding = "gamepad_forwarding"
+        case systemButtons = "system_buttons"
+        case guideGesture = "guide_gesture"
         case statsVerbosity = "stats_verbosity"
         case fullscreenWhileStreaming = "fullscreen_on_stream"
         case enable444 = "enable_444"
@@ -187,6 +191,8 @@ public struct SettingsOverlay: Codable, Equatable, Sendable {
         invertScroll = bool(.invertScroll)
         gamepadType = int(.gamepadType)
         gamepadForwarding = bool(.gamepadForwarding)
+        systemButtons = str(.systemButtons)
+        guideGesture = str(.guideGesture)
         statsVerbosity = str(.statsVerbosity)
         fullscreenWhileStreaming = bool(.fullscreenWhileStreaming)
         enable444 = bool(.enable444)
@@ -224,6 +230,8 @@ public struct SettingsOverlay: Codable, Equatable, Sendable {
         try c.encodeIfPresent(gamepadType, forKey: AnyKey(Key.gamepadType.rawValue))
         try c.encodeIfPresent(
             gamepadForwarding, forKey: AnyKey(Key.gamepadForwarding.rawValue))
+        try c.encodeIfPresent(systemButtons, forKey: AnyKey(Key.systemButtons.rawValue))
+        try c.encodeIfPresent(guideGesture, forKey: AnyKey(Key.guideGesture.rawValue))
         try c.encodeIfPresent(statsVerbosity, forKey: AnyKey(Key.statsVerbosity.rawValue))
         try c.encodeIfPresent(
             fullscreenWhileStreaming, forKey: AnyKey(Key.fullscreenWhileStreaming.rawValue))
@@ -277,6 +285,8 @@ public enum OverlayField {
         case "invert_scroll": overlay.invertScroll = nil
         case "gamepad": overlay.gamepadType = nil
         case "gamepad_forwarding": overlay.gamepadForwarding = nil
+        case "system_buttons": overlay.systemButtons = nil
+        case "guide_gesture": overlay.guideGesture = nil
         case "stats_verbosity": overlay.statsVerbosity = nil
         case "fullscreen_on_stream": overlay.fullscreenWhileStreaming = nil
         case "enable_444": overlay.enable444 = nil
@@ -313,6 +323,8 @@ public enum OverlayField {
         case "invert_scroll": return o.invertScroll != nil
         case "gamepad": return o.gamepadType != nil
         case "gamepad_forwarding": return o.gamepadForwarding != nil
+        case "system_buttons": return o.systemButtons != nil
+        case "guide_gesture": return o.guideGesture != nil
         case "stats_verbosity": return o.statsVerbosity != nil
         case "fullscreen_on_stream": return o.fullscreenWhileStreaming != nil
         case "enable_444": return o.enable444 != nil

clients/apple/Tests/PunktfunkKitTests/DualSenseHIDTests.swift

@@ -43,5 +43,33 @@ final class DualSenseHIDTests: XCTestCase {
         let crc = DualSenseHID.crc32(seed: UInt8(ascii: "1"), Array("23456789".utf8))
         XCTAssertEqual(crc, 0xCBF4_3926)
     }
+
+    // MARK: - Device selection (B14)
+
+    /// With two DualSenses attached, each renderer must drive its OWN device. The old code took
+    /// `Set.first` from an unordered set, so the pad→device binding was a coin flip that could
+    /// point both renderers at the same pad.
+    func testPreferredIndexHonoursAnExplicitLocation() {
+        let ids: [UInt32?] = [0x1D18_0000, 0x1420_0000, 0x1411_0000]
+        XCTAssertEqual(DualSenseHID.preferredIndex(among: ids, preferring: 0x1420_0000), 1)
+        XCTAssertEqual(DualSenseHID.preferredIndex(among: ids, preferring: 0x1D18_0000), 0)
+    }
+
+    /// No preference (or one the pad no longer has): fall back to the LOWEST id — arbitrary, but
+    /// stable across calls, which `Set.first` was not.
+    func testPreferredIndexFallsBackToTheLowestIdDeterministically() {
+        let ids: [UInt32?] = [0x1D18_0000, 0x1420_0000, 0x1411_0000]
+        XCTAssertEqual(DualSenseHID.preferredIndex(among: ids, preferring: nil), 2)
+        // A wanted id that is gone (pad unplugged between enumeration and open) must not fail the
+        // open — it degrades to the same stable fallback.
+        XCTAssertEqual(DualSenseHID.preferredIndex(among: ids, preferring: 0xDEAD_BEEF), 2)
+    }
+
+    /// A device IOKit reports no location for must never displace one it can place.
+    func testPreferredIndexSortsUnplaceableDevicesLast() {
+        XCTAssertEqual(DualSenseHID.preferredIndex(among: [nil, 0x1420_0000], preferring: nil), 1)
+        XCTAssertEqual(DualSenseHID.preferredIndex(among: [nil, nil], preferring: nil), 0)
+        XCTAssertNil(DualSenseHID.preferredIndex(among: [], preferring: nil))
+    }
 }
 #endif

clients/apple/Tests/PunktfunkKitTests/GamepadEscapeChordTests.swift

@@ -0,0 +1,52 @@
+import GameController
+import XCTest
+
+@testable import PunktfunkKit
+
+/// The escape chord's mask and its GameController alias list have to describe the same four
+/// buttons. `GamepadCapture.openSlot` claims the system gesture of every element while forwarding
+/// is on, but only of `escapeChordElements` while it is off — so if the alias list ever stops
+/// covering the mask, the missing button's press stays the system's and the chord never completes.
+///
+/// That matters most on tvOS, where this chord is the only controller way out of a stream: the
+/// symptom is a session nobody can leave with the pad in their hands, and nothing logs or crashes.
+/// Hence a test on the invariant rather than trusting the comment beside it.
+@MainActor
+final class GamepadEscapeChordTests: XCTestCase {
+
+    /// The intended alias↔bit pairing, spelled out independently of the implementation.
+    private let pairing: [(alias: String, bit: UInt32)] = [
+        (GCInputLeftShoulder, GamepadWire.leftShoulder),
+        (GCInputRightShoulder, GamepadWire.rightShoulder),
+        (GCInputButtonMenu, GamepadWire.start),
+        (GCInputButtonOptions, GamepadWire.back),
+    ]
+
+    func testChordMaskIsExactlyTheFourPairedButtons() {
+        XCTAssertEqual(
+            pairing.reduce(UInt32(0)) { $0 | $1.bit },
+            GamepadCapture.escapeChord,
+            "the chord mask and the alias pairing describe different buttons")
+    }
+
+    func testEveryChordBitHasAnElementToClaim() {
+        // One alias per bit — a mask that grew a fifth button without a matching alias would
+        // leave that button's gesture with the OS while forwarding is off.
+        XCTAssertEqual(
+            GamepadCapture.escapeChordElements.count,
+            GamepadCapture.escapeChord.nonzeroBitCount,
+            "alias list and chord mask differ in size")
+        XCTAssertEqual(GamepadCapture.escapeChordElements, pairing.map(\.alias))
+    }
+
+    /// The claim list is a strict subset of what a forwarding slot takes — it is a NARROWING of
+    /// the full sweep, never an extra grab, and it must not be empty (that would be "skip", which
+    /// is the behaviour this deliberately avoids).
+    func testClaimListIsNonEmptyAndAllDistinct() {
+        XCTAssertFalse(GamepadCapture.escapeChordElements.isEmpty)
+        XCTAssertEqual(
+            Set(GamepadCapture.escapeChordElements).count,
+            GamepadCapture.escapeChordElements.count,
+            "a repeated alias would mean a chord bit has no element")
+    }
+}

clients/apple/Tests/PunktfunkKitTests/GamepadWireTests.swift

@@ -79,7 +79,7 @@ final class GamepadWireTests: XCTestCase {
         XCTAssertEqual(GamepadWire.axisRSY, UInt32(PUNKTFUNK_AXIS_RS_Y))
         XCTAssertEqual(GamepadWire.axisLT, UInt32(PUNKTFUNK_AXIS_LT))
         XCTAssertEqual(GamepadWire.axisRT, UInt32(PUNKTFUNK_AXIS_RT))
-        XCTAssertEqual(GamepadWire.maxPads, Int(MAX_PADS))
+        XCTAssertEqual(GamepadWire.maxPads, Int(PUNKTFUNK_MAX_PADS))
     }
 
     func testPadIndexRidesFlagsOnEveryPerPadEvent() {

clients/apple/Tests/PunktfunkKitTests/RumbleTuningTests.swift

@@ -56,7 +56,7 @@ final class RumbleTuningTests: XCTestCase {
     /// storm, an audible target left to the ticker (watchdog path), then `stop()` — which runs
     /// `queue.sync` against the same serial queue the ticker fires on and must not deadlock.
     func testRendererSurvivesCallStormAndTeardownWithoutController() {
-        let renderer = RumbleRenderer(policy: .session)
+        let renderer = RumbleRenderer()
         renderer.retarget(nil)
         for i in 0..<500 {
             renderer.apply(
@@ -72,7 +72,7 @@ final class RumbleTuningTests: XCTestCase {
     /// every policy stop (lease expiry, legacy staleness, session close), and the renderer's only
     /// job is to apply them. Drive the real queue/ticker (no physical pad) and confirm no wedge.
     func testZeroCommandSilencesAndTeardownDoesNotDeadlock() {
-        let renderer = RumbleRenderer(policy: .session)
+        let renderer = RumbleRenderer()
         renderer.retarget(nil)
         renderer.apply(low: 0x8000, high: 0x8000)
         Thread.sleep(forTimeInterval: 0.1)

clients/apple/store/README.md

@@ -0,0 +1,51 @@
+# App Store copy
+
+Source of truth for what goes into App Store Connect. Every character-limited field in here has
+been counted with `check-limits.py`; run it after any edit.
+
+```sh
+python3 clients/apple/store/check-limits.py
+```
+
+| File | Covers |
+|------|--------|
+| [`ios.md`](ios.md) | iOS/iPadOS Promotional Text (DE + EN), with alternates |
+| [`macos.md`](macos.md) | macOS Promotional Text, Description, Keywords (DE + EN) |
+| [`tvos.md`](tvos.md) | tvOS Promotional Text, Description, Keywords (DE + EN) |
+| [`review-notes.md`](review-notes.md) | App Review notes template + pre-submission checklist |
+| [`privacy-app-addendum.md`](privacy-app-addendum.md) | App-specific privacy text to add to the existing policy page |
+
+German is primary throughout and uses the same informal "du" voice as the website
+(`punktfunk-website/messages/de.json`). English is a localisation, not a translation exercise — a
+few lines diverge where the German idiom does not carry.
+
+## Three things that contradicted the original brief
+
+1. **A Mac cannot be a host.** The brief suggested Mac copy could cover "running as a host/server
+   or client on Mac". There is no macOS host — `punktfunk-host` has no macOS capture, virtual
+   display, or encode backend. The macOS copy is client-only and says so explicitly.
+2. **The existing privacy policy is website-only.** It covers server logs, Plausible, and a
+   language cookie, and never mentions the apps. Linking it unchanged from App Store Connect is
+   the kind of thing that draws a reviewer's attention to analytics that have nothing to do with
+   the app. See `privacy-app-addendum.md` for the text to append.
+3. **App Review notes cap at 4000 characters**, not the unlimited field the brief implied. The
+   template is 3919 and fits.
+
+## Claims used, and where they come from
+
+Everything asserted in the copy was checked against the source rather than the marketing site:
+
+- Hardware decode, HDR/4:4:4, controller and input support — `clients/apple/README.md`
+- Entitlements and their justifications — `Config/Punktfunk.entitlements`,
+  `Config/Punktfunk-macOS.entitlements` (both carry detailed rationale comments)
+- Background audio mode and its 2.5.4 constraints — `Config/Info.plist`
+- "Collects no data" — verified by absence: no analytics SDK in `Package.swift`, no telemetry
+  symbols in `Sources/`, `URLSession` used only against the paired host
+- Host platforms and protocol details — root `README.md`, `docs/releases/v0.24.0.md`
+- Feature ship dates — `git tag --contains` on the relevant commits
+
+## Not done here
+
+`clients/apple` has no `PrivacyInfo.xcprivacy`. The app uses `UserDefaults`, which is a
+required-reason API, so a manifest is expected. Flagged at the end of `review-notes.md`; left
+alone because it is a code change, not copy.

clients/apple/store/check-limits.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""Check every App Store copy block in this directory against its field limit.
+
+App Store Connect silently truncates or hard-rejects over-long fields, and the German copy is the
+easy one to get wrong because umlauts read as one character but two bytes. Apple counts characters,
+so `len()` on a `str` is the right measure — do not switch this to a byte count.
+
+Each fenced code block in the .md files here is one field. Which limit applies is inferred from the
+nearest heading above it. Exit status is non-zero if anything is over, so CI can gate on it.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import re
+import sys
+
+LIMITS = {"PROMO": 170, "DESC": 4000, "KW": 100, "NOTES": 4000}
+
+
+def blocks(text: str):
+    """Yield (heading, body) for every fenced block, tagged with the heading above it."""
+    heading = None
+    buf: list[str] | None = None
+    for line in text.split("\n"):
+        if line.startswith("#") and buf is None:
+            heading = line.lstrip("#").strip()
+        if line.strip() == "```":
+            if buf is None:
+                buf = []
+            else:
+                yield heading or "", "\n".join(buf)
+                buf = None
+            continue
+        if buf is not None:
+            buf.append(line)
+
+
+def kind_of(heading: str, body: str) -> str:
+    low = heading.lower()
+    if "keyword" in low or re.fullmatch(r"(de|en) \(\d+\)", low):
+        return "KW"
+    if "template" in low:
+        return "NOTES"
+    return "DESC" if len(body) > 400 else "PROMO"
+
+
+def main() -> int:
+    here = pathlib.Path(__file__).parent
+    failures = 0
+    stale = 0
+    for path in sorted(here.glob("*.md")):
+        found = list(blocks(path.read_text(encoding="utf-8")))
+        if not found:
+            continue
+        print(f"\n=== {path.name} ===")
+        for heading, body in found:
+            kind = kind_of(heading, body)
+            limit = LIMITS[kind]
+            n = len(body)
+            over = n > limit
+            failures += over
+            # Headings carry the count in parentheses; flag any that drifted from the real length.
+            claimed = re.search(r"\((\d+)\)\s*$", heading)
+            drift = ""
+            if claimed and int(claimed.group(1)) != n:
+                drift = f"   [heading claims {claimed.group(1)}]"
+                stale += 1
+            status = "OVER" if over else "ok"
+            print(f"  [{kind:5}] {status:>4} {n:>4}/{limit}  {heading[:48]}{drift}")
+
+    if failures:
+        print(f"\n{failures} block(s) OVER the limit")
+    elif stale:
+        print(f"\nAll within limits, but {stale} heading count(s) are stale")
+    else:
+        print("\nAll blocks within limits, all heading counts accurate")
+    return 1 if failures or stale else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

clients/apple/store/ios.md

@@ -0,0 +1,71 @@
+# iOS / iPadOS — App Store metadata
+
+Existing, unchanged:
+
+- **Name:** Punktfunk
+- **Subtitle (DE):** Schnell, lokal & offen.
+
+Only the Promotional Text is new here. It is the one field that can be changed **without** a new
+build or a review, so it is the right place for "what landed most recently".
+
+---
+
+## Promotional Text (DE) — max 170 characters
+
+### Primary (160)
+
+```
+Neu: Profile pro Host – Auflösung, Bitrate und Ton einmal einstellen, dann mit einem Tipp verbinden. Dazu Live Activity, Sperrbildschirm-Widget und Wake-on-LAN.
+```
+
+### Alternate A — evergreen hook, no "new" claim (156)
+
+```
+Dein Gaming-PC auf dem iPhone, in dessen exakter Auflösung – ohne Konto, ohne Cloud, nur dein Netzwerk. Hardware-Decoding, HDR und dein DualSense mit allem.
+```
+
+### Alternate B — leads on the DualSense (161)
+
+```
+Dein DualSense, vollständig: Rumble, adaptive Trigger, Lightbar, Touchpad und Gyro gehen bis ins Spiel durch. Dazu Profile pro Host und Wake-on-LAN vom Sofa aus.
+```
+
+### Alternate C — leads on latency (153)
+
+```
+Kein Konto, keine Cloud, kein Umweg: punktfunk/1 fährt über QUIC direkt zu deinem PC. Auflösungswechsel mitten im Stream, ohne die Verbindung zu trennen.
+```
+
+---
+
+## Promotional Text (EN) — max 170 characters
+
+### Primary (152)
+
+```
+New: per-host profiles — set resolution, bitrate and audio once, then connect with one tap. Plus Live Activities, a Lock Screen widget, and Wake-on-LAN.
+```
+
+### Alternate A — evergreen hook (159)
+
+```
+Your gaming PC on your iPhone, at your iPhone's exact resolution — no account, no cloud, just your network. Hardware decoding, HDR, and your DualSense in full.
+```
+
+### Alternate B — leads on the DualSense (160)
+
+```
+Your DualSense, in full: rumble, adaptive triggers, lightbar, touchpad and gyro all reach the game. Plus per-host profiles and Wake-on-LAN from across the room.
+```
+
+---
+
+## Notes on the claims
+
+- "Profile pro Host" shipped in **v0.22.0** (`25b12780`, `80c0ca69`) and is in every tag since. It is
+  the strongest recent user-facing Apple feature, so "Neu" is defensible for one release cycle — but
+  drop the word once 0.25 ships something newer.
+- Live Activities and the Hosts widget shipped long ago (`ba1caf02`, in v0.15.0+). They are safe to
+  *mention* but should not be called "neu".
+- The only Apple-visible feature unique to **v0.24.0** is the "Forward controllers" off switch
+  (`b297542c`), which is too niche to headline.

clients/apple/store/macos.md

@@ -0,0 +1,159 @@
+# macOS — App Store metadata
+
+> **Scope correction.** The Mac app is a **client only**. There is no macOS host: `punktfunk-host`
+> has no macOS capture, virtual-display, or encode backend (the two `cfg!(target_os = "macos")` hits
+> in the host crate are OS *detection* for the host tile and a path helper; the loopback-test host
+> is a synthetic frame source for `test-loopback.sh`, not a shippable host). A macOS host is a
+> feasibility study — it needs four new backends and the private `CGVirtualDisplay` API.
+> None of the copy below claims a Mac can host, and it should not until that ships.
+
+- **Name:** Punktfunk
+- **Subtitle (DE):** Schnell, lokal & offen.
+- **Subtitle (EN):** Fast, local & open.
+
+---
+
+## Promotional Text (DE) — max 170 characters
+
+### Primary (164)
+
+```
+Neu: Profile pro Host – ein Mac, mehrere Gaming-PCs, jeder mit eigenen Einstellungen. Dazu AV1-Hardware-Decoding auf M3 und neuer, HDR und volles 4:4:4 für Schrift.
+```
+
+### Alternate (156)
+
+```
+Dein Gaming-PC im Fenster oder im Vollbild, in der exakten Auflösung deines Displays. Maus und Tastatur gehen durch, Auflösungswechsel ohne neue Verbindung.
+```
+
+## Promotional Text (EN) — max 170 characters
+
+### Primary (161)
+
+```
+New: per-host profiles — one Mac, several gaming PCs, each with its own settings. Plus AV1 hardware decoding on M3 and later, HDR, and full 4:4:4 for crisp text.
+```
+
+### Alternate (156)
+
+```
+Your gaming PC in a window or full screen, at your display's exact resolution. Mouse and keyboard pass straight through; resize without dropping the stream.
+```
+
+---
+
+## Description (DE) — max 4000 characters
+
+```
+Punktfunk streamt deinen Gaming-PC auf den Mac – in der exakten Auflösung und Bildwiederholrate deines Displays, über dein eigenes Netzwerk, ohne Konto und ohne Cloud.
+
+Punktfunk besteht aus zwei Hälften: einem Host auf dem PC, von dem du streamst, und dieser App auf dem Gerät, auf dem du spielst. Der Host ist quelloffen und kostenlos, läuft auf Linux und auf Windows 11 – auf dem Gaming-Rig unterm Schreibtisch, auf einem Laptop oder headless auf einem Server, an dem gar kein Monitor hängt.
+
+DEIN MAC BEKOMMT SEIN EIGENES DISPLAY
+
+Für jede Verbindung legt der Host ein echtes virtuelles Display an – in genau der Auflösung und Bildrate, die dein Mac meldet. Kein Skalieren, keine schwarzen Balken, kein Umsortieren deiner echten Monitore. Änderst du mitten im Stream die Fenstergröße oder gehst auf Vollbild, wird die Auflösung neu ausgehandelt, ohne die Verbindung zu trennen. Mehrere Geräte können gleichzeitig streamen, jedes auf seinem eigenen Display.
+
+SCHNELL, WEIL UNS DER GANZE WEG GEHÖRT
+
+Die nativen Apps sprechen punktfunk/1: eine QUIC-Steuerebene und eine verschlüsselte Datenebene mit Vorwärtsfehlerkorrektur, die Auflösung und Bildrate mitten im Stream wechselt, ohne neu zu verbinden. Dekodiert wird in Hardware über VideoToolbox – H.264, HEVC und AV1 auf Macs, die AV1 in Hardware können (M3 und neuer).
+
+FÜR DEN MAC GEMACHT
+
+• Im Fenster oder im Vollbild, auf jedem angeschlossenen Display
+• Maus und Tastatur gehen vollständig durch – Klick zum Fangen, Cmd+Esc oder Ctrl+Alt+Shift+Q zum Freigeben
+• Ein Stream-Menü in der Menüleiste: Maus freigeben, Trennen, Statistik einblenden
+• Mikrofon-Uplink mit Echounterdrückung – dein Mac wird zum Headset am PC
+• HDR mit PQ-Passthrough und ein optionaler Vollchroma-Modus (4:4:4), damit kleine Schrift und feine Linien scharf bleiben
+
+CONTROLLER, VOLLSTÄNDIG
+
+DualSense, Xbox- und weitere MFi-kompatible Controller. Beim DualSense gehen Rumble, Lightbar, Player-LEDs, adaptive Trigger, Touchpad und Gyro bis ins Spiel durch. Welchen Typ das virtuelle Gamepad am Host annimmt, richtet sich nach dem, was bei dir wirklich in der Hand liegt.
+
+DEINE BIBLIOTHEK, DEIN NETZWERK
+
+Installierte Steam-Titel und selbst hinzugefügte Spiele erscheinen als Raster mit Artwork und starten direkt. Hosts findet die App im Netzwerk von allein. Beim ersten Mal koppelst du einmalig mit einer PIN, danach verbindet sich der Mac über eine gepinnte Identität aus deinem Schlüsselbund – kein Konto, kein Login. Einen schlafenden PC weckt Punktfunk per Wake-on-LAN.
+
+MESSEN STATT GLAUBEN
+
+Ein gestuftes Overlay zeigt Bildrate, Bitrate und Latenz – über zwei Maschinen hinweg um den Uhrenversatz korrigiert, also eine Messung und kein Versprechen. Ein Geschwindigkeitstest pro Host schlägt eine passende Bitrate vor. Profile halten pro Host fest, wie gestreamt werden soll.
+
+WAS DU BRAUCHST
+
+Einen Punktfunk-Host auf einem Linux-PC oder auf Windows 11 (22H2 oder neuer) im selben Netzwerk. Der Host ist quelloffen (MIT/Apache-2.0) und kostenlos – Anleitungen und Quellcode findest du auf punktfunk.unom.io. Diese App ist der Client: ein Mac kann derzeit nicht selbst Host sein.
+
+Kein Konto. Keine Cloud. Keine Telemetrie. Die App erfasst keine Daten über dich.
+```
+
+---
+
+## Description (EN) — max 4000 characters
+
+```
+Punktfunk streams your gaming PC to your Mac — at your display's exact resolution and refresh rate, over your own network, with no account and no cloud.
+
+Punktfunk comes in two halves: a host on the PC you stream from, and this app on the device you play on. The host is open source and free, and runs on Linux and on Windows 11 — on the gaming rig under your desk, on a laptop, or headless on a server with no monitor attached at all.
+
+YOUR MAC GETS A DISPLAY OF ITS OWN
+
+For every connection, the host creates a real virtual display at exactly the resolution and refresh rate your Mac reports. No scaling, no black bars, no rearranging your actual monitors. Resize the window mid-stream or go full screen and the resolution is renegotiated without dropping the connection. Several devices can stream at once, each on its own display.
+
+FAST, BECAUSE WE OWN THE WHOLE PATH
+
+The native apps speak punktfunk/1: a QUIC control plane and an encrypted data plane with forward error correction, able to change resolution and frame rate mid-stream without reconnecting. Decoding is done in hardware through VideoToolbox — H.264, HEVC, and AV1 on Macs with an AV1 hardware decoder (M3 and later).
+
+BUILT FOR THE MAC
+
+• In a window or full screen, on any attached display
+• Mouse and keyboard pass straight through — click to capture, Cmd+Esc or Ctrl+Alt+Shift+Q to release
+• A Stream menu in the menu bar: release the mouse, disconnect, toggle the stats overlay
+• Microphone uplink with echo cancellation — your Mac becomes the headset on your PC
+• HDR with PQ passthrough, plus an optional full-chroma (4:4:4) mode that keeps small text and fine UI lines sharp
+
+CONTROLLERS, IN FULL
+
+DualSense, Xbox, and other MFi-compatible controllers. On a DualSense, rumble, lightbar, player LEDs, adaptive triggers, touchpad, and gyro all reach the game. The virtual gamepad the host presents takes its type from the controller actually in your hands.
+
+YOUR LIBRARY, YOUR NETWORK
+
+Installed Steam titles and games you add yourself appear as a grid with artwork, ready to launch. The app finds hosts on your network by itself. The first time, you pair once with a PIN; after that your Mac reconnects on a pinned identity stored in your keychain — no account, no login. Punktfunk can wake a sleeping PC over Wake-on-LAN.
+
+MEASURED, NOT PROMISED
+
+A tiered overlay shows frame rate, bitrate, and latency — corrected for clock skew across the two machines, so it is a measurement rather than a claim. A per-host speed test suggests a bitrate that matches your link. Profiles remember how each host should be streamed.
+
+WHAT YOU NEED
+
+A Punktfunk host on a Linux PC or on Windows 11 (22H2 or later) on the same network. The host is open source (MIT/Apache-2.0) and free — guides and source at punktfunk.unom.io. This app is the client: a Mac cannot currently act as a host.
+
+No account. No cloud. No telemetry. This app collects no data about you.
+```
+
+---
+
+## Keywords — max 100 characters
+
+Comma-separated, **no spaces after the commas** (spaces count against the limit). The app name and
+the subtitle are already indexed, so `punktfunk`, `schnell`, `lokal`, and `offen` are deliberately
+absent — repeating them would waste characters.
+
+### DE (97)
+
+```
+streaming,spiele,remote,desktop,fernzugriff,pc,linux,windows,controller,gamepad,latenz,quelloffen
+```
+
+### EN (95)
+
+```
+streaming,remote,desktop,pc,linux,windows,gaming,controller,gamepad,latency,selfhosted,lan,play
+```
+
+**Deliberately excluded:** `Moonlight`, `GameStream`, `NVIDIA`, `Steam`. Punktfunk genuinely is
+GameStream-compatible and does read your Steam library, but App Store Review Guideline 4.1 and the
+metadata rules disallow third-party app, product, and company names in the **keyword** field — it is
+a routine rejection. Saying it in the description is fine; the current descriptions avoid naming
+Moonlight and mention Steam only as a factual statement about your own library.
+
+The previous keyword set (`Game-Streaming, Lokal, Open-Source, Gaming`) spent characters on spaces,
+on `Lokal` (already in the subtitle), and on both `Game-Streaming` and `Gaming`, which share a stem.

clients/apple/store/privacy-app-addendum.md

@@ -0,0 +1,146 @@
+# Privacy — what to link from App Store Connect
+
+## The situation
+
+You already have a privacy policy at **punktfunk.unom.io/legal/privacy**. It is good, current
+(Stand: 28. Juni 2026), and localised DE/EN. But it is a **website** privacy policy: it covers
+server log files, Plausible Analytics on `analytics.unom.io`, the `PARAGLIDE_LOCALE` cookie, and
+self-hosted fonts. It does not mention the apps at all.
+
+That is a problem for App Store Connect in two directions:
+
+1. Apple requires the linked policy to describe **the app's** data practices. A reviewer following
+   the link finds a page about a website.
+2. It reads as *contradicting* a "Data Not Collected" declaration. The page prominently describes
+   analytics and a cookie. A reviewer who skims it sees "Reichweitenmessung mit Plausible
+   Analytics" and has every reason to question the App Privacy answers.
+
+**Recommendation:** keep the existing page and append an app-specific section to it (the text
+below), so one URL covers both. The alternative — a separate `/legal/privacy-apps` route — also
+works, but one URL is less to keep in sync.
+
+The page is CMS-driven (`src/routes/legal/privacy.tsx` renders Payload `RichText` blocks from the
+`pages` collection, slug `legal/privacy`, tenant `punktfunk`), so this is a CMS edit rather than a
+code change.
+
+## Confirming the "collects no data" framing
+
+Checked against the source rather than taken on trust, and it holds:
+
+- **No analytics, telemetry, or crash-reporting SDK.** `Package.swift` declares no such dependency.
+  A case-insensitive sweep of `Sources/` for `sentry|firebase|analytics|telemetry|amplitude|
+  mixpanel|crashlytics|posthog|plausible` returns 43 hits — 43 of them the word "amplitude" in
+  haptics code (rumble amplitude), and one the English word "plausible" in a comment.
+- **No outbound calls to us.** The only `URLSession` use is `LibraryClient`, fetching cover art
+  **from the paired host**, over a TLS session that pins the host's own certificate. The only
+  external URLs anywhere in the Swift sources are three UI links the user can tap: the docs site,
+  the source on `git.unom.io`, and the Discord invite.
+- **No account system.** Identity is a client keypair in the device keychain
+  (`keychain-access-groups`, `ClientIdentityStore`); pairing is SPAKE2 with a PIN, host-to-device.
+- **Data stays on device.** Saved hosts and settings live in a shared `UserDefaults` suite
+  (`group.io.unom.punktfunk`) so the widget can read them. Nothing syncs; there is no CloudKit
+  entitlement.
+- **No ATT.** No `NSUserTrackingUsageDescription` anywhere, consistent with no tracking.
+
+So **App Privacy → "Data Not Collected"** is accurate for all four platforms. Two caveats worth
+stating in the policy text anyway, because they are true and pre-empt questions:
+
+- The microphone uplink **is** audio leaving the device — but only to the host the user paired with,
+  encrypted, and never to us. Apple's questionnaire asks about data collected *by you or your
+  third-party partners*; streaming to the user's own machine is not collection. Saying so plainly
+  is better than staying silent about a microphone permission.
+- The apps are distributed through the App Store, so **Apple** collects its own analytics. That is
+  Apple's processing, not yours, but naming it avoids looking like an omission.
+
+---
+
+## Text to append — Deutsch
+
+> ## Die Punktfunk-Apps
+>
+> Dieser Abschnitt betrifft die Punktfunk-Apps für iPhone, iPad, Apple TV, Mac, Windows, Linux und
+> Android – im Unterschied zu den vorstehenden Abschnitten, die sich auf diese Website beziehen.
+>
+> **Die Apps erheben keine personenbezogenen Daten.** Es gibt keine Benutzerkonten, keine
+> Registrierung und keine Anmeldung. Die Apps enthalten keine Analyse-, Tracking-, Werbe- oder
+> Absturzbericht-Bibliotheken von Drittanbietern. Es findet kein Tracking im Sinne des App
+> Tracking Transparency Frameworks statt, und es werden keine Daten an uns oder an Dritte
+> übermittelt.
+>
+> **Wohin die Daten fließen.** Punktfunk verbindet Ihr Gerät direkt mit einem Host-Rechner, den Sie
+> selbst betreiben – in der Regel in Ihrem eigenen Netzwerk. Video, Ton, Maus-, Tastatur- und
+> Controller-Eingaben sowie – sofern Sie ihn einschalten – Ihr Mikrofon werden ausschließlich
+> zwischen Ihrem Gerät und diesem Host übertragen, verschlüsselt und ohne Umweg über einen Server
+> von uns. Wir betreiben für den Streaming-Betrieb keine Vermittlungs-, Relay- oder Cloud-Dienste
+> und haben zu keinem Zeitpunkt Zugriff auf die Inhalte einer Sitzung.
+>
+> **Was auf dem Gerät bleibt.** Die App speichert lokal auf Ihrem Gerät: die von Ihnen
+> hinzugefügten oder im Netzwerk gefundenen Hosts, Ihre Einstellungen und Profile sowie einen
+> kryptografischen Schlüssel, mit dem sich Ihr Gerät gegenüber einem gekoppelten Host ausweist
+> (auf Apple-Geräten im Schlüsselbund). Diese Daten verlassen Ihr Gerät nicht und werden gelöscht,
+> wenn Sie die App entfernen.
+>
+> **Berechtigungen.** Die App fragt nur Berechtigungen ab, die für den Betrieb nötig sind: den
+> Zugriff auf das lokale Netzwerk, um Hosts zu finden und sich mit ihnen zu verbinden, und – nur
+> wenn Sie die Mikrofonübertragung nutzen – das Mikrofon. Das Mikrofonsignal wird an den von Ihnen
+> gekoppelten Host übertragen, wo es als virtuelles Mikrofon erscheint; es wird nicht
+> aufgezeichnet und nicht an uns gesendet.
+>
+> **Verteilung über App-Stores.** Wenn Sie die App über den App Store oder Google Play beziehen,
+> verarbeiten Apple bzw. Google im Rahmen der Auslieferung eigene Daten (etwa Kauf-, Installations-
+> und Absturzstatistiken). Darauf haben wir keinen Einfluss; es gelten die
+> Datenschutzbestimmungen des jeweiligen Anbieters. Aggregierte Statistiken, die uns Apple oder
+> Google in ihren Entwicklerkonsolen anzeigen, lassen keinen Rückschluss auf einzelne Personen zu.
+>
+> **Der Host.** Der Punktfunk-Host ist quelloffene Software, die Sie selbst auf Ihrem eigenen
+> Rechner betreiben. Welche Daten dabei anfallen – etwa lokale Protokolldateien –, bleibt
+> vollständig unter Ihrer Kontrolle; wir erhalten davon nichts. Der Quellcode ist unter
+> git.unom.io/unom/punktfunk einsehbar.
+
+---
+
+## Text to append — English
+
+> ## The Punktfunk apps
+>
+> This section concerns the Punktfunk apps for iPhone, iPad, Apple TV, Mac, Windows, Linux, and
+> Android — as distinct from the sections above, which concern this website.
+>
+> **The apps collect no personal data.** There are no user accounts, no registration, and no sign-in.
+> The apps contain no third-party analytics, tracking, advertising, or crash-reporting libraries.
+> No tracking within the meaning of Apple's App Tracking Transparency framework takes place, and no
+> data is transmitted to us or to any third party.
+>
+> **Where your data goes.** Punktfunk connects your device directly to a host machine that you run
+> yourself, normally on your own network. Video, audio, mouse, keyboard, and controller input — and
+> your microphone, if you switch it on — travel only between your device and that host, encrypted,
+> without passing through any server of ours. We operate no brokering, relay, or cloud service for
+> streaming, and we have no access to the contents of a session at any point.
+>
+> **What stays on your device.** The app stores locally on your device: the hosts you have added or
+> discovered on your network, your settings and profiles, and a cryptographic key your device uses
+> to identify itself to a paired host (in the keychain, on Apple devices). This data does not leave
+> your device and is removed when you delete the app.
+>
+> **Permissions.** The app requests only the permissions it needs to work: access to the local
+> network, in order to find hosts and connect to them, and — only if you use microphone streaming —
+> the microphone. The microphone signal is sent to the host you paired with, where it appears as a
+> virtual microphone; it is not recorded and is not sent to us.
+>
+> **Distribution through app stores.** If you obtain the app from the App Store or Google Play,
+> Apple or Google process their own data as part of distributing it (such as purchase, installation,
+> and crash statistics). We have no influence over this, and the respective provider's privacy
+> policy applies. The aggregated statistics Apple and Google show us in their developer consoles do
+> not allow any individual to be identified.
+>
+> **The host.** The Punktfunk host is open source software that you run on your own machine. Any
+> data it produces — local log files, for instance — remains entirely under your control, and none
+> of it reaches us. The source is available at git.unom.io/unom/punktfunk.
+
+---
+
+## Also update
+
+- Bump **Stand: / Effective date:** on the page when you add this.
+- App Store Connect → App Privacy → **Data Not Collected** for all four platforms.
+- The same URL works for Google Play's Data safety declaration; the wording above already covers it.

clients/apple/store/review-notes.md

@@ -0,0 +1,132 @@
+# App Review notes
+
+## The core problem, stated plainly
+
+Punktfunk is the client half of a two-part system. Without a reachable host it shows a host list, a
+pairing sheet, and settings — and nothing else. There is **no demo or offline mode in a release
+build**: the mock-data screens in `Sources/PunktfunkClient/Screenshots/` are wrapped in `#if DEBUG`
+and are compiled out of anything you ship. A reviewer who launches the App Store build with no host
+on their network sees an empty "On this network" list.
+
+Guideline 2.1 requires you to supply whatever is needed to fully exercise the app. So you must
+attach **one** of:
+
+- **(a) A reachable demo host.** Best outcome — the reviewer sees the real thing. Requires a host
+  exposed to the internet with its UDP ports forwarded, plus a pairing PIN in the notes. The client
+  can add a host by IP or hostname, so mDNS discovery is not required for this path.
+- **(b) A demo video.** Apple accepts this for hardware- or setup-dependent apps. Less good: a
+  reviewer who cannot reproduce is a reviewer who can reject on something unrelated.
+
+**Attach (a) if you can keep a host up for the review window; (b) is the fallback.** Whichever you
+pick, fill in the placeholders before submitting — the template assumes (a) and marks the spots.
+
+> **⚠ Decide before submitting:** if you go with (b), replace the "CONNECTING TO OUR DEMO HOST"
+> section with the video URL and say explicitly that no host can be provided.
+
+---
+
+## Notes template — paste into App Store Connect
+
+The App Review Information "Notes" field caps at **4000 characters**. The block below is **3919**,
+and filling the five placeholders in shortens it further (the literal `[[FILL IN: …]]` text is
+longer than the values that replace it). If you add to it, re-check the count — an over-long note
+is silently truncated, and what gets cut is the end, where the privacy and entitlement answers
+live.
+
+```
+WHAT THIS APP IS
+
+Punktfunk is a low-latency game- and desktop-streaming client. It streams from a "host" the user
+installs on their own gaming PC (Linux, or Windows 11 22H2+), over their own network. The host is
+separate open-source software we publish at https://git.unom.io/unom/punktfunk; it is not sold,
+and this app has no purchases.
+
+This app is the client half only: it renders video and audio from the user's own machine and
+sends input back. There is no content library and no server of ours in a session.
+
+IMPORTANT: THIS APP NEEDS A HOST
+
+With no reachable host, the app can only show its host list, the pairing screen and settings --
+inherent to what it is, not an incomplete build. We have provided a live host for review.
+
+CONNECTING TO OUR DEMO HOST
+
+1. Launch Punktfunk. The main screen lists hosts on the local network. Ours is not on yours, so
+   add it by hand: "+" (top right) then "Add host"; on Apple TV, "Add host" on the main screen.
+2. Enter:  Host: [[FILL IN: hostname or IP]]   Port: [[FILL IN: port, default 47998]]
+   Name it anything, then confirm.
+3. The app connects and asks for a pairing PIN. Enter:  [[FILL IN: PIN]]
+   A one-time SPAKE2 pairing; afterwards the device is remembered and needs no PIN.
+4. The host's game library appears as a grid. Select any title to stream; video and audio start
+   within a few seconds.
+5. While streaming: stats overlay = Ctrl+Alt+Shift+S (or three-finger tap on iOS/iPadOS); release
+   mouse = Cmd+Esc or Ctrl+Alt+Shift+Q; disconnect = Ctrl+Alt+Shift+D.
+6. Settings (gear) covers decoder, bitrate, HDR, audio, controllers and profiles; the per-host
+   "Speed test" suggests a bitrate for the link.
+
+The host stays reachable throughout review. If you cannot reach it, please contact
+[[FILL IN: contact email]] and we will restore it promptly.
+
+WHY THE APP ASKS FOR WHAT IT ASKS FOR
+
+- Local Network: finds hosts via Bonjour (_punktfunk._udp) and connects to them -- the app's
+  entire purpose.
+- Microphone (optional, off by default): audio goes to the user's own paired host, appearing
+  there as a virtual microphone for voice chat. Never recorded, never sent to us.
+- networking.multicast: sends the Wake-on-LAN magic packet, which must go to a broadcast address:
+  a sleeping PC has no ARP entry, so unicast cannot reach it. Used for nothing else.
+- device.usb / device.bluetooth (macOS): the GameController framework reaches wired controllers
+  through IOHIDLibUserClient and wireless ones through startWirelessControllerDiscovery. USB also
+  drives DualSense rumble, which CoreHaptics will not. Without these, no controller input.
+- network.server (macOS): the app is outbound-only, but the App Sandbox gates bind() itself. Our
+  QUIC endpoint and UDP socket each bind a local port to receive host-to-client datagrams;
+  without this, no video, audio or rumble arrives.
+- UIBackgroundModes "audio" (iPhone/iPad): a session carries real, audible audio from the host,
+  and this keeps it alive if the user steps away briefly. Backgrounded, video decoding stops, only
+  the real audio keeps rendering, and a bounded timer disconnects automatically. We never play
+  silence to stay alive, nor use the mode outside an audible session.
+
+REGARDING BUILD 0.4.2 (3384)
+
+That build was rejected under 2.4.5(i) for a temporary-exception entitlement
+(mach-lookup.global-name, com.apple.audioanalyticsd), added on a mistaken belief about CoreHaptics
+rumble under the App Sandbox. We have since verified rumble works without it; this build carries
+no temporary exception.
+
+ACCOUNTS, PURCHASES, DATA
+
+No account, no sign-in, no in-app purchase. The app collects no personal data: no analytics,
+tracking, advertising or crash-reporting SDKs, and no connection to any server of ours during a
+session. Device identity is a keychain keypair used only to authenticate to the user's own host.
+
+Privacy policy: [[FILL IN: https://punktfunk.unom.io/legal/privacy]]
+```
+
+---
+
+## Before you submit — checklist
+
+- [ ] Fill every `[[FILL IN: …]]` placeholder. There are five.
+- [ ] Confirm the demo host is reachable **from outside your own network** — test it on cellular,
+      not on the LAN it lives on. This is the failure mode that wastes a review cycle.
+- [ ] Confirm the pairing PIN in the notes is the one the host will actually accept during the
+      review window, and that pairing is left open (it is on-demand in the web console).
+- [ ] Put at least one launchable title in the demo host's library. An empty grid after a
+      successful pairing looks like a broken app.
+- [ ] If submitting tvOS, verify the whole flow is reachable with the **Siri Remote alone**. A
+      reviewer will not have a controller paired, and "requires an accessory to navigate" is a
+      tvOS rejection.
+- [ ] Attach the demo video as a URL in the notes if you are going the (b) route.
+
+## Separately worth checking: the privacy manifest
+
+There is **no `PrivacyInfo.xcprivacy`** anywhere in `clients/apple`. The app does use
+`UserDefaults` (`HostStore` reads the `group.io.unom.punktfunk` suite), and `UserDefaults` is one of
+Apple's "required reason" APIs, which are expected to be declared in a privacy manifest. Apps
+missing a declaration typically get an automated **ITMS-91053** notice on upload.
+
+This is adjacent to the copy work rather than part of it, so nothing has been changed here — but it
+is worth adding a manifest declaring `NSPrivacyAccessedAPICategoryUserDefaults` with reason code
+`CA92.1` (access to an app group container) and `NSPrivacyTracking` set to `false`, before the next
+submission. Confirm the current reason codes against Apple's documentation rather than taking the
+code above on trust; the list has changed since it was introduced.

clients/apple/store/tvos.md

@@ -0,0 +1,145 @@
+# tvOS — App Store metadata
+
+Client only, living-room framing. Things the other platforms have that the **Apple TV does not**,
+and which the copy therefore avoids claiming:
+
+- **No microphone uplink.** There is no usable audio input on tvOS, so the "your Mac becomes the
+  headset" line does not transfer.
+- **No gamepad console shell.** `ShotScenes` builds the gamepad home/settings screens for iOS and
+  macOS only — tvOS uses the native focus engine instead.
+- **No AV1.** Apple TV 4K has no AV1 hardware decoder; HEVC and H.264 only.
+- Mouse/keyboard capture exists on tvOS but is not a living-room story, so it stays out.
+
+Kept, and genuinely tvOS-shaped: Siri Remote pointer navigation (`SiriRemotePointer`), controllers
+including the full DualSense feedback set, HDR passthrough, and Wake-on-LAN — which is the single
+best Apple TV feature, because it is what removes the trip to the other room.
+
+- **Name:** Punktfunk
+- **Subtitle (DE):** Schnell, lokal & offen.
+- **Subtitle (EN):** Fast, local & open.
+
+---
+
+## Promotional Text (DE) — max 170 characters
+
+### Primary (161)
+
+```
+Anschalten, Host wählen, spielen: Punktfunk weckt deinen Gaming-PC per Wake-on-LAN und verbindet sich, sobald er wach ist. In 4K, mit HDR, mit deinem Controller.
+```
+
+### Alternate A — leads on the picture (157)
+
+```
+Dein Gaming-PC am großen Bildschirm – in genau der Auflösung und Bildrate deines Fernsehers, mit HDR. Ohne Konto, ohne Cloud, nur über dein eigenes Netzwerk.
+```
+
+### Alternate B — leads on the DualSense (160)
+
+```
+Dein DualSense am Apple TV, vollständig: Rumble, adaptive Trigger, Lightbar, Touchpad und Gyro gehen bis ins Spiel durch. Dazu Profile pro Host und Wake-on-LAN.
+```
+
+## Promotional Text (EN) — max 170 characters
+
+### Primary (160)
+
+```
+Turn on, pick a host, play: Punktfunk wakes your gaming PC over Wake-on-LAN and connects as soon as it's up. In 4K, with HDR, with the controller in your hands.
+```
+
+### Alternate A — leads on the picture (148)
+
+```
+Your gaming PC on the big screen — at your TV's exact resolution and refresh rate, with HDR. No account, no cloud, nothing leaving your own network.
+```
+
+---
+
+## Description (DE) — max 4000 characters
+
+```
+Punktfunk macht aus deinem Apple TV die Konsole für den Gaming-PC, der ohnehin schon im Haus steht – in 4K, mit HDR, über dein eigenes Netzwerk, ohne Konto und ohne Cloud.
+
+Punktfunk besteht aus zwei Hälften: einem Host auf dem PC, von dem du streamst, und dieser App auf dem Gerät, auf dem du spielst. Der Host ist quelloffen und kostenlos, läuft auf Linux und auf Windows 11 – auch headless auf einem Rechner, an dem gar kein Monitor hängt.
+
+VOM SOFA AUS, VON ANFANG BIS ENDE
+
+Anschalten, Host auswählen, spielen. Die App findet Hosts im Netzwerk von allein. Beim ersten Mal koppelst du einmalig mit einer PIN, danach verbindet sich der Apple TV über eine gepinnte Identität – kein Konto, kein Login, kein Abtippen von IP-Adressen. Steht dein Gaming-PC im Standby, weckt ihn Punktfunk per Wake-on-LAN und verbindet sich, sobald er wach ist. Niemand muss dafür aufstehen.
+
+DAS BILD, DAS DEIN FERNSEHER WIRKLICH KANN
+
+Für den Apple TV legt der Host ein echtes virtuelles Display an – in genau der Auflösung und Bildrate, die dein Fernseher meldet, bis 4K. Kein Skalieren, keine schwarzen Balken, und die Monitore am PC werden nicht umsortiert. Dekodiert wird in Hardware über VideoToolbox (HEVC und H.264), HDR wird als PQ durchgereicht, statt es flach zu rechnen.
+
+CONTROLLER, VOLLSTÄNDIG
+
+DualSense, Xbox- und weitere MFi-kompatible Controller. Beim DualSense gehen Rumble, Lightbar, Player-LEDs, adaptive Trigger, Touchpad und Gyro bis ins Spiel durch. Welchen Typ das virtuelle Gamepad am Host annimmt, richtet sich nach dem, was bei dir wirklich in der Hand liegt. Bedienen lässt sich alles mit der Siri Remote oder komplett mit dem Controller – die Oberfläche ist für die Fernbedienung gebaut, nicht für eine Maus.
+
+DEINE BIBLIOTHEK AUF DEM FERNSEHER
+
+Installierte Steam-Titel und selbst hinzugefügte Spiele erscheinen als Raster mit Artwork und starten direkt vom Sofa aus. Mehrere Geräte können gleichzeitig streamen, jedes auf seinem eigenen Display – der Apple TV im Wohnzimmer stört also niemanden, der am Schreibtisch weiterarbeitet.
+
+SCHNELL, WEIL UNS DER GANZE WEG GEHÖRT
+
+Die nativen Apps sprechen punktfunk/1: eine QUIC-Steuerebene und eine verschlüsselte Datenebene mit Vorwärtsfehlerkorrektur. Ein gestuftes Overlay zeigt Bildrate, Bitrate und Latenz – über zwei Maschinen hinweg um den Uhrenversatz korrigiert, also eine Messung und kein Versprechen. Ein Geschwindigkeitstest pro Host schlägt eine passende Bitrate für dein Netzwerk vor.
+
+WAS DU BRAUCHST
+
+Einen Punktfunk-Host auf einem Linux-PC oder auf Windows 11 (22H2 oder neuer) im selben Netzwerk. Für die beste Erfahrung hängt der Apple TV am Kabel oder an einem guten 5-GHz-WLAN. Der Host ist quelloffen (MIT/Apache-2.0) und kostenlos – Anleitungen und Quellcode findest du auf punktfunk.unom.io.
+
+Kein Konto. Keine Cloud. Keine Telemetrie. Die App erfasst keine Daten über dich.
+```
+
+---
+
+## Description (EN) — max 4000 characters
+
+```
+Punktfunk turns your Apple TV into a console for the gaming PC you already own — in 4K, with HDR, over your own network, with no account and no cloud.
+
+Punktfunk comes in two halves: a host on the PC you stream from, and this app on the device you play on. The host is open source and free, and runs on Linux and on Windows 11 — including headless, on a machine with no monitor attached at all.
+
+FROM THE COUCH, START TO FINISH
+
+Turn on, pick a host, play. The app finds hosts on your network by itself. The first time, you pair once with a PIN; after that your Apple TV reconnects on a pinned identity — no account, no login, no typing IP addresses with a remote. If your gaming PC is asleep, Punktfunk wakes it over Wake-on-LAN and connects as soon as it is up. Nobody has to get up to make that happen.
+
+THE PICTURE YOUR TV CAN ACTUALLY SHOW
+
+For your Apple TV, the host creates a real virtual display at exactly the resolution and refresh rate your TV reports, up to 4K. No scaling, no black bars, and the monitors on your PC are left where they are. Decoding is done in hardware through VideoToolbox (HEVC and H.264), and HDR is passed through as PQ rather than flattened.
+
+CONTROLLERS, IN FULL
+
+DualSense, Xbox, and other MFi-compatible controllers. On a DualSense, rumble, lightbar, player LEDs, adaptive triggers, touchpad, and gyro all reach the game. The virtual gamepad the host presents takes its type from the controller actually in your hands. Everything is navigable with the Siri Remote or entirely with a controller — the interface is built for a remote, not for a mouse.
+
+YOUR LIBRARY ON THE BIG SCREEN
+
+Installed Steam titles and games you add yourself appear as a grid with artwork, ready to launch from the couch. Several devices can stream at once, each on its own display — so the Apple TV in the living room does not disturb anyone still working at the desk.
+
+FAST, BECAUSE WE OWN THE WHOLE PATH
+
+The native apps speak punktfunk/1: a QUIC control plane and an encrypted data plane with forward error correction. A tiered overlay shows frame rate, bitrate, and latency — corrected for clock skew across the two machines, so it is a measurement rather than a claim. A per-host speed test suggests a bitrate that matches your network.
+
+WHAT YOU NEED
+
+A Punktfunk host on a Linux PC or on Windows 11 (22H2 or later) on the same network. For the best experience, put your Apple TV on Ethernet or on good 5 GHz Wi-Fi. The host is open source (MIT/Apache-2.0) and free — guides and source at punktfunk.unom.io.
+
+No account. No cloud. No telemetry. This app collects no data about you.
+```
+
+---
+
+## Keywords — max 100 characters
+
+### DE (93)
+
+```
+streaming,spiele,gaming,controller,gamepad,wohnzimmer,fernseher,pc,linux,windows,4k,hdr,couch
+```
+
+### EN (91)
+
+```
+streaming,gaming,controller,gamepad,livingroom,tv,pc,linux,windows,4k,hdr,couch,remote,play
+```
+
+Same exclusions as macOS: no `Moonlight`, `GameStream`, `NVIDIA`, or `Steam` in the keyword field.

clients/cli/src/main.rs

@@ -41,16 +41,23 @@ mod cli {
 
     const PROBE_TIMEOUT: Duration = Duration::from_millis(2500);
 
+    /// The handshake budget `--request-access` runs on. Matches the host's `PENDING_APPROVAL_WAIT`
+    /// — the connect is PARKED for that long while an operator decides, so anything shorter would
+    /// give up while the approval prompt is still on their screen.
+    const REQUEST_ACCESS_TIMEOUT_SECS: u64 = 185;
+
     const USAGE: &str = "\
 punktfunk — the Punktfunk client, headless
 
+  punktfunk discover [--json] [--timeout SECS]
   punktfunk pair <host[:port]> [--pin N] [--name LABEL]
   punktfunk hosts list [--probe] [--json]
   punktfunk hosts add <host[:port]> [--name LABEL] [--fp HEX]
   punktfunk hosts forget <host-ref>
   punktfunk wake <host-ref> [--wait]
   punktfunk library <host-ref> [--json]
-  punktfunk launch <host-ref> [--game ID] [--profile REF] [--exec] [--fullscreen]
+  punktfunk launch <host-ref> [--game ID] [--profile REF] [--request-access]
+                              [--exec] [--fullscreen]
   punktfunk open <punktfunk://…>
   punktfunk reachable <host-ref>
   punktfunk speed-test <host-ref>
@@ -68,6 +75,24 @@ punktfunk:// link takes. Exit codes: 0 ok, 2 connect, 3 trust, 4 renderer, 5 not
     /// (what goes to stdout vs stderr, and which exit codes mean what).
     fn verb_help(verb: &str) -> Option<&'static str> {
         Some(match verb {
+            "discover" => {
+                "\
+punktfunk discover [--json] [--timeout SECS] — browse the LAN for hosts
+
+Listens for Punktfunk hosts advertising over mDNS and prints what answered:
+name TAB addr:port TAB saved|new TAB paired|unpaired. `saved` means this
+device already has a record for it, matched by fingerprint first and address
+second — the same rule every other surface joins the two lists by.
+
+  --timeout SECS  how long to browse (default 3, capped at 30) — a bounded
+                  call, so a panel can wait for it
+  --json          {\"hosts\":[{\"name\",\"addr\",\"port\",\"fp\",\"pair\",\"id\",\"mgmt\",
+                  \"os\",\"saved\",\"paired\"}]}
+
+Nothing answering is an answer, not a failure: an empty list exits 0. A host
+mDNS never sees (Tailscale, another subnet) will not appear here — save it by
+address with `punktfunk hosts add` and it shows in `hosts list --probe`."
+            }
             "pair" => {
                 "\
 punktfunk pair <host[:port]> — enrol this device with a host (PIN ceremony)
@@ -96,6 +121,13 @@ punktfunk hosts — the saved-hosts store (shared with the desktop client)
       another subnet). Without --fp it is a placeholder to pair later; with a
       64-hex fingerprint it is pinned immediately (still unpaired).
 
+      Idempotent, and keyed on the FINGERPRINT once there is one: re-running it
+      for a host already saved is a no-op, and giving a known fingerprint a new
+      address MOVES that host's record there rather than filing a second one
+      (which is how a host that changed DHCP lease stays reachable by its id).
+      A different fingerprint for an address already saved is refused, exit 3 —
+      a changed identity is a decision for a person.
+
   punktfunk hosts forget <host-ref>
       Remove a saved host, its pinned fingerprint included. A later connect
       must pair or trust it again."
@@ -119,7 +151,8 @@ this. Needs a paired host (exit 6 otherwise)."
             }
             "launch" => {
                 "\
-punktfunk launch <host-ref> [--game ID] [--profile REF] [--exec] [--fullscreen]
+punktfunk launch <host-ref> [--game ID] [--profile REF] [--request-access]
+                            [--exec] [--fullscreen]
 
 Start a stream — waking the host first if it is asleep and its MAC is known.
 The stream runs in the punktfunk-session renderer; this command supervises it
@@ -132,6 +165,16 @@ and relays its lifecycle to stderr.
   --exec         become the session process instead of supervising it — the
                  gamescope-wrapper mode, where the launched process must BE
                  the streaming one for focus and lifecycle to work
+  --request-access
+                 ask the host's operator to let this device in instead of
+                 typing a PIN. The host PARKS the connect until somebody
+                 approves it in its console or web UI (up to ~185 s), then
+                 admits it and the stream starts by itself; the host is
+                 recorded as paired once that happens, so later streams are
+                 silent. Needs the host's fingerprint pinned already
+                 (`punktfunk hosts add <addr> --fp <hex>`), and cannot be
+                 combined with --exec — under --exec there is no process
+                 left to record the approval.
 
 Exit 0 when the stream ends cleanly, 2 connect failed, 3 the host no longer
 trusts this device (re-pair), 4 the renderer could not start."
@@ -222,7 +265,7 @@ from the config directory for a true factory reset."
     fn flag_takes_value(flag: &str) -> bool {
         matches!(
             flag,
-            "--pin" | "--name" | "--fp" | "--game" | "--profile" | "--port"
+            "--pin" | "--name" | "--fp" | "--game" | "--profile" | "--port" | "--timeout"
         )
     }
 
@@ -269,6 +312,7 @@ from the config directory for a true factory reset."
             return OK;
         }
         match verb.as_str() {
+            "discover" => discover(&rest),
             "pair" => pair(&rest),
             "hosts" => hosts(&rest),
             "wake" => wake(&rest),
@@ -306,6 +350,104 @@ from the config directory for a true factory reset."
         }
     }
 
+    /// How long `discover` browses when nobody says, and the ceiling on what they can ask for.
+    /// The cap is not politeness: this verb is called from a Quick Access panel, and a typo'd
+    /// `--timeout 3000` would hang that panel with no way to cancel it.
+    const DISCOVER_DEFAULT_SECS: f64 = 3.0;
+    const DISCOVER_MAX_SECS: f64 = 30.0;
+
+    /// `discover [--json] [--timeout SECS]` — browse the LAN over mDNS and print what answered,
+    /// annotated against the saved-hosts store.
+    ///
+    /// The annotation is the point: a caller wants "can I stream this", which is a question
+    /// about BOTH lists, and joining them itself is how two surfaces end up disagreeing about
+    /// the same host. So the match rule lives here, once, and is the same one every other
+    /// surface uses — fingerprint first (survives a DHCP move), address second.
+    fn discover(args: &[String]) -> u8 {
+        let secs = value(args, "--timeout")
+            .and_then(|v| v.parse::<f64>().ok())
+            .filter(|s| *s > 0.0)
+            .unwrap_or(DISCOVER_DEFAULT_SECS)
+            .min(DISCOVER_MAX_SECS);
+        let found = pf_client_core::discovery::discover_for(Duration::from_secs_f64(secs));
+        // `read`, not `load`: this verb only LOOKS at the records to annotate what it found, and
+        // never hands their ids back. `load` would mint ids for a pre-mint store and save them —
+        // a write from a read-only verb, and one that races the `hosts list` a caller is very
+        // likely running at the same moment (the Decky panel issues both together).
+        let known = KnownHosts::read();
+        let rows: Vec<(
+            &pf_client_core::discovery::DiscoveredHost,
+            Option<&KnownHost>,
+        )> = found.iter().map(|d| (d, match_saved(&known, d))).collect();
+        if has(args, "--json") {
+            let hosts: Vec<serde_json::Value> = rows
+                .iter()
+                .map(|(d, saved)| {
+                    serde_json::json!({
+                        "name": d.name,
+                        "addr": d.addr,
+                        "port": d.port,
+                        "fp": d.fp_hex,
+                        "pair": d.pair,
+                        "id": d.advertised_id(),
+                        // 0 = not advertised, which is what a consumer's own "no mgmt port"
+                        // already means — an older host simply omits the TXT.
+                        "mgmt": d.mgmt_port.unwrap_or(0),
+                        "os": d.os,
+                        "saved": saved.is_some(),
+                        "paired": saved.is_some_and(|h| h.paired),
+                    })
+                })
+                .collect();
+            println!("{}", serde_json::json!({ "hosts": hosts }));
+        } else {
+            for (d, saved) in &rows {
+                println!(
+                    "{}\t{}:{}\t{}\t{}",
+                    d.name,
+                    d.addr,
+                    d.port,
+                    if saved.is_some() { "saved" } else { "new" },
+                    if saved.is_some_and(|h| h.paired) {
+                        "paired"
+                    } else {
+                        "unpaired"
+                    },
+                );
+            }
+        }
+        // An empty LAN is an answer, not a failure — a caller branching on the exit code is
+        // asking "did the browse run", and it did.
+        OK
+    }
+
+    /// The saved record an advert belongs to, if any: fingerprint first, address second.
+    ///
+    /// Fingerprint FIRST is deliberate and load-bearing — a host that moved to a new DHCP lease
+    /// still matches its record, and a *different* host that inherited the old address does not
+    /// inherit its pairing. This is the rule the plugin's `mergeHosts` and the shells' hosts
+    /// pages already use; keeping one copy is what stops two surfaces disagreeing about whether
+    /// the box in front of you is paired.
+    fn match_saved<'a>(
+        known: &'a KnownHosts,
+        advert: &pf_client_core::discovery::DiscoveredHost,
+    ) -> Option<&'a KnownHost> {
+        known
+            .hosts
+            .iter()
+            .find(|h| {
+                !h.fp_hex.is_empty()
+                    && !advert.fp_hex.is_empty()
+                    && h.fp_hex.eq_ignore_ascii_case(&advert.fp_hex)
+            })
+            .or_else(|| {
+                known
+                    .hosts
+                    .iter()
+                    .find(|h| h.addr == advert.addr && h.port == advert.port)
+            })
+    }
+
     /// `pair <host[:port]> [--pin N]` — the SPAKE2 ceremony. Without `--pin` it prompts, which
     /// is the interactive shape; with one it is scriptable. Refuses rather than prompting when
     /// stdin isn't a terminal and no PIN was given: a pairing that silently blocks a CI job
@@ -424,16 +566,69 @@ from the config directory for a true factory reset."
                     return UNRESOLVED;
                 };
                 let (addr, port) = split_host_port(&target);
+                let fp = value(args, "--fp").unwrap_or_default();
+                let name = value(args, "--name");
                 let mut known = KnownHosts::load();
-                if known.hosts.iter().any(|h| h.addr == addr && h.port == port) {
-                    eprintln!("{addr}:{port} is already saved");
-                    return OK;
+                if let Some(i) = known
+                    .hosts
+                    .iter()
+                    .position(|h| h.addr == addr && h.port == port)
+                {
+                    return match merge_saved_host(&mut known, i, &fp, name.as_deref()) {
+                        AddOutcome::Unchanged => {
+                            eprintln!("{addr}:{port} is already saved");
+                            OK
+                        }
+                        AddOutcome::Conflict => {
+                            eprintln!(
+                                "{addr}:{port} is already saved with a different fingerprint — \
+                                 forget it first if you really mean to replace it \
+                                 (punktfunk hosts forget {addr}:{port})"
+                            );
+                            TRUST_REJECTED
+                        }
+                        AddOutcome::Pinned => match known.save() {
+                            Ok(()) => {
+                                println!("updated {addr}:{port}");
+                                OK
+                            }
+                            Err(e) => {
+                                eprintln!("saving: {e:#}");
+                                CONNECT_FAILED
+                            }
+                        },
+                    };
+                }
+                // No record at this address — but a record carrying this exact FINGERPRINT is
+                // this same host at a new one. Re-point it rather than filing a second record:
+                // the fingerprint is the identity, and a host that changed DHCP lease is the
+                // whole reason `hosts add --fp` is idempotent in the first place. Without this a
+                // moved host accumulates one record per address it has ever held, and the one a
+                // stable id resolves to keeps the address it can no longer be reached at.
+                if let Some(i) = known
+                    .hosts
+                    .iter()
+                    .position(|h| !fp.is_empty() && h.fp_hex.eq_ignore_ascii_case(&fp))
+                {
+                    let was = format!("{}:{}", known.hosts[i].addr, known.hosts[i].port);
+                    known.hosts[i].addr = addr.clone();
+                    known.hosts[i].port = port;
+                    return match known.save() {
+                        Ok(()) => {
+                            println!("moved {was} to {addr}:{port}");
+                            OK
+                        }
+                        Err(e) => {
+                            eprintln!("saving: {e:#}");
+                            CONNECT_FAILED
+                        }
+                    };
                 }
                 known.hosts.push(KnownHost {
-                    name: value(args, "--name").unwrap_or_else(|| addr.clone()),
+                    name: name.unwrap_or_else(|| addr.clone()),
                     addr: addr.clone(),
                     port,
-                    fp_hex: value(args, "--fp").unwrap_or_default(),
+                    fp_hex: fp,
                     ..Default::default()
                 });
                 match known.save() {
@@ -475,6 +670,55 @@ from the config directory for a true factory reset."
         }
     }
 
+    /// What `hosts add` did to a record that was ALREADY saved for this address.
+    #[derive(Debug, PartialEq, Eq)]
+    enum AddOutcome {
+        /// Nothing to do — no fingerprint was offered, or the record already carries this one.
+        /// Exits 0 on purpose: a panel retrying step 1 of request access must not have to
+        /// invent an error to show for a state that is already correct.
+        Unchanged,
+        /// The record had no fingerprint and now has this one.
+        Pinned,
+        /// The record carries a DIFFERENT fingerprint. Refused, never overwritten.
+        Conflict,
+    }
+
+    /// `hosts add --fp` against an address that is already saved. The difference between these
+    /// three is a trust decision, not bookkeeping.
+    ///
+    /// Filling in an empty fingerprint is step 1 of request access (design §5): a host found by
+    /// advert is saved by address first and pinned second. Without it the `--fp` is dropped on
+    /// the floor and the launch that follows refuses for want of a pin — which is what this did
+    /// before, silently and with exit 0.
+    ///
+    /// A *different* fingerprint is refused because a changed identity is a decision for a
+    /// person, at a surface that can show them both. That is what `upsert_trusted` exists to
+    /// enforce; quietly overwriting it here would be a back door through the pinning the rest
+    /// of the client is built on.
+    fn merge_saved_host(
+        known: &mut KnownHosts,
+        i: usize,
+        fp: &str,
+        name: Option<&str>,
+    ) -> AddOutcome {
+        let existing = known.hosts[i].fp_hex.clone();
+        if fp.is_empty() || existing.eq_ignore_ascii_case(fp) {
+            return AddOutcome::Unchanged;
+        }
+        if !existing.is_empty() {
+            return AddOutcome::Conflict;
+        }
+        known.hosts[i].fp_hex = fp.to_string();
+        // Only a record still named after its own address is renamed: a label the user chose is
+        // theirs, and an advert's name must not quietly overwrite it.
+        if let Some(label) = name {
+            if known.hosts[i].name == known.hosts[i].addr {
+                known.hosts[i].name = label.to_string();
+            }
+        }
+        AddOutcome::Pinned
+    }
+
     /// `wake <host-ref> [--wait]` — a magic packet, and with `--wait` the same bounded
     /// wake-and-wait the shells run (`WakeWait`: a packet every 6 s, presence polled every
     /// second, 90 s budget).
@@ -585,6 +829,19 @@ from the config directory for a true factory reset."
             eprintln!("usage: punktfunk launch <host-ref> [--game ID] [--profile REF] [--exec]");
             return UNRESOLVED;
         };
+        let exec = has(args, "--exec");
+        let request_access = has(args, "--request-access");
+        // Refused rather than silently downgraded: under `--exec` this process BECOMES the
+        // session, so nothing survives to see `Ready` and record the approval. A launch that
+        // quietly dropped the persistence would leave hosts reading "trusted" forever with
+        // nobody able to say why.
+        if request_access && exec {
+            eprintln!(
+                "--request-access can't be combined with --exec: under --exec there is no \
+                 process left to record the host's approval"
+            );
+            return UNRESOLVED;
+        }
         let (known, i) = match resolve(&reference) {
             Ok(v) => v,
             Err(code) => return code,
@@ -597,7 +854,10 @@ from the config directory for a true factory reset."
         if has(args, "--fullscreen") {
             plan.settings.fullscreen_on_stream = true;
         }
-        run_plan(plan, has(args, "--exec"))
+        if request_access {
+            plan.connect_timeout_secs = Some(REQUEST_ACCESS_TIMEOUT_SECS);
+        }
+        run_plan(plan, exec, request_access)
     }
 
     /// `open <url>` — the `punktfunk://` grammar, headless. Same parser, same refusal rules and
@@ -622,7 +882,7 @@ from the config directory for a true factory reset."
             &trust::Settings::load(),
         );
         match outcome {
-            Ok(PlanOutcome::Connect(plan)) => run_plan(*plan, has(args, "--exec")),
+            Ok(PlanOutcome::Connect(plan)) => run_plan(*plan, has(args, "--exec"), false),
             // A URL may never pair or trust on its own — that is a decision for a person, at a
             // surface that can show them the fingerprint.
             Ok(PlanOutcome::ConfirmUnknown(u)) => {
@@ -646,7 +906,13 @@ from the config directory for a true factory reset."
     }
 
     /// Wake if needed, then run the session — supervising it, or becoming it under `--exec`.
-    fn run_plan(plan: ConnectPlan, exec: bool) -> u8 {
+    ///
+    /// `persist_paired` records the host as *paired* when the child reports ready. Only
+    /// `launch --request-access` passes true: there, the host parked the connect until an
+    /// operator approved this device, so `Ready` IS the approval arriving — the same thing
+    /// `SpawnOpts::persist_paired` means in the GTK shell. Every other launch records nothing,
+    /// which is correct: a plain connect proves reachability, not a new trust decision.
+    fn run_plan(plan: ConnectPlan, exec: bool, persist_paired: bool) -> u8 {
         if plan.host.fp_hex.is_none() {
             eprintln!(
                 "{} has no pinned fingerprint — punktfunk pair {}",
@@ -708,7 +974,24 @@ from the config directory for a true factory reset."
         let mut failure: Option<(String, bool)> = None;
         while let Ok(ev) = rx.recv() {
             match ev {
-                SessionEvent::Ready => eprintln!("streaming"),
+                SessionEvent::Ready => {
+                    eprintln!("streaming");
+                    // The pin we connected WITH, not one re-derived from the store: the record
+                    // is what we are about to rewrite, and the session proved the host holds
+                    // exactly this identity by completing a pinned handshake against it.
+                    if persist_paired {
+                        if let Some(fp_hex) = &plan.host.fp_hex {
+                            trust::persist_host(
+                                &plan.host.name,
+                                &plan.host.addr,
+                                plan.host.port,
+                                fp_hex,
+                                true,
+                            );
+                            trust::forget_placeholder(&plan.host.addr, plan.host.port);
+                        }
+                    }
+                }
                 SessionEvent::Error {
                     msg,
                     trust_rejected,
@@ -967,6 +1250,7 @@ from the config directory for a true factory reset."
         #[test]
         fn every_usage_verb_has_help() {
             for verb in [
+                "discover",
                 "pair",
                 "hosts",
                 "wake",
@@ -988,6 +1272,109 @@ from the config directory for a true factory reset."
             assert!(verb_help("bogus").is_none());
         }
 
+        fn saved(name: &str, addr: &str, fp: &str) -> KnownHost {
+            KnownHost {
+                name: name.into(),
+                addr: addr.into(),
+                port: 9777,
+                fp_hex: fp.into(),
+                ..Default::default()
+            }
+        }
+
+        /// Step 1 of request access: a host saved by address gains the fingerprint its advert
+        /// carried. Before this, `hosts add --fp` on an existing record exited 0 having done
+        /// NOTHING — the launch that followed then refused for want of a pin, and the panel had
+        /// no way to tell why.
+        #[test]
+        fn adding_a_fingerprint_to_a_placeholder_fills_it_in() {
+            let mut known = KnownHosts {
+                hosts: vec![saved("192.168.1.9", "192.168.1.9", "")],
+            };
+            assert_eq!(
+                merge_saved_host(&mut known, 0, "abc123", Some("living-room")),
+                AddOutcome::Pinned
+            );
+            assert_eq!(known.hosts[0].fp_hex, "abc123");
+            assert_eq!(
+                known.hosts[0].name, "living-room",
+                "a record still named after its address takes the offered label"
+            );
+        }
+
+        /// A label the user chose is theirs — an advert's name must not overwrite it.
+        #[test]
+        fn filling_in_a_fingerprint_keeps_a_user_chosen_name() {
+            let mut known = KnownHosts {
+                hosts: vec![saved("Basement rig", "192.168.1.9", "")],
+            };
+            merge_saved_host(&mut known, 0, "abc123", Some("living-room"));
+            assert_eq!(known.hosts[0].name, "Basement rig");
+        }
+
+        /// Idempotent: the panel may retry step 1, and re-offering the fingerprint a record
+        /// already carries is a state that is already correct, not an error to render.
+        #[test]
+        fn re_adding_the_same_fingerprint_changes_nothing() {
+            let mut known = KnownHosts {
+                hosts: vec![saved("desk", "192.168.1.9", "ABC123")],
+            };
+            assert_eq!(
+                merge_saved_host(&mut known, 0, "abc123", None),
+                AddOutcome::Unchanged,
+                "fingerprints compare case-insensitively"
+            );
+            // And a bare `hosts add` with no --fp at all leaves the pin alone.
+            assert_eq!(
+                merge_saved_host(&mut known, 0, "", None),
+                AddOutcome::Unchanged
+            );
+            assert_eq!(known.hosts[0].fp_hex, "ABC123");
+        }
+
+        /// A changed identity is a decision for a person. Never a silent overwrite — this is the
+        /// same rule `upsert_trusted` enforces, and a back door here would defeat it everywhere.
+        #[test]
+        fn a_different_fingerprint_is_refused_not_overwritten() {
+            let mut known = KnownHosts {
+                hosts: vec![saved("desk", "192.168.1.9", "abc123")],
+            };
+            assert_eq!(
+                merge_saved_host(&mut known, 0, "deadbeef", None),
+                AddOutcome::Conflict
+            );
+            assert_eq!(
+                known.hosts[0].fp_hex, "abc123",
+                "the pin must survive intact"
+            );
+        }
+
+        /// A host that changed DHCP lease is re-pointed, not filed a second time. Without this
+        /// the record a stable id resolves to keeps an address the host has left, so a launch
+        /// dials into the void while the panel shows the live one.
+        #[test]
+        fn a_known_fingerprint_at_a_new_address_moves_the_record() {
+            let mut known = KnownHosts {
+                hosts: vec![saved("desk", "192.168.1.9", "abc123")],
+            };
+            // Simulates `hosts add 192.168.1.50 --fp abc123` finding no record at that address.
+            let by_addr = known
+                .hosts
+                .iter()
+                .position(|h| h.addr == "192.168.1.50" && h.port == 9777);
+            assert!(
+                by_addr.is_none(),
+                "the new address is not yet on any record"
+            );
+            let by_fp = known
+                .hosts
+                .iter()
+                .position(|h| h.fp_hex.eq_ignore_ascii_case("abc123"));
+            assert_eq!(by_fp, Some(0), "the fingerprint still identifies the host");
+            known.hosts[0].addr = "192.168.1.50".into();
+            assert_eq!(known.hosts.len(), 1, "one host, one record");
+        }
+
         #[test]
         fn value_reads_the_argument_after_its_flag() {
             let a = argv(&["--game", "steam:570", "--exec"]);

clients/cli/tests/cli_smoke.rs

@@ -67,3 +67,21 @@ fn unknown_verbs_refuse_with_the_not_found_code() {
     let out = punktfunk(&["help", "frobnicate"]);
     assert_eq!(out.status.code(), Some(5), "unknown help topic exits 5");
 }
+
+/// `discover` and `launch --request-access` document themselves. Help only — the verbs
+/// themselves browse the LAN and dial a host, which no runner may be asked to do.
+///
+/// The Decky panel detects a too-old client by exactly the signature the test above pins
+/// (exit 5 + `unknown command`), so this is the other half of that contract: on a client new
+/// enough, `discover` is a verb with help rather than an unknown word.
+#[test]
+fn the_request_access_surfaces_document_themselves() {
+    let out = punktfunk(&["help", "discover"]);
+    assert!(out.status.success(), "discover has its own help topic");
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    assert!(stdout.contains("--timeout"), "discover documents --timeout");
+    assert!(stdout.contains("--json"), "discover documents --json");
+
+    let out = punktfunk(&["launch", "--help"]);
+    assert!(String::from_utf8_lossy(&out.stdout).contains("--request-access"));
+}

clients/decky/README.md

@@ -2,49 +2,61 @@
 
 Stream to your **Steam Deck** without ever leaving Gaming Mode. This
 **[Decky Loader](https://decky.xyz/)** plugin adds a **Punktfunk** panel to the Quick Access Menu
-(the `…` button): discover hosts on your network, pair with a PIN, tweak stream settings, and launch
-a fullscreen, gamescope-focused stream — all from the couch, gamepad-navigable.
+(the `…` button): the hosts you can stream, the pinned cards you set up, and one tap into each.
 
-The video itself is the native GTK4 Linux client (the `io.unom.Punktfunk` flatpak); the plugin
-discovers, pairs, configures, and *launches it the right way* so gamescope fullscreens it — the same
-Steam-shortcut trick MoonDeck uses. Because it's built from real Steam UI primitives (`@decky/ui`),
-the panel looks and feels native to Gaming Mode.
+The plugin is a **launcher**, not a client. It doesn't decode video, browse your library, or hold
+any settings of its own — the Rust client does all of that, and the plugin's job is to start it
+*the right way* so gamescope fullscreens and focuses it (the same Steam-shortcut trick MoonDeck
+uses). Everything the panel doesn't do is one tap away in the client's own gamepad UI.
 
 ## What it does
 
-1. **Discover** — browses the LAN over mDNS for Punktfunk hosts, in both the QAM panel and a
-   fullscreen page; each host row opens a details view (address, pairing policy, certificate
-   fingerprint to cross-check against the host's log).
-2. **Pair** — for a host that requires it, a gamepad-navigable PIN keypad runs the SPAKE2 pairing
-   ceremony headlessly, then remembers the host so future streams connect silently.
-3. **Stream** — launches fullscreen via a branded "Punktfunk" Steam shortcut so gamescope focuses it.
-4. **Games** — each host row has a games button that opens its **library picker**: pin titles as
-   one-tap "Stream <Game>" rows in the QAM (jump straight into e.g. Playnite on the host), or
-   **"Open library on screen"** to launch the client's controller-driven, console-style library
-   browser (aurora backdrop + poster coverflow; A plays, B returns to Gaming Mode). Pins survive
-   plugin reinstalls (stored next to the client's config) and follow a host across IP changes
-   (matched by certificate fingerprint).
-5. **Settings** — the client's whole settings store, written to its config. Laid out like SteamOS's
-   own Settings: a left rail of categories (`SidebarNavigation`), one page each, so no page needs
-   scrolling. The categories and their order are the console settings screen's — Stream (resolution
-   / refresh / render scale / bitrate / compositor), Video (codec / decoder / GPU / HDR / 4:4:4),
-   Presentation (prioritize / smoothness buffer / V-Sync / VRR), Audio (channels / output + mic
-   device / echo cancellation), Controllers, Touch & mouse, Interface (stats overlay / auto-wake /
-   library / fullscreen). The device pickers are populated
-   from the session binary (`--list-adapters` / `--list-audio`); the GPU row appears only where
-   there is more than one adapter.
-6. **About** — plugin version, an explicit "Check for updates" button, the setup-guide link, and
-   a force-stop for a wedged stream client.
+1. **Hosts** — the hosts on your network plus the ones you've saved, in one list. Discovery is
+   mDNS; saved hosts are also probed directly, so a box reached over Tailscale or a VPN shows as
+   online even though it never advertises. Rows sort online-first, then most recently used.
+2. **Trust** — an unpaired host opens a small sheet with two ways in:
+   - **Request access** (the default) — no PIN. The host's operator approves this Deck in its
+     console or web UI and the stream starts by itself. See [Request access](#request-access).
+   - **Use a PIN instead** — the gamepad-navigable keypad, running the same SPAKE2 ceremony.
+3. **Stream** — launches fullscreen via a branded "Punktfunk" Steam shortcut so gamescope focuses
+   it. A sleeping host is woken first (the client runs the real wake-and-wait loop, then dials).
+4. **Pinned cards** — a *(host, profile)* pair renders nested under its host as `▸ <Profile name>`
+   and streams with that settings profile applied. Cards are the **shared** pinning model every
+   other client speaks, stored on the host's record — so one you make in the desktop client shows
+   up here, and vice versa. The plugin renders them; it doesn't create or edit them.
+5. **Open Punktfunk** — launches the client's **console home**: the host picker, add-host by
+   address, PIN pairing, the game library browser, and the **full settings screen**. This is where
+   everything the panel no longer does now lives.
+6. **About** — plugin version, "Check for updates", "Recreate library shortcut", and a force-stop
+   for a wedged stream.
 
 To leave a stream: the in-client controller chord (**L1 + R1 + Start + Select**), or close the
 "game" from the Steam overlay — either returns you to Gaming Mode.
 
+### Request access
+
+Request access is not a second pairing ceremony — it is a **launch**. The plugin saves the host
+with the fingerprint it **advertised**, then starts an ordinary identified connect with the
+handshake budget stretched to 185 s. The host *parks* that connection until its operator approves
+the device, then admits the same connection; the stream starts on its own, and the record flips
+to **paired** so every later stream is silent.
+
+**No advertised fingerprint, no request access.** That pinned fingerprint is the only thing
+standing between a 185-second wait and an impostor answering for the host, so a host you typed in
+by address gets the PIN path only — and the sheet says why. The plugin never trusts-on-first-use
+past a missing fingerprint.
+
 ## Install on the Deck
 
-You need **[Decky Loader](https://decky.xyz/)** and the **`io.unom.Punktfunk` flatpak**
-([`packaging/flatpak`](../../packaging/flatpak/README.md)) installed on the Deck — SteamOS `/usr` is
-read-only, so the flatpak (which bundles libadwaita/SDL3) is the canonical client. Discovery uses
-`avahi-browse`, which ships on SteamOS/Bazzite.
+You need **[Decky Loader](https://decky.xyz/)** and a **Punktfunk client** on the Deck. On a normal
+Deck that's the `io.unom.Punktfunk` flatpak ([`packaging/flatpak`](../../packaging/flatpak/README.md)) —
+SteamOS `/usr` is read-only, so the flatpak (which bundles libadwaita/SDL3) is the canonical client.
+A native install (sysext, distro package, nix profile, your own build) works too.
+
+**The client must be v0.22.0 or newer** — that is when the headless `punktfunk` CLI shipped, and
+the panel drives everything through it. An older client says so in the panel, with the update
+button that fixes it right there. (Discovery no longer needs `avahi-browse` on the Deck; the
+client's own mDNS does it.)
 
 **Recommended — install from URL** (published by CI): in Decky → Settings → **Developer Mode** →
 **Install Plugin from URL**, paste:
@@ -55,17 +67,15 @@ https://unom.io/pf-decky
 
 (short link for `https://git.unom.io/api/packages/unom/generic/punktfunk-decky/latest/punktfunk.zip`;
 for a pinned version use `https://git.unom.io/api/packages/unom/generic/punktfunk-decky/<version>/punktfunk.zip`
-directly). The plugin then **self-updates** without
-the Decky store — when a newer build exists, an **Update** button appears and drives Decky
-Loader's own (SHA-256-verified) install. Installs and updates can take a couple of minutes on some
-networks: Decky's installer also contacts its plugin store first, which may be slow or blackholed
-before the actual download proceeds.
+directly). The plugin then **self-updates** without the Decky store — when a newer build exists, an
+**Update** button appears and drives Decky Loader's own (SHA-256-verified) install. Installs and
+updates can take a couple of minutes on some networks: Decky's installer also contacts its plugin
+store first, which may be slow or blackholed before the actual download proceeds.
 
 ### Updating the client
 
 The plugin also reports — and where it can, installs — updates for the **client** it launches.
-What is possible depends on how that client was installed, and the About tab names the install
-kind so the answer is never a mystery:
+What is possible depends on how that client was installed:
 
 | Install | Update |
 | --- | --- |
@@ -88,6 +98,8 @@ pnpm install
 pnpm build                             # rollup → dist/index.js
 pnpm run package                       # → out/punktfunk/ + out/punktfunk-v<ver>.zip
 DECK=deck@<deck-ip> pnpm run deploy    # rsync → /tmp, sudo-install into the root-owned plugins dir, restart loader
+
+python3.13 scripts/test-backend.py     # backend unit checks (needs Python ≥3.10)
 ```
 
 `~/homebrew/plugins/` is root-owned (the loader runs as root), so `deploy.sh` stages to a temp dir
@@ -96,28 +108,46 @@ restart is required for an out-of-band install to appear.
 
 ## Architecture
 
+Everything below the panel is the CLI. `main.py` builds argv and maps exit codes; it parses none of
+the client's data files and re-implements none of its rules.
+
 | File | Role |
 | --- | --- |
-| `src/index.tsx` | Plugin entry: the QAM panel + route registration. |
-| `src/page.tsx` | The `/punktfunk` fullscreen page — Hosts (with per-host details) / Settings / About tabs. |
-| `src/settings.tsx` · `src/pair.tsx` | The settings screen (a `SidebarNavigation` of seven category pages over one shared settings object); the gamepad-navigable PIN-pairing modal. |
-| `src/library.tsx` | The per-host game picker (pin/unpin, "Open library on screen") + the pinned-game launch helper. |
-| `src/hostmgmt.tsx` | Add / edit host dialogs — mutate the shared known-hosts store (`client-known-hosts.json`) via the flatpak client's headless modes, so a host saved here shows up in the desktop client too. |
-| `src/ui.tsx` | Shared UI primitives for the fullscreen page + modals (right-aligned row actions, consistent Field layout). |
-| `src/hooks.ts` · `src/boundary.tsx` | Shared discovery/update/pins hooks + actions; the render error boundary. |
-| `src/steam.ts` | Steam-shortcut launch (`AddShortcut` / `SetAppLaunchOptions` / `RunGame`) — the focus-correct stream start. The shortcut's exe is `/bin/sh` with the wrapper passed as an argument, so the script never needs an exec bit (Decky's zip extraction drops it and the root-owned plugins dir can't be chmodded by the unprivileged backend). Launch extras ride env-prefix tokens: `PF_LAUNCH=<id>` (pinned game) / `PF_BROWSE=1` + `PF_MGMT=<port>` (on-screen library); ids are validated space/quote-free at pin AND launch time. |
-| `src/backend.ts` | Typed `callable` bridges to `main.py`. |
-| `bin/punktfunkrun.sh` | The launch wrapper the Steam shortcut runs (so the window is focusable); maps `PF_LAUNCH`/`PF_BROWSE`/`PF_MGMT` to `--launch`/`--browse`/`--mgmt`. An older flatpak ignores the flags harmlessly (plain stream / hosts page). |
-| `main.py` | Backend: `discover` (via `avahi-browse`) / `pair` / `library` (headless flatpak `--library`, TSV) / pins store (`decky-pinned.json`) / settings / `kill_stream` / `check_update` (with an explicit CA-bundle search — Decky's embedded Python has no usable default TLS roots on SteamOS). |
-| `scripts/test-backend.py` | Stdlib-only checks for the backend's pure parsers (TSV, error classes, avahi TXT) + the pins round trip. |
+| `src/index.tsx` | Plugin entry + the QAM panel: update banner, hosts (with nested pinned cards), the console-home door, about. |
+| `src/hooks.ts` | `useHosts` (one call merging discovery and the saved store), the update hooks, and the launch action. Also the trust-state model the rows render. |
+| `src/trust.tsx` · `src/pair.tsx` | The trust sheet (Request access / Use a PIN instead / Cancel) and the gamepad-navigable PIN keypad. |
+| `src/steam.ts` | Steam-shortcut launch (`AddShortcut` / `SetAppLaunchOptions` / `RunGame`) — the focus-correct stream start. The shortcut's exe is `/bin/sh` with the wrapper passed as an argument, so the script never needs an exec bit (Decky's zip extraction drops it and the root-owned plugins dir can't be chmodded by the unprivileged backend). |
+| `src/backend.ts` · `src/boundary.tsx` · `src/os-icon.tsx` | Typed `callable` bridges to `main.py`; the render error boundary; the host row's OS mark. |
+| `bin/punktfunkrun.sh` | The launch wrapper the Steam shortcut runs (so the window is focusable). Reads `PF_REF` / `PF_PROFILE` / `PF_REQUEST_ACCESS` / `PF_BROWSE` and runs `punktfunk launch` — or the session's `--browse` for console home. |
+| `main.py` | Backend: four thin CLI shells (`discover` / `hosts` / `pair` / `trust_host`) plus the Steam-side work only a plugin can do — `runner_info`, `shortcut_art`, `apply_controller_config`, `kill_stream`, `check_update` / `update_client` (with an explicit CA-bundle search — Decky's embedded Python has no usable default TLS roots on SteamOS). |
+| `scripts/test-backend.py` | Stdlib-only checks: argv shape, the CLI exit-code mapping, and the Steam configset editor. |
 | `plugin.json` · `update.json` | Decky manifest; CI-baked update channel. |
 
+### Why the launch goes through Steam
+
+gamescope only gives focus and fullscreen to the window tree Steam launched via `reaper` (it
+detects the "current app" by AppID — gamescope#484). A client spawned from the plugin's own
+backend comes up invisible and unfocused. So the plugin registers non-Steam shortcuts whose exe is
+`/bin/sh` running `bin/punktfunkrun.sh`, and starts them with `RunGame`.
+
+There are **two** shortcuts, both named `Punktfunk` so Steam keys them to one Steam Input
+configset (the key is the lowercase name): a hidden, stateful one that carries the stream, and the
+visible, stateless library entry that opens console home.
+
 ## Limitations / next steps
 
-- No manual "add host by IP" entry yet (discovery is mDNS-only).
-- No in-stream overlay inside the plugin — the client owns the session once launched.
-- Pairing needs the operator to **arm pairing on the host** so it shows the PIN; the plugin can't arm
-  it remotely.
+- **Profiles and pinned cards can't be created here** — the panel renders them; making one needs
+  the desktop client, or the client's own gamepad UI once that work lands. A Deck with no profiles
+  simply sees host rows, and nothing is broken.
+- **Per-game pins are on hold.** The shared model pins *host+profile*; nothing in the shared store
+  persists a pinned *game* yet. The old `decky-pinned.json` is left on disk untouched so a later
+  migration can read it.
+- Pairing with a PIN needs the operator to **arm pairing on the host** so it shows the PIN; the
+  plugin can't arm it remotely. Request access needs no arming — just an approval.
+- **A parked connect looks like a hanging one.** The plugin toasts before launching a request-access
+  stream to set expectations, which is a patch rather than a fix; teaching the session's connect
+  screen the same "waiting for approval" copy the console shell already has would pay off for every
+  shell.
 
 ## Related
 

clients/decky/bin/punktfunkrun.sh

@@ -1,33 +1,32 @@
 #!/usr/bin/env bash
-# punktfunk stream runner — the target of the hidden non-Steam shortcut the plugin creates.
+# punktfunk stream runner — the target of the non-Steam shortcuts the plugin creates.
 #
 # WHY A WRAPPER SCRIPT (load-bearing, from MoonDeck's hard-won knowledge): the stream client
 # must be a descendant of the process Steam launches via `reaper`, or gamescope never gives
 # its window focus/fullscreen in Gaming Mode (gamescope detects the "current app" by AppID,
 # which only attaches to reaper's descendants — see gamescope#484). So the Decky plugin
-# launches THIS script through SteamClient.Apps.RunGame; the script then execs the flatpak
-# client, which inherits the shortcut's AppID and is focused. Launching the flatpak directly
-# from the (root) Decky backend produces an unfocused, invisible window.
+# launches THIS script through SteamClient.Apps.RunGame; the script then runs the client,
+# which inherits the shortcut's AppID and is focused. Launching the client directly from the
+# (root) Decky backend produces an unfocused, invisible window.
 #
 # Per-session parameters arrive as environment variables, set as the shortcut's Steam launch
 # options by the plugin (SteamClient.Apps.SetAppLaunchOptions), so ONE generic shortcut serves
-# every host (and every pinned game):
-#   PF_HOST   host[:port] to connect to            (required for streaming; optional for browse)
-#   PF_LAUNCH library id to launch on connect       (optional, e.g. steam:570 — pinned games)
-#   PF_BROWSE non-empty = open the gamepad library  (optional; --browse instead of --connect)
-#   PF_MGMT   management-API port for --browse       (optional; client defaults to 47990)
-#   PF_CONNECT_TIMEOUT  connect budget in seconds    (optional; the plugin stretches it after
-#                        firing Wake-on-LAN so the connect survives the host's resume)
-#   PF_APPID  flatpak app id                        (default io.unom.Punktfunk)
-#   PF_FLATPAK  override the flatpak binary path     (default: `flatpak` on PATH)
+# every host:
+#   PF_REF     host reference — a saved host's stable id, or addr[:port]  (required to stream)
+#   PF_PROFILE settings-profile id for a pinned card                      (optional)
+#   PF_REQUEST_ACCESS  non-empty = ask the host's operator to admit this device instead of
+#                      pairing with a PIN. The connect PARKS until somebody approves it.
+#   PF_BROWSE  non-empty = open the client's console home instead of streaming
+#   PF_APPID   flatpak app id                        (default io.unom.Punktfunk)
+#   PF_FLATPAK override the flatpak binary path      (default: `flatpak` on PATH)
 #   PF_CLIENT_BIN  absolute path of a NATIVE client  (optional; set by the plugin when it
-#                  resolved a non-flatpak install — then the client is exec'd directly and
+#                  resolved a non-flatpak install — then the client is run directly and
 #                  PF_APPID/PF_FLATPAK are unused)
 #
-# Values are plain tokens (the plugin validates launch ids to space/quote-free ASCII before
-# they ever reach Steam launch options). An older flatpak without --launch/--browse ignores
-# the unknown flags harmlessly (hand-scanned argv): PF_LAUNCH degrades to the plain desktop
-# session, PF_BROWSE to the client's hosts page.
+# A REFERENCE, NEVER A VALUE. Host refs and profile ids are the only things that ride this
+# channel; no resolution, bitrate or codec ever does. The client resolves both against its own
+# stores, which is what keeps a Steam launch option from becoming a second settings surface.
+# The plugin validates them to space/quote-free ASCII before they reach Steam's tokenizer.
 #
 # Runs as the `deck` user (Steam launched it), so the --user flatpak install is visible and
 # WAYLAND_DISPLAY / XDG_RUNTIME_DIR are already correct for gamescope.
@@ -42,13 +41,22 @@ APPID="${PF_APPID:-io.unom.Punktfunk}"
 FLATPAK="${PF_FLATPAK:-flatpak}"
 
 # The client is not always the flatpak: a sysext, a .deb/.rpm, an AUR build or a nix profile
-# installs a native `punktfunk-client`, and the plugin passes its absolute path here when that
-# is what it resolved. Both kinds take the same argv and share ~/.config/punktfunk, so the only
-# difference is the prefix in front of it.
+# installs a native `punktfunk-client` with the CLI as its sibling, and the plugin passes the
+# client's absolute path here when that is what it resolved.
 #
-# exec so the client IS the game process — when it exits, Steam ends the "game" and Gaming Mode
-# reclaims focus automatically (no manual refocus needed).
-run_client() {
+# run_cli execs the HEADLESS CLI (`punktfunk`); run_session execs the GTK/console shell
+# (`punktfunk-client`). Both live in the same place in both install kinds — /app/bin inside the
+# flatpak, reachable with `--command=`, and one bindir natively.
+run_cli() {
+    if [ -n "${PF_CLIENT_BIN:-}" ]; then
+        # `${VAR%/*}` rather than `dirname`: pure parameter expansion, so this works with no
+        # PATH at all — which is the environment a Steam launch option can leave us in.
+        exec "${PF_CLIENT_BIN%/*}/punktfunk" "$@"
+    fi
+    exec "$FLATPAK" run --arch=x86_64 --command=punktfunk "$APPID" "$@"
+}
+
+run_session() {
     if [ -n "${PF_CLIENT_BIN:-}" ]; then
         exec "$PF_CLIENT_BIN" "$@"
     fi
@@ -58,40 +66,35 @@ run_client() {
 # What we are about to run, for the log line each branch prints.
 CLIENT_LABEL="${PF_CLIENT_BIN:-$APPID}"
 
-# --fullscreen: present the stream chrome-less and fullscreen (the client also auto-detects the
-# Deck/gamescope env, and ignores the flag harmlessly on older builds that predate it).
+# The console home: the client's own gamepad UI (host picker, pairing, add-host by address, the
+# library browser and the full settings screen). UNCHANGED from before this rework — the shell
+# binary already execs the session for `--browse`, so there is nothing to repoint here.
 if [ -n "${PF_BROWSE:-}" ]; then
-    # The gamepad UI. BARE `--browse` (no PF_HOST) opens the console home — the self-contained
-    # host picker + pairing + settings, gamepad-navigable — which is what the stateless, visible
-    # library shortcut launches. `--browse <host>` opens straight into that host's library (the
-    # per-host "open on screen" action). A streams a game, session end returns here, B quits.
-    if [ -z "${PF_HOST:-}" ]; then
-        echo "punktfunkrun: gamepad UI $CLIENT_LABEL --browse (console home)" >&2
-        run_client --browse --fullscreen
-    fi
-    echo "punktfunkrun: library $CLIENT_LABEL --browse $PF_HOST" >&2
-    if [ -n "${PF_MGMT:-}" ]; then
-        run_client --browse "$PF_HOST" --mgmt "$PF_MGMT" --fullscreen
-    fi
-    run_client --browse "$PF_HOST" --fullscreen
+    echo "punktfunkrun: gamepad UI $CLIENT_LABEL --browse (console home)" >&2
+    run_session --browse --fullscreen
 fi
 
-# Streaming modes need a host (browse above is the only host-less path).
-if [ -z "${PF_HOST:-}" ]; then
-    echo "punktfunkrun: PF_HOST is not set (the plugin sets it as a launch option)" >&2
+if [ -z "${PF_REF:-}" ]; then
+    echo "punktfunkrun: PF_REF is not set (the plugin sets it as a launch option)" >&2
     exit 2
 fi
-# Trailing args shared by both streaming execs. A stretched connect budget rides along when the
-# plugin set one (it just fired Wake-on-LAN, so the host may still be resuming); an older flatpak
-# without --connect-timeout ignores the flag harmlessly (hand-scanned argv).
+
 set -- --fullscreen
-if [ -n "${PF_CONNECT_TIMEOUT:-}" ]; then
-    set -- --connect-timeout "$PF_CONNECT_TIMEOUT" "$@"
+if [ -n "${PF_PROFILE:-}" ]; then
+    set -- --profile "$PF_PROFILE" "$@"
 fi
-if [ -n "${PF_LAUNCH:-}" ]; then
-    # A pinned game: the id rides the session Hello and the host launches that title.
-    echo "punktfunkrun: streaming $CLIENT_LABEL --connect $PF_HOST --launch $PF_LAUNCH" >&2
-    run_client --connect "$PF_HOST" --launch "$PF_LAUNCH" "$@"
+
+# REQUEST ACCESS RUNS SUPERVISED — no `--exec`. Under --exec the CLI BECOMES the session, so no
+# process survives to see the stream come up and record the host as paired; the CLI refuses the
+# combination outright rather than downgrading silently. This is safe for gamescope because
+# focus follows reaper's DESCENDANT TREE, not a single process, and `flatpak run`/`bwrap`
+# already sit between reaper and the client on every other path.
+if [ -n "${PF_REQUEST_ACCESS:-}" ]; then
+    echo "punktfunkrun: request access $CLIENT_LABEL launch $PF_REF (waiting for approval)" >&2
+    run_cli launch "$PF_REF" --request-access "$@"
 fi
-echo "punktfunkrun: streaming $CLIENT_LABEL --connect $PF_HOST" >&2
-run_client --connect "$PF_HOST" "$@"
+
+# The ordinary stream. `--exec` is the documented gamescope-wrapper mode: the CLI becomes the
+# session, so the process tree stays flat and Steam's "game" ends exactly when the stream does.
+echo "punktfunkrun: streaming $CLIENT_LABEL launch $PF_REF" >&2
+run_cli launch "$PF_REF" --exec "$@"

clients/decky/scripts/test-backend.py

@@ -1,12 +1,12 @@
 #!/usr/bin/env python3
 """Unit checks for main.py's pure helpers — stdlib only, no Decky runtime needed.
 
-Stubs the ``decky`` module (main.py imports it at module level), then asserts the
-avahi/TSV/error parsers against fixture strings. The LibraryError fixtures are pinned to
-the REAL Display strings in clients/linux/src/library.rs — if those are reworded, the
-classifier degrades to ``client-error`` and the matching assertion here fails on purpose.
+Stubs the ``decky`` module (main.py imports it at module level), then asserts the argv
+shapes, the exit-code mapping and the Steam VDF editor against fixtures.
 
-    python3 clients/decky/scripts/test-backend.py
+Needs Python >= 3.10 for `X | None` annotations — macOS ships 3.9, so run it explicitly:
+
+    python3.13 clients/decky/scripts/test-backend.py
 """
 
 import sys
@@ -40,136 +40,135 @@ def check(name: str, cond: bool):
         failures += 1
 
 
-# ---- _parse_library_tsv -----------------------------------------------------------------
-tsv = (
-    "steam:570\tsteam\tDota 2\n"
-    "custom:abc\tcustom\tTabs\tin\ttitle\n"  # tabs inside the title survive (split max 2)
-    "2 game(s)\n"  # the count trailer has no tabs — self-skips
+# ---- _cli_argv: the flatpak app id must stay LAST ---------------------------------------
+#
+# `flatpak run --command=X <app-id> ARGS` — everything after the app id is the APP's argv, so
+# an app id that drifts left silently turns our flags into the client's. This is the shape the
+# deleted _session_argv used and the one thing about it that is easy to get wrong.
+main._client_argv = lambda: ["/usr/bin/flatpak", "run", "--arch=x86_64", "io.unom.Punktfunk"]
+main._flatpak = lambda: "/usr/bin/flatpak"
+check(
+    "cli argv: flatpak form, app id last",
+    main._cli_argv()
+    == [
+        "/usr/bin/flatpak",
+        "run",
+        "--arch=x86_64",
+        "--command=punktfunk",
+        "io.unom.Punktfunk",
+    ],
 )
-games = main._parse_library_tsv(tsv)
-check("tsv: two games parsed", len(games) == 2)
-check("tsv: fields", games[0] == {"id": "steam:570", "store": "steam", "title": "Dota 2"})
-check("tsv: tabs in title preserved", games[1]["title"] == "Tabs\tin\ttitle")
-check("tsv: empty input", main._parse_library_tsv("0 game(s)\n") == [])
 
-# ---- _classify_library_error (fixtures = library.rs Display strings) --------------------
-check(
-    "err: not-paired",
-    main._classify_library_error(
-        "library: The host didn't recognize this device. Pair with the host first — the "
-        "library is authorized by this device's certificate (no token needed)."
-    )
-    == "not-paired",
-)
-check(
-    "err: pin-mismatch",
-    main._classify_library_error(
-        "library: The host's certificate doesn't match the pinned fingerprint. "
-        "Re-pair with a PIN to re-establish trust."
-    )
-    == "pin-mismatch",
-)
-check(
-    "err: unreachable",
-    main._classify_library_error(
-        "library: Couldn't reach the host's management API: connection refused. Check the "
-        "host is updated and reachable."
-    )
-    == "unreachable",
-)
-check(
-    "err: http",
-    main._classify_library_error("library: The management API returned HTTP 500.") == "http",
-)
-check(
-    "err: outdated client (GTK init noise)",
-    main._classify_library_error("cannot open display: \nGtk-WARNING: init failed")
-    == "client-outdated",
-)
-check("err: generic fallback", main._classify_library_error("boom") == "client-error")
-
-# ---- _parse_avahi_browse (incl. the new id/mgmt TXT keys) --------------------------------
-avahi = (
-    "+;eth0;IPv4;living-room;_punktfunk._udp;local\n"
-    "=;eth0;IPv4;living-room;_punktfunk._udp;local;lr.local;192.168.1.42;9777;"
-    '"proto=punktfunk/1" "fp=aabbcc" "pair=required" "id=abc123" "mgmt=47990"\n'
-    "=;eth0;IPv6;living-room;_punktfunk._udp;local;lr.local;fe80::1;9777;"
-    '"proto=punktfunk/1" "fp=aabbcc" "pair=required" "id=abc123" "mgmt=47990"\n'
-    "=;eth0;IPv4;bare-host;_punktfunk._udp;local;bh.local;192.168.1.77;9777;"
-    '"proto=punktfunk/1" "fp=ddeeff" "pair=optional"\n'
-)
-hosts = main._parse_avahi_browse(avahi)
-check("avahi: two hosts (id-dedup, IPv4 preferred)", len(hosts) == 2)
-lr = next(h for h in hosts if h["name"] == "living-room")
-check("avahi: ipv4 wins", lr["host"] == "192.168.1.42")
-check("avahi: mgmt parsed", lr["mgmt"] == 47990)
-check("avahi: id parsed", lr["id"] == "abc123")
-bare = next(h for h in hosts if h["name"] == "bare-host")
-check("avahi: mgmt absent -> 0", bare["mgmt"] == 0)
-check("avahi: id absent -> empty", bare["id"] == "")
-
-# ---- pins store (round-trip through the real methods, isolated HOME) --------------------
-import asyncio  # noqa: E402
+# A native install: the CLI is the client binary's sibling. Absent => no CLI at all, which the
+# caller must see as "unavailable" rather than as an empty result.
+#
+# The fixture dir is torn down FIRST, not just created: leaving the sibling behind made the
+# "absent" assertion below pass only on the first run of the day and fail on every rerun.
 import shutil  # noqa: E402
 
-shutil.rmtree(decky.DECKY_USER_HOME, ignore_errors=True)
-plugin = main.Plugin()
-pin = {
-    "game_id": "steam:570",
-    "title": "Dota 2",
-    "store": "steam",
-    "host_fp": "AABBCC",
-    "host_id": "abc123",
-    "host_name": "living-room",
-    "host": "192.168.1.42",
-    "port": 9777,
-    "mgmt": 47990,
-    "added_at": 1780000000,
-}
-dupe = dict(pin, title="Dota 2 again")
-junk = {"title": "no game id"}
-res = asyncio.run(plugin.set_pins([pin, dupe, junk]))
-check("pins: write ok", res.get("ok") is True)
-got = asyncio.run(plugin.get_pins())["pins"]
-check("pins: dedup + junk dropped", len(got) == 1)
-check("pins: unpaired without known-hosts", got[0]["paired"] is False)
-# Mark the host paired in the client's known-hosts store — get_pins must pick it up.
-cfg = main._client_config_dir()
-cfg.mkdir(parents=True, exist_ok=True)
-(cfg / "client-known-hosts.json").write_text(
-    '{"hosts": [{"name": "living-room", "addr": "192.168.1.42", "port": 9777, '
-    '"fp_hex": "aabbcc", "paired": true}]}'
-)
-got = asyncio.run(plugin.get_pins())["pins"]
-check("pins: paired via known-hosts fp (case-insensitive)", got[0]["paired"] is True)
-shutil.rmtree(decky.DECKY_USER_HOME, ignore_errors=True)
+shutil.rmtree("/tmp/pf-test-native", ignore_errors=True)
+tmp = Path("/tmp/pf-test-native/bin")
+tmp.mkdir(parents=True, exist_ok=True)
+(tmp / "punktfunk-client").write_text("")
+main._client_argv = lambda: [str(tmp / "punktfunk-client")]
+check("cli argv: native without a sibling CLI is None", main._cli_argv() is None)
+(tmp / "punktfunk").write_text("")
+check("cli argv: native sibling found", main._cli_argv() == [str(tmp / "punktfunk")])
 
-# ---- `--list-audio` parsing (the settings tab's device pickers) --------------------------
-sinks, sources = main._parse_audio_endpoints(
-    "sink\talsa_output.pci-0000_04_00.6.analog-stereo\tSteam Deck Speakers\n"
-    "sink\tbluez_output.AC_12_2F.1\tWH-1000XM4\n"
-    "source\talsa_input.pci-0000_04_00.6.analog-stereo\tSteam Deck Microphone\n"
+# ---- _cli_error: the CLI's exit-code contract -------------------------------------------
+#
+# Exit 5 + `unknown command` is how a client too old for a verb announces itself — the ONE
+# signature the panel turns into "update the client" plus the button that fixes it. Getting it
+# wrong makes an out-of-date client look like a broken plugin.
+check(
+    "err: unknown verb => client-outdated",
+    main._cli_error(5, 'unknown command "discover"\n\npunktfunk — the Punktfunk client')
+    == "client-outdated",
 )
-check("audio: sinks parsed", [d["name"] for d in sinks] == [
-    "alsa_output.pci-0000_04_00.6.analog-stereo", "bluez_output.AC_12_2F.1"
-])
-check("audio: sources parsed", len(sources) == 1)
-check("audio: description kept", sinks[1]["description"] == "WH-1000XM4")
+check(
+    "err: exit 5 without that phrase is NOT outdated",
+    main._cli_error(5, 'no saved host matches "desk"') == "unresolved",
+)
+check("err: connect failed", main._cli_error(2, "unreachable 10.0.0.1:9777") == "unreachable")
+check("err: trust rejected", main._cli_error(3, "wrong PIN") == "refused")
+check("err: needs a person", main._cli_error(6, "pair it first") == "needs-pairing")
+check("err: nothing ran", main._cli_error(-1, "") == "client-unavailable")
+check("err: unmapped code falls back", main._cli_error(4, "renderer") == "client-error")
 
-# Junk the picker must not offer: no node.name is unusable (it is the id that gets stored), a
-# short line is malformed, and an unknown kind belongs to neither list. A blank description
-# falls back to the name so no entry renders unlabelled.
-sinks, sources = main._parse_audio_endpoints(
-    "sink\t\tNo node name\n"
-    "sink\tonly-two-columns\n"
-    "monitor\tsome.monitor\tNot a sink or source\n"
-    "source\tbare.node\t\n"
-    "\n"
+# ---- _cli_json: a zero exit with junk on stdout is a FAILURE, not an empty result --------
+import asyncio  # noqa: E402
+
+
+def _fake_cli(rc: int, out: str, err: str = ""):
+    async def run(_args, timeout=20.0):
+        return rc, out, err
+
+    return run
+
+
+main._run_cli = _fake_cli(0, '{"hosts": [{"name": "desk"}]}')
+got = asyncio.run(main._cli_json(["discover", "--json"]))
+check("json: payload merged under ok", got == {"ok": True, "hosts": [{"name": "desk"}]})
+
+main._run_cli = _fake_cli(0, "not json at all")
+got = asyncio.run(main._cli_json(["discover", "--json"]))
+check("json: unparseable stdout is an error, not an empty list", got["ok"] is False)
+check("json: ...and says so specifically", got["error"] == "client-error")
+
+main._run_cli = _fake_cli(5, "", 'unknown command "discover"')
+got = asyncio.run(main._cli_json(["discover", "--json"]))
+check("json: old client surfaces as client-outdated", got["error"] == "client-outdated")
+check("json: detail carries the CLI's own last line", "unknown command" in got["detail"])
+
+# ---- _field_from (flatpak info parsing, drives the client update check) ------------------
+info = "        ID: io.unom.Punktfunk\n    Origin: punktfunk-origin\n    Commit: abc123def\n"
+check("field: commit", main._field_from(info, "Commit") == "abc123def")
+check("field: origin", main._field_from(info, "Origin") == "punktfunk-origin")
+check("field: absent", main._field_from(info, "Nope") == "")
+
+# ---- _looks_outdated (the GTK-init signature of a client predating a headless flag) ------
+check("outdated: gtk init noise", main._looks_outdated("cannot open display: \nGtk-WARNING") is True)
+check("outdated: an ordinary error is not", main._looks_outdated("connection refused") is False)
+
+# ---- _semver_tuple (plugin update comparison) --------------------------------------------
+check("semver: plain", main._semver_tuple("1.2.3") == (1, 2, 3))
+check("semver: pre-release suffix dropped", main._semver_tuple("1.2.3-rc1") == (1, 2, 3))
+check("semver: short forms pad", main._semver_tuple("2") == (2, 0, 0))
+check("semver: ordering", main._semver_tuple("0.10.0") > main._semver_tuple("0.9.9"))
+
+# ---- _upsert_configset_entry (Steam Input layout binding) --------------------------------
+#
+# Untested until now, and the riskiest thing that survived the cut: it edits a file holding
+# HUNDREDS of other games' controller bindings, in place. Every assertion below is about not
+# touching them.
+empty = main._upsert_configset_entry("", "punktfunk", "template", "punktfunk.vdf")
+check("vdf: builds the skeleton when the file is new", '"controller_config"' in empty)
+check("vdf: the entry lands", '"punktfunk"' in empty and '"punktfunk.vdf"' in empty)
+
+existing = (
+    '"controller_config"\n'
+    "{\n"
+    '\t"halflife2"\n'
+    "\t{\n"
+    '\t\t"template"\t\t"other.vdf"\n'
+    "\t}\n"
+    "}\n"
 )
-check("audio: junk lines dropped", sinks == [])
-check("audio: blank description falls back to the node name", sources == [
-    {"name": "bare.node", "description": "bare.node"}
-])
+added = main._upsert_configset_entry(existing, "punktfunk", "template", "punktfunk.vdf")
+check("vdf: an existing game's entry survives insertion", '"halflife2"' in added)
+check("vdf: ours is inserted", '"punktfunk"' in added)
+
+# Re-running must REPLACE our block, not accumulate a second one (this runs on every plugin
+# session gated only by a localStorage marker, so idempotence is the whole contract).
+twice = main._upsert_configset_entry(added, "punktfunk", "template", "punktfunk.vdf")
+check("vdf: idempotent", twice.count('"punktfunk"\n') == 1)
+check("vdf: neighbour still intact after the rewrite", '"halflife2"' in twice)
+
+# Steam keys non-Steam games by their LOWERCASE name, and files on disk may carry either case —
+# a case-sensitive match would append a duplicate the game never reads.
+mixed = existing.replace('"halflife2"', '"Punktfunk"')
+replaced = main._upsert_configset_entry(mixed, "punktfunk", "template", "punktfunk.vdf")
+check("vdf: matches an existing key case-insensitively", replaced.count("unktfunk\"\n") == 1)
 
 print()
 if failures:

clients/decky/src/backend.ts

@@ -1,95 +1,94 @@
 // Bridge to the Python backend (main.py) + shared types.
+//
+// Every call here is a thin shell over the headless `punktfunk` CLI, so these types are the
+// CLI's JSON shapes rather than anything this plugin invents. That is deliberate: the plugin
+// used to model the client's stores itself and drifted from them with every field the client
+// added.
+
 import { callable } from "@decky/api";
 
-export interface Host {
-  name: string;
-  host: string;
-  port: number;
-  pair: string; // "required" | "optional" — the HOST's policy
-  fp: string; // host cert SHA-256 fingerprint (lowercase hex) from the mDNS advert
-  proto: string; // advertised protocol, e.g. "punktfunk/1"
-  paired: boolean; // whether THIS device has already PIN-paired this host (by fingerprint)
-  id: string; // the host's stable instance id (mDNS TXT `id`; "" when not advertised)
-  mgmt: number; // management-API port (mDNS TXT `mgmt`; 0 = not advertised → default 47990)
-  os: string; // OS-identity chain (mDNS TXT `os`, e.g. "linux/fedora/bazzite"); "" on older hosts
-}
-
-// One title from a host's game library (the flatpak client's --library TSV, parsed by the
-// backend). `id` is store-qualified (steam:<appid> / custom:<id>) and doubles as the
-// launch handle (PF_LAUNCH → the session Hello).
-export interface GameEntry {
+/** A settings profile as the CLI resolves it — ids are dangling-checked and names attached. */
+export interface Profile {
   id: string;
-  store: string; // "steam" | "custom" | "heroic" | "lutris" | …
-  title: string;
+  name: string;
 }
 
-export interface LibraryResult {
-  ok: boolean;
-  games?: GameEntry[];
-  // "flatpak-not-found" | "timeout" | "not-paired" | "pin-mismatch" | "unreachable" |
-  // "http" | "client-outdated" | "client-error"
-  error?: string;
-  detail?: string; // the client's own one-line reason, for the generic error copy
-}
-
-// A pinned game — a one-tap stream row in the QAM. The host is identified primarily by
-// cert fingerprint (survives IP changes; pairing is fp-keyed too), with the stored
-// address as the launch fallback when the host isn't currently advertising.
-export interface PinnedGame {
-  game_id: string;
-  title: string;
-  store: string;
-  host_fp: string;
-  host_id: string;
-  host_name: string;
-  host: string;
-  port: number;
-  mgmt: number;
-  added_at: number; // unix seconds
-  paired?: boolean; // annotated by get_pins from the client's known-hosts store
-}
-
-export interface PairResult {
-  ok: boolean;
-  fp?: string;
-  error?: string;
-}
-
-// A host in the SHARED saved-hosts store (client-known-hosts.json) — the same file the desktop
-// client reads/writes, so add/rename/pair in either surface shows up in both. `online` comes
-// from a mDNS-INDEPENDENT reachability probe (a Tailscale/VPN host isn't shown offline just
-// because it doesn't advertise); `null` means reachability is unknown (probe skipped or a client
-// too old for `--list-hosts`, which then also can't probe).
-export interface SavedHost {
+/**
+ * A host answering on mDNS right now (`punktfunk discover --json`).
+ *
+ * `saved`/`paired` are annotated BY THE CLI against the saved-hosts store — fingerprint first,
+ * address second. The plugin does not join the two lists itself; that rule living in one place
+ * is what stops this surface disagreeing with the desktop client about the same box.
+ */
+export interface DiscoveredHost {
   name: string;
   addr: string;
   port: number;
-  fp_hex: string; // host cert fingerprint (lowercase hex); "" for a not-yet-paired manual entry
+  fp: string; // advertised cert fingerprint (lowercase hex); "" when not advertised
+  pair: string; // the HOST's policy: "required" | "optional"
+  id: string; // the host's advertised stable id; "" when not advertised
+  mgmt: number; // management-API port; 0 = not advertised
+  os: string; // OS-identity chain, e.g. "linux/fedora/bazzite"; "" on older hosts
+  saved: boolean;
+  paired: boolean;
+}
+
+/**
+ * A host in the shared saved-hosts store (`punktfunk hosts list --probe --json`) — the same
+ * `client-known-hosts.json` the desktop client owns.
+ *
+ * `online` comes from a mDNS-INDEPENDENT probe, so a host reached over Tailscale/VPN is not
+ * shown offline merely because it never advertises; `null` means the probe was skipped.
+ *
+ * `profile` is the host's DEFAULT binding, which a plain connect applies silently. It is not
+ * the same thing as `pinned_profiles`, which are the cards a user chose to surface. Both come
+ * back already resolved against the profile catalog, so this plugin never opens it.
+ */
+export interface SavedHost {
+  id: string | null; // the record's stable id — the reference a launch should use
+  name: string;
+  addr: string;
+  port: number;
+  fp_hex: string; // "" for a placeholder saved by address with no pin yet
   paired: boolean;
   mac: string[];
-  // OS-identity chain learned by the desktop client; optional because the installed
-  // flatpak client may predate the field.
-  os?: string;
+  os: string;
   last_used: number | null;
+  clipboard_sync: boolean;
+  profile: Profile | null;
+  pinned_profiles: Profile[];
   online: boolean | null;
 }
 
-export interface HostsResult {
-  ok: boolean;
-  hosts: SavedHost[];
-  probed: boolean;
-  fallback?: boolean; // true when read straight off disk (client too old for --list-hosts)
-}
-
-// The result of a host-store mutation (add/edit/forget). `error` is a stable code:
-// "client-unavailable" (flatpak missing) | "client-outdated" (client predates the mode) |
-// "unreachable"/"http"/… (from the client) | "client-error" (generic; see `detail`).
-export interface MutationResult {
+/**
+ * Every backend call answers in this shape. `error` is a stable code, never prose:
+ *
+ * - `client-unavailable` — no client is installed, or the call never ran
+ * - `client-outdated`    — the installed client predates the verb (exit 5 + `unknown command`)
+ * - `unreachable`        — the host did not answer
+ * - `refused`            — trust rejected: a wrong PIN, or a fingerprint that already differs
+ * - `needs-pairing`      — the CLI refused because it needs a person
+ * - `unresolved`         — nothing matched what was named
+ * - `client-error`       — anything else; `detail` carries the CLI's own last line
+ */
+export interface CliResult {
   ok: boolean;
   error?: string;
   detail?: string;
 }
 
+export interface DiscoverResult extends CliResult {
+  hosts?: DiscoveredHost[];
+}
+
+export interface HostsResult extends CliResult {
+  hosts?: SavedHost[];
+}
+
+export interface PairResult extends CliResult {
+  fp?: string;
+}
+
 export interface RunnerInfo {
   runner: string; // absolute path to bin/punktfunkrun.sh
   app_id: string; // flatpak app id
@@ -101,99 +100,6 @@ export interface RunnerInfo {
   client_bin?: string;
 }
 
-// The flatpak client's settings JSON — the SAME `client-gtk-settings.json` the desktop client
-// and the console's settings screen own, so a value changed in any of them shows in the others.
-//
-// Every field the client's `Settings` struct persists is modelled here EXCEPT the ones that
-// cannot be answered from a plugin backend or aren't settings at all:
-//   • `forward_pad`   — which physical pad is player 1. Needs SDL's live device list, which only
-//                       the client process has; there is no CLI that enumerates pads.
-//   • `last_window_w/h` — the session's remembered window size, written BY the client, not a
-//                       preference anyone sets.
-// Both round-trip untouched: get_settings returns the whole parsed file, patches are object
-// spreads, and set_settings merges onto what's on disk.
-//
-// Optional (`?`) marks a key the client writes with a serde `default`, so a store written before
-// that key existed simply lacks it. Read those through the same fallback the client uses —
-// `?? true` for the default-on ones, never `!!` — or a pre-existing file reads as "off" here
-// while the stream runs with it on.
-export interface StreamSettings {
-  // ---- Stream mode ----
-  width: number; // 0 = native
-  height: number; // 0 = native
-  refresh_hz: number; // 0 = native
-  render_scale?: number; // render-resolution multiplier; 1.0 = native (absent in pre-scale files)
-  bitrate_kbps: number; // 0 = host default
-  compositor: string; // "auto" | "kwin" | "wlroots" | "mutter" | "gamescope"
-  // Stream mode follows the session window instead of width/height, renegotiating on resize.
-  // Overrides width/height while on; degenerates to the display's native mode on fullscreen.
-  match_window?: boolean;
-
-  // ---- Video ----
-  codec?: string; // "auto" | "hevc" | "h264" | "av1" | "pyrowave" (absent in pre-codec files)
-  decoder?: string; // "auto" | "vulkan" | "vaapi" | "software"
-  hdr_enabled?: boolean; // default ON — advertise 10-bit/HDR10
-  enable_444?: boolean; // default off — ask for full chroma
-  adapter?: string; // decode/present GPU by marketing name; "" = automatic
-
-  // ---- Presentation ----
-  // What the client optimises for when a decoded frame is ready: "latency" | "smooth". Shared
-  // with the Apple and Android clients under this name, so one profile reads the same everywhere.
-  present_priority?: string;
-  smooth_buffer?: number; // frames held back under "smooth"; 0 = Automatic (resolves to 2), else 1–3
-  vsync?: boolean; // default ON — tear-free; off asks for a tearing present mode (best-effort)
-  allow_vrr?: boolean; // default ON — let a VRR panel refresh in step with the stream
-
-  // ---- Audio ----
-  audio_channels?: number; // 2 (stereo) | 6 (5.1) | 8 (7.1)
-  speaker_device?: string; // PipeWire node.name for playback; "" = system default
-  mic_enabled: boolean;
-  mic_device?: string; // PipeWire node.name for capture; "" = system default
-  echo_cancel?: boolean; // default ON; only meaningful while mic_enabled
-
-  // ---- Controllers ----
-  gamepad: string; // "auto" | "xbox360" | "xboxone" | "dualsense" | "dualshock4" | "steamdeck"
-  // Forward this device's controllers at all. Absent in pre-forwarding files, where the
-  // client's own serde default (true) applies — so `?? true` at every read, never `!!`.
-  gamepad_forwarding?: boolean;
-
-  // ---- Touchscreen, mouse & keyboard ----
-  touch_mode?: string; // "trackpad" | "pointer" | "touch"
-  mouse_mode?: string; // "capture" | "desktop"
-  invert_scroll?: boolean;
-  // Whether the session grabs the keyboard so Alt+Tab/Super reach the host.
-  inhibit_shortcuts: boolean;
-
-  // ---- Interface & behaviour ----
-  // Stats-overlay tier: "off" | "compact" | "normal" | "detailed". Absent in a pre-tier file,
-  // which resolves through `show_stats` — read both the way the client's
-  // `Settings::stats_verbosity` does, and write both the way `set_stats_verbosity` does.
-  stats_verbosity?: string;
-  // The legacy on/off the tier supersedes; kept written in sync so a client that predates the
-  // tiers still honours an Off chosen here.
-  show_stats?: boolean;
-  fullscreen_on_stream?: boolean;
-  auto_wake?: boolean; // default ON — Wake-on-LAN a sleeping host before connecting
-  library_enabled?: boolean; // the CLIENT's own library browser (this plugin has its own)
-}
-
-// One audio endpoint from the client's enumeration: the stable id that gets stored, plus the
-// human name to show.
-export interface AudioDevice {
-  name: string; // PipeWire node.name — what `speaker_device` / `mic_device` store
-  description: string; // human label ("Steam Deck Speakers")
-}
-
-// What the device pickers need, read from the session binary (`--list-adapters` / `--list-audio`).
-// `ok: false` = the session binary couldn't be run or failed; every list is then empty and the
-// pickers stay on their stored value rather than pretending the device is gone.
-export interface DeviceLists {
-  ok: boolean;
-  adapters: string[]; // Vulkan physical devices, discrete first
-  sinks: AudioDevice[]; // playback endpoints
-  sources: AudioDevice[]; // capture endpoints
-}
-
 export interface UpdateInfo {
   current: string; // installed PLUGIN version (package.json)
   latest: string; // newest plugin version in our registry for this channel
@@ -229,21 +135,30 @@ export interface ShortcutArt {
   icon_path: string;
 }
 
-export const discover = callable<[], Host[]>("discover");
+// ---- The four CLI shells --------------------------------------------------------------
+
+/** Browse the LAN over mDNS. Bounded by the CLI (3 s) plus a cold-start allowance. */
+export const discover = callable<[], DiscoverResult>("discover");
+/** The saved hosts, probed for reachability, with profiles and pinned cards resolved. */
+export const hosts = callable<[], HostsResult>("hosts");
+/** The PIN ceremony. `refused` = wrong PIN or a host that isn't armed. */
 export const pair = callable<
-  [host: string, port: number, pin: string, name: string],
+  [addr: string, port: number, pin: string, name: string],
   PairResult
 >("pair");
-// Fetch a paired host's game library (headless flatpak --library; can take seconds on a
-// cold client start — show a spinner). Pass fp whenever known so the pin can't degrade.
-export const library = callable<
-  [host: string, mgmt_port: number, fp: string],
-  LibraryResult
->("library");
-export const getPins = callable<[], { pins: PinnedGame[] }>("get_pins");
-export const setPins = callable<[pins: PinnedGame[]], { ok: boolean; error?: string }>(
-  "set_pins",
-);
+/**
+ * Step 1 of request access: save the host with its ADVERTISED fingerprint, pinned but unpaired.
+ * The launch that follows pins the same fingerprint, which is the only thing standing between a
+ * 185 s wait for approval and an impostor answering for the host. Idempotent; a host already
+ * saved under a DIFFERENT fingerprint comes back `refused` rather than being overwritten.
+ */
+export const trustHost = callable<
+  [addr: string, port: number, fp: string, name: string],
+  CliResult
+>("trust_host");
+
+// ---- Steam / plugin business (only a Decky plugin can do these) ------------------------
+
 export const runnerInfo = callable<[], RunnerInfo>("runner_info");
 export const shortcutArt = callable<[], ShortcutArt>("shortcut_art");
 // Install the Steam Input layout (native touchscreen `ts_n` + gamepad passthrough) and point our
@@ -254,48 +169,16 @@ export const applyControllerConfig = callable<
   [name: string],
   { ok: boolean; applied?: string[]; errors?: string[]; accounts?: number; error?: string; detail?: string }
 >("apply_controller_config");
-export const getSettings = callable<[], StreamSettings>("get_settings");
-export const setSettings = callable<[settings: StreamSettings], { ok: boolean }>(
-  "set_settings",
-);
-// GPUs + audio endpoints for the device pickers. Costs a subprocess that initialises Vulkan and
-// PipeWire, so it is called ONCE when the settings tab mounts and never on the launch path.
-export const listDevices = callable<[], DeviceLists>("list_devices");
-// The same, bypassing the backend's cache — for the user who just plugged in a headset.
-export const refreshDevices = callable<[], DeviceLists>("refresh_devices");
 export const killStream = callable<[], { ok: boolean }>("kill_stream");
-// Send a Wake-on-LAN magic packet to a saved host (headless flatpak --wake) so a sleeping host is
-// up by the time the stream connects. The MAC is looked up from the flatpak client's own
-// known-hosts store; `ok: false` (no-op) when none has been learned yet. Fire before launching.
-export const wake = callable<[host: string, port: number], { ok: boolean; error?: string }>(
-  "wake",
+// Whether the streaming client's control socket exists (a stream/console client is up) —
+// gates the QAM panel's host-button section.
+export const streamRunning = callable<[], { running: boolean }>("stream_running");
+// Press a HOST system button on the running stream: "guide" | "qam". The raw Steam/QAM
+// presses stay on the Deck by default (the client's Controllers settings), so this — and
+// holding Select — is how the host's own menus are reached.
+export const hostAction = callable<[action: string], { ok: boolean; error?: string }>(
+  "host_action",
 );
-// ---- Shared saved-hosts store (the SAME client-known-hosts.json the desktop client owns) ----
-// The saved hosts, each annotated with a live (mDNS-independent) `online` probe when `probe` is
-// true. Falls back to a direct JSON read (no reachability) on a client too old for --list-hosts.
-export const listHosts = callable<[probe: boolean], HostsResult>("list_hosts");
-// Save a host by address (survives mDNS-blind networks). `fp` empty = unpaired placeholder to
-// pair next; a later pair replaces it with the fingerprinted entry.
-export const addHost = callable<[target: string, name: string, fp: string], MutationResult>(
-  "add_host",
-);
-// Rename and/or re-point a saved host. `selector` = its fingerprint (survives IP change) or
-// current addr[:port]; empty fields are left untouched.
-export const editHost = callable<
-  [selector: string, name: string, addr: string, port: number],
-  MutationResult
->("edit_host");
-// Remove a saved host by fingerprint or addr[:port] (idempotent).
-export const forgetHost = callable<[selector: string], MutationResult>("forget_host");
-// Reset this device's Punktfunk state (saved hosts + stream settings + pins); KEEPS the client
-// identity so the box isn't seen as new everywhere (re-pairing re-adds hosts).
-export const resetConfig = callable<[], { ok: boolean; error?: string }>("reset_config");
-// Reachability of one host[:port] via the client's mDNS-independent QUIC probe (a "test address"
-// check). `{ ok: true, online }` when determined, else `{ ok: false, error }`.
-export const probeHost = callable<
-  [target: string],
-  { ok: boolean; online?: boolean; error?: string }
->("probe_host");
 export const checkUpdate = callable<[force: boolean], UpdateInfo>("check_update");
 // Update the client by whichever route its install supports: `flatpak update --user` for the
 // flatpak, `punktfunk-client --apply-update` (the packaged root helper) for a one-tap-capable

clients/decky/src/hooks.ts

@@ -1,18 +1,14 @@
-// Shared state hooks + user actions for the QAM panel and the fullscreen page.
+// Shared state hooks + user actions for the QAM panel.
 import { toaster } from "@decky/api";
 import { Navigation } from "@decky/ui";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import {
   checkUpdate,
   discover,
-  GameEntry,
-  getPins,
-  Host,
-  listHosts,
-  PinnedGame,
-  resetConfig,
+  DiscoveredHost,
+  hosts as listHosts,
+  Profile,
   SavedHost,
-  setPins as setPinsBackend,
   updateClient,
   UpdateInfo,
 } from "./backend";
@@ -37,19 +33,191 @@ declare global {
 // PluginInstallType.UPDATE in decky-loader's browser.py (INSTALL=0/REINSTALL=1/UPDATE=2/…).
 const INSTALL_TYPE_UPDATE = 2;
 
+/**
+ * How far this device has got with a host. The three states are what the row says under the
+ * name, and which of them a host is in decides whether pressing it streams or opens the trust
+ * sheet.
+ *
+ * - `paired`       — the host approved this device (a PIN ceremony, or request access).
+ * - `trusted`      — its fingerprint is pinned but nobody has approved us yet. Streams work if
+ *                    the host's policy is `optional`; under `required` the connect parks.
+ * - `needs-access` — no pinned fingerprint. Not streamable until the trust sheet runs.
+ */
+export type TrustState = "paired" | "trusted" | "needs-access";
+
+/**
+ * One host as the panel shows it — the union of the saved store and the live mDNS browse.
+ *
+ * A saved host is ONLINE when it either advertises or answers the reachability probe, so a box
+ * reached over Tailscale/VPN stops reading as offline. Discovered hosts that aren't saved are
+ * appended as extra rows.
+ */
+export interface HostView {
+  name: string;
+  addr: string;
+  port: number;
+  /**
+   * The fingerprint PINNED ON THE RECORD. "" means nothing is pinned, which is exactly what
+   * makes a host unstreamable — the session binary refuses a pinless connect.
+   *
+   * Deliberately NOT filled in from a live advert. A host saved by address that happens to be
+   * advertising right now still has an empty pin on disk, and borrowing the advert's here would
+   * draw it as ready to stream while every launch refused for want of a fingerprint. What the
+   * advert offers is [`advertisedFp`], and moving it onto the record is a trust decision the
+   * user makes in the sheet.
+   */
+  fp: string;
+  /** What the host is advertising right now, if anything — what request access would pin. */
+  advertisedFp: string;
+  /**
+   * The host is answering at an address its record does not carry — it changed DHCP lease.
+   *
+   * This matters because a launch names the host by [`ref`], and the CLI dials whatever address
+   * the RECORD holds. So the row would show the live address and dial the dead one. The record
+   * has to be re-pointed before such a host can stream; `startStream` does it.
+   */
+  moved: boolean;
+  paired: boolean;
+  online: boolean;
+  saved: boolean;
+  /** The advert's policy ("required"|"optional"); "" when the host isn't advertising. */
+  pairPolicy: string;
+  /** OS-identity chain (live advert preferred, else the stored one); "" unknown. */
+  os: string;
+  /**
+   * What a launch should NAME this host by: the record's stable id, which survives renames and
+   * DHCP moves, falling back to `addr:port` for a row that has no record yet (a discovered host
+   * the trust sheet is about to save, or a client too old to have minted ids).
+   */
+  ref: string;
+  /** The host's default profile binding — applied silently by a plain connect, not a card. */
+  profile: Profile | null;
+  /** The cards to render nested under this host; already resolved against the catalog. */
+  pinnedProfiles: Profile[];
+  lastUsed: number | null;
+}
+
+export function trustState(v: HostView): TrustState {
+  if (v.paired) return "paired";
+  return v.fp ? "trusted" : "needs-access";
+}
+
+/**
+ * Must this host go through the trust sheet before it can stream?
+ *
+ * A pinned fingerprint is the ONLY rule. The session binary refuses a pinless connect, so a row
+ * without one can offer nothing but a button that fails; with one, the connect is verified and
+ * the host either admits it or parks it for an operator. The old rule also consulted the
+ * advertised policy for unsaved hosts, which made the answer depend on which of two lists a row
+ * came from — the same box could read differently before and after being saved.
+ */
+export function needsPair(v: HostView): boolean {
+  return v.fp === "";
+}
+
+function advertMatchesSaved(a: DiscoveredHost, s: SavedHost): boolean {
+  return (
+    (!!s.fp_hex && !!a.fp && s.fp_hex.toLowerCase() === a.fp.toLowerCase()) ||
+    (s.addr === a.addr && s.port === a.port)
+  );
+}
+
+/**
+ * Join the saved store and the live browse into the rows the panel draws.
+ *
+ * Fingerprint first, address second — a host that moved DHCP lease still matches its record,
+ * and a different box that inherited the old address does not inherit its pairing. The CLI's
+ * `discover` annotates `saved`/`paired` by exactly this rule too, so the two can't disagree.
+ */
+export function mergeHosts(saved: SavedHost[], discovered: DiscoveredHost[]): HostView[] {
+  const views: HostView[] = saved.map((s) => {
+    // Prefer a live advert's address: the host may have moved since it was last saved.
+    const advert = discovered.find((a) => advertMatchesSaved(a, s));
+    return {
+      name: s.name || s.addr,
+      addr: advert?.addr ?? s.addr,
+      port: advert?.port ?? s.port,
+      fp: s.fp_hex,
+      advertisedFp: advert?.fp ?? "",
+      moved: !!advert && (advert.addr !== s.addr || advert.port !== s.port),
+      paired: s.paired,
+      online: !!advert || s.online === true,
+      saved: true,
+      pairPolicy: advert?.pair ?? "",
+      os: advert?.os || s.os || "",
+      ref: s.id || `${advert?.addr ?? s.addr}:${advert?.port ?? s.port}`,
+      profile: s.profile,
+      pinnedProfiles: s.pinned_profiles ?? [],
+      lastUsed: s.last_used,
+    };
+  });
+  for (const a of discovered) {
+    if (saved.some((s) => advertMatchesSaved(a, s))) {
+      continue; // already rendered as its saved row, with a live pip
+    }
+    views.push({
+      name: a.name,
+      addr: a.addr,
+      port: a.port,
+      // No record, so nothing is pinned — whatever it advertises is an OFFER, not a pin.
+      fp: "",
+      advertisedFp: a.fp,
+      moved: false, // no record, so nothing to be stale
+      paired: a.paired,
+      online: true,
+      saved: false,
+      pairPolicy: a.pair,
+      os: a.os,
+      ref: `${a.addr}:${a.port}`,
+      profile: null,
+      pinnedProfiles: [],
+      lastUsed: null,
+    });
+  }
+  return views.sort(sortRows);
+}
+
+/**
+ * Online first, then most recently used, then by name. The host you streamed last night should
+ * be the first thing under your thumb; a host that is off right now should never be.
+ */
+function sortRows(a: HostView, b: HostView): number {
+  if (a.online !== b.online) return a.online ? -1 : 1;
+  if ((a.lastUsed ?? 0) !== (b.lastUsed ?? 0)) return (b.lastUsed ?? 0) - (a.lastUsed ?? 0);
+  return a.name.localeCompare(b.name);
+}
+
 // ----------------------------------------------------------------------------------------
-// Discovery — mDNS scan state shared by the QAM panel and the full page.
+// Hosts — ONE call site for both lists. They were separate hooks when the plugin had two
+// views mounting them independently; the panel is the only view now, and merging them means
+// the "scanning" state covers the whole row set rather than half of it flickering in first.
 // ----------------------------------------------------------------------------------------
 export function useHosts() {
-  const [hosts, setHosts] = useState<Host[]>([]);
+  const [views, setViews] = useState<HostView[]>([]);
   const [scanning, setScanning] = useState(false);
+  // Why the list is empty, when it is empty for a reason other than an empty LAN. Rendering
+  // either of these as "No hosts yet" would blame the user's network for the plugin's problem:
+  //   "client-outdated"    — the installed client predates `punktfunk discover`
+  //   "client-unavailable" — there is no client installed at all
+  const [problem, setProblem] = useState<string | null>(null);
 
   const refresh = useCallback(async () => {
     setScanning(true);
     try {
-      setHosts(await discover());
+      // Both in flight at once: the browse is time-bounded and the probe is network-bound, so
+      // running them in sequence would cost the sum of two waits for no benefit.
+      const [d, s] = await Promise.all([discover(), listHosts()]);
+      // Both calls run the same binary, so they fail the same way; take whichever answered.
+      setProblem(
+        d.error === "client-unavailable" || s.error === "client-unavailable"
+          ? "client-unavailable"
+          : d.error === "client-outdated" || s.error === "client-outdated"
+            ? "client-outdated"
+            : null,
+      );
+      setViews(mergeHosts(s.hosts ?? [], d.hosts ?? []));
     } catch (e) {
-      toaster.toast({ title: "Punktfunk", body: `Discovery failed: ${e}` });
+      toaster.toast({ title: "Punktfunk", body: `Couldn't list hosts: ${e}` });
     } finally {
       setScanning(false);
     }
@@ -59,157 +227,7 @@ export function useHosts() {
     void refresh();
   }, [refresh]);
 
-  return { hosts, scanning, refresh };
-}
-
-// ----------------------------------------------------------------------------------------
-// Saved hosts — the SHARED known-hosts store (client-known-hosts.json), the same file the
-// desktop client reads/writes. Fetched WITH a reachability probe so a host reached over a
-// routed network (Tailscale/VPN) reports online without ever appearing on mDNS.
-// ----------------------------------------------------------------------------------------
-export function useSavedHosts() {
-  const [saved, setSaved] = useState<SavedHost[]>([]);
-  const [loading, setLoading] = useState(false);
-
-  const refresh = useCallback(async () => {
-    setLoading(true);
-    try {
-      const r = await listHosts(true);
-      setSaved(r.hosts ?? []);
-    } catch {
-      /* backend unavailable — keep the current view */
-    } finally {
-      setLoading(false);
-    }
-  }, []);
-
-  useEffect(() => {
-    void refresh();
-  }, [refresh]);
-
-  return { saved, loading, refresh };
-}
-
-/**
- * One host as the UI shows it — the union of the saved store and the live mDNS scan. A saved
- * host is ONLINE when it either advertises on mDNS OR answers the reachability probe (so
- * mDNS-blind-but-reachable hosts stop reading as offline). Discovered hosts not in the store
- * are appended as unsaved rows.
- */
-export interface HostView {
-  name: string;
-  addr: string;
-  port: number;
-  fp: string; // "" for a saved-but-unpaired placeholder
-  paired: boolean; // PIN-paired specifically (a TOFU host has fp but paired=false)
-  online: boolean;
-  saved: boolean; // present in the known-hosts store
-  pairPolicy: string; // the advert's policy ("required"|"optional"), "" when not advertising
-  mgmt: number; // advertised mgmt-API port (0 = not advertised → default)
-  id: string; // advertised stable host id ("" when not advertising)
-  os: string; // OS-identity chain (live advert preferred, else the stored one); "" unknown
-}
-
-function advertMatchesSaved(a: Host, s: SavedHost): boolean {
-  return (
-    (!!s.fp_hex && !!a.fp && s.fp_hex.toLowerCase() === a.fp.toLowerCase()) ||
-    (s.addr === a.host && s.port === a.port)
-  );
-}
-
-export function mergeHosts(saved: SavedHost[], discovered: Host[]): HostView[] {
-  const views: HostView[] = saved.map((s) => {
-    // Prefer a live advert's address (a host may have moved DHCP leases since it was saved).
-    const advert = discovered.find((a) => advertMatchesSaved(a, s));
-    return {
-      name: s.name || s.addr,
-      addr: advert?.host ?? s.addr,
-      port: advert?.port ?? s.port,
-      fp: s.fp_hex || advert?.fp || "",
-      paired: s.paired,
-      online: !!advert || s.online === true,
-      saved: true,
-      pairPolicy: advert?.pair ?? "",
-      mgmt: advert?.mgmt ?? 0,
-      id: advert?.id ?? "",
-      os: advert?.os || s.os || "",
-    };
-  });
-  for (const a of discovered) {
-    if (saved.some((s) => advertMatchesSaved(a, s))) {
-      continue; // already rendered as its saved card (with a live pip)
-    }
-    views.push({
-      name: a.name,
-      addr: a.host,
-      port: a.port,
-      fp: a.fp,
-      paired: a.paired,
-      online: true,
-      saved: false,
-      pairPolicy: a.pair,
-      mgmt: a.mgmt,
-      id: a.id,
-      os: a.os,
-    });
-  }
-  return views;
-}
-
-/**
- * True when this host must be paired before it can stream. A saved host is streamable once it
- * has a pinned fingerprint (PIN-paired OR TOFU-trusted); a saved placeholder (no fp yet) must be
- * paired. For an unsaved discovered host we keep the advertised-policy rule the UI always used.
- */
-export function needsPair(v: HostView): boolean {
-  return v.saved ? v.fp === "" : v.pairPolicy === "required" && !v.paired;
-}
-
-/** Adapt a merged view back into the `Host` shape the pair/library/stream helpers consume. */
-export function toHost(v: HostView): Host {
-  return {
-    name: v.name,
-    host: v.addr,
-    port: v.port,
-    pair: v.pairPolicy || (needsPair(v) ? "required" : "optional"),
-    fp: v.fp,
-    proto: "",
-    paired: v.paired,
-    id: v.id,
-    mgmt: v.mgmt,
-    os: v.os,
-  };
-}
-
-/** Is a pinned game's host currently online, considering BOTH the live scan and saved probe? */
-export function pinIsOnline(pin: PinnedGame, views: HostView[]): boolean {
-  const fp = pin.host_fp.toLowerCase();
-  return views.some(
-    (v) =>
-      v.online &&
-      ((!!fp && v.fp.toLowerCase() === fp) ||
-        (!!pin.host_id && v.id === pin.host_id) ||
-        (v.addr === pin.host && v.port === pin.port)),
-  );
-}
-
-/**
- * Reset all Punktfunk state (saved hosts + stream settings + pins), keeping the client identity.
- * Refreshes whatever views are passed so the UI clears immediately. Ends in a toast.
- */
-export async function resetAll(refreshers: Array<() => void | Promise<void>>): Promise<void> {
-  try {
-    const r = await resetConfig();
-    for (const fn of refreshers) void fn();
-    toaster.toast({
-      title: "Punktfunk",
-      body: r.ok
-        ? "Reset — saved hosts, settings, and pins cleared."
-        : `Reset failed${r.error ? ` (${r.error})` : ""}.`,
-    });
-  } catch {
-    toaster.toast({ title: "Punktfunk", body: "Reset failed." });
-  }
+  return { views, scanning, problem, refresh };
 }
 
 // ----------------------------------------------------------------------------------------
@@ -260,36 +278,6 @@ export function clientUpdateIsOneTap(info: UpdateInfo | null | undefined): boole
   );
 }
 
-/**
- * How the client got onto this box, in words a Deck user recognises. The raw kind comes from
- * the client's own detector (`pf_update_check::detect`); anything unmapped falls through as
- * itself rather than as "unknown", because the raw word is still more useful than a shrug.
- */
-export function clientInstallLabel(kind: string): string {
-  switch (kind) {
-    case "flatpak":
-      return "Flatpak (per-user)";
-    case "apt":
-      return "System package (apt)";
-    case "dnf":
-      return "System package (dnf)";
-    case "rpm-ostree":
-      return "Layered package (rpm-ostree)";
-    case "pacman":
-      return "System package (pacman)";
-    case "sysext":
-      return "System extension (sysext)";
-    case "nix":
-      return "Nix profile";
-    case "steamos-source":
-      return "On-device build";
-    case "source":
-      return "Built from source";
-    default:
-      return kind;
-  }
-}
-
 /** True when the only pending update is one this Deck can't apply itself. */
 export function clientUpdateIsManualOnly(info: UpdateInfo | null | undefined): boolean {
   return !!info && info.client_update_available && !clientUpdateIsOneTap(info);
@@ -427,167 +415,26 @@ export async function applyUpdate(
 }
 
 // ----------------------------------------------------------------------------------------
-// Stream launch — via the hidden Steam shortcut (see steam.ts for why).
+// Stream launch — via the hidden Steam shortcut (see steam.ts for why it can't be direct).
 // ----------------------------------------------------------------------------------------
+
+/**
+ * Stream this host. `opts.profileId` streams one of its pinned cards; `opts.requestAccess`
+ * runs the supervised launch that waits for the host's operator to approve this Deck.
+ *
+ * The host is named by REFERENCE (`v.ref`), never by value — no resolution, bitrate or codec
+ * ever rides the launch path, which is the same rule the deep-link grammar enforces.
+ */
 export async function startStream(
-  h: Host,
+  v: HostView,
   opts: LaunchOpts = {},
   label?: string,
 ): Promise<void> {
   try {
-    await launchStream(h.host, h.port, opts);
+    await launchStream(v.ref, opts);
     Navigation.CloseSideMenus();
-    toaster.toast({ title: "Punktfunk", body: `Starting ${label ?? "stream"} — ${h.name}` });
+    toaster.toast({ title: "Punktfunk", body: `Starting ${label ?? "stream"} — ${v.name}` });
   } catch (e) {
     toaster.toast({ title: "Punktfunk", body: `Launch failed: ${e}` });
   }
 }
-
-/** Open the GTK client's gamepad library launcher for a host (`--browse` via PF_BROWSE). */
-export async function startBrowse(h: Host): Promise<void> {
-  try {
-    await launchStream(h.host, h.port, { browse: true, mgmt: h.mgmt });
-    Navigation.CloseSideMenus();
-    toaster.toast({ title: "Punktfunk", body: `Opening library — ${h.name}` });
-  } catch (e) {
-    toaster.toast({ title: "Punktfunk", body: `Launch failed: ${e}` });
-  }
-}
-
-// ----------------------------------------------------------------------------------------
-// Pinned games — the QAM's one-tap game rows, persisted by the backend next to the
-// client's config (survives plugin reinstalls).
-// ----------------------------------------------------------------------------------------
-export interface PinsApi {
-  pins: PinnedGame[];
-  addPin: (h: Host, g: GameEntry) => void;
-  removePin: (hostFp: string, gameId: string) => void;
-  isPinned: (hostFp: string, gameId: string) => boolean;
-  /** Refresh a pin's stored address from a live advert (hosts change IPs). */
-  updatePinHost: (pin: PinnedGame, h: Host) => void;
-  refresh: () => Promise<void>;
-}
-
-export function usePins(): PinsApi {
-  const [pins, setPins] = useState<PinnedGame[]>([]);
-  // A live mirror of `pins`. The Games picker is mounted by Decky's `showModal` into a
-  // detached portal that captures this hook's callbacks ONCE and never re-renders with fresh
-  // props, so a mutator closing over the `pins` array reads a frozen base — pinning a second
-  // game in the same session would compute from the stale `[]` and clobber the first (silent
-  // data loss). Reading the ref keeps every mutation based on the current set, and lets the
-  // callbacks keep a stable identity (deps free of `pins`).
-  const pinsRef = useRef<PinnedGame[]>([]);
-  pinsRef.current = pins;
-
-  const refresh = useCallback(async () => {
-    try {
-      setPins((await getPins()).pins);
-    } catch {
-      /* backend unavailable — keep the current view */
-    }
-  }, []);
-
-  useEffect(() => {
-    void refresh();
-  }, [refresh]);
-
-  // Optimistic local state; the backend validates/dedups and is re-read on failure.
-  const save = useCallback(
-    (next: PinnedGame[]) => {
-      pinsRef.current = next;
-      setPins(next);
-      setPinsBackend(next).catch(() => void refresh());
-    },
-    [refresh],
-  );
-
-  const addPin = useCallback(
-    (h: Host, g: GameEntry) => {
-      const pin: PinnedGame = {
-        game_id: g.id,
-        title: g.title,
-        store: g.store,
-        host_fp: h.fp,
-        host_id: h.id,
-        host_name: h.name,
-        host: h.host,
-        port: h.port,
-        mgmt: h.mgmt,
-        added_at: Math.floor(Date.now() / 1000),
-        paired: h.paired,
-      };
-      save([
-        ...pinsRef.current.filter(
-          (p) => !(p.host_fp === pin.host_fp && p.game_id === pin.game_id),
-        ),
-        pin,
-      ]);
-    },
-    [save],
-  );
-
-  const removePin = useCallback(
-    (hostFp: string, gameId: string) => {
-      save(pinsRef.current.filter((p) => !(p.host_fp === hostFp && p.game_id === gameId)));
-    },
-    [save],
-  );
-
-  const isPinned = useCallback(
-    (hostFp: string, gameId: string) =>
-      pins.some((p) => p.host_fp === hostFp && p.game_id === gameId),
-    [pins],
-  );
-
-  const updatePinHost = useCallback(
-    (pin: PinnedGame, h: Host) => {
-      if (pin.host === h.host && pin.port === h.port && pin.mgmt === h.mgmt) {
-        return;
-      }
-      save(
-        pinsRef.current.map((p) =>
-          p.host_fp === pin.host_fp && p.game_id === pin.game_id
-            ? { ...p, host: h.host, port: h.port, mgmt: h.mgmt, host_name: h.name }
-            : p,
-        ),
-      );
-    },
-    [save],
-  );
-
-  return { pins, addPin, removePin, isPinned, updatePinHost, refresh };
-}
-
-/**
- * The host a pin should launch against right now: match the live mDNS scan by cert
- * fingerprint first (pairing is fp-keyed, survives IP changes), then by the host's stable
- * id, else fall back to the stored address (host offline or scan flaky — still launch).
- */
-export function resolvePinHost(
-  pin: PinnedGame,
-  live: Host[],
-): { host: Host; online: boolean } {
-  const fp = pin.host_fp.toLowerCase();
-  const match =
-    (fp && live.find((h) => h.fp && h.fp.toLowerCase() === fp)) ||
-    (pin.host_id && live.find((h) => h.id && h.id === pin.host_id)) ||
-    undefined;
-  if (match) {
-    return { host: match, online: true };
-  }
-  return {
-    host: {
-      name: pin.host_name || pin.host,
-      host: pin.host,
-      port: pin.port,
-      pair: pin.paired ? "optional" : "required",
-      fp: pin.host_fp,
-      proto: "",
-      paired: !!pin.paired,
-      id: pin.host_id,
-      mgmt: pin.mgmt,
-      os: "", // pins don't store the chain; the icon is a hosts-tab affordance
-    },
-    online: false,
-  };
-}

clients/decky/src/hostmgmt.tsx

@@ -1,164 +0,0 @@
-// Add / edit host dialogs for the fullscreen page. These mutate the SHARED known-hosts store
-// (client-known-hosts.json) through the flatpak client's headless modes, so a host saved or
-// renamed here shows up in the desktop client too. Text entry uses @decky/ui's TextField, which
-// brings up Steam's on-screen keyboard on focus (the digit-grid trick in pair.tsx is only needed
-// for the numeric PIN).
-import { DialogButton, Focusable, ModalRoot, Spinner, TextField } from "@decky/ui";
-import { toaster } from "@decky/api";
-import { ChangeEvent, FC, useState } from "react";
-import { addHost, editHost, MutationResult } from "./backend";
-import { HostView } from "./hooks";
-import { actionButton } from "./ui";
-
-/** Stable copy for a failed host-store mutation. */
-export function mutationError(r: MutationResult): string {
-  switch (r.error) {
-    case "client-unavailable":
-      return "The Punktfunk client isn't installed (flatpak io.unom.Punktfunk).";
-    case "client-outdated":
-      return "The installed client is too old for host management — update it from the About tab.";
-    default:
-      return r.detail || "Couldn't save the host.";
-  }
-}
-
-// Split a typed address: a pasted `host:port` wins over the separate port field. IPv6 literals
-// aren't supported by the host advert/known-hosts format, so a bare colon is treated as host:port.
-function targetFrom(addr: string, port: string): string {
-  const a = addr.trim();
-  if (a.includes(":")) {
-    return a;
-  }
-  const p = port.trim() || "9777";
-  return `${a}:${p}`;
-}
-
-const field: React.CSSProperties = { marginBottom: "0.8em" };
-
-const HostForm: FC<{
-  title: string;
-  submitLabel: string;
-  initial: { addr: string; port: string; name: string };
-  addrDisabled?: boolean;
-  onSubmit: (addr: string, port: string, name: string) => Promise<MutationResult>;
-  onDone: () => void;
-  closeModal?: () => void;
-}> = ({ title, submitLabel, initial, addrDisabled, onSubmit, onDone, closeModal }) => {
-  const [addr, setAddr] = useState(initial.addr);
-  const [port, setPort] = useState(initial.port);
-  const [name, setName] = useState(initial.name);
-  const [busy, setBusy] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-
-  const submit = async () => {
-    if (!addr.trim()) {
-      setError("Enter an address.");
-      return;
-    }
-    setBusy(true);
-    setError(null);
-    try {
-      const r = await onSubmit(addr.trim(), port.trim(), name.trim());
-      if (r.ok) {
-        onDone();
-        closeModal?.();
-      } else {
-        setError(mutationError(r));
-      }
-    } catch (e) {
-      setError(String(e));
-    } finally {
-      setBusy(false);
-    }
-  };
-
-  return (
-    <ModalRoot closeModal={closeModal}>
-      <div style={{ fontWeight: "bold", fontSize: "1.3em", marginBottom: "0.6em" }}>{title}</div>
-      <div style={field}>
-        <TextField
-          label="Address"
-          description="IP or hostname (a Tailscale/VPN name works too). Add :port to override."
-          value={addr}
-          disabled={addrDisabled || busy}
-          onChange={(e: ChangeEvent<HTMLInputElement>) => setAddr(e.target.value)}
-        />
-      </div>
-      <div style={field}>
-        <TextField
-          label="Port"
-          value={port}
-          mustBeNumeric
-          disabled={busy}
-          onChange={(e: ChangeEvent<HTMLInputElement>) => setPort(e.target.value)}
-        />
-      </div>
-      <div style={field}>
-        <TextField
-          label="Name (optional)"
-          value={name}
-          disabled={busy}
-          onChange={(e: ChangeEvent<HTMLInputElement>) => setName(e.target.value)}
-        />
-      </div>
-      {error && (
-        <div style={{ color: "#ff6b6b", marginBottom: "0.6em" }}>{error}</div>
-      )}
-      <Focusable style={{ display: "flex", gap: "0.5em", justifyContent: "flex-end" }}>
-        <DialogButton style={actionButton} disabled={busy} onClick={() => closeModal?.()}>
-          Cancel
-        </DialogButton>
-        <DialogButton style={actionButton} disabled={busy} onClick={submit}>
-          {busy ? <Spinner style={{ height: "1em" }} /> : submitLabel}
-        </DialogButton>
-      </Focusable>
-    </ModalRoot>
-  );
-};
-
-/** "+" — save a new host by address (unpaired placeholder; the user pairs it next). */
-export const AddHostModal: FC<{ onDone: () => void; closeModal?: () => void }> = ({
-  onDone,
-  closeModal,
-}) => (
-  <HostForm
-    title="Add host"
-    submitLabel="Add"
-    initial={{ addr: "", port: "9777", name: "" }}
-    onSubmit={async (addr, port, name) => {
-      const r = await addHost(targetFrom(addr, port), name, "");
-      if (r.ok) {
-        toaster.toast({ title: "Punktfunk", body: `Added ${name || addr}` });
-      }
-      return r;
-    }}
-    onDone={onDone}
-    closeModal={closeModal}
-  />
-);
-
-/** Rename / re-point a saved host. Identified by fingerprint when it has one (survives IP
- *  changes), else by its current address. */
-export const EditHostModal: FC<{
-  host: HostView;
-  onDone: () => void;
-  closeModal?: () => void;
-}> = ({ host, onDone, closeModal }) => {
-  const selector = host.fp || `${host.addr}:${host.port}`;
-  return (
-    <HostForm
-      title={`Edit ${host.name}`}
-      submitLabel="Save"
-      initial={{ addr: host.addr, port: String(host.port), name: host.name }}
-      onSubmit={async (addr, port, name) => {
-        const r = await editHost(selector, name, addr, parseInt(port, 10) || 0);
-        if (r.ok) {
-          toaster.toast({ title: "Punktfunk", body: `Updated ${name || addr}` });
-        }
-        return r;
-      }}
-      onDone={onDone}
-      closeModal={closeModal}
-    />
-  );
-};

clients/decky/src/index.tsx

@@ -1,5 +1,10 @@
-// Plugin entry: the Quick Access Menu panel + route registration. The fullscreen page lives
-// in page.tsx; shared hooks/actions in hooks.ts; the Steam-shortcut launch in steam.ts.
+// Plugin entry: the Quick Access Menu panel. That is the whole plugin now — the fullscreen
+// route, the settings screen, the host editor and the games picker are gone, because the
+// client's own console home does all four one shortcut away (and is gamepad-navigable, which
+// a QAM panel re-implementing them never quite was).
+//
+// What is left is what only a Decky plugin can do: start a stream through Steam so gamescope
+// focuses it (see steam.ts), and stand in front of the trust decision that gates it.
 import {
   ButtonItem,
   Field,
@@ -10,37 +15,35 @@ import {
   showModal,
   staticClasses,
 } from "@decky/ui";
-import { definePlugin, routerHook, toaster } from "@decky/api";
-import { FC } from "react";
+import { definePlugin, toaster } from "@decky/api";
+import { FC, useEffect, useState } from "react";
 import {
   FaDownload,
+  FaGamepad,
   FaLock,
-  FaLockOpen,
   FaPlay,
   FaPlus,
+  FaStopCircle,
   FaSyncAlt,
   FaTv,
 } from "react-icons/fa";
+import { hostAction, killStream, streamRunning } from "./backend";
 import { PluginErrorBoundary } from "./boundary";
 import {
   applyUpdate,
   checkForUpdatesNow,
   clientUpdateIsManualOnly,
   hasUpdate,
-  mergeHosts,
+  HostView,
   needsPair,
-  pinIsOnline,
   startStream,
-  toHost,
+  trustState,
   useHosts,
-  usePins,
-  useSavedHosts,
   useUpdate,
 } from "./hooks";
-import { streamPin } from "./library";
-import { PunktfunkRoute, ROUTE } from "./page";
-import { PairModal } from "./pair";
-import { ensureGamepadUiShortcut, recreateShortcuts } from "./steam";
+import { OsMark } from "./os-icon";
+import { ensureGamepadUiShortcut, launchGamepadUi, recreateShortcuts, stopStream } from "./steam";
+import { TrustSheet } from "./trust";
 
 // Recovery action for "the Punktfunk library entry vanished" — recreates the visible shortcut.
 // Deleting the shortcut (optionally + reinstalling the plugin) leaves a stale appId in Steam's
@@ -54,22 +57,106 @@ async function recreatePunktfunkShortcut(): Promise<void> {
   });
 }
 
-// ----------------------------------------------------------------------------------------
-// QAM panel — quick status + entry into the full page + one-tap stream for known hosts
-// and pinned games.
-// ----------------------------------------------------------------------------------------
-const QamPanel: FC = () => {
-  const { hosts: discovered, scanning, refresh: refreshDiscovered } = useHosts();
-  const { saved, loading: loadingSaved, refresh: refreshSaved } = useSavedHosts();
-  const { info: update, checking, check } = useUpdate();
-  const pins = usePins();
+/** Force-stop a wedged stream: end Steam's "game", then make sure the client itself is gone. */
+async function forceStop(): Promise<void> {
+  stopStream();
+  try {
+    await killStream();
+  } catch {
+    /* best-effort — the TerminateApp above is usually enough */
+  }
+  toaster.toast({ title: "Punktfunk", body: "Stopped the stream" });
+}
 
-  const hosts = mergeHosts(saved, discovered);
-  const busy = scanning || loadingSaved;
-  const refresh = () => {
-    void refreshDiscovered();
-    void refreshSaved();
-  };
+// Press a host system button (guide/QAM) on the running stream, then hand the screen back
+// to it — closing the local menus is what lets the HOST's overlay show through. The raw
+// Steam/··· presses stay on the Deck by default (both overlays would open at once), so this
+// is the panel route to the host's menus; holding Select is the controller route.
+async function pressHost(action: "guide" | "qam"): Promise<void> {
+  const r = await hostAction(action).catch(() => ({ ok: false as const, error: "backend" }));
+  if (r.ok) {
+    Navigation.CloseSideMenus();
+  } else {
+    toaster.toast({
+      title: "Punktfunk",
+      body: r.error === "no-stream" ? "No stream is running" : "Couldn't reach the stream",
+    });
+  }
+}
+
+/** The line under a host's name: where it is, whether it's up, and how far trust has got. */
+function hostDescription(v: HostView): string {
+  const trust = {
+    paired: "paired",
+    trusted: "trusted",
+    "needs-access": "needs access",
+  }[trustState(v)];
+  return `${v.addr}:${v.port} · ${v.online ? "online" : "offline"} · ${trust}`;
+}
+
+const HostRow: FC<{ host: HostView; refresh: () => void }> = ({ host, refresh }) => {
+  const gated = needsPair(host);
+  const stream = (opts: { requestAccess?: boolean } = {}) => void startStream(host, opts);
+  return (
+    <>
+      <PanelSectionRow>
+        <ButtonItem
+          layout="below"
+          onClick={() =>
+            gated
+              ? showModal(
+                  <TrustSheet host={host} onStream={stream} onChanged={refresh} />,
+                )
+              : stream()
+          }
+          label={
+            <span style={{ display: "inline-flex", alignItems: "center", gap: "0.4em" }}>
+              {gated ? <FaLock /> : <OsMark os={host.os} />}
+              {host.name}
+            </span>
+          }
+          description={hostDescription(host)}
+        >
+          {gated ? "Connect…" : "Stream"}
+        </ButtonItem>
+      </PanelSectionRow>
+      {/* Pinned cards, nested under their host rather than in a section of their own: a card
+          IS a (host, profile) pair, and a row that floats free of its host is the "a pinned
+          tile reads as a duplicate host" problem the desktop shells still have. The host's
+          own BOUND profile is deliberately not a card — it applies silently on the plain row
+          above, and showing it twice would suggest they do different things. */}
+      {!gated &&
+        host.pinnedProfiles.map((p) => (
+          <PanelSectionRow key={`${host.ref}:${p.id}`}>
+            <ButtonItem
+              layout="below"
+              onClick={() => void startStream(host, { profileId: p.id }, `“${p.name}”`)}
+              label={`▸ ${p.name}`}
+            >
+              <FaPlay style={{ marginRight: "0.5em" }} />
+              Stream
+            </ButtonItem>
+          </PanelSectionRow>
+        ))}
+    </>
+  );
+};
+
+const QamPanel: FC = () => {
+  const { views, scanning, problem, refresh } = useHosts();
+  const { info: update, checking, check } = useUpdate();
+  // The host-buttons section shows only while the streaming client is up (checked per
+  // panel open — the QAM panel mounts fresh each time).
+  const [streaming, setStreaming] = useState(false);
+  useEffect(() => {
+    let live = true;
+    void streamRunning()
+      .then((r) => live && setStreaming(r.running))
+      .catch(() => {});
+    return () => {
+      live = false;
+    };
+  }, []);
 
   return (
     <>
@@ -110,15 +197,62 @@ const QamPanel: FC = () => {
           </PanelSection>
         ))}
 
+      <PanelSection title="Hosts">
+        <PanelSectionRow>
+          <ButtonItem layout="below" onClick={() => void refresh()} disabled={scanning}>
+            {scanning ? (
+              <Spinner style={{ height: "1em", marginRight: "0.5em" }} />
+            ) : (
+              <FaSyncAlt style={{ marginRight: "0.5em" }} />
+            )}
+            {scanning ? "Scanning…" : "Refresh"}
+          </ButtonItem>
+        </PanelSectionRow>
+        {/* A client that is missing or too old explains itself rather than rendering an empty
+            list — "no hosts on your LAN" would blame the network for the plugin's problem, and
+            for the outdated case the button that fixes it is in this same panel. */}
+        {problem && (
+          <PanelSectionRow>
+            <Field
+              focusable={false}
+              label={
+                problem === "client-unavailable"
+                  ? "Punktfunk isn’t installed"
+                  : "Update the Punktfunk client"
+              }
+              description={
+                problem === "client-unavailable"
+                  ? "This panel launches the Punktfunk app, which isn’t on this Deck yet. Install it in Desktop Mode."
+                  : "This client is too old to find hosts on your network. Saved hosts still work."
+              }
+            />
+          </PanelSectionRow>
+        )}
+        {views.length === 0 && scanning && (
+          <PanelSectionRow>
+            <Field focusable={false} description="Scanning your network…" />
+          </PanelSectionRow>
+        )}
+        {views.length === 0 && !scanning && !problem && (
+          <PanelSectionRow>
+            <Field
+              focusable={false}
+              label="No hosts yet"
+              description="Open Punktfunk to find and pair one."
+            />
+          </PanelSectionRow>
+        )}
+        {views.map((v) => (
+          <HostRow key={v.ref} host={v} refresh={refresh} />
+        ))}
+      </PanelSection>
+
       <PanelSection title="Punktfunk">
         <PanelSectionRow>
           <ButtonItem
             layout="below"
-            description="Host details, stream settings, and help"
-            onClick={() => {
-              Navigation.Navigate(ROUTE);
-              Navigation.CloseSideMenus();
-            }}
+            description="Settings, adding a host by address, and browsing a host's games all live here."
+            onClick={() => void launchGamepadUi()}
           >
             <FaTv style={{ marginRight: "0.5em" }} />
             Open Punktfunk
@@ -126,85 +260,31 @@ const QamPanel: FC = () => {
         </PanelSectionRow>
       </PanelSection>
 
-      {/* Pinned games — the "jump straight into Playnite" rows. Pin games from a host's
-          picker (fullscreen page → host row → games button). */}
-      {pins.pins.length > 0 && (
-        <PanelSection title="Pinned Games">
-          {pins.pins.map((pin) => {
-            const online = pinIsOnline(pin, hosts);
-            return (
-              <PanelSectionRow key={`${pin.host_fp}:${pin.game_id}`}>
-                <ButtonItem
-                  layout="below"
-                  onClick={() => streamPin(pin, hosts.map(toHost), pins)}
-                  label={pin.title}
-                  description={`${pin.host_name}${online ? "" : " · offline?"}${
-                    pin.paired ? "" : " · pairing required"
-                  }`}
-                >
-                  <FaPlay style={{ marginRight: "0.5em" }} />
-                  Stream
-                </ButtonItem>
-              </PanelSectionRow>
-            );
-          })}
+      {streaming && (
+        <PanelSection title="Host menus">
+          <PanelSectionRow>
+            <ButtonItem
+              layout="below"
+              description="Press the Steam/guide button on the host"
+              onClick={() => void pressHost("guide")}
+            >
+              <FaGamepad style={{ marginRight: "0.5em" }} />
+              Steam menu on host
+            </ButtonItem>
+          </PanelSectionRow>
+          <PanelSectionRow>
+            <ButtonItem
+              layout="below"
+              description="Open the host's Quick Access Menu"
+              onClick={() => void pressHost("qam")}
+            >
+              <FaGamepad style={{ marginRight: "0.5em" }} />
+              Quick access on host
+            </ButtonItem>
+          </PanelSectionRow>
         </PanelSection>
       )}
 
-      <PanelSection title="Hosts">
-        <PanelSectionRow>
-          <ButtonItem layout="below" onClick={refresh} disabled={busy}>
-            {busy ? (
-              <Spinner style={{ height: "1em", marginRight: "0.5em" }} />
-            ) : (
-              <FaSyncAlt style={{ marginRight: "0.5em" }} />
-            )}
-            {busy ? "Scanning…" : "Refresh"}
-          </ButtonItem>
-        </PanelSectionRow>
-        {hosts.length === 0 && busy && (
-          <PanelSectionRow>
-            <Field focusable={false} description="Scanning your network…" />
-          </PanelSectionRow>
-        )}
-        {hosts.length === 0 && !busy && (
-          <PanelSectionRow>
-            <Field
-              focusable={false}
-              label="No hosts found"
-              description="Open Punktfunk to add a host by address, or start a host on this network and refresh."
-            />
-          </PanelSectionRow>
-        )}
-        {hosts.map((v) => {
-          const pair = needsPair(v);
-          const h = toHost(v);
-          return (
-            <PanelSectionRow key={v.fp || `${v.addr}:${v.port}`}>
-              <ButtonItem
-                layout="below"
-                onClick={() =>
-                  pair
-                    ? showModal(<PairModal host={h} onPaired={() => startStream(h)} />)
-                    : startStream(h)
-                }
-                label={
-                  <span style={{ display: "inline-flex", alignItems: "center", gap: "0.4em" }}>
-                    {pair ? <FaLock /> : <FaLockOpen />}
-                    {v.name}
-                  </span>
-                }
-                description={`${v.addr}:${v.port} · ${v.online ? "online" : "offline"}${
-                  pair ? " · pairing required" : v.paired ? " · paired" : ""
-                }`}
-              >
-                {pair ? "Pair & Stream" : "Stream"}
-              </ButtonItem>
-            </PanelSectionRow>
-          );
-        })}
-      </PanelSection>
-
       <PanelSection title="About">
         <PanelSectionRow>
           <Field
@@ -236,13 +316,22 @@ const QamPanel: FC = () => {
             Recreate library shortcut
           </ButtonItem>
         </PanelSectionRow>
+        <PanelSectionRow>
+          <ButtonItem
+            layout="below"
+            description="Ends a stream that stopped responding."
+            onClick={() => void forceStop()}
+          >
+            <FaStopCircle style={{ marginRight: "0.5em" }} />
+            Force-stop
+          </ButtonItem>
+        </PanelSectionRow>
       </PanelSection>
     </>
   );
 };
 
 export default definePlugin(() => {
-  routerHook.addRoute(ROUTE, PunktfunkRoute, { exact: true });
   // Ensure the visible, stateless "Punktfunk" library entry (opens the gamepad UI / console
   // home) exists and is repointed to the current plugin dir — also installs the native-touch
   // controller config. Fire-and-forget: cosmetic library upkeep must never block plugin load.
@@ -260,8 +349,5 @@ export default definePlugin(() => {
       </PluginErrorBoundary>
     ),
     icon: <FaTv />,
-    onDismount() {
-      routerHook.removeRoute(ROUTE);
-    },
   };
 });

clients/decky/src/library.tsx

@@ -1,230 +0,0 @@
-// The per-host game picker + pinned-game launch helper. The picker fetches a paired
-// host's library through the backend (headless flatpak --library — a cold client start
-// can take seconds, hence the explicit spinner copy) and pins titles as one-tap rows in
-// the QAM's Games section; its header also launches the GTK client's on-screen gamepad
-// library (`--browse`).
-import { DialogButton, Field, ModalRoot, Spinner, showModal } from "@decky/ui";
-import { FC, useEffect, useState } from "react";
-import { FaThLarge, FaTv } from "react-icons/fa";
-import { GameEntry, Host, library, LibraryResult, PinnedGame } from "./backend";
-import { PinsApi, resolvePinHost, startBrowse, startStream } from "./hooks";
-import { isSafeLaunchId } from "./steam";
-import { PairModal } from "./pair";
-import { RowActions, actionButton } from "./ui";
-
-/** Human store tag (mirrors the GTK client's `store_label`). */
-export function storeLabel(store: string): string {
-  switch (store) {
-    case "steam":
-      return "Steam";
-    case "custom":
-      return "Custom";
-    case "heroic":
-      return "Heroic";
-    case "lutris":
-      return "Lutris";
-    case "epic":
-      return "Epic";
-    case "gog":
-      return "GOG";
-    case "xbox":
-      return "Xbox";
-    default:
-      return "Game";
-  }
-}
-
-/**
- * Stream a pinned game: resolve the host from the live scan (fp → id → stored address),
- * opportunistically refresh a drifted stored address, and route through pairing first if
- * this device is no longer paired with the host.
- */
-export function streamPin(pin: PinnedGame, live: Host[], pins: PinsApi): void {
-  const { host, online } = resolvePinHost(pin, live);
-  if (online) {
-    pins.updatePinHost(pin, host); // no-op unless the address actually drifted
-  }
-  if (!pin.paired) {
-    showModal(
-      <PairModal
-        host={host}
-        onPaired={() => {
-          void pins.refresh(); // pick up the now-paired annotation
-          void startStream(host, { launchId: pin.game_id }, pin.title);
-        }}
-      />,
-    );
-    return;
-  }
-  void startStream(host, { launchId: pin.game_id }, pin.title);
-}
-
-// Copy per backend error code (LibraryResult.error); `detail` covers the generic case.
-function errorCopy(res: LibraryResult): string {
-  switch (res.error) {
-    case "not-paired":
-      return "This Deck isn't paired with the host — pair first, then browse its library.";
-    case "pin-mismatch":
-      return "The host's identity changed — re-pair to re-establish trust.";
-    case "unreachable":
-      return "Couldn't reach the host's management API. Is the host online and up to date?";
-    case "timeout":
-      return "Timed out talking to the host — try again.";
-    case "flatpak-not-found":
-      return "The Punktfunk client isn't installed (flatpak io.unom.Punktfunk).";
-    case "client-outdated":
-      return "The installed client is too old for library browsing — update it from the About tab.";
-    default:
-      return res.detail || "Couldn't fetch the library.";
-  }
-}
-
-// ----------------------------------------------------------------------------------------
-// The picker modal: "open on screen" + a pin-toggle list of the host's games.
-// ----------------------------------------------------------------------------------------
-export const GamePickerModal: FC<{
-  host: Host;
-  pins: PinsApi;
-  clientUpdatePending?: boolean;
-  closeModal?: () => void;
-}> = ({ host, pins, clientUpdatePending, closeModal }) => {
-  const [result, setResult] = useState<LibraryResult | null>(null);
-  const [attempt, setAttempt] = useState(0); // bump to refetch (retry / after pairing)
-  // The modal is a detached `showModal` portal that never re-renders from the page's pin
-  // state, so `pins.isPinned` would read a frozen snapshot and the Pin/Unpin label would
-  // never flip within a session. Track this host's pinned ids locally, seeded once from the
-  // snapshot at open; persistence still goes through the (stale-closure-safe) pins API.
-  const [pinnedIds, setPinnedIds] = useState<Set<string>>(
-    () => new Set(pins.pins.filter((p) => p.host_fp === host.fp).map((p) => p.game_id)),
-  );
-  const togglePin = (g: GameEntry) => {
-    const wasPinned = pinnedIds.has(g.id);
-    setPinnedIds((prev) => {
-      const next = new Set(prev);
-      if (wasPinned) next.delete(g.id);
-      else next.add(g.id);
-      return next;
-    });
-    if (wasPinned) pins.removePin(host.fp, g.id);
-    else pins.addPin(host, g);
-  };
-
-  useEffect(() => {
-    let stale = false;
-    setResult(null);
-    library(host.host, host.mgmt, host.fp)
-      .then((res) => {
-        if (!stale) setResult(res);
-      })
-      .catch((e) => {
-        if (!stale) setResult({ ok: false, error: "client-error", detail: String(e) });
-      });
-    return () => {
-      stale = true;
-    };
-  }, [host.host, host.mgmt, host.fp, attempt]);
-
-  const games = (result?.ok && result.games) || [];
-  const sorted = [...games].sort((a, b) => a.title.localeCompare(b.title));
-
-  return (
-    <ModalRoot closeModal={closeModal}>
-      <div style={{ fontWeight: "bold", fontSize: "1.3em", marginBottom: "0.4em" }}>
-        {host.name} — Games
-      </div>
-
-      <Field
-        label="Open library on screen"
-        description="Browse this host's games with the controller, full screen"
-        childrenContainerWidth="max"
-      >
-        <RowActions>
-          <DialogButton
-            style={actionButton}
-            onClick={() => {
-              closeModal?.();
-              void startBrowse(host);
-            }}
-          >
-            <FaTv style={{ marginRight: "0.4em" }} />
-            Open
-          </DialogButton>
-        </RowActions>
-      </Field>
-
-      {clientUpdatePending && (
-        <Field
-          focusable={false}
-          description="A client update is available — direct game launch and on-screen browsing need the latest client."
-        />
-      )}
-
-      {result === null && (
-        <Field
-          focusable={false}
-          label={
-            <span style={{ display: "inline-flex", alignItems: "center", gap: "0.6em" }}>
-              <Spinner style={{ height: "1em" }} />
-              Fetching the library…
-            </span>
-          }
-          description="This starts the client headlessly — a cold start can take a few seconds."
-        />
-      )}
-
-      {result !== null && !result.ok && (
-        <Field label="Couldn't fetch the library" description={errorCopy(result)} childrenContainerWidth="max">
-          <RowActions>
-            {result.error === "not-paired" && (
-              <DialogButton
-                style={actionButton}
-                onClick={() =>
-                  showModal(<PairModal host={host} onPaired={() => setAttempt((n) => n + 1)} />)
-                }
-              >
-                Pair
-              </DialogButton>
-            )}
-            <DialogButton style={actionButton} onClick={() => setAttempt((n) => n + 1)}>
-              Retry
-            </DialogButton>
-          </RowActions>
-        </Field>
-      )}
-
-      {result?.ok && sorted.length === 0 && (
-        <Field
-          focusable={false}
-          label="No games found"
-          description="Install Steam titles or add custom entries in the host's web console."
-        />
-      )}
-
-      {sorted.length > 0 && (
-        <div style={{ maxHeight: "55vh", overflowY: "auto" }}>
-          {sorted.map((g: GameEntry) => {
-            const pinned = pinnedIds.has(g.id);
-            const safe = isSafeLaunchId(g.id);
-            return (
-              <Field
-                key={g.id}
-                label={g.title}
-                description={
-                  storeLabel(g.store) + (safe ? "" : " · unsupported id — can't be pinned")
-                }
-                childrenContainerWidth="max"
-              >
-                <RowActions>
-                  <DialogButton style={actionButton} disabled={!safe} onClick={() => togglePin(g)}>
-                    <FaThLarge style={{ marginRight: "0.4em" }} />
-                    {pinned ? "Unpin" : "Pin"}
-                  </DialogButton>
-                </RowActions>
-              </Field>
-            );
-          })}
-        </div>
-      )}
-    </ModalRoot>
-  );
-};

clients/decky/src/page.tsx

@@ -1,596 +0,0 @@
-// The fullscreen page (registered as the /punktfunk route) — Hosts / Settings / About tabs.
-import {
-  ConfirmModal,
-  DialogButton,
-  Field,
-  Focusable,
-  ModalRoot,
-  Navigation,
-  Spinner,
-  Tabs,
-  showModal,
-  staticClasses,
-} from "@decky/ui";
-import { RowActions, actionButton, iconButton } from "./ui";
-import { toaster } from "@decky/api";
-import { CSSProperties, FC, useState } from "react";
-import {
-  FaArrowLeft,
-  FaDownload,
-  FaExternalLinkAlt,
-  FaInfoCircle,
-  FaLock,
-  FaLockOpen,
-  FaPen,
-  FaPlay,
-  FaPlus,
-  FaSyncAlt,
-  FaThLarge,
-  FaTrashAlt,
-} from "react-icons/fa";
-import { UpdateInfo, forgetHost, killStream } from "./backend";
-import { PluginErrorBoundary } from "./boundary";
-import { OsMark } from "./os-icon";
-import {
-  DOCS_URL,
-  HostView,
-  PinsApi,
-  applyUpdate,
-  checkForUpdatesNow,
-  clientInstallLabel,
-  clientUpdateIsManualOnly,
-  hasUpdate,
-  mergeHosts,
-  needsPair,
-  pinIsOnline,
-  resetAll,
-  startStream,
-  toHost,
-  useHosts,
-  usePins,
-  useSavedHosts,
-  useUpdate,
-} from "./hooks";
-import { AddHostModal, EditHostModal, mutationError } from "./hostmgmt";
-import { GamePickerModal, storeLabel, streamPin } from "./library";
-import { PairModal } from "./pair";
-import { SettingsSection } from "./settings";
-import { stopStream } from "./steam";
-
-export const ROUTE = "/punktfunk";
-
-// Bottom inset so the last control clears Gaming Mode's footer hint bar. Routed pages render
-// *under* that bar otherwise — that's why the last Stream-settings row was getting hidden. The
-// value is generous on purpose (and harmless where the tab area already insets); tune to taste.
-const SAFE_BOTTOM = "80px";
-
-// Each tab is its own scroll area so long content is always reachable above the footer.
-const tabScroll: CSSProperties = {
-  height: "100%",
-  overflowY: "auto",
-  padding: "0.5em 2.5em",
-  paddingBottom: SAFE_BOTTOM,
-  boxSizing: "border-box",
-};
-
-// The one-line status under a host name: address, live presence, and trust state.
-function hostSubtitle(v: HostView): string {
-  const parts = [`${v.addr}:${v.port}`, v.online ? "online" : "offline"];
-  if (needsPair(v)) {
-    parts.push("pairing required");
-  } else if (v.paired) {
-    parts.push("paired");
-  } else if (v.saved) {
-    parts.push("trusted");
-  }
-  return parts.join(" · ");
-}
-
-/** Confirm + forget a saved host, then refresh the list. */
-function confirmForget(v: HostView, refresh: () => void): void {
-  const selector = v.fp || `${v.addr}:${v.port}`;
-  showModal(
-    <ConfirmModal
-      strTitle={`Forget ${v.name}?`}
-      strDescription="You'll need to pair or trust it again to reconnect."
-      strOKButtonText="Forget"
-      bDestructiveWarning
-      onOK={async () => {
-        const r = await forgetHost(selector);
-        toaster.toast({
-          title: "Punktfunk",
-          body: r.ok ? `Forgot ${v.name}` : mutationError(r),
-        });
-        refresh();
-      }}
-    />,
-  );
-}
-
-// ----------------------------------------------------------------------------------------
-// Host details — everything we know, plus (for a saved host) rename / edit / forget.
-// ----------------------------------------------------------------------------------------
-const HostDetailsModal: FC<{
-  host: HostView;
-  onChanged: () => void;
-  closeModal?: () => void;
-}> = ({ host, onChanged, closeModal }) => {
-  const fp = host.fp ? (host.fp.match(/.{1,4}/g) ?? [host.fp]).join(" ") : "not known yet";
-  return (
-    <ModalRoot closeModal={closeModal}>
-      <div style={{ fontWeight: "bold", fontSize: "1.3em", marginBottom: "0.4em" }}>
-        {host.name}
-      </div>
-      <Field focusable={false} label="Address">
-        {host.addr}:{host.port}
-      </Field>
-      <Field focusable={false} label="Presence">
-        {host.online ? "Online" : "Offline"}
-      </Field>
-      <Field focusable={false} label="This Deck">
-        {host.paired ? "Paired" : host.fp ? "Trusted" : "Not paired yet"}
-      </Field>
-      <Field
-        focusable={false}
-        label="Certificate fingerprint (SHA-256)"
-        description={
-          <span
-            style={{ fontFamily: "monospace", fontSize: "0.85em", wordBreak: "break-word" }}
-          >
-            {fp}
-          </span>
-        }
-      />
-      {host.saved && (
-        <Field label="Manage" childrenContainerWidth="max">
-          <RowActions>
-            <DialogButton
-              style={actionButton}
-              onClick={() => {
-                closeModal?.();
-                showModal(<EditHostModal host={host} onDone={onChanged} />);
-              }}
-            >
-              <FaPen style={{ marginRight: "0.4em" }} />
-              Edit
-            </DialogButton>
-            <DialogButton
-              style={actionButton}
-              onClick={() => {
-                closeModal?.();
-                confirmForget(host, onChanged);
-              }}
-            >
-              <FaTrashAlt style={{ marginRight: "0.4em" }} />
-              Forget
-            </DialogButton>
-          </RowActions>
-        </Field>
-      )}
-    </ModalRoot>
-  );
-};
-
-// ----------------------------------------------------------------------------------------
-// One host row: status icon + address, details / pair / stream actions.
-// ----------------------------------------------------------------------------------------
-const HostRow: FC<{
-  host: HostView;
-  onChanged: () => void;
-  onGames: () => void;
-}> = ({ host, onChanged, onGames }) => {
-  const pair = needsPair(host);
-  const h = toHost(host);
-  return (
-    <Field
-      label={
-        <span style={{ display: "inline-flex", alignItems: "center", gap: "0.4em" }}>
-          <OsMark os={host.os} />
-          {pair ? <FaLock /> : <FaLockOpen />}
-          {host.name}
-        </span>
-      }
-      description={hostSubtitle(host)}
-      childrenContainerWidth="max"
-    >
-      <RowActions>
-        <DialogButton
-          style={iconButton}
-          onClick={() => showModal(<HostDetailsModal host={host} onChanged={onChanged} />)}
-        >
-          <FaInfoCircle />
-        </DialogButton>
-        {/* Labeled, not icon-only: this is the entry to the game picker AND the on-screen
-            library browser, and controller nav has no hover tooltip to explain a bare icon. */}
-        <DialogButton style={actionButton} onClick={onGames}>
-          <FaThLarge style={{ marginRight: "0.4em" }} />
-          Games
-        </DialogButton>
-        {pair && (
-          <DialogButton
-            style={actionButton}
-            onClick={() => showModal(<PairModal host={h} onPaired={onChanged} />)}
-          >
-            Pair
-          </DialogButton>
-        )}
-        <DialogButton
-          style={actionButton}
-          onClick={() =>
-            pair
-              ? showModal(<PairModal host={h} onPaired={() => startStream(h)} />)
-              : startStream(h)
-          }
-        >
-          <FaPlay style={{ marginRight: "0.4em" }} />
-          Stream
-        </DialogButton>
-      </RowActions>
-    </Field>
-  );
-};
-
-const HostsTab: FC<{
-  hosts: HostView[];
-  scanning: boolean;
-  refresh: () => void;
-  pins: PinsApi;
-  clientUpdatePending: boolean;
-}> = ({ hosts, scanning, refresh, pins, clientUpdatePending }) => (
-  <div style={tabScroll}>
-    <Field
-      label="Hosts"
-      description={
-        scanning
-          ? "Scanning the LAN…"
-          : `${hosts.length} host${hosts.length === 1 ? "" : "s"} — saved and on your network`
-      }
-      childrenContainerWidth="max"
-      bottomSeparator={hosts.length ? "standard" : "none"}
-    >
-      <RowActions>
-        <DialogButton
-          style={actionButton}
-          onClick={() => showModal(<AddHostModal onDone={refresh} />)}
-        >
-          <FaPlus style={{ marginRight: "0.5em" }} />
-          Add
-        </DialogButton>
-        <DialogButton style={actionButton} disabled={scanning} onClick={refresh}>
-          {scanning ? (
-            <Spinner style={{ height: "1em", marginRight: "0.5em" }} />
-          ) : (
-            <FaSyncAlt style={{ marginRight: "0.5em" }} />
-          )}
-          {scanning ? "Scanning…" : "Refresh"}
-        </DialogButton>
-      </RowActions>
-    </Field>
-
-    {hosts.length === 0 && !scanning && (
-      <Field
-        focusable={false}
-        label="No hosts yet"
-        description="Add one by address with +, or start a Punktfunk host on this network and refresh. The setup guide (About tab) covers installing a host."
-      />
-    )}
-    {hosts.map((h) => (
-      <HostRow
-        key={h.fp || `${h.addr}:${h.port}`}
-        host={h}
-        onChanged={refresh}
-        onGames={() =>
-          showModal(
-            <GamePickerModal
-              host={toHost(h)}
-              pins={pins}
-              clientUpdatePending={clientUpdatePending}
-            />,
-          )
-        }
-      />
-    ))}
-
-    {/* Pinned games — also the cleanup surface for pins whose host is gone from the scan. */}
-    {pins.pins.length > 0 && (
-      <>
-        <Field
-          focusable={false}
-          label="Pinned games"
-          description="One-tap streams — they also live in the quick-access menu"
-          bottomSeparator="standard"
-        />
-        {pins.pins.map((pin) => {
-          const online = pinIsOnline(pin, hosts);
-          return (
-            <Field
-              key={`${pin.host_fp}:${pin.game_id}`}
-              label={pin.title}
-              description={`${storeLabel(pin.store)} · ${pin.host_name}${
-                online ? "" : " · offline?"
-              }${pin.paired ? "" : " · pairing required"}`}
-              childrenContainerWidth="max"
-            >
-              <RowActions>
-                <DialogButton
-                  style={actionButton}
-                  onClick={() => streamPin(pin, hosts.map(toHost), pins)}
-                >
-                  <FaPlay style={{ marginRight: "0.4em" }} />
-                  Play
-                </DialogButton>
-                <DialogButton
-                  style={actionButton}
-                  onClick={() => pins.removePin(pin.host_fp, pin.game_id)}
-                >
-                  Remove
-                </DialogButton>
-              </RowActions>
-            </Field>
-          );
-        })}
-      </>
-    )}
-  </div>
-);
-
-// NOT `tabScroll`: the settings screen is a SidebarNavigation, which lays out its own rail +
-// content pane and scrolls the pane itself. Wrapping it in an outer scroll area would give it an
-// indefinite height to fill, collapsing the rail — so this pane only hands it the full height and
-// keeps its hands off the overflow. The footer inset lives inside the pages instead.
-const settingsPane: CSSProperties = { height: "100%", overflow: "hidden" };
-
-const SettingsTab: FC = () => (
-  <div style={settingsPane}>
-    <SettingsSection />
-  </div>
-);
-
-// ----------------------------------------------------------------------------------------
-// About — plugin version + explicit update check, docs link, stream-exit help, force-stop,
-// and the destructive "reset everything" action.
-// ----------------------------------------------------------------------------------------
-async function forceStopStream(): Promise<void> {
-  stopStream(); // ask Steam to end the "game" first (clean path)
-  const res = await killStream(); // then the flatpak-level hammer for a wedged client
-  toaster.toast({
-    title: "Punktfunk",
-    body: res.ok ? "Stream client stopped." : "Couldn’t stop the stream client.",
-  });
-}
-
-function confirmReset(refreshers: Array<() => void | Promise<void>>): void {
-  showModal(
-    <ConfirmModal
-      strTitle="Reset Punktfunk?"
-      strDescription="Clears every saved host, your stream settings, and all pinned games on this Deck. Your client identity is kept, so you'll re-pair hosts to reconnect. This can't be undone."
-      strOKButtonText="Reset"
-      bDestructiveWarning
-      onOK={() => void resetAll(refreshers)}
-    />,
-  );
-}
-
-const AboutTab: FC<{
-  update: UpdateInfo | null;
-  checking: boolean;
-  check: (force: boolean) => Promise<UpdateInfo | null>;
-  onReset: () => void;
-}> = ({ update, checking, check, onReset }) => (
-  <div style={tabScroll}>
-    <Field
-      label="Version"
-      description={
-        update
-          ? `v${update.current}${
-              update.channel ? ` · ${update.channel} channel` : " · development build"
-            }`
-          : "…"
-      }
-      childrenContainerWidth="max"
-    >
-      <RowActions>
-        <DialogButton
-          style={actionButton}
-          disabled={checking}
-          onClick={() => void checkForUpdatesNow(check)}
-        >
-          {checking ? <Spinner style={{ height: "1em" }} /> : "Check for updates"}
-        </DialogButton>
-      </RowActions>
-    </Field>
-    {/* What the client IS, so "why is there no Update button?" has a visible answer. The
-        install kind decides everything below it. */}
-    {!!update?.client_install && (
-      <Field
-        label="Client"
-        description={`${clientInstallLabel(update.client_install)}${
-          update.client_current ? ` · ${update.client_current}` : ""
-        }`}
-      />
-    )}
-    {hasUpdate(update) && (
-      <Field
-        label={
-          update!.update_available
-            ? `Plugin update — v${update!.latest}${
-                update!.client_update_available ? " + client" : ""
-              }`
-            : `Client update — ${update!.client_latest || "available"}`
-        }
-        description={
-          // Only promise a one-tap install when there is one. On a notify-only install the
-          // row becomes the command itself, which is the whole answer for that box.
-          clientUpdateIsManualOnly(update) && !update!.update_available
-            ? update!.client_opt_in || update!.client_command
-            : "Installing can take a couple of minutes; Decky reloads the plugin when done"
-        }
-        childrenContainerWidth="max"
-      >
-        {clientUpdateIsManualOnly(update) && !update!.update_available ? null : (
-          <RowActions>
-            <DialogButton style={actionButton} onClick={() => applyUpdate(update!, check)}>
-              <FaDownload style={{ marginRight: "0.4em" }} />
-              Update
-            </DialogButton>
-          </RowActions>
-        )}
-      </Field>
-    )}
-    {!!update?.client_error && (
-      <Field
-        label="Client update check"
-        description={
-          update.client_error === "client-outdated"
-            ? "This client predates update checks — update it once by hand and the check starts working."
-            : "Couldn’t check the client for updates."
-        }
-      />
-    )}
-    <Field
-      label="Setup guide"
-      description="Hosts, pairing, controllers, and troubleshooting — docs.punktfunk.unom.io"
-      childrenContainerWidth="max"
-    >
-      <RowActions>
-        <DialogButton
-          style={actionButton}
-          onClick={() => Navigation.NavigateToExternalWeb(DOCS_URL)}
-        >
-          <FaExternalLinkAlt style={{ marginRight: "0.4em" }} />
-          Open
-        </DialogButton>
-      </RowActions>
-    </Field>
-    <Field
-      focusable={false}
-      label="Leaving a stream"
-      description="Hold L1 + R1 + Start + Select inside the stream, or close the “game” from the Steam overlay — either returns you to Gaming Mode."
-    />
-    <Field
-      label="Stream stuck?"
-      description="Force-stop the stream client if a session wedges"
-      childrenContainerWidth="max"
-    >
-      <RowActions>
-        <DialogButton style={actionButton} onClick={() => void forceStopStream()}>
-          Force-stop
-        </DialogButton>
-      </RowActions>
-    </Field>
-    <Field
-      label="Reset Punktfunk"
-      description="Clear saved hosts, stream settings, and pinned games on this Deck (keeps your client identity)"
-      childrenContainerWidth="max"
-    >
-      <RowActions>
-        <DialogButton style={actionButton} onClick={onReset}>
-          <FaTrashAlt style={{ marginRight: "0.4em" }} />
-          Reset
-        </DialogButton>
-      </RowActions>
-    </Field>
-  </div>
-);
-
-const PunktfunkPage: FC = () => {
-  const { hosts: discovered, scanning, refresh: refreshDiscovered } = useHosts();
-  const { saved, loading: loadingSaved, refresh: refreshSaved } = useSavedHosts();
-  const { info: update, checking, check } = useUpdate();
-  const pins = usePins();
-  const [tab, setTab] = useState("hosts");
-
-  const hosts = mergeHosts(saved, discovered);
-  // A host action (pair/add/edit/forget) can change either store, so refresh both.
-  const refreshHosts = () => {
-    void refreshDiscovered();
-    void refreshSaved();
-  };
-
-  return (
-    <div
-      style={{
-        marginTop: "40px",
-        height: "calc(100% - 40px)",
-        display: "flex",
-        flexDirection: "column",
-      }}
-    >
-      {/* Header is title + back only — updates live on the About tab (and the QAM banner). */}
-      <Focusable
-        style={{
-          display: "flex",
-          alignItems: "center",
-          gap: "1em",
-          padding: "0 2.5em",
-          marginBottom: "0.4em",
-          flexShrink: 0,
-        }}
-      >
-        <DialogButton style={iconButton} onClick={() => Navigation.NavigateBack()}>
-          <FaArrowLeft />
-        </DialogButton>
-        <div className={staticClasses?.Title} style={{ flex: 1, margin: 0 }}>
-          Punktfunk
-        </div>
-      </Focusable>
-
-      {/* Two things fight each other on an L1/R1 tab switch:
-          1. Valve's Tabs slides the incoming panel in from the right with a CSS transform.
-          2. `autoFocusContents` then focuses a control inside that still-offscreen panel, which
-             fires scrollIntoView. Because the panel is offset by a *transform* (not by scroll
-             position), scrollIntoView can't satisfy it by scrolling any one ancestor, so it walks
-             up and pans the whole page — the "screen jumps right, then animates back" glitch.
-          Dropping autoFocusContents removes the scrollIntoView entirely, so nothing fights the
-          slide. L1/R1 still cycles tabs (that handler lives on the Tabs focus scope, active while
-          focus is anywhere inside — including the tab strip); after a switch, focus stays on the
-          strip and Down enters the content, which is how Steam's own tabbed pages behave.
-          The overflow:hidden clip stays as defense-in-depth against any stray horizontal pan. */}
-      <div style={{ flex: 1, minHeight: 0, overflow: "hidden" }}>
-        <Tabs
-          activeTab={tab}
-          onShowTab={(id: string) => setTab(id)}
-          tabs={[
-            {
-              id: "hosts",
-              title: "Hosts",
-              content: (
-                <HostsTab
-                  hosts={hosts}
-                  scanning={scanning || loadingSaved}
-                  refresh={refreshHosts}
-                  pins={pins}
-                  clientUpdatePending={!!update?.client_update_available}
-                />
-              ),
-            },
-            {
-              id: "settings",
-              title: "Settings",
-              content: <SettingsTab />,
-            },
-            {
-              id: "about",
-              title: "About",
-              content: (
-                <AboutTab
-                  update={update}
-                  checking={checking}
-                  check={check}
-                  onReset={() => confirmReset([refreshHosts, pins.refresh])}
-                />
-              ),
-            },
-          ]}
-        />
-      </div>
-    </div>
-  );
-};
-
-// Full page behind the boundary — registered as the /punktfunk route.
-export const PunktfunkRoute: FC = () => (
-  <PluginErrorBoundary>
-    <PunktfunkPage />
-  </PluginErrorBoundary>
-);

clients/decky/src/pair.tsx

@@ -3,10 +3,32 @@
 import { DialogButton, Focusable, ModalRoot, Spinner } from "@decky/ui";
 import { toaster } from "@decky/api";
 import { FC, useState } from "react";
-import { Host, pair } from "./backend";
+import { pair } from "./backend";
+import { HostView } from "./hooks";
+
+/**
+ * User-facing copy for a failed ceremony. The CLI's stable exit codes say WHICH failure it was,
+ * so the keypad can name the fix instead of echoing a log line: `refused` is overwhelmingly a
+ * mistyped PIN or a host nobody armed, and telling someone to check their network for that
+ * would send them the wrong way entirely.
+ */
+function pairErrorBody(error: string | undefined, name: string): string {
+  switch (error) {
+    case "refused":
+      return "Wrong PIN, or the host isn’t showing one. Arm pairing again and retry.";
+    case "unreachable":
+      return `Couldn’t reach ${name}.`;
+    case "client-outdated":
+      return "Update the Punktfunk client to pair from here.";
+    case "client-unavailable":
+      return "Couldn’t reach the Punktfunk client — is it still installed?";
+    default:
+      return "Pairing failed.";
+  }
+}
 
 export const PairModal: FC<{
-  host: Host;
+  host: HostView;
   closeModal?: () => void;
   onPaired: () => void;
 }> = ({ host, closeModal, onPaired }) => {
@@ -21,13 +43,13 @@ export const PairModal: FC<{
     setBusy(true);
     setError(null);
     try {
-      const res = await pair(host.host, host.port, pin, "Steam Deck");
+      const res = await pair(host.addr, host.port, pin, "Steam Deck");
       if (res.ok) {
         toaster.toast({ title: "Punktfunk", body: `Paired with ${host.name}` });
         onPaired();
         closeModal?.();
       } else {
-        setError(res.error ?? "pairing failed");
+        setError(pairErrorBody(res.error, host.name));
         setPin("");
       }
     } catch (e) {

clients/decky/src/settings.tsx

@@ -1,657 +0,0 @@
-// Stream settings — the client's WHOLE settings store, written to the JSON the client reads on
-// launch (main.py set_settings, merged onto what's on disk). This is the same
-// `client-gtk-settings.json` the desktop client and the console's settings screen own, so a value
-// changed in any of the three shows in the other two.
-//
-// SHAPE OF THIS SCREEN. Thirty rows is too many to scroll past on a thumbstick, so they are split
-// across a `SidebarNavigation` — the same left-rail-of-categories layout SteamOS's own Settings
-// uses, and the one Deck users already know. Every page fits on screen without scrolling, which is
-// the whole point of the split: the rail is the index, so nothing is more than one hop away.
-//
-// The categories, their order, and the wording of the rows are the console's settings screen
-// (pf-console-ui/src/screens/settings.rs) — that screen is the other settings editor a user
-// reaches without leaving Gaming Mode, and two different orders for one store is how people stop
-// trusting either. It shows them as one steppable list because it has no pointer and no room for
-// a rail; here they become the rail's pages, same groups, same sequence. Three more rules:
-//
-//   • A setting that depends on another is INDENTED under it and DISABLED, never hidden — the
-//     console dims those rows rather than dropping them, and a row that vanishes as you toggle
-//     the one above it is a moving target for a thumbstick.
-//   • A picker whose options this device doesn't have doesn't appear at all (the GPU row on a
-//     one-GPU Deck). A dead control is worse than an absent one.
-//   • Anything that behaves differently *here* than it does on a desktop says so in its own
-//     description, rather than being silently dropped from the screen.
-//
-// The accepted gamepad/compositor/codec/decoder names mirror punktfunk-core's `*Pref::from_name`
-// and the console's tables; the tier/mode names mirror the `StatsVerbosity` / `TouchMode` /
-// `MouseMode` enums, which serialize lowercase.
-import {
-  DialogButton,
-  Dropdown,
-  Field,
-  SidebarNavigation,
-  SliderField,
-  Spinner,
-  ToggleField,
-} from "@decky/ui";
-import { CSSProperties, FC, ReactElement, ReactNode, useEffect, useState } from "react";
-import {
-  FaDesktop,
-  FaGamepad,
-  FaHandPointer,
-  FaSlidersH,
-  FaTv,
-  FaVideo,
-  FaVolumeUp,
-} from "react-icons/fa";
-import {
-  AudioDevice,
-  DeviceLists,
-  getSettings,
-  listDevices,
-  refreshDevices,
-  setSettings,
-  StreamSettings,
-} from "./backend";
-import { actionButton, RowActions } from "./ui";
-
-// Decky's Dropdown has no width prop — it fills whatever container it's in, and a
-// `childrenContainerWidth="max"` Field is the whole row. Wrapping it in this fit-content shell
-// (inside the right-aligned RowActions) shrinks the control to its selected label, with a floor
-// so short values like "60 Hz" don't collapse to a nub and a ceiling so nothing runs edge to
-// edge. Matches the right-aligned, content-sized buttons everywhere else.
-const selectShell: CSSProperties = {
-  width: "fit-content",
-  minWidth: "10em",
-  maxWidth: "24em",
-};
-
-// ----------------------------------------------------------------------------------------
-// Option tables — the console's, so the two Gaming-Mode editors offer the same choices.
-// ----------------------------------------------------------------------------------------
-
-// "native" and "match" are virtual: they store `width`/`height` of 0 with `match_window` off/on.
-// Match window is offered even though this plugin's launches are always fullscreen (where it
-// degenerates to the display's native mode) — leaving it out would make the row lie about a
-// store the desktop client can set it in.
-const MATCH_WINDOW = "match";
-const RESOLUTIONS: [number, number, string][] = [
-  [0, 0, "Native display"],
-  [1280, 720, "1280 × 720"],
-  [1280, 800, "1280 × 800 (Deck)"],
-  [1920, 1080, "1920 × 1080"],
-  [2560, 1440, "2560 × 1440"],
-  [3840, 2160, "3840 × 2160"],
-];
-const resolutionKey = (w: number, h: number): string => (w === 0 && h === 0 ? "native" : `${w}x${h}`);
-
-const REFRESH = [0, 30, 60, 90, 120];
-// Render-resolution multipliers (mirrors punktfunk_core::render_scale::PRESETS). 1.0 = native.
-const RENDER_SCALES = [0.5, 0.67, 0.75, 1.0, 1.25, 1.5, 2.0, 3.0, 4.0];
-const renderScaleLabel = (x: number): string =>
-  x === 1 ? "Native (1×)" : x > 1 ? `${x}× · supersample` : `${x}×`;
-
-const COMPOSITORS: [string, string][] = [
-  ["auto", "Automatic"],
-  ["kwin", "KDE Plasma (KWin)"],
-  ["wlroots", "Sway (wlroots)"],
-  ["mutter", "GNOME (Mutter)"],
-  ["gamescope", "gamescope"],
-];
-const CODECS: [string, string][] = [
-  ["auto", "Automatic"],
-  ["hevc", "HEVC (H.265)"],
-  ["h264", "H.264 (AVC)"],
-  ["av1", "AV1"],
-  // Opt-in wired-LAN low-latency codec (100–400 Mbit/s class, 8-bit SDR). Only ever selected
-  // when the host advertises it too; anything else falls back to HEVC.
-  ["pyrowave", "PyroWave (wired LAN)"],
-];
-const DECODERS: [string, string][] = [
-  ["auto", "Automatic"],
-  ["vulkan", "Vulkan Video"],
-  ["vaapi", "VAAPI"],
-  ["software", "Software"],
-];
-// Presentation intent — the `present_priority` key shared with the Apple and Android clients, so
-// one profile reads the same on every device.
-const PRESENT_PRIORITIES: [string, string][] = [
-  ["latency", "Lowest latency"],
-  ["smooth", "Smoothness"],
-];
-// Smoothness buffer depth in frames; 0 = Automatic (resolves to 2).
-const SMOOTH_BUFFERS: [number, string][] = [
-  [0, "Automatic"],
-  [1, "1 frame"],
-  [2, "2 frames"],
-  [3, "3 frames"],
-];
-const AUDIO_CHANNELS: [number, string][] = [
-  [2, "Stereo"],
-  [6, "5.1 surround"],
-  [8, "7.1 surround"],
-];
-const GAMEPADS: [string, string][] = [
-  ["auto", "Automatic"],
-  ["xbox360", "Xbox 360"],
-  ["xboxone", "Xbox One"],
-  ["dualsense", "DualSense"],
-  ["dualshock4", "DualShock 4"],
-  ["steamdeck", "Steam Deck"],
-];
-const TOUCH_MODES: [string, string][] = [
-  ["trackpad", "Trackpad"],
-  ["pointer", "Direct pointer"],
-  ["touch", "Touch passthrough"],
-];
-const MOUSE_MODES: [string, string][] = [
-  ["capture", "Capture (games)"],
-  ["desktop", "Desktop (absolute)"],
-];
-const STATS_TIERS: [string, string][] = [
-  ["off", "Off"],
-  ["compact", "Compact"],
-  ["normal", "Normal"],
-  ["detailed", "Detailed"],
-];
-
-// ----------------------------------------------------------------------------------------
-// Row primitives — every picker row is Field + right-aligned, content-sized Dropdown, so the
-// twelve of them below stay one line each and can't drift apart.
-// ----------------------------------------------------------------------------------------
-
-const SelectRow = <T extends string | number>({
-  label,
-  description,
-  options,
-  value,
-  onChange,
-  formatUnknown,
-  disabled,
-  indent,
-}: {
-  label: string;
-  description?: ReactNode;
-  options: [T, string][];
-  value: T;
-  onChange: (v: T) => void;
-  // How to name a stored value this table doesn't list (see below); defaults to the raw value.
-  formatUnknown?: (v: T) => string;
-  disabled?: boolean;
-  indent?: boolean;
-}): ReactElement => {
-  // A Dropdown can only display a value that is one of its options, and this store has four other
-  // writers — the desktop client, the console, a settings profile, a newer client with presets
-  // this build doesn't know. Rather than render a blank control (or, worse, silently show a
-  // different value than the stream will actually use), carry the stored one as its own entry.
-  const shown: [T, string][] = options.some(([v]) => v === value)
-    ? options
-    : [...options, [value, formatUnknown ? formatUnknown(value) : String(value)]];
-  return (
-    <Field
-      label={label}
-      description={description}
-      disabled={disabled}
-      indentLevel={indent ? 1 : undefined}
-      childrenContainerWidth="max"
-    >
-      <RowActions>
-        <div style={selectShell}>
-          <Dropdown
-            disabled={disabled}
-            rgOptions={shown.map(([data, l]) => ({ data, label: l }))}
-            selectedOption={value}
-            onChange={(o) => onChange(o.data as T)}
-          />
-        </div>
-      </RowActions>
-    </Field>
-  );
-};
-
-// An audio-endpoint picker. The stored value is a PipeWire `node.name`; "" means "whatever the OS
-// is using". A stored endpoint that isn't in the current enumeration still gets an entry — it is
-// a real preference that simply isn't plugged in right now, and dropping it would silently
-// re-point the next stream at the default without ever showing the user why.
-const DeviceRow: FC<{
-  label: string;
-  description: string;
-  devices: AudioDevice[] | null;
-  value: string;
-  onChange: (v: string) => void;
-  disabled?: boolean;
-  indent?: boolean;
-}> = ({ label, description, devices, value, onChange, disabled, indent }) => {
-  const options: [string, string][] = [["", "System default"]];
-  for (const d of devices ?? []) options.push([d.name, d.description]);
-  if (value && !options.some(([name]) => name === value)) {
-    options.push([value, `${value} (not connected)`]);
-  }
-  return (
-    <SelectRow
-      label={label}
-      description={devices === null ? "Reading this device's audio endpoints…" : description}
-      options={options}
-      value={value}
-      onChange={onChange}
-      disabled={disabled || devices === null}
-      indent={indent}
-    />
-  );
-};
-
-// ----------------------------------------------------------------------------------------
-// The pages. One settings object, seven views on it — every page takes the same context rather
-// than fetching or holding state of its own, so a change on one page is visible on the others
-// the moment you switch.
-// ----------------------------------------------------------------------------------------
-
-interface PageCtx {
-  s: StreamSettings;
-  patch: (p: Partial<StreamSettings>) => void;
-  devices: DeviceLists | null;
-  reading: boolean;
-  readDevices: (again: boolean) => void;
-}
-
-// SidebarNavigation gives each page Steam's own padding, but the routed page still renders
-// UNDER Gaming Mode's footer hint bar, so the last row of a page needs to clear it (the same
-// inset the tabs use).
-const pageBody: CSSProperties = { paddingBottom: "80px" };
-
-const StreamPage: FC<PageCtx> = ({ s, patch }) => {
-  const renderScale = s.render_scale ?? 1;
-  const resolution = s.match_window ? MATCH_WINDOW : resolutionKey(s.width, s.height);
-  return (
-    <div style={pageBody}>
-      <SelectRow
-        label="Resolution"
-        description="The host creates a virtual display at exactly this size — no scaling. Match window follows the stream window instead, which in Gaming Mode means the Deck's native size."
-        options={[
-          ...RESOLUTIONS.map(([w, h, label]) => [resolutionKey(w, h), label] as [string, string]),
-          [MATCH_WINDOW, "Match window"] as [string, string],
-        ]}
-        value={resolution}
-        // A size set from a desktop profile that isn't one of these presets, spelled the way the
-        // presets are rather than left as the raw "1600x900" key.
-        formatUnknown={(v) => v.replace("x", " × ")}
-        onChange={(v) => {
-          if (v === MATCH_WINDOW) {
-            // The tri-state the console stores: the flag on, the explicit size cleared.
-            patch({ match_window: true, width: 0, height: 0 });
-            return;
-          }
-          const found = RESOLUTIONS.find(([w, h]) => resolutionKey(w, h) === v);
-          patch({ match_window: false, width: found?.[0] ?? 0, height: found?.[1] ?? 0 });
-        }}
-      />
-      <SelectRow
-        label="Refresh rate"
-        description="Native follows the display the stream is on."
-        options={REFRESH.map((r) => [r, r === 0 ? "Native" : `${r} Hz`] as [number, string])}
-        value={s.refresh_hz}
-        formatUnknown={(v) => `${v} Hz`}
-        onChange={(v) => patch({ refresh_hz: v })}
-      />
-      <SelectRow
-        label="Render scale"
-        description="The host renders larger or smaller than the stream mode and the Deck resamples — above 1× supersamples for sharpness, below 1× saves bandwidth."
-        options={RENDER_SCALES.map((x) => [x, renderScaleLabel(x)] as [number, string])}
-        // Snap the stored value to the nearest preset so the dropdown always shows a match.
-        value={RENDER_SCALES.reduce((best, x) =>
-          Math.abs(x - renderScale) < Math.abs(best - renderScale) ? x : best,
-        )}
-        onChange={(v) => patch({ render_scale: v })}
-      />
-      <SliderField
-        label="Bitrate"
-        description="0 = the host's own default (20 Mbit/s)."
-        value={Math.round(s.bitrate_kbps / 1000)}
-        min={0}
-        max={150}
-        step={5}
-        showValue
-        valueSuffix=" Mbit/s"
-        onChange={(v) => patch({ bitrate_kbps: v * 1000 })}
-      />
-      <SelectRow
-        label="Host compositor"
-        description="Which compositor drives the virtual display — honoured only if it's available on the host. Automatic suits almost every host."
-        options={COMPOSITORS}
-        value={s.compositor}
-        onChange={(v) => patch({ compositor: v })}
-      />
-    </div>
-  );
-};
-
-const VideoPage: FC<PageCtx> = ({ s, patch, devices }) => {
-  // Only worth a row on a box that actually has a choice to make. A Deck has one adapter, and a
-  // picker with a single option is a control that can't do anything.
-  const showGpuRow = (devices?.adapters.length ?? 0) > 1;
-  return (
-    <div style={pageBody}>
-      <SelectRow
-        label="Video codec"
-        description="A preference — the host falls back when its GPU can't encode this one."
-        options={CODECS}
-        value={s.codec ?? "auto"}
-        onChange={(v) => patch({ codec: v })}
-      />
-      <SelectRow
-        label="Video decoder"
-        description="How the Deck decodes the stream. Automatic prefers Vulkan Video, then VAAPI, then software."
-        options={DECODERS}
-        value={s.decoder ?? "auto"}
-        onChange={(v) => patch({ decoder: v })}
-      />
-      {showGpuRow && (
-        <SelectRow
-          label="Decode GPU"
-          description="Which adapter decodes and presents the stream. Automatic picks the discrete GPU where there is one."
-          options={[
-            ["", "Automatic"],
-            ...(devices?.adapters ?? []).map((a) => [a, a] as [string, string]),
-          ]}
-          value={s.adapter ?? ""}
-          onChange={(v) => patch({ adapter: v })}
-        />
-      )}
-      <ToggleField
-        label="10-bit HDR"
-        description="Advertise HDR10 so the host sends 10-bit when the content is HDR. Off means never ask for 10-bit."
-        checked={s.hdr_enabled ?? true}
-        onChange={(v) => patch({ hdr_enabled: v })}
-      />
-      <ToggleField
-        label="Full chroma (4:4:4)"
-        description="Full-colour video: crisp small text and thin lines, at more bandwidth. Needs an NVIDIA host (NVENC) or the PyroWave codec — other encoders stream 4:2:0 and the session falls back silently."
-        checked={s.enable_444 ?? false}
-        onChange={(v) => patch({ enable_444: v })}
-      />
-    </div>
-  );
-};
-
-const PresentationPage: FC<PageCtx> = ({ s, patch }) => {
-  const smooth = (s.present_priority ?? "latency") === "smooth";
-  return (
-    <div style={pageBody}>
-      <SelectRow
-        label="Prioritize"
-        description="What to optimise for when a decoded frame is ready. Lowest latency shows each frame the moment the display can take it — a network hiccup becomes an occasional repeated or skipped frame. Smoothness buffers a little to even those out."
-        options={PRESENT_PRIORITIES}
-        value={s.present_priority ?? "latency"}
-        onChange={(v) => patch({ present_priority: v })}
-      />
-      <SelectRow
-        label="Smoothness buffer"
-        description="Frames held back before showing. Each one absorbs about a refresh of network hiccup and adds a refresh of delay. Automatic holds two."
-        options={SMOOTH_BUFFERS}
-        value={s.smooth_buffer ?? 0}
-        formatUnknown={(v) => `${v} frames`}
-        onChange={(v) => patch({ smooth_buffer: v })}
-        disabled={!smooth}
-        indent
-      />
-      <ToggleField
-        label="V-Sync"
-        description="Tear-free. Off removes the wait for the screen's refresh — the lowest possible delay, at the cost of visible tearing. Best-effort: not every driver offers it, and the Detailed stats overlay names the mode actually in use."
-        checked={s.vsync ?? true}
-        onChange={(v) => patch({ vsync: v })}
-      />
-      <ToggleField
-        label="Follow variable refresh"
-        description="On a VRR screen, let the panel refresh in step with the stream instead of on a fixed cadence. Applies to fullscreen sessions — which a Gaming-Mode stream always is — and is harmless on a fixed-refresh screen."
-        checked={s.allow_vrr ?? true}
-        onChange={(v) => patch({ allow_vrr: v })}
-      />
-    </div>
-  );
-};
-
-const AudioPage: FC<PageCtx> = ({ s, patch, devices, reading, readDevices }) => {
-  const micOn = s.mic_enabled;
-  // What the pickers get: null while the enumeration is in flight (they show a loading state),
-  // [] when it answered but couldn't read the endpoints (System default plus whatever is
-  // stored), and the real list otherwise.
-  const endpoints = (list: AudioDevice[] | undefined): AudioDevice[] | null =>
-    reading || !devices ? null : devices.ok ? (list ?? []) : [];
-  return (
-    <div style={pageBody}>
-      <SelectRow
-        label="Audio channels"
-        description="The speaker layout requested from the host, which clamps it to what it can capture."
-        options={AUDIO_CHANNELS}
-        value={s.audio_channels ?? 2}
-        formatUnknown={(v) => `${v} channels`}
-        onChange={(v) => patch({ audio_channels: v })}
-      />
-      <DeviceRow
-        label="Output device"
-        description="Where stream audio plays. System default follows whatever the Deck is using, including a headset you plug in mid-stream."
-        devices={endpoints(devices?.sinks)}
-        value={s.speaker_device ?? ""}
-        onChange={(v) => patch({ speaker_device: v })}
-      />
-      <ToggleField
-        label="Stream microphone"
-        description="Send the Deck's microphone to the host's virtual mic. Ctrl+Alt+Shift+V mutes and unmutes it mid-stream."
-        checked={micOn}
-        onChange={(v) => patch({ mic_enabled: v })}
-      />
-      <DeviceRow
-        label="Microphone device"
-        description="Which input the mic uplink captures from."
-        devices={endpoints(devices?.sources)}
-        value={s.mic_device ?? ""}
-        onChange={(v) => patch({ mic_device: v })}
-        disabled={!micOn}
-        indent
-      />
-      <ToggleField
-        label="Echo cancellation"
-        description="Stops the host's audio, playing from the Deck's speakers, being picked up and sent back. Turn it off if your microphone already runs its own processing."
-        checked={s.echo_cancel ?? true}
-        onChange={(v) => patch({ echo_cancel: v })}
-        disabled={!micOn}
-        indentLevel={1}
-      />
-      {/* The escape hatch for a headset plugged in after this page was opened, and the honest
-          answer when the enumeration failed outright (a client too old to ship the session
-          binary). Rendered unconditionally, including while it is reading: a row that comes and
-          goes under a thumbstick is a moving target, so only its wording changes. */}
-      <Field
-        label={
-          !reading && devices && !devices.ok ? "Couldn't read this device's hardware" : "Devices"
-        }
-        description={
-          reading
-            ? "Reading this device's audio endpoints and GPUs…"
-            : devices && !devices.ok
-              ? "The output, microphone and GPU pickers fall back to Automatic. Reading them needs the client's session binary, which a client older than the two-binary split doesn't ship — update it from the About tab."
-              : "Plugged something in just now? Read the audio endpoints and GPUs again."
-        }
-        childrenContainerWidth="max"
-      >
-        <RowActions>
-          <DialogButton style={actionButton} disabled={reading} onClick={() => readDevices(true)}>
-            {reading ? <Spinner style={{ height: "1em" }} /> : "Refresh"}
-          </DialogButton>
-        </RowActions>
-      </Field>
-    </div>
-  );
-};
-
-const ControllersPage: FC<PageCtx> = ({ s, patch }) => {
-  const forwarding = s.gamepad_forwarding ?? true;
-  return (
-    <div style={pageBody}>
-      <ToggleField
-        label="Forward controllers"
-        description="Send controllers connected to the Deck to the host. Turn it off when your controller already reaches the host another way — USB passthrough such as VirtualHere, or a pad plugged into the host — so games don't see two of them."
-        checked={forwarding}
-        onChange={(v) => patch({ gamepad_forwarding: v })}
-      />
-      <SelectRow
-        label="Controller type"
-        description="The virtual pad the host creates. Automatic matches the controller you're holding."
-        options={GAMEPADS}
-        value={s.gamepad}
-        onChange={(v) => patch({ gamepad: v })}
-        disabled={!forwarding}
-        indent
-      />
-      {forwarding && (s.gamepad === "steamdeck" || s.gamepad === "auto") && (
-        <Field
-          label="⚠ Disable Steam Input"
-          description="On a Deck, Automatic forwards the built-in controller as a Steam Deck pad — paddles, both trackpads, and gyro included. For that, Steam Input must be OFF for Punktfunk: on the game page tap ⚙ → Controller Settings → set Steam Input to Off. Otherwise Steam keeps the Deck's controls and only the sticks + buttons reach the host."
-          indentLevel={1}
-        />
-      )}
-    </div>
-  );
-};
-
-const PointerPage: FC<PageCtx> = ({ s, patch }) => (
-  <div style={pageBody}>
-    <SelectRow
-      label="Touch mode"
-      description="How the touchscreen drives the host: Trackpad (relative cursor, tap to click), Direct pointer (the cursor jumps to your finger), or Touch passthrough (every finger is a host contact — only helps apps that understand touch)."
-      options={TOUCH_MODES}
-      value={s.touch_mode ?? "trackpad"}
-      onChange={(v) => patch({ touch_mode: v })}
-    />
-    <SelectRow
-      label="Mouse mode"
-      description="How a physical mouse drives the host: Capture locks the pointer for games, Desktop leaves it free and sends absolute positions. Ctrl+Alt+Shift+M switches it live mid-stream."
-      options={MOUSE_MODES}
-      value={s.mouse_mode ?? "capture"}
-      onChange={(v) => patch({ mouse_mode: v })}
-    />
-    <ToggleField
-      label="Invert scroll direction"
-      description="Reverses the wheel and trackpad scroll direction sent to the host."
-      checked={s.invert_scroll ?? false}
-      onChange={(v) => patch({ invert_scroll: v })}
-    />
-    <ToggleField
-      label="Capture system shortcuts"
-      description="Sends Alt+Tab, Super and friends to the host while input is captured, instead of leaving them to the local desktop. Gaming Mode is gamescope, which has no shortcuts to hold back — this is for a keyboard attached to the Deck in Desktop Mode, and for the desktop client sharing these settings."
-      checked={s.inhibit_shortcuts}
-      onChange={(v) => patch({ inhibit_shortcuts: v })}
-    />
-  </div>
-);
-
-const InterfacePage: FC<PageCtx> = ({ s, patch }) => {
-  // `Settings::stats_verbosity`: no tier = a pre-tier store, resolved through the legacy bool,
-  // which itself defaults to true.
-  const statsTier = s.stats_verbosity ?? ((s.show_stats ?? true) ? "normal" : "off");
-  return (
-    <div style={pageBody}>
-      <SelectRow
-        label="Statistics overlay"
-        description="How much the in-stream overlay shows: Compact (fps · latency · bitrate on one line) → Normal → Detailed. A three-finger tap on the touchscreen cycles it mid-stream."
-        options={STATS_TIERS}
-        value={statsTier}
-        // Both keys, in sync — the same pairing `Settings::set_stats_verbosity` keeps, so a
-        // client too old for the tiers still honours an Off chosen here.
-        onChange={(v) => patch({ stats_verbosity: v, show_stats: v !== "off" })}
-      />
-      <ToggleField
-        label="Wake hosts automatically"
-        description="Send Wake-on-LAN to a sleeping host before connecting and wait for it to boot. Turn it off for hosts reached over a VPN, where an offline-looking host is really just unreachable by broadcast and the wait only adds delay."
-        checked={s.auto_wake ?? true}
-        onChange={(v) => patch({ auto_wake: v })}
-      />
-      <ToggleField
-        label="Show game library in the client"
-        description="Lets the client's own host cards browse a paired host's games. This plugin's library browser works either way — this is for the client's screens."
-        checked={s.library_enabled ?? false}
-        onChange={(v) => patch({ library_enabled: v })}
-      />
-      <ToggleField
-        label="Start streams fullscreen"
-        description="Streams open fullscreen instead of windowed. Launches from this plugin are always fullscreen whatever this says — it's here because the desktop client reads the same settings."
-        checked={s.fullscreen_on_stream ?? true}
-        onChange={(v) => patch({ fullscreen_on_stream: v })}
-      />
-    </div>
-  );
-};
-
-// ----------------------------------------------------------------------------------------
-
-export const SettingsSection: FC = () => {
-  const [s, setS] = useState<StreamSettings | null>(null);
-  // null until the enumeration answers — the pickers show a loading state rather than briefly
-  // claiming this device has no endpoints.
-  const [devices, setDevices] = useState<DeviceLists | null>(null);
-  const [reading, setReading] = useState(true);
-
-  const readDevices = (again: boolean) => {
-    setReading(true);
-    void (again ? refreshDevices() : listDevices())
-      .then(setDevices)
-      .finally(() => setReading(false));
-  };
-
-  useEffect(() => {
-    void getSettings().then(setS);
-    // Deliberately not awaited together with the settings: a cold flatpak initialising Vulkan
-    // takes seconds, and the rest of the screen must not wait for it.
-    readDevices(false);
-  }, []);
-
-  const patch = (p: Partial<StreamSettings>) => {
-    setS((cur) => {
-      if (!cur) return cur;
-      const next = { ...cur, ...p };
-      void setSettings(next);
-      return next;
-    });
-  };
-
-  if (!s) return <Spinner style={{ height: "1.5em" }} />;
-
-  const ctx: PageCtx = { s, patch, devices, reading, readDevices };
-  return (
-    <SidebarNavigation
-      // We are already inside the plugin's own `/punktfunk` route, rendered in a tab. Route
-      // reporting would have this nav push entries of its own onto the router and fight the
-      // page for the back gesture; the pages are addressed by `identifier` instead.
-      disableRouteReporting
-      pages={[
-        { title: "Stream", identifier: "stream", icon: <FaDesktop />, content: <StreamPage {...ctx} /> },
-        { title: "Video", identifier: "video", icon: <FaVideo />, content: <VideoPage {...ctx} /> },
-        {
-          title: "Presentation",
-          identifier: "presentation",
-          icon: <FaTv />,
-          content: <PresentationPage {...ctx} />,
-        },
-        { title: "Audio", identifier: "audio", icon: <FaVolumeUp />, content: <AudioPage {...ctx} /> },
-        {
-          title: "Controllers",
-          identifier: "controllers",
-          icon: <FaGamepad />,
-          content: <ControllersPage {...ctx} />,
-        },
-        {
-          title: "Touch & mouse",
-          identifier: "pointer",
-          icon: <FaHandPointer />,
-          content: <PointerPage {...ctx} />,
-        },
-        {
-          title: "Interface",
-          identifier: "interface",
-          icon: <FaSlidersH />,
-          content: <InterfacePage {...ctx} />,
-        },
-      ]}
-    />
-  );
-};

clients/decky/src/steam.ts

@@ -8,16 +8,16 @@
 //
 // TWO shortcuts, both named "Punktfunk" (so they share ONE Steam Input controller-config key —
 // see applyControllerConfig):
-//   • STREAM  — hidden, stateful: the per-session launcher. Its launch options carry the host /
-//     pinned game (PF_HOST/PF_LAUNCH/PF_BROWSE), rewritten per launch, so one shortcut serves
-//     every host. Driven by the QAM/pins/host-library actions. Hidden — an implementation detail.
+//   • STREAM  — hidden, stateful: the per-session launcher. Its launch options carry the host
+//     reference and the card's profile (PF_REF/PF_PROFILE/PF_REQUEST_ACCESS), rewritten per
+//     launch, so one shortcut serves every host. Hidden — an implementation detail.
 //   • GAMEPAD UI — visible, stateless: fixed launch options = bare `--browse` (PF_BROWSE, no
 //     host) → the client's console home (host picker + pairing + settings, gamepad-navigable).
 //     This is the library-visible "Punktfunk" app the user opens directly.
 //
 // Both get the shipped artwork and the native-touch controller config.
 
-import { applyControllerConfig, runnerInfo, shortcutArt, wake } from "./backend";
+import { applyControllerConfig, runnerInfo, shortcutArt } from "./backend";
 
 // SteamClient is a Steam-internal global injected into the CEF context; it is not fully typed
 // by @decky/ui, so declare the surface we use. Signatures verified against MoonDeck + the
@@ -257,11 +257,12 @@ export async function ensureGamepadUiShortcut(): Promise<number | null> {
     }
     const startDir = info.runner.replace(/\/[^/]*$/, "");
     void ensureControllerConfig();
-    // Bare browse: PF_BROWSE with no PF_HOST → the wrapper runs `--browse --fullscreen` (console
-    // home). %command% expands to the shortcut exe (/bin/sh); the wrapper rides behind as an arg.
-    // PF_CLIENT_BIN only when the backend resolved a NATIVE client — else the wrapper's flatpak
-    // default stands and this shortcut is exactly what it always was.
-    const clientBin = info.client_bin ? `PF_CLIENT_BIN=${info.client_bin} ` : "";
+    // PF_BROWSE → the wrapper runs the SESSION's `--browse --fullscreen` (console home), which is
+    // the one branch this rework deliberately left alone. %command% expands to the shortcut exe
+    // (/bin/sh); the wrapper rides behind as an arg. PF_CLIENT_BIN only when the backend resolved
+    // a NATIVE client — else the wrapper's flatpak default stands and this shortcut is exactly
+    // what it always was.
+    const clientBin = safeClientBin(info.client_bin) ? `PF_CLIENT_BIN=${info.client_bin} ` : "";
     const launchOpts = `${clientBin}PF_BROWSE=1 %command% "${info.runner}"`;
 
     // Reuse the remembered entry only if it still exists; a stale appId (deleted shortcut whose
@@ -319,77 +320,81 @@ export async function launchGamepadUi(): Promise<void> {
   }
 }
 
-/** Per-launch extras beyond the host target (all optional — {} is the plain stream). */
+/** Per-launch extras beyond the host reference (all optional — {} is the plain stream). */
 export interface LaunchOpts {
-  /** Library id to launch on connect (a pinned game) — rides PF_LAUNCH → `--launch`. */
-  launchId?: string;
-  /** Open the gamepad library launcher instead of streaming (PF_BROWSE → `--browse`). */
-  browse?: boolean;
-  /** Management-API port for the launcher's library fetch (PF_MGMT; 0/absent = default). */
-  mgmt?: number;
+  /** A pinned card: stream with this settings profile, one-off (PF_PROFILE → `--profile`). */
+  profileId?: string;
+  /**
+   * Ask the host's operator to admit this Deck rather than typing a PIN (PF_REQUEST_ACCESS).
+   * The connect PARKS until somebody approves it, and the launch runs SUPERVISED — see the
+   * wrapper for why `--exec` is dropped on this path alone.
+   */
+  requestAccess?: boolean;
 }
 
-// Launch ids ride Steam launch options as an env-prefix token (`PF_LAUNCH=<id>`), so they
-// must be space/quote-free — Steam's tokenizer and the wrapper's env both break otherwise.
-// Real ids are `steam:<digits>` / `custom:<slug>`, so this rejects nothing in practice;
-// it's VALIDATION, never encoding (the host must match the opaque token verbatim).
-const UNSAFE_LAUNCH_ID = /["'\\$`\s]/;
+// Host refs and profile ids ride Steam launch options as env-prefix tokens (`PF_REF=<ref>`),
+// so they must be space/quote-free — Steam's tokenizer and the wrapper's env both break
+// otherwise. Real values are UUIDs or `addr:port`, so this rejects nothing in practice; it is
+// VALIDATION, never encoding (the client must receive the opaque token verbatim).
+const UNSAFE_TOKEN = /["'\\$`\s]/;
 export function isSafeLaunchId(id: string): boolean {
   return (
     id.length > 0 &&
     id.length <= 128 &&
-    UNSAFE_LAUNCH_ID.exec(id) === null &&
+    UNSAFE_TOKEN.exec(id) === null &&
     /^[\x21-\x7e]+$/.test(id)
   );
 }
 
 /**
- * Launch a stream to `host:port` fullscreen in Gaming Mode (optionally straight into a
- * library title, or into a host's gamepad library). Encodes the target into the STREAM
- * shortcut's launch options (so one hidden shortcut serves every host and every pinned game),
- * then RunGame.
+ * Is a resolved native-client path safe to put in Steam's launch options? Same rule, separate
+ * name because the failure is different: an unsafe id is a bug in our own data, an unsafe path
+ * is just where the user installed the client — so the browse shortcut degrades to its flatpak
+ * default rather than refusing to exist.
  */
-export async function launchStream(
-  host: string,
-  port: number,
-  opts: LaunchOpts = {},
-): Promise<void> {
-  // Wake-on-LAN: if this host is asleep, nudge it awake before the stream connects. Kicked off now
-  // so it races with the shortcut setup (near-zero added latency); its outcome is needed below
-  // (the connect budget), and RunGame follows the await either way, so nothing is slower for it.
-  // Best-effort — the flatpak client's --wake looks up the host's learned MAC (a no-op if none is
-  // known), and the connect that follows has its own retry window, so a failure never blocks launch.
-  const waking = wake(host, port).catch(() => ({ ok: false }));
-  const [{ appId, runner, clientBin }, woke] = await Promise.all([ensureStreamShortcut(), waking]);
-  const target = port && port !== 9777 ? `${host}:${port}` : host;
-  const env = [`PF_HOST=${target}`];
+function safeClientBin(bin: string | undefined): bin is string {
+  return !!bin && isSafeLaunchId(bin);
+}
+
+/**
+ * Stream `ref` fullscreen in Gaming Mode, optionally with a pinned card's profile. Encodes the
+ * target into the STREAM shortcut's launch options — one hidden shortcut serves every host —
+ * then RunGame.
+ *
+ * No Wake-on-LAN here any more. The plugin used to fire a magic packet itself and then stretch
+ * the connect budget to 75 s to cover the host's resume, which was a workaround for the era
+ * before the CLI existed. `punktfunk launch` now runs the real wake-and-wait loop (packet at
+ * t=0, re-sent every 6 s, presence polled every second) and only dials once the host answers —
+ * strictly better, and it deletes a backend method, a frontend call and a shell branch.
+ */
+export async function launchStream(ref: string, opts: LaunchOpts = {}): Promise<void> {
+  if (!isSafeLaunchId(ref)) {
+    throw new Error(`unsupported host reference: ${ref}`);
+  }
+  if (opts.profileId && !isSafeLaunchId(opts.profileId)) {
+    throw new Error(`unsupported profile id: ${opts.profileId}`);
+  }
+  const { appId, runner, clientBin } = await ensureStreamShortcut();
+  const env = [`PF_REF=${ref}`];
   // Set only for a NATIVE client install; absent, the wrapper takes its flatpak default, so every
   // existing Deck install produces byte-identical launch options to before.
   if (clientBin) {
+    // The one launch-option value that comes from the backend rather than a store id, and so
+    // the one that could carry a space: a path like `/home/deck/my apps/punktfunk-client` would
+    // split Steam's tokenizer and land its tail in front of %command% as a bogus env token.
+    if (!isSafeLaunchId(clientBin)) {
+      throw new Error(`client path can't ride Steam's launch options: ${clientBin}`);
+    }
     env.push(`PF_CLIENT_BIN=${clientBin}`);
   }
-  // A magic packet actually went out (a MAC was known), so the host may be mid-resume from
-  // suspend — that takes far longer than the client's default 15 s connect budget. Stretch the
-  // budget so the client's wake-tolerant dial keeps retrying across the resume; against an
-  // already-awake host the connect still lands in under a second, so this costs nothing.
-  if (woke.ok) {
-    env.push("PF_CONNECT_TIMEOUT=75");
+  if (opts.profileId) {
+    env.push(`PF_PROFILE=${opts.profileId}`);
   }
-  if (opts.browse) {
-    env.push("PF_BROWSE=1");
-    if (opts.mgmt) {
-      env.push(`PF_MGMT=${Math.floor(opts.mgmt)}`);
-    }
-  } else if (opts.launchId) {
-    if (!isSafeLaunchId(opts.launchId)) {
-      // Enforced at pin time too (the picker disables Pin) — this is the backstop.
-      throw new Error(`unsupported launch id: ${opts.launchId}`);
-    }
-    env.push(`PF_LAUNCH=${opts.launchId}`);
+  if (opts.requestAccess) {
+    env.push("PF_REQUEST_ACCESS=1");
   }
   // KEY=value ... %command% args — %command% expands to the shortcut exe (/bin/sh); the wrapper
-  // script rides behind it as an argument and reads PF_* from the environment. The wake was
-  // awaited above, so the magic packet is out before the connect attempt.
+  // script rides behind it as an argument and reads PF_* from the environment.
   SteamClient.Apps.SetAppLaunchOptions(appId, `${env.join(" ")} %command% "${runner}"`);
   SteamClient.Apps.RunGame(gameIdFromAppId(appId), "", -1, 100);
 }

clients/decky/src/trust.tsx

@@ -0,0 +1,164 @@
+// The trust sheet — the step between "I can see a host" and "I can stream it".
+//
+// Two ways in, in the order the GTK dialog and the console's pair screen offer them:
+//
+//   • REQUEST ACCESS (default) — no PIN. Save the host with the fingerprint it ADVERTISED,
+//     then launch. The host parks that connect until its operator approves this Deck in the
+//     console or web UI, admits it, and the stream starts by itself. It is not a second
+//     pairing ceremony; it is an ordinary identified connect with a stretched budget, which
+//     is why it costs no ceremony surface here at all.
+//   • USE A PIN INSTEAD — the existing gamepad-navigable keypad (pair.tsx).
+//
+// NO FINGERPRINT, NO REQUEST ACCESS. The parked connect pins the advertised fingerprint, and
+// that pin is the only thing standing between a 185 s wait and an impostor answering for the
+// host. A host typed in by address advertises nothing, so it gets the PIN path only — and is
+// told why, rather than being shown a button that could only fail. Under no circumstances does
+// this sheet trust-on-first-use its way past a missing fingerprint.
+import { DialogButton, Focusable, ModalRoot, Spinner, showModal } from "@decky/ui";
+import { toaster } from "@decky/api";
+import { FC, useRef, useState } from "react";
+import { trustHost } from "./backend";
+import { HostView } from "./hooks";
+import { PairModal } from "./pair";
+
+/** User-facing copy for a `trustHost` failure code. */
+function trustErrorBody(error: string | undefined, name: string): string {
+  switch (error) {
+    case "refused":
+      return `${name} is already saved under a different identity. Forget it in the Punktfunk app before trusting it again.`;
+    case "client-outdated":
+      return "Update the Punktfunk client to use request access.";
+    case "client-unavailable":
+      return "Couldn’t reach the Punktfunk client — is it still installed?";
+    default:
+      return `Couldn’t save ${name}.`;
+  }
+}
+
+export const TrustSheet: FC<{
+  host: HostView;
+  closeModal?: () => void;
+  /** Stream this host, having just been let in. */
+  onStream: (opts: { requestAccess?: boolean }) => void;
+  /** Re-read the host list — the record changed underneath the panel. */
+  onChanged: () => void;
+}> = ({ host, closeModal, onStream, onChanged }) => {
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // ⚠ This sheet is a `showModal` PORTAL: it captures its callbacks ONCE and never re-renders
+  // from panel state. Anything it needs to act on later must be read through a ref, not out of
+  // a captured value — reading a captured array is exactly what made pinning a second game
+  // compute from a stale base and clobber the first.
+  const props = useRef({ host, onStream, onChanged });
+  props.current = { host, onStream, onChanged };
+
+  // Request access pins what the host ADVERTISES. The record's own pin is a different thing:
+  // a host that already has one streams without ever opening this sheet.
+  const hasIdentity = host.advertisedFp !== "";
+  // A host advertising `pair=optional` admits anyone who pins its identity — there is no
+  // operator decision to wait for, and asking for one would be a wait that never ends and a
+  // record claiming somebody approved this Deck when nobody did. `paired` means the PIN
+  // ceremony or a real approval; the desktop client records exactly this case as *trusted*.
+  const needsApproval = host.pairPolicy !== "optional";
+  const canRequestAccess = hasIdentity && needsApproval;
+  const canTrustDirectly = hasIdentity && !needsApproval;
+
+  /**
+   * Pin the advertised identity, then stream.
+   *
+   * `approval` is what differs between the two doors, and it is not cosmetic: it decides whether
+   * the launch waits ~185 s for an operator AND whether the record ends up marked paired.
+   */
+  const letIn = async (approval: boolean) => {
+    setBusy(true);
+    setError(null);
+    const { host: h, onStream: stream, onChanged: changed } = props.current;
+    try {
+      // Step 1: save it with the ADVERTISED fingerprint, pinned but unpaired ("trusted").
+      // Idempotent, so a retry after a declined approval is free.
+      const r = await trustHost(h.addr, h.port, h.advertisedFp, h.name);
+      if (!r.ok) {
+        setError(trustErrorBody(r.error, h.name));
+        setBusy(false);
+        return;
+      }
+      changed();
+      // Step 2: the launch. Under approval it PARKS — and the session's plain connecting screen
+      // looks identical whether it is parked or hanging, so say what is about to happen BEFORE
+      // it starts. That toast is a patch over that, and the real fix belongs in the session.
+      if (approval) {
+        toaster.toast({
+          title: "Punktfunk",
+          body: `Approve this Deck in ${h.name}’s console — the stream starts by itself`,
+          duration: 10_000,
+        });
+      }
+      stream({ requestAccess: approval });
+      closeModal?.();
+    } catch (e) {
+      setError(String(e));
+      setBusy(false);
+    }
+  };
+
+  const usePin = () => {
+    // Hand off to the keypad. Closing first keeps one modal on screen at a time, which is what
+    // the gamepad focus model expects.
+    const { host: h, onStream: stream, onChanged: changed } = props.current;
+    closeModal?.();
+    showModal(
+      <PairModal
+        host={h}
+        onPaired={() => {
+          changed();
+          stream({});
+        }}
+      />,
+    );
+  };
+
+  return (
+    <ModalRoot closeModal={closeModal}>
+      <div style={{ fontWeight: "bold", fontSize: "1.3em", marginBottom: "0.3em" }}>
+        Connect to {host.name}
+      </div>
+      <div style={{ opacity: 0.8, marginBottom: "1em" }}>
+        {!hasIdentity
+          ? "No advertised identity for this host — pair with a PIN instead."
+          : canTrustDirectly
+            ? `${host.name} accepts new devices. Connecting pins its identity so later streams are silent.`
+            : `${host.name} needs to let this device in before it can stream.`}
+      </div>
+      {error && (
+        <div style={{ color: "#ff6b6b", marginBottom: "0.6em" }}>{error}</div>
+      )}
+
+      <Focusable style={{ display: "flex", flexDirection: "column", gap: "0.5em" }}>
+        {canRequestAccess && (
+          <DialogButton disabled={busy} onClick={() => void letIn(true)}>
+            {busy ? <Spinner style={{ height: "1em" }} /> : "Request access"}
+          </DialogButton>
+        )}
+        {canTrustDirectly && (
+          <DialogButton disabled={busy} onClick={() => void letIn(false)}>
+            {busy ? <Spinner style={{ height: "1em" }} /> : "Connect"}
+          </DialogButton>
+        )}
+        <DialogButton disabled={busy} onClick={usePin}>
+          Use a PIN instead…
+        </DialogButton>
+        <DialogButton disabled={busy} onClick={() => closeModal?.()}>
+          Cancel
+        </DialogButton>
+      </Focusable>
+
+      {canRequestAccess && (
+        <div style={{ opacity: 0.6, fontSize: "0.85em", marginTop: "0.8em" }}>
+          Request access asks {host.name}’s operator to approve this Deck in its console or web
+          UI. No PIN to type — the stream starts as soon as they do.
+        </div>
+      )}
+    </ModalRoot>
+  );
+};

clients/decky/src/ui.tsx

@@ -1,46 +0,0 @@
-// Shared UI primitives for the fullscreen page + modals. The one rule that keeps every row
-// looking consistent: a Field's action(s) always sit right-aligned, with real space between
-// them and the label text — never hugging it.
-//
-// Decky lays a Field out as `[ label .......... children ]`. When the children container is
-// grown (`childrenContainerWidth="max"`, which we want so multi-button clusters have room), a
-// bare `fit-content` button LEFT-aligns inside that grown container and ends up pressed against
-// the label with the space wasted to its right. Wrapping the action(s) in `RowActions` pushes
-// them to the right edge and evenly spaces multiples — the same treatment every row now gets.
-import { Focusable } from "@decky/ui";
-import { CSSProperties, FC, ReactNode } from "react";
-
-export const RowActions: FC<{ children: ReactNode }> = ({ children }) => (
-  <Focusable
-    style={{
-      display: "flex",
-      gap: "0.5em",
-      justifyContent: "flex-end",
-      alignItems: "center",
-    }}
-  >
-    {children}
-  </Focusable>
-);
-
-// A single action button sized to its content (not the gamepad-UI default of 100% width), with
-// a floor so short labels ("Pair", "Remove") don't render as tiny nubs and every row's button
-// reads at the same weight.
-export const actionButton: CSSProperties = {
-  width: "fit-content",
-  minWidth: "7em",
-  flexShrink: 0,
-};
-
-// Square icon-only button (details ⓘ, header back arrow). Needs an explicit height or the zero
-// padding collapses it to the icon's line height.
-export const iconButton: CSSProperties = {
-  width: "40px",
-  minWidth: "40px",
-  height: "40px",
-  padding: 0,
-  flexShrink: 0,
-  display: "flex",
-  alignItems: "center",
-  justifyContent: "center",
-};

clients/linux/src/ui_settings.rs

@@ -157,6 +157,20 @@ mod index {
         GAMEPADS.iter().position(|&g| g == s.gamepad).unwrap_or(0) as u32
     }
 
+    pub fn system_buttons(s: &Settings) -> u32 {
+        SYSTEM_BUTTONS
+            .iter()
+            .position(|&v| v == s.system_buttons)
+            .unwrap_or(0) as u32
+    }
+
+    pub fn guide_gesture(s: &Settings) -> u32 {
+        GUIDE_GESTURES
+            .iter()
+            .position(|&v| v == s.guide_gesture)
+            .unwrap_or(0) as u32
+    }
+
     pub fn present_priority(s: &Settings) -> u32 {
         // Unknown values (a newer client's intent) read as the default, exactly as
         // `PresentPriority::resolve` treats them.
@@ -642,6 +656,12 @@ fn commit_profile(active: &StreamProfile, touched: &Touched, values: &Settings)
     if touched.has("gamepad_forwarding") {
         o.gamepad_forwarding = Some(values.gamepad_forwarding);
     }
+    if touched.has("system_buttons") {
+        o.system_buttons = Some(values.system_buttons.clone());
+    }
+    if touched.has("guide_gesture") {
+        o.guide_gesture = Some(values.guide_gesture.clone());
+    }
     if touched.has("stats_verbosity") {
         o.stats_verbosity = Some(values.stats_verbosity());
     }
@@ -687,6 +707,15 @@ const GAMEPADS: &[&str] = &[
     "dualshock4",
     "steamdeck",
 ];
+/// System-button routing values (persisted under the cross-client `system_buttons` key):
+/// where the guide (Xbox/PS/Steam) and quick-access presses land while streaming. Auto =
+/// the host, except under Gaming Mode where the local Steam UI reacts to the same press.
+const SYSTEM_BUTTONS: &[&str] = &["auto", "forward", "local"];
+const SYSTEM_BUTTON_LABELS: &[&str] = &["Automatic", "Send to host", "This device"];
+/// Hold-Select guide gesture values (the cross-client `guide_gesture` key). Auto arms it
+/// only where the raw guide press can't reach the host (Gaming Mode here).
+const GUIDE_GESTURES: &[&str] = &["auto", "on", "off"];
+const GUIDE_GESTURE_LABELS: &[&str] = &["Automatic", "On", "Off"];
 const COMPOSITORS: &[&str] = &["auto", "kwin", "wlroots", "mutter", "gamescope"];
 /// Codec setting values (persisted) paired with their display labels below. PyroWave is
 /// preference-only by design (`Settings::preferred_codec`) — the ladder falls back to
@@ -1542,16 +1571,39 @@ pub fn show_scoped(
             "Steam Deck",
         ],
     );
-    // Both pad rows only mean something while something is being forwarded (the same
+    // Where the guide (Xbox/PS/Steam) + quick-access presses land, and the hold-Select
+    // gesture that keeps the host's guide reachable when they stay local. Desktop rarely
+    // needs either off Automatic — they exist here because profiles are authored on the
+    // desktop and applied everywhere, Gaming Mode included.
+    let sysbtn_row = ChoiceRow::new(
+        &dialog,
+        inline,
+        "Steam / guide button",
+        "Automatic sends it to the host, except where this device reacts to it too",
+        SYSTEM_BUTTON_LABELS,
+    );
+    let gesture_row = ChoiceRow::new(
+        &dialog,
+        inline,
+        "Hold Select for guide",
+        "Hold Select alone for the host's guide button — a tap still goes through",
+        GUIDE_GESTURE_LABELS,
+    );
+    // The pad rows only mean something while something is being forwarded (the same
     // relationship mic → echo cancellation draws just above, initial state included: the
     // seed's `set_active` fires this only when it CHANGES the switch).
     {
         let (f, t) = (forward_row.widget().clone(), pad_row.widget().clone());
+        let (sb, gg) = (sysbtn_row.widget().clone(), gesture_row.widget().clone());
         f.set_sensitive(seed.gamepad_forwarding);
         t.set_sensitive(seed.gamepad_forwarding);
+        sb.set_sensitive(seed.gamepad_forwarding);
+        gg.set_sensitive(seed.gamepad_forwarding);
         pad_forward_row.connect_active_notify(move |r| {
             f.set_sensitive(r.is_active());
             t.set_sensitive(r.is_active());
+            sb.set_sensitive(r.is_active());
+            gg.set_sensitive(r.is_active());
         });
     }
 
@@ -1566,6 +1618,8 @@ pub fn show_scoped(
         bitrate_row.set_value(f64::from(s.bitrate_kbps) / 1000.0);
         pad_forward_row.set_active(s.gamepad_forwarding);
         pad_row.set_selected(index::gamepad(s));
+        sysbtn_row.set_selected(index::system_buttons(s));
+        gesture_row.set_selected(index::guide_gesture(s));
         let touch_i = index::touch(s);
         touch_row.set_selected(touch_i);
         // set_selected never fires the changed hook, so seed the dynamic caption directly.
@@ -1795,6 +1849,18 @@ pub fn show_scoped(
             index::surround
         );
         choice!(pad_row, "gamepad", o.gamepad.is_some(), index::gamepad);
+        choice!(
+            sysbtn_row,
+            "system_buttons",
+            o.system_buttons.is_some(),
+            index::system_buttons
+        );
+        choice!(
+            gesture_row,
+            "guide_gesture",
+            o.guide_gesture.is_some(),
+            index::guide_gesture
+        );
         toggle!(
             pad_forward_row,
             "gamepad_forwarding",
@@ -2001,6 +2067,8 @@ pub fn show_scoped(
         controllers_group.add(forward_row.widget());
     }
     controllers_group.add(pad_row.widget());
+    controllers_group.add(sysbtn_row.widget());
+    controllers_group.add(gesture_row.widget());
     controllers.add(&controllers_group);
 
     // Cap every caption in one pass, after the rows exist: a per-row call would be sixteen
@@ -2040,6 +2108,12 @@ pub fn show_scoped(
             if pad_sel != 0 || GAMEPADS.contains(&s.gamepad.as_str()) {
                 s.gamepad = GAMEPADS[pad_sel].to_string();
             }
+            s.system_buttons = SYSTEM_BUTTONS
+                [(sysbtn_row.selected() as usize).min(SYSTEM_BUTTONS.len() - 1)]
+            .to_string();
+            s.guide_gesture = GUIDE_GESTURES
+                [(gesture_row.selected() as usize).min(GUIDE_GESTURES.len() - 1)]
+            .to_string();
             s.touch_mode =
                 TOUCH_MODES[(touch_row.selected() as usize).min(TOUCH_MODES.len() - 1)].to_string();
             s.mouse_mode =

clients/session/src/main.rs

@@ -18,6 +18,78 @@
 #[cfg(all(any(target_os = "linux", windows), feature = "ui"))]
 mod console;
 
+/// The session control socket: a line-per-connection unix socket other same-user
+/// processes use to poke the RUNNING stream — today two verbs, `guide` and `qam`, which
+/// press the HOST's system buttons (the Decky panel's "Steam menu / Quick access on the
+/// host" buttons; see `GamepadService::tap_guide`). Plain text, no JSON: `<verb>\n` in,
+/// `ok\n` / `err\n` back.
+///
+/// The path is `$XDG_RUNTIME_DIR/punktfunk-session-ctl.sock` — inside the flatpak app
+/// runtime dir (`…/app/$FLATPAK_ID/`) when sandboxed, the ONE runtime path a flatpak and
+/// the host see identically, which is what lets the Decky backend (outside the sandbox)
+/// reach a flatpak-run session.
+#[cfg(all(unix, any(target_os = "linux", windows)))]
+mod ctl_socket {
+    use pf_client_core::gamepad::GamepadService;
+    use std::io::{BufRead, BufReader, Write};
+    use std::os::unix::net::UnixListener;
+    use std::path::PathBuf;
+
+    fn path() -> Option<PathBuf> {
+        let mut p = PathBuf::from(std::env::var_os("XDG_RUNTIME_DIR")?);
+        if let Ok(id) = std::env::var("FLATPAK_ID") {
+            p.push("app");
+            p.push(id);
+        }
+        Some(p.join("punktfunk-session-ctl.sock"))
+    }
+
+    /// Bind + serve on a background thread, once per process (later calls no-op). Any
+    /// failure just logs at debug — the socket is a convenience surface, never worth
+    /// failing a stream over.
+    pub(crate) fn spawn(gamepad: GamepadService) {
+        static ONCE: std::sync::Once = std::sync::Once::new();
+        ONCE.call_once(move || {
+            let Some(path) = path() else { return };
+            // A previous session's socket file refuses the bind — it's ours to replace.
+            let _ = std::fs::remove_file(&path);
+            let listener = match UnixListener::bind(&path) {
+                Ok(l) => l,
+                Err(e) => {
+                    tracing::debug!(error = %e, path = %path.display(), "session ctl socket unavailable");
+                    return;
+                }
+            };
+            let spawned = std::thread::Builder::new()
+                .name("pf-session-ctl".into())
+                .spawn(move || {
+                    for stream in listener.incoming() {
+                        let Ok(mut s) = stream else { continue };
+                        let mut line = String::new();
+                        if BufReader::new(&s).read_line(&mut line).is_err() {
+                            continue;
+                        }
+                        let ok = match line.trim() {
+                            "guide" => {
+                                gamepad.tap_guide();
+                                true
+                            }
+                            "qam" => {
+                                gamepad.tap_qam();
+                                true
+                            }
+                            _ => false,
+                        };
+                        let _ = s.write_all(if ok { b"ok\n" } else { b"err\n" });
+                    }
+                });
+            if let Err(e) = spawned {
+                tracing::debug!(error = %e, "session ctl thread failed to start");
+            }
+        });
+    }
+}
+
 #[cfg(any(target_os = "linux", windows))]
 mod session_main {
     use pf_client_core::gamepad::GamepadService;
@@ -44,14 +116,20 @@ mod session_main {
         std::env::args().any(|a| a == flag)
     }
 
+    /// Running under Gaming Mode (a Deck, or any gamescope session): the environment
+    /// where the local Steam UI owns the physical Steam/QAM buttons — the system-button
+    /// "auto" policy keys off this.
+    pub(crate) fn gaming_mode() -> bool {
+        std::env::var_os("SteamDeck").is_some()
+            || std::env::var_os("GAMESCOPE_WAYLAND_DISPLAY").is_some()
+    }
+
     /// Run fullscreen: `--fullscreen`, or the Deck/gamescope env as a fallback so a
     /// manual launch under Gaming Mode does the right thing too. (Browse-mode only —
     /// gated with `mod browse`, its one caller.)
     #[cfg(feature = "ui")]
     pub(crate) fn fullscreen_mode() -> bool {
-        arg_flag("--fullscreen")
-            || std::env::var_os("SteamDeck").is_some()
-            || std::env::var_os("GAMESCOPE_WAYLAND_DISPLAY").is_some()
+        arg_flag("--fullscreen") || gaming_mode()
     }
 
     /// `--window-pos X,Y` → the window's top-left in desktop coordinates (a spawning
@@ -194,6 +272,20 @@ mod session_main {
         // it back. It goes on before the attach below, so a non-forwarding session never opens
         // — never grabs — the device.
         gamepad.set_forwarding(settings.gamepad_forwarding);
+        // System-button routing: whether raw guide/QAM presses ride the wire, and whether
+        // hold-Select arms as the alternate guide route. Auto keys off Gaming Mode — the
+        // local Steam UI reacts to the same physical buttons there no matter what, so
+        // forwarding raw opens BOTH overlays, the local one on top of the stream. Set
+        // unconditionally for the same browse-mode-reuse reason as the line above.
+        let game_mode = gaming_mode();
+        gamepad.set_system_buttons(
+            settings.system_buttons_forward(game_mode),
+            settings.guide_gesture_enabled(game_mode),
+        );
+        // The control socket (guide/QAM injection — the Decky panel's host buttons).
+        // Spawned at first params-build so it exists for --connect AND console launches.
+        #[cfg(unix)]
+        crate::ctl_socket::spawn(gamepad.clone());
         let mode = Mode {
             width: if settings.width == 0 {
                 native.width

clients/windows/src/app/settings.rs

@@ -79,6 +79,17 @@ const GAMEPADS: &[(&str, &str)] = &[
     // user could not ask the host for the Deck-shaped pad (trackpads, back grips).
     ("steamdeck", "Steam Deck"),
 ];
+/// System-button routing: `(stored value, display label)` — where the guide (Xbox/PS)
+/// and quick-access presses land while streaming. The cross-client `system_buttons` key;
+/// Automatic forwards on desktop and stays local under Gaming Mode.
+const SYSTEM_BUTTONS: &[(&str, &str)] = &[
+    ("auto", "Automatic"),
+    ("forward", "Send to host"),
+    ("local", "This device"),
+];
+/// The hold-Select guide gesture: `(stored value, display label)` — the cross-client
+/// `guide_gesture` key. Automatic arms it only where the raw press can't reach the host.
+const GUIDE_GESTURES: &[(&str, &str)] = &[("auto", "Automatic"), ("on", "On"), ("off", "Off")];
 /// Stats-overlay tiers: `(stored value, display label)` — the cross-client verbosity ladder
 /// (Compact ⊂ Normal ⊂ Detailed); Ctrl+Alt+Shift+S cycles it live in the session window.
 const STATS_TIERS: &[(StatsVerbosity, &str)] = &[
@@ -479,6 +490,8 @@ struct OverrideFlags {
     inhibit_shortcuts: bool,
     gamepad: bool,
     gamepad_forwarding: bool,
+    system_buttons: bool,
+    guide_gesture: bool,
     stats_verbosity: bool,
     fullscreen_on_stream: bool,
     present_priority: bool,
@@ -512,6 +525,8 @@ impl OverrideFlags {
             inhibit_shortcuts: o.inhibit_shortcuts.is_some(),
             gamepad: o.gamepad.is_some(),
             gamepad_forwarding: o.gamepad_forwarding.is_some(),
+            system_buttons: o.system_buttons.is_some(),
+            guide_gesture: o.guide_gesture.is_some(),
             stats_verbosity: o.stats_verbosity.is_some(),
             fullscreen_on_stream: o.fullscreen_on_stream.is_some(),
             present_priority: o.present_priority.is_some(),
@@ -966,6 +981,13 @@ pub(crate) fn settings_page(
                 s.forward_pad = key.unwrap_or_default();
                 s.save();
             })
+            // Dimmed with the master switch above it, like echo cancellation under the mic
+            // (see that row) — this and the three below have nothing to act on while no
+            // controller is forwarded at all. Every commit bumps `rev` and re-renders this
+            // screen, so they follow the toggle live. Brings this client in line with how GTK
+            // (`set_sensitive`), the touch settings on both mobile clients (`enabled`) and the
+            // console UI (dim + refuse the step) have always drawn the same relationship.
+            .enabled(s.gamepad_forwarding)
     };
     let pad_forward_toggle =
         setting_toggle(ctx, scope, (rev, set_rev), s.gamepad_forwarding, |s, on| {
@@ -976,7 +998,32 @@ pub(crate) fn settings_page(
     });
     let pad_combo = setting_combo(ctx, scope, (rev, set_rev), pad_names, pad_i, |s, i| {
         s.gamepad = GAMEPADS[i].0.to_string();
-    });
+    })
+    .enabled(s.gamepad_forwarding);
+    let (sysbtn_names, sysbtn_i) = presets(SYSTEM_BUTTONS, |v| *v == s.system_buttons);
+    let sysbtn_combo = setting_combo(
+        ctx,
+        scope,
+        (rev, set_rev),
+        sysbtn_names,
+        sysbtn_i,
+        |s, i| {
+            s.system_buttons = SYSTEM_BUTTONS[i].0.to_string();
+        },
+    )
+    .enabled(s.gamepad_forwarding);
+    let (gesture_names, gesture_i) = presets(GUIDE_GESTURES, |v| *v == s.guide_gesture);
+    let gesture_combo = setting_combo(
+        ctx,
+        scope,
+        (rev, set_rev),
+        gesture_names,
+        gesture_i,
+        |s, i| {
+            s.guide_gesture = GUIDE_GESTURES[i].0.to_string();
+        },
+    )
+    .enabled(s.gamepad_forwarding);
     let (touch_names, touch_i) = presets(TOUCH_MODES, |v| *v == s.touch_mode);
     let touch_combo = setting_combo(ctx, scope, (rev, set_rev), touch_names, touch_i, |s, i| {
         s.touch_mode = TOUCH_MODES[i].0.to_string();
@@ -1407,6 +1454,30 @@ pub(crate) fn settings_page(
                          \u{2014} a DualSense keeps adaptive triggers, lightbar, touchpad and \
                          motion.",
                     )),
+                    Some(described_overridable(
+                        (rev, set_rev),
+                        scope,
+                        "system_buttons",
+                        "Steam / guide button",
+                        over.system_buttons,
+                        sysbtn_combo,
+                        "Where the guide (Xbox/PS) and quick-access presses go while \
+                         streaming. Automatic sends them to the host \u{2014} except on \
+                         devices whose own overlay reacts to the same press (Gaming Mode), \
+                         where they stay local and the gesture below reaches the host.",
+                    )),
+                    Some(described_overridable(
+                        (rev, set_rev),
+                        scope,
+                        "guide_gesture",
+                        "Hold Select for guide",
+                        over.guide_gesture,
+                        gesture_combo,
+                        "Hold Select on its own to press the host's guide button \u{2014} keep \
+                         holding for a Gaming-Mode host's quick-access menu. A Select tap \
+                         still goes through, slightly delayed. Automatic arms it only where \
+                         the real button can't reach the host.",
+                    )),
                 ]
                 .into_iter()
                 .flatten()

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

@@ -4,6 +4,8 @@
 //! cards and flip a saved host's online pip when its advert disappears.
 
 use mdns_sd::{ServiceDaemon, ServiceEvent};
+use std::collections::BTreeMap;
+use std::time::{Duration, Instant};
 
 #[derive(Clone, Debug)]
 pub struct DiscoveredHost {
@@ -31,6 +33,19 @@ pub struct DiscoveredHost {
     pub os: String,
 }
 
+impl DiscoveredHost {
+    /// The host's advertised stable id (mDNS TXT `id`), or `""` when it doesn't advertise one.
+    /// [`DiscoveredHost::key`] falls back to the mDNS fullname in that case, so the two being
+    /// equal is exactly the "no id" signal — read it through here rather than re-deriving it.
+    pub fn advertised_id(&self) -> &str {
+        if self.key == self.fullname {
+            ""
+        } else {
+            &self.key
+        }
+    }
+}
+
 /// One discovery update for the UI's advert map.
 pub enum DiscoveryEvent {
     /// A host advert appeared or refreshed (new address, pairing flipped, …).
@@ -39,8 +54,8 @@ pub enum DiscoveryEvent {
     Removed { fullname: String },
 }
 
-/// Browse continuously for the app's lifetime. The thread exits when the receiver is
-/// dropped (the send fails) or the daemon dies.
+/// Browse continuously. The worker exits when the returned receiver is dropped, or when the
+/// daemon dies — checked on a tick, so it stops even on a LAN where no advert ever arrives.
 pub fn browse() -> async_channel::Receiver<DiscoveryEvent> {
     let (tx, rx) = async_channel::unbounded();
     std::thread::Builder::new()
@@ -60,7 +75,24 @@ pub fn browse() -> async_channel::Receiver<DiscoveryEvent> {
                     return;
                 }
             };
-            while let Ok(event) = receiver.recv() {
+            // Polled rather than blocked on: the worker has to notice that its consumer went
+            // away even when NOTHING is arriving, which is the normal state of a LAN with no
+            // hosts on it. A plain `recv()` parks forever there, and the ignored-event arm below
+            // never touches `tx` — so a bounded consumer like `discover_for` would leak this
+            // thread and its daemon (another thread, and a socket bound to :5353) on every call.
+            loop {
+                // Checked at the TOP so it also covers the arms below that `continue` without
+                // ever touching `tx` — the ignored event kinds, and an advert with no IPv4
+                // address. Those are the paths that would otherwise keep this thread alive with
+                // nobody to send to.
+                if tx.is_closed() {
+                    break;
+                }
+                let event = match receiver.recv_timeout(Duration::from_millis(250)) {
+                    Ok(event) => event,
+                    Err(_) if receiver.is_disconnected() => break,
+                    Err(_) => continue,
+                };
                 let update = match event {
                     ServiceEvent::ServiceResolved(info) => {
                         let props = info.get_properties();
@@ -117,3 +149,154 @@ pub fn browse() -> async_channel::Receiver<DiscoveryEvent> {
         .expect("spawn mdns thread");
     rx
 }
+
+/// The advert map one browse window folded down to. Kept separate from [`discover_for`] so the
+/// fold — which is where dedupe and removal actually live — is testable without a network.
+type Adverts = BTreeMap<String, DiscoveredHost>;
+
+/// Apply one event to the map. A refreshed advert WINS over the one already there (it carries
+/// the newer address — a host that changed DHCP lease re-announces), and a removal drops
+/// whichever entry that mDNS fullname produced, whatever it was keyed under.
+fn fold(adverts: &mut Adverts, event: DiscoveryEvent) {
+    match event {
+        DiscoveryEvent::Resolved(host) => {
+            adverts.insert(host.key.clone(), host);
+        }
+        DiscoveryEvent::Removed { fullname } => {
+            adverts.retain(|_, h| h.fullname != fullname);
+        }
+    }
+}
+
+/// Browse for `timeout`, then return what answered — deduped by `key`, address-sorted.
+///
+/// Blocking; intended for one-shot consumers (the CLI's `discover` verb, a plugin backend that
+/// wants one bounded call rather than a stream). The streaming [`browse`] stays the UI's door:
+/// a live hosts page wants adverts as they land, not a snapshot taken `timeout` after it opened.
+pub fn discover_for(timeout: Duration) -> Vec<DiscoveredHost> {
+    let rx = browse();
+    let deadline = Instant::now() + timeout;
+    let mut adverts = Adverts::new();
+    while Instant::now() < deadline {
+        while let Ok(event) = rx.try_recv() {
+            fold(&mut adverts, event);
+        }
+        // A short tick rather than a blocking recv with a deadline: `async_channel`'s blocking
+        // receive has no timeout, and the whole point of this call is that it is bounded.
+        std::thread::sleep(Duration::from_millis(50).min(timeout));
+    }
+    while let Ok(event) = rx.try_recv() {
+        fold(&mut adverts, event);
+    }
+    // Dropping the receiver is what stops the worker — it polls for that, so this holds even
+    // when nothing is advertising. Without it a one-shot consumer would leak a browse per call.
+    drop(rx);
+    sorted(adverts)
+}
+
+/// The map as the list a caller gets: sorted by address, then port. IPv4 is compared
+/// NUMERICALLY (a lexical sort puts `.10` before `.9`, which reads as scrambled in a host list).
+fn sorted(adverts: Adverts) -> Vec<DiscoveredHost> {
+    let mut hosts: Vec<DiscoveredHost> = adverts.into_values().collect();
+    hosts.sort_by_key(|h| {
+        (
+            h.addr.parse::<std::net::Ipv4Addr>().ok().map(u32::from),
+            h.addr.clone(),
+            h.port,
+        )
+    });
+    hosts
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn host(key: &str, fullname: &str, addr: &str) -> DiscoveredHost {
+        DiscoveredHost {
+            key: key.into(),
+            fullname: fullname.into(),
+            name: fullname.split('.').next().unwrap_or("?").into(),
+            addr: addr.into(),
+            port: 9777,
+            fp_hex: "aa".into(),
+            pair: "required".into(),
+            mgmt_port: Some(47990),
+            mac: vec![],
+            os: String::new(),
+        }
+    }
+
+    /// Two adverts for the same host collapse to one row, and the LATER one wins — that is how
+    /// a host that moved to a new address stops being listed at the stale one.
+    #[test]
+    fn refreshed_advert_supersedes_the_earlier_one() {
+        let mut adverts = Adverts::new();
+        fold(
+            &mut adverts,
+            DiscoveryEvent::Resolved(host("id-1", "desk._punktfunk._udp.local.", "192.168.1.9")),
+        );
+        fold(
+            &mut adverts,
+            DiscoveryEvent::Resolved(host("id-1", "desk._punktfunk._udp.local.", "192.168.1.20")),
+        );
+        let out = sorted(adverts);
+        assert_eq!(out.len(), 1, "same key must not render twice");
+        assert_eq!(out[0].addr, "192.168.1.20", "the newer address wins");
+    }
+
+    /// A host that goes away during the browse window is not in the answer.
+    #[test]
+    fn removal_drops_the_advert_it_names() {
+        let mut adverts = Adverts::new();
+        fold(
+            &mut adverts,
+            DiscoveryEvent::Resolved(host("id-1", "desk._punktfunk._udp.local.", "192.168.1.9")),
+        );
+        fold(
+            &mut adverts,
+            DiscoveryEvent::Resolved(host("id-2", "tv._punktfunk._udp.local.", "192.168.1.10")),
+        );
+        fold(
+            &mut adverts,
+            DiscoveryEvent::Removed {
+                fullname: "desk._punktfunk._udp.local.".into(),
+            },
+        );
+        let out = sorted(adverts);
+        assert_eq!(out.len(), 1);
+        assert_eq!(out[0].key, "id-2");
+    }
+
+    /// A host with no `id` TXT is keyed by its fullname — and must not then report that
+    /// fullname as an id, which would send a caller launching against a nonexistent reference.
+    #[test]
+    fn advertised_id_is_empty_without_the_txt() {
+        let named = host("id-1", "desk._punktfunk._udp.local.", "10.0.0.1");
+        assert_eq!(named.advertised_id(), "id-1");
+        let anonymous = host(
+            "desk._punktfunk._udp.local.",
+            "desk._punktfunk._udp.local.",
+            "10.0.0.1",
+        );
+        assert_eq!(anonymous.advertised_id(), "");
+    }
+
+    /// Addresses sort the way a person reads them, not the way strings compare.
+    #[test]
+    fn addresses_sort_numerically() {
+        let mut adverts = Adverts::new();
+        for (i, addr) in ["192.168.1.20", "192.168.1.9", "192.168.1.100"]
+            .into_iter()
+            .enumerate()
+        {
+            fold(
+                &mut adverts,
+                DiscoveryEvent::Resolved(host(&format!("id-{i}"), &format!("h{i}."), addr)),
+            );
+        }
+        let out = sorted(adverts);
+        let addrs: Vec<&str> = out.iter().map(|h| h.addr.as_str()).collect();
+        assert_eq!(addrs, ["192.168.1.9", "192.168.1.20", "192.168.1.100"]);
+    }
+}

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

@@ -61,6 +61,23 @@ const ESCAPE_CHORD: [u32; 4] = [wire::BTN_LB, wire::BTN_RB, wire::BTN_START, wir
 /// Hold the [`ESCAPE_CHORD`] at least this long to disconnect (escalates the leave-fullscreen press).
 const DISCONNECT_HOLD: Duration = Duration::from_millis(1500);
 
+/// Hold Select/Back ALONE at least this long to send the HOST the guide button — the
+/// [`SelectGesture`], armed by [`Settings::guide_gesture`]. The synthetic guide stays down
+/// for as long as Select is held, so a long hold IS the host's long-press (the QAM on a
+/// Gaming-Mode host). Exists because on some platforms the physical guide press can never
+/// reach the host cleanly: the local shell reserves it (iOS's Game Overlay, tvOS) or
+/// reacts to it in parallel (Gaming Mode's Steam UI — see [`Settings::system_buttons`]).
+///
+/// [`Settings::guide_gesture`]: crate::trust::Settings::guide_gesture
+/// [`Settings::system_buttons`]: crate::trust::Settings::system_buttons
+const GUIDE_HOLD: Duration = Duration::from_millis(350);
+
+/// A held-back Select TAP is delivered as a press with its release scheduled this far
+/// behind — never back-to-back: per-transition sends are folded into seq'd `GamepadState`
+/// snapshots by the core input task, and a down+up inside one fold window can coalesce
+/// into no press at all.
+const TAP_PRESS: Duration = Duration::from_millis(50);
+
 /// Steam Deck actuator-decay keepalive cadence, declared to the core's rumble policy engine as an
 /// [`ActuatorQuirks`] at slot open. The Deck's built-in actuator decays inside SDL's ~2 s internal
 /// rumble resend (`SDL_RUMBLE_RESEND_MS`) and SDL short-circuits an identical `set_rumble` value
@@ -285,6 +302,21 @@ fn set_valve_hidapi(enabled: bool) {
     sdl3::hint::set("SDL_JOYSTICK_HIDAPI_STEAM", v);
 }
 
+/// Disable the Valve HIDAPI drivers **before SDL exists** — call this alongside the other
+/// pre-`SDL_Init` hints, not after a subsystem is up.
+///
+/// The damage these drivers do happens at *enumeration*, which is part of initialising the
+/// joystick/gamepad subsystem. Setting the hint afterwards does detach the driver, but only after
+/// it has already sent the Deck its `ID_CLEAR_DIGITAL_MAPPINGS` + `TRACKPAD_NONE` — so the
+/// built-in trackpad-mouse dies system-wide and stays dead until the firmware watchdog restores
+/// lizard mode seconds later. The threaded worker ([`run`]) has always done this in the right
+/// order; the caller-pumped path could not, because by the time it receives a
+/// [`sdl3::GamepadSubsystem`] the enumeration has already happened. Hence a separate entry point
+/// its callers can put in the right place.
+pub fn preinit_disable_valve_hidapi() {
+    set_valve_hidapi(false);
+}
+
 /// Map the SDL-reported controller type to the virtual pad we'd ask the host to create.
 fn pref_for_type(t: sdl3::gamepad::GamepadType) -> GamepadPref {
     use sdl3::gamepad::GamepadType as T;
@@ -337,6 +369,8 @@ enum Ctl {
     Pin(Option<String>),
     KindOverride(GamepadPref),
     Forwarding(bool),
+    SystemButtons { forward_raw: bool, gesture: bool },
+    TapButton(u32),
     MenuMode(bool),
     MenuRumble(MenuPulse),
 }
@@ -393,9 +427,12 @@ impl GamepadService {
     /// and calls [`GamepadPump::tick`] once per loop iteration (the threaded worker's
     /// per-wakeup work: ctl drain, chord-hold check, menu repeat, feedback).
     ///
-    /// Like the threaded worker, this disables the Valve HIDAPI drivers up front (their
-    /// mere enumeration kills the Deck's trackpad-mouse system-wide); they are enabled
-    /// for the duration of an attached session only.
+    /// The Valve HIDAPI drivers are held off here too, but this is **too late to be the only
+    /// place it happens**: the `subsystem` argument means enumeration is already done, and that
+    /// is when the Deck driver kills the trackpad-mouse. The caller must also call
+    /// [`preinit_disable_valve_hidapi`] with its other pre-`SDL_Init` hints. This call still
+    /// earns its place — it re-asserts "off" for a process that ran a session earlier — but on
+    /// its own it only detaches a driver that has already done the damage.
     pub fn pumped(subsystem: sdl3::GamepadSubsystem) -> (GamepadService, GamepadPump) {
         set_valve_hidapi(false);
         let pads = Arc::new(Mutex::new(Vec::new()));
@@ -503,6 +540,39 @@ impl GamepadService {
         let _ = self.ctl.send(Ctl::Forwarding(on));
     }
 
+    /// The session's system-button policy, resolved from
+    /// [`Settings::system_buttons_forward`] × [`Settings::guide_gesture_enabled`]:
+    /// `forward_raw` gates the physical guide/QAM presses onto the wire (off = they stay
+    /// with the local shell — the Gaming-Mode default, where Steam reacts to them no
+    /// matter what and forwarding opens BOTH overlays); `gesture` arms the hold-Select
+    /// guide gesture ([`GUIDE_HOLD`]), the alternate route that keeps the host's guide —
+    /// and, held longer, a Gaming-Mode host's QAM — reachable from a controller.
+    ///
+    /// [`Settings::system_buttons_forward`]: crate::trust::Settings::system_buttons_forward
+    /// [`Settings::guide_gesture_enabled`]: crate::trust::Settings::guide_gesture_enabled
+    pub fn set_system_buttons(&self, forward_raw: bool, gesture: bool) {
+        let _ = self.ctl.send(Ctl::SystemButtons {
+            forward_raw,
+            gesture,
+        });
+    }
+
+    /// One-shot synthetic tap of the HOST's guide button ([`Ctl::TapButton`]): down now,
+    /// up [`TAP_PRESS`] later, on the first forwarded slot's wire index (pad 0 when none
+    /// is open). The session control socket's "press the host's Steam/guide button" verb
+    /// — the Decky panel's UI route to the host overlay. No-op while no session is
+    /// attached.
+    pub fn tap_guide(&self) {
+        let _ = self.ctl.send(Ctl::TapButton(wire::BTN_GUIDE));
+    }
+
+    /// Like [`Self::tap_guide`] for the quick-access button (`MISC1` — the Deck `…`).
+    /// Opens the QAM on a Gaming-Mode host whose virtual pad is Deck-shaped; other
+    /// virtual pads map it to their own misc button (or drop it) — harmless.
+    pub fn tap_qam(&self) {
+        let _ = self.ctl.send(Ctl::TapButton(wire::BTN_MISC1));
+    }
+
     pub fn attach(&self, connector: Arc<NativeClient>) {
         let _ = self.ctl.send(Ctl::Attach(connector));
     }
@@ -552,10 +622,43 @@ impl GamepadPump {
     /// chord-hold and haptics inside the threaded worker's tolerances).
     pub fn tick(&mut self) {
         let _ = self.worker.drain_ctl(&self.ctl_rx);
+        self.worker.gesture_poll();
         self.worker.maybe_fire_disconnect();
         self.worker.menu_poll();
         self.worker.render_feedback();
     }
+
+    /// Close every forwarded slot — flush its held wire state, tell the host to remove the pad,
+    /// and physically silence it. Call once on the way out of the caller's event loop.
+    ///
+    /// [`GamepadService::detach`] only *posts* `Ctl::Detach`; the close — the flush, the host-side
+    /// `GamepadRemove`, and the explicit `set_rumble(0, 0)` backstop in `close_slot_at` — happens
+    /// when the pump next drains it. An exit path that detached and then left the loop without
+    /// another [`tick`](Self::tick) therefore skipped all of it, and nothing else would: the slots
+    /// hold no `Drop` that silences them. A pad left mid-buzz stayed buzzing.
+    ///
+    /// This closes the slots directly rather than draining the queued `Ctl::Detach` that would
+    /// have done it. Same physical outcome by a shorter path, and deliberately so: this also runs
+    /// from `Drop`, and `drain_ctl` reaches `Mutex::lock().unwrap()`, which on a poisoned lock
+    /// would panic — during an unwind that aborts the process. Closing a slot touches no lock.
+    ///
+    /// Idempotent, and safe with nothing attached.
+    pub fn shutdown(&mut self) {
+        self.worker.close_all_slots();
+    }
+}
+
+/// The silence backstop of last resort. A caller's loop can also leave by `?` on a fatal overlay
+/// or present error — several paths do — and those would skip an explicit
+/// [`shutdown`](GamepadPump::shutdown) entirely, leaving a forwarded pad buzzing on the way out.
+///
+/// Callers should still call `shutdown` at their normal exit rather than lean on this: the pad
+/// wants to go quiet *before* a long teardown (session join, `vkDeviceWaitIdle`), not after it.
+/// Doing both is free — `shutdown` is idempotent.
+impl Drop for GamepadPump {
+    fn drop(&mut self) {
+        self.shutdown();
+    }
 }
 
 /// The lowest wire pad index (0..[`MAX_PADS`](punktfunk_core::input::MAX_PADS)) not already held
@@ -629,13 +732,27 @@ fn axis_value(axis: sdl3::gamepad::Axis, v: i16) -> (u32, i32) {
 /// host parses off its virtual pad; the wire's 11-byte trigger blocks drop in verbatim.
 /// Enable bits select only the fields each update touches, so rumble (driven separately
 /// through SDL) and untouched fields keep their state.
+///
+/// The offsets below are the USB output report's, **minus one**: SDL's payload carries no leading
+/// report id. `pf-inject`'s `dualsense_proto::out_report` is where that layout is written down and
+/// explained (including the Bluetooth `+2` base), but this crate cannot import it — `pf-inject` is
+/// host-side and neither crate depends on the other, and a DualSense report layout has no business
+/// in `punktfunk-core`, the only crate they share. So this is a deliberate second copy, and
+/// [`ds5_offsets_track_the_usb_report`](ds5_feedback_tests) pins the `−1` relationship rather than
+/// leaving it to a comment.
 struct Ds5Feedback;
 
 impl Ds5Feedback {
-    const RIGHT_TRIGGER: usize = 10;
-    const LEFT_TRIGGER: usize = 21;
-    const PAD_LIGHTS: usize = 43;
-    const LED_RGB: usize = 44;
+    /// The USB report offsets these are derived from — see the type doc. Kept beside the derived
+    /// values so the subtraction is visible at the point of definition.
+    const REPORT_ID_LEN: usize = 1;
+    const RIGHT_TRIGGER: usize = 11 - Self::REPORT_ID_LEN;
+    const LEFT_TRIGGER: usize = 22 - Self::REPORT_ID_LEN;
+    const PAD_LIGHTS: usize = 44 - Self::REPORT_ID_LEN;
+    const LED_RGB: usize = 45 - Self::REPORT_ID_LEN;
+    /// One adaptive-trigger parameter block: a mode byte plus 10 parameters. Mirrors
+    /// `PUNKTFUNK_HID_EFFECT_MAX`, which is the same number at the C-ABI boundary.
+    const TRIGGER_LEN: usize = punktfunk_core::abi::PUNKTFUNK_HID_EFFECT_MAX as usize;
 
     fn trigger_packet(which: u8, effect: &[u8]) -> [u8; 47] {
         let mut p = [0u8; 47];
@@ -645,7 +762,7 @@ impl Ds5Feedback {
             (0x08, Self::LEFT_TRIGGER)
         };
         p[0] = flag;
-        let n = effect.len().min(11);
+        let n = effect.len().min(Self::TRIGGER_LEN);
         p[off..off + n].copy_from_slice(&effect[..n]);
         p
     }
@@ -698,6 +815,9 @@ struct Slot {
     /// close lift a click held across detach/unplug.
     held_clicks: [bool; 2],
     last_accel: [i16; 3],
+    /// Hold-Select→guide state ([`SelectGesture`]) — only fed while the worker's
+    /// `guide_gesture` policy is on.
+    gesture: SelectGesture,
 }
 
 impl Slot {
@@ -713,6 +833,7 @@ impl Slot {
             surface_last: [(0, 0, false); 2],
             held_clicks: [false; 2],
             last_accel: [0; 3],
+            gesture: SelectGesture::default(),
         }
     }
 
@@ -723,6 +844,98 @@ impl Slot {
     }
 }
 
+/// Per-slot hold-Select→guide state machine (see [`GUIDE_HOLD`]). Pure — fed transitions
+/// and polled with a clock, it emits the wire sends due as `(button bit, down)` pairs —
+/// so the timing rules are testable without SDL or a live session.
+///
+/// The rules:
+/// - Select pressed ALONE is held back (pending). Any other button already down means
+///   Select is part of a combo — the escape chord ends in it — and passes through.
+/// - A button pressed WHILE Select is pending makes it a real Select after all; its
+///   deferred down goes out first, preserving chronology.
+/// - Pending past [`GUIDE_HOLD`] becomes a synthetic guide, down until Select releases.
+/// - Released before the threshold, it's a TAP: press delivered on release, the release
+///   itself [`TAP_PRESS`] behind it (back-to-back transitions can fold into nothing).
+#[derive(Default)]
+struct SelectGesture {
+    /// Select is down and held back — tap-or-guide undecided.
+    pending_since: Option<Instant>,
+    /// The held-back Select became a synthetic guide; its release lifts the guide.
+    as_guide: bool,
+    /// A delivered tap's release is owed at this time.
+    release_due: Option<Instant>,
+}
+
+impl SelectGesture {
+    /// Select went down (`alone` = no other button held on this slot). Returns true when
+    /// the press is held back; false lets the caller forward it as a normal button.
+    fn on_select_down(&mut self, now: Instant, alone: bool, out: &mut Vec<(u32, bool)>) -> bool {
+        // A previous tap's scheduled release still owed: lift it before the new press.
+        if self.release_due.take().is_some() {
+            out.push((wire::BTN_BACK, false));
+        }
+        if alone {
+            self.pending_since = Some(now);
+            return true;
+        }
+        false
+    }
+
+    /// Another button went down on this slot: a pending Select is a real Select after
+    /// all — its deferred down goes out before the caller sends the new button's.
+    fn on_other_down(&mut self, out: &mut Vec<(u32, bool)>) {
+        if self.pending_since.take().is_some() {
+            out.push((wire::BTN_BACK, true));
+        }
+    }
+
+    /// Select released. Returns true when the gesture owned this release (the caller
+    /// skips the normal button-up send).
+    fn on_select_up(&mut self, now: Instant, out: &mut Vec<(u32, bool)>) -> bool {
+        if self.as_guide {
+            self.as_guide = false;
+            out.push((wire::BTN_GUIDE, false));
+            return true;
+        }
+        if self.pending_since.take().is_some() {
+            // A tap: deliver the held-back press now, its release TAP_PRESS behind.
+            out.push((wire::BTN_BACK, true));
+            self.release_due = Some(now + TAP_PRESS);
+            return true;
+        }
+        false
+    }
+
+    /// Clock-driven work: the hold threshold and the owed tap release.
+    fn poll(&mut self, now: Instant, out: &mut Vec<(u32, bool)>) {
+        if let Some(since) = self.pending_since {
+            if now.duration_since(since) >= GUIDE_HOLD {
+                self.pending_since = None;
+                self.as_guide = true;
+                out.push((wire::BTN_GUIDE, true));
+            }
+        }
+        if let Some(due) = self.release_due {
+            if now >= due {
+                self.release_due = None;
+                out.push((wire::BTN_BACK, false));
+            }
+        }
+    }
+
+    /// Slot close / gesture disarm: nothing may stay down (or owed) on the wire.
+    fn flush(&mut self, out: &mut Vec<(u32, bool)>) {
+        self.pending_since = None;
+        if self.as_guide {
+            self.as_guide = false;
+            out.push((wire::BTN_GUIDE, false));
+        }
+        if self.release_due.take().is_some() {
+            out.push((wire::BTN_BACK, false));
+        }
+    }
+}
+
 struct Worker {
     subsystem: sdl3::GamepadSubsystem,
     /// UI-facing state (the `GamepadService` accessors): pad list, active pad, pin.
@@ -750,6 +963,14 @@ struct Worker {
     /// `Auto` = per-pad detection. Applied at slot open to the kind DECLARED to the host, never
     /// to [`Slot::pref`] — the local feedback paths must keep reading the physical pad.
     kind_override: GamepadPref,
+    /// Forward raw guide/QAM presses ([`GamepadService::set_system_buttons`]); off keeps
+    /// them with the local shell.
+    system_forward: bool,
+    /// The hold-Select guide gesture is armed ([`GamepadService::set_system_buttons`]).
+    guide_gesture: bool,
+    /// Releases owed for synthetic taps ([`Ctl::TapButton`]): `(pad, bit, due)` — the
+    /// down went out on receipt, the up goes out from the poll once `due` passes.
+    synthetic_ups: Vec<(u8, u32, Instant)>,
     attached: Option<Arc<NativeClient>>,
     /// Raises the UI escape signal; the escape chord fires it once per press.
     escape_tx: async_channel::Sender<()>,
@@ -1003,6 +1224,7 @@ impl Worker {
         // unplug) must not depend on what SDL does to a rumbling device at close. Errors are
         // expected for an already-unplugged pad.
         let _ = self.slots[i].pad.set_rumble(0, 0, 100);
+        Self::reset_slot_feedback(&mut self.slots[i]);
         if let Some(c) = self.attached.clone() {
             Self::flush_slot(&c, &mut self.slots[i]);
             // Signal the host to tear down this pad's virtual device (native hot-unplug). Sent
@@ -1018,6 +1240,35 @@ impl Worker {
         );
     }
 
+    /// Hand the physical controller back in a neutral state before its handle closes.
+    ///
+    /// Rumble stops on its own the moment nothing renews it, but the rich planes do not: an
+    /// adaptive-trigger effect and a lightbar colour are LATCHED in the pad's firmware and survive
+    /// the stream, the app, and being unplugged. Ending a session on a weapon's trigger resistance
+    /// left the physical trigger stiff on the desktop afterwards, with nothing to clear it but
+    /// another game. Apple's client already resets on teardown; this is the desktop half.
+    ///
+    /// Best-effort throughout: the pad may already be gone (that is one of the ways we get here).
+    fn reset_slot_feedback(slot: &mut Slot) {
+        if matches!(
+            slot.pref,
+            GamepadPref::DualSense | GamepadPref::DualSenseEdge
+        ) {
+            // An all-zero trigger block is mode 0x00 — no effect — which is what releases the
+            // trigger. Both sides, then the lightbar dark and the player indicator clear.
+            for which in [0u8, 1] {
+                let _ = slot
+                    .pad
+                    .send_effect(&Ds5Feedback::trigger_packet(which, &[0u8; 11]));
+            }
+            let _ = slot.pad.send_effect(&Ds5Feedback::lightbar_packet(0, 0, 0));
+            let _ = slot.pad.send_effect(&Ds5Feedback::player_packet(0));
+        } else {
+            // Anything else with an LED goes dark through SDL, which owns the per-device details.
+            let _ = slot.pad.set_led(0, 0, 0);
+        }
+    }
+
     fn close_all_slots(&mut self) {
         while !self.slots.is_empty() {
             self.close_slot_at(0);
@@ -1051,6 +1302,14 @@ impl Worker {
     /// Emits wire events only (no SDL device calls), so it is safe against an already-removed pad.
     fn flush_slot(c: &NativeClient, slot: &mut Slot) {
         let pad = slot.index;
+        // Gesture first: a synthetic guide is NOT in `held_buttons`, so the drain below
+        // would never lift it — and a still-pending Select was never sent, so dropping
+        // it beats delivering a ghost press into the close.
+        let mut due = Vec::new();
+        slot.gesture.flush(&mut due);
+        for (b, down) in due {
+            send(c, InputKind::GamepadButton, b, down as i32, pad);
+        }
         for b in slot.held_buttons.drain(..) {
             send(c, InputKind::GamepadButton, b, 0, pad);
         }
@@ -1128,6 +1387,36 @@ impl Worker {
         }
     }
 
+    /// Clock-driven [`SelectGesture`] work — the hold threshold and owed tap releases —
+    /// polled like the chord hold, so timings carry at most one wakeup (~10 ms attached)
+    /// of jitter.
+    fn gesture_poll(&mut self) {
+        let Some(c) = self.attached.clone() else {
+            self.synthetic_ups.clear();
+            return;
+        };
+        let now = Instant::now();
+        // Owed releases of synthetic taps (the control socket's guide/QAM verbs).
+        self.synthetic_ups.retain(|&(pad, bit, due)| {
+            if now >= due {
+                send(&c, InputKind::GamepadButton, bit, 0, pad);
+                false
+            } else {
+                true
+            }
+        });
+        if !self.guide_gesture {
+            return;
+        }
+        for slot in &mut self.slots {
+            let mut due = Vec::new();
+            slot.gesture.poll(now, &mut due);
+            for (b, down) in due {
+                send(&c, InputKind::GamepadButton, b, down as i32, slot.index);
+            }
+        }
+    }
+
     /// Fire the disconnect signal once the escape chord has been continuously held past
     /// [`DISCONNECT_HOLD`]. Polled from the main loop so the hold completes without new events.
     fn maybe_fire_disconnect(&mut self) {
@@ -1305,6 +1594,41 @@ impl Worker {
                     self.refresh_active();
                 }
                 Ok(Ctl::KindOverride(pref)) => self.kind_override = pref,
+                Ok(Ctl::SystemButtons {
+                    forward_raw,
+                    gesture,
+                }) => {
+                    self.system_forward = forward_raw;
+                    if self.guide_gesture == gesture {
+                        continue;
+                    }
+                    self.guide_gesture = gesture;
+                    // A mid-session flip may strand gesture state — a synthetic guide
+                    // still down, an owed tap release — lift it now (no-op on the way on:
+                    // an unarmed gesture was never fed).
+                    if let Some(c) = self.attached.clone() {
+                        for slot in &mut self.slots {
+                            let mut due = Vec::new();
+                            slot.gesture.flush(&mut due);
+                            for (b, down) in due {
+                                send(&c, InputKind::GamepadButton, b, down as i32, slot.index);
+                            }
+                        }
+                    }
+                }
+                Ok(Ctl::TapButton(bit)) => {
+                    // Synthetic system-button tap (the session control socket): down on
+                    // the first forwarded slot's index — pad 0 when none is open (a
+                    // forwarding-off session; best-effort there, the wire pad may not
+                    // exist host-side). The up is owed via `synthetic_ups`, TAP_PRESS
+                    // later, so the pair can't fold into nothing.
+                    if let Some(c) = self.attached.clone() {
+                        let pad = self.slots.first().map_or(0, |s| s.index);
+                        send(&c, InputKind::GamepadButton, bit, 1, pad);
+                        self.synthetic_ups
+                            .push((pad, bit, Instant::now() + TAP_PRESS));
+                    }
+                }
                 Ok(Ctl::Forwarding(on)) => {
                     if self.forwarding == on {
                         continue;
@@ -1405,8 +1729,32 @@ impl Worker {
                     return;
                 }
                 if let Some(bit) = button_bit(button) {
+                    // Raw system buttons stay with the local shell when passthrough is
+                    // off (the Gaming-Mode default): Steam already opened ITS overlay
+                    // for this press; the host's is reached via the hold-Select gesture
+                    // (and the Decky panel) instead.
+                    if !self.system_forward && matches!(bit, wire::BTN_GUIDE | wire::BTN_MISC1) {
+                        return;
+                    }
+                    let mut due = Vec::new();
+                    let held_back = if !self.guide_gesture {
+                        false
+                    } else if bit == wire::BTN_BACK {
+                        let alone = slot.held_buttons.is_empty();
+                        slot.gesture.on_select_down(Instant::now(), alone, &mut due)
+                    } else {
+                        slot.gesture.on_other_down(&mut due);
+                        false
+                    };
+                    for (b, down) in due {
+                        send(&c, InputKind::GamepadButton, b, down as i32, slot.index);
+                    }
+                    // Held-back or not, the chord bookkeeping sees the physical press —
+                    // the escape chord must not care that the gesture exists.
                     slot.held_buttons.push(bit);
-                    send(&c, InputKind::GamepadButton, bit, 1, slot.index);
+                    if !held_back {
+                        send(&c, InputKind::GamepadButton, bit, 1, slot.index);
+                    }
                     self.maybe_fire_escape();
                 }
             }
@@ -1422,8 +1770,20 @@ impl Worker {
                     return;
                 }
                 if let Some(bit) = button_bit(button) {
+                    if !self.system_forward && matches!(bit, wire::BTN_GUIDE | wire::BTN_MISC1) {
+                        return;
+                    }
                     slot.held_buttons.retain(|&b| b != bit);
-                    send(&c, InputKind::GamepadButton, bit, 0, slot.index);
+                    let mut due = Vec::new();
+                    let owned = self.guide_gesture
+                        && bit == wire::BTN_BACK
+                        && slot.gesture.on_select_up(Instant::now(), &mut due);
+                    for (b, down) in due {
+                        send(&c, InputKind::GamepadButton, b, down as i32, slot.index);
+                    }
+                    if !owned {
+                        send(&c, InputKind::GamepadButton, bit, 0, slot.index);
+                    }
                     self.rearm_escape();
                 }
             }
@@ -1571,7 +1931,12 @@ impl Worker {
         let dur_ms: u32 = if (low, high) == (0, 0) {
             100 // a stop takes effect immediately; the duration is irrelevant
         } else {
-            backstop_ms.max(160) // floor: a jittered renewal can never gap the actuator
+            // No local floor. There was a `.max(160)` here, and it could never do anything: the
+            // engine's own `backstop()` returns `(2 * ttl).clamp(500, 5000)` or the 2000 ms legacy
+            // value, so a non-zero command's backstop is never below 500. A floor that belongs to a
+            // particular actuator belongs in its `ActuatorQuirks::min_pulse_ms`, which the engine
+            // already applies — not re-invented per renderer where it can silently disagree.
+            backstop_ms
         };
         // Surface a failed SDL rumble write: a swallowed error here (DualSense not in the right
         // HIDAPI mode, etc.) reads exactly like "rumble doesn't work". The host logs the send side
@@ -1626,6 +1991,11 @@ impl Worker {
                 HidOutput::PlayerLeds { bits, .. } if is_ds => {
                     let _ = slot.pad.send_effect(&Ds5Feedback::player_packet(bits));
                 }
+                // Every other pad with player LEDs gets them through SDL, which owns the
+                // per-device pattern. This used to fall through and do nothing at all.
+                HidOutput::PlayerLeds { bits, .. } => {
+                    let _ = set_player_leds(&slot.pad, bits);
+                }
                 HidOutput::Trigger {
                     which, ref effect, ..
                 } if is_ds => {
@@ -1633,12 +2003,43 @@ impl Worker {
                         .pad
                         .send_effect(&Ds5Feedback::trigger_packet(which, effect));
                 }
-                _ => {}
+                // Deliberately unhandled, listed rather than left to a bare `_` so a new
+                // variant cannot join them silently: adaptive triggers exist only on a
+                // DualSense, and the trackpad-haptic / raw-passthrough planes are DS-specific
+                // and carried by `send_effect` above when the pad is one.
+                HidOutput::Trigger { .. }
+                | HidOutput::TrackpadHaptic { .. }
+                | HidOutput::HidRaw { .. } => {}
             }
         }
     }
 }
 
+/// The SDL player index for the wire's positional player-LED `bits`, or `None` for "no player".
+///
+/// The wire carries a bitmask — one bit per LED, low 5 — while SDL wants a player *index* and owns
+/// the per-device pattern. The count bridges them: every convention that reaches this wire spells
+/// "player N" as N lit LEDs, both the DualSense patterns (`0x04`, `0x0A`, `0x15`, `0x1B`, `0x1F`)
+/// and the Switch/XInput run of low bits (`0x01`, `0x03`, `0x07`, `0x0F`). SDL's index is 0-based,
+/// so player 1 is index 0; no lit LED means *no* player rather than player 0.
+///
+/// Split out from [`set_player_leds`] so the mapping is testable — an `sdl3::Gamepad` needs a real
+/// device, so nothing that takes one can be.
+fn player_index_from_bits(bits: u8) -> Option<u16> {
+    match (bits & 0x1F).count_ones() {
+        0 => None,
+        n => Some((n - 1) as u16),
+    }
+}
+
+/// Drive a non-DualSense pad's player LEDs from the wire's positional `bits`.
+fn set_player_leds(pad: &sdl3::gamepad::Gamepad, bits: u8) -> Result<(), sdl3::Error> {
+    match player_index_from_bits(bits) {
+        None => pad.unset_player_index(),
+        Some(i) => pad.set_player_index(i),
+    }
+}
+
 /// The wire pad index a [`HidOutput`] is addressed to (every variant carries `pad`).
 fn hidout_pad(h: &HidOutput) -> u8 {
     match h {
@@ -1671,6 +2072,9 @@ impl Worker {
             pinned: None,
             forwarding: true,
             kind_override: GamepadPref::Auto,
+            system_forward: true,
+            guide_gesture: false,
+            synthetic_ups: Vec::new(),
             attached: None,
             escape_tx,
             disconnect_tx,
@@ -1742,6 +2146,7 @@ fn run(
 
         // Escalate a held escape chord to a disconnect (polled — the hold completes with no
         // new button events; the chord itself is only detected while a session is attached).
+        w.gesture_poll();
         w.maybe_fire_disconnect();
 
         w.menu_poll();
@@ -1749,6 +2154,115 @@ fn run(
     }
 }
 
+#[cfg(test)]
+mod select_gesture_tests {
+    use super::*;
+
+    #[test]
+    fn tap_delivers_press_then_scheduled_release() {
+        let mut g = SelectGesture::default();
+        let t = Instant::now();
+        let mut out = Vec::new();
+        assert!(g.on_select_down(t, true, &mut out), "not held back");
+        assert!(out.is_empty(), "a held-back press sends nothing yet");
+        // Released inside the threshold: the press goes out on release…
+        let up = t + Duration::from_millis(120);
+        assert!(g.on_select_up(up, &mut out));
+        assert_eq!(out, vec![(wire::BTN_BACK, true)]);
+        out.clear();
+        // …and the release only TAP_PRESS behind it, so the pair can't fold away.
+        g.poll(up + TAP_PRESS - Duration::from_millis(1), &mut out);
+        assert!(out.is_empty(), "release went out early");
+        g.poll(up + TAP_PRESS, &mut out);
+        assert_eq!(out, vec![(wire::BTN_BACK, false)]);
+    }
+
+    #[test]
+    fn hold_becomes_guide_down_until_release() {
+        let mut g = SelectGesture::default();
+        let t = Instant::now();
+        let mut out = Vec::new();
+        assert!(g.on_select_down(t, true, &mut out));
+        g.poll(t + GUIDE_HOLD - Duration::from_millis(1), &mut out);
+        assert!(out.is_empty(), "guide fired inside the threshold");
+        g.poll(t + GUIDE_HOLD, &mut out);
+        assert_eq!(out, vec![(wire::BTN_GUIDE, true)]);
+        out.clear();
+        // Held on: nothing more (the host times its own long-press = QAM).
+        g.poll(t + GUIDE_HOLD * 4, &mut out);
+        assert!(out.is_empty());
+        // Release lifts the guide, never a Select.
+        assert!(g.on_select_up(t + GUIDE_HOLD * 5, &mut out));
+        assert_eq!(out, vec![(wire::BTN_GUIDE, false)]);
+    }
+
+    #[test]
+    fn second_button_makes_pending_select_real() {
+        let mut g = SelectGesture::default();
+        let t = Instant::now();
+        let mut out = Vec::new();
+        assert!(g.on_select_down(t, true, &mut out));
+        // A joins inside the window: the deferred Select down goes out first (the
+        // caller then sends A's own down — chronology preserved).
+        g.on_other_down(&mut out);
+        assert_eq!(out, vec![(wire::BTN_BACK, true)]);
+        out.clear();
+        // The release is a normal button-up now — the gesture doesn't own it.
+        assert!(!g.on_select_up(t + Duration::from_millis(200), &mut out));
+        assert!(out.is_empty());
+        // And no stale guide fires later.
+        g.poll(t + GUIDE_HOLD * 2, &mut out);
+        assert!(out.is_empty());
+    }
+
+    #[test]
+    fn select_inside_a_combo_passes_through() {
+        let mut g = SelectGesture::default();
+        let mut out = Vec::new();
+        // L1+R1+Start already down (the escape chord ends in Select): not held back.
+        assert!(!g.on_select_down(Instant::now(), false, &mut out));
+        assert!(out.is_empty());
+    }
+
+    #[test]
+    fn quick_repress_lifts_owed_release_first() {
+        let mut g = SelectGesture::default();
+        let t = Instant::now();
+        let mut out = Vec::new();
+        assert!(g.on_select_down(t, true, &mut out));
+        assert!(g.on_select_up(t + Duration::from_millis(80), &mut out));
+        out.clear();
+        // Re-pressed before the owed release fired: the up goes out before the new
+        // press is held back — the host never sees two downs in a row.
+        assert!(g.on_select_down(t + Duration::from_millis(100), true, &mut out));
+        assert_eq!(out, vec![(wire::BTN_BACK, false)]);
+    }
+
+    #[test]
+    fn flush_lifts_synthetic_guide_and_owed_release() {
+        let mut g = SelectGesture::default();
+        let t = Instant::now();
+        let mut out = Vec::new();
+        // Transformed hold: flush lifts the guide.
+        assert!(g.on_select_down(t, true, &mut out));
+        g.poll(t + GUIDE_HOLD, &mut out);
+        out.clear();
+        g.flush(&mut out);
+        assert_eq!(out, vec![(wire::BTN_GUIDE, false)]);
+        out.clear();
+        // Owed tap release: flush emits it. A pending (never-sent) Select just drops.
+        assert!(g.on_select_down(t, true, &mut out));
+        assert!(g.on_select_up(t + Duration::from_millis(80), &mut out));
+        out.clear();
+        g.flush(&mut out);
+        assert_eq!(out, vec![(wire::BTN_BACK, false)]);
+        out.clear();
+        assert!(g.on_select_down(t, true, &mut out));
+        g.flush(&mut out);
+        assert!(out.is_empty(), "a never-sent pending Select ghosted a send");
+    }
+}
+
 #[cfg(test)]
 mod menu_nav_tests {
     use super::*;
@@ -2008,3 +2522,214 @@ mod slot_tests {
         );
     }
 }
+
+/// [`Ds5Feedback`]'s three packet builders. The host-side parser, the Android writer and the Apple
+/// writer are all pinned by their own suites; this writer had nothing, despite being the one that
+/// hand-shifts every offset by the report-id length.
+#[cfg(test)]
+mod ds5_feedback_tests {
+    use super::*;
+
+    /// The USB output report offsets, written out independently of the implementation. A DS5
+    /// effects payload is the same block with the leading report id removed, so every offset is
+    /// exactly one lower — this is the relationship the derived constants encode.
+    #[test]
+    fn ds5_offsets_track_the_usb_report() {
+        for (usb, payload) in [
+            (11usize, Ds5Feedback::RIGHT_TRIGGER),
+            (22, Ds5Feedback::LEFT_TRIGGER),
+            (44, Ds5Feedback::PAD_LIGHTS),
+            (45, Ds5Feedback::LED_RGB),
+        ] {
+            assert_eq!(payload, usb - 1, "payload offset for USB byte {usb}");
+        }
+        assert_eq!(Ds5Feedback::TRIGGER_LEN, 11);
+    }
+
+    #[test]
+    fn lightbar_sets_only_its_enable_bit_and_its_three_bytes() {
+        let p = Ds5Feedback::lightbar_packet(0x11, 0x22, 0x33);
+        assert_eq!(p.len(), 47);
+        assert_eq!(p[1], 0x04, "valid_flag1 lightbar bit");
+        assert_eq!(p[0], 0, "must not claim any valid_flag0 field");
+        assert_eq!(
+            (
+                p[Ds5Feedback::LED_RGB],
+                p[Ds5Feedback::LED_RGB + 1],
+                p[Ds5Feedback::LED_RGB + 2]
+            ),
+            (0x11, 0x22, 0x33)
+        );
+        // Everything else stays zero — an over-broad packet would blank the triggers/player LEDs
+        // it never meant to touch.
+        let touched = [
+            1,
+            Ds5Feedback::LED_RGB,
+            Ds5Feedback::LED_RGB + 1,
+            Ds5Feedback::LED_RGB + 2,
+        ];
+        assert!(p
+            .iter()
+            .enumerate()
+            .all(|(i, &b)| touched.contains(&i) || b == 0));
+    }
+
+    #[test]
+    fn player_leds_are_masked_to_five_bits() {
+        let p = Ds5Feedback::player_packet(0xFF);
+        assert_eq!(p[1], 0x10, "valid_flag1 player-indicator bit");
+        assert_eq!(
+            p[Ds5Feedback::PAD_LIGHTS],
+            0x1F,
+            "high bits are not ours to set"
+        );
+        let p = Ds5Feedback::player_packet(0b0000_0101);
+        assert_eq!(p[Ds5Feedback::PAD_LIGHTS], 0b0000_0101);
+    }
+
+    /// which 1 = R2 and which 0 = L2 — and the RIGHT block sits FIRST in the report, which is the
+    /// pairing most likely to be transcribed backwards.
+    #[test]
+    fn trigger_which_selects_the_right_flag_and_offset() {
+        let eff: Vec<u8> = (1..=11).collect();
+
+        let r = Ds5Feedback::trigger_packet(1, &eff);
+        assert_eq!(r[0], 0x04, "valid_flag0 R2 bit");
+        assert_eq!(
+            &r[Ds5Feedback::RIGHT_TRIGGER..Ds5Feedback::RIGHT_TRIGGER + 11],
+            &eff[..]
+        );
+        assert_eq!(
+            r[Ds5Feedback::LEFT_TRIGGER],
+            0,
+            "the other trigger is untouched"
+        );
+
+        let l = Ds5Feedback::trigger_packet(0, &eff);
+        assert_eq!(l[0], 0x08, "valid_flag0 L2 bit");
+        assert_eq!(
+            &l[Ds5Feedback::LEFT_TRIGGER..Ds5Feedback::LEFT_TRIGGER + 11],
+            &eff[..]
+        );
+        assert_eq!(l[Ds5Feedback::RIGHT_TRIGGER], 0);
+    }
+
+    #[test]
+    fn an_oversized_effect_is_clamped_rather_than_overflowing_into_the_next_field() {
+        let long = vec![0xAAu8; 40];
+        let p = Ds5Feedback::trigger_packet(1, &long);
+        assert_eq!(p.len(), 47);
+        // Exactly TRIGGER_LEN bytes written; the left block must not be scribbled on.
+        assert_eq!(p[Ds5Feedback::RIGHT_TRIGGER + 10], 0xAA);
+        assert_eq!(p[Ds5Feedback::RIGHT_TRIGGER + 11], 0);
+        assert_eq!(p[Ds5Feedback::LEFT_TRIGGER], 0);
+    }
+
+    #[test]
+    fn a_short_effect_leaves_the_rest_of_the_block_zeroed() {
+        let p = Ds5Feedback::trigger_packet(0, &[0x02, 0x99]);
+        assert_eq!(p[Ds5Feedback::LEFT_TRIGGER], 0x02);
+        assert_eq!(p[Ds5Feedback::LEFT_TRIGGER + 1], 0x99);
+        assert!(
+            p[Ds5Feedback::LEFT_TRIGGER + 2..Ds5Feedback::LEFT_TRIGGER + 11]
+                .iter()
+                .all(|&b| b == 0)
+        );
+    }
+
+    /// An empty effect is a well-formed all-zero block: mode 0x00 = release. It must still assert
+    /// its enable bit, or the pad keeps whatever effect it was holding.
+    #[test]
+    fn an_empty_effect_is_a_release_not_a_no_op() {
+        let p = Ds5Feedback::trigger_packet(1, &[]);
+        assert_eq!(p[0], 0x04);
+        assert!(
+            p[Ds5Feedback::RIGHT_TRIGGER..Ds5Feedback::RIGHT_TRIGGER + 11]
+                .iter()
+                .all(|&b| b == 0)
+        );
+    }
+}
+
+#[cfg(test)]
+mod reset_packet_tests {
+    use super::*;
+
+    /// The exact bytes a teardown sends to hand a DualSense back neutral. The *timing* of this
+    /// (slot close) needs a live SDL handle and stays untestable, so pin the payloads: a wrong
+    /// enable flag or a non-zero mode byte would silently leave the effect latched, which is the
+    /// bug this reset exists to prevent.
+    #[test]
+    fn reset_packets_release_the_triggers_and_darken_the_lights() {
+        // Trigger release: mode 0x00 with no parameters, on the side's own enable bit.
+        let l = Ds5Feedback::trigger_packet(0, &[0u8; 11]);
+        assert_eq!(l[0], 0x08, "left-trigger enable bit");
+        assert!(
+            l[Ds5Feedback::LEFT_TRIGGER..Ds5Feedback::LEFT_TRIGGER + 11]
+                .iter()
+                .all(|&b| b == 0),
+            "an all-zero block is mode 0x00 = no effect"
+        );
+        let r = Ds5Feedback::trigger_packet(1, &[0u8; 11]);
+        assert_eq!(r[0], 0x04, "right-trigger enable bit");
+        assert!(
+            r[Ds5Feedback::RIGHT_TRIGGER..Ds5Feedback::RIGHT_TRIGGER + 11]
+                .iter()
+                .all(|&b| b == 0)
+        );
+
+        // Lightbar off: enable bit set, RGB all zero. The enable bit matters — without it the pad
+        // ignores the payload and keeps the game's last colour.
+        let bar = Ds5Feedback::lightbar_packet(0, 0, 0);
+        assert_eq!(bar[1], 0x04, "lightbar enable bit");
+        assert_eq!(
+            &bar[Ds5Feedback::LED_RGB..Ds5Feedback::LED_RGB + 3],
+            &[0, 0, 0]
+        );
+
+        // Player indicator cleared.
+        let pl = Ds5Feedback::player_packet(0);
+        assert_eq!(pl[1], 0x10, "player-LED enable bit");
+        assert_eq!(pl[Ds5Feedback::PAD_LIGHTS], 0);
+    }
+}
+
+#[cfg(test)]
+mod player_led_tests {
+    use super::*;
+
+    /// Both conventions that reach this wire spell "player N" as N lit LEDs, so the count is the
+    /// player number regardless of WHICH bits a given pad lights. Pinned because the mapping is
+    /// otherwise only obvious once you have seen both patterns side by side.
+    #[test]
+    fn player_index_counts_lit_leds_for_both_conventions() {
+        // DualSense / hid-playstation patterns — non-contiguous, symmetric about the centre LED.
+        assert_eq!(player_index_from_bits(0x04), Some(0)); // player 1
+        assert_eq!(player_index_from_bits(0x0A), Some(1)); // player 2
+        assert_eq!(player_index_from_bits(0x15), Some(2)); // player 3
+        assert_eq!(player_index_from_bits(0x1B), Some(3)); // player 4
+        assert_eq!(player_index_from_bits(0x1F), Some(4)); // player 5
+
+        // Switch/XInput style — a contiguous run of low bits, the same count each time.
+        assert_eq!(player_index_from_bits(0x01), Some(0));
+        assert_eq!(player_index_from_bits(0x03), Some(1));
+        assert_eq!(player_index_from_bits(0x07), Some(2));
+        assert_eq!(player_index_from_bits(0x0F), Some(3));
+    }
+
+    /// No lit LED is "no player", NOT player 0 — the difference between LEDs off and player 1 lit.
+    #[test]
+    fn no_lit_led_is_no_player() {
+        assert_eq!(player_index_from_bits(0x00), None);
+        // Only the low 5 bits are player LEDs; junk above them must not invent a player.
+        assert_eq!(player_index_from_bits(0xE0), None);
+    }
+
+    /// The mask is applied before counting, so out-of-range bits cannot inflate the index past
+    /// the 5 real LEDs.
+    #[test]
+    fn high_bits_are_masked_off_before_counting() {
+        assert_eq!(player_index_from_bits(0xFF), Some(4)); // 0x1F worth of LEDs, not 8
+        assert_eq!(player_index_from_bits(0xE4), Some(0)); // 0x04 with junk on top
+    }
+}

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

@@ -76,6 +76,10 @@ pub struct SettingsOverlay {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub gamepad_forwarding: Option<bool>,
     #[serde(skip_serializing_if = "Option::is_none")]
+    pub system_buttons: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub guide_gesture: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub stats_verbosity: Option<StatsVerbosity>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub fullscreen_on_stream: Option<bool>,
@@ -159,6 +163,12 @@ impl SettingsOverlay {
         if let Some(v) = self.gamepad_forwarding {
             s.gamepad_forwarding = v;
         }
+        if let Some(v) = &self.system_buttons {
+            s.system_buttons = v.clone();
+        }
+        if let Some(v) = &self.guide_gesture {
+            s.guide_gesture = v.clone();
+        }
         if let Some(v) = self.stats_verbosity {
             // Through the setter so the legacy `show_stats` bool stays coherent for
             // pre-tier binaries reading the same settings file.
@@ -252,6 +262,12 @@ impl SettingsOverlay {
         if after.gamepad_forwarding != before.gamepad_forwarding {
             self.gamepad_forwarding = Some(after.gamepad_forwarding);
         }
+        if after.system_buttons != before.system_buttons {
+            self.system_buttons = Some(after.system_buttons.clone());
+        }
+        if after.guide_gesture != before.guide_gesture {
+            self.guide_gesture = Some(after.guide_gesture.clone());
+        }
         if after.stats_verbosity() != before.stats_verbosity() {
             self.stats_verbosity = Some(after.stats_verbosity());
         }
@@ -302,6 +318,8 @@ impl SettingsOverlay {
             "inhibit_shortcuts" => self.inhibit_shortcuts = None,
             "gamepad" => self.gamepad = None,
             "gamepad_forwarding" => self.gamepad_forwarding = None,
+            "system_buttons" => self.system_buttons = None,
+            "guide_gesture" => self.guide_gesture = None,
             "stats_verbosity" => self.stats_verbosity = None,
             "fullscreen_on_stream" => self.fullscreen_on_stream = None,
             "present_priority" => self.present_priority = None,
@@ -506,6 +524,8 @@ mod tests {
             inhibit_shortcuts: Some(false),
             gamepad: Some("dualsense".into()),
             gamepad_forwarding: Some(false),
+            system_buttons: Some("local".into()),
+            guide_gesture: Some("on".into()),
             match_window: Some(true),
             fullscreen_on_stream: Some(false),
             stats_verbosity: Some(StatsVerbosity::Detailed),
@@ -532,6 +552,8 @@ mod tests {
         assert!(!out.inhibit_shortcuts);
         assert_eq!(out.gamepad, "dualsense");
         assert!(!out.gamepad_forwarding);
+        assert_eq!(out.system_buttons, "local");
+        assert_eq!(out.guide_gesture, "on");
         assert!(out.match_window);
         assert!(!out.fullscreen_on_stream);
         assert_eq!(out.stats_verbosity(), StatsVerbosity::Detailed);

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

@@ -232,17 +232,29 @@ impl KnownHosts {
     /// A read-only config dir just keeps re-minting in memory, which harms nothing: no lookup
     /// is keyed by the id yet (design §4.5).
     pub fn load() -> KnownHosts {
-        let mut k: KnownHosts = Self::path()
-            .and_then(|p| Ok(std::fs::read_to_string(p)?))
-            .ok()
-            .and_then(|s| serde_json::from_str(&s).ok())
-            .unwrap_or_default();
+        let mut k = Self::read();
         if k.mint_missing_ids() {
             let _ = k.save();
         }
         k
     }
 
+    /// The store exactly as it is on disk — no mint, and so no write.
+    ///
+    /// For a consumer that only needs to LOOK at the records (annotating a discovery result
+    /// against them, say) and never dials one by id. [`KnownHosts::load`]'s mint is a write, and
+    /// two processes started together against a pre-mint store will each mint a *different* id
+    /// for the same record and race to save it — after which whichever one already handed its
+    /// ids to a caller has handed out references that no longer resolve. A read that stays a
+    /// read cannot take part in that.
+    pub fn read() -> KnownHosts {
+        Self::path()
+            .and_then(|p| Ok(std::fs::read_to_string(p)?))
+            .ok()
+            .and_then(|s| serde_json::from_str(&s).ok())
+            .unwrap_or_default()
+    }
+
     /// Give every record still missing one a stable id; returns true if anything changed
     /// (i.e. whether this needs persisting). Idempotent — a store that has been through it
     /// once is left byte-identical.
@@ -867,6 +879,25 @@ pub struct Settings {
     /// forwarded as pad 0; empty = automatic (most recently connected). Applied to the
     /// gamepad service at startup so the choice survives restarts.
     pub forward_pad: String,
+    /// What a controller's SYSTEM buttons — guide (Xbox/PS/Steam) and the Deck's QAM `…` —
+    /// do while streaming: `"auto"` (default), `"forward"` (raw presses go to the host,
+    /// the pre-setting behaviour), or `"local"` (they stay with this device; the host's
+    /// are reached via the hold-Select gesture instead). Auto resolves per platform in
+    /// [`Settings::system_buttons_forward`]: forward everywhere EXCEPT under Gaming Mode,
+    /// where the local Steam UI always reacts to the same physical press — forwarding
+    /// there opens BOTH overlays, the local one on top of the stream.
+    #[serde(default = "default_auto")]
+    pub system_buttons: String,
+    /// The hold-Select guide gesture: holding Select/Back alone ≥ ~350 ms sends the HOST
+    /// the guide button (down for as long as it's held, so a long hold is the host's
+    /// long-press — the QAM on a Gaming-Mode host). `"auto"` (default) / `"on"` / `"off"`,
+    /// resolved in [`Settings::guide_gesture_enabled`]: auto = on only where the raw
+    /// guide press can't reach the host cleanly (Gaming Mode; iOS/tvOS resolve their own
+    /// auto in the Apple client). While armed, a Select TAP is delivered on release —
+    /// costing it up to the hold threshold in latency — and a Select held as part of a
+    /// combo (any other button already down) passes through untouched.
+    #[serde(default = "default_auto")]
+    pub guide_gesture: String,
     /// Which host compositor backend to request (advisory; the host falls back to
     /// auto-detect when unavailable).
     pub compositor: String,
@@ -1020,6 +1051,10 @@ fn default_codec() -> String {
     "auto".into()
 }
 
+fn default_auto() -> String {
+    "auto".into()
+}
+
 fn default_touch_mode() -> String {
     "trackpad".into()
 }
@@ -1069,6 +1104,29 @@ impl Settings {
         PresentPriority::resolve(&self.present_priority, self.smooth_buffer)
     }
 
+    /// Whether raw system-button presses (guide + QAM) are forwarded to the host.
+    /// `game_mode` = this client runs as the embedded Gaming-Mode stream (gamescope),
+    /// where the local Steam UI reacts to the same physical buttons no matter what we
+    /// do — auto keeps them local there and forwards everywhere else.
+    pub fn system_buttons_forward(&self, game_mode: bool) -> bool {
+        match self.system_buttons.as_str() {
+            "forward" => true,
+            "local" => false,
+            _ => !game_mode,
+        }
+    }
+
+    /// Whether the hold-Select guide gesture is armed ([`Settings::guide_gesture`]).
+    /// Auto = on only under Gaming Mode, where it is the sole controller route to the
+    /// host's guide once raw presses stay local.
+    pub fn guide_gesture_enabled(&self, game_mode: bool) -> bool {
+        match self.guide_gesture.as_str() {
+            "on" => true,
+            "off" => false,
+            _ => game_mode,
+        }
+    }
+
     /// The `codec` setting as a `quic::CODEC_*` preference bit (`0` = auto).
     pub fn preferred_codec(&self) -> u8 {
         match self.codec.as_str() {
@@ -1095,6 +1153,8 @@ impl Default for Settings {
             gamepad: "auto".into(),
             gamepad_forwarding: true,
             forward_pad: String::new(),
+            system_buttons: "auto".into(),
+            guide_gesture: "auto".into(),
             compositor: "auto".into(),
             touch_mode: "trackpad".into(),
             mouse_mode: "capture".into(),

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

@@ -41,6 +41,8 @@ enum RowId {
     PadForward,
     Pad,
     PadType,
+    SystemButtons,
+    GuideGesture,
     Touch,
     Mouse,
     InvertScroll,
@@ -57,7 +59,7 @@ enum RowId {
 // cancellation all were). Still deliberately smaller than the desktop dialogs — device
 // pickers (GPU/speaker/mic) stay desktop-only, and profiles are pinnable here (the
 // trailing Profiles section) but created and edited only in the desktop app (design §5.4).
-const ROWS: [RowId; 27] = [
+const ROWS: [RowId; 29] = [
     RowId::Resolution,
     RowId::Refresh,
     RowId::RenderScale,
@@ -77,6 +79,8 @@ const ROWS: [RowId; 27] = [
     RowId::PadForward,
     RowId::Pad,
     RowId::PadType,
+    RowId::SystemButtons,
+    RowId::GuideGesture,
     RowId::Touch,
     RowId::Mouse,
     RowId::InvertScroll,
@@ -152,6 +156,16 @@ const PAD_TYPES: [(&str, &str); 6] = [
     ("dualshock4", "DualShock 4"),
     ("steamdeck", "Steam Deck"),
 ];
+/// Where the guide (Xbox/PS/Steam) and quick-access presses land while streaming — the
+/// shared `system_buttons` key. Auto = host everywhere except Gaming Mode, where the
+/// local Steam UI reacts to the same press and both overlays would open at once.
+const SYSTEM_BUTTONS: [(&str, &str); 3] = [
+    ("auto", "Automatic"),
+    ("forward", "Send to host"),
+    ("local", "This device"),
+];
+/// The hold-Select guide gesture — the shared `guide_gesture` key.
+const GUIDE_GESTURE: [(&str, &str); 3] = [("auto", "Automatic"), ("on", "On"), ("off", "Off")];
 
 pub(crate) struct SettingsScreen {
     list: MenuList,
@@ -350,7 +364,9 @@ fn row_spec(id: RowId, ctx: &Ctx, profiles: &[(String, String)]) -> RowSpec {
     // move everything under the cursor).
     let enabled = match id {
         RowId::EchoCancel => s.mic_enabled,
-        RowId::Pad | RowId::PadType => s.gamepad_forwarding,
+        RowId::Pad | RowId::PadType | RowId::SystemButtons | RowId::GuideGesture => {
+            s.gamepad_forwarding
+        }
         RowId::SmoothBuffer => s.present_priority == "smooth",
         _ => true,
     };
@@ -457,6 +473,16 @@ fn row_spec(id: RowId, ctx: &Ctx, profiles: &[(String, String)]) -> RowSpec {
             "Controller type",
             label_for(&PAD_TYPES, &s.gamepad).into(),
         ),
+        RowId::SystemButtons => (
+            None,
+            "Steam / guide button",
+            label_for(&SYSTEM_BUTTONS, &s.system_buttons).into(),
+        ),
+        RowId::GuideGesture => (
+            None,
+            "Hold Select for guide",
+            label_for(&GUIDE_GESTURE, &s.guide_gesture).into(),
+        ),
         RowId::Touch => (
             Some("Touchscreen"),
             "Touch mode",
@@ -553,6 +579,16 @@ fn detail(id: RowId) -> &'static str {
         }
         RowId::Pad => "Which pad is forwarded to the host, as player 1.",
         RowId::PadType => "The virtual pad the host creates — Automatic matches this controller.",
+        RowId::SystemButtons => {
+            "Where the guide (Xbox/PS/Steam) and quick-access presses go. Automatic \
+             sends them to the host except in Gaming Mode, where Steam on this device \
+             reacts to the same press and both overlays would open at once."
+        }
+        RowId::GuideGesture => {
+            "Hold Select on its own to press the host's guide button — keep holding for \
+             the host's quick-access menu. Automatic arms it only where the real button \
+             can't reach the host. A Select tap still goes through, slightly delayed."
+        }
         RowId::Touch => {
             "How the touchscreen drives the host: Trackpad (relative cursor), \
              Direct pointer (cursor jumps to your finger), or Touch passthrough (raw contacts)."
@@ -699,6 +735,18 @@ fn adjust(id: RowId, delta: i32, wrap: bool, ctx: &mut Ctx) -> bool {
             }
             step_str(&PAD_TYPES, &mut s.gamepad, delta, wrap)
         }
+        RowId::SystemButtons => {
+            if !s.gamepad_forwarding {
+                return false;
+            }
+            step_str(&SYSTEM_BUTTONS, &mut s.system_buttons, delta, wrap)
+        }
+        RowId::GuideGesture => {
+            if !s.gamepad_forwarding {
+                return false;
+            }
+            step_str(&GUIDE_GESTURE, &mut s.guide_gesture, delta, wrap)
+        }
         RowId::Touch => {
             let cur = TouchMode::ALL.iter().position(|m| *m == s.touch_mode());
             step_option(cur, TouchMode::ALL.len(), delta, wrap)

crates/pf-inject/src/inject/hidout_dedup.rs

@@ -5,6 +5,20 @@
 //! rich state every report; this forwards only genuine changes (one-shot pulses always fire).
 
 use punktfunk_core::quic::HidOutput;
+use std::time::{Duration, Instant};
+
+/// How often the latched rich state is re-emitted even though nothing changed.
+///
+/// The 0xCD plane is deduped AND rides unreliable datagrams, which is a bad pairing: a change is
+/// forwarded exactly once, so if that datagram is dropped the game will never produce it again —
+/// it keeps re-sending the same value and the dedup swallows every copy. The pad is then left
+/// holding the PREVIOUS value: the last weapon's trigger effect, the last lightbar colour, for as
+/// long as the game keeps that setting. For a trigger effect that can be the rest of a level.
+///
+/// Slow on purpose. This is a repair mechanism, not a transport — at one second a lost update
+/// costs a noticeable but bounded wrong-feel window, while the steady-state cost is at most four
+/// small datagrams per second per pad, against a rumble plane that already resends at ~120 ms.
+const RENEW_EVERY: Duration = Duration::from_millis(1000);
 
 /// Per-pad dedup for the DualSense HID-output feedback plane (0xCD). A game's DualSense output report
 /// bundles rumble + lightbar + player-LEDs + adaptive-triggers into one report, so a pad that is
@@ -18,6 +32,9 @@ pub struct HidoutDedup {
     player_leds: Option<u8>,
     /// Last-forwarded adaptive-trigger effect per side: `[0]` = L2, `[1]` = R2.
     trigger: [Option<Vec<u8>>; 2],
+    /// When anything was last put on the wire for this pad. `None` = nothing latched yet, so
+    /// there is nothing to renew. See [`RENEW_EVERY`].
+    last_sent: Option<Instant>,
 }
 
 impl HidoutDedup {
@@ -29,7 +46,53 @@ impl HidoutDedup {
 
     /// Whether `h` should be forwarded: `true` for a genuine change (remembering the new value) or a
     /// one-shot pulse; `false` if it repeats the last-forwarded value for its kind.
-    pub fn should_forward(&mut self, h: &HidOutput) -> bool {
+    ///
+    /// `now` only stamps the renewal clock ([`Self::renewals`]) — forwarding a change resets it, so
+    /// a plane the game is actively changing never pays for a renewal it does not need.
+    pub fn should_forward(&mut self, h: &HidOutput, now: Instant) -> bool {
+        let fwd = self.decide(h);
+        if fwd {
+            self.last_sent = Some(now);
+        }
+        fwd
+    }
+
+    /// Re-emit the latched rich state, so one lost datagram cannot strand the pad on the previous
+    /// value. Returns the reports to send (empty until [`RENEW_EVERY`] has passed since anything
+    /// last went out); every one is idempotent, so a client that DID receive the original simply
+    /// re-applies it.
+    ///
+    /// One-shots are deliberately absent: replaying a `TrackpadHaptic` pulse would be a *new*
+    /// pulse, not a repair, and `HidRaw` is already re-sent verbatim by the device's own refresh
+    /// cadence (see the note in [`Self::decide`]).
+    pub fn renewals(&mut self, pad: u8, now: Instant) -> Vec<HidOutput> {
+        if self
+            .last_sent
+            .is_none_or(|t| now.duration_since(t) < RENEW_EVERY)
+        {
+            return Vec::new();
+        }
+        self.last_sent = Some(now);
+        let mut out = Vec::new();
+        if let Some((r, g, b)) = self.led {
+            out.push(HidOutput::Led { pad, r, g, b });
+        }
+        if let Some(bits) = self.player_leds {
+            out.push(HidOutput::PlayerLeds { pad, bits });
+        }
+        for (which, effect) in self.trigger.iter().enumerate() {
+            if let Some(effect) = effect {
+                out.push(HidOutput::Trigger {
+                    pad,
+                    which: which as u8,
+                    effect: effect.clone(),
+                });
+            }
+        }
+        out
+    }
+
+    fn decide(&mut self, h: &HidOutput) -> bool {
         match h {
             HidOutput::Led { r, g, b, .. } => {
                 let v = Some((*r, *g, *b));
@@ -77,6 +140,7 @@ mod tests {
     /// trigger sides independently, never dedups one-shot haptic pulses, and re-arms after `clear`.
     #[test]
     fn hidout_dedup_forwards_only_changes() {
+        let t = Instant::now();
         let mut d = HidoutDedup::default();
         let led = |r| HidOutput::Led {
             pad: 0,
@@ -85,15 +149,15 @@ mod tests {
             b: 0,
         };
         // First value forwards; an exact repeat is dropped; a change forwards again.
-        assert!(d.should_forward(&led(10)));
-        assert!(!d.should_forward(&led(10)));
-        assert!(d.should_forward(&led(20)));
+        assert!(d.should_forward(&led(10), t));
+        assert!(!d.should_forward(&led(10), t));
+        assert!(d.should_forward(&led(20), t));
 
         // Player LEDs dedup on their own field, independent of the lightbar.
         let pl = |bits| HidOutput::PlayerLeds { pad: 0, bits };
-        assert!(d.should_forward(&pl(0b101)));
-        assert!(!d.should_forward(&pl(0b101)));
-        assert!(!d.should_forward(&led(20))); // lightbar still unchanged
+        assert!(d.should_forward(&pl(0b101), t));
+        assert!(!d.should_forward(&pl(0b101), t));
+        assert!(!d.should_forward(&led(20), t)); // lightbar still unchanged
 
         // The two adaptive triggers (L2=0, R2=1) are tracked separately.
         let trig = |which, byte| HidOutput::Trigger {
@@ -101,10 +165,10 @@ mod tests {
             which,
             effect: vec![byte, 0, 0],
         };
-        assert!(d.should_forward(&trig(0, 1)));
-        assert!(d.should_forward(&trig(1, 1))); // same bytes, other side → still forwards
-        assert!(!d.should_forward(&trig(0, 1)));
-        assert!(d.should_forward(&trig(0, 2))); // L2 effect changed
+        assert!(d.should_forward(&trig(0, 1), t));
+        assert!(d.should_forward(&trig(1, 1), t)); // same bytes, other side → still forwards
+        assert!(!d.should_forward(&trig(0, 1), t));
+        assert!(d.should_forward(&trig(0, 2), t)); // L2 effect changed
 
         // One-shot haptic pulses are never deduped.
         let haptic = HidOutput::TrackpadHaptic {
@@ -114,13 +178,128 @@ mod tests {
             period: 2,
             count: 3,
         };
-        assert!(d.should_forward(&haptic));
-        assert!(d.should_forward(&haptic));
+        assert!(d.should_forward(&haptic, t));
+        assert!(d.should_forward(&haptic, t));
 
         // `clear` re-arms every kind.
         d.clear();
-        assert!(d.should_forward(&led(20)));
-        assert!(d.should_forward(&pl(0b101)));
-        assert!(d.should_forward(&trig(0, 2)));
+        assert!(d.should_forward(&led(20), t));
+        assert!(d.should_forward(&pl(0b101), t));
+        assert!(d.should_forward(&trig(0, 2), t));
+    }
+
+    /// A change is forwarded once and then deduped — so if that one datagram is lost, nothing else
+    /// would ever carry it. The renewal is what repairs that.
+    #[test]
+    fn latched_state_is_renewed_so_a_lost_datagram_is_not_permanent() {
+        let t = Instant::now();
+        let mut d = HidoutDedup::default();
+        let trig = HidOutput::Trigger {
+            pad: 3,
+            which: 1,
+            effect: vec![0x02, 0x90, 0xA0],
+        };
+        assert!(d.should_forward(&trig, t));
+        assert!(
+            !d.should_forward(&trig, t),
+            "the game re-sends it; the dedup swallows it"
+        );
+
+        // Nothing due yet.
+        assert!(d.renewals(3, t + Duration::from_millis(999)).is_empty());
+
+        // Past the window: the latched state goes out again, addressed to the right pad.
+        let out = d.renewals(3, t + Duration::from_millis(1000));
+        assert_eq!(out.len(), 1);
+        assert!(matches!(
+            &out[0],
+            HidOutput::Trigger { pad: 3, which: 1, effect } if effect == &vec![0x02, 0x90, 0xA0]
+        ));
+
+        // And it keeps repairing on the same cadence, not just once.
+        assert!(d.renewals(3, t + Duration::from_millis(1500)).is_empty());
+        assert_eq!(d.renewals(3, t + Duration::from_millis(2000)).len(), 1);
+    }
+
+    /// Every latched plane is renewed together, and a plane the game is actively driving does not
+    /// pay for renewals it does not need (a forward resets the clock).
+    #[test]
+    fn renewal_covers_every_latched_plane_and_an_active_plane_defers_it() {
+        let t = Instant::now();
+        let mut d = HidoutDedup::default();
+        assert!(d.should_forward(
+            &HidOutput::Led {
+                pad: 0,
+                r: 9,
+                g: 8,
+                b: 7
+            },
+            t
+        ));
+        assert!(d.should_forward(
+            &HidOutput::PlayerLeds {
+                pad: 0,
+                bits: 0b100
+            },
+            t
+        ));
+        assert!(d.should_forward(
+            &HidOutput::Trigger {
+                pad: 0,
+                which: 0,
+                effect: vec![1]
+            },
+            t
+        ));
+        assert!(d.should_forward(
+            &HidOutput::Trigger {
+                pad: 0,
+                which: 1,
+                effect: vec![2]
+            },
+            t
+        ));
+
+        let out = d.renewals(0, t + Duration::from_millis(1000));
+        assert_eq!(
+            out.len(),
+            4,
+            "lightbar + player LEDs + both triggers, got {out:?}"
+        );
+
+        // A genuine change re-stamps the clock, so the next renewal is a full window away.
+        let later = t + Duration::from_millis(1500);
+        assert!(d.should_forward(
+            &HidOutput::Led {
+                pad: 0,
+                r: 1,
+                g: 2,
+                b: 3
+            },
+            later
+        ));
+        assert!(d.renewals(0, later + Duration::from_millis(999)).is_empty());
+        assert!(!d
+            .renewals(0, later + Duration::from_millis(1000))
+            .is_empty());
+    }
+
+    /// Nothing latched = nothing to renew; a one-shot pulse must never be replayed as a "repair".
+    #[test]
+    fn renewal_is_silent_with_nothing_latched_and_never_replays_a_pulse() {
+        let t = Instant::now();
+        let mut d = HidoutDedup::default();
+        assert!(d.renewals(0, t + Duration::from_secs(60)).is_empty());
+
+        let pulse = HidOutput::TrackpadHaptic {
+            pad: 0,
+            side: 0,
+            amplitude: 1,
+            period: 2,
+            count: 3,
+        };
+        assert!(d.should_forward(&pulse, t));
+        // The pulse stamped the clock but latched no state, so the renewal has nothing to repeat.
+        assert!(d.renewals(0, t + Duration::from_millis(1000)).is_empty());
     }
 }

crates/pf-inject/src/inject/linux/dualsense.rs

@@ -17,6 +17,11 @@ use super::dualsense_proto::{
     DS_EDGE_PRODUCT, DS_FEATURE_CALIBRATION, DS_FEATURE_FIRMWARE, DS_INPUT_REPORT_LEN, DS_PRODUCT,
     DS_TOUCH_H, DS_TOUCH_W, DS_VENDOR, DUALSENSE_EDGE_RDESC, DUALSENSE_RDESC,
 };
+use crate::uhid_abi::{
+    put_cstr, BUS_USB, HID_MAX_DESCRIPTOR_SIZE, UHID_CREATE2, UHID_DESTROY, UHID_EVENT_SIZE,
+    UHID_GET_REPORT, UHID_GET_REPORT_REPLY, UHID_INPUT2, UHID_OUTPUT, UHID_PATH, UHID_SET_REPORT,
+    UHID_SET_REPORT_REPLY,
+};
 use crate::uhid_manager::{PadFeedback, PadProto, UhidManager};
 use anyhow::{Context, Result};
 use punktfunk_core::quic::RichInput;
@@ -24,27 +29,6 @@ use std::fs::{File, OpenOptions};
 use std::io::{Read, Write};
 use std::os::unix::fs::OpenOptionsExt;
 
-// /dev/uhid event ABI (linux/uhid.h). `struct uhid_event` is __packed__: a u32 `type` then a
-// union whose largest member is uhid_create2_req (128+64+64 + 2+2 + 4*4 + rd_data[4096] = 4372).
-const UHID_PATH: &str = "/dev/uhid";
-const UHID_DESTROY: u32 = 1;
-const UHID_OUTPUT: u32 = 6;
-const UHID_GET_REPORT: u32 = 9;
-const UHID_GET_REPORT_REPLY: u32 = 10;
-const UHID_CREATE2: u32 = 11;
-const UHID_INPUT2: u32 = 12;
-const UHID_SET_REPORT: u32 = 13;
-const UHID_SET_REPORT_REPLY: u32 = 14;
-const HID_MAX_DESCRIPTOR_SIZE: usize = 4096;
-const UHID_EVENT_SIZE: usize = 4 + 4372; // type + union (create2)
-const BUS_USB: u16 = 0x03;
-
-/// Copy a NUL-padded C string field into the event buffer.
-fn put_cstr(ev: &mut [u8], off: usize, cap: usize, s: &str) {
-    let n = s.len().min(cap - 1);
-    ev[off..off + n].copy_from_slice(&s.as_bytes()[..n]); // rest already zero (NUL-terminated)
-}
-
 /// The UHID identity a [`DualSensePad`] is created with — the plain DualSense or the Edge (same
 /// driver, same report codec; the Edge differs by PID + descriptor and carries the four extra
 /// `buttons[2]` bits). Mirrors the uinput pad's `PadIdentity` shape.

crates/pf-inject/src/inject/linux/dualshock4.rs

@@ -18,6 +18,11 @@ use super::dualshock4_proto::{
     parse_ds4_output, serialize_state, Ds4Feedback, DS4_INPUT_REPORT_LEN, DS4_PRODUCT, DS4_TOUCH_H,
     DS4_TOUCH_W, DS4_VENDOR,
 };
+use crate::uhid_abi::{
+    put_cstr, BUS_USB, HID_MAX_DESCRIPTOR_SIZE, UHID_CREATE2, UHID_DESTROY, UHID_EVENT_SIZE,
+    UHID_GET_REPORT, UHID_GET_REPORT_REPLY, UHID_INPUT2, UHID_OUTPUT, UHID_PATH, UHID_SET_REPORT,
+    UHID_SET_REPORT_REPLY,
+};
 use crate::uhid_manager::{PadFeedback, PadProto, UhidManager};
 use anyhow::{Context, Result};
 use punktfunk_core::quic::{HidOutput, RichInput};
@@ -25,20 +30,6 @@ use std::fs::{File, OpenOptions};
 use std::io::{Read, Write};
 use std::os::unix::fs::OpenOptionsExt;
 
-// /dev/uhid event ABI (linux/uhid.h) — identical to the DualSense backend's; see `super::dualsense`.
-const UHID_PATH: &str = "/dev/uhid";
-const UHID_DESTROY: u32 = 1;
-const UHID_OUTPUT: u32 = 6;
-const UHID_GET_REPORT: u32 = 9;
-const UHID_GET_REPORT_REPLY: u32 = 10;
-const UHID_CREATE2: u32 = 11;
-const UHID_INPUT2: u32 = 12;
-const UHID_SET_REPORT: u32 = 13;
-const UHID_SET_REPORT_REPLY: u32 = 14;
-const HID_MAX_DESCRIPTOR_SIZE: usize = 4096;
-const UHID_EVENT_SIZE: usize = 4 + 4372; // type + union (create2)
-const BUS_USB: u16 = 0x03;
-
 // Feature reports `hid-playstation` GET_REPORTs during DS4 init. The PAIRING report (0x12) is
 // MANDATORY — without a valid reply `dualshock4_create()` aborts and creates NO input devices; the
 // kernel reads the 6-byte device MAC from bytes 1..7. CALIBRATION (0x02) and FIRMWARE (0xa3) are
@@ -144,12 +135,6 @@ const DS4_RDESC: &[u8] = &[
     0xB1, 0x02, 0xC0,
 ];
 
-/// Copy a NUL-padded C string field into the event buffer.
-fn put_cstr(ev: &mut [u8], off: usize, cap: usize, s: &str) {
-    let n = s.len().min(cap - 1);
-    ev[off..off + n].copy_from_slice(&s.as_bytes()[..n]); // rest already zero (NUL-terminated)
-}
-
 /// A virtual DualShock 4 backed by `/dev/uhid` (hand-rolled codec mirroring the DualSense pad's).
 /// Dropping it destroys the device (the kernel tears down the bound `hid-playstation` interface).
 pub struct DualShock4Pad {

crates/pf-inject/src/inject/linux/gamepad.rs

@@ -254,13 +254,45 @@ fn ioctl_ptr<T>(fd: i32, req: libc::c_ulong, arg: *mut T, what: &str) -> Result<
     Ok(())
 }
 
+/// The window a played effect occupies: `replay.delay` of silence, then `replay.length` of rumble.
+#[derive(Clone, Copy)]
+struct Playback {
+    /// When the effect starts contributing — `play + replay.delay`. Until then it is armed but
+    /// silent, which is the whole point of the delay.
+    starts: Instant,
+    /// When it stops, or `None` for replay length 0 (until explicitly stopped).
+    ends: Option<Instant>,
+}
+
 /// One FF effect a game uploaded: rumble magnitudes + playback state.
 struct Effect {
     strong: u16,
     weak: u16,
-    /// `Some(deadline)` while playing (replay length 0 = until stopped).
-    playing: Option<Option<Instant>>,
+    /// `Some(window)` while playing.
+    playing: Option<Playback>,
     replay_ms: u16,
+    /// `replay.delay` — how long after the play command the effect stays silent. Decoded from the
+    /// upload since forever and, until now, never acted on: the effect started immediately and
+    /// ended `replay.length` later, so anything scheduling a delayed effect (DirectInput under
+    /// Wine does this routinely) fired early AND finished early by the same amount.
+    delay_ms: u16,
+}
+
+impl Effect {
+    /// The window a play command at `at` opens: silent for `replay.delay`, then `replay.length` of
+    /// rumble (or until stopped, when the length is 0).
+    ///
+    /// `replay.length` is measured from the END of the delay, not from the play command, so the
+    /// delay shifts the whole window instead of eating into it. Split out from the `EV_FF` handler
+    /// purely so this is testable — the handler itself needs a live uinput fd.
+    fn window(&self, at: Instant) -> Playback {
+        let starts = at + Duration::from_millis(self.delay_ms as u64);
+        Playback {
+            starts,
+            ends: (self.replay_ms > 0)
+                .then(|| starts + Duration::from_millis(self.replay_ms as u64)),
+        }
+    }
 }
 
 /// The force-feedback half of a virtual pad — the game-side effect table plus the mixdown policy
@@ -268,7 +300,6 @@ struct Effect {
 /// the policy is pure and unit-testable without a live uinput fd.
 struct FfState {
     effects: HashMap<i16, Effect>,
-    next_effect_id: i16,
     gain: u32,
     /// Last `(low, high)` reported, to dedup.
     last_mix: (u16, u16),
@@ -284,7 +315,6 @@ impl FfState {
     fn new() -> FfState {
         FfState {
             effects: HashMap::new(),
-            next_effect_id: 0,
             gain: 0xFFFF,
             last_mix: (0, 0),
             last_activity: Instant::now(),
@@ -299,17 +329,29 @@ impl FfState {
     /// Mix: sum playing effects (expiring finished ones, force-stopping abandoned infinite ones),
     /// scale by gain. Returns the new `(low, high)` only when it changed since the last call.
     fn mix(&mut self, now: Instant, idle: Option<Duration>) -> Option<(u16, u16)> {
-        let stale = idle.is_some_and(|t| now.duration_since(self.last_activity) >= t);
+        let quiet_since = |t: Instant| idle.is_some_and(|d| now.duration_since(t) >= d);
+        let plane_stale = quiet_since(self.last_activity);
         let (mut strong, mut weak) = (0u32, 0u32);
         for e in self.effects.values_mut() {
-            let Some(deadline) = e.playing else { continue };
-            match deadline {
+            let Some(p) = e.playing else { continue };
+            // Still inside `replay.delay`: armed, silent, and NOT a candidate for expiry or the
+            // abandoned-effect force-off — it has not had its turn yet.
+            if now < p.starts {
+                continue;
+            }
+            match p.ends {
                 Some(d) if now >= d => e.playing = None,
                 // An infinite-replay effect the game stopped driving (no FF traffic for the whole
                 // idle window) — the alive-but-abandoned case the kernel's close-time auto-erase
                 // cannot see. Stop it once; a later EV_FF play re-arms it (and refreshes the
                 // clock). Mirrors the XUSB/UHID abandoned-rumble force-off.
-                None if stale => {
+                //
+                // "Abandoned" needs the effect to have been AUDIBLE for the window too, not just
+                // the plane quiet: the play command is itself the last activity, so an effect with
+                // a `replay.delay` longer than the window would otherwise be force-stopped the
+                // instant it finally started — silent the whole time it waited, then killed on its
+                // first contributing tick.
+                None if plane_stale && quiet_since(p.starts) => {
                     tracing::info!(
                         strong = e.strong,
                         weak = e.weak,
@@ -531,11 +573,13 @@ impl VirtualPad {
                     let mut up: UinputFfUpload = unsafe { std::mem::zeroed() };
                     up.request_id = ev.value as u32;
                     if ioctl_ptr(raw, UI_BEGIN_FF_UPLOAD, &mut up, "UI_BEGIN_FF_UPLOAD").is_ok() {
-                        let mut e = up.effect;
-                        if e.id == -1 {
-                            e.id = self.ff.next_effect_id;
-                            self.ff.next_effect_id = self.ff.next_effect_id.wrapping_add(1);
-                        }
+                        let e = up.effect;
+                        // No `id == -1` fallback: ff-core's `input_ff_upload` picks a free slot and
+                        // writes it into the effect BEFORE handing the request to uinput, so what
+                        // arrives here is always an assigned id. The fallback that used to allocate
+                        // one from a local counter could therefore never run, and a local counter is
+                        // the wrong answer anyway — the kernel owns that id space.
+                        debug_assert!(e.id >= 0, "uinput handed us an unassigned FF effect id");
                         if e.type_ == FF_RUMBLE {
                             let strong = u16::from_ne_bytes([e.u[0], e.u[1]]);
                             let weak = u16::from_ne_bytes([e.u[2], e.u[3]]);
@@ -544,10 +588,12 @@ impl VirtualPad {
                                 weak: 0,
                                 playing: None,
                                 replay_ms: 0,
+                                delay_ms: 0,
                             });
                             slot.strong = strong;
                             slot.weak = weak;
                             slot.replay_ms = e.replay_length;
+                            slot.delay_ms = e.replay_delay;
                         }
                         up.effect.id = e.id; // hand the assigned slot back to the kernel
                         up.retval = 0;
@@ -574,14 +620,7 @@ impl VirtualPad {
                 (EV_FF, code) => {
                     self.ff.note_activity();
                     if let Some(e) = self.ff.effects.get_mut(&(code as i16)) {
-                        e.playing = if ev.value != 0 {
-                            Some((e.replay_ms > 0).then(|| {
-                                Instant::now()
-                                    + std::time::Duration::from_millis(e.replay_ms as u64)
-                            }))
-                        } else {
-                            None
-                        };
+                        e.playing = (ev.value != 0).then(|| e.window(Instant::now()));
                     }
                 }
                 _ => {}
@@ -802,15 +841,34 @@ mod ff_state_tests {
         ff
     }
 
+    /// Playing from `at`, no delay, until explicitly stopped.
+    fn playing(at: Instant) -> Option<Playback> {
+        Some(Playback {
+            starts: at,
+            ends: None,
+        })
+    }
+
+    /// Playing from `at`, no delay, for `len`.
+    fn playing_for(at: Instant, len: Duration) -> Option<Playback> {
+        Some(Playback {
+            starts: at,
+            ends: Some(at + len),
+        })
+    }
+
     #[test]
     fn abandoned_infinite_effect_is_forced_off_after_idle_window() {
+        let now = Instant::now();
         let mut ff = ff_with(Effect {
             strong: 0x8000,
             weak: 0,
-            playing: Some(None),
+            // Playing since before the window: "abandoned" means audible AND unattended, so an
+            // effect that only just started is not a candidate however stale the plane is.
+            playing: playing(now - Duration::from_millis(2600)),
             replay_ms: 0,
+            delay_ms: 0,
         });
-        let now = Instant::now();
         assert_eq!(ff.mix(now, IDLE), Some((scaled(0x8000), 0)));
         assert_eq!(ff.mix(now, IDLE), None); // unchanged level dedups, still playing
                                              // The game goes silent on the FF plane past the idle window: cut, exactly once.
@@ -825,8 +883,9 @@ mod ff_state_tests {
         let mut ff = ff_with(Effect {
             strong: 0x4000,
             weak: 0,
-            playing: Some(Some(now + Duration::from_secs(10))),
+            playing: playing_for(now, Duration::from_secs(10)),
             replay_ms: 10_000,
+            delay_ms: 0,
         });
         // FF plane long stale, but the effect declared a finite replay — the declared duration is
         // the contract (a real pad honors it too), so it keeps playing…
@@ -842,26 +901,135 @@ mod ff_state_tests {
         let mut ff = ff_with(Effect {
             strong: 0x8000,
             weak: 0,
-            playing: Some(None),
+            playing: playing(now - Duration::from_millis(3000)),
             replay_ms: 0,
+            delay_ms: 0,
         });
         assert_eq!(ff.mix(now, IDLE), Some((scaled(0x8000), 0)));
         ff.last_activity = now - Duration::from_millis(3000);
         assert_eq!(ff.mix(now, IDLE), Some((0, 0)));
         // The game plays the effect again — an FF event refreshes the clock and re-arms playback.
         ff.last_activity = now;
-        ff.effects.get_mut(&0).unwrap().playing = Some(None);
+        ff.effects.get_mut(&0).unwrap().playing = playing(now);
         assert_eq!(ff.mix(now, IDLE), Some((scaled(0x8000), 0)));
     }
 
+    /// `replay.delay` shifts the whole window: silent until it elapses, then the FULL
+    /// `replay.length`. Before this the delay was decoded and dropped, so a delayed effect both
+    /// started early and finished early — DirectInput under Wine schedules these routinely.
+    #[test]
+    fn replay_delay_holds_the_effect_off_then_gives_it_its_full_length() {
+        let now = Instant::now();
+        let starts = now + Duration::from_millis(500);
+        let mut ff = ff_with(Effect {
+            strong: 0x8000,
+            weak: 0,
+            playing: Some(Playback {
+                starts,
+                ends: Some(starts + Duration::from_secs(1)),
+            }),
+            replay_ms: 1000,
+            delay_ms: 500,
+        });
+        // Inside the delay: armed but silent.
+        assert_eq!(ff.mix(now, IDLE), None);
+        assert_eq!(ff.mix(now + Duration::from_millis(499), IDLE), None);
+        // Delay elapsed: it plays.
+        assert_eq!(
+            ff.mix(now + Duration::from_millis(501), IDLE),
+            Some((scaled(0x8000), 0))
+        );
+        // Still playing at 1400 ms — it gets its full second FROM the delay, not from the play.
+        assert_eq!(ff.mix(now + Duration::from_millis(1400), IDLE), None);
+        // And ends at delay + length, not at length.
+        assert_eq!(
+            ff.mix(now + Duration::from_millis(1600), IDLE),
+            Some((0, 0))
+        );
+    }
+
+    /// The window a play opens, straight from the uploaded fields — this is the half that reads
+    /// `replay.delay` at all. Pinned separately because the `EV_FF` handler that calls it needs a
+    /// live uinput fd, so a test driving `mix` alone would pass with the delay ignored entirely.
+    #[test]
+    fn window_offsets_the_whole_playback_by_replay_delay() {
+        let at = Instant::now();
+
+        let delayed = Effect {
+            strong: 0,
+            weak: 0,
+            playing: None,
+            replay_ms: 1000,
+            delay_ms: 500,
+        };
+        let w = delayed.window(at);
+        assert_eq!(
+            w.starts,
+            at + Duration::from_millis(500),
+            "delay defers the start"
+        );
+        assert_eq!(
+            w.ends,
+            Some(at + Duration::from_millis(1500)),
+            "length runs from the END of the delay, so the effect keeps its full second"
+        );
+
+        // No delay: starts immediately, unchanged from before.
+        let plain = Effect {
+            strong: 0,
+            weak: 0,
+            playing: None,
+            replay_ms: 1000,
+            delay_ms: 0,
+        };
+        let w = plain.window(at);
+        assert_eq!(w.starts, at);
+        assert_eq!(w.ends, Some(at + Duration::from_millis(1000)));
+
+        // Length 0 = until stopped, but the delay still applies.
+        let infinite = Effect {
+            strong: 0,
+            weak: 0,
+            playing: None,
+            replay_ms: 0,
+            delay_ms: 250,
+        };
+        let w = infinite.window(at);
+        assert_eq!(w.starts, at + Duration::from_millis(250));
+        assert_eq!(w.ends, None);
+    }
+
+    /// A delayed effect must not be force-stopped as "abandoned" while it is still waiting: it has
+    /// not had its turn, and the idle window is shorter than a delay can legitimately be.
+    #[test]
+    fn a_waiting_effect_is_not_cut_by_the_idle_watchdog() {
+        let now = Instant::now();
+        let starts = now + Duration::from_secs(5);
+        let mut ff = ff_with(Effect {
+            strong: 0x8000,
+            weak: 0,
+            playing: Some(Playback { starts, ends: None }),
+            replay_ms: 0,
+            delay_ms: 5000,
+        });
+        ff.last_activity = now - Duration::from_secs(60); // long stale
+        assert_eq!(ff.mix(now, IDLE), None); // silent, but NOT cut
+                                             // It still plays when its delay elapses.
+        assert_eq!(
+            ff.mix(now + Duration::from_millis(5001), IDLE),
+            Some((scaled(0x8000), 0))
+        );
+    }
+
     #[test]
     fn disabled_watchdog_never_cuts() {
         let now = Instant::now();
         let mut ff = ff_with(Effect {
             strong: 0x8000,
             weak: 0,
-            playing: Some(None),
+            playing: playing(now),
             replay_ms: 0,
+            delay_ms: 0,
         });
         ff.last_activity = now - Duration::from_secs(600);
         assert_eq!(ff.mix(now, None), Some((scaled(0x8000), 0)));

crates/pf-inject/src/inject/linux/steam_controller.rs

@@ -23,6 +23,11 @@ use super::steam_proto::{
     btn, parse_steam_output, sc_from_gamepad, serial_reply, serialize_deck_state,
     serialize_sc_state, SteamModel, SteamState, STEAMDECK_RDESC, STEAM_REPORT_LEN, STEAM_VENDOR,
 };
+use crate::uhid_abi::{
+    put_cstr, request_id, set_report_data, BUS_USB, HID_MAX_DESCRIPTOR_SIZE, UHID_CREATE2,
+    UHID_DESTROY, UHID_EVENT_SIZE, UHID_GET_REPORT, UHID_GET_REPORT_REPLY, UHID_INPUT2,
+    UHID_OUTPUT, UHID_PATH, UHID_SET_REPORT, UHID_SET_REPORT_REPLY,
+};
 use crate::uhid_manager::{PadFeedback, PadProto, UhidManager};
 use anyhow::{Context, Result};
 use punktfunk_core::quic::RichInput;
@@ -32,20 +37,6 @@ use std::os::unix::fs::OpenOptionsExt;
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::time::{Duration, Instant};
 
-// /dev/uhid event ABI — same layout as the DualSense backend.
-const UHID_PATH: &str = "/dev/uhid";
-const UHID_DESTROY: u32 = 1;
-const UHID_OUTPUT: u32 = 6;
-const UHID_GET_REPORT: u32 = 9;
-const UHID_GET_REPORT_REPLY: u32 = 10;
-const UHID_CREATE2: u32 = 11;
-const UHID_INPUT2: u32 = 12;
-const UHID_SET_REPORT: u32 = 13;
-const UHID_SET_REPORT_REPLY: u32 = 14;
-const HID_MAX_DESCRIPTOR_SIZE: usize = 4096;
-const UHID_EVENT_SIZE: usize = 4 + 4372;
-const BUS_USB: u16 = 0x03;
-
 /// Hold the `b9.6` mode-switch this long at creation to toggle `gamepad_mode` on (the kernel needs
 /// ~450 ms continuous; give margin).
 const MODE_ENTER: Duration = Duration::from_millis(650);
@@ -53,11 +44,6 @@ const MODE_ENTER: Duration = Duration::from_millis(650);
 /// we insert a one-frame release so an in-game long-Start-hold can't toggle `gamepad_mode` off.
 const MENU_HOLD_CAP: Duration = Duration::from_millis(350);
 
-fn put_cstr(ev: &mut [u8], off: usize, cap: usize, s: &str) {
-    let n = s.len().min(cap - 1);
-    ev[off..off + n].copy_from_slice(&s.as_bytes()[..n]);
-}
-
 /// Best-effort, once per process: clear `hid_steam`'s `lizard_mode` so `steam_do_deck_input_event`
 /// stops gating on `gamepad_mode` (gamepad events then always flow). Needs root; on failure the
 /// per-pad `b9.6` pulse + guard handle it instead.
@@ -214,10 +200,13 @@ impl SteamDeckPad {
                     let _ = self.reply_get_report(id, &serial_reply("PUNKTFUNK01"));
                 }
                 UHID_SET_REPORT => {
-                    let id = u32::from_ne_bytes([ev[4], ev[5], ev[6], ev[7]]);
-                    // SET_REPORT data: [report-id 0, cmd, …] at ev[12..]. Surface rumble, then ack.
-                    let end = (12 + 16).min(UHID_EVENT_SIZE);
-                    if let Some(r) = parse_steam_output(&ev[12..end]).rumble {
+                    let id = request_id(&ev);
+                    // SET_REPORT data: [report-id 0, cmd, …]. Take exactly the bytes the kernel
+                    // declared — this used to read a fixed 16-byte window, which truncated any
+                    // longer report and, for a shorter one, fed the parser whatever the reused
+                    // event buffer still held past the payload. Every sibling backend that parses
+                    // SET_REPORT already read the size field; this one didn't.
+                    if let Some(r) = parse_steam_output(set_report_data(&ev)).rumble {
                         rumble = Some(r);
                     }
                     let _ = self.reply_set_report(id);

crates/pf-inject/src/inject/linux/steam_controller2.rs

@@ -23,6 +23,11 @@ use super::triton_proto::{
     triton_serial, triton_unit_id, TritonState, TRITON_RDESC, TRITON_STATE_LEN, TRITON_VENDOR,
     TRITON_WIRED_PRODUCT,
 };
+use crate::uhid_abi::{
+    put_cstr, BUS_USB, HID_MAX_DESCRIPTOR_SIZE, UHID_CREATE2, UHID_DESTROY, UHID_EVENT_SIZE,
+    UHID_GET_REPORT, UHID_GET_REPORT_REPLY, UHID_INPUT2, UHID_OUTPUT, UHID_PATH, UHID_SET_REPORT,
+    UHID_SET_REPORT_REPLY,
+};
 use crate::uhid_manager::{PadFeedback, PadProto, UhidManager};
 use anyhow::{Context, Result};
 use punktfunk_core::quic::{HidOutput, RichInput, HID_RAW_FEATURE, HID_RAW_OUTPUT};
@@ -30,25 +35,6 @@ use std::fs::{File, OpenOptions};
 use std::io::{Read, Write};
 use std::os::unix::fs::OpenOptionsExt;
 
-// /dev/uhid event ABI — same layout as the Deck/DualSense backends.
-const UHID_PATH: &str = "/dev/uhid";
-const UHID_DESTROY: u32 = 1;
-const UHID_OUTPUT: u32 = 6;
-const UHID_GET_REPORT: u32 = 9;
-const UHID_GET_REPORT_REPLY: u32 = 10;
-const UHID_CREATE2: u32 = 11;
-const UHID_INPUT2: u32 = 12;
-const UHID_SET_REPORT: u32 = 13;
-const UHID_SET_REPORT_REPLY: u32 = 14;
-const HID_MAX_DESCRIPTOR_SIZE: usize = 4096;
-const UHID_EVENT_SIZE: usize = 4 + 4372;
-const BUS_USB: u16 = 0x03;
-
-fn put_cstr(ev: &mut [u8], off: usize, cap: usize, s: &str) {
-    let n = s.len().min(cap - 1);
-    ev[off..off + n].copy_from_slice(&s.as_bytes()[..n]);
-}
-
 /// A virtual Steam Controller 2 backed by `/dev/uhid`. Dropping it destroys the device.
 pub struct TritonPad {
     fd: File,

crates/pf-inject/src/inject/linux/switch_pro.rs

@@ -22,6 +22,10 @@ use super::switch_proto::{
     serialize_report_0x30, spi_flash_read, switch_mac, SwitchOutput, SwitchState, PROCON_RDESC,
     SWITCH_PRODUCT, SWITCH_REPORT_LEN, SWITCH_VENDOR,
 };
+use crate::uhid_abi::{
+    put_cstr, BUS_USB, HID_MAX_DESCRIPTOR_SIZE, UHID_CREATE2, UHID_DESTROY, UHID_EVENT_SIZE,
+    UHID_GET_REPORT, UHID_GET_REPORT_REPLY, UHID_INPUT2, UHID_OUTPUT, UHID_PATH,
+};
 use crate::uhid_manager::{PadFeedback, PadProto, UhidManager};
 use anyhow::{Context, Result};
 use punktfunk_core::quic::{HidOutput, RichInput};
@@ -29,24 +33,6 @@ use std::fs::{File, OpenOptions};
 use std::io::{Read, Write};
 use std::os::unix::fs::OpenOptionsExt;
 
-// /dev/uhid event ABI (linux/uhid.h) — identical to the DualSense backend's; see `super::dualsense`.
-const UHID_PATH: &str = "/dev/uhid";
-const UHID_DESTROY: u32 = 1;
-const UHID_OUTPUT: u32 = 6;
-const UHID_GET_REPORT: u32 = 9;
-const UHID_GET_REPORT_REPLY: u32 = 10;
-const UHID_CREATE2: u32 = 11;
-const UHID_INPUT2: u32 = 12;
-const HID_MAX_DESCRIPTOR_SIZE: usize = 4096;
-const UHID_EVENT_SIZE: usize = 4 + 4372; // type + union (create2)
-const BUS_USB: u16 = 0x03;
-
-/// Copy a NUL-padded C string field into the event buffer.
-fn put_cstr(ev: &mut [u8], off: usize, cap: usize, s: &str) {
-    let n = s.len().min(cap - 1);
-    ev[off..off + n].copy_from_slice(&s.as_bytes()[..n]); // rest already zero (NUL-terminated)
-}
-
 /// A virtual Pro Controller backed by `/dev/uhid`. Dropping it destroys the device (the kernel
 /// tears down the bound `hid-nintendo` interface).
 pub struct SwitchProPad {

crates/pf-inject/src/inject/linux/uhid_abi.rs

@@ -0,0 +1,143 @@
+//! The `/dev/uhid` event ABI (`linux/uhid.h`), in one place.
+//!
+//! Every UHID gamepad backend — DualSense, DualShock 4, Switch Pro, Steam Controller and Steam
+//! Controller 2 — speaks the same kernel protocol, and each carried its own verbatim copy of these
+//! constants plus its own `put_cstr`. Five copies of one kernel ABI is five chances to drift from
+//! it, and they already had: `switch_pro` was missing the SET_REPORT pair entirely, and one backend
+//! read a fixed-size SET_REPORT payload instead of the length the kernel gave it (see
+//! [`set_report_data`]).
+//!
+//! `struct uhid_event` is `__packed__`: a `u32` `type` followed by a union whose largest member is
+//! `uhid_create2_req` (name 128 + phys 64 + uniq 64 + rd_size 2 + bus 2 + 4×u32 + rd_data 4096 =
+//! 4372 bytes). Nothing here allocates or parses a whole event — the backends still drive their own
+//! read/write loops; this module owns the numbers and the two field accessors that are easy to get
+//! subtly wrong.
+
+/// The character device every backend opens.
+pub const UHID_PATH: &str = "/dev/uhid";
+
+// Event types (`enum uhid_event_type`). Only the ones the backends actually use.
+pub const UHID_DESTROY: u32 = 1;
+pub const UHID_OUTPUT: u32 = 6;
+pub const UHID_GET_REPORT: u32 = 9;
+pub const UHID_GET_REPORT_REPLY: u32 = 10;
+pub const UHID_CREATE2: u32 = 11;
+pub const UHID_INPUT2: u32 = 12;
+pub const UHID_SET_REPORT: u32 = 13;
+pub const UHID_SET_REPORT_REPLY: u32 = 14;
+
+/// `HID_MAX_DESCRIPTOR_SIZE` — also the cap on a report payload we will copy out of an event.
+pub const HID_MAX_DESCRIPTOR_SIZE: usize = 4096;
+/// `size_of::<uhid_event>()`: the `u32` type tag plus the create2 union.
+pub const UHID_EVENT_SIZE: usize = 4 + 4372;
+/// `BUS_USB` from `linux/input.h`.
+pub const BUS_USB: u16 = 0x03;
+
+/// Offset of the `id` field shared by the GET_REPORT / SET_REPORT request and reply structs.
+const OFF_ID: usize = 4;
+/// Offset of `uhid_set_report_req::size` (after `id: u32`, `rnum: u8`, `rtype: u8`).
+const OFF_SET_REPORT_SIZE: usize = 10;
+/// Offset of the payload in a SET_REPORT request — and of `data` in the reply structs.
+const OFF_DATA: usize = 12;
+/// Offset of `uhid_output_req::size` (the payload follows `data[4096]`).
+const OFF_OUTPUT_SIZE: usize = 4 + HID_MAX_DESCRIPTOR_SIZE;
+
+/// Copy a NUL-padded C string field into the event buffer. The buffer is zeroed by the caller, so
+/// truncation still leaves a NUL terminator.
+pub fn put_cstr(ev: &mut [u8], off: usize, cap: usize, s: &str) {
+    let n = s.len().min(cap - 1);
+    ev[off..off + n].copy_from_slice(&s.as_bytes()[..n]); // rest already zero (NUL-terminated)
+}
+
+/// The request id of a GET_REPORT / SET_REPORT event — what the matching reply must echo.
+pub fn request_id(ev: &[u8]) -> u32 {
+    u32::from_ne_bytes([ev[OFF_ID], ev[OFF_ID + 1], ev[OFF_ID + 2], ev[OFF_ID + 3]])
+}
+
+/// The payload of a `UHID_SET_REPORT` event: exactly the bytes the kernel says are there.
+///
+/// Read the length from the event's own `size` field. Assuming a fixed window instead is wrong in
+/// both directions — a longer report is silently truncated, and a shorter one is parsed together
+/// with whatever stale bytes the reused event buffer still holds past its end, which for a rumble
+/// report means acting on numbers the game never wrote.
+pub fn set_report_data(ev: &[u8]) -> &[u8] {
+    let size = u16::from_ne_bytes([ev[OFF_SET_REPORT_SIZE], ev[OFF_SET_REPORT_SIZE + 1]]) as usize;
+    let end = (OFF_DATA + size.min(HID_MAX_DESCRIPTOR_SIZE)).min(ev.len());
+    &ev[OFF_DATA.min(end)..end]
+}
+
+/// The payload of a `UHID_OUTPUT` event (`uhid_output_req`: `data[4096]` then `size`).
+pub fn output_data(ev: &[u8]) -> &[u8] {
+    let size = u16::from_ne_bytes([ev[OFF_OUTPUT_SIZE], ev[OFF_OUTPUT_SIZE + 1]]) as usize;
+    let end = (4 + size.min(HID_MAX_DESCRIPTOR_SIZE)).min(ev.len());
+    &ev[4.min(end)..end]
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn blank() -> Vec<u8> {
+        vec![0u8; UHID_EVENT_SIZE]
+    }
+
+    #[test]
+    fn set_report_data_honours_the_events_own_size() {
+        let mut ev = blank();
+        ev[OFF_SET_REPORT_SIZE..OFF_SET_REPORT_SIZE + 2].copy_from_slice(&5u16.to_ne_bytes());
+        for (i, b) in [1u8, 2, 3, 4, 5].iter().enumerate() {
+            ev[OFF_DATA + i] = *b;
+        }
+        // Stale bytes past the payload — a fixed-window read would hand these to the parser.
+        ev[OFF_DATA + 5] = 0xAA;
+        ev[OFF_DATA + 15] = 0xBB;
+        assert_eq!(set_report_data(&ev), &[1, 2, 3, 4, 5]);
+    }
+
+    #[test]
+    fn set_report_data_is_not_truncated_at_sixteen() {
+        let mut ev = blank();
+        let n = 40usize;
+        ev[OFF_SET_REPORT_SIZE..OFF_SET_REPORT_SIZE + 2].copy_from_slice(&(n as u16).to_ne_bytes());
+        for i in 0..n {
+            ev[OFF_DATA + i] = i as u8;
+        }
+        let d = set_report_data(&ev);
+        assert_eq!(
+            d.len(),
+            n,
+            "a report longer than 16 bytes must survive whole"
+        );
+        assert_eq!(d[39], 39);
+    }
+
+    #[test]
+    fn oversized_and_empty_sizes_stay_in_bounds() {
+        let mut ev = blank();
+        ev[OFF_SET_REPORT_SIZE..OFF_SET_REPORT_SIZE + 2].copy_from_slice(&u16::MAX.to_ne_bytes());
+        assert!(set_report_data(&ev).len() <= HID_MAX_DESCRIPTOR_SIZE);
+        assert!(OFF_DATA + set_report_data(&ev).len() <= UHID_EVENT_SIZE);
+
+        let ev0 = blank(); // size = 0
+        assert!(set_report_data(&ev0).is_empty());
+        assert!(output_data(&ev0).is_empty());
+    }
+
+    #[test]
+    fn output_data_reads_its_trailing_size_field() {
+        let mut ev = blank();
+        ev[OFF_OUTPUT_SIZE..OFF_OUTPUT_SIZE + 2].copy_from_slice(&3u16.to_ne_bytes());
+        ev[4] = 0x02;
+        ev[5] = 0x11;
+        ev[6] = 0x22;
+        ev[7] = 0x33; // past the declared size
+        assert_eq!(output_data(&ev), &[0x02, 0x11, 0x22]);
+    }
+
+    #[test]
+    fn request_id_round_trips() {
+        let mut ev = blank();
+        ev[OFF_ID..OFF_ID + 4].copy_from_slice(&0xDEAD_BEEFu32.to_ne_bytes());
+        assert_eq!(request_id(&ev), 0xDEAD_BEEF);
+    }
+}

crates/pf-inject/src/inject/proto/dualsense_proto.rs

@@ -250,11 +250,19 @@ impl DsState {
         use punktfunk_core::input::gamepad as gs;
         let to_u8 = |v: i16| (((v as i32) + 32768) >> 8) as u8;
         let on = |bit: u32| buttons & bit != 0;
+        // Invert in i16 space, BEFORE the quantisation, rather than as `255 - to_u8(v)`.
+        // 0..=255 has no exact midpoint: `to_u8` puts centre at 0x80, which leaves 128 codes below
+        // it and 127 above, so mirroring the *output* (`255 - 0x80` = 0x7F) lands a centred stick
+        // one LSB off the 0x80 that `DsState::neutral` — and the pad's own resting report — use.
+        // Games idle-poll a centred stick constantly, so that off-by-one showed up as a permanent
+        // sub-deadzone tilt on the Y axes only. Negating first maps centre to centre by
+        // construction and keeps both extremes exact (+32767 → 0, -32768 → 255); the only cost is
+        // that i16::MIN and -32767 share the 255 code, one LSB at the very end of the travel.
         let mut s = DsState {
             lx: to_u8(lx),
-            ly: 255 - to_u8(ly),
+            ly: to_u8(ly.saturating_neg()),
             rx: to_u8(rx),
-            ry: 255 - to_u8(ry),
+            ry: to_u8(ry.saturating_neg()),
             l2: lt,
             r2: rt,
             ..DsState::neutral()
@@ -471,7 +479,14 @@ fn pack_touch(dst: &mut [u8], t: &Touch) {
 #[derive(Default)]
 pub struct DsFeedback {
     pub hidout: Vec<HidOutput>,
-    /// `(low, high)` motor levels (0..=0xFFFF), if a report carried them.
+    /// `(low, high)` motor levels, if a report carried them.
+    ///
+    /// This parser widens the device's 8-bit motor bytes by `<< 8`, so the values it produces are
+    /// `0..=0xFF00` in steps of 0x100 — NOT `0..=0xFFFF`, which is what this said before. The
+    /// Windows backend widens the same bytes by `× 257` and does reach 0xFFFF. Both are correct:
+    /// every consumer narrows with `>> 8`, and 0xFF00 and 0xFFFF both narrow back to 255. Do not
+    /// "fix" one to match the other — see [`crate::uhid_manager::PadFeedback::rumble`], which is
+    /// the type that sees both.
     pub rumble: Option<(u16, u16)>,
     /// The driver's output-report ring overflowed this poll — pending reports were DISCARDED and
     /// feedback state is unknown; the [`UhidManager`](crate::uhid_manager) must resync (silence +
@@ -479,64 +494,101 @@ pub struct DsFeedback {
     pub resync: bool,
 }
 
-/// Parse a DualSense USB output report (`0x02`) into a [`DsFeedback`]. The byte layout below is
-/// the USB DualSense common report; only the well-understood fields (motor rumble, lightbar RGB,
-/// player LEDs) are surfaced — adaptive-trigger blocks are forwarded raw for the client.
+/// Field offsets in the DualSense **output** report, as indices into a whole USB report — i.e.
+/// including the leading report id at `[0]`. This is the one place in Rust the layout is written
+/// down; index off these rather than repeating the numbers.
+///
+/// **The same fields sit at different offsets per transport, and that is not drift.** Every writer
+/// lays out one common block; what changes is how much header precedes it:
+///
+/// | base | where | first payload byte |
+/// |---|---|---|
+/// | `0`  | USB report, id included — what these constants describe, and what this parser reads | `[1]` |
+/// | `−1` | SDL `DS5EffectsState_t` — a 47-byte payload with NO report id (`pf-client-core`'s `Ds5Feedback`) | `[0]` |
+/// | `+2` | Bluetooth report `0x31` — id, sequence, magic, then the block; CRC32 in the last 4 bytes | `[3]` |
+///
+/// Subtract or add the base to translate. Mirrors that cannot import this module — Kotlin
+/// (`DsDevice.kt`, USB base 0) and Swift (`DualSenseHID.swift`, which handles both the USB and
+/// Bluetooth bases) — carry a pointer back here; keep them in step by hand.
+pub mod out_report {
+    /// `valid_flag0`: BIT0 compat vibration, BIT1 haptics select, BIT2 R2, BIT3 L2.
+    pub const VALID_FLAG0: usize = 1;
+    /// `valid_flag1`: BIT2 lightbar, BIT4 player indicators.
+    pub const VALID_FLAG1: usize = 2;
+    /// High-frequency (small / right) motor.
+    pub const MOTOR_RIGHT: usize = 3;
+    /// Low-frequency (big / left) motor.
+    pub const MOTOR_LEFT: usize = 4;
+    /// First byte of the RIGHT trigger's parameter block — it precedes the left one in the report.
+    pub const RIGHT_TRIGGER: usize = 11;
+    /// First byte of the LEFT trigger's parameter block.
+    pub const LEFT_TRIGGER: usize = 22;
+    /// One adaptive-trigger parameter block: a mode byte plus 10 parameters.
+    pub const TRIGGER_LEN: usize = 11;
+    /// `valid_flag2`: BIT2 = `COMPATIBLE_VIBRATION2` (the firmware ≥ 2.24 rumble signal).
+    pub const VALID_FLAG2: usize = 39;
+    /// Lit player-indicator bits (low 5).
+    pub const PLAYER_LEDS: usize = 44;
+    /// Lightbar red; green and blue follow.
+    pub const LED_RGB: usize = 45;
+}
+
+/// Parse a DualSense USB output report (`0x02`) into a [`DsFeedback`], indexed off
+/// [`out_report`]. Only the well-understood fields (motor rumble, lightbar RGB, player LEDs) are
+/// surfaced — adaptive-trigger blocks are forwarded raw for the client.
 ///
 /// Every field is gated on the report's valid-flags (`valid_flag0` at data[1], `valid_flag1`
 /// at data[2]) — writers only set the bits for fields they mean to change (the rest is zeroed),
 /// so an ungated parse would turn every plain rumble write into a lightbar-off + triggers-off
 /// broadcast.
 pub fn parse_ds_output(pad: u8, data: &[u8], fb: &mut DsFeedback) {
+    use out_report as o;
     // data[0] is the report id (0x02). Be defensive about short reports.
     if data.first() != Some(&0x02) || data.len() < 48 {
         return;
     }
-    let flag0 = data[1]; // BIT0 compat vibration, BIT1 haptics select, BIT2 R2, BIT3 L2
-    let flag1 = data[2]; // BIT2 lightbar, BIT4 player indicators
-                         // Motor rumble: high-frequency (small/right) motor at data[3], low-frequency (big/left) at
-                         // data[4]. Scale 0..255 → 0..0xFFFF, same (low, high) convention as the uinput pad's mixer,
-                         // and route to the universal rumble plane (0xCA).
-                         // Writers on firmware ≥ 2.24 signal rumble via COMPATIBLE_VIBRATION2 in valid_flag2
-                         // (data[39] BIT2) instead of flag0 BIT0. Our feature report advertises a version
-                         // above 2.24 (DS_FEATURE_FIRMWARE bytes 44..46, chosen to keep Sony's updater
-                         // quiet), so the kernel and SDL write the v2 flag — while older writers, and any
-                         // that never read the version, stay on flag0. Both conventions must land here: a
-                         // rumble dropped on either — including stops — is silently ignored, and a missed
-                         // stop buzzes for the rest of the session (the 500 ms refresh re-sends stale state
-                         // forever).
-    if flag0 & 0x03 != 0 || data[39] & 0x04 != 0 {
-        let high = (data[3] as u16) << 8;
-        let low = (data[4] as u16) << 8;
+    let flag0 = data[o::VALID_FLAG0]; // BIT0 compat vibration, BIT1 haptics select, BIT2 R2, BIT3 L2
+    let flag1 = data[o::VALID_FLAG1]; // BIT2 lightbar, BIT4 player indicators
+                                      // Motor rumble: high-frequency (small/right) motor first, low-frequency (big/left) second.
+                                      // Widened 0..255 → 0..0xFF00 by `<< 8` (NOT 0xFFFF — see `DsFeedback::rumble`), same
+                                      // (low, high) convention as the uinput pad's mixer, and routed to the 0xCA plane.
+                                      // Writers on firmware ≥ 2.24 signal rumble via COMPATIBLE_VIBRATION2 in valid_flag2
+                                      // instead of flag0 BIT0. Our feature report advertises a version above 2.24
+                                      // (DS_FEATURE_FIRMWARE bytes 44..46, chosen to keep Sony's updater quiet), so the
+                                      // kernel and SDL write the v2 flag — while older writers, and any that never read the
+                                      // version, stay on flag0. Both conventions must land here: a rumble dropped on either
+                                      // — including stops — is silently ignored, and a missed stop buzzes for the rest of
+                                      // the session (the 500 ms refresh re-sends stale state forever).
+    if flag0 & 0x03 != 0 || data[o::VALID_FLAG2] & 0x04 != 0 {
+        let high = (data[o::MOTOR_RIGHT] as u16) << 8;
+        let low = (data[o::MOTOR_LEFT] as u16) << 8;
         fb.rumble = Some((low, high));
     }
-    // Lightbar RGB (USB common report: bytes 45..48). Player LEDs at byte 44.
     if flag1 & 0x04 != 0 {
-        let (r, g, b) = (data[45], data[46], data[47]);
+        let (r, g, b) = (data[o::LED_RGB], data[o::LED_RGB + 1], data[o::LED_RGB + 2]);
         fb.hidout.push(HidOutput::Led { pad, r, g, b });
     }
     if flag1 & 0x10 != 0 {
         fb.hidout.push(HidOutput::PlayerLeds {
             pad,
-            bits: data[44] & 0x1F,
+            bits: data[o::PLAYER_LEDS] & 0x1F,
         });
     }
-    // Adaptive-trigger parameter blocks, 11 bytes each: the RIGHT trigger comes FIRST in the
-    // report (bytes 11..22), the left at 22..33 — per SDL's DS5EffectsState_t / inputtino's
-    // ps5.hpp. Wire convention: which 0 = L2, 1 = R2.
-    if data.len() >= 33 {
+    // The RIGHT trigger block comes FIRST in the report — per SDL's DS5EffectsState_t /
+    // inputtino's ps5.hpp. Wire convention: which 0 = L2, 1 = R2.
+    if data.len() >= o::LEFT_TRIGGER + o::TRIGGER_LEN {
         if flag0 & 0x04 != 0 {
             fb.hidout.push(HidOutput::Trigger {
                 pad,
                 which: 1,
-                effect: data[11..22].to_vec(),
+                effect: data[o::RIGHT_TRIGGER..o::RIGHT_TRIGGER + o::TRIGGER_LEN].to_vec(),
             });
         }
         if flag0 & 0x08 != 0 {
             fb.hidout.push(HidOutput::Trigger {
                 pad,
                 which: 0,
-                effect: data[22..33].to_vec(),
+                effect: data[o::LEFT_TRIGGER..o::LEFT_TRIGGER + o::TRIGGER_LEN].to_vec(),
             });
         }
     }
@@ -783,6 +835,29 @@ mod tests {
         assert_eq!(r[53], 0x0A);
     }
 
+    /// A centred stick must encode as the pad's own neutral on BOTH axes. Inverting the quantised
+    /// byte (`255 - v`) put Y one LSB below it, which games idle-poll constantly — a permanent
+    /// sub-deadzone tilt. Extremes must stay exact either way.
+    #[test]
+    fn centred_sticks_encode_as_neutral_on_every_axis() {
+        let n = DsState::neutral();
+        let s = DsState::from_gamepad(0, 0, 0, 0, 0, 0, 0);
+        assert_eq!((s.lx, s.ly), (n.lx, n.ly), "left stick centre");
+        assert_eq!((s.rx, s.ry), (n.rx, n.ry), "right stick centre");
+
+        // Y is still inverted (XInput +y = up, DualSense 0 = up) and both ends stay exact.
+        let up = DsState::from_gamepad(0, 0, i16::MAX, 0, i16::MAX, 0, 0);
+        assert_eq!((up.ly, up.ry), (0, 0), "full up = 0");
+        let down = DsState::from_gamepad(0, 0, i16::MIN, 0, i16::MIN, 0, 0);
+        assert_eq!((down.ly, down.ry), (255, 255), "full down = 255");
+
+        // X keeps its existing mapping.
+        let right = DsState::from_gamepad(0, i16::MAX, 0, i16::MAX, 0, 0, 0);
+        assert_eq!((right.lx, right.rx), (255, 255));
+        let left = DsState::from_gamepad(0, i16::MIN, 0, i16::MIN, 0, 0, 0);
+        assert_eq!((left.lx, left.rx), (0, 0));
+    }
+
     /// The wire touchpad-click / guide / mute bits (Moonlight's extended positions) land in
     /// `buttons[2]`.
     #[test]

crates/pf-inject/src/inject/proto/steam_proto.rs

@@ -183,8 +183,9 @@ impl SteamState {
 
     /// Map an `XInput`/GameStream pad frame (button bitmask + i16 sticks + u8 triggers) into the Deck
     /// state. Sticks pass through (the kernel negates Y, which yields the conventional direction —
-    /// validated on-box); triggers scale u8 0..255 → u16 0..32640 and set the full-pull bit when
-    /// pressed. Trackpad + motion + the back grips arrive separately ([`apply_rich`], the M3 wire).
+    /// validated on-box); triggers scale u8 0..255 → u16 0..32767 ([`trigger_u16`]) and set the
+    /// full-pull bit when pressed. Trackpad + motion + the back grips arrive separately
+    /// ([`apply_rich`], the M3 wire).
     pub fn from_gamepad(
         buttons: u32,
         lx: i16,
@@ -200,8 +201,8 @@ impl SteamState {
             ly,
             rx,
             ry,
-            lt: (lt as u16) * 128,
-            rt: (rt as u16) * 128,
+            lt: trigger_u16(lt),
+            rt: trigger_u16(rt),
             ..SteamState::neutral()
         };
         let mut b = 0u64;
@@ -375,8 +376,8 @@ pub fn sc_from_gamepad(
         ly,
         rx: 0,
         ry: 0,
-        lt: (lt as u16) * 128,
-        rt: (rt as u16) * 128,
+        lt: trigger_u16(lt),
+        rt: trigger_u16(rt),
         // The wire right stick becomes a right-pad contact (see the doc above).
         rpad_x: rx,
         rpad_y: ry,
@@ -466,6 +467,18 @@ pub fn serialize_sc_state(r: &mut [u8; STEAM_REPORT_LEN], st: &SteamState, seq:
     r[38..40].copy_from_slice(&st.gyro[2].to_le_bytes());
 }
 
+/// Scale a wire trigger (u8 `0..=255`) onto the Deck's full axis (u16 `0..=32767`).
+///
+/// This was `v * 128`, which tops out at 32640 — a fully-pulled trigger reported 99.6% and the top
+/// 127 counts of the declared range were unreachable, so a game reading the axis could never see a
+/// true full pull. One multiply gets both ends exact (`0 → 0`, `255 → 32767`) and stays monotonic.
+///
+/// `serialize_report`'s inverse (`>> 7`, for the legacy u8 trigger bytes) still round-trips both
+/// ends against this: `32767 >> 7 == 255`.
+fn trigger_u16(v: u8) -> u16 {
+    ((v as u32 * 32767) / 255) as u16
+}
+
 /// Build the `steam_get_serial` GET_REPORT reply. The Steam feature path is report-id-0 with a
 /// leading report-id byte the kernel strips (`steam_recv_report` does `memcpy(data, buf+1, …)`), so
 /// the wire is `[0x00, 0xAE, len, 0x01, ascii…]`; the kernel then validates `reply[0]==0xAE`,
@@ -473,7 +486,12 @@ pub fn serialize_sc_state(r: &mut [u8; STEAM_REPORT_LEN], st: &SteamState, seq:
 pub fn serial_reply(serial: &str) -> [u8; STEAM_REPORT_LEN] {
     let mut buf = [0u8; STEAM_REPORT_LEN];
     let bytes = serial.as_bytes();
-    let len = bytes.len().clamp(1, 21);
+    // `min`, not `clamp(1, 21)`. Clamping the LOW end to 1 and then slicing `bytes[..len]` asks a
+    // zero-byte slice for one byte, which panics — on the service thread, for an input the kernel
+    // already has a graceful answer to. Reporting the true length lets its own validation
+    // (`1 <= reply[1] <= 21`) reject an empty serial and fall back to "XXXXXXXXXX", which is the
+    // documented behaviour for a reply it does not like.
+    let len = bytes.len().min(21);
     buf[0] = 0x00; // report id 0 — stripped by steam_recv_report
     buf[1] = ID_GET_STRING_ATTRIBUTE;
     buf[2] = len as u8;
@@ -704,7 +722,7 @@ mod tests {
         assert_ne!(s.buttons & btn::STEAM, 0);
         assert_ne!(s.buttons & btn::LB, 0);
         assert_ne!(s.buttons & btn::LT_FULL, 0); // lt=255 → full-pull bit
-        assert_eq!(s.lt, 255 * 128);
+        assert_eq!(s.lt, 32767); // full pull reaches the TOP of the declared range
         assert_eq!(s.lx, 1000);
         assert_eq!(s.ly, -2000);
 
@@ -730,6 +748,30 @@ mod tests {
         assert_eq!(s.accel, [16384, -8192, 0]);
     }
 
+    /// An empty serial must not panic. `clamp(1, 21)` asked a zero-byte slice for one byte, which
+    /// is an out-of-range slice index — on the service thread. The kernel rejects a zero length by
+    /// its own rule (`1 <= reply[1] <= 21`) and falls back, which is the graceful answer.
+    #[test]
+    fn empty_serial_reply_does_not_panic() {
+        let r = serial_reply("");
+        assert_eq!(r[1], ID_GET_STRING_ATTRIBUTE);
+        assert_eq!(
+            r[2], 0,
+            "length the kernel will reject, rather than a panic"
+        );
+
+        // Normal and over-long serials still behave.
+        let r = serial_reply("ABC123");
+        assert_eq!(r[2], 6);
+        assert_eq!(&r[4..10], b"ABC123");
+        let long = "X".repeat(40);
+        assert_eq!(
+            serial_reply(&long)[2],
+            21,
+            "clamped to the protocol maximum"
+        );
+    }
+
     /// M3: the wire back-button bits map to the four Deck grips + QAM, and `TouchpadEx` routes the
     /// left / right surfaces to the matching pad (x passes straight through; y flips from the
     /// wire's screen convention (+down) to the Deck's raw +up — the live-verified direction).

crates/pf-inject/src/inject/uhid_manager.rs

@@ -18,7 +18,12 @@ use std::time::{Duration, Instant};
 /// 0xCD feedback events (lightbar / player LEDs / adaptive triggers), deduped via [`HidoutDedup`].
 #[derive(Default)]
 pub struct PadFeedback {
-    /// `(low, high)` motor levels (0..=0xFF00), if the pass saw a rumble report.
+    /// `(low, high)` motor levels, if the pass saw a rumble report.
+    ///
+    /// Range is `0..=0xFFFF` — this said `0..=0xFF00`, which is only true of the backends that
+    /// widen the device's 8-bit motor byte by `<< 8` (the UHID/DualSense path). The Windows
+    /// backend widens by `× 257` and does reach 0xFFFF, and this type carries both. Neither is a
+    /// defect: consumers narrow with `>> 8`, and 0xFF00 and 0xFFFF both narrow back to 255.
     pub rumble: Option<(u16, u16)>,
     pub hidout: Vec<HidOutput>,
     /// Whether the game drove this pad's RUMBLE plane this poll — at least one output report
@@ -159,6 +164,22 @@ impl OverflowWarn {
 /// real firmware decays, and that re-assert is what keeps a legitimately-held long rumble alive
 /// here. The XUSB path shares this window via [`rumble_idle_timeout`] (every XUSB write IS a
 /// rumble write, so its any-activity keying is already rumble-keyed by construction).
+///
+/// KNOWN COST, deliberately accepted. That invariant only covers writers that re-assert. A game
+/// driving the pad through the kernel's *evdev* FF interface does not: `ff-memless` sends one
+/// output report when an effect starts and one when it stops, with nothing in between, so a finite
+/// effect longer than this window is cut in half here. The uinput path
+/// (`linux/gamepad.rs`) exempts exactly that case — but it can, because evdev FF hands it an
+/// explicit `replay.length`. Nothing equivalent reaches this layer: [`PadFeedback`] carries motor
+/// levels, and the protocols it speaks (DualSense / DS4 / Deck / Switch Pro) are all
+/// level-triggered with no duration field anywhere in a report. So the choice is between cutting a
+/// long finite effect and letting an abandoned residual drone forever, and the residual is the one
+/// with field evidence behind it (a stuck level resent every 500 ms for 5.5 minutes). Switch Pro is
+/// not affected either way — `hid-nintendo` re-sends rumble continuously, and a physical Pro's
+/// HD-rumble decays faster than this window regardless.
+///
+/// Do not "fix" this by widening or disabling the window without evidence about which failure real
+/// titles actually hit; the hatch below exists for exactly that experiment.
 const RUMBLE_IDLE_TIMEOUT: Duration = Duration::from_millis(2500);
 
 /// The abandoned-rumble force-off window, env-hatched: `PUNKTFUNK_RUMBLE_IDLE_MS` overrides
@@ -338,10 +359,17 @@ impl<B: PadProto> UhidManager<B> {
             for h in fb.hidout {
                 // Skip rich feedback that repeats the last-forwarded value (a game's output report
                 // re-sends unchanged lightbar/LED/trigger state alongside every rumble update).
-                if self.hidout_dedup[i].should_forward(&h) {
+                if self.hidout_dedup[i].should_forward(&h, now) {
                     hidout(h);
                 }
             }
+            // Re-assert the latched rich state on a slow cadence. Deduping a plane that rides
+            // unreliable datagrams means a dropped update is never re-derived from the game — it
+            // keeps sending the same value and the dedup eats every copy — so without this one
+            // lost datagram leaves the pad on the previous weapon's trigger effect indefinitely.
+            for h in self.hidout_dedup[i].renewals(i as u8, now) {
+                hidout(h);
+            }
         }
     }
 

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

@@ -819,46 +819,77 @@ impl DriverAttach {
 
     /// One-shot WARN with everything the host can find out about WHY the driver isn't attached:
     /// driver-store presence, the devnode's PnP status/problem code, and where to look next.
+    ///
+    /// Runs on its own thread and returns immediately. The caller is the session's pad service
+    /// thread — the one feeding input and rumble — and everything below is slow: the driver-store
+    /// check waits up to [`INVENTORY_WAIT`] for a `pnputil` enumeration that can take tens of
+    /// seconds, and the devnode lookup is a synchronous PnP call. Blocking there stalled input for
+    /// up to two seconds *per unattached pad* (the wait is a deadline, not a one-off: while the
+    /// enumeration is still outstanding every pad pays it again), at exactly the moment a session
+    /// is already going wrong. Diagnostics must never be able to hurt the thing they diagnose.
+    ///
+    /// Off the hot path the wait also stops being a compromise — it can afford to be patient and
+    /// report what it actually found rather than "still enumerating".
     fn diagnose(&self) {
-        let store = match driver_store_has(self.inf) {
-            Some(true) => "driver package present in the driver store",
-            Some(false) => {
-                "driver package NOT in the driver store — run: punktfunk-host.exe driver install --gamepad"
-            }
-            None => "driver store could not be queried (pnputil failed or still enumerating)",
-        };
-        let devnode = match &self.instance_id {
-            Some(id) => devnode_status_line(id),
-            None => {
-                "no per-session devnode (SwDeviceCreate failed earlier — see the warning above)"
-                    .to_string()
-            }
-        };
-        tracing::warn!(
-            driver = self.driver,
-            shm = %self.shm_name,
-            grace_secs = ATTACH_GRACE.as_secs(),
-            store,
-            devnode = %devnode,
-            driver_log = self.driver_log,
-            "gamepad driver has not attached to the shared section — the virtual pad exists but no \
-             driver is serving it (games will not see it); an old (pre-sealed-channel) driver also \
-             reads as not-attached: update with punktfunk-host.exe driver install --gamepad \
-             (driver_log is only written by debug driver builds, or with the PFXUSB_DEBUG_LOG / \
-             PFGAMEPAD_DEBUG_LOG / PFMOUSE_DEBUG_LOG system env var set + the device restarted)"
-        );
+        let (driver, inf, driver_log) = (self.driver, self.inf, self.driver_log);
+        let shm_name = self.shm_name.clone();
+        let instance_id = self.instance_id.clone();
+        std::thread::Builder::new()
+            .name("pf-driver-diagnose".into())
+            .spawn(move || diagnose_blocking(driver, inf, driver_log, &shm_name, instance_id))
+            .ok();
     }
 }
 
-/// How long [`driver_store_inventory`] lets the caller wait for the background pnputil query
-/// before reporting without it — [`observe`] runs on the pad service thread, which must keep
-/// draining pad slots even when the driver store is wedged.
-const INVENTORY_WAIT: Duration = Duration::from_secs(2);
+/// The body of [`DriverAttach::diagnose`], on its own thread. Split out rather than inlined into
+/// the closure so the blocking calls stay visible as blocking.
+fn diagnose_blocking(
+    driver: &'static str,
+    inf: &'static str,
+    driver_log: &'static str,
+    shm_name: &str,
+    instance_id: Option<String>,
+) {
+    let store = match driver_store_has(inf) {
+        Some(true) => "driver package present in the driver store",
+        Some(false) => {
+            "driver package NOT in the driver store — run: punktfunk-host.exe driver install --gamepad"
+        }
+        None => "driver store could not be queried (pnputil failed or still enumerating)",
+    };
+    let devnode = match &instance_id {
+        Some(id) => devnode_status_line(id),
+        None => "no per-session devnode (SwDeviceCreate failed earlier — see the warning above)"
+            .to_string(),
+    };
+    tracing::warn!(
+        driver,
+        shm = %shm_name,
+        grace_secs = ATTACH_GRACE.as_secs(),
+        store,
+        devnode = %devnode,
+        driver_log,
+        "gamepad driver has not attached to the shared section — the virtual pad exists but no \
+         driver is serving it (games will not see it); an old (pre-sealed-channel) driver also \
+         reads as not-attached: update with punktfunk-host.exe driver install --gamepad \
+         (driver_log is only written by debug driver builds, or with the PFXUSB_DEBUG_LOG / \
+         PFGAMEPAD_DEBUG_LOG / PFMOUSE_DEBUG_LOG system env var set + the device restarted)"
+    );
+}
+
+/// How long [`driver_store_inventory`] waits for the background pnputil query before reporting
+/// without it. Only [`diagnose_blocking`] waits, and that has a thread to itself, so this is
+/// generous: pnputil routinely takes longer than a couple of seconds on a busy driver store, and
+/// the old two-second budget — chosen to limit the damage while this ran on the pad service thread
+/// — meant the diagnosis usually gave up and printed "still enumerating", which is the one answer
+/// that helps nobody. Nothing waits on this thread, so patience costs only a late log line.
+const INVENTORY_WAIT: Duration = Duration::from_secs(30);
 
 /// Driver-store inventory (`pnputil /enum-drivers`), lower-cased, fetched once per process — only
 /// consulted on the failure path, so the subprocess cost never hits a healthy session. The query
 /// runs on its OWN thread: pnputil can block for tens of seconds on a busy/wedged driver store,
-/// and the caller is the pad service thread. `None` = not available yet (query still running) or
+/// and this keeps one wedged query from being re-run per pad. `None` = not available yet (query
+/// still running past [`INVENTORY_WAIT`]) or
 /// failed; a query that outlives [`INVENTORY_WAIT`] still lands in the cache for later reports.
 fn driver_store_inventory() -> Option<&'static str> {
     static INV: OnceLock<String> = OnceLock::new();

crates/pf-inject/src/lib.rs

@@ -457,6 +457,11 @@ pub mod triton_proto;
 #[cfg(target_os = "linux")]
 #[path = "inject/linux/triton_usbip.rs"]
 pub mod triton_usbip;
+/// Linux: the `/dev/uhid` event ABI shared by every UHID gamepad backend — the constants each
+/// used to transcribe for itself, plus the field accessors that read a payload's real length.
+#[cfg(target_os = "linux")]
+#[path = "inject/linux/uhid_abi.rs"]
+pub mod uhid_abi;
 /// The generic stateful virtual-pad manager ([`uhid_manager::UhidManager`]) — event routing, frame
 /// merge, heartbeat, and feedback pump shared by the five UHID/UMDF backends; each supplies only
 /// its per-controller protocol via [`uhid_manager::PadProto`] (G12).

crates/pf-presenter/src/run.rs

@@ -466,6 +466,13 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
     #[cfg(windows)]
     crate::win32::set_app_user_model_id();
     sdl3::hint::set("SDL_JOYSTICK_THREAD", "1");
+    // Hold SDL's Valve HIDAPI drivers off BEFORE SDL_Init: the Deck driver clears the pad's
+    // digital mappings at *enumeration*, which is part of bringing the gamepad subsystem up, so a
+    // hint set after `sdl.gamepad()` — where this used to live, inside GamepadService::pumped —
+    // only detached a driver that had already killed the built-in trackpad-mouse system-wide. The
+    // symptom was the Deck losing its trackpad cursor at the start of every session until the
+    // firmware watchdog restored lizard mode. They are still enabled for an attached session.
+    pf_client_core::gamepad::preinit_disable_valve_hidapi();
     // A touchscreen (the Deck's glass) is forwarded as REAL touch passthrough below — so
     // suppress SDL's default synthesis of mouse events from touch. Left on, every touch
     // ALSO warps a synthetic mouse to the touch point, which under the stream's relative
@@ -1895,6 +1902,13 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
         }
     };
 
+    // Every exit from the loop above converges here, which is why the gamepad teardown belongs
+    // here and not on the individual `break`s. `gamepad.detach()` only queues the detach; the
+    // close — flush, host-side GamepadRemove, and the explicit rumble-stop backstop — runs when
+    // the pump drains it. Single mode broke out of the loop immediately after detaching and
+    // Event::Quit never detached at all, so both left forwarded pads unflushed and, if the game
+    // was rumbling at the time, still buzzing.
+    pump.shutdown();
     // Join the pump BEFORE the device-wide idle: its decode submissions on the shared
     // device would race vkDeviceWaitIdle otherwise.
     if let Some(st) = stream.take() {

crates/pf-vdisplay/src/vdisplay/windows/manager.rs

@@ -1764,6 +1764,11 @@ impl VirtualDisplayManager {
             if let Some(saved) = inner.group.ccd_saved.take() {
                 restore_displays_ccd(&saved);
             }
+            // Drop the isolate's crash-recovery marker even when there was no snapshot to restore
+            // (a failed `isolate_displays_ccd` leaves `ccd_saved` None, and `restore_displays_ccd`
+            // — which clears it itself — then never runs). The group is gone either way, so no
+            // future host start owes this desk a force-EXTEND.
+            pf_win_display::win_display::isolate_journal::clear();
             // EXPERIMENTAL `ddc_power_off` wake. OUTSIDE the `ccd_saved` gate, for the same reason
             // `pnp_disabled` is above it: the panels were commanded dark BEFORE the isolate, and
             // the isolate can return `None` (its `query_active_config` failed). Nested inside that

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

@@ -1215,6 +1215,186 @@ pub fn target_inventory() -> Vec<TargetInventory> {
     out
 }
 
+/// Crash-recovery journal for the EXCLUSIVE isolate — the marker that lets a *fresh* host undo what
+/// a *dead* one did.
+///
+/// [`isolate_displays_ccd`] deactivates the operator's physical displays and hands the pre-isolate
+/// topology back to its caller, which restores it at teardown ([`restore_displays_ccd`]). That
+/// snapshot lives in **process memory only**, so a host that crashes, is killed, or is stopped
+/// mid-session never restores it. Windows does not restore it either — the isolated topology is
+/// deliberately never saved to the CCD database, precisely so teardown can put the user's layout
+/// back. The result was a field-reported dead end: the physical screen stays dark, no timeout ever
+/// fires, and nothing in the product puts it back (the operator's only recourse was `DisplaySwitch`
+/// or a reboot).
+///
+/// Same shape as [`monitor_devnode`](crate::monitor_devnode)'s PnP journal: write a marker while the
+/// isolate is live, clear it on a clean restore, and re-light the desk at host startup if a marker
+/// survived.
+///
+/// **Why the EXTEND preset rather than replaying the saved CCD blob.** That blob pins target ids
+/// *including the virtual display's*, and the crashed host's monitors die with it (startup reaps the
+/// orphans), so a replay would mostly fail `ERROR_BAD_CONFIGURATION` and land in the very
+/// force-EXTEND backstop [`restore_displays_ccd`] already keeps for that case. EXTEND re-activates
+/// every connected display from the OS's own database, needs no struct serialization, and stays
+/// correct across a reboot — where saved target ids would be stale anyway.
+pub mod isolate_journal {
+    use std::sync::Mutex;
+
+    /// What we last wrote, so the exclusive re-assert watchdog's repeat isolates don't rewrite the
+    /// file every couple of seconds. `None` = "no marker known to be on disk".
+    static LAST: Mutex<Option<Vec<u32>>> = Mutex::new(None);
+
+    fn path() -> std::path::PathBuf {
+        pf_paths::config_dir().join("display-isolate-active.json")
+    }
+
+    /// Record that `deactivated` physical target(s) are switched off for a live exclusive isolate.
+    /// Best-effort: a journal we cannot write costs crash recovery, not the session.
+    pub fn mark(deactivated: &[u32]) {
+        if deactivated.is_empty() {
+            return; // nothing was deactivated ⇒ nothing for a later host to put back
+        }
+        let mut last = LAST.lock().unwrap_or_else(|e| e.into_inner());
+        if last.as_deref() == Some(deactivated) {
+            return;
+        }
+        let p = path();
+        if let Some(dir) = p.parent() {
+            let _ = pf_paths::create_private_dir(dir);
+        }
+        match std::fs::write(
+            &p,
+            serde_json::to_vec_pretty(deactivated).unwrap_or_default(),
+        ) {
+            Ok(()) => *last = Some(deactivated.to_vec()),
+            Err(e) => tracing::warn!(
+                error = %e,
+                "display isolate: could not write the crash-recovery journal — if this host dies \
+                 mid-session the deactivated panels will stay dark"
+            ),
+        }
+    }
+
+    /// The isolate is over (restored, or there was nothing to restore) — drop the marker.
+    /// Idempotent; safe to call when no marker exists.
+    pub fn clear() {
+        let mut last = LAST.lock().unwrap_or_else(|e| e.into_inner());
+        let _ = std::fs::remove_file(path());
+        *last = None;
+    }
+
+    /// Host-startup crash recovery: if a previous host exited with an exclusive isolate live, its
+    /// physical displays are still deactivated. Re-light them with the EXTEND preset.
+    ///
+    /// Call once, early in `serve`, **before** any session touches the topology. Gated on the marker
+    /// rather than on "is anything active", so a legitimately headless host is never forced awake.
+    pub fn startup_recover() {
+        let Some(targets) = pending() else {
+            return;
+        };
+        tracing::warn!(
+            deactivated = ?targets,
+            "display isolate: a previous host exited with the operator's display(s) deactivated for \
+             an EXCLUSIVE session and never restored them — forcing the EXTEND preset so the desk is \
+             not left dark"
+        );
+        super::force_extend_topology();
+        clear();
+    }
+
+    /// The marker a previous host left behind, if any (its deactivated target ids) — the *decision*
+    /// half of [`startup_recover`], split out so the recovery rule is testable without driving a
+    /// real `SetDisplayConfig` against the machine running the test.
+    pub fn pending() -> Option<Vec<u32>> {
+        let bytes = std::fs::read(path()).ok()?;
+        Some(serde_json::from_slice(&bytes).unwrap_or_default())
+    }
+
+    #[cfg(test)]
+    mod tests {
+        use super::*;
+
+        /// `PUNKTFUNK_CONFIG_DIR` (which `path()` resolves through) and the `LAST` cache are both
+        /// process-global, so these cases must not interleave.
+        static ENV: Mutex<()> = Mutex::new(());
+
+        /// Point the journal at a scratch dir for the duration of one case.
+        fn with_temp_dir(name: &str, f: impl FnOnce(&std::path::Path)) {
+            let _g = ENV.lock().unwrap_or_else(|e| e.into_inner());
+            let dir = std::env::temp_dir().join(format!("pf-isolate-journal-{name}"));
+            let _ = std::fs::remove_dir_all(&dir);
+            std::fs::create_dir_all(&dir).expect("scratch dir");
+            std::env::set_var("PUNKTFUNK_CONFIG_DIR", &dir);
+            clear(); // reset the LAST cache + any leftover marker from a previous run
+            f(&dir);
+            clear();
+            std::env::remove_var("PUNKTFUNK_CONFIG_DIR");
+            let _ = std::fs::remove_dir_all(&dir);
+        }
+
+        /// The crash path: a host marks what it switched off and dies. The next start must see the
+        /// marker (and which targets), which is what makes it force the desk back on.
+        #[test]
+        fn a_mark_survives_for_the_next_host_and_clear_retracts_it() {
+            with_temp_dir("roundtrip", |_| {
+                assert_eq!(pending(), None, "a clean box owes no recovery");
+                mark(&[101, 202]);
+                assert_eq!(
+                    pending(),
+                    Some(vec![101, 202]),
+                    "a crashed host's marker must be readable by the next start"
+                );
+                clear();
+                assert_eq!(pending(), None, "a clean teardown retracts the marker");
+            });
+        }
+
+        /// An isolate that deactivated nothing (single-display box: the virtual output is already
+        /// the only head) owes the next start no force-EXTEND — marking there would re-arrange a
+        /// desk we never touched.
+        #[test]
+        fn deactivating_nothing_writes_no_marker() {
+            with_temp_dir("empty", |_| {
+                mark(&[]);
+                assert_eq!(pending(), None);
+            });
+        }
+
+        /// The re-assert watchdog re-isolates every couple of seconds while something fights it;
+        /// that must not mean a disk write per cycle.
+        #[test]
+        fn repeating_the_same_mark_does_not_rewrite_the_file() {
+            with_temp_dir("cached", |dir| {
+                let file = dir.join("display-isolate-active.json");
+                mark(&[7]);
+                // Overwrite behind the journal's back rather than comparing mtimes — a filesystem
+                // whose timestamp resolution is coarser than two back-to-back writes would let an
+                // mtime assertion pass without proving anything.
+                std::fs::write(&file, b"SENTINEL").unwrap();
+                mark(&[7]);
+                assert_eq!(
+                    std::fs::read(&file).unwrap(),
+                    b"SENTINEL",
+                    "an unchanged mark must not rewrite the journal"
+                );
+                // A CHANGED set still lands — the group grew/shrank and recovery must follow it.
+                mark(&[7, 8]);
+                assert_eq!(pending(), Some(vec![7, 8]));
+            });
+        }
+
+        /// A corrupt/truncated journal must still trigger recovery: the FILE's existence is the
+        /// signal ("a host left displays off"), its contents are only diagnostics.
+        #[test]
+        fn an_unparseable_marker_still_asks_for_recovery() {
+            with_temp_dir("corrupt", |dir| {
+                std::fs::write(dir.join("display-isolate-active.json"), b"{ not json").unwrap();
+                assert_eq!(pending(), Some(Vec::new()));
+            });
+        }
+    }
+}
+
 /// Robust display isolation via the CCD API. The naive GDI approach (EnumDisplayDevices +
 /// ChangeDisplaySettings) MISSES displays on a hybrid box — an iGPU-attached physical monitor isn't
 /// flagged `ATTACHED_TO_DESKTOP` in the GDI enum, so it's never detached and the secure desktop /
@@ -1246,6 +1426,18 @@ pub fn isolate_displays_ccd(keep_target_ids: &[u32]) -> Option<SavedConfig> {
         return Some(saved);
     }
 
+    // Journal what we are about to switch off BEFORE the first apply, not after a verified one: the
+    // window this exists to cover includes dying mid-apply. `saved.0` is the ACTIVE path set
+    // (QDC_ONLY_ACTIVE_PATHS), so everything in it outside the keep set is exactly what teardown
+    // owes the operator back. See `isolate_journal`.
+    let doomed: Vec<u32> = saved
+        .0
+        .iter()
+        .map(|p| p.targetInfo.id)
+        .filter(|id| !keep_target_ids.contains(id))
+        .collect();
+    isolate_journal::mark(&doomed);
+
     // Deactivate every non-keep display, then VERIFY and RETRY. A field-reported bug had a physical
     // monitor STAY ACTIVE in exclusive mode, so we don't trust a single SetDisplayConfig: re-query the
     // live topology each attempt and re-apply until ONLY the keep set is active. Secure-desktop
@@ -1769,6 +1961,15 @@ static DARK_SINKS_FUTILE: std::sync::Mutex<Vec<(u32, String)>> = std::sync::Mute
 /// removed), re-activating the displays we deactivated.
 // pub so vdisplay::pf_vdisplay can reuse this backend-neutral CCD restore helper.
 pub fn restore_displays_ccd(saved: &SavedConfig) {
+    restore_displays_ccd_inner(saved);
+    // Clear the crash-recovery marker only AFTER the restore (and its dark-desk backstop) has run,
+    // never before: a host that dies part-way through the restore must still leave the marker
+    // behind so the next start re-lights the desk. `_inner` has several early returns, which is
+    // why this wraps rather than trailing the body.
+    isolate_journal::clear();
+}
+
+fn restore_displays_ccd_inner(saved: &SavedConfig) {
     let (paths, modes) = saved;
     if paths.is_empty() {
         return;

crates/punktfunk-core/cbindgen.toml

@@ -56,6 +56,167 @@ exclude = ["MsghdrX", "recvmsg_x", "mmsghdr", "sendmmsg", "recvmmsg"]
 "FRAME_MS" = "PUNKTFUNK_AUDIO_FRAME_MS"
 "SAMPLE_RATE_HZ" = "PUNKTFUNK_AUDIO_SAMPLE_RATE_HZ"
 
+# R21: every remaining exported constant, prefixed. cbindgen emits a bare `#define` per
+# `pub const`, so without an entry here names as generic as MAX_PADS, TAG_LEN, ABI_VERSION and
+# INPUT_MAGIC land in the namespace of every C embedder that includes this header — and, as the
+# note above says, a clashing #define silently takes the last definition rather than failing to
+# compile. The table above had been doing this by hand for the handful someone noticed; this is
+# the rest of them, so the stated rule finally holds for the whole surface.
+#
+# NOT covered, deliberately: associated constants (`ColorInfo_CP_BT709`, `ClockResync_ROUNDS`,
+# `ResyncGuard_MAX_REJECTED_STREAK`). cbindgen already qualifies those with their type name,
+# which is the very property whose absence makes a bare `MAX_PADS` dangerous — they are
+# namespaced, just not by us.
+"ABI_VERSION" = "PUNKTFUNK_ABI_VERSION"
+"APP_EXITED_CLOSE_CODE" = "PUNKTFUNK_APP_EXITED_CLOSE_CODE"
+"BTN_MISC1" = "PUNKTFUNK_BTN_MISC1"
+"BTN_PADDLE1" = "PUNKTFUNK_BTN_PADDLE1"
+"BTN_PADDLE2" = "PUNKTFUNK_BTN_PADDLE2"
+"BTN_PADDLE3" = "PUNKTFUNK_BTN_PADDLE3"
+"BTN_PADDLE4" = "PUNKTFUNK_BTN_PADDLE4"
+"CHROMA_IDC_420" = "PUNKTFUNK_CHROMA_IDC_420"
+"CHROMA_IDC_444" = "PUNKTFUNK_CHROMA_IDC_444"
+"CIPHER_AES_128_GCM" = "PUNKTFUNK_CIPHER_AES_128_GCM"
+"CIPHER_CHACHA20_POLY1305" = "PUNKTFUNK_CIPHER_CHACHA20_POLY1305"
+"CLIENT_CAP_AUDIO_RED" = "PUNKTFUNK_CLIENT_CAP_AUDIO_RED"
+"CLIENT_CAP_CURSOR" = "PUNKTFUNK_CLIENT_CAP_CURSOR"
+"CLIENT_CAP_PHASE_LOCK" = "PUNKTFUNK_CLIENT_CAP_PHASE_LOCK"
+"CLIP_CANCELLED_CODE" = "PUNKTFUNK_CLIP_CANCELLED_CODE"
+"CLIP_CHUNK" = "PUNKTFUNK_CLIP_CHUNK"
+"CLIP_FETCH_CAP" = "PUNKTFUNK_CLIP_FETCH_CAP"
+"CLIP_FETCH_DENIED" = "PUNKTFUNK_CLIP_FETCH_DENIED"
+"CLIP_FETCH_OK" = "PUNKTFUNK_CLIP_FETCH_OK"
+"CLIP_FETCH_STALE" = "PUNKTFUNK_CLIP_FETCH_STALE"
+"CLIP_FETCH_UNAVAILABLE" = "PUNKTFUNK_CLIP_FETCH_UNAVAILABLE"
+"CLIP_FILE_INDEX_NONE" = "PUNKTFUNK_CLIP_FILE_INDEX_NONE"
+"CLIP_FLAG_FILES" = "PUNKTFUNK_CLIP_FLAG_FILES"
+"CLIP_MAX_KINDS" = "PUNKTFUNK_CLIP_MAX_KINDS"
+"CLIP_MAX_MIME" = "PUNKTFUNK_CLIP_MAX_MIME"
+"CLIP_POLICY_FILES" = "PUNKTFUNK_CLIP_POLICY_FILES"
+"CLIP_POLICY_TEXT" = "PUNKTFUNK_CLIP_POLICY_TEXT"
+"CLIP_REASON_BACKEND_UNAVAILABLE" = "PUNKTFUNK_CLIP_REASON_BACKEND_UNAVAILABLE"
+"CLIP_REASON_NO_FILES" = "PUNKTFUNK_CLIP_REASON_NO_FILES"
+"CLIP_REASON_OK" = "PUNKTFUNK_CLIP_REASON_OK"
+"CLIP_REASON_POLICY_DISABLED" = "PUNKTFUNK_CLIP_REASON_POLICY_DISABLED"
+"CLIP_REASON_TAKEN_OVER" = "PUNKTFUNK_CLIP_REASON_TAKEN_OVER"
+"CLIP_STREAM_KIND_FETCH" = "PUNKTFUNK_CLIP_STREAM_KIND_FETCH"
+"ClockResync_ROUNDS" = "PUNKTFUNK_ClockResync_ROUNDS"
+"CODEC_AV1" = "PUNKTFUNK_CODEC_AV1"
+"CODEC_H264" = "PUNKTFUNK_CODEC_H264"
+"CODEC_HEVC" = "PUNKTFUNK_CODEC_HEVC"
+"CODEC_PYROWAVE" = "PUNKTFUNK_CODEC_PYROWAVE"
+"ColorInfo_CP_BT2020" = "PUNKTFUNK_ColorInfo_CP_BT2020"
+"ColorInfo_CP_BT709" = "PUNKTFUNK_ColorInfo_CP_BT709"
+"ColorInfo_MC_BT2020_NCL" = "PUNKTFUNK_ColorInfo_MC_BT2020_NCL"
+"ColorInfo_MC_BT709" = "PUNKTFUNK_ColorInfo_MC_BT709"
+"ColorInfo_TRC_BT709" = "PUNKTFUNK_ColorInfo_TRC_BT709"
+"ColorInfo_TRC_HLG" = "PUNKTFUNK_ColorInfo_TRC_HLG"
+"ColorInfo_TRC_PQ" = "PUNKTFUNK_ColorInfo_TRC_PQ"
+"CURSOR_RELATIVE_HINT" = "PUNKTFUNK_CURSOR_RELATIVE_HINT"
+"CURSOR_SHAPE_MAX_SIDE" = "PUNKTFUNK_CURSOR_SHAPE_MAX_SIDE"
+"CURSOR_STATE_MAGIC" = "PUNKTFUNK_CURSOR_STATE_MAGIC"
+"CURSOR_VISIBLE" = "PUNKTFUNK_CURSOR_VISIBLE"
+"FLAG_EOF" = "PUNKTFUNK_FLAG_EOF"
+"FLAG_PIC" = "PUNKTFUNK_FLAG_PIC"
+"FLAG_PROBE" = "PUNKTFUNK_FLAG_PROBE"
+"FLAG_SOF" = "PUNKTFUNK_FLAG_SOF"
+"HDR_META_BODY_LEN" = "PUNKTFUNK_HDR_META_BODY_LEN"
+"HDR_META_MAGIC" = "PUNKTFUNK_HDR_META_MAGIC"
+"HELLO_LAUNCH_MAX" = "PUNKTFUNK_HELLO_LAUNCH_MAX"
+"HELLO_NAME_MAX" = "PUNKTFUNK_HELLO_NAME_MAX"
+"HID_RAW_FEATURE" = "PUNKTFUNK_HID_RAW_FEATURE"
+"HID_RAW_OUTPUT" = "PUNKTFUNK_HID_RAW_OUTPUT"
+"HID_REPORT_MAX" = "PUNKTFUNK_HID_REPORT_MAX"
+"HIDOUT_MAGIC" = "PUNKTFUNK_HIDOUT_MAGIC"
+"HOST_CAP_AUDIO_RED" = "PUNKTFUNK_HOST_CAP_AUDIO_RED"
+"HOST_CAP_CLIPBOARD" = "PUNKTFUNK_HOST_CAP_CLIPBOARD"
+"HOST_CAP_CURSOR" = "PUNKTFUNK_HOST_CAP_CURSOR"
+"HOST_CAP_GAMEPAD_STATE" = "PUNKTFUNK_HOST_CAP_GAMEPAD_STATE"
+"HOST_CAP_PEN" = "PUNKTFUNK_HOST_CAP_PEN"
+"HOST_CAP_TEXT_INPUT" = "PUNKTFUNK_HOST_CAP_TEXT_INPUT"
+"HOST_TIMING_MAGIC" = "PUNKTFUNK_HOST_TIMING_MAGIC"
+"INBOUND_REQ_FLAG" = "PUNKTFUNK_INBOUND_REQ_FLAG"
+"INPUT_MAGIC" = "PUNKTFUNK_INPUT_MAGIC"
+"INPUT_WIRE_LEN" = "PUNKTFUNK_INPUT_WIRE_LEN"
+"LEGACY_STALE_MS" = "PUNKTFUNK_LEGACY_STALE_MS"
+"MAX_DATAGRAM_BYTES" = "PUNKTFUNK_MAX_DATAGRAM_BYTES"
+"MAX_PADS" = "PUNKTFUNK_MAX_PADS"
+"MAX_SCALE" = "PUNKTFUNK_MAX_SCALE"
+"MIC_MAGIC" = "PUNKTFUNK_MIC_MAGIC"
+"MIN_SCALE" = "PUNKTFUNK_MIN_SCALE"
+"MIN_SHARD_PAYLOAD" = "PUNKTFUNK_MIN_SHARD_PAYLOAD"
+"MIN_STREAM_BLOCK_SHARDS" = "PUNKTFUNK_MIN_STREAM_BLOCK_SHARDS"
+"MSG_BITRATE_CHANGED" = "PUNKTFUNK_MSG_BITRATE_CHANGED"
+"MSG_CLIP_CONTROL" = "PUNKTFUNK_MSG_CLIP_CONTROL"
+"MSG_CLIP_FETCH" = "PUNKTFUNK_MSG_CLIP_FETCH"
+"MSG_CLIP_FETCH_HDR" = "PUNKTFUNK_MSG_CLIP_FETCH_HDR"
+"MSG_CLIP_OFFER" = "PUNKTFUNK_MSG_CLIP_OFFER"
+"MSG_CLIP_STATE" = "PUNKTFUNK_MSG_CLIP_STATE"
+"MSG_CLOCK_ECHO" = "PUNKTFUNK_MSG_CLOCK_ECHO"
+"MSG_CLOCK_PROBE" = "PUNKTFUNK_MSG_CLOCK_PROBE"
+"MSG_CURSOR_RENDER" = "PUNKTFUNK_MSG_CURSOR_RENDER"
+"MSG_CURSOR_SHAPE" = "PUNKTFUNK_MSG_CURSOR_SHAPE"
+"MSG_LOSS_REPORT" = "PUNKTFUNK_MSG_LOSS_REPORT"
+"MSG_PAIR_CHALLENGE" = "PUNKTFUNK_MSG_PAIR_CHALLENGE"
+"MSG_PAIR_PROOF" = "PUNKTFUNK_MSG_PAIR_PROOF"
+"MSG_PAIR_REQUEST" = "PUNKTFUNK_MSG_PAIR_REQUEST"
+"MSG_PAIR_RESULT" = "PUNKTFUNK_MSG_PAIR_RESULT"
+"MSG_PHASE_REPORT" = "PUNKTFUNK_MSG_PHASE_REPORT"
+"MSG_PROBE_REQUEST" = "PUNKTFUNK_MSG_PROBE_REQUEST"
+"MSG_PROBE_RESULT" = "PUNKTFUNK_MSG_PROBE_RESULT"
+"MSG_RECONFIGURE" = "PUNKTFUNK_MSG_RECONFIGURE"
+"MSG_RECONFIGURED" = "PUNKTFUNK_MSG_RECONFIGURED"
+"MSG_REQUEST_KEYFRAME" = "PUNKTFUNK_MSG_REQUEST_KEYFRAME"
+"MSG_RFI_REQUEST" = "PUNKTFUNK_MSG_RFI_REQUEST"
+"MSG_SET_BITRATE" = "PUNKTFUNK_MSG_SET_BITRATE"
+"MSG_SHARD_PAYLOAD_ACK" = "PUNKTFUNK_MSG_SHARD_PAYLOAD_ACK"
+"MSG_SHARD_PAYLOAD_CHANGED" = "PUNKTFUNK_MSG_SHARD_PAYLOAD_CHANGED"
+"NO_OUTPUT_KEYFRAME_STREAK" = "PUNKTFUNK_NO_OUTPUT_KEYFRAME_STREAK"
+"PAIR_APPROVAL_TIMEOUT_CLOSE_CODE" = "PUNKTFUNK_PAIR_APPROVAL_TIMEOUT_CLOSE_CODE"
+"PAIR_BOUND_OTHER_CLOSE_CODE" = "PUNKTFUNK_PAIR_BOUND_OTHER_CLOSE_CODE"
+"PAIR_DENIED_CLOSE_CODE" = "PUNKTFUNK_PAIR_DENIED_CLOSE_CODE"
+"PAIR_NO_IDENTITY_CLOSE_CODE" = "PUNKTFUNK_PAIR_NO_IDENTITY_CLOSE_CODE"
+"PAIR_NOT_ARMED_CLOSE_CODE" = "PUNKTFUNK_PAIR_NOT_ARMED_CLOSE_CODE"
+"PAIR_RATE_LIMITED_CLOSE_CODE" = "PUNKTFUNK_PAIR_RATE_LIMITED_CLOSE_CODE"
+"PAIR_SUPERSEDED_CLOSE_CODE" = "PUNKTFUNK_PAIR_SUPERSEDED_CLOSE_CODE"
+"PEN_ANGLE_UNKNOWN" = "PUNKTFUNK_PEN_ANGLE_UNKNOWN"
+"PEN_BARREL1" = "PUNKTFUNK_PEN_BARREL1"
+"PEN_BARREL2" = "PUNKTFUNK_PEN_BARREL2"
+"PEN_BATCH_MAX" = "PUNKTFUNK_PEN_BATCH_MAX"
+"PEN_DISTANCE_UNKNOWN" = "PUNKTFUNK_PEN_DISTANCE_UNKNOWN"
+"PEN_IN_RANGE" = "PUNKTFUNK_PEN_IN_RANGE"
+"PEN_PREDICTED" = "PUNKTFUNK_PEN_PREDICTED"
+"PEN_SAMPLE_WIRE_LEN" = "PUNKTFUNK_PEN_SAMPLE_WIRE_LEN"
+"PEN_TILT_UNKNOWN" = "PUNKTFUNK_PEN_TILT_UNKNOWN"
+"PEN_TOUCH_TIMEOUT_MS" = "PUNKTFUNK_PEN_TOUCH_TIMEOUT_MS"
+"PEN_TOUCHING" = "PUNKTFUNK_PEN_TOUCHING"
+"PRESETS" = "PUNKTFUNK_PRESETS"
+"QUIT_CLOSE_CODE" = "PUNKTFUNK_QUIT_CLOSE_CODE"
+"REANCHOR_MARKS_TO_LIFT" = "PUNKTFUNK_REANCHOR_MARKS_TO_LIFT"
+"REJECT_BUSY_CLOSE_CODE" = "PUNKTFUNK_REJECT_BUSY_CLOSE_CODE"
+"ResyncGuard_MAX_REJECTED_STREAK" = "PUNKTFUNK_ResyncGuard_MAX_REJECTED_STREAK"
+"RFI_MAX_RANGE" = "PUNKTFUNK_RFI_MAX_RANGE"
+"RICH_INPUT_MAGIC" = "PUNKTFUNK_RICH_INPUT_MAGIC"
+"RUMBLE_V1_LEN" = "PUNKTFUNK_RUMBLE_V1_LEN"
+"RUMBLE_V2_LEN" = "PUNKTFUNK_RUMBLE_V2_LEN"
+"SETUP_FAILED_CLOSE_CODE" = "PUNKTFUNK_SETUP_FAILED_CLOSE_CODE"
+"TAG_LEN" = "PUNKTFUNK_TAG_LEN"
+"TRIGGER_EFFECT_MAX" = "PUNKTFUNK_TRIGGER_EFFECT_MAX"
+"USER_FLAG_CHUNK_ALIGNED" = "PUNKTFUNK_USER_FLAG_CHUNK_ALIGNED"
+"USER_FLAG_RECOVERY_ANCHOR" = "PUNKTFUNK_USER_FLAG_RECOVERY_ANCHOR"
+"USER_FLAG_RECOVERY_POINT" = "PUNKTFUNK_USER_FLAG_RECOVERY_POINT"
+"USER_FLAG_SLICE_STREAM" = "PUNKTFUNK_USER_FLAG_SLICE_STREAM"
+"VIDEO_CAP_10BIT" = "PUNKTFUNK_VIDEO_CAP_10BIT"
+"VIDEO_CAP_444" = "PUNKTFUNK_VIDEO_CAP_444"
+"VIDEO_CAP_CHACHA20" = "PUNKTFUNK_VIDEO_CAP_CHACHA20"
+"VIDEO_CAP_HDR" = "PUNKTFUNK_VIDEO_CAP_HDR"
+"VIDEO_CAP_HOST_TIMING" = "PUNKTFUNK_VIDEO_CAP_HOST_TIMING"
+"VIDEO_CAP_MULTI_SLICE" = "PUNKTFUNK_VIDEO_CAP_MULTI_SLICE"
+"VIDEO_CAP_PROBE_SEQ" = "PUNKTFUNK_VIDEO_CAP_PROBE_SEQ"
+"VIDEO_CAP_STREAMED_AU" = "PUNKTFUNK_VIDEO_CAP_STREAMED_AU"
+"WIRE_VERSION" = "PUNKTFUNK_WIRE_VERSION"
+"WIRE_VERSION_CLOSE_CODE" = "PUNKTFUNK_WIRE_VERSION_CLOSE_CODE"
+
 # QualifiedScreamingSnakeCase already qualifies each variant with the enum name
 # (PunktfunkStatus::Ok -> PUNKTFUNK_STATUS_OK); do NOT also set prefix_with_name or it doubles.
 [enum]

crates/punktfunk-core/src/abi.rs

@@ -698,7 +698,10 @@ pub struct PunktfunkHidOutput {
     /// Trigger: number of valid bytes in `effect` (≤ `PUNKTFUNK_HID_EFFECT_MAX`).
     pub effect_len: u8,
     /// Trigger: the raw DualSense trigger parameter block (mode + params).
-    pub effect: [u8; 11],
+    /// Sized off [`PUNKTFUNK_HID_EFFECT_MAX`] rather than a second literal `11` — the constant is
+    /// exported precisely so embedders can size their own buffers against it, and it declaring one
+    /// number while the struct it describes hardcoded another was the whole hazard.
+    pub effect: [u8; PUNKTFUNK_HID_EFFECT_MAX as usize],
 }
 
 #[cfg(feature = "quic")]
@@ -2497,10 +2500,12 @@ pub unsafe extern "C" fn punktfunk_connection_next_rumble_cmd(
 /// Declare a physical actuator's quirks for wire pad `pad` — how a platform parameterizes the
 /// shared rumble policy engine instead of forking it (typically called at controller attach).
 /// `keepalive_ms`: re-emit an unchanged non-zero level at this cadence for actuators whose
-/// hardware output decays between wire renewals (Steam Deck ≈ 40, DualSense-over-BT raw HID
-/// ≈ 900); `0` = none. `min_pulse_ms`: floor for `backstop_ms` on non-zero commands. `flags`:
+/// hardware output decays between wire renewals (the Steam Deck's ≈ 40 is the one in-tree user);
+/// `0` = none. `min_pulse_ms`: floor for `backstop_ms` on non-zero commands — no in-tree caller
+/// sets it, it exists for embedders whose duration-taking API rejects short values. `flags`:
 /// [`PUNKTFUNK_RUMBLE_QUIRK_DEDUP_JITTER`]. All-zero (the initial state) describes a well-behaved
-/// actuator.
+/// actuator. See [`ActuatorQuirks`](crate::client::rumble::ActuatorQuirks) for why a renderer that
+/// dedupes its own writes (the Apple HID path) cannot use `keepalive_ms` and keeps its own.
 ///
 /// # Safety
 /// `c` is a valid connection handle. Callable from any thread.

crates/punktfunk-core/src/client/pump/datagram_task.rs

@@ -60,22 +60,28 @@ pub(super) async fn run(
             }
             Some(&crate::quic::RUMBLE_MAGIC) => {
                 if let Some(u) = crate::quic::decode_rumble_envelope(&d) {
+                    // A pad index the client cannot represent is dropped outright, before either
+                    // consumer sees it. It used to be waved through: the seq gate was skipped (its
+                    // per-pad cursor has no slot for it) and it was handed to the legacy queue,
+                    // while the policy engine silently discarded it on its own bounds check — so
+                    // "both consumers are fed" below was false for exactly these, and an embedder
+                    // draining the queue could be handed an index it would use to subscript its
+                    // own per-pad array. The host never emits one; this is malformed or hostile.
+                    let idx = u.pad as usize;
+                    if idx >= crate::input::MAX_PADS {
+                        continue;
+                    }
                     // Gate v2 envelopes on their per-pad seq; forward v1 (envelope: None) as-is.
                     let fresh = match u.envelope {
                         Some(env) => {
-                            let idx = u.pad as usize;
-                            if idx < crate::input::MAX_PADS {
-                                if crate::input::GamepadSnapshot::seq_newer(
-                                    env.seq,
-                                    rumble_last_seq[idx],
-                                ) {
-                                    rumble_last_seq[idx] = Some(env.seq);
-                                    true
-                                } else {
-                                    false // reordered/duplicate — drop, keep the newer state
-                                }
+                            if crate::input::GamepadSnapshot::seq_newer(
+                                env.seq,
+                                rumble_last_seq[idx],
+                            ) {
+                                rumble_last_seq[idx] = Some(env.seq);
+                                true
                             } else {
-                                true // out-of-range pad (host never sends these): no gate
+                                false // reordered/duplicate — drop, keep the newer state
                             }
                         }
                         None => true,

crates/punktfunk-core/src/client/rumble.rs

@@ -36,6 +36,22 @@ pub const LEGACY_STALE_MS: u64 = 1000;
 /// engine's staleness zero lands at 1 s; this is the hardware-level net under an engine stall).
 const BACKSTOP_LEGACY_MS: u32 = 2000;
 
+/// The longest lease the engine honours, whatever the envelope claims — the receiver-side mirror of
+/// the host's own `RUMBLE_TTL_CEIL_MS`.
+///
+/// No host built from this tree can exceed it (the `PUNKTFUNK_RUMBLE_TTL_MS` hatch is clamped to
+/// `[150, 5000]` before it reaches the wire), so this is defence in depth against a third-party or
+/// modified sender that stamps a long TTL and then wedges its renewal pump while the connection
+/// stays up. It matters on exactly the platforms that sustain a level for the whole lease: Apple,
+/// whose renderer deliberately keeps no staleness policy of its own, and a Deck slot, whose
+/// keepalive re-kicks the actuator until the lease ends. Duration-parameterized embedders (SDL,
+/// Android) already self-terminate at the clamped backstop.
+///
+/// Deliberately NOT `pub`: an embedder has no use for it, and every `pub` const in this crate is
+/// emitted into `include/punktfunk_core.h` as an UNPREFIXED `#define` — a collision hazard the
+/// header already has ~170 instances of, and one this has no reason to add to.
+const MAX_LEASE_MS: u16 = 5_000;
+
 /// One effective actuator command. `(0, 0)` means stop now. `backstop_ms` is a safety-net
 /// duration for platform APIs that take one (SDL rumble, Android one-shots): the engine emits
 /// explicit zeros at every policy stop, so the backstop only matters if the embedder thread itself
@@ -53,10 +69,25 @@ pub struct RumbleCommand {
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub struct ActuatorQuirks {
     /// Re-emit an unchanged non-zero level every this many ms — for actuators whose hardware
-    /// output decays between wire renewals (Steam Deck ≈ 40, macOS DualSense-over-HID BT ≈ 900).
-    /// `0` = no keepalive (the common case).
+    /// output decays between wire renewals. `0` = no keepalive (the common case).
+    ///
+    /// The one in-tree producer is the Steam Deck's ≈ 40 ms (`pf-client-core`'s slot open, paired
+    /// with `dedup_jitter`). The macOS DualSense-over-HID Bluetooth decay is NOT served by this
+    /// quirk, though it reads like the obvious second example: the Apple client keeps its own
+    /// ≈ 900 ms keepalive down in `RumbleRenderer` (`RumbleTuning.hidKeepaliveSeconds`) because
+    /// the re-emit has to happen BELOW the command layer. An engine keepalive arrives as a
+    /// command carrying the same levels, and that renderer skips a HID write whose levels are
+    /// unchanged — so the re-emit would be swallowed by the very dedupe it exists to defeat
+    /// (`dedup_jitter` is the Deck's answer to the same problem one layer up).
     pub keepalive_ms: u16,
-    /// Floor for `backstop_ms` on non-zero commands (Android's `createOneShot` throws on 0).
+    /// Floor for `backstop_ms` on non-zero commands.
+    ///
+    /// **No in-tree producer sets this non-zero** — it is reachable only through the C ABI
+    /// (`punktfunk_connection_set_rumble_quirks`), for embedders whose duration-taking API
+    /// rejects short values. The case it was written for is handled elsewhere: Android's
+    /// `createOneShot` does throw on a non-positive duration, but the Kotlin renderer floors the
+    /// duration itself at the call, and that path never declares quirks at all. Kept because it
+    /// is exported ABI, and because a floor belongs here rather than re-invented per embedder.
     pub min_pulse_ms: u16,
     /// Alternate the low motor's LSB on keepalive re-emits (imperceptible) so an SDL-class layer
     /// that no-ops identical values still writes the device — the Deck's dedupe-defeat.
@@ -75,8 +106,11 @@ struct PadState {
     /// A wire update landed since the last emit (level change OR renewal — renewals re-emit).
     dirty: bool,
     next_keepalive: Option<Instant>,
-    /// Current jitter phase (see [`ActuatorQuirks::dedup_jitter`]).
-    jitter: bool,
+    /// The exact value last handed to an embedder. `(0, 0)` ⇔ the engine believes this actuator is
+    /// silent. It replaces a free-running jitter phase because one field answers all three live
+    /// questions: would re-sending this be a no-op device write (the dedupe nudge), is a stop
+    /// redundant, and would the nudge synthesize the reserved stop.
+    last_emit: (u16, u16),
     quirks: ActuatorQuirks,
 }
 
@@ -88,7 +122,7 @@ impl PadState {
         legacy_wire: None,
         dirty: false,
         next_keepalive: None,
-        jitter: false,
+        last_emit: (0, 0),
         quirks: ActuatorQuirks {
             keepalive_ms: 0,
             min_pulse_ms: 0,
@@ -112,6 +146,7 @@ impl PadState {
         self.legacy_wire = None;
         self.next_keepalive = None;
         self.dirty = false;
+        self.last_emit = (0, 0);
         RumbleCommand {
             pad,
             low: 0,
@@ -119,6 +154,40 @@ impl PadState {
             backstop_ms: 0,
         }
     }
+
+    /// Build the command for the pad's current level, and record what we handed out.
+    ///
+    /// On a `dedup_jitter` actuator, re-emitting the value the device last took is a no-op write on
+    /// an SDL-class layer, so the low motor's LSB is nudged. Keying that on `last_emit` rather than
+    /// on a free-running phase is what makes it work on EVERY emit path. Previously the nudge lived
+    /// only in the keepalive branch, so a host renewal — which arrives every `ttl*3/10` ms, 120 ms
+    /// at the 400 ms default and 60 ms at the hatch floor — re-emitted the raw level, collided with
+    /// the last jittered write, was swallowed, AND re-anchored the keepalive. That stretched the
+    /// gap between *distinct* device writes to 80 ms at the default cadence and 100 ms at the
+    /// floor, on an actuator whose quirk declares 40.
+    ///
+    /// The nudge is refused when it would synthesize the reserved `(0, 0)` stop. That is level
+    /// `(1, 0)` and only that: `high` must already be 0, and `low ^ 1 == 0` implies `low == 1`.
+    /// There the LSB steps up instead, so the phase still alternates (1 ↔ 3, two parts in 65535)
+    /// and the pad never receives a stop the policy did not order.
+    fn emit(&mut self, pad: u16) -> RumbleCommand {
+        let (mut low, high) = self.level;
+        if self.quirks.dedup_jitter && (low, high) == self.last_emit {
+            let alt = low ^ 1;
+            low = if (alt, high) == (0, 0) {
+                low | 0b10
+            } else {
+                alt
+            };
+        }
+        self.last_emit = (low, high);
+        RumbleCommand {
+            pad,
+            low,
+            high,
+            backstop_ms: self.backstop(),
+        }
+    }
 }
 
 /// The pure per-connection policy state machine. Time is always passed in (`now`) so the policy
@@ -156,6 +225,8 @@ impl RumbleEngine {
         p.dirty = true;
         match ttl_ms {
             Some(t) => {
+                // Never honour a lease longer than [`MAX_LEASE_MS`], whatever the sender claims.
+                let t = t.min(MAX_LEASE_MS);
                 p.ttl_ms = t;
                 p.legacy_wire = None;
                 p.deadline = if (low, high) != (0, 0) {
@@ -214,22 +285,25 @@ impl RumbleEngine {
             if p.dirty {
                 p.dirty = false;
                 if p.level == (0, 0) {
-                    return (Some(p.silence(pad)), None);
+                    // Relay a stop only if the actuator is, as far as the engine knows, still
+                    // buzzing. A zero on an already-silent pad heals nothing and costs every
+                    // embedder a command — Android an unconditional log line plus a binder
+                    // `cancel()`. Two senders produce them: the host's deliberate
+                    // `RUMBLE_STOP_BURST` re-sends after the first stop already landed, and (behind
+                    // `PUNKTFUNK_RUMBLE_ENVELOPE=0`) the legacy flat 500 ms refresh, which re-sends
+                    // zeros for every latched pad for the rest of the session. The burst still
+                    // heals the case it exists for: a LOST first stop leaves the pad buzzing, so
+                    // `last_emit != (0, 0)` and the re-send does emit.
+                    if p.last_emit != (0, 0) {
+                        return (Some(p.silence(pad)), None);
+                    }
+                    continue;
                 }
                 if p.quirks.keepalive_ms > 0 {
                     p.next_keepalive =
                         Some(now + Duration::from_millis(p.quirks.keepalive_ms as u64));
                 }
-                let (low, high) = p.level;
-                return (
-                    Some(RumbleCommand {
-                        pad,
-                        low,
-                        high,
-                        backstop_ms: p.backstop(),
-                    }),
-                    None,
-                );
+                return (Some(p.emit(pad)), None);
             }
             // 4) actuator-decay keepalive, bounded by (1)/(2) above by construction: an expired
             // or stale pad was silenced before reaching here, so a keepalive can never sustain a
@@ -239,20 +313,7 @@ impl RumbleEngine {
                 let due = *p.next_keepalive.get_or_insert(now + ka);
                 if now >= due {
                     p.next_keepalive = Some(now + ka);
-                    let (mut low, high) = p.level;
-                    if p.quirks.dedup_jitter {
-                        p.jitter = !p.jitter;
-                        low ^= p.jitter as u16;
-                    }
-                    return (
-                        Some(RumbleCommand {
-                            pad,
-                            low,
-                            high,
-                            backstop_ms: p.backstop(),
-                        }),
-                        None,
-                    );
+                    return (Some(p.emit(pad)), None);
                 }
                 merge_wake(&mut wake, due);
             }
@@ -357,6 +418,22 @@ pub(crate) struct Closed;
 mod tests {
     use super::*;
 
+    /// The Steam Deck's declared quirks — the only shipping actuator with `dedup_jitter`.
+    const DECK: ActuatorQuirks = ActuatorQuirks {
+        keepalive_ms: 40,
+        min_pulse_ms: 0,
+        dedup_jitter: true,
+    };
+
+    /// Drain the engine the way an embedder does: poll until nothing is due.
+    fn drain(e: &mut RumbleEngine, t: Instant) -> Vec<(u16, u16)> {
+        let mut out = Vec::new();
+        while let (Some(c), _) = e.poll(t) {
+            out.push((c.low, c.high));
+        }
+        out
+    }
+
     fn ms(v: u64) -> Duration {
         Duration::from_millis(v)
     }
@@ -527,4 +604,133 @@ mod tests {
         );
         assert_eq!(shared.next_command(ms(10)), Err(Closed));
     }
+
+    /// A host renewal must not repeat the value the device last took, or an SDL-class layer
+    /// swallows the write. Before the jitter moved onto every emit path it lived only in the
+    /// keepalive branch, so each renewal collided with the last jittered write and was deduped.
+    #[test]
+    fn renewal_keeps_the_dedupe_jitter_alternating() {
+        let mut e = RumbleEngine::new();
+        e.set_quirks(0, DECK);
+        let t0 = Instant::now();
+        e.wire_update(t0, 0, 100, 200, Some(400));
+        assert_eq!(drain(&mut e, t0), vec![(100, 200)]);
+        assert_eq!(drain(&mut e, t0 + ms(40)), vec![(101, 200)]);
+        assert_eq!(drain(&mut e, t0 + ms(80)), vec![(100, 200)]);
+        // The renewal at the 120 ms default cadence: same level, must still be a distinct write.
+        e.wire_update(t0 + ms(120), 0, 100, 200, Some(400));
+        assert_eq!(drain(&mut e, t0 + ms(120)), vec![(101, 200)]);
+        assert_eq!(drain(&mut e, t0 + ms(160)), vec![(100, 200)]);
+    }
+
+    /// Phase-robust version of the same property, at the TTL hatch's 60 ms renewal floor: no two
+    /// consecutive DISTINCT device writes may be further apart than the declared 40 ms cadence.
+    #[test]
+    fn renewal_never_gaps_distinct_writes_at_the_60ms_floor() {
+        let mut e = RumbleEngine::new();
+        e.set_quirks(0, DECK);
+        let t0 = Instant::now();
+        let (mut last, mut last_write, mut worst) = ((0u16, 0u16), 0u64, 0u64);
+        for tick in 0..=360u64 {
+            let t = t0 + ms(tick);
+            if tick % 60 == 0 {
+                e.wire_update(t, 0, 100, 200, Some(400));
+            }
+            for v in drain(&mut e, t) {
+                assert_ne!(v, (0, 0), "a live lease must never emit the stop sentinel");
+                if v != last {
+                    worst = worst.max(tick - last_write);
+                    last_write = tick;
+                    last = v;
+                }
+            }
+        }
+        assert!(
+            worst <= 41,
+            "worst distinct-write gap {worst} ms exceeds the 40 ms declared cadence"
+        );
+    }
+
+    /// The nudge must stay behind `dedup_jitter`: an off-by-one amplitude on a default-quirks pad
+    /// would land in Apple's identical-target comparison and Android's one-shot amplitudes.
+    #[test]
+    fn default_quirks_pads_get_the_level_verbatim_on_every_renewal() {
+        let mut e = RumbleEngine::new(); // Apple / Android / plain SDL
+        let t0 = Instant::now();
+        e.wire_update(t0, 0, 100, 200, Some(400));
+        assert_eq!(e.poll(t0).0, Some(cmd(0, 100, 200, 800)));
+        e.wire_update(t0 + ms(120), 0, 100, 200, Some(400));
+        assert_eq!(e.poll(t0 + ms(120)).0, Some(cmd(0, 100, 200, 800)));
+    }
+
+    /// Level `(1, 0)` is the one value whose LSB flip is the reserved stop. The nudge steps up
+    /// instead, so the phase still alternates and no stop is invented under a live lease.
+    #[test]
+    fn jitter_never_synthesizes_the_stop_sentinel() {
+        let mut e = RumbleEngine::new();
+        e.set_quirks(0, DECK);
+        let t0 = Instant::now();
+        e.wire_update(t0, 0, 1, 0, Some(400));
+        assert_eq!(e.poll(t0).0, Some(cmd(0, 1, 0, 800)));
+        assert_eq!(e.poll(t0 + ms(40)).0, Some(cmd(0, 3, 0, 800)));
+        assert_eq!(e.poll(t0 + ms(80)).0, Some(cmd(0, 1, 0, 800)));
+    }
+
+    /// A zero for a pad the engine already believes is silent is dropped: it heals nothing and
+    /// costs every embedder a command. The deliberate stop-burst heal is unaffected, because a
+    /// LOST stop leaves the pad buzzing and the re-send therefore does emit.
+    #[test]
+    fn a_redundant_stop_is_dropped_but_the_burst_still_heals_a_lost_one() {
+        let mut e = RumbleEngine::new();
+        let t0 = Instant::now();
+        e.wire_update(t0, 0, 100, 200, Some(400));
+        assert_eq!(drain(&mut e, t0), vec![(100, 200)]);
+        // First stop reaches the embedder…
+        e.wire_update(t0 + ms(10), 0, 0, 0, Some(0));
+        assert_eq!(drain(&mut e, t0 + ms(10)), vec![(0, 0)]);
+        // …and the burst re-sends behind it are now silent.
+        e.wire_update(t0 + ms(20), 0, 0, 0, Some(0));
+        e.wire_update(t0 + ms(30), 0, 0, 0, Some(0));
+        assert_eq!(drain(&mut e, t0 + ms(30)), Vec::new());
+
+        // But if the pad is buzzing (the stop that mattered was lost), a re-send still emits.
+        e.wire_update(t0 + ms(40), 0, 100, 200, Some(400));
+        assert_eq!(drain(&mut e, t0 + ms(40)), vec![(100, 200)]);
+        e.wire_update(t0 + ms(50), 0, 0, 0, Some(0));
+        assert_eq!(drain(&mut e, t0 + ms(50)), vec![(0, 0)]);
+    }
+
+    /// The client bounds the host's lease. `RUMBLE_TTL_CEIL_MS` is sender-side only, so a modified
+    /// or third-party host could otherwise stamp a huge TTL and wedge its pump, leaving Apple and
+    /// the Deck buzzing for the whole of it.
+    #[test]
+    fn an_overlong_lease_is_clamped_to_the_ceiling() {
+        let mut e = RumbleEngine::new();
+        let t0 = Instant::now();
+        e.wire_update(t0, 0, 100, 200, Some(u16::MAX));
+        assert_eq!(e.poll(t0).0, Some(cmd(0, 100, 200, 5000)));
+        // Silenced at the ceiling, not at the 65 s the sender asked for.
+        assert!(e.poll(t0 + ms(MAX_LEASE_MS as u64 - 1)).0.is_none());
+        assert_eq!(
+            e.poll(t0 + ms(MAX_LEASE_MS as u64)).0,
+            Some(cmd(0, 0, 0, 0)),
+            "the lease must end at the ceiling"
+        );
+    }
+
+    /// A v2 envelope carrying `ttl_ms == 0` on a LIVE level. The audit suspected the zero would be
+    /// mistaken for the legacy sentinel in `backstop()`; it cannot, because the expiry check
+    /// preempts the relay branch — the pad silences on the same poll and never reaches a backstop.
+    /// Pinned so that ordering stays load-bearing rather than incidental.
+    #[test]
+    fn a_zero_ttl_envelope_silences_rather_than_taking_the_legacy_backstop() {
+        let mut e = RumbleEngine::new();
+        let t0 = Instant::now();
+        e.wire_update(t0, 0, 100, 200, Some(0));
+        assert_eq!(
+            e.poll(t0).0,
+            Some(cmd(0, 0, 0, 0)),
+            "a zero-length lease must expire immediately, not emit with a legacy backstop"
+        );
+    }
 }

crates/punktfunk-core/src/lib.rs

@@ -107,6 +107,10 @@ pub use stats::Stats;
 /// v10: added `punktfunk_connection_clock_offset_now_ns` — the LIVE (mid-stream re-synced)
 /// clock offset ongoing latency math must use; the connect-time getter stays frozen by
 /// contract. Additive, client-local — no wire change, so [`WIRE_VERSION`] is unchanged.
+/// v11: added `punktfunk_connect_ex9` — `connect_ex8` plus a `client_caps` bitfield
+/// (`PUNKTFUNK_CLIENT_CAP_CURSOR`, later `…_PHASE_LOCK`), which is how a client tells the host it
+/// renders the pointer itself. Additive; the caps ride the existing Hello, so [`WIRE_VERSION`] is
+/// unchanged. (Documented late — the bump shipped without its line here.)
 /// v12: added `punktfunk_connection_set_cursor_render` — the mid-stream cursor-render flip
 /// (design/remote-desktop-sweep.md §8): the client's mouse-model chord tells the host who
 /// renders the pointer. Additive; rides the existing control stream (a new message TYPE, which
@@ -120,7 +124,15 @@ pub use stats::Stats;
 /// uncertainty and the circular arrival-lead statistic the host's controller steers on. Additive;
 /// the wire grows only a new control message (`PhaseReport`, 0x32) an old host never reads and a
 /// strict-prefix append on the 0xCF host-timing tail, so [`WIRE_VERSION`] is unchanged.
-pub const ABI_VERSION: u32 = 14;
+/// v15: versions the shared rumble policy engine's C surface —
+/// `punktfunk_connection_next_rumble_cmd`, `punktfunk_connection_set_rumble_quirks` and the
+/// `PUNKTFUNK_RUMBLE_QUIRK_*` bits. These symbols are NOT new: they landed while this constant
+/// still read 7 and no bump was made, so every core since has exported them while advertising a
+/// version that never promised them. That cannot be corrected retroactively — a shipped binary
+/// says what it says — so v15 is the floor that *guarantees* them: at or above it the surface is
+/// present, below it an embedder must probe for the symbol. Purely a version statement; no code
+/// changed with this bump, and no wire change, so [`WIRE_VERSION`] is unchanged.
+pub const ABI_VERSION: u32 = 15;
 
 /// The punktfunk/1 **wire** version — what `Hello`/`Welcome` carry and hosts equality-check.
 /// Deliberately its own constant: [`ABI_VERSION`] tracks the embeddable **C surface**

crates/punktfunk-core/src/quic/datagram.rs

@@ -401,6 +401,16 @@ impl RichInput {
     }
 }
 
+/// Longest [`HidOutput::Trigger`] `effect` the wire carries: the DualSense adaptive-trigger
+/// parameter block is a mode byte plus ten parameters, and every consumer copies at most this many
+/// into its report.
+///
+/// The single source for the clamp on BOTH sides. `Trigger` was the only variable-length variant
+/// bounded on neither: encode appended whatever it was handed and decode took the entire tail, so
+/// an attacker-sized datagram was reproduced verbatim into a `Vec` while its sibling `HidRaw` had
+/// been bounded on both ends all along.
+pub const TRIGGER_EFFECT_MAX: usize = 11;
+
 const HIDOUT_LED: u8 = 0x01;
 const HIDOUT_PLAYER_LEDS: u8 = 0x02;
 const HIDOUT_TRIGGER: u8 = 0x03;
@@ -431,6 +441,14 @@ pub enum HidOutput {
     /// A trackpad haptic pulse for a Steam Controller's voice-coil actuators (its only "rumble").
     /// `side` 0 = right pad, 1 = left pad; `amplitude` + `period` (µs off-time) + `count` (pulses)
     /// synthesize a buzz. A client without trackpad coils drops it (or maps it to ordinary rumble).
+    ///
+    /// **STAGED SCAFFOLDING — deliberately unreachable today, do not delete.** Nothing on the host
+    /// produces this variant and no client renders it; it codes/decodes and round-trips in tests
+    /// and nothing else. It stays because `HIDOUT_TRACKPAD_HAPTIC` is an allocated tag on a
+    /// SHIPPED wire: removing the variant would not reclaim the tag (a future peer could still
+    /// send it), it would only lose the decoder that keeps such a datagram from being mistaken
+    /// for something else. The producer is the Steam Controller coil path; the renderer is the
+    /// client-side coil write. Wire up either half and this becomes live with no format change.
     TrackpadHaptic {
         pad: u8,
         side: u8,
@@ -460,7 +478,7 @@ impl HidOutput {
             }
             HidOutput::Trigger { pad, which, effect } => {
                 out.extend_from_slice(&[HIDOUT_TRIGGER, *pad, *which]);
-                out.extend_from_slice(effect);
+                out.extend_from_slice(&effect[..effect.len().min(TRIGGER_EFFECT_MAX)]);
             }
             HidOutput::TrackpadHaptic {
                 pad,
@@ -497,10 +515,17 @@ impl HidOutput {
                 pad: b[2],
                 bits: b[3],
             }),
-            HIDOUT_TRIGGER if b.len() >= 4 => Some(HidOutput::Trigger {
+            // `> 4`, not `>= 4`: a body with no effect bytes at all is malformed, and decoding it
+            // as an EMPTY effect was actively harmful — downstream an empty block is written as an
+            // all-zero trigger report, which is mode 0x00, which RELEASES a held effect. A
+            // truncated datagram could therefore silently cancel the trigger a game was holding.
+            // A genuine "no effect" is a full-length zero block and still decodes fine.
+            HIDOUT_TRIGGER if b.len() > 4 => Some(HidOutput::Trigger {
                 pad: b[2],
                 which: b[3],
-                effect: b[4..].to_vec(),
+                // Bounded like `HidRaw` below: at most the parameter block is kept from the
+                // (attacker-sized) tail.
+                effect: b[4..b.len().min(4 + TRIGGER_EFFECT_MAX)].to_vec(),
             }),
             HIDOUT_TRACKPAD_HAPTIC if b.len() >= 10 => Some(HidOutput::TrackpadHaptic {
                 pad: b[2],
@@ -981,6 +1006,82 @@ mod tests {
         assert!(decode_rumble_datagram(&d[..6]).is_none());
     }
 
+    /// `Trigger` is the only variable-length variant that used to be bounded on NEITHER side.
+    /// Pinned here because both halves matter: an over-long effect must be clamped on the way out
+    /// AND on the way in, and a body with no effect bytes must not decode at all.
+    #[test]
+    fn trigger_effect_is_clamped_on_both_encode_and_decode() {
+        // Encode clamps: a caller handing over an over-long block cannot put it on the wire.
+        let long = HidOutput::Trigger {
+            pad: 1,
+            which: 0,
+            effect: vec![0xAB; 200],
+        };
+        let d = long.encode();
+        assert_eq!(
+            d.len(),
+            4 + TRIGGER_EFFECT_MAX,
+            "magic + kind + pad + which + at most the parameter block"
+        );
+
+        // Decode clamps independently of encode — a hostile peer does not use our encoder.
+        let mut hostile = vec![HIDOUT_MAGIC, super::HIDOUT_TRIGGER, 1, 0];
+        hostile.extend_from_slice(&[0xCD; 500]);
+        match HidOutput::decode(&hostile) {
+            Some(HidOutput::Trigger { effect, .. }) => {
+                assert_eq!(effect.len(), TRIGGER_EFFECT_MAX, "tail is bounded");
+            }
+            other => panic!("expected a clamped Trigger, got {other:?}"),
+        }
+
+        // An exact-length effect survives untouched, and round-trips.
+        let ok = HidOutput::Trigger {
+            pad: 2,
+            which: 1,
+            effect: vec![0x02, 0x90, 0xA0, 0xFF, 0, 0, 0, 0, 0, 0, 0],
+        };
+        assert_eq!(HidOutput::decode(&ok.encode()), Some(ok));
+    }
+
+    /// A body with no effect bytes is malformed and must be REJECTED, not read as an empty effect:
+    /// downstream an empty block becomes an all-zero trigger report, which is mode 0x00 — it
+    /// releases whatever effect the game was holding. A truncated datagram must not do that.
+    #[test]
+    fn a_trigger_with_no_effect_bytes_is_rejected_not_read_as_cancel() {
+        let empty = [HIDOUT_MAGIC, super::HIDOUT_TRIGGER, 0, 0];
+        assert_eq!(HidOutput::decode(&empty), None);
+
+        // One byte of effect is a legitimate short block (consumers zero-pad it) and still decodes.
+        let one = [HIDOUT_MAGIC, super::HIDOUT_TRIGGER, 0, 0, 0x02];
+        assert_eq!(
+            HidOutput::decode(&one),
+            Some(HidOutput::Trigger {
+                pad: 0,
+                which: 0,
+                effect: vec![0x02]
+            })
+        );
+    }
+
+    /// `HidRaw`'s bound was already correct on both sides — pinned alongside `Trigger` so the pair
+    /// cannot drift apart again.
+    #[test]
+    fn hid_raw_stays_bounded_on_both_sides() {
+        let long = HidOutput::HidRaw {
+            pad: 0,
+            kind: HID_RAW_OUTPUT,
+            data: vec![0x11; 500],
+        };
+        assert_eq!(long.encode().len(), 4 + HID_REPORT_MAX);
+
+        let mut hostile = vec![HIDOUT_MAGIC, super::HIDOUT_HID_RAW, 0, HID_RAW_FEATURE];
+        hostile.extend_from_slice(&[0x22; 900]);
+        match HidOutput::decode(&hostile) {
+            Some(HidOutput::HidRaw { data, .. }) => assert_eq!(data.len(), HID_REPORT_MAX),
+            other => panic!("expected a clamped HidRaw, got {other:?}"),
+        }
+    }
+
     #[test]
     fn rumble_envelope_roundtrip_and_legacy_tolerance() {
         // v2 envelope round-trips seq + ttl.

crates/punktfunk-host/src/detect.rs

@@ -16,6 +16,19 @@
 //! [`KNOWN`] as new forks appear) matched against running processes, registered OS services/units,
 //! and on-disk install markers. The platform back-ends (`detect/windows.rs`, `detect/linux.rs`)
 //! provide the raw facts; the matching + rendering here is portable and unit-tested.
+//!
+//! **Not every fingerprint is a conflict.** Only a host that is running, or that will start on its
+//! own, can take the ports or load a second virtual-display driver. A leftover `Program Files`
+//! folder from an uninstall, a binary on `PATH`, or a service registered but *disabled* clashes
+//! with nothing — Sunshine's and Apollo's uninstallers both leave their config/log directories
+//! behind, so treating mere presence as a conflict cries wolf on a machine whose other host is long
+//! gone. [`Evidence::is_active`] draws that line and [`Detection::is_active`] lifts it to the
+//! product; the warning surfaces (startup log, `/local/summary` → the web console's conflicts card,
+//! the `detect-conflicts` exit code) report **only** active detections, while the full report still
+//! lists the dormant ones as context for support. This matches the installer's own probe
+//! (`punktfunk-host.iss`'s `StreamHostEnabled`: service start type <= 2), which was narrowed to
+//! exactly this rule after a dormant Sunshine aborted a `winget install` in the field, and the tray,
+//! which dropped its always-on warning over a merely-installed Sunshine in `3e782852`.
 
 use std::sync::OnceLock;
 
@@ -73,17 +86,38 @@ impl Product {
 pub enum Evidence {
     /// A matching process is running **right now** (process/executable basename).
     Running { process: String },
-    /// An OS service / systemd unit for the product is registered (installed; may be stopped).
-    Service { name: String },
+    /// An OS service / systemd unit for the product is registered. `autostart` is the load-bearing
+    /// bit: a service that comes up on its own (Windows start type boot/system/automatic; an enabled
+    /// systemd unit) *will* clash, whereas a disabled/manual one is inert until someone starts it by
+    /// hand — at which point the `Running` evidence catches it on the next scan.
+    Service { name: String, autostart: bool },
     /// Installed on disk — a Program Files directory, a flatpak app id, or a binary on `PATH`.
+    /// Always dormant: files that nothing launches bind no ports.
     Installed { at: String },
 }
 
 impl Evidence {
+    /// Does this observation mean a conflicting host will actually take the ports / load a second
+    /// virtual-display driver? See the module docs — this is the whole false-alarm fix.
+    pub fn is_active(&self) -> bool {
+        match self {
+            Evidence::Running { .. } => true,
+            Evidence::Service { autostart, .. } => *autostart,
+            Evidence::Installed { .. } => false,
+        }
+    }
+
     fn render(&self) -> String {
         match self {
             Evidence::Running { process } => format!("running now ({process})"),
-            Evidence::Service { name } => format!("service {name}"),
+            Evidence::Service {
+                name,
+                autostart: true,
+            } => format!("service {name} (starts automatically)"),
+            Evidence::Service {
+                name,
+                autostart: false,
+            } => format!("service {name} (disabled/manual — dormant)"),
             Evidence::Installed { at } => format!("installed at {at}"),
         }
     }
@@ -105,12 +139,24 @@ impl Detection {
             .any(|e| matches!(e, Evidence::Running { .. }))
     }
 
-    /// A compact one-line label for the tray/console summary, e.g. `Sunshine (running)`.
+    /// True when this host is running **or** will start on its own — i.e. the detection is worth
+    /// warning a user about. A product seen only as files on disk or a disabled service is dormant
+    /// and reports `false`; see the module docs.
+    pub fn is_active(&self) -> bool {
+        self.evidence.iter().any(Evidence::is_active)
+    }
+
+    /// A compact one-line label for the console summary, e.g. `Sunshine (running)`. The qualifier
+    /// names what was actually observed, so a card built from these labels can never claim a
+    /// dormant install is running.
     pub fn label(&self) -> String {
+        let name = self.product.label();
         if self.is_running() {
-            format!("{} (running)", self.product.label())
+            format!("{name} (running)")
+        } else if self.is_active() {
+            format!("{name} (starts automatically)")
         } else {
-            self.product.label().to_string()
+            format!("{name} (installed, not running)")
         }
     }
 }
@@ -225,28 +271,66 @@ pub fn snapshot() -> &'static [Detection] {
     SNAPSHOT.get().map(Vec::as_slice).unwrap_or(&[])
 }
 
-/// Compact labels for the tray / web-console summary (e.g. `["Sunshine (running)", "Apollo"]`).
-pub fn summary_labels(detections: &[Detection]) -> Vec<String> {
-    detections.iter().map(Detection::label).collect()
+/// True if any detection is active — the one gate the warning surfaces share (startup log, the
+/// `detect-conflicts` exit code, the console card).
+pub fn any_active(detections: &[Detection]) -> bool {
+    detections.iter().any(Detection::is_active)
 }
 
-/// A full human-readable report: the blurb + one bullet per detected host with its evidence.
-/// Empty string when nothing was detected (callers gate on `is_empty()`).
+/// Compact labels for the web-console summary (e.g. `["Sunshine (running)"]`).
+///
+/// **Active detections only.** A dormant leftover (an uninstalled Sunshine's `Program Files` folder,
+/// a disabled service) is deliberately absent: this feeds the console's conflicts card, which exists
+/// to explain why clients cannot reach a working-looking host, and files that nothing launches never
+/// cause that. The full [`render_report`] still lists them for support.
+pub fn summary_labels(detections: &[Detection]) -> Vec<String> {
+    detections
+        .iter()
+        .filter(|d| d.is_active())
+        .map(Detection::label)
+        .collect()
+}
+
+/// A full human-readable report, split by whether the finding can actually clash. Empty string when
+/// nothing was detected at all (callers gate on `is_empty()`).
+///
+/// The dormant section is why this stays verbose where [`summary_labels`] is quiet: when a user asks
+/// "why does Punktfunk think I have Apollo?", the answer is the exact leftover path, and the report
+/// says in the same breath that it needs no action.
 pub fn render_report(detections: &[Detection]) -> String {
     if detections.is_empty() {
         return String::new();
     }
-    let mut s = String::from("Detected another game-streaming host on this machine.\n");
-    s.push_str(UNSUPPORTED_BLURB);
-    s.push_str("\n\nDetected:\n");
-    for d in detections {
+    let bullet = |d: &Detection| {
         let ev = d
             .evidence
             .iter()
             .map(Evidence::render)
             .collect::<Vec<_>>()
             .join("; ");
-        s.push_str(&format!("  \u{2022} {} \u{2014} {ev}\n", d.product.label()));
+        format!("  \u{2022} {} \u{2014} {ev}\n", d.product.label())
+    };
+    let (active, dormant): (Vec<_>, Vec<_>) = detections.iter().partition(|d| d.is_active());
+    let mut s = String::new();
+    if !active.is_empty() {
+        s.push_str("Detected another game-streaming host on this machine.\n");
+        s.push_str(UNSUPPORTED_BLURB);
+        s.push_str("\n\nDetected:\n");
+        for d in &active {
+            s.push_str(&bullet(d));
+        }
+    }
+    if !dormant.is_empty() {
+        if !active.is_empty() {
+            s.push('\n');
+        }
+        s.push_str(
+            "Also present but DORMANT — not running and not set to start on its own, so it clashes \
+with nothing and needs no action (typically leftovers from an uninstall):\n",
+        );
+        for d in &dormant {
+            s.push_str(&bullet(d));
+        }
     }
     s
 }
@@ -275,15 +359,19 @@ mod tests {
                 },
                 Evidence::Service {
                     name: "SunshineService".into(),
+                    autostart: true,
                 },
             ],
         );
         assert!(d.is_running());
+        assert!(d.is_active());
         assert_eq!(d.label(), "Sunshine (running)");
     }
 
+    /// The field case this split exists for: Apollo uninstalled, its `Program Files` folder left
+    /// behind. Nothing launches it, so it is NOT a conflict and must never reach the console card.
     #[test]
-    fn installed_only_is_not_running() {
+    fn a_leftover_install_dir_is_dormant_and_never_surfaces() {
         let d = det(
             Product::Apollo,
             vec![Evidence::Installed {
@@ -291,42 +379,77 @@ mod tests {
             }],
         );
         assert!(!d.is_running());
-        assert_eq!(d.label(), "Apollo");
+        assert!(!d.is_active(), "files on disk cannot bind a port");
+        assert_eq!(d.label(), "Apollo (installed, not running)");
+        assert!(summary_labels(std::slice::from_ref(&d)).is_empty());
+        assert!(!any_active(&[d]));
+    }
+
+    /// A registered-but-DISABLED service is the other half of the same false alarm: `service_exists`
+    /// used to count it, which disagreed with the installer's `Start <= 2` probe.
+    #[test]
+    fn a_disabled_service_is_dormant_but_an_autostart_one_is_not() {
+        let disabled = det(
+            Product::Sunshine,
+            vec![Evidence::Service {
+                name: "SunshineService".into(),
+                autostart: false,
+            }],
+        );
+        assert!(!disabled.is_active());
+        assert!(summary_labels(&[disabled]).is_empty());
+
+        let auto = det(
+            Product::Sunshine,
+            vec![Evidence::Service {
+                name: "SunshineService".into(),
+                autostart: true,
+            }],
+        );
+        assert!(auto.is_active());
+        assert!(!auto.is_running(), "registered to start != started");
+        assert_eq!(auto.label(), "Sunshine (starts automatically)");
+        assert_eq!(
+            summary_labels(&[auto]),
+            vec!["Sunshine (starts automatically)".to_string()]
+        );
     }
 
     #[test]
-    fn report_lists_every_product_and_the_blurb() {
-        let report = render_report(&[
-            det(
-                Product::Sunshine,
-                vec![Evidence::Running {
-                    process: "sunshine".into(),
-                }],
-            ),
-            det(
-                Product::Apollo,
-                vec![Evidence::Installed {
-                    at: "/usr/bin/apollo".into(),
-                }],
-            ),
-        ]);
+    fn report_separates_active_from_dormant_and_keeps_the_blurb() {
+        let active = det(
+            Product::Sunshine,
+            vec![Evidence::Running {
+                process: "sunshine".into(),
+            }],
+        );
+        let dormant = det(
+            Product::Apollo,
+            vec![Evidence::Installed {
+                at: "/usr/bin/apollo".into(),
+            }],
+        );
+        let report = render_report(&[active.clone(), dormant.clone()]);
         assert!(report.contains("UNSUPPORTED"));
+        // The bullets name the PRODUCT and let the evidence speak — `Detection::label`'s qualifier
+        // would only restate what follows the dash ("Sunshine (running) — running now (sunshine)").
+        // The qualifier is for `summary_labels`, which has no evidence text beside it.
         assert!(report.contains("Sunshine \u{2014} running now (sunshine)"));
+        assert!(report.contains("DORMANT"));
         assert!(report.contains("Apollo \u{2014} installed at /usr/bin/apollo"));
+        // Only the live one is offered to the console card.
         assert_eq!(
-            summary_labels(&[
-                det(
-                    Product::Sunshine,
-                    vec![Evidence::Running {
-                        process: "sunshine".into()
-                    }]
-                ),
-                det(
-                    Product::Apollo,
-                    vec![Evidence::Installed { at: "x".into() }]
-                ),
-            ]),
-            vec!["Sunshine (running)".to_string(), "Apollo".to_string()]
+            summary_labels(&[active, dormant.clone()]),
+            vec!["Sunshine (running)".to_string()]
+        );
+
+        // A dormant-only machine gets the explanatory listing WITHOUT the "unsupported" alarm — the
+        // whole point is that this needs no action.
+        let dormant_only = render_report(&[dormant]);
+        assert!(dormant_only.contains("DORMANT"));
+        assert!(
+            !dormant_only.contains("UNSUPPORTED"),
+            "a leftover folder must not read as an unsupported dual-host setup:\n{dormant_only}"
         );
     }
 

crates/punktfunk-host/src/detect/linux.rs

@@ -50,7 +50,11 @@ pub fn static_evidence(known: &Known) -> Vec<Evidence> {
     for unit in known.linux_units {
         let file = format!("{unit}.service");
         if unit_dirs.iter().any(|d| Path::new(d).join(&file).exists()) {
-            ev.push(Evidence::Service { name: file });
+            let autostart = unit_enabled(&file, home.as_deref());
+            ev.push(Evidence::Service {
+                name: file,
+                autostart,
+            });
         }
     }
 
@@ -78,6 +82,49 @@ pub fn static_evidence(known: &Known) -> Vec<Evidence> {
     ev
 }
 
+/// Is `unit` (a `<name>.service` filename) **enabled** — i.e. will systemd start it on its own?
+///
+/// `systemctl enable` works by symlinking the unit into a target's `.wants`/`.requires` directory,
+/// so the presence of that link is the enablement fact — readable without spawning `systemctl`
+/// (this module is deliberately subprocess-free, and the host often runs where `systemctl` output
+/// would need a bus connection anyway). A unit file that exists but is linked from no target is
+/// installed-but-inert: nothing starts it at boot, so it clashes with nothing.
+///
+/// Scans the `.wants`/`.requires` subdirectories of the drop-in roots systemd actually reads, rather
+/// than hardcoding `multi-user.target` — a unit pulled in by `graphical.target`, a user
+/// `default.target`, or any other target is just as enabled.
+fn unit_enabled(unit: &str, home: Option<&std::ffi::OsStr>) -> bool {
+    let mut roots: Vec<String> = vec![
+        "/etc/systemd/system".into(),
+        "/run/systemd/system".into(),
+        "/usr/lib/systemd/system".into(),
+        "/lib/systemd/system".into(),
+        "/etc/systemd/user".into(),
+        "/usr/lib/systemd/user".into(),
+    ];
+    if let Some(h) = home {
+        roots.push(format!("{}/.config/systemd/user", h.to_string_lossy()));
+    }
+    for root in roots {
+        let Ok(entries) = std::fs::read_dir(&root) else {
+            continue;
+        };
+        for entry in entries.flatten() {
+            let name = entry.file_name();
+            let name = name.to_string_lossy();
+            if !(name.ends_with(".wants") || name.ends_with(".requires")) {
+                continue;
+            }
+            // `symlink_metadata` so a DANGLING link still counts: a link into a target's .wants is
+            // what "enabled" means, and a broken one still says the operator enabled it.
+            if std::fs::symlink_metadata(entry.path().join(unit)).is_ok() {
+                return true;
+            }
+        }
+    }
+    false
+}
+
 fn find_on_path(bin: &str, path: Option<&std::ffi::OsStr>) -> Option<String> {
     let dirs = path.map(std::env::split_paths).into_iter().flatten();
     // Always also probe the common bindirs, even if PATH is unset/narrow (e.g. a service context).

crates/punktfunk-host/src/detect/windows.rs

@@ -7,7 +7,7 @@ use windows::Win32::Foundation::CloseHandle;
 use windows::Win32::System::Diagnostics::ToolHelp::{
     CreateToolhelp32Snapshot, Process32FirstW, Process32NextW, PROCESSENTRY32W, TH32CS_SNAPPROCESS,
 };
-use windows_service::service::ServiceAccess;
+use windows_service::service::{ServiceAccess, ServiceStartType};
 use windows_service::service_manager::{ServiceManager, ServiceManagerAccess};
 
 /// Lowercased executable basenames (without `.exe`) of every running process, via a Toolhelp
@@ -49,9 +49,10 @@ pub fn running_processes() -> Vec<String> {
 pub fn static_evidence(known: &Known) -> Vec<Evidence> {
     let mut ev = Vec::new();
     for svc in known.win_services {
-        if service_exists(svc) {
+        if let Some(autostart) = service_start_type(svc) {
             ev.push(Evidence::Service {
                 name: (*svc).to_string(),
+                autostart,
             });
         }
     }
@@ -63,14 +64,35 @@ pub fn static_evidence(known: &Known) -> Vec<Evidence> {
     ev
 }
 
-/// True if a service by this name is registered with the SCM (running or stopped). Opening it with
-/// `QUERY_STATUS` fails cleanly when it doesn't exist.
-fn service_exists(name: &str) -> bool {
-    let Ok(mgr) = ServiceManager::local_computer(None::<&str>, ServiceManagerAccess::CONNECT)
-    else {
-        return false;
-    };
-    mgr.open_service(name, ServiceAccess::QUERY_STATUS).is_ok()
+/// `Some(autostart)` if a service by this name is registered with the SCM (running or stopped),
+/// `None` if it does not exist. Opening it fails cleanly when it doesn't exist.
+///
+/// `autostart` mirrors the installer's `StreamHostEnabled` (start type <= 2): only boot/system/auto
+/// come up on their own, and only a host that comes up can take the GameStream ports. A disabled or
+/// manual service is dormant — see the module docs on `super`. When the start type cannot be read
+/// (no `QUERY_CONFIG` right) we report the service as dormant rather than guessing it autostarts:
+/// the false-alarm this whole split exists to kill is worse than a missed warning, and a host that
+/// is genuinely up is caught by the process scan regardless of what its service config says.
+fn service_start_type(name: &str) -> Option<bool> {
+    let mgr = ServiceManager::local_computer(None::<&str>, ServiceManagerAccess::CONNECT).ok()?;
+    let svc = mgr
+        .open_service(
+            name,
+            ServiceAccess::QUERY_CONFIG | ServiceAccess::QUERY_STATUS,
+        )
+        // Fall back to a status-only handle so a service we may not configure still registers as
+        // present (dormant) instead of vanishing from the report entirely.
+        .or_else(|_| mgr.open_service(name, ServiceAccess::QUERY_STATUS))
+        .ok()?;
+    let autostart = svc.query_config().is_ok_and(|c| {
+        matches!(
+            c.start_type,
+            ServiceStartType::AutoStart
+                | ServiceStartType::BootStart
+                | ServiceStartType::SystemStart
+        )
+    });
+    Some(autostart)
 }
 
 /// The install directory under any of the Program Files roots, if it exists.

crates/punktfunk-host/src/gamestream/mod.rs

@@ -334,15 +334,26 @@ pub fn serve(
         "punktfunk host"
     );
     // Surface a conflicting Moonlight-compatible host (Sunshine/Apollo/…) as early as possible:
-    // scan once (cached for `/local/summary` → tray + web console) and warn loudly if found.
+    // scan once (cached for `/local/summary` → the web console) and warn loudly if one can actually
+    // clash. A dormant leftover (an uninstalled Sunshine's Program Files folder, a disabled service)
+    // is logged at INFO instead — it belongs in a support log, not in a warning that reads like a
+    // fault on every boot.
     let conflicts = crate::detect::init();
     if !conflicts.is_empty() {
-        tracing::warn!(
-            target: "punktfunk::detect",
-            count = conflicts.len(),
-            "{}",
-            crate::detect::render_report(conflicts)
-        );
+        let report = crate::detect::render_report(conflicts);
+        if crate::detect::any_active(conflicts) {
+            tracing::warn!(
+                target: "punktfunk::detect",
+                count = conflicts.len(),
+                "{report}"
+            );
+        } else {
+            tracing::info!(
+                target: "punktfunk::detect",
+                count = conflicts.len(),
+                "{report}"
+            );
+        }
     }
     if gamestream {
         tracing::warn!(

crates/punktfunk-host/src/main.rs

@@ -104,10 +104,14 @@ mod tray;
 mod store;
 mod stream_marker;
 mod update;
-// `monitor_devnode::startup_recover()` (below) re-enables PnP monitor devnodes disabled by a prior
-// run; it lives in the `pf-win-display` leaf crate (plan §W6).
+// The two startup crash-recovery legs (below), both in the `pf-win-display` leaf crate (plan §W6):
+// `monitor_devnode::startup_recover()` re-enables PnP monitor devnodes disabled by a prior run, and
+// `isolate_journal::startup_recover()` re-lights displays a prior run deactivated for an EXCLUSIVE
+// session and never restored.
 #[cfg(target_os = "windows")]
 use pf_win_display::monitor_devnode;
+#[cfg(target_os = "windows")]
+use pf_win_display::win_display::isolate_journal;
 // Virtual-display orchestration lives in the `pf-vdisplay` subsystem crate (plan §W6); this shim
 // keeps every existing `crate::vdisplay::*` path valid (serve/mgmt/native/capture consume the trait,
 // registry, and manager through it). The DDC panel control + the KWin zkde protocol moved with it.
@@ -379,6 +383,12 @@ fn real_main() -> Result<()> {
             // restored (crash/kill/power loss) — before any new session touches the topology.
             #[cfg(target_os = "windows")]
             monitor_devnode::startup_recover();
+            // The same recovery for the DEFAULT Exclusive path: a previous host that died holding a
+            // CCD isolate left the operator's panels deactivated with nothing to put them back (the
+            // restore snapshot was process memory). Runs AFTER the devnode leg so re-enabled
+            // monitors are present again and the EXTEND preset can actually light them.
+            #[cfg(target_os = "windows")]
+            isolate_journal::startup_recover();
             gamestream::serve(mgmt_opts, native, gamestream)
         }
         // Report other Moonlight-compatible hosts (Sunshine/Apollo/…) installed or running on this
@@ -388,11 +398,17 @@ fn real_main() -> Result<()> {
             let found = detect::scan();
             if found.is_empty() {
                 println!("No conflicting game-streaming host detected.");
-                Ok(())
-            } else {
-                print!("{}", detect::render_report(&found));
+                return Ok(());
+            }
+            print!("{}", detect::render_report(&found));
+            // Exit 1 ONLY for a host that runs or will start on its own. The installers and support
+            // scripts gate on this code, and a dormant leftover used to abort them — a `winget
+            // install` failed in the field on a box whose Sunshine was merely present (see the
+            // module docs + `punktfunk-host.iss`). Dormant findings print, then exit 0.
+            if detect::any_active(&found) {
                 std::process::exit(1);
             }
+            Ok(())
         }
         // Install and run host plugins: `plugins add playnite`, `plugins enable`, … Package ops are
         // forwarded to the bun runner; enable/disable/status drive the systemd unit (Linux) or the

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

@@ -15,13 +15,14 @@ The Linux, Windows, Mac, iPhone/iPad and Android apps group settings the same wa
 **Display**, **Input**, **Audio**, **Controllers** — under *Preferences* on Linux and *Settings*
 elsewhere. The Apple TV app shows one scrolling list instead, and so does any client's settings
 screen reached with a controller. A controller-driven launch (Steam Deck Gaming Mode) opens the
-client's **console home**, whose settings screen is one steppable list; the Decky plugin's Settings
-tab covers the same store in the same groups and the same order, as a left rail of categories the
-way SteamOS's own Settings looks. The console home is part of the
-client — it is not the host's
-[web console](/docs/web-console).
+client's **console home**, whose settings screen is one steppable list of sections — **Stream**,
+**Video**, **Presentation**, **Audio**, **Controller**, **Touchscreen**, **Interface**,
+**Profiles**. On a Steam Deck that list *is* the settings surface: the
+[Decky plugin](/docs/steam-deck) is a launcher and keeps no settings of its own, and its **Open
+Punktfunk** button puts the console home one tap from the Quick Access Menu. The console home is
+part of the client — it is not the host's [web console](/docs/web-console).
 
-Linux stores them in `~/.config/punktfunk/client-gtk-settings.json`, the same file the Decky plugin
+Linux stores them in `~/.config/punktfunk/client-gtk-settings.json`, the same file the console home
 writes, so a change in either shows up in the other. Windows uses
 `%APPDATA%\punktfunk\client-windows-settings.json`; the Apple and Android apps use their own stores.
 
@@ -45,9 +46,9 @@ and your client scales what it gets — see
 
 **Match window** — *default: off.* The stream mode follows your window instead, and each resize
 renegotiates the host's display and encoder, so a windowed session stays pixel-exact. Fullscreen
-degenerates to the display's native mode. Offered by the Linux, Windows, Mac, iPhone/iPad, console
-home and Decky screens (on Decky it sits in the Resolution picker, and Gaming-Mode streams are
-always fullscreen, so it lands on native); not by Android.
+degenerates to the display's native mode. Offered by the Linux, Windows, Mac, iPhone/iPad and
+console-home screens (in the console home it is an option inside the Resolution picker, and a
+Gaming-Mode stream is always fullscreen, so there it lands on native); not by Android.
 
 **Refresh rate** — *default: Native*, the refresh of the display your window is on. The Apple app
 stores an explicit rate (60 Hz by default): iPhone and iPad offer the rates the device can display,
@@ -68,11 +69,11 @@ capacity probe stay off for the whole session.
 multiplied by this, and your device resamples the result to its window. Above 1× supersamples for
 sharpness, at more bandwidth *and* more decode work; below 1× is lighter on both the host and the
 link. The stops run 0.5× to 4×. The result is floored to an even size and capped per axis at
-4096 px for H.264, 8192 px otherwise. Offered everywhere except the console home's list.
+4096 px for H.264, 8192 px otherwise. Offered everywhere.
 
 **Video codec** — *default: Automatic.* A soft preference: the host emits your choice when it can
 also produce it, otherwise the best codec you both speak, in the order HEVC → AV1 → H.264.
-**PyroWave** is never auto-picked — pick it explicitly on Linux, Windows, the console home, Decky, or
+**PyroWave** is never auto-picked — pick it explicitly on Linux, Windows, the console home, or
 an Apple device whose decode probe passes; anywhere else it isn't offered, and asking for it lands on
 that same order. See [PyroWave](/docs/pyrowave). The Android and Apple apps hide AV1 unless the
 device has a hardware AV1 decoder; Android never offers PyroWave.
@@ -86,13 +87,13 @@ Full detail: [HDR](/docs/hdr).
 needs HEVC or PyroWave, the host's own 4:4:4 policy left on, a capture path that delivers full
 chroma, and a GPU that can encode it; if any gate fails the host says 4:2:0 before your decoder is
 built. The Apple, Linux and Windows apps all advertise it (Apple additionally requires its hardware
-decode probe to pass). The console home and Decky offer the toggle; Android doesn't.
+decode probe to pass). The console home offers the toggle; Android doesn't.
 
 **Prioritize** — *default: Lowest latency.* What the client optimizes for when a decoded frame is
 ready. **Lowest latency** shows every frame the moment the display can take it, so a network hiccup
 becomes an occasional repeated or skipped frame. **Smoothness** holds a small buffer that evens
-those hiccups out, at that buffer's worth of added delay. Linux and Windows apps, the console home
-and Decky; the Apple and Android apps have carried the same setting for a while, and it is stored
+those hiccups out, at that buffer's worth of added delay. Linux and Windows apps and the console
+home; the Apple and Android apps have carried the same setting for a while, and it is stored
 under the same name, so a [profile](/docs/profiles-and-links) means the same thing on every device.
 
 **Smoothness buffer** — *default: Automatic (two frames).* Only shown under **Smoothness**. How
@@ -106,7 +107,7 @@ the instant it's ready instead of waiting for the screen's next refresh: the low
 can give you, at the cost of visible tearing on fast motion. It is **best-effort** — not every
 driver or compositor offers a tearing mode, and where none is available the stream stays tear-free.
 The Detailed [stats overlay](/docs/stats) names the mode actually in use, so you can tell "off"
-from "off but unavailable". Linux and Windows apps, the console home and Decky.
+from "off but unavailable". Linux and Windows apps and the console home.
 
 **Follow variable refresh rate** — *default: on.* On a VRR / FreeSync / G-Sync screen, let the panel
 refresh in step with the stream rather than on a fixed cadence — which removes the wait between a
@@ -115,8 +116,8 @@ windowed one is at the compositor's mercy) and is harmless on a fixed-refresh sc
 graphics driver that offers the modern queue-free display mode; on an older driver it does nothing
 unless you also set `PUNKTFUNK_VRR_FIFO=1` (see [configuration](/docs/configuration)), because the
 older way of following a panel costs noticeable latency on a fixed-refresh screen. The stats overlay
-reports `vrr yes` once it has *measured* that the panel really is following. Linux and Windows apps,
-the console home and Decky.
+reports `vrr yes` once it has *measured* that the panel really is following. Linux and Windows apps
+and the console home.
 
 **Host compositor** — *default: Automatic.* Which backend a **Linux** host uses to drive the virtual
 output. Advisory: a host without that backend quietly auto-detects instead.
@@ -130,7 +131,7 @@ claims a sink advertising exactly that many channels, so applications produce re
 **Windows** host loopback-captures your current output endpoint and lets Windows convert it — so 5.1
 from a stereo endpoint is an upmix, not new channels. Offered everywhere.
 
-**Microphone** — *default: off on Linux, Windows, Android, the console home and Decky; on in the
+**Microphone** — *default: off on Linux, Windows, Android and the console home; on in the
 Apple app.* Sends this device's microphone to the host's virtual mic. On Linux and Windows the
 row is spelled *Stream microphone*, and **Ctrl+Alt+Shift+V** mutes it mid-stream without ending
 anything — see [Muting your microphone](/docs/input#muting-your-microphone).
@@ -142,18 +143,18 @@ from an echo-cancelled PipeWire source when your desktop provides one, on **Wind
 for the Communications stream category so the endpoint's processing engages, and on **Apple** and
 **Android** the platform's voice-processing mode. Turn it off if your microphone already runs its
 own processing, or if the canceller makes your voice sound thin. The row sits under the microphone
-toggle and greys out while the microphone is off. Offered by the Linux, Windows, Apple, Android,
-console-home and Decky clients. What it can and can't fix is in
+toggle and greys out while the microphone is off. Offered by the Linux, Windows, Apple, Android and
+console-home clients. What it can and can't fix is in
 [Why do I hear myself](/docs/echo).
 
 **Speaker** and **Microphone** device pickers — *default: System default.* Which endpoint stream
-audio plays out of, and which input feeds the uplink. Only the Linux app (PipeWire nodes), the
-**Mac** app (which also has a microphone *channel* picker) and **Decky** have these — iPhone, iPad,
-Apple TV, Android and the console home have none, and the Windows app has none and ignores a stored
-speaker choice. On Linux, a device that has since disappeared keeps a "(not detected)" entry rather
-than silently snapping back to the default; the Mac shows it as "Unavailable device" and Decky as
-"(not connected)". Decky reads the endpoint list from the client's session binary, so a client
-older than the two-binary split leaves these pickers on Automatic.
+audio plays out of, and which input feeds the uplink. Only the Linux app (PipeWire nodes) and the
+**Mac** app (which also has a microphone *channel* picker) have these — iPhone, iPad, Apple TV,
+Android and the console home have none, and the Windows app has none and ignores a stored speaker
+choice. On Linux, a device that has since disappeared keeps a "(not detected)" entry rather than
+silently snapping back to the default; the Mac shows it as "Unavailable device". A Steam Deck in
+Gaming Mode therefore has no endpoint picker at all: the session uses whatever the Desktop-Mode app
+last stored, and the system default otherwise.
 
 ## Input
 
@@ -182,7 +183,7 @@ client greys them out to say so.
 
 **Gamepad type** (*Controller type* on Apple, Android and the console home) — *default: Automatic*,
 which matches each physical controller. The pickers offer Xbox 360, Xbox One, DualSense and
-DualShock 4 everywhere, plus Steam Deck on Linux, Android, the console home and Decky. Your client
+DualShock 4 everywhere, plus Steam Deck on Linux, Android and the console home. Your client
 declares a type per pad as it connects — Automatic declares what that controller really is, an
 explicit choice declares your choice — and the host builds each virtual pad from that. A type the
 host has no backend for degrades to an Xbox 360 pad rather than failing: Xbox One on a Windows host,
@@ -193,8 +194,23 @@ which forwards *every* connected controller, each as its own player, on Linux, W
 console home. Pinning one restricts the session to that controller alone — single-player. The Android
 app has no such picker.
 
-**Capture system shortcuts** — *default: on.* Offered by the Linux and Windows apps, the console home
-and Decky; Windows spells the row out as *Capture system shortcuts (Alt+Tab, Win, …)*. On a Deck it
+**Steam / guide button** (*Guide button* on Apple and Android) — *default: Automatic*, on every
+client. Where the guide (Xbox/PS/Steam) and quick-access presses go while streaming: **Send to
+host** forwards them raw, **This device** keeps them local. Automatic forwards everywhere except
+Gaming Mode, where SteamOS opens its own menus for those buttons no matter what — forwarding raw
+there opens *both* menus at once, the local one covering the stream. The full story, including how
+to reach the host's menus when the raw press stays local, is on the
+[Input page](/docs/input#the-guide-button-xbox--ps--steam-and-quick-access).
+
+**Hold Select for guide** — *default: Automatic*, on every client. The gesture that presses the
+host's guide button from any controller: hold Select (Back/View) on its own for about a third of a
+second, and keep holding for the host's long-press (a Gaming-Mode host's Quick Access Menu, on a
+regular pad). Automatic arms it only where the raw guide press can't reach the host cleanly —
+Gaming Mode, iPhone/iPad, Apple TV — because the gesture has a cost: a Select *tap* arrives a beat
+late, and a game that expects a *held* Select would trigger it. Set **On** or **Off** to overrule.
+
+**Capture system shortcuts** — *default: on.* Offered by the Linux and Windows apps and the console
+home; Windows spells the row out as *Capture system shortcuts (Alt+Tab, Win, …)*. On a Deck it
 matters only for a keyboard you attached yourself, for the reason the paragraph below gives: Gaming
 Mode is gamescope, which has nothing to hold back. On, Alt+Tab and the Windows key
 (Super on Linux) reach the host while the stream has input captured. Off, they act on this machine
@@ -215,21 +231,22 @@ the wlroots compositors all do, and X11 sessions grab the keyboard directly. Und
 Wake-on-LAN and waits for it to boot — only for a host whose MAC address this client has already
 learned. Turn it off for hosts you reach over a VPN, where "offline" usually means "not reachable by
 broadcast" and the wake only adds a delay. The Linux, Windows, Apple and Android apps have this
-toggle, as do the console home and Decky — and note that the Decky plugin sends a wake of its own
-before a stream starts whatever this setting says, so on a Deck it governs the client's connect
-rather than the launch. The console home also offers wake as an explicit action on an offline host.
-See
+toggle, as does the console home — and on a Steam Deck it governs the
+[Decky plugin's](/docs/steam-deck) launches too, because the plugin starts every stream through the
+client, which reads this setting like any other connect. The console home also offers wake as an
+explicit action on an offline host, whatever the toggle says. See
 [Wake-on-LAN](/docs/wake-on-lan).
 
 **Show game library** — *default: off on Linux and Windows; on in the Apple and Android apps.* Browse
 a paired host's games and launch one directly; the Windows app still labels it experimental. The
-console home and Decky have the toggle too — on Decky it governs the *client's* screens, since the
-plugin's own library browser works either way. See [Game library](/docs/game-library).
+console home has the toggle too, and it governs the desktop clients that share the store — the
+console's own **Library** button is offered on any paired host either way. See
+[Game library](/docs/game-library).
 
 **Start streams in fullscreen** — *default: on.* On Linux and Windows, F11 or Alt+Enter leaves
 fullscreen live. On a Mac the setting is **Fullscreen while streaming**, and the window comes back
-when you return to the host list. The console home and Decky carry the row for the desktop client
-that shares the store — a Gaming-Mode launch is fullscreen whatever it says. iPhone, iPad, Apple TV
+when you return to the host list. The console home carries the row for the desktop client that
+shares the store — a Gaming-Mode launch is fullscreen whatever it says. iPhone, iPad, Apple TV
 and Android have no equivalent.
 
 ## Overlay
@@ -237,9 +254,9 @@ and Android have no equivalent.
 **Statistics overlay** — *default: Normal.* Four tiers — Off, Compact, Normal, Detailed — each a
 superset of the one before. This setting only picks the tier a session *starts* at — you can cycle
 them live in-stream, with a shortcut that differs by platform. The Apple app additionally lets you
-choose which corner the overlay sits in (Top Left, Top Right, Bottom Left, Bottom Right). The Decky
-plugin has the tier picker too, in its Settings section. The shortcuts, and every number in the
-overlay, are in
+choose which corner the overlay sits in (Top Left, Top Right, Bottom Left, Bottom Right). The
+console home has the tier picker too, as **Statistics overlay** under **Interface**. The shortcuts,
+and every number in the overlay, are in
 [Understanding the stats overlay](/docs/stats).
 
 ## Settings that are facts about your device
@@ -251,8 +268,8 @@ stay global and **cannot be put in a settings profile**:
   vendor-ordered and falls back on its own; change it only when debugging, and note that
   `PUNKTFUNK_DECODER` overrides it
   ([Configuration](/docs/configuration#client-side-native-clients)). The decoder picker is on Linux,
-  Windows, in the console home and in Decky; the GPU picker on Windows, and on Linux and Decky only
-  when the machine has more than one adapter — which a Deck doesn't, so the row isn't there. The
+  Windows and in the console home; the GPU picker on Windows, and on Linux only when the machine has
+  more than one adapter — the console home has none, and a Deck has a single adapter anyway. The
   Apple and Android apps have neither.
 - **Speaker** and **Microphone** device pickers — this device's audio endpoints.
 - **Forwarded controller** — which physical pad is in your hands. The *type* the host creates is a

docs-site/content/docs/clipboard.md

@@ -77,7 +77,8 @@ The setting is read when a session starts, so if you change it while streaming,
 macOS can also flip it mid-session: **Stream ▸ Share Clipboard** (⌃⌥⇧C), which becomes **Stop
 Sharing Clipboard** once the host has acknowledged it.
 
-iOS, iPadOS, tvOS and the Steam Deck Decky plugin have no clipboard switch — see
+iOS, iPadOS, tvOS and a Steam Deck in Gaming Mode have no clipboard switch — neither the Decky
+panel nor the client's console home has a host edit sheet — see
 [what each client does](#which-hosts-and-clients-support-it) below.
 
 ## Nothing crosses until something pastes
@@ -134,8 +135,9 @@ when a host application pastes.
 
 The **Linux client has the switch but no working clipboard bridge**: it enables the plane and then
 has no code to read or write the desktop's own clipboard, so nothing is announced and nothing is
-pasted. Turning it on there is harmless but has no effect today. The Decky plugin on the Steam Deck
-has no switch at all.
+pasted. Turning it on there is harmless but has no effect today. On a Steam Deck in Gaming Mode
+there is no switch at all — the Decky panel doesn't edit hosts — and since a Deck streams with that
+same Linux client, a switch there would have nothing to move anyway.
 
 When you copy **on the Windows client**, images cross only if the copying application publishes the
 registered `PNG` clipboard format. Many Windows apps publish only a bitmap, and those copies aren't

docs-site/content/docs/game-library.md

@@ -132,11 +132,10 @@ and runs what it already knows about the title, so a client can never hand the h
 - **Android** — the library lives only in the controller-optimized home, which a TV always uses and a
   phone or tablet switches to when a controller is connected. Press **Y** on a saved host, or open its
   options and choose **Library**.
-- **Steam Deck (Decky)** — the plugin's per-host **Games** picker lists the library and lets you
-  **Pin** titles; a pinned game becomes a one-tap row under **Pinned Games** in the Quick Access Menu.
-  The picker itself doesn't launch anything — either tap a pinned row, or use **Open library on
-  screen** to browse the host's games full-screen on the Deck and launch from there. See
-  [Steam Deck](/docs/steam-deck).
+- **Steam Deck (Decky)** — the panel is a launcher and browses nothing itself: tap **Open
+  Punktfunk**, which opens the client's console home, and a paired host's **Library** button is
+  right there — full-screen covers, gamepad-navigable, and a press starts the stream with the title
+  launching. See [Steam Deck](/docs/steam-deck).
 - **Moonlight** — when the host runs with `--gamestream`, your library appears in Moonlight's app
   list beside `Desktop`, with covers served by the host. A title keeps the same app id across host
   restarts, so Moonlight's cached tiles stay correct. Titles with no launch recipe are left out.

docs-site/content/docs/input.md

@@ -49,8 +49,9 @@ your settings. If the stream isn't sending a microphone at all (**Stream microph
 [client settings](/docs/client-settings#audio)) the shortcut does nothing and no badge appears,
 rather than pretending to mute something.
 
-This is on the **Linux and Windows** clients. The Apple, Android and Decky clients have no mute
-shortcut yet; turn **Stream microphone** off in their settings instead.
+This is on the **Linux and Windows** clients — including a Steam Deck stream, which is the Linux
+client, so an attached keyboard gets the chord. The Apple and Android clients have no mute shortcut
+yet; turn **Stream microphone** off in their settings instead.
 
 Alt-Tabbing away releases input on its own and takes it back when you return. A release you asked
 for with the chord stays released until you opt back in. Either way, keys and buttons you were
@@ -98,6 +99,39 @@ there the client stops opening the controller at all, which is the point of the
 **Ctrl+Alt+Shift+D** or the client's own UI to leave instead. The Apple and Android apps keep
 watching for the chord either way.
 
+### The guide button (Xbox / PS / Steam) and Quick Access
+
+A controller's **guide button** — the Xbox logo, the PS button, the Deck's **Steam** button — is
+meant to open menus **on the host**: the Steam overlay, or a Gaming-Mode host's Steam menu. Some
+devices want that button for themselves, so every client also carries a gesture that works
+everywhere:
+
+**Hold Select (Back / View) on its own for about a third of a second.** The host sees its guide
+button go down, and it stays down for as long as you hold — so keeping it held reads as a long
+press on the host, which is how SteamOS opens the **Quick Access Menu** for a regular pad. A quick
+tap of Select still reaches the game, delivered when you let go (a beat late). Select pressed as
+part of a combo — including the leave chord above — passes through untouched.
+
+What the raw button does, per client:
+
+- **Linux & Windows desktop, macOS, Android** — the guide press is forwarded to the host. If
+  Steam Big Picture or the Xbox Game Bar is also watching for it *on the device in your hands*,
+  both may react — that's a local setting on that device, not something the stream can suppress.
+- **Steam Deck / Gaming Mode** — the **Steam** and **`…`** buttons stay with the Deck by default:
+  SteamOS always opens its own menus for them, so forwarding the raw press as well opened BOTH
+  menus at once, the Deck's on top of the stream. Reach the host's menus with **hold-Select**, or
+  with the Punktfunk panel's **Host menus** buttons ([Steam Deck page](/docs/steam-deck)). The
+  old behavior is one setting away: **Steam / guide button → Send to host**.
+- **iPhone / iPad** — iOS reserves the Home press for its own Game Overlay, so hold-Select is the
+  reliable route to the host's overlay. On iOS 27 or later you can also hand the button to the
+  app yourself, in the system's per-controller Home-button setting.
+- **Apple TV** — tvOS never delivers the Home press to apps; hold-Select is the only route.
+
+Both halves are [settings](/docs/client-settings#input), per profile like everything else:
+**Steam / guide button** (Automatic / Send to host / This device) and **Hold Select for guide**
+(Automatic / On / Off). Automatic picks the behavior above for each platform — the gesture stays
+off where the raw button already works, so games that use a *held* Select keep it.
+
 ## Mouse modes
 
 There are two, and they are a per-client setting called **Mouse input**:

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

@@ -79,9 +79,11 @@ list: [Clients → the `punktfunk` CLI](/docs/clients#scripting-the-punktfunk-cl
 ## Steam Deck
 
 Most Deck users want **Gaming Mode**: install the **[Decky plugin](/docs/steam-deck)** and a
-**Punktfunk** panel lands in the Quick Access Menu, so you can discover hosts, pair with a PIN, and
-stream **without dropping to the desktop**. Follow the **[Steam Deck (Decky) guide](/docs/steam-deck)**
-— it walks through Decky Loader, the plugin, and the one-time client install.
+**Punktfunk** panel lands in the Quick Access Menu, so you can find a host, get let in (a PIN, or a
+request the host's operator approves), and stream **without dropping to the desktop**. Everything
+else — settings, the game library, adding a host by address — is one tap away in the client's own
+gamepad UI. Follow the **[Steam Deck (Decky) guide](/docs/steam-deck)** — it walks through Decky
+Loader, the plugin, and the one-time client install.
 
 > The plugin doesn't decode video itself — it drives whichever `punktfunk-client` is installed on
 > the Deck. The Flatpak below is the tested default; a native package or a sysext works too. If your

docs-site/content/docs/pairing.md

@@ -61,8 +61,8 @@ Then, on the client:
 - **[Native clients](/docs/clients) (Apple, Linux, Windows, Android):** select the host (or use
   *Pair with PIN…* from its menu) and enter the PIN the host displays.
 - **[Steam Deck](/docs/steam-deck) (the Decky plugin):** open Punktfunk from the Quick Access menu
-  and pick the host — an unpaired one's button reads **Pair & Stream**. Enter the PIN on the
-  4-digit pad it opens.
+  and pick the host — an unpaired one opens a sheet offering **Request access** (no PIN: somebody
+  approves the Deck at the host) or **Use a PIN instead**, which opens the 4-digit pad.
 - **[Moonlight](/docs/moonlight):** choose **Pair**; Moonlight shows a 4-digit PIN, and you type
   that PIN into the console's **Moonlight (GameStream) pairing** card and press **Submit PIN**.
   (This direction is the reverse of the native flow, and arming doesn't apply to it.)