chore(apple): declare non-exempt encryption in Info.plist (export compliance)

ITSAppUsesNonExemptEncryption = true — the app's AES-GCM session crypto is
non-exempt under the App Store Connect encryption questionnaire (category
chosen; French ANSSI declaration in progress). First of the six targets;
the remaining Info.plists follow with the rest of the compliance work.

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

.cargo/config.toml

@@ -0,0 +1,18 @@
+# Workspace-wide build flags.
+#
+# aes_armv8: RustCrypto's `aes` 0.8.x enables ARMv8-Crypto hardware AES on aarch64 only behind
+# this cfg (x86_64 AES-NI is runtime-detected with no flag; the 0.9 line will make aarch64
+# automatic too). Without it every aarch64 client (all Apple + virtually all Android) ran
+# SOFTWARE AES on the per-packet decrypt path — measured 2026-07-14 on an M3 Ultra at
+# ~240 MiB/s/core (~7 µs per 1.4 KB datagram), which single-handedly capped receive throughput
+# at ~1.57 Gbps wire. The cfg still runtime-detects via `cpufeatures`, so a chip without the
+# extensions falls back safely.
+#
+# NOTE: a RUSTFLAGS environment variable OVERRIDES config rustflags entirely — build scripts /
+# CI lanes that set RUSTFLAGS for aarch64 targets (cargo-ndk, xcframework) must carry
+# `--cfg aes_armv8` themselves.
+# polyval_armv8: same story for GCM's other half — `polyval` 0.6.x gates its PMULL (carry-less
+# multiply) GHASH path behind this cfg on aarch64. AES alone took open_in_place from 240 to
+# ~790 MiB/s on the M3 Ultra; software GHASH still dominated until this flag joined it.
+[target.'cfg(target_arch = "aarch64")']
+rustflags = ["--cfg", "aes_armv8", "--cfg", "polyval_armv8"]

.gitea/workflows/deb.yml

@@ -90,7 +90,14 @@ jobs:
           git config --global --add safe.directory "$PWD"
           # punktfunk-client-session is the Vulkan/Skia streamer the shell execs for a connect —
           # both client binaries must ship (build-client-deb.sh installs both).
-          cargo build --release --locked \
+          # --features punktfunk-host/nvenc: the direct-SDK NVENC path (real RFI + recovery anchor on
+          # Linux NVIDIA; design/linux-direct-nvenc.md). AMD/Intel-safe — NVENC/CUDA is dlopen'd at
+          # runtime (no link-time dep; identical DT_NEEDED to a plain build), and the encoder is only
+          # constructed for a CUDA capture frame + PUNKTFUNK_NVENC_DIRECT, never on VAAPI hosts.
+          # --features punktfunk-host/vulkan-encode: the AMD/Intel twin — raw VK_KHR_video_encode_h265
+          # with real RFI (design/linux-vulkan-video-encode.md). Pure Rust ash (no new lib / link dep);
+          # default on for HEVC (PUNKTFUNK_VULKAN_ENCODE=0 → libav VAAPI), failed open falls back to VAAPI.
+          cargo build --release --locked --features punktfunk-host/nvenc,punktfunk-host/vulkan-encode \
             -p punktfunk-host -p punktfunk-client-linux -p punktfunk-client-session
 
       - name: Build + smoke-boot web console (bun preset)

CONTRIBUTING.md

@@ -30,6 +30,16 @@ file with `scripts/gen-third-party-notices.sh` when the dependency tree changes.
 
 ## Before you push
 
+Enable the repo git hooks once per clone — they run the exact rustfmt gates CI runs (main
+workspace + the UMDF driver workspace) on every commit and push, so a push can never fail CI
+on formatting alone:
+
+```sh
+git config core.hooksPath scripts/git-hooks
+```
+
+Then the usual full pass:
+
 ```sh
 cargo fmt --all --check
 cargo clippy --workspace --all-targets -- -D warnings

Cargo.lock

@@ -870,15 +870,6 @@ dependencies = [
  "itertools 0.10.5",
 ]
 
-[[package]]
-name = "crossbeam-channel"
-version = "0.5.15"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "82b8f8f868b36967f9606790d1903570de9ceaf870a7bf9fbbd3016d636a2cb2"
-dependencies = [
- "crossbeam-utils",
-]
-
 [[package]]
 name = "crossbeam-deque"
 version = "0.8.6"
@@ -2154,7 +2145,7 @@ dependencies = [
 
 [[package]]
 name = "latency-probe"
-version = "0.9.2"
+version = "0.11.0"
 
 [[package]]
 name = "lazy_static"
@@ -2286,7 +2277,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
 
 [[package]]
 name = "loss-harness"
-version = "0.9.2"
+version = "0.11.0"
 dependencies = [
  "punktfunk-core",
 ]
@@ -2765,7 +2756,7 @@ checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
 
 [[package]]
 name = "pf-client-core"
-version = "0.9.2"
+version = "0.11.0"
 dependencies = [
  "anyhow",
  "async-channel",
@@ -2787,7 +2778,7 @@ dependencies = [
 
 [[package]]
 name = "pf-console-ui"
-version = "0.9.2"
+version = "0.11.0"
 dependencies = [
  "anyhow",
  "ash",
@@ -2808,7 +2799,7 @@ dependencies = [
 
 [[package]]
 name = "pf-ffvk"
-version = "0.9.2"
+version = "0.11.0"
 dependencies = [
  "ash",
  "bindgen",
@@ -2817,7 +2808,7 @@ dependencies = [
 
 [[package]]
 name = "pf-presenter"
-version = "0.9.2"
+version = "0.11.0"
 dependencies = [
  "anyhow",
  "ash",
@@ -3001,7 +2992,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-android"
-version = "0.9.2"
+version = "0.11.0"
 dependencies = [
  "android_logger",
  "jni",
@@ -3017,7 +3008,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-linux"
-version = "0.9.2"
+version = "0.11.0"
 dependencies = [
  "anyhow",
  "async-channel",
@@ -3033,7 +3024,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-session"
-version = "0.9.2"
+version = "0.11.0"
 dependencies = [
  "anyhow",
  "pf-client-core",
@@ -3048,22 +3039,17 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-windows"
-version = "0.9.2"
+version = "0.11.0"
 dependencies = [
- "anyhow",
  "async-channel",
- "crossbeam-channel",
  "ffmpeg-next",
  "mdns-sd",
- "opus",
  "pf-client-core",
  "punktfunk-core",
- "sdl3",
  "serde",
  "serde_json",
  "tracing",
  "tracing-subscriber",
- "wasapi",
  "windows 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
  "windows-reactor",
  "windows-reactor-setup",
@@ -3072,7 +3058,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-core"
-version = "0.9.2"
+version = "0.11.0"
 dependencies = [
  "aes-gcm",
  "bytes",
@@ -3103,7 +3089,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-host"
-version = "0.9.2"
+version = "0.11.0"
 dependencies = [
  "aes",
  "aes-gcm",
@@ -3175,7 +3161,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-probe"
-version = "0.9.2"
+version = "0.11.0"
 dependencies = [
  "anyhow",
  "mdns-sd",
@@ -3189,7 +3175,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-tray"
-version = "0.9.2"
+version = "0.11.0"
 dependencies = [
  "anyhow",
  "ksni",

Cargo.toml

@@ -35,7 +35,7 @@ exclude = [
 ndk = { path = "clients/android/native/vendor/ndk" }
 
 [workspace.package]
-version = "0.9.2"
+version = "0.11.0"
 edition = "2021"
 rust-version = "1.82"
 license = "MIT OR Apache-2.0"

clients/android/app/src/main/AndroidManifest.xml

@@ -33,6 +33,13 @@
     <uses-feature android:name="android.hardware.touchscreen" android:required="false" />
     <uses-feature android:name="android.software.leanback" android:required="false" />
     <uses-feature android:name="android.hardware.gamepad" android:required="false" />
+    <!-- Neutralize Play's IMPLIED hard requirements, which filtered real TVs as "not compatible"
+         (reported on a Philips OLED707): RECORD_AUDIO implies android.hardware.microphone and the
+         Wi-Fi state permissions imply android.hardware.wifi, both required=true unless declared
+         otherwise. Some TVs declare no microphone (mic uplink is optional and runtime-gated) and
+         ethernet-only boxes declare no wifi (discovery/WifiLock are best-effort hedges there). -->
+    <uses-feature android:name="android.hardware.microphone" android:required="false" />
+    <uses-feature android:name="android.hardware.wifi" android:required="false" />
 
     <!-- appCategory="game": a game-streaming client IS a game as far as the SoC is concerned.
          On Snapdragon devices (and other OEMs with a Game Mode / Game Dashboard) this makes the app

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

@@ -0,0 +1,277 @@
+package io.unom.punktfunk
+
+import androidx.activity.compose.BackHandler
+import androidx.compose.animation.core.LinearEasing
+import androidx.compose.animation.core.RepeatMode
+import androidx.compose.animation.core.animateFloat
+import androidx.compose.animation.core.infiniteRepeatable
+import androidx.compose.animation.core.rememberInfiniteTransition
+import androidx.compose.animation.core.tween
+import androidx.compose.foundation.Canvas
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.interaction.MutableInteractionSource
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.widthIn
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Bedtime
+import androidx.compose.material3.AlertDialog
+import androidx.compose.material3.CircularProgressIndicator
+import androidx.compose.material3.Icon
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.remember
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.drawscope.Stroke
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+import androidx.compose.ui.window.DialogProperties
+
+/**
+ * Which phase of the connect flow to draw — the pure view model [ConnectOverlay] resolves from the
+ * live dial/wake state, so [ConnectTakeover] / [ConnectModal] can render (and be screenshot-tested)
+ * statelessly.
+ */
+internal sealed interface ConnectPhase {
+    val hostName: String
+
+    /** The dial is in flight (shown the instant a host is picked). */
+    data class Connecting(override val hostName: String) : ConnectPhase
+
+    /** A sleeping host is being Wake-on-LAN'd and we're waiting for it to advertise again. */
+    data class Waking(override val hostName: String, val seconds: Int, val connectsAfter: Boolean) : ConnectPhase
+
+    /** The wake wait ran out — offer retry / cancel. */
+    data class WakeTimedOut(override val hostName: String) : ConnectPhase
+}
+
+/** Per-phase copy, shared by the console takeover and the touch modal so both read identically. */
+private data class ConnectCopy(
+    val title: String,
+    val subtitle: String,
+    /** Monospace the subtitle so a ticking seconds counter doesn't jitter its width. */
+    val monoSubtitle: Boolean,
+    val cancelLabel: String,
+)
+
+private fun connectCopy(phase: ConnectPhase): ConnectCopy = when (phase) {
+    is ConnectPhase.Connecting -> ConnectCopy(
+        "Connecting to ${phase.hostName}", "Establishing a secure connection…", false, "Cancel",
+    )
+    is ConnectPhase.Waking -> ConnectCopy(
+        "Waking ${phase.hostName}…",
+        "Waiting for it to come online · ${phase.seconds}s",
+        true,
+        // A wake-only wait (no dial after) says "Stop Waiting"; a wake that will connect says "Cancel".
+        if (!phase.connectsAfter) "Stop Waiting" else "Cancel",
+    )
+    is ConnectPhase.WakeTimedOut -> ConnectCopy(
+        "${phase.hostName} didn't wake",
+        "It may still be booting, or it's powered off / off this network.",
+        false,
+        "Cancel",
+    )
+}
+
+/**
+ * The unified "getting you connected" feedback — one flow for BOTH phases of reaching a host, so the
+ * user gets feedback the instant they pick one and it flows seamlessly into a wake if the host turns
+ * out to be asleep:
+ *
+ *  - **Connecting** ([connectingHostName] non-null): the dial is in flight. Shown immediately on tap,
+ *    so a host that takes a beat to answer no longer looks like nothing happened.
+ *  - **Waking** ([WakeController.waking] non-null): the dial failed on a sleeping host, so we're firing
+ *    Wake-on-LAN and waiting for it to advertise again, escalating to a retry/cancel prompt on timeout.
+ *
+ * Presentation is mode-aware (mirrors the Apple client): in the **console / gamepad** UI it's a
+ * full-screen aurora [ConnectTakeover] — the same signature backdrop the console home uses, driven by
+ * the pad (B cancels, A retries once timed out) with a hint bar. In the **default touch** UI it's a
+ * Material [ConnectModal] over the host grid, matching the app's other dialogs — the aurora takeover
+ * looked out of place there.
+ *
+ * The two phases hand off within a single Compose frame (see ConnectScreen's `doConnectDirect` →
+ * `waker.start` → redial), so nothing blinks between them.
+ */
+@Composable
+fun ConnectOverlay(
+    connectingHostName: String?,
+    waker: WakeController,
+    gamepadUi: Boolean,
+    onCancelConnect: () -> Unit,
+) {
+    val waking = waker.waking
+    // Waking takes precedence (it only exists after a dial has failed) so a stray overlap can't strand
+    // the "Connecting…" phase over a wake in progress.
+    val phase = when {
+        waking != null && waking.timedOut -> ConnectPhase.WakeTimedOut(waking.hostName)
+        waking != null -> ConnectPhase.Waking(waking.hostName, waking.seconds, waking.connectsAfter)
+        connectingHostName != null -> ConnectPhase.Connecting(connectingHostName)
+        else -> return
+    }
+
+    // System Back / pad B (remapped) cancels whatever's in flight — a plain dial or the wake wait.
+    val cancel = { if (waking != null) waker.cancel() else onCancelConnect() }
+
+    if (gamepadUi) {
+        BackHandler { cancel() }
+        // A retries once a wake has timed out; B falls through to the BackHandler above.
+        GamepadNavEffect2D(
+            active = true,
+            onDirection = {},
+            onActivate = { if (phase is ConnectPhase.WakeTimedOut) waker.retry() },
+        )
+        ConnectTakeover(phase = phase, onCancel = cancel, onRetry = { waker.retry() })
+    } else {
+        // The AlertDialog owns its own scrim + system-Back handling (routed to cancel).
+        ConnectModal(phase = phase, onCancel = cancel, onRetry = { waker.retry() })
+    }
+}
+
+/**
+ * The default-UI presentation: a Material dialog over the host grid, matching the app's other touch
+ * dialogs. A spinner (or the sleep glyph once timed out) sits above the title; the scrim is inert so a
+ * stray tap can't drop a connect in flight — only the buttons or system Back cancel.
+ */
+@Composable
+internal fun ConnectModal(
+    phase: ConnectPhase,
+    onCancel: () -> Unit,
+    onRetry: () -> Unit,
+) {
+    val copy = connectCopy(phase)
+    val timedOut = phase is ConnectPhase.WakeTimedOut
+    AlertDialog(
+        onDismissRequest = onCancel,
+        properties = DialogProperties(dismissOnClickOutside = false),
+        icon = {
+            if (timedOut) {
+                Icon(Icons.Filled.Bedtime, contentDescription = null)
+            } else {
+                CircularProgressIndicator(modifier = Modifier.size(28.dp), strokeWidth = 3.dp)
+            }
+        },
+        title = { Text(copy.title, textAlign = TextAlign.Center) },
+        text = {
+            Text(
+                copy.subtitle,
+                textAlign = TextAlign.Center,
+                fontFamily = if (copy.monoSubtitle) FontFamily.Monospace else FontFamily.Default,
+            )
+        },
+        // No confirm action until the wake times out; then "Try Again" is the primary button.
+        confirmButton = {
+            if (timedOut) TextButton(onClick = onRetry) { Text("Try Again") }
+        },
+        dismissButton = {
+            TextButton(onClick = onCancel) { Text(copy.cancelLabel) }
+        },
+    )
+}
+
+/**
+ * The console / gamepad presentation: an opaque aurora backdrop with a centred spinner/title/subtitle
+ * for [phase], plus a bottom hint bar spelling out the pad actions (B cancels, A retries once timed
+ * out) — glyph-driven like every other console screen. onClick keeps the hints tappable too, so a
+ * user without a working pad can still get out.
+ */
+@Composable
+internal fun ConnectTakeover(
+    phase: ConnectPhase,
+    onCancel: () -> Unit,
+    onRetry: () -> Unit,
+) {
+    val copy = connectCopy(phase)
+    val timedOut = phase is ConnectPhase.WakeTimedOut
+
+    Box(
+        Modifier
+            .fillMaxSize()
+            // Swallow taps so the screen behind can't be touched through the takeover.
+            .clickable(interactionSource = remember { MutableInteractionSource() }, indication = null) {},
+        contentAlignment = Alignment.Center,
+    ) {
+        GamepadAuroraBackground(Modifier.fillMaxSize())
+        Column(
+            Modifier.padding(horizontal = 40.dp).widthIn(max = 460.dp),
+            horizontalAlignment = Alignment.CenterHorizontally,
+            verticalArrangement = Arrangement.spacedBy(18.dp),
+        ) {
+            if (timedOut) {
+                Box(Modifier.size(120.dp), contentAlignment = Alignment.Center) {
+                    Icon(
+                        Icons.Filled.Bedtime,
+                        contentDescription = null,
+                        tint = Color.White.copy(alpha = 0.9f),
+                        modifier = Modifier.size(46.dp),
+                    )
+                }
+            } else {
+                PulsingSpinner()
+            }
+            Text(
+                copy.title,
+                color = Color.White,
+                fontWeight = FontWeight.Bold,
+                fontSize = 24.sp,
+                textAlign = TextAlign.Center,
+            )
+            Text(
+                copy.subtitle,
+                color = Color.White.copy(alpha = 0.65f),
+                fontSize = 14.sp,
+                textAlign = TextAlign.Center,
+                fontFamily = if (copy.monoSubtitle) FontFamily.Monospace else FontFamily.Default,
+            )
+        }
+        val hints = buildList {
+            add(PadGlyph.hint('B', copy.cancelLabel, onClick = onCancel))
+            if (timedOut) add(PadGlyph.hint('A', "Try Again", onClick = onRetry))
+        }
+        GamepadHintBar(hints, Modifier.align(Alignment.BottomCenter).padding(bottom = 28.dp))
+    }
+}
+
+/**
+ * The connecting/waking indicator: a white progress ring inside two brand-violet halo rings that
+ * expand and fade on a staggered loop — a small sign of life so the takeover reads as working, not
+ * stalled.
+ */
+@Composable
+private fun PulsingSpinner() {
+    val transition = rememberInfiniteTransition(label = "connectPulse")
+    val pulse by transition.animateFloat(
+        initialValue = 0f,
+        targetValue = 1f,
+        animationSpec = infiniteRepeatable(tween(1600, easing = LinearEasing), RepeatMode.Restart),
+        label = "pulse",
+    )
+    Box(Modifier.size(120.dp), contentAlignment = Alignment.Center) {
+        Canvas(Modifier.fillMaxSize()) {
+            val maxR = size.minDimension / 2f
+            for (i in 0..1) {
+                val p = (pulse + i * 0.5f) % 1f
+                drawCircle(
+                    color = Color(0xFF8678F5).copy(alpha = (1f - p) * 0.35f),
+                    radius = maxR * (0.42f + p * 0.58f),
+                    style = Stroke(width = 2.dp.toPx()),
+                )
+            }
+        }
+        CircularProgressIndicator(
+            color = Color.White,
+            strokeWidth = 3.dp,
+            modifier = Modifier.size(54.dp),
+        )
+    }
+}

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

@@ -88,6 +88,16 @@ private class RequestAccessState(val target: PendingTrust) {
     val cancelled = AtomicBoolean(false)
 }
 
+/**
+ * A plain dial in flight — [hostName] labels the unified [ConnectOverlay]'s "Connecting…" phase, and
+ * [cancelled] lets its Cancel abort. The native connect is a blocking call with no abort, so Cancel
+ * returns the UI immediately and a late-arriving handle is torn down silently rather than navigating
+ * into a session the user already backed out of. Mirrors [RequestAccessState]'s late-result handling.
+ */
+private class ConnectAttempt(val hostName: String) {
+    val cancelled = AtomicBoolean(false)
+}
+
 @Composable
 fun ConnectScreen(
     settings: Settings,
@@ -107,6 +117,9 @@ fun ConnectScreen(
     var port by remember { mutableStateOf("9777") }
     var connecting by remember { mutableStateOf(false) }
     var status by remember { mutableStateOf<String?>(null) }
+    // A plain dial in flight (drives the "Connecting…" phase of the full-screen ConnectOverlay); null
+    // when idle or when the request-access / wake flows own the screen instead.
+    var attempt by remember { mutableStateOf<ConnectAttempt?>(null) }
     // The host streams at exactly this mode; "Native" settings resolve from the device display.
     val (w, h, hz) = settings.effectiveMode(context)
 
@@ -267,11 +280,20 @@ fun ConnectScreen(
             status = "Identity not ready yet — try again in a moment"
             return
         }
+        val thisAttempt = ConnectAttempt(name)
+        attempt = thisAttempt // shows the ConnectOverlay's "Connecting…" phase immediately
         connecting = true
-        status = "Connecting to $targetHost:$targetPort…"
+        status = null
         discovery.stop() // free the Wi-Fi radio before the stream session
         scope.launch {
             val handle = connectNative(id, targetHost, targetPort, pinHex ?: "", CONNECT_TIMEOUT_MS)
+            // Cancelled mid-dial: the UI's already been returned (and discovery restarted) by
+            // cancelConnect — drop the just-opened session silently rather than navigating into it.
+            if (thisAttempt.cancelled.get()) {
+                if (handle != 0L) withContext(Dispatchers.IO) { NativeBridge.nativeClose(handle) }
+                return@launch
+            }
+            attempt = null
             connecting = false
             if (handle != 0L) {
                 if (pinHex == null) { // TOFU: pin what we observed (unpaired)
@@ -284,7 +306,9 @@ fun ConnectScreen(
             } else {
                 discovery.start()
                 if (onFailure != null) {
-                    status = ""
+                    // Hand off to the wake-and-wait flow — clearing `attempt` above and setting
+                    // `waker.waking` here land in one recompose, so the overlay slides
+                    // Connecting → Waking without a blank frame.
                     onFailure()
                 } else {
                     status = "Connection failed — check host/port, PIN, and logcat"
@@ -293,6 +317,16 @@ fun ConnectScreen(
         }
     }
 
+    // Cancel a plain dial in flight (the overlay's "Connecting…" phase, B / Cancel). The native
+    // connect can't be aborted, so flag this attempt (a late handle is closed silently in
+    // doConnectDirect) and return the UI now, resuming the discovery we paused for the dial.
+    fun cancelConnect() {
+        attempt?.cancelled?.set(true)
+        attempt = null
+        connecting = false
+        discovery.start()
+    }
+
     // Wake-aware connect. If auto-wake is on (Settings.autoWakeEnabled) and the target is a saved
     // host with a learned MAC that ISN'T currently advertising, fire a wake packet and DIAL
     // IMMEDIATELY — mDNS absence does NOT mean unreachable (a host reached over a routed network —
@@ -506,40 +540,21 @@ fun ConnectScreen(
                     Spacer(Modifier.height(24.dp))
 
                     status?.let {
-                        // While connecting it's progress (spinner, neutral); otherwise it's a
-                        // result/error (red). Previously every status showed in error-red, so a
-                        // normal "Connecting…" looked like a failure.
-                        if (connecting) {
-                            Row(
-                                verticalAlignment = Alignment.CenterVertically,
-                                horizontalArrangement = Arrangement.spacedBy(8.dp),
-                            ) {
-                                CircularProgressIndicator(
-                                    modifier = Modifier.size(16.dp),
-                                    strokeWidth = 2.dp,
-                                )
-                                Text(
-                                    it,
-                                    style = MaterialTheme.typography.bodyMedium,
-                                    color = MaterialTheme.colorScheme.onSurfaceVariant,
-                                )
-                            }
-                        } else {
-                            // Result/error: a filled error container reads as a real failure banner,
-                            // not just red text lost in the layout.
-                            Surface(
-                                color = MaterialTheme.colorScheme.errorContainer,
-                                shape = MaterialTheme.shapes.medium,
-                                modifier = Modifier.fillMaxWidth(),
-                            ) {
-                                Text(
-                                    it,
-                                    style = MaterialTheme.typography.bodyMedium,
-                                    color = MaterialTheme.colorScheme.onErrorContainer,
-                                    textAlign = TextAlign.Center,
-                                    modifier = Modifier.padding(horizontal = 16.dp, vertical = 12.dp),
-                                )
-                            }
+                        // In-flight progress (connecting / waking) is the full-screen ConnectOverlay's
+                        // job now, so `status` only ever carries a result/error here — a filled error
+                        // container reads as a real failure banner, not just red text lost in the layout.
+                        Surface(
+                            color = MaterialTheme.colorScheme.errorContainer,
+                            shape = MaterialTheme.shapes.medium,
+                            modifier = Modifier.fillMaxWidth(),
+                        ) {
+                            Text(
+                                it,
+                                style = MaterialTheme.typography.bodyMedium,
+                                color = MaterialTheme.colorScheme.onErrorContainer,
+                                textAlign = TextAlign.Center,
+                                modifier = Modifier.padding(horizontal = 16.dp, vertical = 12.dp),
+                            )
                         }
                         Spacer(Modifier.height(16.dp))
                     }
@@ -837,8 +852,15 @@ fun ConnectScreen(
         }
     }
 
-    // Topmost: the "Waking…" overlay rides over both the touch grid and the console home.
-    WakeOverlay(waker, gamepadUi)
+    // Topmost: the full-screen connect takeover — instant "Connecting…" feedback on any dial, flowing
+    // seamlessly into the "Waking…" wait if the host turns out to be asleep. Rides over both the touch
+    // grid and the console home.
+    ConnectOverlay(
+        connectingHostName = attempt?.hostName,
+        waker = waker,
+        gamepadUi = gamepadUi,
+        onCancelConnect = { cancelConnect() },
+    )
 }
 
 /**

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

@@ -158,8 +158,11 @@ fun ControllersScreen(gamepadSetting: Int, onBack: () -> Unit) {
                     color = MaterialTheme.colorScheme.onSurfaceVariant,
                 )
             }
-            pads.forEachIndexed { i, dev ->
-                PadRow(dev, forwarded = i == 0, gamepadSetting = gamepadSetting)
+            // Every real controller is forwarded now (Automatic forwards them all, each on its own
+            // wire pad index) — not just the first. A joystick-only device Android doesn't classify as
+            // a gamepad still can't be forwarded (the host wants a gamepad), so gate the badge on it.
+            pads.forEach { dev ->
+                PadRow(dev, forwarded = isForwarded(dev), gamepadSetting = gamepadSetting)
             }
         }
 
@@ -222,8 +225,12 @@ private fun PadRow(dev: InputDevice, forwarded: Boolean, gamepadSetting: Int) {
             Row(modifier = Modifier.fillMaxWidth(), verticalAlignment = Alignment.CenterVertically) {
                 Text(dev.name, style = MaterialTheme.typography.bodyLarge, modifier = Modifier.weight(1f))
                 if (forwarded) {
+                    // Android's own controller number (1-based; 0 = unassigned), shown so a multi-pad
+                    // user can tell which physical pad is which. The stream's wire pad index is
+                    // assigned separately (lowest-free per device) once streaming starts.
+                    val number = dev.controllerNumber
                     Text(
-                        "forwarded to host",
+                        if (number > 0) "forwarded · player $number" else "forwarded to host",
                         style = MaterialTheme.typography.labelSmall,
                         color = MaterialTheme.colorScheme.primary,
                     )
@@ -319,6 +326,15 @@ private fun Group(title: String, content: @Composable ColumnScope.() -> Unit) {
     }
 }
 
+/**
+ * Whether this device is actually forwarded to the host — the same rule the stream's [GamepadRouter]
+ * applies: a real, non-virtual controller whose source classes include GAMEPAD. A joystick-only node
+ * (e.g. a DualSense motion-sensor sibling, or an adapter that enumerates as bare joystick) shows in
+ * the list but isn't forwarded.
+ */
+private fun isForwarded(dev: InputDevice): Boolean =
+    !dev.isVirtual && dev.sources and InputDevice.SOURCE_GAMEPAD == InputDevice.SOURCE_GAMEPAD
+
 /** Whether the controller reports a rumble motor — via VibratorManager (API 31+) or the legacy Vibrator. */
 private fun deviceHasVibrator(dev: InputDevice): Boolean =
     if (Build.VERSION.SDK_INT >= 31) {
@@ -371,6 +387,8 @@ private fun prefLabel(pref: Int): String = when (pref) {
     Gamepad.PREF_DUALSHOCK4 -> "DualShock 4"
     Gamepad.PREF_STEAMCONTROLLER -> "Steam Controller"
     Gamepad.PREF_STEAMDECK -> "Steam Deck"
+    Gamepad.PREF_DUALSENSEEDGE -> "DualSense Edge"
+    Gamepad.PREF_SWITCHPRO -> "Switch Pro"
     else -> "Automatic"
 }
 

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

@@ -241,7 +241,10 @@ private fun resolveDir(s: NavInputState): NavDir? {
     if (s.hatY >= 0.5f) return NavDir.DOWN
     if (s.hatX <= -0.5f) return NavDir.LEFT
     if (s.hatX >= 0.5f) return NavDir.RIGHT
-    return if (abs(s.stickY) >= abs(s.stickX)) {
+    // Horizontal wins an exact |x| == |y| diagonal tie (Y must be strictly greater to take the
+    // vertical branch), matching the SDL core and Apple nav so a perfect 45° push resolves the
+    // same on every client.
+    return if (abs(s.stickY) > abs(s.stickX)) {
         when {
             s.stickY <= -STICK_HIGH -> NavDir.UP
             s.stickY >= STICK_HIGH -> NavDir.DOWN

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

@@ -49,12 +49,14 @@ import androidx.compose.ui.draw.clip
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.graphics.graphicsLayer
 import androidx.compose.ui.platform.LocalConfiguration
+import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.text.style.TextOverflow
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.unit.sp
 import dev.chrisbanes.haze.HazeState
 import dev.chrisbanes.haze.hazeSource
+import io.unom.punktfunk.kit.deviceBodyVibrator
 
 // The gamepad-driven settings screen — the Android mirror of the Apple client's GamepadSettingsView:
 // the couch-relevant subset of the touch settings restyled as a console page and fully navigable with
@@ -82,7 +84,10 @@ fun GamepadSettingsScreen(
     var s by remember { mutableStateOf(initial) }
     fun update(next: Settings) { s = next; onChange(next) }
 
-    val rows = buildSettingsRows(s, ::update)
+    val context = LocalContext.current
+    // Gates the "Rumble on this phone" row — a TV box has no body vibrator to mirror onto.
+    val hasBodyVibrator = remember { deviceBodyVibrator(context) != null }
+    val rows = buildSettingsRows(s, hasBodyVibrator, ::update)
     var focus by remember { mutableIntStateOf(0) }
     if (focus > rows.lastIndex) focus = rows.lastIndex
     // The direction the focused value last stepped (+1 forward / -1 back) — drives which way the
@@ -257,8 +262,13 @@ private fun SettingRowView(row: GpRow, focused: Boolean, adjustDir: Int, onClick
     }
 }
 
-/** Build the console settings rows from the current [Settings], writing through [update]. */
-private fun buildSettingsRows(s: Settings, update: (Settings) -> Unit): List<GpRow> {
+/** Build the console settings rows from the current [Settings], writing through [update].
+ * [hasBodyVibrator] gates the "Rumble on this phone" row (absent on TVs). */
+private fun buildSettingsRows(
+    s: Settings,
+    hasBodyVibrator: Boolean,
+    update: (Settings) -> Unit,
+): List<GpRow> {
     fun <T> choice(
         id: String, header: String?, label: String, detail: String,
         options: List<Pair<T, String>>, current: T, write: (T) -> Unit,
@@ -354,7 +364,18 @@ private fun buildSettingsRows(s: Settings, update: (Settings) -> Unit): List<GpR
             "The virtual pad the host creates — Automatic matches this controller.",
             GAMEPAD_OPTIONS.mapIndexed { i, lbl -> i to lbl }, s.gamepad,
         ) { update(s.copy(gamepad = it)) },
-
+    ) + listOfNotNull(
+        if (hasBodyVibrator) {
+            toggle(
+                "phoneRumble", null, "Rumble on this phone",
+                "Also play controller 1's rumble on this phone's own vibration motor — " +
+                    "for clip-on pads without rumble motors.",
+                s.rumbleOnPhone,
+            ) { update(s.copy(rumbleOnPhone = it)) }
+        } else {
+            null
+        },
+    ) + listOf(
         choice(
             "hud", "Interface", "Statistics overlay",
             "How much the overlay shows: Compact (one line) → Normal → Detailed (full HUD). " +

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

@@ -3,6 +3,7 @@ package io.unom.punktfunk
 import android.os.Build
 import android.os.Bundle
 import android.view.InputDevice
+import android.view.KeyCharacterMap
 import android.view.KeyEvent
 import android.view.MotionEvent
 import androidx.activity.ComponentActivity
@@ -16,6 +17,7 @@ import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
 import io.unom.punktfunk.kit.Gamepad
+import io.unom.punktfunk.kit.GamepadRouter
 import io.unom.punktfunk.kit.Keymap
 import io.unom.punktfunk.kit.NativeBridge
 
@@ -27,8 +29,12 @@ class MainActivity : ComponentActivity() {
      */
     var streamHandle: Long = 0L
 
-    /** Joystick-axis state mapper for the active session (built/reset by StreamScreen). */
-    var axisMapper: Gamepad.AxisMapper? = null
+    /**
+     * Multi-controller router for the active session (built/released by StreamScreen): assigns each
+     * connected pad a stable wire index, threads it onto every event, declares/removes pads on
+     * hot-plug, and routes rumble/HID feedback back by pad index. Null while not streaming.
+     */
+    var gamepadRouter: GamepadRouter? = null
 
     /**
      * Input observers for the Controllers debug screen (set while it is shown, like [streamHandle]).
@@ -44,9 +50,6 @@ class MainActivity : ComponentActivity() {
      */
     var requestStreamExit: (() -> Unit)? = null
 
-    /** Currently-held forwarded pad buttons (bitmask of `Gamepad.BTN_*`), for chord detection. */
-    private var heldPadButtons = 0
-
     /**
      * Whether the last console input came from a real gamepad (face buttons / stick) vs. a TV D-pad
      * remote (which has no A/B/X/Y). The console UI reads this to show glyphs the user recognises — pad
@@ -125,23 +128,12 @@ class MainActivity : ComponentActivity() {
             if (event.isFromSource(InputDevice.SOURCE_GAMEPAD)) {
                 val bit = Gamepad.buttonBit(event.keyCode)
                 if (bit != 0) {
-                    when (event.action) {
-                        // repeatCount guard: don't re-send a held button as auto-repeat.
-                        KeyEvent.ACTION_DOWN -> {
-                            if (event.repeatCount == 0) NativeBridge.nativeSendGamepadButton(handle, bit, true)
-                            heldPadButtons = heldPadButtons or bit
-                            // Emergency exit: Select + Start + L1 + R1 held together leaves the stream
-                            // (a couch user has no keyboard/Back). Fired once per full chord.
-                            if (heldPadButtons and STREAM_EXIT_CHORD == STREAM_EXIT_CHORD) {
-                                heldPadButtons = 0
-                                requestStreamExit?.let { exit -> window.decorView.post { exit() } }
-                            }
-                        }
-                        KeyEvent.ACTION_UP -> {
-                            NativeBridge.nativeSendGamepadButton(handle, bit, false)
-                            heldPadButtons = heldPadButtons and bit.inv()
-                        }
-                    }
+                    // The router forwards the bit on this device's own wire pad index and tracks held
+                    // state per pad. The emergency-exit chord (Select + Start + L1 + R1) is handled
+                    // inside the router: holding it for ~1.5 s fires router.onExitChord (wired in
+                    // StreamScreen), so a couch user with no keyboard/Back can still leave — but an
+                    // accidental brush of the four buttons no longer quits instantly.
+                    gamepadRouter?.onButton(event, bit)
                     return true // consumed
                 }
             }
@@ -162,7 +154,18 @@ class MainActivity : ComponentActivity() {
                     // physical-keyboard layout), keycode fallback — see Keymap docs.
                     val vk = Keymap.toVk(event)
                     if (vk != 0) {
+                        // Soft-keyboard events (the IME's virtual device — the stream's
+                        // KeyCaptureView path) carry Shift only as META state, where a real
+                        // keyboard sends discrete Shift transitions — so mirror the meta bit as
+                        // a VK_LSHIFT wrap or every IME capital/symbol lands unshifted on the
+                        // host. Never applied to hardware events: their Shift already went over
+                        // the wire, and a synthetic release here would un-hold a physical Shift
+                        // the user is still pressing.
+                        val imeShift = event.deviceId == KeyCharacterMap.VIRTUAL_KEYBOARD &&
+                            event.isShiftPressed && vk != 0xA0 && vk != 0xA1
+                        if (down && imeShift) NativeBridge.nativeSendKey(handle, 0xA0, true, 0)
                         NativeBridge.nativeSendKey(handle, vk, down, 0)
+                        if (!down && imeShift) NativeBridge.nativeSendKey(handle, 0xA0, false, 0)
                         return true // consumed — don't let the system also act on it
                     }
                 }
@@ -203,7 +206,7 @@ class MainActivity : ComponentActivity() {
 
     override fun dispatchGenericMotionEvent(event: MotionEvent): Boolean {
         if (streamHandle != 0L) {
-            if (axisMapper?.onMotion(event) == true) return true
+            if (gamepadRouter?.onMotion(event) == true) return true
             return super.dispatchGenericMotionEvent(event)
         }
         // The Controllers debug screen sees pad motion before the stick→D-pad synthesis below.
@@ -248,9 +251,4 @@ class MainActivity : ComponentActivity() {
         -> true
         else -> KeyEvent.isGamepadButton(kc)
     }
-
-    private companion object {
-        /** Emergency stream-exit chord: Select + Start + L1 + R1 held together. */
-        val STREAM_EXIT_CHORD = Gamepad.BTN_BACK or Gamepad.BTN_START or Gamepad.BTN_LB or Gamepad.BTN_RB
-    }
 }

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

@@ -82,6 +82,14 @@ data class Settings(
      * otherwise misfire and wait out its timeout despite the host already being reachable.
      */
     val autoWakeEnabled: Boolean = true,
+    /**
+     * Opt-in: ALSO play the rumble the host addresses to controller 1 (wire pad 0) on this
+     * phone's own vibration motor — for clip-on gamepads that ship without rumble motors, where
+     * the phone body is the only actuator in the player's hands. Off by default; read once per
+     * session by StreamScreen (it hands GamepadFeedback the device vibrator only when set). The
+     * toggle is hidden on devices without a vibrator (TVs), where this would be a silent no-op.
+     */
+    val rumbleOnPhone: Boolean = false,
 )
 
 /** [Settings.touchMode] values; persisted by name. */
@@ -142,6 +150,7 @@ class SettingsStore(context: Context) {
         libraryEnabled = prefs.getBoolean(K_LIBRARY, true),
         lowLatencyMode = prefs.getBoolean(K_LOW_LATENCY, true),
         autoWakeEnabled = prefs.getBoolean(K_AUTO_WAKE, true),
+        rumbleOnPhone = prefs.getBoolean(K_RUMBLE_ON_PHONE, false),
     )
 
     fun save(s: Settings) {
@@ -162,6 +171,7 @@ class SettingsStore(context: Context) {
             .putBoolean(K_LIBRARY, s.libraryEnabled)
             .putBoolean(K_LOW_LATENCY, s.lowLatencyMode)
             .putBoolean(K_AUTO_WAKE, s.autoWakeEnabled)
+            .putBoolean(K_RUMBLE_ON_PHONE, s.rumbleOnPhone)
             .apply()
     }
 
@@ -197,6 +207,7 @@ class SettingsStore(context: Context) {
          */
         const val K_LOW_LATENCY = "low_latency_mode_v2"
         const val K_AUTO_WAKE = "auto_wake_enabled"
+        const val K_RUMBLE_ON_PHONE = "rumble_on_phone"
 
         /** Legacy Boolean the enum replaced — read once as the migration default, never written. */
         const val K_TRACKPAD = "trackpad_mode"

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

@@ -69,6 +69,7 @@ import androidx.compose.ui.text.input.KeyboardType
 import androidx.compose.ui.unit.dp
 import androidx.core.content.ContextCompat
 import io.unom.punktfunk.kit.VideoDecoders
+import io.unom.punktfunk.kit.deviceBodyVibrator
 
 /**
  * Stream settings, organised as an iOS-Settings / Android-system-settings style list of category
@@ -414,6 +415,18 @@ private fun ControlsSettings(s: Settings, update: (Settings) -> Unit, onOpenCont
             subtitle = "What the app detects, with a live input test",
             onClick = onOpenControllers,
         )
+        // Only where the device has a body vibrator to mirror onto (a TV box doesn't).
+        val context = LocalContext.current
+        val hasBodyVibrator = remember { deviceBodyVibrator(context) != null }
+        if (hasBodyVibrator) {
+            ToggleRow(
+                title = "Rumble on this phone",
+                subtitle = "Also play controller 1's rumble on this phone's own vibration " +
+                    "motor — for clip-on pads without rumble motors",
+                checked = s.rumbleOnPhone,
+                onCheckedChange = { on -> update(s.copy(rumbleOnPhone = on)) },
+            )
+        }
     }
 }
 

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

@@ -6,15 +6,22 @@ import android.content.pm.ActivityInfo
 import android.content.pm.PackageManager
 import android.net.wifi.WifiManager
 import android.os.Build
+import android.text.InputType
 import android.util.Log
 import android.view.SurfaceHolder
 import android.view.SurfaceView
+import android.view.View
 import android.view.WindowManager
+import android.view.inputmethod.BaseInputConnection
+import android.view.inputmethod.EditorInfo
+import android.view.inputmethod.InputConnection
+import android.view.inputmethod.InputMethodManager
 import android.widget.Toast
 import androidx.activity.compose.BackHandler
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.LaunchedEffect
@@ -32,8 +39,9 @@ import androidx.core.content.ContextCompat
 import androidx.core.view.WindowCompat
 import androidx.core.view.WindowInsetsCompat
 import androidx.core.view.WindowInsetsControllerCompat
-import io.unom.punktfunk.kit.Gamepad
 import io.unom.punktfunk.kit.GamepadFeedback
+import io.unom.punktfunk.kit.GamepadRouter
+import io.unom.punktfunk.kit.deviceBodyVibrator
 import io.unom.punktfunk.kit.NativeBridge
 import io.unom.punktfunk.kit.VideoDecoders
 import java.util.concurrent.atomic.AtomicBoolean
@@ -166,6 +174,12 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
             it.systemBarsBehavior = WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE
             it.hide(WindowInsetsCompat.Type.systemBars())
         }
+        // The soft keyboard (three-finger swipe up → KeyCaptureView below) must OVERLAY the
+        // stream, never pan/resize it — the video is a fixed-mode surface, not a document.
+        // Scoped to the stream; the app's other screens keep the default for their text fields.
+        val priorSoftInput = window?.attributes?.softInputMode
+            ?: WindowManager.LayoutParams.SOFT_INPUT_ADJUST_UNSPECIFIED
+        window?.setSoftInputMode(WindowManager.LayoutParams.SOFT_INPUT_ADJUST_NOTHING)
         // Lock to landscape while streaming — the host streams a landscape desktop, so pin the device
         // there (either landscape direction is fine) and stop it rotating to portrait mid-session. The
         // activity declares configChanges=orientation, so this re-lays out the surface in place without
@@ -174,21 +188,40 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
         val priorOrientation = activity?.requestedOrientation
         activity?.requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE
         activity?.streamHandle = handle // route hardware keys to this session
-        activity?.axisMapper = Gamepad.AxisMapper(handle) // route joystick axes
+        // Multi-controller router: a stable wire pad index per connected controller, per-device axis
+        // state, Arrival/Remove on hot-plug, and feedback routed back by pad index. Forwards every
+        // controller (Automatic). Built here, released on dispose.
+        val router = GamepadRouter(context, handle, initialSettings.gamepad)
+        activity?.gamepadRouter = router
         // Select+Start+L1+R1 chord leaves the stream — a deliberate quit (signal it so the host skips
-        // the keep-alive linger), unlike a host-ended / backgrounded drop.
+        // the keep-alive linger), unlike a host-ended / backgrounded drop. The router debounces it
+        // (must be held ~1.5 s) and fires onExitChord on its main-thread timer, so leave the stream
+        // the same way the Back gesture does.
         activity?.requestStreamExit = { NativeBridge.nativeDisconnectQuit(handle); onDisconnect() }
+        router.onExitChord = { activity?.requestStreamExit?.invoke() }
         activity?.setConsoleHighRefreshRate(false) // let the decoder's setFrameRate pick the panel rate
-        // Host→client feedback (rumble + DualSense lightbar/LEDs); poll threads stopped before close.
-        val feedback = GamepadFeedback(handle).also { it.start() }
+        // Host→client feedback (rumble + DualSense lightbar/LEDs), routed to each controller by pad
+        // index via the router; poll threads stopped + joined before the router is released and the
+        // session closed. "Rumble on this phone" (opt-in) additionally mirrors controller 1's
+        // rumble onto the device's own vibrator — for clip-on pads without rumble motors.
+        val feedback = GamepadFeedback(
+            handle,
+            router,
+            deviceVibrator = if (initialSettings.rumbleOnPhone) deviceBodyVibrator(context) else null,
+        ).also { it.start() }
+        // Free a disconnected controller's rumble/lights bindings promptly (else the open lights
+        // session leaks until the session ends). The router owns hot-plug; the feedback owns the binds.
+        router.onSlotClosed = feedback::onDeviceRemoved
         onDispose {
             closed.set(true) // from here the handle gets freed; surfaceDestroyed must not touch it
-            feedback.stop() // stop + join the poll threads BEFORE nativeClose frees the handle
-            activity?.axisMapper?.reset() // release-all so nothing sticks on the host
-            activity?.axisMapper = null
+            feedback.stop() // stop + join the poll threads BEFORE the router is released / handle freed
+            router.release() // flush every slot (nothing sticks host-side) + drop the hot-plug listener
+            activity?.gamepadRouter = null
             activity?.streamHandle = 0L
             activity?.requestStreamExit = null
             activity?.setConsoleHighRefreshRate(true) // back to the console UI's max refresh
+            controller?.hide(WindowInsetsCompat.Type.ime()) // drop any keyboard left showing
+            window?.setSoftInputMode(priorSoftInput)
             controller?.show(WindowInsetsCompat.Type.systemBars())
             window?.clearFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
             if (lowLatencyMode && Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
@@ -209,6 +242,9 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
     // Back gesture = a deliberate exit → signal the quit so the host tears down now (no linger).
     BackHandler { NativeBridge.nativeDisconnectQuit(handle); onDisconnect() }
 
+    // Focus anchor the three-finger keyboard swipe summons the IME onto (see KeyCaptureView).
+    var keyCapture by remember { mutableStateOf<KeyCaptureView?>(null) }
+
     Box(modifier = Modifier.fillMaxSize()) {
         AndroidView(
             modifier = Modifier.fillMaxSize(),
@@ -259,8 +295,16 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
                 StatsOverlay(it, statsVerbosity, decoderLabel, Modifier.align(Alignment.TopStart).padding(12.dp))
             }
         }
+        // Invisible 1-px focus anchor for the host-typing soft keyboard (three-finger swipe
+        // up in the mouse modes) — it never draws or takes touches, it just owns IME focus.
+        AndroidView(
+            modifier = Modifier.size(1.dp),
+            factory = { ctx -> KeyCaptureView(ctx).also { keyCapture = it } },
+        )
         // Touch input per the Settings model: trackpad/direct-pointer mouse (the shared gesture
-        // vocabulary) or real multi-touch passthrough — see TouchInput.kt.
+        // vocabulary) or real multi-touch passthrough — see TouchInput.kt. Passthrough gets no
+        // keyboard gesture: its fingers belong to the host verbatim (a swipe there may BE a
+        // host-OS gesture), so intercepting three fingers would corrupt real multi-touch.
         Box(
             Modifier.fillMaxSize().pointerInput(handle, touchMode) {
                 when (touchMode) {
@@ -269,9 +313,45 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
                         handle,
                         trackpad = touchMode == TouchMode.TRACKPAD,
                         onCycleStats = { statsVerbosity = statsVerbosity.next() },
+                        onKeyboard = { show -> keyCapture?.setImeVisible(show) },
                     )
                 }
             },
         )
     }
 }
+
+/**
+ * Invisible focus anchor for typing on the host: the three-finger swipe summons the device IME
+ * onto this view. `TYPE_NULL` puts the IME in "dumb keyboard" mode — it delivers raw [KeyEvent]s
+ * (no composing text, no autocorrect), which flow through `MainActivity.dispatchKeyEvent` →
+ * `Keymap.toVk` → the host, the exact path a hardware keyboard takes. Text an IME insists on
+ * committing instead still arrives: the non-editable [BaseInputConnection] synthesizes KeyEvents
+ * for it via `KeyCharacterMap` (with Shift carried as meta state — see the IME-shift wrap in
+ * `MainActivity.dispatchKeyEvent`).
+ */
+private class KeyCaptureView(context: Context) : View(context) {
+    init {
+        isFocusable = true
+        isFocusableInTouchMode = true
+    }
+
+    override fun onCheckIsTextEditor(): Boolean = true
+
+    override fun onCreateInputConnection(outAttrs: EditorInfo): InputConnection {
+        outAttrs.inputType = InputType.TYPE_NULL
+        outAttrs.imeOptions = EditorInfo.IME_FLAG_NO_EXTRACT_UI or EditorInfo.IME_FLAG_NO_FULLSCREEN
+        return BaseInputConnection(this, false)
+    }
+
+    fun setImeVisible(show: Boolean) {
+        val imm = context.getSystemService(Context.INPUT_METHOD_SERVICE) as? InputMethodManager
+            ?: return
+        if (show) {
+            requestFocus()
+            imm.showSoftInput(this, 0)
+        } else {
+            imm.hideSoftInputFromWindow(windowToken, 0)
+        }
+    }
+}

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

@@ -19,6 +19,10 @@ private const val TAP_SLOP = 12f
 private const val TAP_DRAG_MS = 250L
 private const val SCROLL_DIV = 4f
 
+// Three-finger vertical swipe: the fraction of the view height the centroid must travel to
+// summon (up) / dismiss (down) the local soft keyboard.
+private const val KB_SWIPE_FRACTION = 0.10f
+
 // Trackpad-mode pointer ballistics (relative one-finger motion). POINTER_SENS: base finger-px →
 // host-px gain (~1:1, never twitchy). The rest is mild acceleration so a flick crosses the screen
 // while a slow drag stays precise: above ACCEL_SPEED_FLOOR px/ms the gain ramps by ACCEL_GAIN per
@@ -40,7 +44,9 @@ private const val ACCEL_MAX = 3.0f
  *
  * Both share the same gesture vocabulary: tap = left click; two-finger tap = right click;
  * two-finger drag = scroll; tap-then-press-and-drag = left-drag (text selection / moving
- * windows); three-finger tap = [onCycleStats] (cycle the stats-HUD verbosity tier).
+ * windows); three-finger tap = [onCycleStats] (cycle the stats-HUD verbosity tier);
+ * three-finger swipe up/down = [onKeyboard] (summon/dismiss the local soft keyboard, for
+ * typing on the host).
  */
 /**
  * Real multi-touch passthrough ([TouchMode.TOUCH]): every finger forwards as a host touchscreen
@@ -94,6 +100,7 @@ internal suspend fun PointerInputScope.streamTouchInput(
     handle: Long,
     trackpad: Boolean,
     onCycleStats: () -> Unit,
+    onKeyboard: (show: Boolean) -> Unit,
 ) {
     var lastTapUp = 0L
     var lastTapX = 0f
@@ -128,6 +135,12 @@ internal suspend fun PointerInputScope.streamTouchInput(
         var maxFingers = 1
         var scrolling = false
         var scrollCount = 0 // pointer count the scroll centroid is anchored at
+        // Keyboard-swipe state: the 3+-finger centroid anchor (per finger count, like the
+        // scroll anchor) and a once-per-gesture latch.
+        var kbCount = 0
+        var kbAnchorX = 0f
+        var kbAnchorY = 0f
+        var kbFired = false
         var prevCx = startX
         var prevCy = startY
         var upTime = down.uptimeMillis
@@ -148,9 +161,12 @@ internal suspend fun PointerInputScope.streamTouchInput(
                 break
             }
             if (pressed.size > maxFingers) maxFingers = pressed.size
+            // Dropping below three fingers forgets the keyboard-swipe anchor, so a 3→2→3
+            // bounce re-anchors instead of reading the count change as swipe travel.
+            if (pressed.size < 3) kbCount = 0
 
-            if (pressed.size >= 2) {
-                // Two+ fingers → scroll by the centroid delta; never move the cursor.
+            if (pressed.size == 2) {
+                // Two fingers → scroll by the centroid delta; never move the cursor.
                 val cx = (pressed.sumOf { it.position.x.toDouble() } / pressed.size).toFloat()
                 val cy = (pressed.sumOf { it.position.y.toDouble() } / pressed.size).toFloat()
                 // (Re-)anchor whenever the finger COUNT changes, not just on scroll start: the
@@ -177,6 +193,36 @@ internal suspend fun PointerInputScope.streamTouchInput(
                     prevCx = cx
                     moved = true
                 }
+            } else if (pressed.size >= 3) {
+                // Three+ fingers → the keyboard swipe, never scroll (the documented
+                // vocabulary is TWO-finger scroll; 3+ only fell into the scroll path as an
+                // accident of its old `>= 2` bound). Anchor the centroid per finger count
+                // (same reasoning as the scroll anchor above) and fire once per gesture when
+                // the vertical travel crosses the threshold: up = show, down = hide.
+                val cx = (pressed.sumOf { it.position.x.toDouble() } / pressed.size).toFloat()
+                val cy = (pressed.sumOf { it.position.y.toDouble() } / pressed.size).toFloat()
+                if (pressed.size != kbCount) {
+                    kbCount = pressed.size
+                    kbAnchorX = cx
+                    kbAnchorY = cy
+                } else {
+                    val dy = cy - kbAnchorY
+                    // Real centroid travel disqualifies the tap classification below (else a
+                    // sub-threshold swipe would still fire the three-finger stats tap).
+                    if (abs(dy) > TAP_SLOP || abs(cx - kbAnchorX) > TAP_SLOP) moved = true
+                    if (!kbFired && abs(dy) >= size.height * KB_SWIPE_FRACTION) {
+                        kbFired = true
+                        onKeyboard(dy < 0) // finger up → show, finger down → hide
+                    }
+                }
+                // Leaving the scroll state stale would read the 3→2 centroid jump as a wheel
+                // notch; clearing it makes a return to two fingers re-anchor fresh. Same for
+                // the trackpad's tracked finger: its prev position froze while 3+ fingers were
+                // down, so dropping straight back to one finger must re-anchor (zero delta),
+                // not replay the whole 3-finger phase as one cursor jump.
+                scrolling = false
+                scrollCount = 0
+                trackId = PointerId(Long.MIN_VALUE)
             } else if (!scrolling) {
                 // One finger (skipped once a gesture turned into a scroll, so dropping
                 // back to one finger doesn't jerk the cursor).

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

@@ -26,7 +26,7 @@ import kotlinx.coroutines.launch
  * [isOnline]/[onOnline] callbacks all run on the main thread; only the blocking send is off-loaded.
  */
 class WakeController(private val scope: CoroutineScope) {
-    /** null = idle; non-null drives [WakeOverlay]. */
+    /** null = idle; non-null drives the "Waking…" phase of [ConnectOverlay]. */
     data class Waking(
         val hostName: String,
         /** Whether coming online chains into a connect (Wake & Connect) vs. just stopping. */

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

@@ -1,124 +0,0 @@
-package io.unom.punktfunk
-
-import androidx.activity.compose.BackHandler
-import androidx.compose.foundation.background
-import androidx.compose.foundation.border
-import androidx.compose.foundation.clickable
-import androidx.compose.foundation.interaction.MutableInteractionSource
-import androidx.compose.foundation.layout.Arrangement
-import androidx.compose.foundation.layout.Box
-import androidx.compose.foundation.layout.Column
-import androidx.compose.foundation.layout.Row
-import androidx.compose.foundation.layout.fillMaxSize
-import androidx.compose.foundation.layout.padding
-import androidx.compose.foundation.layout.size
-import androidx.compose.foundation.layout.widthIn
-import androidx.compose.foundation.shape.RoundedCornerShape
-import androidx.compose.material.icons.Icons
-import androidx.compose.material.icons.filled.Bedtime
-import androidx.compose.material3.Button
-import androidx.compose.material3.CircularProgressIndicator
-import androidx.compose.material3.Icon
-import androidx.compose.material3.OutlinedButton
-import androidx.compose.material3.Text
-import androidx.compose.runtime.Composable
-import androidx.compose.runtime.remember
-import androidx.compose.ui.Alignment
-import androidx.compose.ui.Modifier
-import androidx.compose.ui.draw.clip
-import androidx.compose.ui.graphics.Color
-import androidx.compose.ui.text.font.FontFamily
-import androidx.compose.ui.text.font.FontWeight
-import androidx.compose.ui.text.style.TextAlign
-import androidx.compose.ui.unit.dp
-import androidx.compose.ui.unit.sp
-
-/**
- * The "Waking <host>…" modal shown while [WakeController] brings a sleeping host back — a spinner + a
- * live elapsed counter, escalating to a retry/cancel prompt on timeout. The Android mirror of the
- * Apple client's `WakeOverlay`. Rendered over BOTH the touch grid and the console home; it swallows
- * input to the screen behind it, and in console mode the pad drives it (B cancels, A retries once
- * timed out) while the touch buttons work for a pointer.
- */
-@Composable
-fun WakeOverlay(waker: WakeController, gamepadUi: Boolean) {
-    val w = waker.waking ?: return
-
-    BackHandler { waker.cancel() } // system Back / pad B (remapped) cancels the wait
-    if (gamepadUi) {
-        // A retries once timed out; B falls through to the BackHandler above.
-        GamepadNavEffect2D(
-            active = true,
-            onDirection = {},
-            onActivate = { if (w.timedOut) waker.retry() },
-        )
-    }
-
-    Box(
-        Modifier
-            .fillMaxSize()
-            .background(Color.Black.copy(alpha = 0.6f))
-            // Swallow taps so the home behind can't be touched while waking.
-            .clickable(interactionSource = remember { MutableInteractionSource() }, indication = null) {},
-        contentAlignment = Alignment.Center,
-    ) {
-        Column(
-            Modifier
-                .padding(40.dp)
-                .widthIn(max = 380.dp)
-                .clip(RoundedCornerShape(22.dp))
-                .background(Color(0xF01A1730))
-                .border(1.dp, Color.White.copy(alpha = 0.12f), RoundedCornerShape(22.dp))
-                .padding(28.dp),
-            horizontalAlignment = Alignment.CenterHorizontally,
-            verticalArrangement = Arrangement.spacedBy(14.dp),
-        ) {
-            if (w.timedOut) {
-                Icon(
-                    Icons.Filled.Bedtime,
-                    contentDescription = null,
-                    tint = Color.White.copy(alpha = 0.85f),
-                    modifier = Modifier.size(34.dp),
-                )
-                Text(
-                    "${w.hostName} didn't wake",
-                    color = Color.White,
-                    fontWeight = FontWeight.Bold,
-                    fontSize = 19.sp,
-                    textAlign = TextAlign.Center,
-                )
-                Text(
-                    "It may still be booting, or it's powered off / off this network.",
-                    color = Color.White.copy(alpha = 0.6f),
-                    fontSize = 13.sp,
-                    textAlign = TextAlign.Center,
-                )
-                Row(
-                    horizontalArrangement = Arrangement.spacedBy(12.dp),
-                    modifier = Modifier.padding(top = 6.dp),
-                ) {
-                    OutlinedButton(onClick = { waker.cancel() }) { Text("Cancel") }
-                    Button(onClick = { waker.retry() }) { Text("Try Again") }
-                }
-            } else {
-                CircularProgressIndicator(color = Color.White)
-                Text(
-                    "Waking ${w.hostName}…",
-                    color = Color.White,
-                    fontWeight = FontWeight.Bold,
-                    fontSize = 19.sp,
-                    textAlign = TextAlign.Center,
-                )
-                Text(
-                    "Waiting for it to come online · ${w.seconds}s",
-                    color = Color.White.copy(alpha = 0.6f),
-                    fontSize = 13.sp,
-                    fontFamily = FontFamily.Monospace,
-                )
-                OutlinedButton(onClick = { waker.cancel() }, modifier = Modifier.padding(top = 6.dp)) {
-                    Text(if (w.connectsAfter) "Cancel" else "Stop Waiting")
-                }
-            }
-        }
-    }
-}

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

@@ -68,6 +68,29 @@ class ScreenshotTest {
     @Config(sdk = [36], qualifiers = "w800dp-h360dp-xxhdpi")
     fun streamNormal() = shootRoot("stream-normal") { StreamScene(io.unom.punktfunk.StatsVerbosity.NORMAL) }
 
+    // The touch flow is a Material dialog over the host grid (a separate window → shootScreen).
+    @Test
+    fun connecting() = shootScreen("connecting") {
+        HostsScene()
+        ConnectingScene()
+    }
+
+    @Test
+    fun waking() = shootScreen("waking") {
+        HostsScene()
+        WakingScene()
+    }
+
+    @Test
+    fun wakeTimedOut() = shootScreen("wake-timed-out") {
+        HostsScene()
+        WakeTimedOutScene()
+    }
+
+    // The console flow is the full-screen aurora takeover (a root capture).
+    @Test
+    fun connectingConsole() = shootRoot("connecting-console") { ConnectConsoleScene() }
+
     @Test
     fun trust() = shootScreen("trust") {
         HostsScene()

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

@@ -26,6 +26,9 @@ import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.text.style.TextAlign
 import androidx.compose.ui.unit.dp
 import io.unom.punktfunk.BrandDark
+import io.unom.punktfunk.ConnectModal
+import io.unom.punktfunk.ConnectPhase
+import io.unom.punktfunk.ConnectTakeover
 import io.unom.punktfunk.Settings
 import io.unom.punktfunk.TouchMode
 import io.unom.punktfunk.SettingsScreen
@@ -215,3 +218,31 @@ internal fun StreamScene(verbosity: StatsVerbosity = StatsVerbosity.DETAILED) {
         )
     }
 }
+
+/**
+ * The default-UI connect flow (the real [ConnectModal]) in each phase — instant "Connecting…"
+ * feedback, the "Waking…" wait, and the wake-timed-out prompt. These render as a Material dialog over
+ * the host grid, so the test composes [HostsScene] behind them and captures the whole screen.
+ */
+@Composable
+internal fun ConnectingScene() =
+    ConnectModal(ConnectPhase.Connecting("Living Room PC"), onCancel = {}, onRetry = {})
+
+@Composable
+internal fun WakingScene() =
+    ConnectModal(
+        ConnectPhase.Waking("Living Room PC", seconds = 12, connectsAfter = true),
+        onCancel = {}, onRetry = {},
+    )
+
+@Composable
+internal fun WakeTimedOutScene() =
+    ConnectModal(ConnectPhase.WakeTimedOut("Living Room PC"), onCancel = {}, onRetry = {})
+
+/**
+ * The console / gamepad connect flow (the real full-screen [ConnectTakeover]) — the aurora backdrop
+ * with a bottom hint bar, the same signature look the console home uses.
+ */
+@Composable
+internal fun ConnectConsoleScene() =
+    ConnectTakeover(ConnectPhase.Connecting("Living Room PC"), onCancel = {}, onRetry = {})

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

@@ -52,6 +52,8 @@ object Gamepad {
     const val PREF_DUALSHOCK4 = 4
     const val PREF_STEAMCONTROLLER = 5
     const val PREF_STEAMDECK = 6
+    const val PREF_DUALSENSEEDGE = 7
+    const val PREF_SWITCHPRO = 8
 
     // USB vendor ids of the controllers we can identify by VID/PID.
     private const val VID_SONY = 0x054C
@@ -59,10 +61,19 @@ object Gamepad {
     private const val VID_VALVE = 0x28DE
     private const val VID_NINTENDO = 0x057E
 
-    // Sony product ids. DualSense (PS5) and DualShock 4 (PS4) map to distinct host pad types.
-    private val PID_DUALSENSE = setOf(0x0CE6, 0x0DF2)
+    // Sony product ids. DualSense (PS5), DualSense Edge, and DualShock 4 (PS4) map to distinct
+    // host pad types — the Edge's back paddles get native slots on the virtual Edge (Android
+    // forwards no paddle input yet, but the identity + rich planes match the physical pad).
+    private val PID_DUALSENSE = setOf(0x0CE6)
+    private val PID_DUALSENSEEDGE = setOf(0x0DF2)
     private val PID_DUALSHOCK4 = setOf(0x05C4, 0x09CC)
 
+    // Nintendo: Switch Pro Controller — the host builds the virtual hid-nintendo pad (correct
+    // glyphs + positional layout). The Switch 2 Pro Controller (0x2069) and a Joy-Con 2 pair
+    // (0x2068) are the same full pad surface and ride the same virtual pad (SDL folds them to
+    // its NINTENDO_SWITCH_PRO type too).
+    private val PID_SWITCHPRO = setOf(0x2009, 0x2069, 0x2068)
+
     // Valve: Steam Deck built-in controller (0x1205); classic Steam Controller wired (0x1102) /
     // dongle (0x1142). The host builds the virtual hid-steam pad; rich-input capture (paddles /
     // trackpads / gyro) is out of scope on Android (no rich-input plane yet), so only the standard
@@ -91,10 +102,12 @@ object Gamepad {
         val pid = dev.productId
         return when {
             vid == VID_SONY && pid in PID_DUALSENSE -> PREF_DUALSENSE
+            vid == VID_SONY && pid in PID_DUALSENSEEDGE -> PREF_DUALSENSEEDGE
             vid == VID_SONY && pid in PID_DUALSHOCK4 -> PREF_DUALSHOCK4
             vid == VID_MICROSOFT && pid in PID_XBOXONE -> PREF_XBOXONE
             vid == VID_VALVE && pid in PID_STEAMDECK -> PREF_STEAMDECK
             vid == VID_VALVE && pid in PID_STEAMCONTROLLER -> PREF_STEAMCONTROLLER
+            vid == VID_NINTENDO && pid in PID_SWITCHPRO -> PREF_SWITCHPRO
             else -> PREF_XBOX360
         }
     }
@@ -171,47 +184,26 @@ object Gamepad {
     }
 
     /**
-     * Maps joystick MotionEvents to axis (+ HAT→dpad) sends for one session, **on change only**.
-     * Holds the previous axis/hat state so an unchanged frame emits nothing. One instance per
-     * session; call [reset] on release-all (focus loss / disconnect / session stop) so nothing
-     * sticks on the host (which has no client-side held-state knowledge).
+     * Maps one controller's joystick MotionEvents to axis (+ HAT→dpad) sends on wire pad index [pad],
+     * **on change only**. Holds the previous axis/hat state so an unchanged frame emits nothing. One
+     * instance per forwarded controller (owned by [GamepadRouter], which routes each device's events
+     * to its own mapper so a second pad can't clobber the first); call [reset] on that slot closing
+     * (disconnect / session stop) so nothing sticks on the host (which has no client-side held-state
+     * knowledge).
      *
-     * Single-source: only ONE qualifying controller feeds pad 0. Events must come from a device
-     * whose source classes include GAMEPAD (see [onMotion]) and the mapper pins itself to the
-     * first such device — a controller's joystick-classified sibling nodes (DualSense/DS4 motion
-     * sensors) and any second pad report every axis as 0, and folding them into the same state
-     * flapped a held trigger/stick between its value and 0 on every event interleave.
+     * The router only ever feeds this a qualifying event from the mapper's own device — a real
+     * gamepad (its source classes include GAMEPAD), never a controller's joystick-classified sibling
+     * node (DualSense/DS4 motion sensors), which reports every pad axis as 0. [onMotion] therefore
+     * folds the event straight in without re-qualifying it.
      */
-    class AxisMapper(private val handle: Long) {
+    class AxisMapper(private val handle: Long, private val pad: Int) {
         // Sentinel so the first real value (incl. 0) always sends once after attach (Linux parity).
         private val last = IntArray(6) { Int.MIN_VALUE }
         private var hatX = 0 // -1 / 0 / +1
         private var hatY = 0
 
-        /** deviceId of the controller pad 0 is pinned to; −1 until the first qualifying event. */
-        private var deviceId = -1
-
-        /** Returns true if this was a joystick ACTION_MOVE we consumed. */
-        fun onMotion(event: MotionEvent): Boolean {
-            if (!event.isFromSource(InputDevice.SOURCE_JOYSTICK)) return false
-            if (event.actionMasked != MotionEvent.ACTION_MOVE) return false
-            // Only a true gamepad drives pad 0. A joystick ACTION_MOVE's own source is plain
-            // JOYSTICK for every sender, so qualify by the DEVICE's source classes: a real pad
-            // carries the GAMEPAD (button) class too, its sensor/touchpad sibling nodes and
-            // joystick-class remotes don't — and those report every pad axis as 0 (see the
-            // class doc for the held-trigger flap this caused).
-            val dev = event.device ?: return false
-            if (dev.sources and InputDevice.SOURCE_GAMEPAD != InputDevice.SOURCE_GAMEPAD) return false
-            // Single-pad model: pin to the first qualifying controller so a second pad (or its
-            // stick drift) can't fight pad 0; re-adopt only once the pinned device is gone.
-            if (deviceId != event.deviceId) {
-                if (deviceId != -1) {
-                    if (InputDevice.getDevice(deviceId) != null) return false
-                    reset() // the pinned pad is gone — lift its held state before adopting
-                }
-                deviceId = event.deviceId
-            }
-
+        /** Fold one joystick ACTION_MOVE from this mapper's controller onto its pad index. */
+        fun onMotion(event: MotionEvent) {
             // Sticks: Android floats −1..1, +y = down → ±32767, negate Y for the wire's +y = up.
             sendAxis(AXIS_LS_X, stick(event.getAxisValue(MotionEvent.AXIS_X)))
             sendAxis(AXIS_LS_Y, stick(-event.getAxisValue(MotionEvent.AXIS_Y)))
@@ -240,23 +232,39 @@ object Gamepad {
                 ),
             )
 
-            // HAT → dpad button transitions (track previous, emit only the deltas).
-            val hx = sign(event.getAxisValue(MotionEvent.AXIS_HAT_X))
+            // HAT → dpad button transitions. Android BATCHES joystick ACTION_MOVEs, so a rapid d-pad
+            // tap (press+release inside one batch window) lives only in the historical samples — the
+            // final getAxisValue would show the HAT already back at rest and miss the tap entirely.
+            // Feed every historical HAT sample (oldest→newest) through the same transition logic
+            // before the current one, so each edge is emitted. (Sticks/triggers stay latest-wins:
+            // only the final value matters for an analog axis.)
+            for (h in 0 until event.historySize) {
+                applyHat(
+                    sign(event.getHistoricalAxisValue(MotionEvent.AXIS_HAT_X, h)),
+                    sign(event.getHistoricalAxisValue(MotionEvent.AXIS_HAT_Y, h)),
+                )
+            }
+            applyHat(
+                sign(event.getAxisValue(MotionEvent.AXIS_HAT_X)),
+                sign(event.getAxisValue(MotionEvent.AXIS_HAT_Y)),
+            )
+        }
+
+        /** Emit dpad button deltas for one HAT sample (`hx`/`hy` each −1/0/+1), tracking held state. */
+        private fun applyHat(hx: Int, hy: Int) {
             if (hx != hatX) {
                 if (hatX < 0) btn(BTN_DPAD_LEFT, false) else if (hatX > 0) btn(BTN_DPAD_RIGHT, false)
                 if (hx < 0) btn(BTN_DPAD_LEFT, true) else if (hx > 0) btn(BTN_DPAD_RIGHT, true)
                 hatX = hx
             }
-            val hy = sign(event.getAxisValue(MotionEvent.AXIS_HAT_Y))
             if (hy != hatY) {
                 if (hatY < 0) btn(BTN_DPAD_UP, false) else if (hatY > 0) btn(BTN_DPAD_DOWN, false)
                 if (hy < 0) btn(BTN_DPAD_UP, true) else if (hy > 0) btn(BTN_DPAD_DOWN, true)
                 hatY = hy
             }
-            return true
         }
 
-        /** Release-all: zero every axis and clear the held dpad. */
+        /** Release-all: zero every axis and clear the held dpad (all on this mapper's pad index). */
         fun reset() {
             for (id in 0..5) sendAxis(id, 0)
             if (hatX < 0) btn(BTN_DPAD_LEFT, false) else if (hatX > 0) btn(BTN_DPAD_RIGHT, false)
@@ -268,10 +276,10 @@ object Gamepad {
         private fun sendAxis(id: Int, v: Int) {
             if (last[id] == v) return
             last[id] = v
-            NativeBridge.nativeSendGamepadAxis(handle, id, v)
+            NativeBridge.nativeSendGamepadAxis(handle, id, v, pad)
         }
 
-        private fun btn(bit: Int, down: Boolean) = NativeBridge.nativeSendGamepadButton(handle, bit, down)
+        private fun btn(bit: Int, down: Boolean) = NativeBridge.nativeSendGamepadButton(handle, bit, down, pad)
 
         // −1..1 float → ±32767 i16 (matches the Apple client's 32767 scale).
         private fun stick(v: Float): Int = (v.coerceIn(-1f, 1f) * 32767f).toInt()

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

@@ -1,5 +1,6 @@
 package io.unom.punktfunk.kit
 
+import android.content.Context
 import android.graphics.Color
 import android.hardware.lights.Light
 import android.hardware.lights.LightState
@@ -15,21 +16,36 @@ import android.view.InputDevice
 import java.nio.ByteBuffer
 
 /**
- * Host→client gamepad feedback for one session (single-pad model — pad 0 only). Two daemon poll
- * threads drain the blocking native pulls and render in Kotlin: rumble → the controller's
- * `VibratorManager` (API 31+) or its single legacy `Vibrator` on API 28–30; HID-output → lightbar /
- * player-LED via `LightsManager` (API 33+); adaptive
- * triggers are parse-validated and logged (Android has no public adaptive-trigger API).
+ * Host→client gamepad feedback for one session, routed per controller by wire pad index. Two daemon
+ * poll threads drain the blocking native pulls and render in Kotlin: rumble → the addressed
+ * controller's `VibratorManager` (API 31+) or its single legacy `Vibrator` on API 28–30; HID-output
+ * → that controller's lightbar / player-LED via `LightsManager` (API 33+); adaptive triggers are
+ * parse-validated and logged (Android has no public adaptive-trigger API).
+ *
+ * Each pull carries the wire pad index it is addressed to; [GamepadRouter.deviceForPad] resolves it
+ * to the physical controller currently holding that index — so a rumble the host aimed at pad 1
+ * drives pad 1's motors, and an update for an index with no live controller (a pad that just
+ * unplugged) is dropped. Per-controller rumble/light bindings are built lazily and cached by device
+ * id (bounded — at most 16 pads).
  *
  * Mirrors `nativeStartAudio`'s lifecycle: [start]/[stop] driven by the StreamScreen. [stop] flips a
  * flag; the ~100 ms native pull timeout lets the threads exit, then they're joined (bounded) — and
- * this MUST run before `nativeClose` frees the session handle.
+ * this MUST run before the router is released and `nativeClose` frees the session handle.
  *
- * The active pad is resolved from the connected input devices (first gamepad/joystick). With none
- * connected (emulator) rumble/lights become logged no-ops — exactly the verification path; the
- * `Log.i` receipt lines fire regardless of rendering hardware.
+ * With no controller connected (emulator) rumble/lights become logged no-ops — exactly the
+ * verification path; the `Log.i` receipt lines fire regardless of rendering hardware.
+ *
+ * [deviceVibrator] is the opt-in phone mirror ("Rumble on this phone", off by default): when
+ * non-null, rumble the host addresses to wire pad 0 (controller 1) is ALSO played on this
+ * device's own vibration motor — for clip-on gamepads that ship without rumble motors, where the
+ * phone body is the only actuator in the player's hands. StreamScreen passes it only when the
+ * setting is on (see [deviceBodyVibrator]).
  */
-class GamepadFeedback(private val handle: Long) {
+class GamepadFeedback(
+    private val handle: Long,
+    private val router: GamepadRouter?,
+    private val deviceVibrator: Vibrator? = null,
+) {
     private companion object {
         const val TAG = "pf.feedback"
         const val TAG_LED: Byte = 0x01
@@ -40,42 +56,54 @@ class GamepadFeedback(private val handle: Long) {
         const val LEGACY_RUMBLE_MS = 60_000L
     }
 
+    /** One controller's rumble binding — VibratorManager (API 31+) OR the legacy single Vibrator (API 28–30). */
+    private class RumbleBind(
+        val vm: VibratorManager?,
+        val legacy: Vibrator?,
+        val ids: IntArray,
+        val amplitudeControlled: Boolean,
+    )
+
+    /** One controller's lights binding (API 33+): its open session + the RGB / player-id lights it exposes. */
+    private class LightBind(
+        val session: LightsManager.LightsSession,
+        val rgb: Light?,
+        val player: Light?,
+    )
+
     @Volatile private var running = false
     private var rumbleThread: Thread? = null
     private var hidoutThread: Thread? = null
 
-    private var vm: VibratorManager? = null
-    // API 28–30 fallback: the controller's single legacy Vibrator (no per-motor VibratorManager
-    // until API 31). Exactly one of [vm] / [legacy] is bound; rumble degrades to one blended motor.
-    private var legacy: Vibrator? = null
-    private var vibratorIds: IntArray = IntArray(0)
-    private var amplitudeControlled = false
-
-    private var lightsSession: LightsManager.LightsSession? = null
-    private var rgbLight: Light? = null
-    private var playerLight: Light? = null
+    // Per-controller bindings, keyed by device id, built lazily. rumbleBinds is written by the rumble
+    // thread and lightBinds by the hidout thread while running; [onDeviceRemoved] also evicts+closes
+    // from the MAIN thread on a hot-unplug, and stop() clears both from the main thread after joining
+    // the threads. That main-vs-poll concurrency is why every access goes through `bindsLock` (a plain
+    // HashMap can corrupt under a concurrent structural write, and ConcurrentHashMap can't hold the
+    // null value that caches "this controller has no vibrator / no controllable lights"). The lock
+    // guards only the map ops — rendering runs on the returned reference outside it; a stale reference
+    // is harmless (a closed LightsSession's requestLights and a cancelled Vibrator are runCatching'd
+    // no-ops). A null value caches the negative result so a pad with no hardware isn't re-probed.
+    private val bindsLock = Any()
+    private val rumbleBinds = HashMap<Int, RumbleBind?>()
+    private val lightBinds = HashMap<Int, LightBind?>()
 
     fun start() {
-        val dev = resolvePad()
-        bindRumble(dev)
-        if (Build.VERSION.SDK_INT >= 33) {
-            bindLights(dev)
-        } else {
-            Log.i(TAG, "lights need API 33 (have ${Build.VERSION.SDK_INT}) — lightbar/playerLed no-op")
-        }
-
         running = true
         rumbleThread = Thread({
             while (running) {
                 val ev = NativeBridge.nativeNextRumble(handle)
                 if (ev < 0L) continue // timeout / closed
-                // ev bit 48 = has a v2 lease; bits 32..47 = ttl_ms; 16..31 = low; 0..15 = high. The
-                // lease flag is out-of-band, so any ttl_ms (incl. 0xFFFF) is a real lease — no
-                // in-band sentinel. No lease (legacy host) → the prior long one-shot.
+                // ev bits 49..52 = wire pad index; bit 48 = has a v2 lease; bits 32..47 = ttl_ms;
+                // 16..31 = low; 0..15 = high. The lease flag is out-of-band, so any ttl_ms (incl.
+                // 0xFFFF) is a real lease — no in-band sentinel. No lease (legacy host) → the prior
+                // long one-shot.
+                val pad = ((ev ushr 49) and 0xFL).toInt()
                 val hasLease = ((ev ushr 48) and 0x1L) == 0x1L
                 val ttl = ((ev ushr 32) and 0xFFFF).toInt()
                 val durationMs = if (hasLease) ttl.toLong() else LEGACY_RUMBLE_MS
                 renderRumble(
+                    pad,
                     ((ev ushr 16) and 0xFFFF).toInt(),
                     (ev and 0xFFFF).toInt(),
                     durationMs,
@@ -93,100 +121,136 @@ class GamepadFeedback(private val handle: Long) {
         }, "pf-hidout").apply { isDaemon = true; start() }
     }
 
-    /** Idempotent. Stops + joins the poll threads (must complete before the session handle is freed). */
+    /** Idempotent. Stops + joins the poll threads (must complete before the router is released / handle freed). */
     fun stop() {
         running = false
         rumbleThread?.interrupt()
         hidoutThread?.interrupt()
-        runCatching { vm?.cancel() } // drop any held rumble immediately
-        runCatching { legacy?.cancel() }
         // Join WITHOUT a timeout. These poll threads dereference the native session handle on every
-        // pull (nativeNextRumble/nativeNextHidout), so they MUST be dead before StreamScreen's
-        // onDispose reaches nativeClose, which frees that handle. A *bounded* join that times out
-        // would let a thread survive into the freed handle → use-after-free SIGSEGV (the
-        // back-while-streaming crash, on the one path the main-thread `closed` guard can't cover).
-        // Safe to block unbounded: the native pulls are internally time-bounded (PULL_TIMEOUT ~100 ms)
-        // and rendering is a quick best-effort binder call, so each thread observes running=false and
-        // exits within ~one timeout — the join returns promptly (well under any ANR threshold).
+        // pull (nativeNextRumble/nativeNextHidout) and read the router, so they MUST be dead before
+        // StreamScreen's onDispose reaches router.release() / nativeClose, which free that state. A
+        // *bounded* join that times out would let a thread survive into the freed handle → use-after-
+        // free SIGSEGV (the back-while-streaming crash, on the one path the main-thread `closed` guard
+        // can't cover). Safe to block unbounded: the native pulls are internally time-bounded
+        // (PULL_TIMEOUT ~100 ms) and rendering is a quick best-effort binder call, so each thread
+        // observes running=false and exits within ~one timeout — the join returns promptly.
         runCatching { rumbleThread?.join() }
         runCatching { hidoutThread?.join() }
         rumbleThread = null
         hidoutThread = null
-        runCatching { lightsSession?.close() }
-        lightsSession = null
-        rgbLight = null
-        playerLight = null
-        vm = null
-        legacy = null
-        vibratorIds = IntArray(0)
+        // Threads are dead — drop any held rumble (incl. the phone mirror's) and close every
+        // lights session.
+        runCatching { deviceVibrator?.cancel() }
+        synchronized(bindsLock) {
+            for (b in rumbleBinds.values) b?.let {
+                runCatching { it.vm?.cancel() }
+                runCatching { it.legacy?.cancel() }
+            }
+            for (b in lightBinds.values) b?.let { runCatching { it.session.close() } }
+            rumbleBinds.clear()
+            lightBinds.clear()
+        }
     }
 
-    /** First connected gamepad/joystick InputDevice, or null (→ logged no-op on the emulator). */
-    private fun resolvePad(): InputDevice? = Gamepad.firstPad()
+    /**
+     * Evict and release the bindings for a controller that just disconnected — invoked from
+     * [GamepadRouter]'s slot-close on the main thread (routed via `StreamScreen`). Closes its
+     * `LightsSession` and cancels any held rumble, so a hot-unplug mid-session frees the session
+     * immediately instead of leaking it until [stop]. A no-op for a device with no cached binding.
+     * The next feedback for that pad index rebinds against whatever controller now holds it.
+     */
+    // Same runtime-guarded cleanup as [stop] (VIBRATE is app-declared; the light bind only exists
+    // under the SDK 33 guard) — suppress the module-isolation lint false positives it re-triggers.
+    @Suppress("MissingPermission", "NewApi")
+    fun onDeviceRemoved(deviceId: Int) {
+        synchronized(bindsLock) {
+            rumbleBinds.remove(deviceId)?.let {
+                runCatching { it.vm?.cancel() }
+                runCatching { it.legacy?.cancel() }
+            }
+            lightBinds.remove(deviceId)?.let { runCatching { it.session.close() } }
+        }
+    }
 
     // ---- Rumble ----
 
-    private fun bindRumble(dev: InputDevice?) {
-        if (dev == null) {
-            Log.i(TAG, "rumble: no controller connected — rumble no-op (emulator path)")
-            return
+    /** The rumble binding for the controller on wire pad [pad], or null (no live pad / no vibrator). Cached by device id. */
+    private fun rumbleBindFor(pad: Int): RumbleBind? {
+        val dev = router?.deviceForPad(pad) ?: return null
+        synchronized(bindsLock) {
+            if (rumbleBinds.containsKey(dev.id)) return rumbleBinds[dev.id]
+            val bind = bindRumble(dev)
+            rumbleBinds[dev.id] = bind
+            return bind
         }
+    }
+
+    private fun bindRumble(dev: InputDevice): RumbleBind? {
         if (Build.VERSION.SDK_INT >= 31) {
             val m = dev.vibratorManager
             val ids = m.vibratorIds
             if (ids.isEmpty()) {
                 Log.i(TAG, "rumble: controller '${dev.name}' has no vibrators — rumble no-op")
-                return
+                return null
             }
-            vm = m
-            vibratorIds = ids
-            amplitudeControlled = ids.all { m.getVibrator(it).hasAmplitudeControl() }
-            Log.i(TAG, "rumble: bound ${ids.size} vibrators amplitudeControl=$amplitudeControlled")
-        } else {
-            // API 28–30: no VibratorManager — fall back to the controller's single legacy Vibrator.
-            @Suppress("DEPRECATION")
-            val v = dev.vibrator
-            if (!v.hasVibrator()) {
-                Log.i(TAG, "rumble: controller '${dev.name}' has no vibrator — rumble no-op")
-                return
-            }
-            legacy = v
-            amplitudeControlled = v.hasAmplitudeControl()
-            Log.i(TAG, "rumble: bound legacy vibrator amplitudeControl=$amplitudeControlled")
+            val amp = ids.all { m.getVibrator(it).hasAmplitudeControl() }
+            Log.i(TAG, "rumble: bound ${ids.size} vibrators for '${dev.name}' amplitudeControl=$amp")
+            return RumbleBind(m, null, ids, amp)
         }
+        // API 28–30: no VibratorManager — fall back to the controller's single legacy Vibrator.
+        @Suppress("DEPRECATION")
+        val v = dev.vibrator
+        if (!v.hasVibrator()) {
+            Log.i(TAG, "rumble: controller '${dev.name}' has no vibrator — rumble no-op")
+            return null
+        }
+        Log.i(TAG, "rumble: bound legacy vibrator for '${dev.name}' amplitudeControl=${v.hasAmplitudeControl()}")
+        return RumbleBind(null, v, IntArray(0), v.hasAmplitudeControl())
     }
 
     /**
-     * low = heavy/left motor, high = light/right motor; both 0..0xFFFF (the host's u16 amplitudes).
-     * `durationMs` is the host's v2 envelope TTL — the one-shot self-terminates after it unless the
-     * host renews, so a lost stop (or a dead host) silences at the lease instead of the old fixed
-     * 60 s. Against a legacy host it is [LEGACY_RUMBLE_MS] (the prior fixed duration).
+     * low = heavy/left motor, high = light/right motor; both 0..0xFFFF (the host's u16 amplitudes),
+     * addressed to wire pad [pad]. `durationMs` is the host's v2 envelope TTL — the one-shot self-
+     * terminates after it unless the host renews, so a lost stop (or a dead host) silences at the
+     * lease instead of the old fixed 60 s. Against a legacy host it is [LEGACY_RUMBLE_MS].
      */
-    private fun renderRumble(low: Int, high: Int, durationMs: Long) {
-        Log.i(TAG, "rumble low=$low high=$high ttlMs=$durationMs") // verification line — BEFORE any no-op return
+    private fun renderRumble(pad: Int, low: Int, high: Int, durationMs: Long) {
+        Log.i(TAG, "rumble pad=$pad low=$low high=$high ttlMs=$durationMs") // verification line — BEFORE any no-op return
+        // Opt-in phone mirror, BEFORE the controller-bind early-return: the exact pads this
+        // serves have no vibrator of their own, so their bind below is null. It follows
+        // controller 1 unconditionally rather than only motor-less pads — capability probing
+        // already decided the bind, and the user opted in.
+        if (pad == 0) renderDeviceRumble(low, high, durationMs)
+        val bind = rumbleBindFor(pad) ?: return
         val lo = toAmplitude(low)
         val hi = toAmplitude(high)
-        val m = vm
+        val m = bind.vm
         if (m != null) {
             if (lo == 0 && hi == 0) {
                 m.cancel() // (0,0) = stop
                 return
             }
             val combo = CombinedVibration.startParallel()
-            if (amplitudeControlled && vibratorIds.size >= 2) {
-                // ids[0] = light/right, ids[1] = heavy/left (XInput/Moonlight convention).
-                if (hi != 0) combo.addVibrator(vibratorIds[0], oneShot(hi, durationMs))
-                if (lo != 0) combo.addVibrator(vibratorIds[1], oneShot(lo, durationMs))
+            if (bind.amplitudeControlled && bind.ids.size >= 2) {
+                // Two-motor split — ASSUMPTION: ids[0] = light/right, ids[1] = heavy/left
+                // (XInput/Moonlight convention). Android does not guarantee the order of
+                // VibratorManager.getVibratorIds(), so a pad that enumerates heavy-first would
+                // invert the feel: the stronger amplitude drives the physically-lighter motor.
+                // Failure mode is tactile only — both motors still fire, nothing silences or
+                // crashes — so this stays the default pending per-pad on-glass verification (G20).
+                // ids beyond the first two (rare) are left alone here.
+                if (hi != 0) combo.addVibrator(bind.ids[0], oneShot(hi, durationMs))
+                if (lo != 0) combo.addVibrator(bind.ids[1], oneShot(lo, durationMs))
             } else {
                 // Single motor or no amplitude control: blend both into one effect.
                 val a = (lo * 0.8 + hi * 0.33).toInt().coerceIn(1, 255)
-                for (id in vibratorIds) combo.addVibrator(id, oneShot(a, durationMs))
+                for (id in bind.ids) combo.addVibrator(id, oneShot(a, durationMs))
             }
             runCatching { m.vibrate(combo.combine()) }
             return
         }
         // API 28–30 legacy single-motor path: blend both motors into one effect.
-        val lv = legacy ?: return
+        val lv = bind.legacy ?: return
         if (lo == 0 && hi == 0) {
             lv.cancel() // (0,0) = stop
             return
@@ -194,7 +258,30 @@ class GamepadFeedback(private val handle: Long) {
         val a = (lo * 0.8 + hi * 0.33).toInt().coerceIn(1, 255)
         runCatching {
             lv.vibrate(
-                if (amplitudeControlled) oneShot(a, durationMs)
+                if (bind.amplitudeControlled) oneShot(a, durationMs)
+                else oneShot(VibrationEffect.DEFAULT_AMPLITUDE, durationMs)
+            )
+        }
+    }
+
+    /**
+     * The opt-in phone mirror: play a wire-pad-0 rumble on this device's own vibration motor —
+     * one physical actuator, so both wire motors blend into one effect (the same blend as the
+     * single-motor controller path). Same envelope semantics too: a one-shot held for the host's
+     * TTL, cancel on (0,0).
+     */
+    private fun renderDeviceRumble(low: Int, high: Int, durationMs: Long) {
+        val v = deviceVibrator ?: return
+        val lo = toAmplitude(low)
+        val hi = toAmplitude(high)
+        if (lo == 0 && hi == 0) {
+            runCatching { v.cancel() } // (0,0) = stop
+            return
+        }
+        val a = (lo * 0.8 + hi * 0.33).toInt().coerceIn(1, 255)
+        runCatching {
+            v.vibrate(
+                if (v.hasAmplitudeControl()) oneShot(a, durationMs)
                 else oneShot(VibrationEffect.DEFAULT_AMPLITUDE, durationMs)
             )
         }
@@ -207,36 +294,41 @@ class GamepadFeedback(private val handle: Long) {
     }
 
     // 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.
+    // 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
+    // (e.g. the legacy-Deck ceiling) with a nonzero amplitude — which reaches here past the (0,0)
+    // stop guard. On the VibratorManager path the effect is built OUTSIDE the vibrate() runCatching,
+    // so an uncaught throw here would kill the whole rumble poll thread.
     private fun oneShot(amp: Int, durationMs: Long): VibrationEffect =
-        VibrationEffect.createOneShot(durationMs, amp)
+        VibrationEffect.createOneShot(durationMs.coerceAtLeast(1), amp)
 
     // ---- HID output ----
 
     private fun dispatchHidout(buf: ByteBuffer, n: Int) {
         buf.rewind()
+        val pad = buf.get().toInt() and 0xFF // wire pad index the event is addressed to
         when (buf.get()) { // kind tag
             TAG_LED -> {
                 val r = buf.get().toInt() and 0xFF
                 val g = buf.get().toInt() and 0xFF
                 val b = buf.get().toInt() and 0xFF
-                Log.i(TAG, "hidout Led r=$r g=$g b=$b") // verification line
-                if (Build.VERSION.SDK_INT >= 33) setLightbar(Color.rgb(r, g, b))
+                Log.i(TAG, "hidout pad=$pad Led r=$r g=$g b=$b") // verification line
+                if (Build.VERSION.SDK_INT >= 33) setLightbar(pad, Color.rgb(r, g, b))
             }
             TAG_PLAYER_LEDS -> {
                 val bits = buf.get().toInt() and 0x1F
                 val player = playerIndexForBits(bits)
-                Log.i(TAG, "hidout PlayerLeds bits=$bits player=$player") // verification line
-                if (Build.VERSION.SDK_INT >= 33) setPlayerId(player)
+                Log.i(TAG, "hidout pad=$pad PlayerLeds bits=$bits player=$player") // verification line
+                if (Build.VERSION.SDK_INT >= 33) setPlayerId(pad, player)
             }
             TAG_TRIGGER -> {
                 val which = buf.get().toInt() and 0xFF // 0 = L2, 1 = R2
-                val effLen = n - 2
+                val effLen = n - 3 // [pad][kind][which] header, then the effect block
                 val mode = if (effLen > 0) buf.get().toInt() and 0xFF else 0
                 // No public adaptive-trigger API on Android — parse-validate the mode + log only.
                 Log.i(
                     TAG,
-                    "hidout Trigger which=$which effLen=$effLen mode=0x%02x (adaptive triggers unsupported on Android)".format(mode),
+                    "hidout pad=$pad Trigger which=$which effLen=$effLen mode=0x%02x (adaptive triggers unsupported on Android)".format(mode),
                 )
             }
             else -> Log.d(TAG, "hidout: unknown kind, dropped")
@@ -253,37 +345,63 @@ class GamepadFeedback(private val handle: Long) {
         else -> Integer.bitCount(bits and 0x1F).coerceIn(1, 4)
     }
 
-    private fun bindLights(dev: InputDevice?) {
-        if (dev == null) {
-            Log.i(TAG, "lights: no controller connected — lightbar/playerLed no-op (emulator path)")
-            return
+    /** The lights binding for the controller on wire pad [pad], or null (no live pad / no lights / < API 33). Cached by device id. */
+    private fun lightBindFor(pad: Int): LightBind? {
+        if (Build.VERSION.SDK_INT < 33) return null
+        val dev = router?.deviceForPad(pad) ?: return null
+        synchronized(bindsLock) {
+            if (lightBinds.containsKey(dev.id)) return lightBinds[dev.id]
+            val bind = bindLights(dev)
+            lightBinds[dev.id] = bind
+            return bind
         }
+    }
+
+    private fun bindLights(dev: InputDevice): LightBind? {
         val lm = dev.lightsManager
+        var rgb: Light? = null
+        var player: Light? = null
         for (l in lm.lights) {
-            if (rgbLight == null && l.hasRgbControl()) rgbLight = l
-            if (playerLight == null && l.type == Light.LIGHT_TYPE_PLAYER_ID) playerLight = l
+            if (rgb == null && l.hasRgbControl()) rgb = l
+            if (player == null && l.type == Light.LIGHT_TYPE_PLAYER_ID) player = l
         }
-        if (rgbLight == null && playerLight == null) {
+        if (rgb == null && player == null) {
             Log.i(TAG, "lights: controller '${dev.name}' exposes no controllable lights — no-op")
-            return
+            return null
         }
-        lightsSession = lm.openSession()
-        Log.i(TAG, "lights: bound rgb=${rgbLight != null} playerLed=${playerLight != null}")
+        val session = lm.openSession()
+        Log.i(TAG, "lights: bound rgb=${rgb != null} playerLed=${player != null} for '${dev.name}'")
+        return LightBind(session, rgb, player)
     }
 
-    private fun setLightbar(argb: Int) {
-        val s = lightsSession ?: return
-        val l = rgbLight ?: return
+    private fun setLightbar(pad: Int, argb: Int) {
+        val bind = lightBindFor(pad) ?: return
+        val l = bind.rgb ?: return
         runCatching {
-            s.requestLights(LightsRequest.Builder().addLight(l, LightState.Builder().setColor(argb).build()).build())
+            bind.session.requestLights(LightsRequest.Builder().addLight(l, LightState.Builder().setColor(argb).build()).build())
         }
     }
 
-    private fun setPlayerId(player: Int) {
-        val s = lightsSession ?: return
-        val l = playerLight ?: return
+    private fun setPlayerId(pad: Int, player: Int) {
+        val bind = lightBindFor(pad) ?: return
+        val l = bind.player ?: return
         runCatching {
-            s.requestLights(LightsRequest.Builder().addLight(l, LightState.Builder().setPlayerId(player).build()).build())
+            bind.session.requestLights(LightsRequest.Builder().addLight(l, LightState.Builder().setPlayerId(player).build()).build())
         }
     }
 }
+
+/**
+ * This device's own body vibrator (the phone, not a controller), or null where there is none
+ * (TVs) — gates the "Rumble on this phone" setting's visibility and feeds
+ * [GamepadFeedback.deviceVibrator] when it's on.
+ */
+fun deviceBodyVibrator(context: Context): Vibrator? {
+    val v = if (Build.VERSION.SDK_INT >= 31) {
+        context.getSystemService(VibratorManager::class.java)?.defaultVibrator
+    } else {
+        @Suppress("DEPRECATION")
+        context.getSystemService(Context.VIBRATOR_SERVICE) as? Vibrator
+    }
+    return v?.takeIf { it.hasVibrator() }
+}

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

@@ -0,0 +1,256 @@
+package io.unom.punktfunk.kit
+
+import android.content.Context
+import android.hardware.input.InputManager
+import android.os.Handler
+import android.os.Looper
+import android.view.InputDevice
+import android.view.KeyEvent
+import android.view.MotionEvent
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * Multi-controller router for one stream session — the Android analogue of the Linux client's gamepad
+ * `Worker`/`Slot` model (`pf-client-core/src/gamepad.rs`) over the shared native-plane wire contract
+ * (`punktfunk-core/src/input.rs`). Each physical controller (Android `deviceId`) gets a STABLE
+ * lowest-free wire pad index (0..15) held for its lifetime and freed only on disconnect, so a pad
+ * dropping never renumbers the others (a game must not see its players shuffle). Every forwarded event
+ * carries that pad index; a [NativeBridge.nativeSendGamepadArrival] declaring the pad's type is sent
+ * once BEFORE its first input, a [NativeBridge.nativeSendGamepadRemove] on disconnect. Per-device axis
+ * state lives in each slot's [Gamepad.AxisMapper] so a second controller can't clobber the first.
+ * Feedback (rumble / HID) is routed BACK to the originating device by pad index via [deviceForPad].
+ *
+ * Selection: forward EVERY real controller (the Linux client's single-player pin has no Android UI
+ * surface yet — Automatic is the only mode). Lifetime matches the session: constructed on stream
+ * attach (opening a slot for every already-connected pad, so its Arrival lands before any input),
+ * released on detach.
+ *
+ * A single controller lands on wire index 0, so its per-transition button/axis wire is byte-identical
+ * to the old single-pad path (plus the Arrival/Remove declarations the contract requires — which an
+ * older host simply ignores).
+ *
+ * Threading: slot mutation + dispatch run on the main thread (Android input dispatch and the
+ * InputManager hot-plug callbacks both land there). [deviceForPad] is read from the feedback poll
+ * threads, so the slot table is a [ConcurrentHashMap].
+ */
+class GamepadRouter(context: Context, private val handle: Long, private val setting: Int) {
+
+    /** 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
+    }
+
+    /** deviceId → slot. Concurrent: the feedback poll threads read it via [deviceForPad]. */
+    private val slots = ConcurrentHashMap<Int, Slot>()
+
+    /**
+     * Invoked (main thread) with the deviceId whenever a slot closes — hot-unplug or session teardown.
+     * `StreamScreen` wires this to `GamepadFeedback.onDeviceRemoved` so a disconnected pad's rumble /
+     * lights bindings are released promptly instead of leaking until the feedback threads stop.
+     */
+    var onSlotClosed: ((deviceId: Int) -> Unit)? = null
+
+    /**
+     * Invoked (main thread) when the emergency-exit chord has been HELD for [EXIT_HOLD_MS] — the caller
+     * leaves the stream. `StreamScreen` wires this to the deliberate-quit exit.
+     */
+    var onExitChord: (() -> Unit)? = null
+
+    private val mainHandler = Handler(Looper.getMainLooper())
+    /** The pending exit-chord hold timer, or null when the chord isn't currently armed. */
+    private var pendingExit: Runnable? = null
+
+    private val inputManager = context.getSystemService(InputManager::class.java)
+    private val listener = object : InputManager.InputDeviceListener {
+        override fun onInputDeviceAdded(deviceId: Int) {
+            InputDevice.getDevice(deviceId)?.let { if (isForwardable(it)) openSlot(it) }
+        }
+
+        override fun onInputDeviceRemoved(deviceId: Int) = closeSlot(deviceId)
+        override fun onInputDeviceChanged(deviceId: Int) {}
+    }
+
+    init {
+        inputManager?.registerInputDeviceListener(listener, mainHandler)
+        // Open a slot for every controller already connected when the session starts — the pads that
+        // will never fire onInputDeviceAdded during this session; their Arrival lands before any input.
+        for (id in InputDevice.getDeviceIds()) {
+            InputDevice.getDevice(id)?.let { if (isForwardable(it)) openSlot(it) }
+        }
+    }
+
+    /**
+     * One gamepad button transition for the device that produced [event] (already resolved to BTN_*
+     * bit [bit]). Opens the device's slot (declaring its type) if unseen, forwards the bit on the
+     * slot's pad index, and tracks held state. Completing the emergency stream-exit chord (Select +
+     * Start + L1 + R1) on any one pad ARMS a [EXIT_HOLD_MS] hold timer rather than leaving instantly;
+     * [onExitChord] fires only if the chord is still held at expiry (a brief accidental brush is
+     * ignored), matching `DISCONNECT_HOLD` on the SDL/Apple clients. Any controller can leave.
+     */
+    fun onButton(event: KeyEvent, bit: Int) {
+        val slot = slotFor(event.device) ?: return
+        when (event.action) {
+            KeyEvent.ACTION_DOWN -> {
+                // repeatCount guard: don't re-send a held button as auto-repeat.
+                if (event.repeatCount == 0) NativeBridge.nativeSendGamepadButton(handle, bit, true, slot.index)
+                slot.held = slot.held or bit
+                // Full chord now held on this pad → start the hold countdown (idempotent while held).
+                if (slot.held and EXIT_CHORD == EXIT_CHORD) armExit()
+            }
+            KeyEvent.ACTION_UP -> {
+                NativeBridge.nativeSendGamepadButton(handle, bit, false, slot.index)
+                slot.held = slot.held and bit.inv()
+                // A chord button lifted before the hold elapsed → cancel, unless another pad still
+                // holds the full chord.
+                if (bit and EXIT_CHORD != 0 && slots.values.none { it.held and EXIT_CHORD == EXIT_CHORD }) {
+                    disarmExit()
+                }
+            }
+        }
+    }
+
+    /** 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
+        val r = Runnable {
+            pendingExit = null
+            // Fire only if the chord survived the full hold on some pad.
+            val held = slots.values.filter { it.held and EXIT_CHORD == EXIT_CHORD }
+            if (held.isNotEmpty()) {
+                // Release the held buttons + zero the axes on every triggering pad so nothing sticks
+                // host-side once we leave, then signal the deliberate exit.
+                for (s in held) releaseHeld(s)
+                onExitChord?.invoke()
+            }
+        }
+        pendingExit = r
+        mainHandler.postDelayed(r, EXIT_HOLD_MS)
+    }
+
+    /** Cancel a pending exit-chord hold timer. */
+    private fun disarmExit() {
+        pendingExit?.let { mainHandler.removeCallbacks(it) }
+        pendingExit = null
+    }
+
+    /**
+     * One joystick MotionEvent — routed to the producing device's own [Gamepad.AxisMapper] (per-device
+     * state). Returns true if consumed. Only a real gamepad drives a pad: a DualSense/DS4 motion-sensor
+     * sibling node classifies as bare joystick (no GAMEPAD source class) and reports every pad axis as
+     * 0, so [isForwardable] filters it out before it can open a slot or clobber axes.
+     */
+    fun onMotion(event: MotionEvent): Boolean {
+        if (!event.isFromSource(InputDevice.SOURCE_JOYSTICK)) return false
+        if (event.actionMasked != MotionEvent.ACTION_MOVE) return false
+        val dev = event.device ?: return false
+        if (!isForwardable(dev)) return false
+        val slot = slotFor(dev) ?: return false
+        slot.mapper.onMotion(event)
+        return true
+    }
+
+    /**
+     * The controller currently mapped to wire pad [pad], for feedback routing; null if that index
+     * holds no live slot (a pad that just unplugged — the update is then dropped). Read from the
+     * feedback poll threads.
+     */
+    fun deviceForPad(pad: Int): InputDevice? {
+        for ((deviceId, slot) in slots) {
+            if (slot.index == pad) return InputDevice.getDevice(deviceId)
+        }
+        return null
+    }
+
+    /**
+     * Flush + drop every slot and unregister the hot-plug listener. Call on session teardown, AFTER
+     * the feedback poll threads are joined (they read [deviceForPad]).
+     */
+    fun release() {
+        inputManager?.unregisterInputDeviceListener(listener)
+        disarmExit() // drop any pending exit-chord timer so it can't fire after teardown
+        // Snapshot the ids first — closeSlot mutates the map.
+        for (id in slots.keys.toList()) closeSlot(id)
+    }
+
+    // ---- slots ----
+
+    /** A real, non-virtual controller we forward — its source classes include GAMEPAD (excludes a pad's bare-joystick sensor node). */
+    private fun isForwardable(dev: InputDevice): Boolean =
+        !dev.isVirtual && dev.sources and InputDevice.SOURCE_GAMEPAD == InputDevice.SOURCE_GAMEPAD
+
+    /**
+     * The slot for [dev], opening one (and declaring the pad) if this device is unseen; null when [dev]
+     * isn't a forwardable controller or every wire index is taken. The [isForwardable] gate lives here —
+     * the single lazy-open chokepoint both [onButton] and [onMotion] funnel through — so no entry point
+     * can open a phantom slot for a virtual/non-gamepad source (the hot-plug listener and init loop
+     * pre-filter and call [openSlot] directly).
+     */
+    private fun slotFor(dev: InputDevice?): Slot? {
+        if (dev == null) return null
+        slots[dev.id]?.let { return it }
+        if (!isForwardable(dev)) return null
+        return openSlot(dev)
+    }
+
+    /**
+     * Open a slot for [dev] on the lowest free wire index, declaring its kind ([NativeBridge.nativeSendGamepadArrival])
+     * before any input so the host builds a matching virtual device (mixed types across pads).
+     * Idempotent; null when all 16 wire indices are already forwarded.
+     */
+    private fun openSlot(dev: InputDevice): Slot? {
+        slots[dev.id]?.let { return it }
+        val index = lowestFreeIndex() ?: return null // 16 pads already forwarded — drop this one
+        // Automatic resolves the pad's type from its VID/PID; an explicit setting forces every pad
+        // to that type (a single global choice — matches the handshake's session-default pref).
+        val pref = if (setting == Gamepad.PREF_AUTO) Gamepad.prefFor(dev) else setting
+        NativeBridge.nativeSendGamepadArrival(handle, pref, index)
+        val slot = Slot(index, Gamepad.AxisMapper(handle, index))
+        slots[dev.id] = slot
+        return slot
+    }
+
+    /**
+     * Flush a slot's held wire state (so nothing sticks host-side), signal the removal, and free its
+     * index. Safe against an already-gone device — the flush emits wire events only, no device access.
+     */
+    private fun closeSlot(deviceId: Int) {
+        val slot = slots.remove(deviceId) ?: return
+        releaseHeld(slot)
+        NativeBridge.nativeSendGamepadRemove(handle, slot.index)
+        // If this pad was mid-exit-chord, its removal may have left no pad holding it — drop the timer.
+        if (slots.values.none { it.held and EXIT_CHORD == EXIT_CHORD }) disarmExit()
+        // Release this controller's feedback bindings (close its lights session / cancel rumble).
+        onSlotClosed?.invoke(deviceId)
+    }
+
+    /** Lift every held button + zero the axes/HAT dpad for [slot] (wire events only, all on its index). */
+    private fun releaseHeld(slot: Slot) {
+        var bits = slot.held
+        while (bits != 0) {
+            val bit = bits and -bits // lowest set bit
+            NativeBridge.nativeSendGamepadButton(handle, bit, false, slot.index)
+            bits = bits and bit.inv()
+        }
+        slot.held = 0
+        slot.mapper.reset() // zero sticks/triggers + release the HAT dpad
+    }
+
+    /** Lowest wire index 0..[MAX_PADS) not held by a slot, or null when full — stable lowest-free keeps indices from shuffling on hot-plug. */
+    private fun lowestFreeIndex(): Int? {
+        val taken = slots.values.mapTo(HashSet()) { it.index }
+        for (i in 0 until MAX_PADS) if (i !in taken) return i
+        return null
+    }
+
+    private companion object {
+        /** Mirror of `punktfunk-core::input::MAX_PADS` — wire pad indices 0..15. */
+        const val MAX_PADS = 16
+
+        /** Emergency stream-exit chord: Select + Start + L1 + R1 held together (matches the legacy single-pad chord). */
+        const val EXIT_CHORD = Gamepad.BTN_BACK or Gamepad.BTN_START or Gamepad.BTN_LB or Gamepad.BTN_RB
+
+        /** How long the exit chord must be held before the stream leaves — matches SDL/Apple `DISCONNECT_HOLD`. */
+        const val EXIT_HOLD_MS = 1500L
+    }
+}

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

@@ -269,26 +269,43 @@ object NativeBridge {
     /** One key transition. vk: Windows VK (0 = dropped by Rust). mods: VK modifier mask (0 for now). */
     external fun nativeSendKey(handle: Long, vk: Int, down: Boolean, mods: Int)
 
-    // ---- Gamepad: one pad forwarded as pad 0 (Rust hardcodes flags=0) ----
+    // ---- Gamepad: each controller forwarded on its own wire pad index (0..15, low byte of flags) ----
+    // The pad index is assigned per Android device by GamepadRouter; a single controller lands on 0,
+    // so its wire is byte-identical to the old single-pad path. The core folds the per-transition
+    // events into seq'd GamepadState snapshots keyed on this index and owns the per-pad seq.
 
-    /** One gamepad button transition. bit: a [Gamepad].BTN_* bit. down: press/release. */
-    external fun nativeSendGamepadButton(handle: Long, bit: Int, down: Boolean)
+    /** One gamepad button transition on wire pad [pad] (0..15). bit: a [Gamepad].BTN_* bit. down: press/release. */
+    external fun nativeSendGamepadButton(handle: Long, bit: Int, down: Boolean, pad: Int)
 
-    /** One gamepad axis update. axisId: [Gamepad].AXIS_* (0..5). value: stick i16 (+y=up) / trigger 0..255. */
-    external fun nativeSendGamepadAxis(handle: Long, axisId: Int, value: Int)
+    /** One gamepad axis update on wire pad [pad] (0..15). axisId: [Gamepad].AXIS_* (0..5). value: stick i16 (+y=up) / trigger 0..255. */
+    external fun nativeSendGamepadAxis(handle: Long, axisId: Int, value: Int, pad: Int)
+
+    /**
+     * Declare the controller KIND presented on wire pad [pad] (0..15) so the host builds a matching
+     * virtual device (mixed types across pads). pref: a [Gamepad].PREF_* wire byte. Send ONCE when a
+     * pad opens, BEFORE any of its input; an older host ignores it (that pad then uses the handshake's
+     * session-default kind — the pre-existing single-pad behaviour on pad 0).
+     */
+    external fun nativeSendGamepadArrival(handle: Long, pref: Int, pad: Int)
+
+    /** Signal wire pad [pad] (0..15) was unplugged so the host tears its virtual device down. The core stamps the seq + re-sends. */
+    external fun nativeSendGamepadRemove(handle: Long, pad: Int)
 
     // ---- Host→client gamepad feedback: Rust pulls block ~100ms, Kotlin renders (see GamepadFeedback) ----
 
     /**
-     * Block up to ~100 ms for the next rumble update. Returns `(low shl 16) or high` (each
-     * 0..0xFFFF; 0 = stop), or -1 on timeout / session closed. Call from a dedicated poll thread.
+     * Block up to ~100 ms for the next rumble update. Returns a packed positive long: bits 49..52 =
+     * wire pad index (0..15), bit 48 = has a v2 lease, bits 32..47 = ttl_ms, bits 16..31 = low, bits
+     * 0..15 = high (each amplitude 0..0xFFFF; 0/0 = stop), or -1 on timeout / session closed. Kotlin
+     * routes the update to the controller holding that pad index. Call from a dedicated poll thread.
      */
     external fun nativeNextRumble(handle: Long): Long
 
     /**
      * Block up to ~100 ms for the next DualSense HID-output event, written into [buf] (a direct
-     * ByteBuffer, capacity >= 64) as `[kind][fields…]`: Led=01 r g b, PlayerLeds=02 bits,
-     * Trigger=03 which effect…. Returns the byte count, or -1 on timeout / session closed.
+     * ByteBuffer, capacity >= 64) as `[pad][kind][fields…]` (leading pad = the wire pad index to
+     * route to): Led=pad 01 r g b, PlayerLeds=pad 02 bits, Trigger=pad 03 which effect…. Returns the
+     * byte count, or -1 on timeout / session closed.
      */
     external fun nativeNextHidout(handle: Long, buf: java.nio.ByteBuffer): Int
 }

clients/android/native/src/decode.rs

@@ -15,6 +15,7 @@ use ndk::media::media_format::MediaFormat;
 use ndk::native_window::NativeWindow;
 use punktfunk_core::client::NativeClient;
 use punktfunk_core::error::PunktfunkError;
+use punktfunk_core::reanchor::{GateVerdict, ReanchorGate};
 use punktfunk_core::session::Frame;
 use std::collections::VecDeque;
 use std::ffi::c_void;
@@ -208,9 +209,15 @@ fn run_sync(
     // pressure the AU stays parked here instead of being dropped (a drop forces a keyframe
     // round-trip) and we only pop the next one once it's queued.
     let mut pending: Option<Frame> = None;
-    // Loss recovery: watch the host→client unrecoverable-drop count and ask for an IDR when it
-    // climbs.
-    let mut last_dropped = client.frames_dropped();
+    // Freeze-until-reanchor: the shared post-loss gate ([`punktfunk_core::reanchor::ReanchorGate`]).
+    // Armed on a frame-index gap or a dropped-count climb, it withholds the decoder's concealed output
+    // (released WITHOUT rendering — the SurfaceView keeps the last rendered frame on glass) until a
+    // proven clean re-anchor lifts it: an IDR (wire FLAG_SOF), an RFI anchor, or the 2nd recovery mark.
+    // `last_kf_req` throttles the keyframe intents it emits; `recovery_flags` carries each AU's
+    // user_flags from feed to present (keyed by the codec-echoed pts) so `on_decoded` reads the
+    // re-anchor signalling the platform decoder doesn't expose.
+    let mut gate = ReanchorGate::new(client.frames_dropped());
+    let mut recovery_flags: VecDeque<(u64, u32)> = VecDeque::new();
     let mut last_kf_req: Option<Instant> = None;
     // Skew-corrected latency stats (spec: design/stats-unification.md) use the negotiated
     // host-minus-client clock offset (0 if the host didn't answer the skew handshake — then the
@@ -243,6 +250,20 @@ fn run_sync(
         if pending.is_none() {
             match client.next_frame(Duration::from_millis(5)) {
                 Ok(frame) => {
+                    // Loss recovery (RFI): feed the frame index so a forward gap fires a throttled
+                    // reference-frame-invalidation request — an RFI-capable host (AMD LTR / NVENC)
+                    // recovers with a cheap clean P-frame instead of a full IDR. The same forward gap
+                    // arms the freeze gate so the decoder's concealment is held off the screen until the
+                    // recovery re-anchors. The frames_dropped keyframe path below stays the backstop.
+                    if client.note_frame_index(frame.frame_index) {
+                        gate.arm(Instant::now());
+                    }
+                    // Park this AU's re-anchor flags for the present side (keyed by the pts the codec
+                    // echoes on the output buffer) — unconditional, unlike the HUD's `in_flight` map.
+                    recovery_flags.push_back((frame.pts_ns / 1000, frame.flags));
+                    if recovery_flags.len() > IN_FLIGHT_CAP {
+                        recovery_flags.pop_front();
+                    }
                     if fed == 0 {
                         let p = &frame.data;
                         log::info!(
@@ -331,6 +352,8 @@ fn run_sync(
             &mut in_flight,
             clock_offset.load(Ordering::Relaxed),
             &tracker,
+            &mut gate,
+            &mut recovery_flags,
         );
         rendered += r;
         discarded += d;
@@ -370,21 +393,19 @@ fn run_sync(
             work_accum_ns = 0;
         }
 
-        // Loss recovery: under infinite GOP the only recovery keyframe is one we request. The
-        // reassembler drops unrecoverable AUs (frames_dropped); the decoder then conceals the
-        // reference-missing delta frames that follow and renders them without error, so keying off
-        // a decode error rarely fires. Request an IDR when the drop count climbs, throttled — the
-        // decode stays wedged for several frames until the IDR lands, so requesting every frame
-        // would flood the control stream.
-        let dropped = client.frames_dropped();
-        if dropped > last_dropped {
-            last_dropped = dropped;
-            let now = Instant::now();
-            if last_kf_req.is_none_or(|t| now.duration_since(t) >= Duration::from_millis(100)) {
-                last_kf_req = Some(now);
-                let _ = client.request_keyframe();
-                log::debug!("decode: requested keyframe (loss recovery, dropped={dropped})");
-            }
+        // Loss recovery + overdue backstop, folded through the gate. Under infinite GOP the only
+        // recovery keyframe is one we request; the reassembler drops unrecoverable AUs (frames_dropped)
+        // and the decoder then conceals the reference-missing deltas and renders them without error, so
+        // a decode-error trigger rarely fires — the gate arms the freeze on the drop-count climb
+        // instead. An overdue freeze (held REANCHOR_FREEZE_MAX with no clean re-anchor) re-asks while it
+        // keeps holding: never resume to gray — a dead stream is the QUIC idle-timeout watchdog's job.
+        let now = Instant::now();
+        if gate.poll(client.frames_dropped(), now)
+            && last_kf_req.is_none_or(|t| now.duration_since(t) >= Duration::from_millis(100))
+        {
+            last_kf_req = Some(now);
+            let _ = client.request_keyframe();
+            log::debug!("decode: requested keyframe (loss recovery / overdue re-anchor)");
         }
     }
 
@@ -702,8 +723,10 @@ struct OutputReady {
 /// internal looper thread) push the codec ones; the feeder thread pushes `Au`. Each carries only
 /// owned/`Copy` data so the callback closures satisfy the `Send` bound and never touch the codec.
 enum DecodeEvent {
-    /// A received access unit from the feeder, ready to queue into the decoder.
-    Au(Frame),
+    /// A received access unit from the feeder, ready to queue into the decoder. The `bool` is the
+    /// feeder's [`NativeClient::note_frame_index`] verdict — `true` when this AU revealed a forward
+    /// frame-index gap, so the loop arms the freeze gate (the feeder already fired the RFI request).
+    Au(Frame, bool),
     /// An input buffer slot freed (index) — we can queue an AU into it.
     InputAvailable(usize),
     /// A decoded frame is ready (buffer index + echoed pts + the callback-time `decoded` stamp).
@@ -889,7 +912,12 @@ fn run_async(
     let mut discarded: u64 = 0;
     // AUs larger than the codec input buffer, dropped whole (see `feed`/`feed_ready`).
     let mut oversized_dropped: u64 = 0;
-    let mut last_dropped = client.frames_dropped();
+    // Freeze-until-reanchor gate (see the sync loop for the rationale). Armed on a frame-index gap
+    // (the feeder's Au verdict), a parked-AU overflow drop, a dropped-count climb, or a recoverable
+    // codec error; `recovery_flags` carries each AU's user_flags from `dispatch_event` (feed) to
+    // `present_ready` (present), keyed by the codec-echoed pts.
+    let mut gate = ReanchorGate::new(client.frames_dropped());
+    let mut recovery_flags: VecDeque<(u64, u32)> = VecDeque::new();
     let mut last_kf_req: Option<Instant> = None;
     // Productive (dispatch+feed+present) time between displayed frames; reported to ADPF once one is
     // presented. The blocking event wait is excluded (idle, not work) — same accounting as the sync loop.
@@ -915,6 +943,8 @@ fn run_async(
                 &mut ready,
                 &mut fmt_dirty,
                 &mut fatal,
+                &mut gate,
+                &mut recovery_flags,
             ));
         }
         // Coalesce every other event already queued into this one work pass — correct newest-only
@@ -927,6 +957,8 @@ fn run_async(
                 &mut ready,
                 &mut fmt_dirty,
                 &mut fatal,
+                &mut gate,
+                &mut recovery_flags,
             ));
         }
         stats.note_skipped(aus_dropped); // parked-AU overflow drops are client-side skips too
@@ -951,6 +983,8 @@ fn run_async(
             &tracker,
             &mut rendered,
             &mut discarded,
+            &mut gate,
+            &mut recovery_flags,
         );
 
         work_accum_ns += work_t0.elapsed().as_nanos() as i64;
@@ -982,17 +1016,19 @@ fn run_async(
                 log::info!("decode: fed={fed} rendered={rendered} discarded={discarded}");
             }
         }
-        // Loss recovery: request an IDR when the reassembler's unrecoverable-drop count climbs (or we
-        // dropped a parked AU on overflow), throttled so a multi-frame recovery gap doesn't flood the
-        // control stream.
-        let dropped = client.frames_dropped();
-        if dropped > last_dropped || aus_dropped > 0 {
-            last_dropped = dropped;
-            let now = Instant::now();
-            if last_kf_req.is_none_or(|t| now.duration_since(t) >= Duration::from_millis(100)) {
-                last_kf_req = Some(now);
-                let _ = client.request_keyframe();
-            }
+        // Loss recovery + overdue backstop, folded through the gate. A parked-AU overflow drop is itself
+        // a loss, so it arms the freeze directly; the gate's `poll` then arms on a dropped-count climb
+        // and re-asks on an overdue freeze. All keyframe intents route through the shared 100 ms
+        // throttle so a multi-frame recovery gap can't flood the control stream.
+        let now = Instant::now();
+        if aus_dropped > 0 {
+            gate.arm(now);
+        }
+        if (gate.poll(client.frames_dropped(), now) || aus_dropped > 0)
+            && last_kf_req.is_none_or(|t| now.duration_since(t) >= Duration::from_millis(100))
+        {
+            last_kf_req = Some(now);
+            let _ = client.request_keyframe();
         }
     }
 
@@ -1026,6 +1062,11 @@ fn feeder_loop(
     while !shutdown.load(Ordering::Relaxed) {
         match client.next_frame(Duration::from_millis(5)) {
             Ok(frame) => {
+                // Loss recovery (RFI): a forward frame-index gap fires a throttled reference-frame-
+                // invalidation request so an RFI-capable host recovers with a cheap clean P-frame
+                // instead of a full IDR (the frames_dropped keyframe path is the backstop). The gap
+                // verdict rides the Au event so the decode loop arms its freeze gate on the same signal.
+                let gap = client.note_frame_index(frame.frame_index);
                 if stats.enabled() {
                     let received_ns = now_realtime_ns();
                     let clock_offset = clock_offset.load(Ordering::Relaxed) as i128;
@@ -1058,7 +1099,7 @@ fn feeder_loop(
                         }
                     }
                 }
-                if ev_tx.send(DecodeEvent::Au(frame)).is_err() {
+                if ev_tx.send(DecodeEvent::Au(frame, gap)).is_err() {
                     break; // the decode loop is gone
                 }
             }
@@ -1070,6 +1111,7 @@ fn feeder_loop(
 
 /// Route one [`DecodeEvent`] into the loop's working sets. Returns `true` only when a parked AU was
 /// dropped on overflow (the caller then requests a keyframe).
+#[allow(clippy::too_many_arguments)] // two call sites; the freeze gate + flag map are threaded in
 fn dispatch_event(
     ev: DecodeEvent,
     pending_aus: &mut VecDeque<Frame>,
@@ -1077,9 +1119,20 @@ fn dispatch_event(
     ready: &mut Vec<OutputReady>,
     fmt_dirty: &mut bool,
     fatal: &mut bool,
+    gate: &mut ReanchorGate,
+    recovery_flags: &mut VecDeque<(u64, u32)>,
 ) -> bool {
     match ev {
-        DecodeEvent::Au(f) => {
+        DecodeEvent::Au(f, gap) => {
+            // A forward frame-index gap arms the freeze; park this AU's flags for the present side to
+            // fold `on_decoded` (keyed by the pts the codec will echo).
+            if gap {
+                gate.arm(Instant::now());
+            }
+            recovery_flags.push_back((f.pts_ns / 1000, f.flags));
+            if recovery_flags.len() > IN_FLIGHT_CAP {
+                recovery_flags.pop_front();
+            }
             pending_aus.push_back(f);
             if pending_aus.len() > FRAME_PARK_CAP {
                 pending_aus.pop_front(); // sustained overflow — drop oldest, signal a keyframe request
@@ -1100,6 +1153,10 @@ fn dispatch_event(
         DecodeEvent::Error { fatal: f } => {
             if f {
                 *fatal = true;
+            } else {
+                // A recoverable/transient codec error is a decode hiccup on a broken reference chain —
+                // arm the freeze so the concealed output it recovers into is held off the screen.
+                gate.arm(Instant::now());
             }
         }
     }
@@ -1171,6 +1228,8 @@ fn present_ready(
     tracker: &DisplayTracker,
     rendered: &mut u64,
     discarded: &mut u64,
+    gate: &mut ReanchorGate,
+    recovery_flags: &mut VecDeque<(u64, u32)>,
 ) {
     if ready.is_empty() {
         return;
@@ -1183,10 +1242,16 @@ fn present_ready(
             note_decoded_pts(stats, &mut g, clock_offset, o.pts_us, o.decoded_ns);
         }
     }
+    // Fold EVERY output through the gate in pts (== decode) order — even the ones newest-wins discards —
+    // so the two-mark re-anchor count stays correct; the newest's verdict decides whether it reaches
+    // glass (`false` = withheld concealment; the SurfaceView keeps the last rendered frame frozen on).
+    let now = Instant::now();
     let last = ready.len() - 1;
     let mut skipped: u64 = 0;
     for (i, o) in ready.drain(..).enumerate() {
-        let render = i == last;
+        let flags = take_flags(recovery_flags, o.pts_us);
+        let present = gate.on_decoded(flags, false, now) == GateVerdict::Present;
+        let render = i == last && present;
         match codec.release_output_buffer_by_index(o.index, render) {
             Ok(()) if render => {
                 *rendered += 1;
@@ -1206,7 +1271,7 @@ fn present_ready(
             }
         }
     }
-    stats.note_skipped(skipped); // HUD `skipped` counter (newest-wins drops); no-op while hidden
+    stats.note_skipped(skipped); // HUD `skipped` counter (newest-wins + held-off drops); no-op hidden
 }
 
 /// React to an output-format change by signalling the stream's HDR dataspace on the Surface (SDR
@@ -1402,19 +1467,30 @@ fn drain(
     in_flight: &mut VecDeque<(u64, i128)>,
     clock_offset: i64,
     tracker: &DisplayTracker,
+    gate: &mut ReanchorGate,
+    recovery_flags: &mut VecDeque<(u64, u32)>,
 ) -> (u64, u64) {
     // Newest ready buffer so far (presented after the loop) with its HUD metadata —
-    // `Some((pts_us, decoded_ns))` only while the HUD is visible (the stamp read is gated).
+    // `Some((pts_us, decoded_ns))` only while the HUD is visible. `held_present` is the freeze gate's
+    // verdict for that newest buffer (`false` = a post-loss concealment to withhold).
     let mut held: Option<(OutputBuffer<'_>, Option<(u64, i128)>)> = None;
+    let mut held_present = true;
     let mut discarded: u64 = 0;
     let mut wait = first_wait;
     loop {
         match codec.dequeue_output_buffer(wait) {
             Ok(DequeuedOutputBufferInfoResult::Buffer(buf)) => {
-                wait = Duration::ZERO; // only the first dequeue may block
+                // Only the first dequeue may block; later ones poll (wait == ZERO).
+                wait = Duration::ZERO;
+                // Fold every dequeued frame through the gate in pts (== decode) order — even the ones
+                // the newest-wins policy discards — so the two-mark re-anchor count stays correct; the
+                // verdict of the newest (last folded) buffer decides whether it reaches glass.
+                let pts_us = buf.info().presentation_time_us().max(0) as u64;
+                let flags = take_flags(recovery_flags, pts_us);
+                held_present =
+                    gate.on_decoded(flags, false, Instant::now()) == GateVerdict::Present;
                 let meta = if stats.enabled() {
                     // The dequeue IS the sync loop's decoded-availability instant.
-                    let pts_us = buf.info().presentation_time_us().max(0) as u64;
                     let decoded_ns = now_realtime_ns();
                     note_decoded_pts(stats, in_flight, clock_offset, pts_us, decoded_ns);
                     Some((pts_us, decoded_ns))
@@ -1460,16 +1536,19 @@ fn drain(
             }
         }
     }
-    // Present the newest ready frame, if any, and park its metadata for the render callback.
+    // Present the newest ready frame — UNLESS the gate is withholding it as a post-loss concealment,
+    // in which case release it without rendering (the SurfaceView keeps the last rendered frame frozen
+    // on glass) and count it as a discard rather than a display.
     let mut rendered = 0;
     if let Some((buf, meta)) = held {
-        match codec.release_output_buffer(buf, true) {
-            Ok(()) => {
+        match codec.release_output_buffer(buf, held_present) {
+            Ok(()) if held_present => {
                 rendered = 1;
                 if let Some((pts_us, decoded_ns)) = meta {
                     tracker.note_rendered(pts_us, decoded_ns);
                 }
             }
+            Ok(()) => discarded += 1, // held off the screen — awaiting a clean re-anchor
             Err(e) => log::warn!("decode: release_output_buffer: {e}"),
         }
     }
@@ -1511,6 +1590,25 @@ fn note_decoded_pts(
     stats.note_decoded(e2e_us, decode_us);
 }
 
+/// The AU `user_flags` for a decoded output, keyed by the echoed `presentationTimeUs`. Recovery
+/// signalling (FLAG_SOF IDR marker / RECOVERY_ANCHOR / RECOVERY_POINT) rides the AU's flags, which are
+/// only in scope at feed time — so the feed side parks `(pts_us, flags)` here and the present side
+/// looks them up to fold [`ReanchorGate::on_decoded`]. Decode order == input order (low-latency, no
+/// B-frames), so this evicts entries older than `pts_us` as it goes; a miss (probe filler, or an entry
+/// aged past the cap) reads `0` — no recovery flags, decoded normally.
+fn take_flags(map: &mut VecDeque<(u64, u32)>, pts_us: u64) -> u32 {
+    while let Some(&(p, f)) = map.front() {
+        if p > pts_us {
+            break; // future frame — leave it for its own output buffer
+        }
+        map.pop_front();
+        if p == pts_us {
+            return f;
+        }
+    }
+    0
+}
+
 /// Map the decoder's reported output colour to a BT.2020 HDR dataspace, or `None` for SDR. The
 /// integer values are the Android MediaFormat colour constants the NDK shares: COLOR_TRANSFER
 /// ST2084 = 6 (PQ/HDR10), HLG = 7; COLOR_RANGE FULL = 1, LIMITED = 2 (the host encodes limited).

clients/android/native/src/feedback.rs

@@ -24,12 +24,13 @@ const TAG_PLAYER_LEDS: u8 = 0x02;
 const TAG_TRIGGER: u8 = 0x03;
 
 /// `NativeBridge.nativeNextRumble(handle): Long` — block up to ~100 ms for the next rumble update.
-/// Returns a packed positive long: bit 48 = "has a v2 lease", bits 32..47 = `ttl_ms`, bits 16..31 =
-/// `low`, bits 0..15 = `high` (`low`/`high` 0..=0xFFFF, `0/0` = stop). The lease flag is
-/// out-of-band so ANY 16-bit `ttl_ms` — including 0xFFFF — is unambiguous (no in-band sentinel to
-/// collide with a real 65535 ms lease). No lease (legacy host) → bit 48 clear, and Kotlin falls
-/// back to its long one-shot. `-1` on timeout / session closed (all packed values are positive, so
-/// `-1` stays unambiguous). Pad index is dropped (single-pad model). Run from a Kotlin poll thread.
+/// Returns a packed positive long: bits 49..52 = wire `pad` index (0..15), bit 48 = "has a v2 lease",
+/// bits 32..47 = `ttl_ms`, bits 16..31 = `low`, bits 0..15 = `high` (`low`/`high` 0..=0xFFFF, `0/0` =
+/// stop). The lease flag is out-of-band so ANY 16-bit `ttl_ms` — including 0xFFFF — is unambiguous (no
+/// in-band sentinel to collide with a real 65535 ms lease). No lease (legacy host) → bit 48 clear, and
+/// Kotlin falls back to its long one-shot. `-1` on timeout / session closed (all packed values are
+/// positive, so `-1` stays unambiguous). Kotlin routes the update back to the controller holding that
+/// wire `pad` index (multi-pad rumble). Run from a Kotlin poll thread.
 #[no_mangle]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextRumble(
     _env: JNIEnv,
@@ -46,14 +47,19 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextRumble(
         // threads (and joins them — unbounded) before nativeClose frees the handle.
         let h = unsafe { &*(handle as *const SessionHandle) };
         match h.client.next_rumble_ttl(PULL_TIMEOUT) {
-            Ok((_pad, low, high, ttl)) => {
+            Ok((pad, low, high, ttl)) => {
                 // The reorder gate already ran in the core, so this update is fresh. Encode the
-                // Option out-of-band: a real lease sets bit 48 and carries ttl_ms verbatim.
+                // Option out-of-band: a real lease sets bit 48 and carries ttl_ms verbatim. The pad
+                // index rides above the lease flag (bits 49..52), keeping the whole word positive.
                 let (lease_flag, ttl_bits) = match ttl {
                     Some(ms) => (1i64 << 48, jlong::from(ms) << 32),
                     None => (0, 0),
                 };
-                lease_flag | ttl_bits | (jlong::from(low) << 16) | jlong::from(high)
+                (jlong::from(pad & 0xF) << 49)
+                    | lease_flag
+                    | ttl_bits
+                    | (jlong::from(low) << 16)
+                    | jlong::from(high)
             }
             Err(_) => -1, // NoFrame (timeout) or Closed — Kotlin loops on its running flag
         }
@@ -61,10 +67,12 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextRumble(
 }
 
 /// `NativeBridge.nativeNextHidout(handle, buf): Int` — block up to ~100 ms for the next DualSense
-/// HID-output event, written into the caller's direct ByteBuffer as `[kind][fields…]`:
-///   Led        → `[0x01][r][g][b]`         (len 4)
-///   PlayerLeds → `[0x02][bits]`            (len 2)
-///   Trigger    → `[0x03][which][effect…]`  (len 2 + effect.len())
+/// HID-output event, written into the caller's direct ByteBuffer as `[pad][kind][fields…]` (the
+/// leading `pad` is the wire pad index the event is addressed to, so Kotlin routes it to that
+/// controller — multi-pad HID feedback):
+///   Led        → `[pad][0x01][r][g][b]`         (len 5)
+///   PlayerLeds → `[pad][0x02][bits]`            (len 3)
+///   Trigger    → `[pad][0x03][which][effect…]`  (len 3 + effect.len())
 /// Returns the byte count written, or `-1` on timeout / session closed / buffer too small.
 #[no_mangle]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextHidout(
@@ -97,33 +105,37 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextHidout(
         // SAFETY: `ptr`/`cap` describe the direct ByteBuffer's backing store, valid for this call.
         let out = unsafe { std::slice::from_raw_parts_mut(ptr, cap) };
 
+        // out[0] = wire pad index; out[1] = kind tag; the rest is the per-kind payload.
         let n = match ev {
-            HidOutput::Led { r, g, b, .. } => {
-                if cap < 4 {
+            HidOutput::Led { pad, r, g, b } => {
+                if cap < 5 {
                     return -1;
                 }
-                out[0] = TAG_LED;
-                out[1] = r;
-                out[2] = g;
-                out[3] = b;
-                4
+                out[0] = pad;
+                out[1] = TAG_LED;
+                out[2] = r;
+                out[3] = g;
+                out[4] = b;
+                5
             }
-            HidOutput::PlayerLeds { bits, .. } => {
-                if cap < 2 {
+            HidOutput::PlayerLeds { pad, bits } => {
+                if cap < 3 {
                     return -1;
                 }
-                out[0] = TAG_PLAYER_LEDS;
-                out[1] = bits;
-                2
+                out[0] = pad;
+                out[1] = TAG_PLAYER_LEDS;
+                out[2] = bits;
+                3
             }
-            HidOutput::Trigger { which, effect, .. } => {
-                let n = 2 + effect.len();
+            HidOutput::Trigger { pad, which, effect } => {
+                let n = 3 + effect.len();
                 if cap < n {
                     return -1; // the raw DS5 trigger block is ~11 bytes; Kotlin allocates 64
                 }
-                out[0] = TAG_TRIGGER;
-                out[1] = which;
-                out[2..n].copy_from_slice(&effect);
+                out[0] = pad;
+                out[1] = TAG_TRIGGER;
+                out[2] = which;
+                out[3..n].copy_from_slice(&effect);
                 n
             }
             HidOutput::TrackpadHaptic { .. } => {

clients/android/native/src/session/input.rs

@@ -145,13 +145,19 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendKey(
 }
 
 // ---- Gamepad: Kotlin captures (KeyEvent/MotionEvent) → NativeClient::send_input ---------------
-// Single-pad model: exactly one controller, forwarded as pad 0 (flags = 0). Buttons carry the
-// gamepad::BTN_* bit in `code` and pressed/released in `x` (1/0); axes carry the gamepad::AXIS_* id
-// in `code` and the value in `x` (sticks i16 −32768..32767, +y = up; triggers 0..255). The host
-// accumulates the incremental events into its virtual xpad. Wire contract: input.rs::gamepad.
+// Multi-pad model: each physical controller is forwarded on its own wire pad index (0..15), carried
+// in the low byte of `flags` on every per-pad event — the Kotlin side (`GamepadRouter`) assigns a
+// stable lowest-free index per Android device and threads it here. Buttons carry the gamepad::BTN_*
+// bit in `code` and pressed/released in `x` (1/0); axes carry the gamepad::AXIS_* id in `code` and
+// the value in `x` (sticks i16 −32768..32767, +y = up; triggers 0..255). The host accumulates the
+// incremental events per pad into a matching virtual device. The core input task folds these into
+// the seq'd GamepadState snapshots (keyed on this same `flags` index) and owns the per-pad seq — so
+// the only thing this layer must get right is the index. Wire contract: input.rs::gamepad. A single
+// controller lands on index 0, so its wire is byte-identical to the old single-pad path.
 
-/// `NativeBridge.nativeSendGamepadButton(handle, bit, down)` — one gamepad button transition.
-/// `bit`: a `gamepad::BTN_*` bit (e.g. BTN_A = 0x1000). `down`: 1=press, 0=release.
+/// `NativeBridge.nativeSendGamepadButton(handle, bit, down, pad)` — one gamepad button transition on
+/// wire pad index `pad`. `bit`: a `gamepad::BTN_*` bit (e.g. BTN_A = 0x1000). `down`: 1=press,
+/// 0=release. `pad`: wire pad index 0..15 (rides `flags`).
 #[no_mangle]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadButton(
     _env: JNIEnv,
@@ -159,21 +165,21 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepad
     handle: jlong,
     bit: jint,
     down: jboolean,
+    pad: jint,
 ) {
-    // flags = 0: pad index 0 — single-pad model.
     send_event(
         handle,
         InputKind::GamepadButton,
         bit as u32,
         i32::from(down != 0),
         0,
-        0,
+        pad as u32,
     );
 }
 
-/// `NativeBridge.nativeSendGamepadAxis(handle, axisId, value)` — one gamepad axis update.
-/// `axisId`: a `gamepad::AXIS_*` id (LS_X=0..RT=5). `value`: stick i16 (−32768..32767, +y=up) or
-/// trigger 0..255.
+/// `NativeBridge.nativeSendGamepadAxis(handle, axisId, value, pad)` — one gamepad axis update on wire
+/// pad index `pad`. `axisId`: a `gamepad::AXIS_*` id (LS_X=0..RT=5). `value`: stick i16
+/// (−32768..32767, +y=up) or trigger 0..255. `pad`: wire pad index 0..15 (rides `flags`).
 #[no_mangle]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadAxis(
     _env: JNIEnv,
@@ -181,7 +187,52 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepad
     handle: jlong,
     axis_id: jint,
     value: jint,
+    pad: jint,
 ) {
-    // flags = 0: pad index 0 — single-pad model.
-    send_event(handle, InputKind::GamepadAxis, axis_id as u32, value, 0, 0);
+    send_event(
+        handle,
+        InputKind::GamepadAxis,
+        axis_id as u32,
+        value,
+        0,
+        pad as u32,
+    );
+}
+
+/// `NativeBridge.nativeSendGamepadArrival(handle, pref, pad)` — declare the controller KIND presented
+/// on wire pad index `pad` so the host builds a matching virtual device (mixed types — pad 0 a
+/// DualSense, pad 1 an Xbox pad). `pref`: the `GamepadPref` wire byte (rides `code`). `pad`: wire pad
+/// index 0..15 (rides `flags`). Sent ONCE when a pad opens, BEFORE any of its input; the core re-sends
+/// it a few times against datagram loss, and an older host ignores the unknown tag (that pad then uses
+/// the session-default kind from the handshake — the pre-existing single-pad behaviour on pad 0).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadArrival(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    pref: jint,
+    pad: jint,
+) {
+    send_event(
+        handle,
+        InputKind::GamepadArrival,
+        pref as u32,
+        0,
+        0,
+        pad as u32,
+    );
+}
+
+/// `NativeBridge.nativeSendGamepadRemove(handle, pad)` — signal that wire pad index `pad` was
+/// unplugged so the host tears its virtual device down. `pad` (rides `flags`) is the only field; the
+/// core stamps the per-pad seq (in the snapshot seq space, so a reordered snapshot can't resurrect the
+/// pad) and arms a re-send burst against datagram loss. An older host ignores the unknown tag.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadRemove(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    pad: jint,
+) {
+    send_event(handle, InputKind::GamepadRemove, 0, 0, 0, pad as u32);
 }

clients/apple/Config/Info.plist

@@ -2,24 +2,24 @@
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
-	<!-- Custom keys merged into the auto-generated Info.plist (GENERATE_INFOPLIST_FILE=YES
-	     supplies the rest). NSBonjourServices is required for NWBrowser to browse this
-	     service type on iOS/tvOS — without it the system blocks the browse and discovery
-	     returns nothing. Kept OUT of the synchronized App/ + Sources/ groups so it isn't
-	     auto-added as a bundle resource (which collides with Info.plist processing). -->
+	<key>CADisableMinimumFrameDurationOnPhone</key>
+	<true/>
+	<key>GCSupportedGameControllers</key>
+	<array>
+		<dict>
+			<key>ProfileName</key>
+			<string>ExtendedGamepad</string>
+		</dict>
+		<dict>
+			<key>ProfileName</key>
+			<string>MicroGamepad</string>
+		</dict>
+	</array>
+	<key>ITSAppUsesNonExemptEncryption</key>
+	<true/>
 	<key>NSBonjourServices</key>
 	<array>
 		<string>_punktfunk._udp</string>
 	</array>
-	<!-- Standard-algorithm crypto only (AES-GCM via the Rust core) — exempt from export
-	     compliance, but the key must be declared or every TestFlight build stalls on the
-	     compliance question. -->
-	<key>ITSAppUsesNonExemptEncryption</key>
-	<false/>
-	<!-- Allow CADisplayLink above 60 Hz on ProMotion iPhones: without this key the system
-	     silently caps the link at 60 even when SessionPresenter asks for the stream's rate
-	     via preferredFrameRateRange, so a 120 fps stream would present at half rate. -->
-	<key>CADisableMinimumFrameDurationOnPhone</key>
-	<true/>
 </dict>
 </plist>

clients/apple/Config/Punktfunk.entitlements

@@ -14,19 +14,11 @@
 	<!-- Wake-on-LAN needs to send a UDP broadcast magic packet (a sleeping host has no ARP
 	     entry, so unicast can't wake it). Since iOS 14 / tvOS 14 the OS blocks sending to
 	     broadcast/multicast addresses unless the app carries this managed entitlement — it must
-	     be requested from and approved by Apple for the App ID, then enabled in the provisioning
-	     profile. macOS is not gated by this (its App Sandbox network.client/server cover it).
-
-	     GATED pending Apple's approval of the request (form filed) — an unauthorized managed
-	     entitlement breaks iOS/tvOS signing, so it's commented out to keep those apps releasable.
-	     ON APPROVAL: (1) uncomment the two lines below, and (2) flip
-	     PunktfunkConnection.wakeOnLANAvailable (PunktfunkConnection.swift) to enable the iOS/tvOS
-	     wake path + UI. Until then iOS/tvOS Wake-on-LAN is a clean no-op — MACs are still learned
-	     from mDNS so it works immediately once ungated. macOS is unaffected (separate entitlements
-	     file, no multicast entitlement needed). -->
-	<!--
+	     be approved by Apple for the App ID and enabled in the provisioning profile. macOS is not
+	     gated by this (its App Sandbox network.client/server cover it), hence its separate file.
+	     Approved and provisioned, so it's enabled here and PunktfunkConnection.wakeOnLANAvailable
+	     is true on iOS/tvOS too. -->
 	<key>com.apple.developer.networking.multicast</key>
 	<true/>
-	-->
 </dict>
 </plist>

clients/apple/Package.swift

@@ -40,6 +40,8 @@ let package = Package(
         // its manifest breaks SwiftPM whole-graph validation on macOS, and only the
         // Punktfunk-tvOS target links it; the #if os(tvOS) import never compiles here.)
         .executableTarget(name: "PunktfunkClient", dependencies: ["PunktfunkKit"]),
-        .testTarget(name: "PunktfunkKitTests", dependencies: ["PunktfunkKit"]),
+        // PunktfunkCore is a direct dep too so the wire tests can name the C ABI's
+        // `PunktfunkInputEvent` / `PUNKTFUNK_INPUT_KIND_*` when asserting the gamepad byte layout.
+        .testTarget(name: "PunktfunkKitTests", dependencies: ["PunktfunkKit", "PunktfunkCore"]),
     ]
 )

clients/apple/Punktfunk.xcodeproj/project.pbxproj

@@ -436,6 +436,7 @@
 				INFOPLIST_KEY_CFBundleDisplayName = Punktfunk;
 				INFOPLIST_KEY_GCSupportsControllerUserInteraction = YES;
 				INFOPLIST_KEY_GCSupportsGameMode = YES;
+				INFOPLIST_KEY_ITSAppUsesNonExemptEncryption = NO;
 				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.games";
 				INFOPLIST_KEY_NSLocalNetworkUsageDescription = "Punktfunk connects directly to your punktfunk host on the local network to stream video, audio, and input.";
 				INFOPLIST_KEY_NSMicrophoneUsageDescription = "Your microphone is streamed to the connected punktfunk host, where it appears as a virtual microphone.";
@@ -477,6 +478,7 @@
 				INFOPLIST_KEY_CFBundleDisplayName = Punktfunk;
 				INFOPLIST_KEY_GCSupportsControllerUserInteraction = YES;
 				INFOPLIST_KEY_GCSupportsGameMode = YES;
+				INFOPLIST_KEY_ITSAppUsesNonExemptEncryption = NO;
 				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.games";
 				INFOPLIST_KEY_NSLocalNetworkUsageDescription = "Punktfunk connects directly to your punktfunk host on the local network to stream video, audio, and input.";
 				INFOPLIST_KEY_NSMicrophoneUsageDescription = "Your microphone is streamed to the connected punktfunk host, where it appears as a virtual microphone.";

clients/apple/Punktfunk.xcodeproj/xcshareddata/xcschemes/Punktfunk-iOS.xcscheme

@@ -49,6 +49,13 @@
             ReferencedContainer = "container:Punktfunk.xcodeproj">
          </BuildableReference>
       </BuildableProductRunnable>
+      <EnvironmentVariables>
+         <EnvironmentVariable
+            key = "PUNKTFUNK_BILINEAR_LUMA"
+            value = "1"
+            isEnabled = "YES">
+         </EnvironmentVariable>
+      </EnvironmentVariables>
    </LaunchAction>
    <ProfileAction
       buildConfiguration = "Release"

clients/apple/Sources/PunktfunkClient/ContentView.swift

@@ -60,7 +60,8 @@ struct ContentView: View {
     @State private var speedTestTarget: StoredHost?
     @State private var libraryTarget: StoredHost?
     /// Wakes a sleeping host and waits for it to come back online before connecting (drives the
-    /// "Waking…" overlay). macOS-only in practice — WoL is gated off on iOS/tvOS.
+    /// "Waking…" phase of the connect overlay). Available on every platform now that the iOS/tvOS
+    /// multicast entitlement is granted (see PunktfunkConnection.wakeOnLANAvailable).
     @StateObject private var waker = HostWaker()
     #if os(macOS)
     /// Whether the hosting window is native-fullscreen right now (reported by
@@ -86,6 +87,10 @@ struct ContentView: View {
     // with no (extended) controller attached tvOS falls back to HomeView as before.
     @ObservedObject private var gamepadManager = GamepadManager.shared
     @AppStorage(DefaultsKey.gamepadUIEnabled) private var gamepadUIEnabled = true
+    /// Auto-wake on connect (Settings → General). On (default): a dial to an offline saved host
+    /// fires Wake-on-LAN up front and falls into the "Waking…" wait if the dial fails. Off: connects
+    /// go straight through with no wake. The explicit "Wake Host" action is unaffected either way.
+    @AppStorage(DefaultsKey.autoWake) private var autoWakeEnabled = true
     private var gamepadUIActive: Bool {
         GamepadUIEnvironment.isActive(
             gamepadConnected: gamepadManager.active != nil, enabledSetting: gamepadUIEnabled)
@@ -259,9 +264,26 @@ struct ContentView: View {
     }
 
     private var home: some View {
-        // The "Waking…" overlay rides over BOTH home UIs (and the pre-connect window is still
-        // `home`, so it covers the whole wake→online→connect sequence).
-        homeBase.overlay { WakeOverlay(waker: waker) }
+        // The full-screen connect takeover rides over BOTH home UIs (and the pre-connect window is
+        // still `home`, so it covers the whole dial → wake → online → connect sequence): instant
+        // "Connecting…" feedback on any dial, flowing seamlessly into the "Waking…" wait if the host
+        // turns out to be asleep.
+        homeBase.overlay {
+            ConnectOverlay(
+                connectingHostName: connectingOverlayName,
+                waker: waker,
+                gamepadUI: gamepadUIActive,
+                onCancelConnect: { model.disconnect() })
+        }
+    }
+
+    /// The host label for the connect takeover's "Connecting…" phase — a plain dial in flight. Nil
+    /// during the delegated-approval wait (that has its own "Waiting for approval" prompt, so the
+    /// takeover must not stack over it) and, of course, when idle or streaming.
+    private var connectingOverlayName: String? {
+        guard awaitingApproval == nil, model.phase == .connecting, let host = model.activeHost
+        else { return nil }
+        return host.displayName
     }
 
     @ViewBuilder private var homeBase: some View {
@@ -327,12 +349,25 @@ struct ContentView: View {
         }()
         return ZStack {
             stream(captureEnabled: pendingFingerprint == nil)
-                .blur(radius: pendingFingerprint != nil ? 32 : 0)
+                // Blur the live stream during the trust prompt (heavy) and during a resize (lighter
+                // — the deliberate "hold on" while the host rebuilds its pipeline and the decoder
+                // re-inits on the new-mode IDR). Only the resize blur animates; the trust blur snaps
+                // as before (its own overlay handles the transition).
+                .blur(radius: pendingFingerprint != nil ? 32 : (model.resizing ? 16 : 0))
+                .animation(.easeInOut(duration: 0.22), value: model.resizing)
                 .overlay {
                     if pendingFingerprint != nil {
                         Color.black.opacity(0.45)
                     }
                 }
+                // The resize spinner rides over the (blurred) stream; suppressed under the trust
+                // prompt, which owns the screen. It never hit-tests, so window-drag resizes keep
+                // steering and the next click still reaches the stream.
+                .overlay {
+                    if pendingFingerprint == nil {
+                        ResizeIndicatorView(active: model.resizing)
+                    }
+                }
             if let fp = pendingFingerprint {
                 TrustCardView(
                     fingerprint: fp,
@@ -410,6 +445,16 @@ struct ContentView: View {
                     onSessionEnd: { [weak model] in
                         Task { @MainActor in model?.sessionEnded() }
                     },
+                    // Resize overlay START — the follower is main-actor, so this drives the blur
+                    // + spinner synchronously the instant the window differs from the live mode.
+                    onResizeTarget: { [weak model] w, h in
+                        model?.resizeTargeted(width: w, height: h)
+                    },
+                    // Resize overlay END — the coded dims of each new-mode IDR, reported from the
+                    // decode pump thread; hop to the main actor to clear the overlay.
+                    onDecodedSize: { [weak model] w, h in
+                        Task { @MainActor in model?.resizeDecoded(width: w, height: h) }
+                    },
                     endToEndMeter: model.endToEnd,
                     decodeMeter: model.decodeStage,
                     displayMeter: model.displayStage
@@ -544,7 +589,8 @@ struct ContentView: View {
         // packet up front, so a genuinely-asleep host is waking while the connect times out; only
         // when that dial FAILS do we fall into the visible "Waking…" wait — a cold box takes far
         // longer to boot than a connect will sit — and redial once it's back on mDNS.
-        if PunktfunkConnection.wakeOnLANAvailable, !host.wakeMacs.isEmpty, !discovery.advertises(host) {
+        if autoWakeEnabled, PunktfunkConnection.wakeOnLANAvailable,
+           !host.wakeMacs.isEmpty, !discovery.advertises(host) {
             discovery.start() // so the wake-wait can observe it reappear
             startSessionDirect(
                 host, launchID: launchID, allowTofu: allowTofu,
@@ -601,7 +647,9 @@ struct ContentView: View {
     private func prepareWake(for host: StoredHost) {
         if let live = discovery.hosts.first(where: { host.matches($0) }) {
             store.updateMacs(host.id, macs: live.macAddresses) // learn — on every platform
-        } else if PunktfunkConnection.wakeOnLANAvailable, !host.wakeMacs.isEmpty {
+        } else if autoWakeEnabled, PunktfunkConnection.wakeOnLANAvailable, !host.wakeMacs.isEmpty {
+            // Auto-wake only: fire the up-front packet so a genuinely-asleep host is booting while the
+            // dial times out. With auto-wake off, connects go straight through (no packet).
             let macs = host.wakeMacs
             let ip = host.address
             DispatchQueue.global(qos: .userInitiated).async {

clients/apple/Sources/PunktfunkClient/Home/ConnectOverlay.swift

@@ -0,0 +1,145 @@
+// The unified "getting you connected" overlay — one look for BOTH phases of reaching a host, so the
+// user gets feedback the instant they pick one and it flows seamlessly into a wake if the host turns
+// out to be asleep. The Apple mirror of the Android client's `ConnectOverlay` and the shared console
+// UI's connect/wake takeover; it replaces the old centered-card `WakeOverlay`.
+//
+//   - Connecting (`connectingHostName` non-nil): the dial is in flight. Shown immediately on activate
+//     so a host that takes a beat to answer no longer looks like nothing happened.
+//   - Waking (`waker.waking` non-nil): the dial failed on a sleeping host, so we're firing
+//     Wake-on-LAN and waiting for it to advertise again, escalating to a retry/cancel prompt on
+//     timeout.
+//
+// Presentation is mode-aware: the gamepad ("console") UI gets a full-screen aurora takeover — the
+// same living backdrop the console home wears, so it reads as a deliberate 10-foot moment; the
+// default touch/desktop UI gets a Liquid Glass modal over a dim scrim, which sits right at home among
+// the app's other floating surfaces (the trust card, the HUD) instead of a full-screen aurora that
+// looked out of place there.
+//
+// The two phases hand off within a single view update (HostWaker clears `waking` and starts the
+// connect in the same MainActor step), so the overlay never blinks between them. It swallows input to
+// the screen behind it, and on iOS/macOS the pad drives it (B cancels, A retries once timed out).
+
+import PunktfunkKit
+import SwiftUI
+
+struct ConnectOverlay: View {
+    /// Non-nil while a plain dial is in flight (the delegated-approval wait has its own prompt, so it
+    /// passes nil here). Drives the "Connecting…" phase.
+    let connectingHostName: String?
+    @ObservedObject var waker: HostWaker
+    /// The console launcher is up → full-screen aurora takeover; otherwise the default UI's Liquid
+    /// Glass modal.
+    var gamepadUI: Bool
+    /// Cancel a dial in flight — tears down the (uncancelable) connect and returns the UI; the late
+    /// result is discarded by SessionModel's connect guard.
+    var onCancelConnect: () -> Void
+
+    private enum Phase {
+        case connecting(name: String)
+        case waking(HostWaker.Waking)
+    }
+
+    /// Waking takes precedence — it only ever exists after a dial has already failed, so a stray
+    /// overlap can't strand the "Connecting…" phase over a wake in progress.
+    private var phase: Phase? {
+        if let w = waker.waking { return .waking(w) }
+        if let name = connectingHostName { return .connecting(name: name) }
+        return nil
+    }
+
+    var body: some View {
+        if let phase {
+            ZStack {
+                if gamepadUI {
+                    // Console: an opaque, living aurora over everything.
+                    Color.black.ignoresSafeArea()
+                    GamepadScreenBackground().ignoresSafeArea()
+                    Color.clear.contentShape(Rectangle()).onTapGesture {}
+                    content(phase).padding(40).frame(maxWidth: 460)
+                } else {
+                    // Default UI: a Liquid Glass modal over a dim scrim.
+                    Rectangle().fill(.black.opacity(0.5)).ignoresSafeArea()
+                        .contentShape(Rectangle()).onTapGesture {}
+                    content(phase)
+                        .padding(28)
+                        .frame(maxWidth: 380)
+                        .glassBackground(RoundedRectangle(cornerRadius: 26, style: .continuous))
+                        .overlay(
+                            RoundedRectangle(cornerRadius: 26, style: .continuous)
+                                .strokeBorder(.white.opacity(0.12), lineWidth: 1))
+                        .padding(40)
+                }
+            }
+            .environment(\.colorScheme, .dark)
+            .transition(.opacity)
+            #if os(iOS) || os(macOS)
+            .background { ConnectControllerInput(waker: waker, onCancelConnect: onCancelConnect) }
+            #endif
+        }
+    }
+
+    @ViewBuilder private func content(_ phase: Phase) -> some View {
+        // The takeover carries larger type than the compact modal.
+        let titleSize: CGFloat = gamepadUI ? 24 : 19
+        let bodySize: CGFloat = gamepadUI ? 14 : 13
+        VStack(spacing: gamepadUI ? 16 : 14) {
+            switch phase {
+            case .connecting(let name):
+                ProgressView().controlSize(.large).tint(.white)
+                Text("Connecting to \(name)")
+                    .font(.geist(titleSize, .bold, relativeTo: .title3)).foregroundStyle(.white)
+                    .multilineTextAlignment(.center)
+                Text("Establishing a secure connection…")
+                    .font(.geist(bodySize, relativeTo: .caption)).foregroundStyle(.white.opacity(0.6))
+                Button("Cancel") { onCancelConnect() }.buttonStyle(.bordered).padding(.top, 6)
+            case .waking(let w) where w.timedOut:
+                Image(systemName: "moon.zzz.fill")
+                    .font(.system(size: gamepadUI ? 40 : 34)).foregroundStyle(.white.opacity(0.9))
+                Text("\(w.hostName) didn't wake")
+                    .font(.geist(titleSize, .bold, relativeTo: .title3)).foregroundStyle(.white)
+                    .multilineTextAlignment(.center)
+                Text("It may still be booting, or it's powered off / off this network.")
+                    .font(.geist(bodySize, relativeTo: .caption)).foregroundStyle(.white.opacity(0.6))
+                    .multilineTextAlignment(.center)
+                HStack(spacing: 12) {
+                    Button("Cancel") { waker.cancel() }.buttonStyle(.bordered)
+                    Button("Try Again") { waker.retry() }.glassProminentButtonStyle()
+                }
+                .padding(.top, 6)
+            case .waking(let w):
+                ProgressView().controlSize(.large).tint(.white)
+                Text("Waking \(w.hostName)…")
+                    .font(.geist(titleSize, .bold, relativeTo: .title3)).foregroundStyle(.white)
+                    .multilineTextAlignment(.center)
+                Text("Waiting for it to come online · \(w.seconds)s")
+                    .font(.geistFixed(bodySize)).foregroundStyle(.white.opacity(0.6)).monospacedDigit()
+                // A wake-only wait (no dial after) offers "Stop Waiting"; a wake-&-connect is "Cancel".
+                Button(w.connectsAfter ? "Cancel" : "Stop Waiting") { waker.cancel() }
+                    .buttonStyle(.bordered).padding(.top, 6)
+            }
+        }
+    }
+}
+
+#if os(iOS) || os(macOS)
+/// Controller binding for the overlay: B cancels whatever's in flight (a dial or the wake wait); A
+/// retries once a wake has timed out. The closures read the live state on each press, so they stay
+/// correct across the Connecting ↔ Waking handoff without the view re-mounting. A zero-size backing
+/// view owning a `GamepadMenuInput` for the overlay's lifetime (the home is gated inactive while the
+/// overlay is up, so nothing else is consuming the pad).
+private struct ConnectControllerInput: View {
+    @ObservedObject var waker: HostWaker
+    var onCancelConnect: () -> Void
+    @State private var input = GamepadMenuInput(manager: .shared)
+
+    var body: some View {
+        Color.clear
+            .onAppear {
+                input.onBack = { if waker.waking != nil { waker.cancel() } else { onCancelConnect() } }
+                input.onConfirm = { if waker.waking?.timedOut == true { waker.retry() } }
+                input.start()
+            }
+            .onDisappear { input.stop() }
+    }
+}
+#endif

clients/apple/Sources/PunktfunkClient/Home/GamepadHomeView.swift

@@ -65,6 +65,9 @@ struct GamepadHomeView: View {
     /// Same gate the touch grid's "Browse Library…" context-menu item uses (default ON; the
     /// Settings "Game library" toggle opts out).
     @AppStorage(DefaultsKey.libraryEnabled) private var libraryEnabled = true
+    /// Auto-wake on connect (default ON) — when off, activating an offline host just dials (no wake),
+    /// so the tile drops its "Wake & Connect" affordance for a plain "Connect".
+    @AppStorage(DefaultsKey.autoWake) private var autoWakeEnabled = true
     #if os(iOS)
     /// `.compact` in a landscape phone window — drives tighter chrome so everything still fits.
     @Environment(\.verticalSizeClass) private var vSizeClass
@@ -192,9 +195,12 @@ struct GamepadHomeView: View {
             onActivate: { $0.activate() },
             onSecondary: { openLibraryForSelected() },
             onTertiary: { showSettings = true },
-            // Stop consuming the controller while another screen (or the wake overlay) is on top —
-            // otherwise the launcher navigates behind it (invisibly on iPhone, visibly on iPad).
-            isActive: libraryTarget == nil && !showSettings && !showAddHost && waker.waking == nil
+            // Stop consuming the controller while another screen (or the connect/wake takeover) is on
+            // top — otherwise the launcher navigates behind it (invisibly on iPhone, visibly on iPad),
+            // and a second A during a dial would launch a concurrent connect. `.connecting` covers the
+            // takeover's Connecting phase; `waker.waking` covers its Waking phase.
+            isActive: libraryTarget == nil && !showSettings && !showAddHost
+                && waker.waking == nil && model.phase != .connecting
         ) { tile in
             hostCard(tile, size: CGSize(width: cardWidth, height: cardHeight))
         }
@@ -256,7 +262,7 @@ struct GamepadHomeView: View {
                 isConnecting: model.phase == .connecting && model.activeHost?.id == host.id,
                 filled: true,
                 hasLibrary: true,
-                canWake: PunktfunkConnection.wakeOnLANAvailable
+                canWake: autoWakeEnabled && PunktfunkConnection.wakeOnLANAvailable
                     && !discovery.advertises(host) && !store.probedOnline.contains(host.id)
                     && !host.wakeMacs.isEmpty,
                 activate: { connect(host) })

clients/apple/Sources/PunktfunkClient/Home/WakeOverlay.swift

@@ -1,84 +0,0 @@
-// The "Waking <host>…" modal shown while HostWaker brings a sleeping host back — a spinner + a
-// live elapsed counter, escalating to a retry/cancel prompt on timeout. Presented over BOTH the
-// touch and gamepad home (a wake only ever starts on macOS today, where WoL is ungated), and it
-// drives from either a pointer (the buttons) or a controller (B cancels, A retries once timed out).
-
-import PunktfunkKit
-import SwiftUI
-
-struct WakeOverlay: View {
-    @ObservedObject var waker: HostWaker
-
-    var body: some View {
-        if let w = waker.waking {
-            ZStack {
-                // Dim + swallow input to the home behind it.
-                Rectangle().fill(.black.opacity(0.6)).ignoresSafeArea()
-                    .contentShape(Rectangle())
-                    .onTapGesture {}
-                card(w)
-                    .frame(maxWidth: 380)
-                    .padding(28)
-                    .consoleGlass(RoundedRectangle(cornerRadius: 22, style: .continuous))
-                    .overlay(
-                        RoundedRectangle(cornerRadius: 22, style: .continuous)
-                            .strokeBorder(.white.opacity(0.12), lineWidth: 1))
-                    .padding(40)
-            }
-            .environment(\.colorScheme, .dark)
-            .transition(.opacity)
-            #if os(iOS) || os(macOS)
-            .background { WakeControllerInput(waker: waker) }
-            #endif
-        }
-    }
-
-    @ViewBuilder private func card(_ w: HostWaker.Waking) -> some View {
-        VStack(spacing: 14) {
-            if w.timedOut {
-                Image(systemName: "moon.zzz.fill")
-                    .font(.system(size: 34)).foregroundStyle(.white.opacity(0.85))
-                Text("\(w.hostName) didn't wake")
-                    .font(.geist(19, .bold, relativeTo: .title3)).foregroundStyle(.white)
-                Text("It may still be booting, or it's powered off / off this network.")
-                    .font(.geist(13, relativeTo: .caption)).foregroundStyle(.white.opacity(0.6))
-                    .multilineTextAlignment(.center)
-                HStack(spacing: 12) {
-                    Button("Cancel") { waker.cancel() }.buttonStyle(.bordered)
-                    Button("Try Again") { waker.retry() }.glassProminentButtonStyle()
-                }
-                .padding(.top, 6)
-            } else {
-                ProgressView().controlSize(.large).tint(.white)
-                Text("Waking \(w.hostName)…")
-                    .font(.geist(19, .bold, relativeTo: .title3)).foregroundStyle(.white)
-                Text("Waiting for it to come online · \(w.seconds)s")
-                    .font(.geistFixed(13)).foregroundStyle(.white.opacity(0.6))
-                    .monospacedDigit()
-                Button(w.connectsAfter ? "Cancel" : "Stop Waiting") { waker.cancel() }
-                    .buttonStyle(.bordered)
-                    .padding(.top, 6)
-            }
-        }
-    }
-}
-
-#if os(iOS) || os(macOS)
-/// Controller binding for the overlay: B cancels; A retries once it has timed out. A zero-size
-/// backing view owning a `GamepadMenuInput` for the overlay's lifetime (the home carousel/list is
-/// gated inactive while a wake is up, so nothing else is consuming the pad).
-private struct WakeControllerInput: View {
-    @ObservedObject var waker: HostWaker
-    @State private var input = GamepadMenuInput(manager: .shared)
-
-    var body: some View {
-        Color.clear
-            .onAppear {
-                input.onBack = { waker.cancel() }
-                input.onConfirm = { if waker.waking?.timedOut == true { waker.retry() } }
-                input.start()
-            }
-            .onDisappear { input.stop() }
-    }
-}
-#endif

clients/apple/Sources/PunktfunkClient/Screenshots/ScreenshotScenes.swift

@@ -49,8 +49,24 @@ enum ShotScenes {
             ShotScene(name: "08-gamepad-addhost", orientation: .natural, colorScheme: .dark) {
                 AnyView(ShotGamepadAddHost())
             },
-            ShotScene(name: "09-waking", orientation: .natural, colorScheme: .dark) {
-                AnyView(ShotWaking())
+            ShotScene(name: "09-connecting", orientation: .natural, colorScheme: .dark) {
+                AnyView(ShotConnect(kind: .connecting))
+            },
+            ShotScene(name: "09b-waking", orientation: .natural, colorScheme: .dark) {
+                AnyView(ShotConnect(kind: .waking))
+            },
+            ShotScene(name: "09c-wake-timed-out", orientation: .natural, colorScheme: .dark) {
+                AnyView(ShotConnect(kind: .timedOut))
+            },
+            // The default-UI presentation (Liquid Glass modal over the touch grid) of the same phases.
+            ShotScene(name: "09d-connecting-modal", orientation: .natural, colorScheme: .dark) {
+                AnyView(ShotConnect(kind: .connecting, gamepadUI: false))
+            },
+            ShotScene(name: "09e-waking-modal", orientation: .natural, colorScheme: .dark) {
+                AnyView(ShotConnect(kind: .waking, gamepadUI: false))
+            },
+            ShotScene(name: "09f-wake-timed-out-modal", orientation: .natural, colorScheme: .dark) {
+                AnyView(ShotConnect(kind: .timedOut, gamepadUI: false))
             },
         ]
         #endif
@@ -137,23 +153,53 @@ private struct ShotGamepadAddHost: View {
     var body: some View { GamepadAddHostView(onAdd: { _ in }) }
 }
 
-private struct ShotWaking: View {
+/// The unified connect overlay (the real `ConnectOverlay`) in each phase — instant "Connecting…"
+/// feedback, the "Waking…" wait, and the wake-timed-out prompt. `gamepadUI` picks the presentation:
+/// the console's full-screen aurora takeover over the gamepad home, or the default UI's Liquid Glass
+/// modal over the touch host grid.
+private struct ShotConnect: View {
+    enum Kind { case connecting, waking, timedOut }
+    let kind: Kind
+    var gamepadUI = true
+
     @StateObject private var store = ShotMock.hostStore()
     @StateObject private var model = SessionModel()
     @StateObject private var discovery = HostDiscovery()
     @StateObject private var waker = HostWaker()
 
     var body: some View {
-        GamepadHomeView(
-            store: store, model: model, discovery: discovery,
-            libraryTarget: .constant(nil), waker: waker,
-            connect: { _ in }, connectDiscovered: { _ in }
-        )
-        .overlay { WakeOverlay(waker: waker) }
-        .onAppear {
-            waker.debugSet(.init(
-                hostID: store.hosts.first?.id ?? UUID(),
-                hostName: "Battlestation", connectsAfter: true, seconds: 14))
+        backdrop
+            .overlay {
+                ConnectOverlay(
+                    connectingHostName: kind == .connecting ? "Battlestation" : nil,
+                    waker: waker,
+                    gamepadUI: gamepadUI,
+                    onCancelConnect: {})
+            }
+            .onAppear {
+                switch kind {
+                case .connecting:
+                    break
+                case .waking:
+                    waker.debugSet(.init(
+                        hostID: store.hosts.first?.id ?? UUID(),
+                        hostName: "Battlestation", connectsAfter: true, seconds: 14))
+                case .timedOut:
+                    waker.debugSet(.init(
+                        hostID: store.hosts.first?.id ?? UUID(),
+                        hostName: "Battlestation", connectsAfter: true, seconds: 90, timedOut: true))
+                }
+            }
+    }
+
+    @ViewBuilder private var backdrop: some View {
+        if gamepadUI {
+            GamepadHomeView(
+                store: store, model: model, discovery: discovery,
+                libraryTarget: .constant(nil), waker: waker,
+                connect: { _ in }, connectDiscovered: { _ in })
+        } else {
+            ShotHome()
         }
     }
 }

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

@@ -22,7 +22,7 @@ final class HostWaker: ObservableObject {
         var timedOut = false
     }
 
-    /// nil = idle; non-nil drives `WakeOverlay`.
+    /// nil = idle; non-nil drives the "Waking…" phase of `ConnectOverlay`.
     @Published private(set) var waking: Waking?
 
     /// How long to wait for the host to reappear before giving up. Generous — a cold boot + service

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

@@ -0,0 +1,41 @@
+// The resize overlay (design/midstream-resolution-resize.md — client resize UX). A Match-window
+// resize renegotiates the host's virtual display + encoder and re-inits the local VideoToolbox
+// decoder on the first new-mode IDR — an unavoidable sub-second gap where the last frame lingers,
+// briefly freezes, or the picture pops to the new geometry. Rather than let that read as a stutter,
+// we make it DELIBERATE: the caller blurs the live stream and this centered spinner + caption
+// acknowledges the transition. It clears the instant a frame at the requested size decodes (the
+// `onDecodedSize` END signal) or on the follower's safety timeout — see `SessionModel.resizing`.
+//
+// Floating overlay, never a hit-test target: input keeps flowing to the stream underneath so a
+// resize the user triggers by dragging the window never swallows their next click.
+
+import PunktfunkKit
+import SwiftUI
+
+struct ResizeIndicatorView: View {
+    /// Mirrors `SessionModel.resizing`; the fade in/out is driven off this.
+    let active: Bool
+
+    var body: some View {
+        ZStack {
+            if active {
+                VStack(spacing: 12) {
+                    ProgressView().controlSize(.large).tint(.white)
+                    Text("Resizing…")
+                        .font(.geist(15, .medium, relativeTo: .callout))
+                        .foregroundStyle(.white.opacity(0.85))
+                }
+                .padding(.horizontal, 30)
+                .padding(.vertical, 24)
+                .glassBackground(RoundedRectangle(cornerRadius: 20, style: .continuous))
+                .overlay(
+                    RoundedRectangle(cornerRadius: 20, style: .continuous)
+                        .strokeBorder(.white.opacity(0.12), lineWidth: 1))
+                .transition(.opacity.combined(with: .scale(scale: 0.92)))
+            }
+        }
+        .environment(\.colorScheme, .dark) // the spinner + glass read over any frame
+        .animation(.easeInOut(duration: 0.22), value: active)
+        .allowsHitTesting(false) // the stream keeps receiving input the whole time
+    }
+}

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

@@ -109,6 +109,16 @@ final class SessionModel: ObservableObject {
     /// Mirrors StreamView's capture state (it owns the input capture; this drives the
     /// HUD's "click to capture" / "⌘⎋ releases" hint).
     @Published var mouseCaptured = false
+    /// Resize overlay (design/midstream-resolution-resize.md — client resize UX): true from the
+    /// instant a Match-window resize starts steering toward a new size until a frame at that size
+    /// decodes (or a safety timeout). Drives the blur+spinner so the unavoidable host-rebuild delay
+    /// reads as a deliberate, acknowledged transition instead of a stutter. Pure state lives in
+    /// `ResizeIndicator`; this mirrors its `active` for SwiftUI.
+    @Published private(set) var resizing = false
+    /// START = follower steering (main actor), END = a new-mode IDR's coded dims (decode pump,
+    /// hopped to main), TIMEOUT = safety net for a rejected/capped switch that never yields a
+    /// differently-sized frame. Ticked from the 1 Hz stats timer.
+    private var resizeIndicator = ResizeIndicator()
 
     let meter = FrameMeter()
     /// Capture→received (the host+network stage), fed per AU at receipt by the stream view's
@@ -364,6 +374,8 @@ final class SessionModel: ObservableObject {
         lostFrames = 0
         lostPct = 0
         mouseCaptured = false
+        resizing = false
+        resizeIndicator = ResizeIndicator() // no stale target/timer into the next session
     }
 
     /// Called (via the main actor) when the pump hits end-of-session.
@@ -374,6 +386,23 @@ final class SessionModel: ObservableObject {
         errorMessage = "Session ended by \(name)."
     }
 
+    /// Resize overlay START (main actor — from the Match-window follower's `onResizeTarget`): the
+    /// window began differing from the live mode, so a `Reconfigure` toward `(width, height)` is
+    /// imminent. Show the blur+spinner immediately, before the debounced request even leaves.
+    func resizeTargeted(width: UInt32, height: UInt32) {
+        resizeIndicator.steering(
+            width: width, height: height, now: Date().timeIntervalSinceReferenceDate)
+        resizing = resizeIndicator.active
+    }
+
+    /// Resize overlay END (main actor — hopped from the decode pump's `onDecodedSize`): a new-mode
+    /// IDR decoded at `(width, height)`. Clears the overlay only when that matches the size we're
+    /// steering to (a same-size loss-recovery IDR, or the initial connect IDR, is a no-op).
+    func resizeDecoded(width: Int, height: Int) {
+        resizeIndicator.decoded(width: UInt32(max(width, 0)), height: UInt32(max(height, 0)))
+        resizing = resizeIndicator.active
+    }
+
     private func beginStreaming() {
         guard let conn = connection else { return }
         // Input capture itself is owned by StreamView (engaged by the captureEnabled
@@ -390,9 +419,10 @@ final class SessionModel: ObservableObject {
             micChannel: defaults.integer(forKey: DefaultsKey.micChannel),
             micEnabled: defaults.object(forKey: DefaultsKey.micEnabled) as? Bool ?? true)
         self.audio = audio
-        // Gamepads: forward GamepadManager's active controller as pad 0 and render the
-        // host's feedback (rumble always; lightbar/player-LEDs/adaptive-triggers when the
-        // session's virtual pad is a DualSense). Same trust gate as audio — nothing is
+        // Gamepads: forward every controller GamepadManager selected — each on its own wire pad
+        // index (a pin forwards only one, Automatic forwards all) — and render the host's feedback
+        // back to the pad it's addressed to (rumble always; lightbar/player-LEDs/adaptive-triggers
+        // when a pad's virtual device is a DualSense). Same trust gate as audio — nothing is
         // forwarded during the trust prompt.
         let capture = GamepadCapture(connection: conn, manager: .shared)
         // The cross-client escape chord (hold L1+R1+Start+Select 1.5 s) — on tvOS the only
@@ -417,6 +447,11 @@ final class SessionModel: ObservableObject {
         let timer = Timer(timeInterval: 1.0, repeats: true) { [weak self] _ in
             guard let self else { return }
             Task { @MainActor in
+                // Resize-overlay safety net: clear a stuck overlay when a targeted size never
+                // decodes (a rejected/capped switch). The decoded-frame END clears it promptly on
+                // success; this only fires after the timeout.
+                self.resizeIndicator.tick(now: Date().timeIntervalSinceReferenceDate)
+                self.resizing = self.resizeIndicator.active
                 let (frames, bytes, total) = self.meter.drain()
                 self.fps = frames
                 self.mbps = Double(bytes) * 8 / 1_000_000

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

@@ -15,6 +15,9 @@ import PunktfunkKit
 import SwiftUI
 #if os(iOS) || os(macOS) || os(tvOS)
 import GameController
+#if os(iOS)
+import CoreHaptics
+#endif
 
 struct GamepadSettingsView: View {
     @Environment(\.dismiss) private var dismiss
@@ -36,7 +39,11 @@ struct GamepadSettingsView: View {
     @AppStorage(DefaultsKey.hudPlacement) private var hudPlacement = HUDPlacement.topTrailing.rawValue
     @AppStorage(DefaultsKey.libraryEnabled) private var libraryEnabled = true
     @AppStorage(DefaultsKey.gamepadUIEnabled) private var gamepadUIEnabled = true
+    @AppStorage(DefaultsKey.autoWake) private var autoWakeEnabled = true
     @AppStorage(DefaultsKey.presenter) private var presenter = SettingsOptions.presenterDefault
+    #if os(iOS)
+    @AppStorage(DefaultsKey.rumbleOnDevice) private var rumbleOnDevice = false
+    #endif
     @ObservedObject private var gamepads = GamepadManager.shared
 
     #if os(iOS)
@@ -229,7 +236,7 @@ struct GamepadSettingsView: View {
             .map { (label: "\($0) Hz", tag: $0) }
         let bitrate = SettingsOptions.bitrateOptions(current: bitrateKbps)
         let controllers = SettingsOptions.controllerOptions(gamepads)
-        return [
+        var list: [Row] = [
             choiceRow(
                 id: "resolution", header: "Stream", icon: "aspectratio",
                 label: "Resolution",
@@ -258,6 +265,11 @@ struct GamepadSettingsView: View {
                     + "available on the host.",
                 options: SettingsOptions.compositors, current: compositor
             ) { compositor = $0 },
+            toggleRow(
+                id: "autoWake", icon: "power", label: "Auto-wake on connect",
+                detail: "Send Wake-on-LAN to a sleeping saved host and wait for it before "
+                    + "streaming. Off connects straight through.",
+                value: $autoWakeEnabled),
 
             choiceRow(
                 id: "codec", header: "Video", icon: "film", label: "Video codec",
@@ -323,6 +335,23 @@ struct GamepadSettingsView: View {
                 detail: "Turn off to use the touch interface even with a controller connected.",
                 value: $gamepadUIEnabled),
         ]
+        #if os(iOS)
+        // The device-rumble mirror slots in after "Controller type" (staying inside the
+        // Controller group — the next row carries the "Interface" header). iPhone only in
+        // practice: hidden where the device itself can't play haptics (iPad).
+        if CHHapticEngine.capabilitiesForHardware().supportsHaptics,
+            let at = list.firstIndex(where: { $0.id == "padType" }) {
+            list.insert(
+                toggleRow(
+                    id: "deviceRumble", icon: "iphone.radiowaves.left.and.right",
+                    label: "Rumble on this iPhone",
+                    detail: "Also play player 1's rumble on the phone's own Taptic Engine — "
+                        + "for clip-on pads without rumble motors.",
+                    value: $rumbleOnDevice),
+                at: at + 1)
+        }
+        #endif
+        return list
     }
 
     /// Resolution choices as "WxH" tags — the current size is inserted when it's a custom mode

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

@@ -1,6 +1,9 @@
 // SettingsView's shared sections — each setting's Section is defined exactly once here and
 // composed by the per-platform bodies in SettingsView.swift.
 
+#if os(iOS)
+import CoreHaptics
+#endif
 import PunktfunkKit
 import SwiftUI
 
@@ -13,6 +16,11 @@ extension SettingsView {
     // failed exactly one slice: the iOS archive (macOS/tvOS never compile that branch).
     @ViewBuilder var streamModeSection: some View {
         Section {
+            #if os(iOS) || os(macOS)
+            // Match-window (design/midstream-resolution-resize.md D1): follow the session
+            // window/scene, renegotiating the host mode on a resize. Off → the explicit mode below.
+            Toggle("Match window", isOn: $matchWindow)
+            #endif
             #if os(iOS)
             iosResolutionWheel
             iosRefreshRows
@@ -35,8 +43,12 @@ extension SettingsView {
         } header: {
             Text("Stream mode")
         } footer: {
-            Text("The host creates a virtual output at exactly this mode — "
-                + "native resolution, no scaling. \(Self.bitrateFooter)")
+            Text(matchWindow
+                ? "The stream follows this window — the host resizes its virtual output to match "
+                    + "as you resize, so the picture stays pixel-exact (1:1) with no scaling. "
+                    + "\(Self.bitrateFooter)"
+                : "The host creates a virtual output at exactly this mode — native resolution, but "
+                    + "a window that isn't this size is scaled to fit. \(Self.bitrateFooter)")
                 .font(.geist(12, relativeTo: .caption))
                 .foregroundStyle(.secondary)
         }
@@ -286,6 +298,24 @@ extension SettingsView {
         }
     }
 
+    /// Auto-wake on connect — fire Wake-on-LAN + wait for a sleeping saved host to come back before
+    /// giving up. Now available on every platform (the iOS/tvOS multicast entitlement is granted).
+    @ViewBuilder var wakeSection: some View {
+        Section {
+            Toggle("Auto-wake on connect", isOn: $autoWakeEnabled)
+        } header: {
+            Text("Wake-on-LAN")
+        } footer: {
+            Text("Connecting to a saved host that isn't on the network yet sends a Wake-on-LAN "
+                + "packet and waits for it to come back before streaming. Turn off if a host that's "
+                + "already on just isn't visible here (e.g. over a VPN), so connects go straight "
+                + "through instead of waiting out the wake. A host's “Wake” action still works either "
+                + "way.")
+                .font(.geist(12, relativeTo: .caption))
+                .foregroundStyle(.secondary)
+        }
+    }
+
     @ViewBuilder var windowSection: some View {
         #if os(macOS)
         Section {
@@ -444,6 +474,12 @@ extension SettingsView {
                     Text(option.label).tag(option.tag)
                 }
             }
+            #if os(iOS)
+            // iPhone only in practice: hidden where the device itself can't play haptics (iPad).
+            if CHHapticEngine.capabilitiesForHardware().supportsHaptics {
+                Toggle("Rumble on this iPhone", isOn: $rumbleOnDevice)
+            }
+            #endif
             #if !os(tvOS)
             Toggle("Gamepad-optimized browsing", isOn: $gamepadUIEnabled)
             #endif
@@ -460,6 +496,11 @@ extension SettingsView {
             // for its own footer and has no such toggle to describe.
             VStack(alignment: .leading, spacing: 6) {
                 Text(Self.controllersFooter)
+                #if os(iOS)
+                if CHHapticEngine.capabilitiesForHardware().supportsHaptics {
+                    Text(Self.deviceRumbleFooter)
+                }
+                #endif
                 #if !os(tvOS)
                 Text(Self.gamepadUIFooter)
                 #endif

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

@@ -88,6 +88,13 @@ extension SettingsView {
         + "controller (a DualSense keeps adaptive triggers, lightbar, touchpad and motion). "
         + "Applies from the next session."
 
+    #if os(iOS)
+    static let deviceRumbleFooter =
+        "Rumble on this iPhone plays player 1's rumble on the phone's own Taptic Engine as "
+        + "well — for clip-on controllers that have no rumble motors of their own. Applies "
+        + "from the next session."
+    #endif
+
     #if !os(tvOS)
     static let gamepadUIFooter =
         "When a controller connects, the host list and library switch to a controller-"
@@ -133,8 +140,10 @@ extension SettingsView {
                 .foregroundStyle(.secondary)
             }
             Spacer()
-            if gamepads.active?.id == controller.id {
-                Text("In use")
+            // Every forwarded controller is surfaced (not just the primary `active`) with its
+            // wire pad index as a player number — a pin forwards only one, Automatic forwards all.
+            if let pad = gamepads.padIndex(for: controller) {
+                Text("Player \(pad + 1)")
                     .font(.geist(11, .semibold, relativeTo: .caption2))
                     .padding(.horizontal, 8)
                     .padding(.vertical, 3)

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

@@ -21,6 +21,10 @@ struct SettingsView: View {
     @AppStorage(DefaultsKey.streamWidth) var width = 1920
     @AppStorage(DefaultsKey.streamHeight) var height = 1080
     @AppStorage(DefaultsKey.streamHz) var hz = 60
+    // Opt-in (default OFF): the explicit mode below is used and never auto-resized. When ON, a
+    // windowed session instead streams at the window's native pixels (1:1, no scaling) so it stays
+    // pixel-exact rather than the presenter resampling a fixed-mode frame into the window.
+    @AppStorage(DefaultsKey.matchWindow) var matchWindow = false
     @AppStorage(DefaultsKey.compositor) var compositor = 0
     @AppStorage(DefaultsKey.gamepadType) var gamepadType = 0
     @AppStorage(DefaultsKey.bitrateKbps) var bitrateKbps = 0
@@ -44,12 +48,14 @@ struct SettingsView: View {
     @AppStorage(DefaultsKey.hudPlacement) var hudPlacement = HUDPlacement.topTrailing.rawValue
     @ObservedObject var gamepads = GamepadManager.shared
     @AppStorage(DefaultsKey.gamepadUIEnabled) var gamepadUIEnabled = true
+    @AppStorage(DefaultsKey.autoWake) var autoWakeEnabled = true
     #if DEBUG && !os(tvOS)
     @State var showControllerTest = false
     #endif
     #if os(iOS)
     @AppStorage(DefaultsKey.pointerCapture) var pointerCapture = true
     @AppStorage(DefaultsKey.touchMode) var touchMode = TouchInputMode.trackpad.rawValue
+    @AppStorage(DefaultsKey.rumbleOnDevice) var rumbleOnDevice = false
     // The sidebar selection drives the detail pane on iPad and the pushed sub-page on iPhone.
     // Width class decides the initial value: nil on iPhone (show the category list first),
     // General on iPad (a two-column layout should never open with an empty detail).
@@ -105,6 +111,7 @@ struct SettingsView: View {
             Form {
                 streamModeSection
                 compositorSection
+                wakeSection
             }
             .formStyle(.grouped)
             .tabItem { Label("General", systemImage: "gearshape") }
@@ -234,6 +241,7 @@ struct SettingsView: View {
                 streamModeSection
                 pointerSection
                 compositorSection
+                wakeSection
             }
             .formStyle(.grouped)
             .navigationTitle("General")
@@ -304,6 +312,10 @@ struct SettingsView: View {
         Binding(get: { gamepadUIEnabled ? "on" : "off" }, set: { gamepadUIEnabled = $0 == "on" })
     }
 
+    private var autoWakeEnabledTag: Binding<String> {
+        Binding(get: { autoWakeEnabled ? "on" : "off" }, set: { autoWakeEnabled = $0 == "on" })
+    }
+
     private var tvBody: some View {
         let currentTag = "\(width)x\(height)x\(hz)"
         let bounds = UIScreen.main.nativeBounds
@@ -343,9 +355,13 @@ struct SettingsView: View {
                 TVSelectionRow(
                     title: "10-bit HDR",
                     options: [("On", "on"), ("Off", "off")], selection: hdrEnabledTag)
+                TVSelectionRow(
+                    title: "Auto-wake on connect",
+                    options: [("On", "on"), ("Off", "off")], selection: autoWakeEnabledTag)
                 Text("The host creates a virtual output at exactly this mode — native "
                     + "resolution, no scaling. \(Self.bitrateFooter) A specific compositor "
-                    + "is honored only if available on the host.")
+                    + "is honored only if available on the host. Auto-wake sends Wake-on-LAN to a "
+                    + "sleeping saved host and waits for it before streaming.")
                     .font(.geist(20, relativeTo: .caption))
                     .foregroundStyle(.secondary)
                     .multilineTextAlignment(.center)

clients/apple/Sources/PunktfunkKit/Connection/InputEvents.swift

@@ -59,6 +59,26 @@ public extension PunktfunkInputEvent {
         make(PUNKTFUNK_INPUT_KIND_GAMEPAD_AXIS.rawValue, code: axis, x: value, y: 0, flags: pad)
     }
 
+    /// Declare a pad's controller KIND (`InputKind::GamepadArrival`): `pref` is the
+    /// `GamepadType` wire byte (Auto=0, Xbox360=1, DualSense=2, XboxOne=3, DualShock4=4,
+    /// SteamController=5, SteamDeck=6), `pad` the wire index. Sent once when a controller slot
+    /// opens — BEFORE that pad's first input — so the host builds a matching virtual device and a
+    /// session can mix types (pad 0 a DualSense, pad 1 an Xbox pad). The core re-sends it a few
+    /// times against datagram loss and folds per-pad state behind it; a host that predates the tag
+    /// ignores it and uses the session-default kind from the handshake. Idempotent on the host.
+    static func gamepadArrival(pref: UInt32, pad: UInt32) -> PunktfunkInputEvent {
+        make(PUNKTFUNK_INPUT_KIND_GAMEPAD_ARRIVAL.rawValue, code: pref, x: 0, y: 0, flags: pad)
+    }
+
+    /// A pad disconnected (`InputKind::GamepadRemove`): `flags` = pad index. The client sends the
+    /// bare index; the core stamps the per-pad removal seq (`encode_gamepad_remove`) in the shared
+    /// snapshot seq space and arms a loss-resistant re-send burst, so the host tears the pad's
+    /// virtual device down and no reordered snapshot can resurrect it. A host that predates the tag
+    /// ignores it (the pad then lingers until session end — the pre-existing behaviour).
+    static func gamepadRemove(pad: UInt32) -> PunktfunkInputEvent {
+        make(PUNKTFUNK_INPUT_KIND_GAMEPAD_REMOVE.rawValue, code: 0, x: 0, y: 0, flags: pad)
+    }
+
     // Touch (host-side: libei ei_touchscreen on the virtual output). `id` distinguishes
     // fingers and is reusable after touchUp; coordinates are absolute pixels on the
     // client's touch surface, whose size rides in `flags` so the host can rescale —

clients/apple/Sources/PunktfunkKit/Connection/PunktfunkConnection.swift

@@ -70,19 +70,10 @@ func withOptionalCString<R>(_ s: String?, _ body: (UnsafePointer<CChar>?) -> R)
 public extension PunktfunkConnection {
     /// Whether the Wake-on-LAN broadcast path is usable on this platform/build. macOS can always
     /// broadcast (its App Sandbox network entitlements cover it). iOS/tvOS need the managed
-    /// `com.apple.developer.networking.multicast` entitlement, which is GATED pending Apple's
-    /// approval (see `Config/Punktfunk.entitlements`) — until it's granted, sending a broadcast is
-    /// blocked by the OS, so the wake path + its UI are gated off there to avoid a dead action.
-    /// The MAC-learning path stays active on every platform, so flipping this on once the
-    /// entitlement lands makes wake work immediately. ON APPROVAL: change `#if os(macOS)` below to
-    /// `true` for iOS/tvOS too (and uncomment the entitlement).
-    static var wakeOnLANAvailable: Bool {
-        #if os(macOS)
-        return true
-        #else
-        return false
-        #endif
-    }
+    /// `com.apple.developer.networking.multicast` entitlement — now approved and enabled (see
+    /// `Config/Punktfunk.entitlements`), so wake is available on every platform. Kept as the single
+    /// switch every call site gates on, should a future build ever need to disable it.
+    static var wakeOnLANAvailable: Bool { true }
 
     /// Send a Wake-on-LAN magic packet to wake a sleeping host. `macs` are the host's NIC MAC(s)
     /// (`aa:bb:cc:dd:ee:ff`, learned from its mDNS `mac` TXT while awake); malformed entries are
@@ -197,6 +188,14 @@ public final class PunktfunkConnection {
         // exist so the resolved type round-trips and name parsing matches the host.
         case steamController = 5
         case steamDeck = 6
+        /// DualSense Edge (Linux UHID / Windows UMDF hosts): the DualSense plus native back/Fn
+        /// buttons. GameController exposes the Edge as a `GCDualSenseGamepad` with its own
+        /// product category; paddle CAPTURE is still gated on G22, but the declared identity +
+        /// rich planes match the physical pad.
+        case dualSenseEdge = 7
+        /// Nintendo Switch Pro Controller (Linux UHID hid-nintendo hosts): correct Nintendo
+        /// glyphs + positional layout on the host side.
+        case switchPro = 8
 
         /// Loose name parsing for env/dev hooks, mirroring the host's
         /// `GamepadPref::from_name`.
@@ -209,6 +208,9 @@ public final class PunktfunkConnection {
             case "dualshock4", "dualshock", "ds4", "ps4": self = .dualShock4
             case "steamdeck", "steam-deck", "deck": self = .steamDeck
             case "steamcontroller", "steam-controller", "steamcon": self = .steamController
+            case "dualsenseedge", "dualsense-edge", "edge", "dsedge": self = .dualSenseEdge
+            case "switchpro", "switch-pro", "switch", "procontroller", "pro-controller":
+                self = .switchPro
             default: return nil
             }
         }
@@ -445,6 +447,35 @@ public final class PunktfunkConnection {
         _ = punktfunk_connection_request_keyframe(h)
     }
 
+    /// Feed each received AU's `frameIndex` (in receive order) so the client recovers from loss with a
+    /// cheap reference-frame invalidation instead of always paying for a full IDR. On a forward gap —
+    /// a `frameIndex` jump means the intervening frames were lost and the following AUs reference a
+    /// picture that never arrived — the core fires a THROTTLED RFI request for the lost range, and an
+    /// RFI-capable host (AMD LTR / NVENC) recovers with a clean P-frame rather than a 20-40× IDR
+    /// spike. Call it for every received AU; the `framesDropped`-driven `requestKeyframe()` path stays
+    /// the backstop for when the recovery frame itself is lost. Cheap; silently dropped after close.
+    public func noteFrameIndex(_ frameIndex: UInt32) {
+        abiLock.lock()
+        defer { abiLock.unlock() }
+        guard let h = handle, !closeRequested else { return }
+        _ = punktfunk_connection_note_frame_index(h, frameIndex, nil)
+    }
+
+    /// Like `noteFrameIndex`, but also reports whether the core saw a FORWARD frame-index gap — the
+    /// signal that intervening frames were lost and the following AUs reference a picture that never
+    /// arrived. The post-loss re-anchor gate arms its display freeze on a gap (the earliest, most
+    /// precise loss trigger — ahead of the `framesDropped` climb). Same core side effect as
+    /// `noteFrameIndex` (the throttled RFI request); call it for every received AU. Returns false
+    /// after close.
+    public func noteFrameIndexGap(_ frameIndex: UInt32) -> Bool {
+        abiLock.lock()
+        defer { abiLock.unlock() }
+        guard let h = handle, !closeRequested else { return false }
+        var gap = false
+        _ = punktfunk_connection_note_frame_index(h, frameIndex, &gap)
+        return gap
+    }
+
     /// Cumulative access units the host→client reassembler dropped as unrecoverable (FEC couldn't
     /// rebuild them). The video pump polls this and calls `requestKeyframe()` when it climbs — the
     /// correct loss trigger under the host's infinite GOP, where unrecoverable loss yields

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

@@ -1,24 +1,33 @@
-// Gamepad capture → punktfunk/1 datagrams. Forwards exactly ONE controller — whatever
-// GamepadManager selected — as pad 0, for the lifetime of a streaming session.
+// Gamepad capture → punktfunk/1 datagrams. Forwards EVERY controller GamepadManager selected —
+// each on its own stable wire pad index (pf-client-core's slot model) — for the lifetime of a
+// streaming session. One physical controller with no pin is player 0 (byte-identical to the old
+// single-pad path); a pin forwards only that one, also as pad 0.
 //
-// The wire is incremental (one button/axis transition per 18-byte event, accumulated
-// host-side into the virtual pad — see punktfunk_core::input::gamepad), so we snapshot the
-// full GCExtendedGamepad state on every valueChanged and diff against the previous
-// snapshot. Sticks are ±32767 with +y = up (GC already matches, no flip), triggers 0...255.
+// Each forwarded controller gets a `Slot`: its open GC handlers plus the wire state (buttons,
+// axes, touchpad fingers, motion throttle) for its pad index — isolated per device so two
+// controllers never clobber each other. On connect a slot opens (GamepadArrival declares its
+// kind, then input flows); on disconnect / pin change / stop it closes (held state flushed to
+// rest on the wire, then GamepadRemove tells the host to tear the pad's virtual device down).
+//
+// The wire is incremental (one button/axis transition per 18-byte event, accumulated host-side
+// into the virtual pad — see punktfunk_core::input::gamepad), so we snapshot the full
+// GCExtendedGamepad state on every valueChanged and diff against the previous snapshot. Sticks
+// are ±32767 with +y = up (GC already matches, no flip), triggers 0...255. The core folds these
+// per-pad transitions into idempotent, sequence-numbered snapshots keyed on the same pad index,
+// so all this layer must get right is the index — one controller per slot, one slot per index.
 //
 // PlayStation-pad extras ride the rich-input plane (0xCC): touchpad contacts normalized
-// 0...65535 (origin top-left, +y down — GC's ±1/+y-up is converted here) and motion
-// samples in raw DualSense sensor units (gyro 20 LSB per deg/s, accel 10000 LSB per g —
-// derived from the host's fixed calibration blob; the conversion lives in ONE place,
-// `Wire`, so a live sign/scale correction is a one-line change). The host ignores both
-// unless the session's virtual pad is a DualSense or DualShock 4 — both carry a touchpad
-// and motion, so the capture below covers either (`GCDualShockGamepad` exposes the same
-// `touchpad*` surface as `GCDualSenseGamepad`).
+// 0...65535 (origin top-left, +y down — GC's ±1/+y-up is converted here) and motion samples in
+// raw DualSense sensor units (gyro 20 LSB per deg/s, accel 10000 LSB per g — derived from the
+// host's fixed calibration blob; the conversion lives in ONE place, `Wire`, so a live sign/scale
+// correction is a one-line change). The host ignores both unless a pad's virtual device is a
+// DualSense or DualShock 4 — both carry a touchpad and motion, so the capture below covers either
+// (`GCDualShockGamepad` exposes the same `touchpad*` surface as `GCDualSenseGamepad`).
 //
-// Unlike mouse/keyboard capture, gamepad forwarding is NOT gated on the mouse-capture
-// toggle — a controller can't click local UI, so it always drives the host while the app
-// is active. On deactivation, controller switch, or stop, every held control is released
-// on the wire (the host pad would otherwise stay stuck on the last state).
+// Unlike mouse/keyboard capture, gamepad forwarding is NOT gated on the mouse-capture toggle — a
+// controller can't click local UI, so it always drives the host while the app is active. On
+// deactivation, controller switch, or stop, every held control is released on the wire (the host
+// pad would otherwise stay stuck on the last state).
 
 #if os(macOS)
 import AppKit
@@ -33,17 +42,35 @@ import GameController
 public final class GamepadCapture {
     private let connection: PunktfunkConnection
     private let manager: GamepadManager
-    private var activeSub: AnyCancellable?
+    private var forwardedSub: AnyCancellable?
     private var observers: [NSObjectProtocol] = []
-    private var bound: GCController?
     /// App inactive → GC stops delivering; everything is released and stays silent.
     private var suspended = false
 
-    // Last wire state (the diff base — also what releaseAll() unwinds).
-    private var buttons: UInt32 = 0
-    private var axes: [Int32] = [0, 0, 0, 0, 0, 0]
-    private var fingerActive: [Bool] = [false, false]
-    private var lastMotionNs: UInt64 = 0
+    /// One forwarded controller: the open device plus the last wire state for its pad index (the
+    /// diff base — also what `flush` unwinds). Held per Slot so two controllers never clobber each
+    /// other's held buttons/axes/fingers. Mirrors pf-client-core's `Slot`.
+    private final class Slot {
+        let controller: GCController
+        /// Wire pad index (GamepadManager's stable lowest-free assignment), threaded onto every
+        /// event this controller sends — the low byte of `flags`.
+        let pad: UInt32
+        /// The controller KIND declared to the host (GamepadArrival) when the slot opened.
+        let pref: PunktfunkConnection.GamepadType
+        var buttons: UInt32 = 0
+        var axes: [Int32] = [0, 0, 0, 0, 0, 0]
+        var fingerActive: [Bool] = [false, false]
+        var lastMotionNs: UInt64 = 0
+        init(controller: GCController, pad: UInt32, pref: PunktfunkConnection.GamepadType) {
+            self.controller = controller
+            self.pad = pad
+            self.pref = pref
+        }
+    }
+
+    /// Open forwarded controllers, one Slot per physical pad on its own wire index. Reconciled
+    /// against `manager.forwarded` (empty until a session's `start`, cleared by `stop`).
+    private var slots: [Slot] = []
 
     /// Motion forwarding floor: ≥ 4 ms between samples (≈ 250 Hz, the DualSense's own rate).
     private static let motionIntervalNs: UInt64 = 4_000_000
@@ -71,10 +98,14 @@ public final class GamepadCapture {
     }
 
     public func start() {
-        // Fires immediately with the current selection, then on every change — a switch
-        // releases the old controller's wire state before the new one takes over.
-        activeSub = manager.$active.sink { [weak self] dc in
-            MainActor.assumeIsolated { self?.rebind(to: dc?.controller) }
+        // Session-scoped index assignment: a controller pinned before the session forwards as
+        // pad 0 (pf-client-core assigns indices at slot-open time, not app-launch time).
+        manager.resetForwardingAssignment()
+        // Fires immediately with the current forwarded set, then on every change — a connect,
+        // disconnect, or pin change reconciles the open slots against it (opening/closing devices
+        // and flushing wire state so nothing sticks down).
+        forwardedSub = manager.$forwarded.sink { [weak self] list in
+            MainActor.assumeIsolated { self?.reconcile(list) }
         }
         #if os(macOS)
         let resign = NSApplication.willResignActiveNotification
@@ -97,53 +128,56 @@ public final class GamepadCapture {
             MainActor.assumeIsolated {
                 guard let self else { return }
                 self.suspended = false
-                if let ext = self.bound?.extendedGamepad { self.sync(ext) }
+                // Re-send every open pad's current state (GC delivered nothing while inactive).
+                for slot in self.slots {
+                    if let ext = slot.controller.extendedGamepad { self.sync(slot, ext) }
+                }
             }
         })
     }
 
     public func stop() {
-        releaseAll()
-        rebind(to: nil)
-        activeSub = nil
+        closeAllSlots()
+        forwardedSub = nil
         observers.forEach { NotificationCenter.default.removeObserver($0) }
         observers.removeAll()
     }
 
-    private func rebind(to controller: GCController?) {
-        guard controller !== bound else { return }
-        releaseAll()
-        if let ext = bound?.extendedGamepad {
-            ext.valueChangedHandler = nil
-            let tp = Self.touchpad(ext)
-            tp?.primary.valueChangedHandler = nil
-            tp?.secondary.valueChangedHandler = nil
+    /// Bring `slots` in line with the forwarded set: close any slot no longer wanted (flushing its
+    /// held wire state and sending GamepadRemove first) and open any newly-forwarded controller into
+    /// its assigned wire index. A controller that stays forwarded keeps its slot untouched, so a
+    /// second pad connecting never disturbs the first. Mirrors pf-client-core's `reconcile_slots`.
+    private func reconcile(_ forwarded: [GamepadManager.DiscoveredController]) {
+        let wantIDs = Set(forwarded.map { ObjectIdentifier($0.controller) })
+        for slot in slots where !wantIDs.contains(ObjectIdentifier(slot.controller)) {
+            closeSlot(slot)
         }
-        // Hand the system gestures back to the OS before letting the old pad go — outside a
-        // stream the share button's screenshot and the Home overlay are the user's, not ours.
-        if let old = bound {
-            for element in old.physicalInputProfile.elements.values {
-                element.preferredSystemGestureState = .enabled
-            }
+        for dc in forwarded where !slots.contains(where: { $0.controller === dc.controller }) {
+            openSlot(dc)
         }
-        if let motion = bound?.motion {
-            motion.valueChangedHandler = nil
-            // Power the sensors back down — left active they keep the pad streaming
-            // gyro/accel over Bluetooth (battery drain) long after the session.
-            if motion.sensorsRequireManualActivation { motion.sensorsActive = false }
-        }
-        bound = controller
-        guard let c = controller, let ext = c.extendedGamepad else { return }
+        // A chord-holding pad may have just unplugged — re-evaluate so a stale hold disarms.
+        updateEscapeChord()
+    }
 
-        ext.valueChangedHandler = { [weak self] g, _ in
-            MainActor.assumeIsolated { self?.sync(g) }
+    /// Open one forwarded controller on its assigned wire index: attach GC handlers, claim its
+    /// system gestures, declare its kind (GamepadArrival — before any input), then wake the host
+    /// pad and send its initial state. Skipped when the pad has no wire index (every slot taken)
+    /// or exposes no extended profile.
+    private func openSlot(_ dc: GamepadManager.DiscoveredController) {
+        guard let pad = manager.padIndex(for: dc), let ext = dc.controller.extendedGamepad else { return }
+        let c = dc.controller
+        let slot = Slot(controller: c, pad: UInt32(pad), pref: dc.kind)
+        slots.append(slot)
+
+        ext.valueChangedHandler = { [weak self, weak slot] g, _ in
+            MainActor.assumeIsolated { if let self, let slot { self.sync(slot, g) } }
         }
         // Claim EVERY element's system gesture while this pad drives a stream. The OS attaches
         // gestures to several controller buttons — share/create → local screenshot/recording,
         // Home → Game Center overlay (iOS) / Launchpad's Games folder (macOS) — and with a
         // 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 unbind.
+        // the PS button must open the host's Steam overlay. Restored to .enabled on close.
         for element in c.physicalInputProfile.elements.values {
             element.preferredSystemGestureState = .disabled
         }
@@ -153,67 +187,114 @@ public final class GamepadCapture {
         // `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.
         if let home = c.physicalInputProfile.buttons[GCInputButtonHome] {
-            home.pressedChangedHandler = { [weak self] _, _, pressed in
-                MainActor.assumeIsolated { self?.sendGuide(down: pressed) }
+            home.pressedChangedHandler = { [weak self, weak slot] _, _, pressed in
+                MainActor.assumeIsolated { if let self, let slot { self.sendGuide(slot, down: pressed) } }
             }
         }
-        // Wake the host pad immediately (pads are created lazily from the first event;
-        // a DualSense's UHID handshake + initial lightbar write only start then).
-        connection.send(.gamepadAxis(GamepadWire.axisLSX, value: 0, pad: 0))
-        sync(ext)
+        // Declare this pad's controller KIND before any of its input, so the host builds a
+        // matching virtual device (mixed types — pad 0 a DualSense, pad 1 an Xbox pad). The core
+        // re-sends it a few times against datagram loss; an older host ignores it and uses the
+        // session-default kind. Then wake the host pad (pads are created lazily from the first
+        // event; a DualSense's UHID handshake + initial lightbar write only start then).
+        connection.send(.gamepadArrival(pref: slot.pref.rawValue, pad: slot.pad))
+        connection.send(.gamepadAxis(GamepadWire.axisLSX, value: 0, pad: slot.pad))
+        sync(slot, ext)
 
         if let tp = Self.touchpad(ext) {
-            tp.primary.valueChangedHandler = { [weak self] _, x, y in
-                MainActor.assumeIsolated { self?.touch(finger: 0, x: x, y: y) }
+            tp.primary.valueChangedHandler = { [weak self, weak slot] _, x, y in
+                MainActor.assumeIsolated { if let self, let slot { self.touch(slot, finger: 0, x: x, y: y) } }
             }
-            tp.secondary.valueChangedHandler = { [weak self] _, x, y in
-                MainActor.assumeIsolated { self?.touch(finger: 1, x: x, y: y) }
+            tp.secondary.valueChangedHandler = { [weak self, weak slot] _, x, y in
+                MainActor.assumeIsolated { if let self, let slot { self.touch(slot, finger: 1, x: x, y: y) } }
             }
         }
         if let motion = c.motion {
             if motion.sensorsRequireManualActivation { motion.sensorsActive = true }
-            motion.valueChangedHandler = { [weak self] m in
-                MainActor.assumeIsolated { self?.forwardMotion(m) }
+            motion.valueChangedHandler = { [weak self, weak slot] m in
+                MainActor.assumeIsolated { if let self, let slot { self.forwardMotion(slot, m) } }
             }
         }
     }
 
-    /// Snapshot the profile into wire state and send every transition since the last one.
-    private func sync(_ g: GCExtendedGamepad) {
+    /// Flush a slot's held wire state (so nothing sticks down host-side) and signal the host to tear
+    /// its virtual device down (GamepadRemove), then detach GC handlers, hand the system gestures
+    /// back, and power the sensors down. Wire-only until the GC cleanup, so it is safe even when the
+    /// device already physically unplugged. Mirrors pf-client-core's `close_slot_at`.
+    private func closeSlot(_ slot: Slot) {
+        flush(slot)
+        // Sent after the flush so the core stamps it with a seq past the zeroing snapshots; the host
+        // seq-gates it, so a reordered snapshot can't resurrect the removed pad.
+        connection.send(.gamepadRemove(pad: slot.pad))
+        let c = slot.controller
+        if let ext = c.extendedGamepad {
+            ext.valueChangedHandler = nil
+            let tp = Self.touchpad(ext)
+            tp?.primary.valueChangedHandler = nil
+            tp?.secondary.valueChangedHandler = nil
+        }
+        c.physicalInputProfile.buttons[GCInputButtonHome]?.pressedChangedHandler = nil
+        // Hand the system gestures back to the OS before letting the pad go — outside a stream the
+        // share button's screenshot and the Home overlay are the user's, not ours.
+        for element in c.physicalInputProfile.elements.values {
+            element.preferredSystemGestureState = .enabled
+        }
+        if let motion = c.motion {
+            motion.valueChangedHandler = nil
+            // Power the sensors back down — left active they keep the pad streaming gyro/accel
+            // over Bluetooth (battery drain) long after the session.
+            if motion.sensorsRequireManualActivation { motion.sensorsActive = false }
+        }
+        slots.removeAll { $0 === slot }
+    }
+
+    private func closeAllSlots() {
+        while let slot = slots.first { closeSlot(slot) }
+        chordTimer?.invalidate()
+        chordTimer = nil
+    }
+
+    /// Snapshot the profile into a slot's wire state and send every transition since the last one,
+    /// tagged with the slot's wire pad index.
+    private func sync(_ slot: Slot, _ g: GCExtendedGamepad) {
         guard !suspended else { return }
-        let newButtons = Self.buttonMask(g)
-        updateEscapeChord(newButtons)
-        let changed = newButtons ^ buttons
+        // guide is driven separately (`sendGuide`, off the Home handler) and deliberately kept out
+        // of `buttonMask`. Preserve its current held state here so the XOR diff below never sees it
+        // 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)
+        let changed = newButtons ^ slot.buttons
         if changed != 0 {
             for bit in GamepadWire.allButtons where changed & bit != 0 {
-                connection.send(.gamepadButton(bit, down: newButtons & bit != 0, pad: 0))
+                connection.send(.gamepadButton(bit, down: newButtons & bit != 0, pad: slot.pad))
             }
-            buttons = newButtons
+            slot.buttons = newButtons
         }
         let newAxes: [Int32] = [
-            Int32((g.leftThumbstick.xAxis.value * 32767).rounded()),
-            Int32((g.leftThumbstick.yAxis.value * 32767).rounded()),
-            Int32((g.rightThumbstick.xAxis.value * 32767).rounded()),
-            Int32((g.rightThumbstick.yAxis.value * 32767).rounded()),
-            Int32((g.leftTrigger.value * 255).rounded()),
-            Int32((g.rightTrigger.value * 255).rounded()),
+            Int32(g.leftThumbstick.xAxis.value * 32767),
+            Int32(g.leftThumbstick.yAxis.value * 32767),
+            Int32(g.rightThumbstick.xAxis.value * 32767),
+            Int32(g.rightThumbstick.yAxis.value * 32767),
+            Int32(g.leftTrigger.value * 255),
+            Int32(g.rightTrigger.value * 255),
         ]
-        for (i, v) in newAxes.enumerated() where v != axes[i] {
-            connection.send(.gamepadAxis(UInt32(i), value: v, pad: 0))
-            axes[i] = v
+        for (i, v) in newAxes.enumerated() where v != slot.axes[i] {
+            connection.send(.gamepadAxis(UInt32(i), value: v, pad: slot.pad))
+            slot.axes[i] = v
         }
+        updateEscapeChord()
     }
 
     /// Forward the guide (Home/PS) transition directly — it's kept out of `buttonMask` (the legacy
-    /// `buttonHome` element is unreliable). Folds into `buttons` so a held PS button is released by
-    /// `releaseAll` on focus loss just like the others.
-    private func sendGuide(down: Bool) {
+    /// `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) {
         guard !suspended else { return }
         let bit = GamepadWire.guide
-        let now = down ? (buttons | bit) : (buttons & ~bit)
-        guard now != buttons else { return }
-        connection.send(.gamepadButton(bit, down: down, pad: 0))
-        buttons = now
+        let now = down ? (slot.buttons | bit) : (slot.buttons & ~bit)
+        guard now != slot.buttons else { return }
+        connection.send(.gamepadButton(bit, down: down, pad: slot.pad))
+        slot.buttons = now
     }
 
     private static func buttonMask(_ g: GCExtendedGamepad) -> UInt32 {
@@ -224,17 +305,21 @@ public final class GamepadCapture {
         if g.dpad.right.isPressed { b |= GamepadWire.dpadRight }
         if g.buttonMenu.isPressed { b |= GamepadWire.start }
         if g.buttonOptions?.isPressed == true { b |= GamepadWire.back }
-        // The share/create/capture element (Xbox Series share, a clone pad's screenshot button —
-        // e.g. the GameSir G8's, below its d-pad) folds into back/select too. On pads that expose
-        // the create button BOTH as buttonOptions and as the share element this OR is harmless —
-        // same wire bit.
-        if g.buttons[GCInputButtonShare]?.isPressed == true { b |= GamepadWire.back }
+        // The dedicated share/create/capture element (Xbox-Series Share, DualSense Create, a clone
+        // pad's screenshot button — e.g. the GameSir G8's, below its d-pad) → the wire's capture
+        // bit, matching the Rust client's `Button::Misc1 => wire::BTN_MISC1`. On an Xbox-Series pad
+        // this is a button physically DISTINCT from View (buttonOptions, above), so it must not
+        // collapse onto back — the host reads MISC1 as its own control (DualSense mute / Steam
+        // quick-access). Caveat: a pad that surfaces ONE physical button as both buttonOptions and
+        // this share element now emits back+misc1 for it — harmless on a plain xpad session (no
+        // misc button) and rare otherwise. NOTE: on-glass verify on a real Xbox-Series pad.
+        if g.buttons[GCInputButtonShare]?.isPressed == true { b |= GamepadWire.misc1 }
         if g.leftThumbstickButton?.isPressed == true { b |= GamepadWire.leftStickClick }
         if g.rightThumbstickButton?.isPressed == true { b |= GamepadWire.rightStickClick }
         if g.leftShoulder.isPressed { b |= GamepadWire.leftShoulder }
         if g.rightShoulder.isPressed { b |= GamepadWire.rightShoulder }
         // guide (Home/PS) is NOT read here — it's forwarded directly by the Home button's
-        // pressedChangedHandler (the legacy `buttonHome` element is unreliable). See `rebind`.
+        // pressedChangedHandler (the legacy `buttonHome` element is unreliable). See `openSlot`.
         if g.buttonA.isPressed { b |= GamepadWire.a }
         if g.buttonB.isPressed { b |= GamepadWire.b }
         if g.buttonX.isPressed { b |= GamepadWire.x }
@@ -262,29 +347,29 @@ public final class GamepadCapture {
         return nil
     }
 
-    /// One touchpad finger moved. GC reports ±1 positions and snaps to exactly (0, 0) on
-    /// lift — treated as the lift signal (a real finger landing on the precise center
+    /// One touchpad finger moved on a slot's pad. GC reports ±1 positions and snaps to exactly
+    /// (0, 0) on lift — treated as the lift signal (a real finger landing on the precise center
     /// momentarily reads as a lift; harmless for a 1-in-65k coincidence).
-    private func touch(finger: Int, x: Float, y: Float) {
+    private func touch(_ slot: Slot, finger: Int, x: Float, y: Float) {
         guard !suspended else { return }
         let lifted = x == 0 && y == 0
         if lifted {
-            if fingerActive[finger] {
-                fingerActive[finger] = false
-                connection.sendTouchpad(finger: UInt8(finger), active: false, x: 0, y: 0)
+            if slot.fingerActive[finger] {
+                slot.fingerActive[finger] = false
+                connection.sendTouchpad(pad: UInt8(slot.pad), finger: UInt8(finger), active: false, x: 0, y: 0)
             }
             return
         }
-        fingerActive[finger] = true
+        slot.fingerActive[finger] = true
         let w = GamepadWire.touchpad(x: x, y: y)
-        connection.sendTouchpad(finger: UInt8(finger), active: true, x: w.x, y: w.y)
+        connection.sendTouchpad(pad: UInt8(slot.pad), finger: UInt8(finger), active: true, x: w.x, y: w.y)
     }
 
-    private func forwardMotion(_ m: GCMotion) {
+    private func forwardMotion(_ slot: Slot, _ m: GCMotion) {
         guard !suspended else { return }
         let now = DispatchTime.now().uptimeNanoseconds
-        guard now &- lastMotionNs >= Self.motionIntervalNs else { return }
-        lastMotionNs = now
+        guard now &- slot.lastMotionNs >= Self.motionIntervalNs else { return }
+        slot.lastMotionNs = now
         // Total acceleration in g: gravity + user when split, else the raw vector.
         let ax: Float
         let ay: Float
@@ -301,6 +386,7 @@ public final class GamepadCapture {
         let gs = GamepadWire.gyroLSBPerRadS
         let as_ = GamepadWire.accelLSBPerG
         connection.sendMotion(
+            pad: UInt8(slot.pad),
             gyro: (
                 GamepadWire.motionRaw(Float(m.rotationRate.x), scale: gs),
                 GamepadWire.motionRaw(Float(m.rotationRate.y), scale: gs),
@@ -313,13 +399,12 @@ public final class GamepadCapture {
             ))
     }
 
-    /// Unwind everything held on the wire: button-ups, neutral axes, lifted fingers. The
-    /// host's virtual pad returns to rest instead of running with the last state.
-    /// Arm the disconnect timer when the full chord lands, disarm the moment any of the four
-    /// releases. Events only arrive on state CHANGES, so a held chord needs the timer — the
-    /// handler won't fire again until something moves.
-    private func updateEscapeChord(_ newButtons: UInt32) {
-        let held = newButtons & Self.escapeChord == Self.escapeChord
+    /// Arm the disconnect timer when ANY forwarded pad holds the full escape chord, disarm the
+    /// moment none do — a release, or the holding pad unplugged (pf-client-core's `chord_held` is
+    /// likewise any-slot). GC events only arrive on state CHANGES, so a held chord needs the timer:
+    /// the handler won't fire again until something moves.
+    private func updateEscapeChord() {
+        let held = slots.contains { $0.buttons & Self.escapeChord == Self.escapeChord }
         if held, chordTimer == nil {
             let timer = Timer(timeInterval: Self.disconnectHold, repeats: false) { [weak self] _ in
                 Task { @MainActor in self?.onDisconnectRequest?() }
@@ -332,20 +417,31 @@ public final class GamepadCapture {
         }
     }
 
+    /// Unwind everything a slot holds on the wire: button-ups, neutral axes, lifted fingers. The
+    /// host's virtual pad returns to rest instead of running with the last state. Wire events only
+    /// (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) {
+        for bit in GamepadWire.allButtons where slot.buttons & bit != 0 {
+            connection.send(.gamepadButton(bit, down: false, pad: slot.pad))
+        }
+        slot.buttons = 0
+        for (i, v) in slot.axes.enumerated() where v != 0 {
+            connection.send(.gamepadAxis(UInt32(i), value: 0, pad: slot.pad))
+            slot.axes[i] = 0
+        }
+        for (f, active) in slot.fingerActive.enumerated() where active {
+            connection.sendTouchpad(pad: UInt8(slot.pad), finger: UInt8(f), active: false, x: 0, y: 0)
+            slot.fingerActive[f] = false
+        }
+    }
+
+    /// Flush every open slot's held state (app deactivation) — keeps the slots open (GC just stops
+    /// delivering; resume re-syncs), disarms the escape chord. Distinct from `closeAllSlots`, which
+    /// also sends GamepadRemove and detaches handlers.
     private func releaseAll() {
         chordTimer?.invalidate()
         chordTimer = nil
-        for bit in GamepadWire.allButtons where buttons & bit != 0 {
-            connection.send(.gamepadButton(bit, down: false, pad: 0))
-        }
-        buttons = 0
-        for (i, v) in axes.enumerated() where v != 0 {
-            connection.send(.gamepadAxis(UInt32(i), value: 0, pad: 0))
-            axes[i] = 0
-        }
-        for (f, active) in fingerActive.enumerated() where active {
-            connection.sendTouchpad(finger: UInt8(f), active: false, x: 0, y: 0)
-            fingerActive[f] = false
-        }
+        for slot in slots { flush(slot) }
     }
 }

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

@@ -1,47 +1,82 @@
 // Host→client gamepad feedback rendering: one drain thread polls the rumble (0xCA) and
-// HID-output (0xCD) planes and replays them on the active physical controller —
+// HID-output (0xCD) planes and replays each update on the forwarded physical controller it is
+// ADDRESSED TO by wire pad index —
 //
 //   rumble        → CHHapticEngine players (per-handle localities when the pad has them,
-//                   one combined engine otherwise),
+//                   one combined engine otherwise), a RumbleRenderer per pad,
 //   lightbar      → GCDeviceLight,
 //   player LEDs   → GCController.playerIndex (the DS bit patterns map to player 1–4),
 //   trigger FX    → DualSenseTriggerEffect.parse → GCDualSenseAdaptiveTrigger.
 //
-// Only pad 0 is rendered (exactly one controller is forwarded). HID-output traffic exists
-// only on PlayStation-pad sessions (a DualSense, or a DualShock 4 = lightbar only) — the
-// drain always polls both planes with short timeouts and never spins, so an Xbox session
-// just renders rumble. GameController profile mutation
-// happens on main; CHHapticEngine work on its own serial queue; the drain thread itself
-// touches neither. When GamepadManager switches the active controller mid-session, the
-// old pad is reset (triggers off, player index unset) and the last known feedback state
-// is replayed onto the new one.
+// Every forwarded controller gets a per-pad feedback slot (its RumbleRenderer + last light /
+// player-LED / trigger state) keyed on the same wire index GamepadCapture streams it on, so a
+// rumble the host aimed at pad 1 drives pad 1's actuator and nothing else. An update for a pad
+// with no live slot (one that just closed) is dropped. HID-output traffic exists only on
+// PlayStation-pad sessions (a DualSense, or a DualShock 4 = lightbar only); the drain always
+// polls both planes with short timeouts and never spins, so an Xbox pad just renders rumble.
+// GameController profile mutation happens on main; CHHapticEngine work on the renderer's serial
+// queue; the drain thread itself touches neither (it routes rumble to the pad's renderer under a
+// lock and hops HID to main). When a controller leaves the forwarded set the old pad is reset
+// (triggers off, player index unset) and its renderer silenced.
 
 import Combine
+import CoreHaptics
 import Foundation
 import GameController
 
 public final class GamepadFeedback {
     private let connection: PunktfunkConnection
+    private let manager: GamepadManager
     private let flag = StopFlag()
     private let drainDone = DispatchSemaphore(value: 0)
     private var drainStarted = false
-    private let rumble = RumbleRenderer(policy: .session)
-    private var activeSub: AnyCancellable?
+    private var forwardedSub: AnyCancellable?
 
-    // Last applied feedback (main-actor) — replayed when the active controller changes.
-    @MainActor private var target: GCController?
-    @MainActor private var lastLight: (r: UInt8, g: UInt8, b: UInt8)?
-    @MainActor private var lastPlayerBits: UInt8?
-    @MainActor private var lastTrigger: [DualSenseTriggerEffect?] = [nil, nil]
+    /// One forwarded controller's non-rumble feedback state (main-actor) — the GC target plus the
+    /// last applied lightbar / player-LED / trigger, replayed if the controller on this pad swaps.
+    @MainActor private final class Slot {
+        var controller: GCController?
+        var lastLight: (r: UInt8, g: UInt8, b: UInt8)?
+        var lastPlayerBits: UInt8?
+        var lastTrigger: [DualSenseTriggerEffect?] = [nil, nil]
+        init(controller: GCController?) { self.controller = controller }
+    }
+    /// HID / lightbar / player-LED slots, keyed by wire pad index. Main-actor only.
+    @MainActor private var slots: [UInt8: Slot] = [:]
+
+    /// Rumble renderers keyed by wire pad index, guarded by `routingLock` so the background drain
+    /// thread can route an incoming envelope to the right pad's renderer while the main actor
+    /// reconciles the set. RumbleRenderer serializes on its own queue, so calling `apply` from the
+    /// drain thread is safe — only the map lookup needs the lock.
+    private let routingLock = NSLock()
+    private var rumbleByPad: [UInt8: RumbleRenderer] = [:]
+
+    /// Opt-in device mirror (`DefaultsKey.rumbleOnDevice`, iPhone only): rumble the host
+    /// addresses to controller 1 (wire pad 0) is ALSO rendered on this device's own Taptic
+    /// Engine — for phone-clip pads that ship without rumble motors, where the phone body is the
+    /// only actuator in the player's hands. Session-scoped (the setting is read once here); nil
+    /// when off or where the device has no haptic actuator.
+    private let deviceRumble: RumbleRenderer?
 
     public init(connection: PunktfunkConnection, manager: GamepadManager) {
         self.connection = connection
+        self.manager = manager
+        #if os(iOS)
+        if UserDefaults.standard.bool(forKey: DefaultsKey.rumbleOnDevice),
+            CHHapticEngine.capabilitiesForHardware().supportsHaptics {
+            deviceRumble = RumbleRenderer(policy: .session, actuator: .device)
+        } else {
+            deviceRumble = nil
+        }
+        #else
+        deviceRumble = nil
+        #endif
         // Capture self weakly in the hop too, so the inner sink's weak capture isn't shadowing
         // an implicit strong one — and the subscription (stored on self) never retain-cycles.
         Task { @MainActor [weak self] in
             guard let self else { return }
-            self.activeSub = manager.$active.sink { [weak self] dc in
-                MainActor.assumeIsolated { self?.retarget(dc?.controller) }
+            self.forwardedSub = manager.$forwarded.sink { [weak self] list in
+                MainActor.assumeIsolated { self?.reconcile(list) }
             }
         }
     }
@@ -67,6 +102,38 @@ public final class GamepadFeedback {
         }
     }
 
+    /// Bring the per-pad feedback slots in line with the forwarded set: drop pads no longer
+    /// forwarded (silence + release their renderer, reset their controller), add a slot +
+    /// renderer for each new pad, and retarget a pad whose controller changed (a re-plug into the
+    /// same freed index) — replaying its cached feedback onto the new device.
+    @MainActor
+    private func reconcile(_ forwarded: [GamepadManager.DiscoveredController]) {
+        var want: [UInt8: GCController] = [:]
+        for dc in forwarded {
+            if let pad = manager.padIndex(for: dc) { want[pad] = dc.controller }
+        }
+        for (pad, slot) in slots where want[pad] == nil {
+            reset(slot.controller)
+            slots[pad] = nil
+            let renderer = withRouting { rumbleByPad.removeValue(forKey: pad) }
+            renderer?.stop()
+        }
+        for (pad, controller) in want {
+            if let slot = slots[pad] {
+                guard slot.controller !== controller else { continue }
+                reset(slot.controller)
+                slot.controller = controller
+                withRouting { rumbleByPad[pad]?.retarget(controller) }
+                replay(slot)
+            } else {
+                slots[pad] = Slot(controller: controller)
+                let renderer = RumbleRenderer(policy: .session)
+                renderer.retarget(controller)
+                withRouting { rumbleByPad[pad] = renderer }
+            }
+        }
+    }
+
     public func start() {
         guard !drainStarted else { return }
         drainStarted = true
@@ -88,19 +155,19 @@ public final class GamepadFeedback {
                     // rumble/HID latency low while leaving the lock free between polls.
                     //
                     // Rumble is idempotent state, so drain the plane DRY and apply only the newest
-                    // level. The old one-datagram-per-cycle shape let a burst outpace the ~125 Hz
-                    // drain: levels rendered up to ~130 ms late through the core's 16-deep queue,
-                    // and its drop-newest overflow could shed a stop while stale nonzero states
-                    // queued ahead of it — buzzing until the host's next 500 ms refresh.
-                    var newest: (low: UInt16, high: UInt16, ttl: UInt32)?
+                    // level PER PAD. The old one-datagram-per-cycle shape let a burst outpace the
+                    // ~125 Hz drain: levels rendered up to ~130 ms late through the core's 16-deep
+                    // queue, and its drop-newest overflow could shed a stop while stale nonzero
+                    // states queued ahead of it — buzzing until the host's next 500 ms refresh.
+                    var newestByPad: [UInt8: (low: UInt16, high: UInt16, ttl: UInt32)] = [:]
                     var rumbleBurst = 0
                     while rumbleBurst < 64, !flag.isStopped,
                           let r = try connection.nextRumble2(timeoutMs: 0) {
-                        if r.pad == 0 { newest = (r.low, r.high, r.ttlMs) }
+                        newestByPad[UInt8(truncatingIfNeeded: r.pad)] = (r.low, r.high, r.ttlMs)
                         rumbleBurst += 1
                     }
-                    if let n = newest {
-                        self?.rumble.apply(low: n.low, high: n.high, ttlMs: n.ttl)
+                    for (pad, n) in newestByPad {
+                        self?.routeRumble(pad: pad, low: n.low, high: n.high, ttlMs: n.ttl)
                     }
                     // Drain a BOUNDED burst of hidout events so sustained 0xCD traffic (a game writing
                     // per-frame LED/trigger reports) can't spin here or block stop() past one cycle.
@@ -126,7 +193,7 @@ public final class GamepadFeedback {
         thread.start()
     }
 
-    /// Stop the drain and silence the motors. Blocks until the drain thread exits (≤ one
+    /// Stop the drain and silence every pad's motors. Blocks until the drain thread exits (≤ one
     /// poll cycle) — call off the main actor, before `connection.close()`.
     public func stop() {
         flag.stop()
@@ -134,17 +201,37 @@ public final class GamepadFeedback {
             drainDone.wait()
             drainStarted = false
         }
-        rumble.stop()
-        // Drop the retarget subscription and the dead session's cached feedback — a
-        // controller change after teardown must not replay this session's triggers/LEDs.
-        Task { @MainActor in
-            self.activeSub = nil
-            self.lastLight = nil
-            self.lastPlayerBits = nil
-            self.lastTrigger = [nil, nil]
-            self.reset(self.target)
-            self.target = nil
+        let renderers = withRouting { () -> [RumbleRenderer] in
+            let r = Array(rumbleByPad.values)
+            rumbleByPad.removeAll()
+            return r
         }
+        for r in renderers { r.stop() }
+        deviceRumble?.stop()
+        // Drop the subscription and every dead pad's cached feedback — a controller change after
+        // teardown must not replay this session's triggers/LEDs.
+        Task { @MainActor in
+            self.forwardedSub = nil
+            for slot in self.slots.values { self.reset(slot.controller) }
+            self.slots.removeAll()
+        }
+    }
+
+    /// Route one rumble envelope to its pad's renderer (drain thread). An update for a pad with no
+    /// live renderer — one that just left the forwarded set — is dropped.
+    private func routeRumble(pad: UInt8, low: UInt16, high: UInt16, ttlMs: UInt32) {
+        let renderer = withRouting { rumbleByPad[pad] }
+        renderer?.apply(low: low, high: high, ttlMs: ttlMs)
+        // The opt-in device mirror follows controller 1 unconditionally — the pads it exists for
+        // have no motors (their renderer above no-ops), and mirroring deliberately isn't gated on
+        // that: capability probing can't see a motor-less MFi pad, and the user opted in.
+        if pad == 0 { deviceRumble?.apply(low: low, high: high, ttlMs: ttlMs) }
+    }
+
+    private func withRouting<R>(_ body: () -> R) -> R {
+        routingLock.lock()
+        defer { routingLock.unlock() }
+        return body()
     }
 
     private func render(_ ev: PunktfunkConnection.HidOutputEvent) {
@@ -157,40 +244,37 @@ public final class GamepadFeedback {
     private func apply(_ ev: PunktfunkConnection.HidOutputEvent) {
         switch ev {
         case let .led(pad, r, g, b):
-            guard pad == 0 else { return }
-            lastLight = (r, g, b)
-            target?.light?.color = GCColor(
+            guard let slot = slots[pad] else { return }
+            slot.lastLight = (r, g, b)
+            slot.controller?.light?.color = GCColor(
                 red: Float(r) / 255, green: Float(g) / 255, blue: Float(b) / 255)
         case let .playerLEDs(pad, bits):
-            guard pad == 0 else { return }
-            lastPlayerBits = bits
-            target?.playerIndex = Self.playerIndex(forBits: bits)
+            guard let slot = slots[pad] else { return }
+            slot.lastPlayerBits = bits
+            slot.controller?.playerIndex = Self.playerIndex(forBits: bits)
         case let .triggerEffect(pad, which, effect):
-            guard pad == 0, which < 2 else { return }
+            guard which < 2, let slot = slots[pad] else { return }
             let parsed = DualSenseTriggerEffect.parse(effect)
-            lastTrigger[Int(which)] = parsed
-            if let trigger = adaptiveTrigger(which) {
+            slot.lastTrigger[Int(which)] = parsed
+            if let trigger = adaptiveTrigger(slot.controller, which) {
                 parsed.apply(to: trigger)
             }
         }
     }
 
+    /// Replay a pad's cached feedback onto its (swapped-in) controller so a re-plug looks the same.
     @MainActor
-    private func retarget(_ controller: GCController?) {
-        guard controller !== target else { return }
-        reset(target)
-        target = controller
-        rumble.retarget(controller)
-        // Replay the session's feedback state so a swapped-in controller looks the same.
-        if let (r, g, b) = lastLight {
-            controller?.light?.color = GCColor(
+    private func replay(_ slot: Slot) {
+        if let (r, g, b) = slot.lastLight {
+            slot.controller?.light?.color = GCColor(
                 red: Float(r) / 255, green: Float(g) / 255, blue: Float(b) / 255)
         }
-        if let bits = lastPlayerBits {
-            controller?.playerIndex = Self.playerIndex(forBits: bits)
+        if let bits = slot.lastPlayerBits {
+            slot.controller?.playerIndex = Self.playerIndex(forBits: bits)
         }
         for which in 0..<2 {
-            if let effect = lastTrigger[which], let trigger = adaptiveTrigger(UInt8(which)) {
+            if let effect = slot.lastTrigger[which],
+               let trigger = adaptiveTrigger(slot.controller, UInt8(which)) {
                 effect.apply(to: trigger)
             }
         }
@@ -207,8 +291,8 @@ public final class GamepadFeedback {
     }
 
     @MainActor
-    private func adaptiveTrigger(_ which: UInt8) -> GCDualSenseAdaptiveTrigger? {
-        guard let ds = target?.extendedGamepad as? GCDualSenseGamepad else { return nil }
+    private func adaptiveTrigger(_ controller: GCController?, _ which: UInt8) -> GCDualSenseAdaptiveTrigger? {
+        guard let ds = controller?.extendedGamepad as? GCDualSenseGamepad else { return nil }
         return which == 0 ? ds.leftTrigger : ds.rightTrigger
     }
 }

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

@@ -1,14 +1,18 @@
 // Controller discovery + selection, app-lifetime. One GamepadManager (`.shared`) watches
 // GCController connect/disconnect from launch, so the Settings page shows live controller
 // state without a session, and the session components (GamepadCapture / GamepadFeedback)
-// follow `active` — exactly ONE physical controller is forwarded to the host, as pad 0.
+// follow `forwarded` — every forwarded controller is streamed to the host, each on its own
+// wire pad index (pf-client-core parity; up to `GamepadWire.maxPads`).
 //
-// Selection: the user can pin a controller in Settings (persisted under
-// DefaultsKey.gamepadID); with no pin — or the pinned one absent — the most recently
-// connected extended gamepad wins. GCController has no stable hardware serial, so the pin
-// is a fingerprint of vendorName|productCategory (+ a connect-order suffix for twins);
-// identical twin controllers may swap a pin across reconnects, which the Settings footer
-// documents.
+// Selection (mirrors pf-client-core's `forwarded_ids` + slot model): with no pin, EVERY
+// extended controller is forwarded — each assigned a stable lowest-free pad index held for
+// its forwarded lifetime, so a disconnect frees only its own index and never renumbers the
+// others. A pin (Settings, persisted under DefaultsKey.gamepadID) forwards ONLY that one pad
+// — an explicit single-player choice. `active` stays the single "primary" pad (the pinned
+// one, else the most recently connected extended gamepad) that the Settings / launcher / menu
+// UI reads. GCController has no stable hardware serial, so the pin is a fingerprint of
+// vendorName|productCategory (+ a connect-order suffix for twins); identical twin controllers
+// may swap a pin across reconnects, which the Settings footer documents.
 //
 // A singleton (not a SwiftUI environment object) because macOS shows Settings in its own
 // `Settings{}` scene — there is no common ancestor view to inject from.
@@ -38,13 +42,14 @@ public final class GamepadManager: ObservableObject {
         public let hasHaptics: Bool
         public let hasMotion: Bool
         public let hasAdaptiveTriggers: Bool
-        /// Specifically a DualSense — gates the DualSense-only feedback (adaptive triggers,
-        /// player LEDs) and the PlayStation glyph in Settings.
-        public var isDualSense: Bool { kind == .dualSense }
-        /// A PlayStation pad with a touchpad + motion (DualSense OR DualShock 4) — gates
+        /// Specifically a DualSense (incl. the Edge — same feedback surface) — gates the
+        /// DualSense-only feedback (adaptive triggers, player LEDs) and the PlayStation glyph
+        /// in Settings.
+        public var isDualSense: Bool { kind == .dualSense || kind == .dualSenseEdge }
+        /// A PlayStation pad with a touchpad + motion (DualSense family OR DualShock 4) — gates
         /// rich-input CAPTURE (touchpad contacts + gyro/accel on plane 0xCC).
         public var hasTouchpadAndMotion: Bool {
-            kind == .dualSense || kind == .dualShock4
+            kind == .dualSense || kind == .dualSenseEdge || kind == .dualShock4
         }
         /// 0...1, nil when the controller doesn't report a battery (e.g. wired).
         public let batteryLevel: Float?
@@ -60,9 +65,23 @@ public final class GamepadManager: ObservableObject {
     /// Every detected controller, in connect order (Settings lists these).
     @Published public private(set) var controllers: [DiscoveredController] = []
 
-    /// The one controller forwarded to the host (pad 0); nil when none qualifies.
+    /// The single "primary" controller — the pinned one, else the most recently connected
+    /// extended gamepad; nil when none qualifies. The Settings / launcher / menu UI and the
+    /// connect-time `resolveType` read this; the streaming input path uses `forwarded`.
     @Published public private(set) var active: DiscoveredController?
 
+    /// The controllers forwarded to the host this session, in wire-pad-index preference order
+    /// (pf-client-core's `forwarded_ids`): a pin forwards ONLY the pinned pad; Automatic forwards
+    /// every extended controller. GamepadCapture opens a slot per entry and GamepadFeedback routes
+    /// feedback back to it, each on the index from `padIndex(for:)`.
+    @Published public private(set) var forwarded: [DiscoveredController] = []
+
+    /// Stable wire pad index (0..<`GamepadWire.maxPads`) per forwarded controller, keyed by
+    /// GCController identity. Lowest-free, held while the controller stays forwarded — a
+    /// disconnect frees only its own index so the others never renumber (pf-client-core's
+    /// `lowest_free_index`). Recomputed by `assignPadIndices` whenever `forwarded` changes.
+    private var padIndexByController: [ObjectIdentifier: UInt8] = [:]
+
     /// The user's pinned controller fingerprint ("" = automatic). Persisted; updating it
     /// reselects immediately, so a Settings Picker can bind straight to this.
     @Published public var preferredID: String {
@@ -159,12 +178,57 @@ public final class GamepadManager: ObservableObject {
         let candidates = controllers.filter(\.isExtended)
         // The pin wins when present; otherwise the most recently connected extended pad
         // (list is in connect order). A stale pin falls back to automatic.
-        active = candidates.last { $0.id == preferredID } ?? candidates.last
+        let pinned = candidates.last { $0.id == preferredID }
+        active = pinned ?? candidates.last
+        // Forwarded set (pf-client-core's `forwarded_ids`): a pin forwards ONLY the pinned pad
+        // (explicit single-player); Automatic forwards every extended controller in connect order
+        // (oldest→newest), so a game's player numbers are stable across hot-plug churn.
+        let next = pinned.map { [$0] } ?? candidates
+        // Update the pad-index assignment BEFORE publishing `forwarded`: @Published emits in
+        // `willSet`, so GamepadCapture/GamepadFeedback reconcile against `padIndex(for:)` the
+        // instant this assignment lands — a stale map here would skip a newly-forwarded pad.
+        assignPadIndices(for: next)
+        forwarded = next
+    }
+
+    /// Assign each forwarded controller a stable wire pad index (lowest-free, held while it stays
+    /// forwarded) — mirrors pf-client-core's slot model, where a disconnect frees only its own
+    /// index and the others keep theirs. A controller already holding an index keeps it across the
+    /// churn; a slot beyond `GamepadWire.maxPads` goes unassigned (that pad is not forwarded).
+    private func assignPadIndices(for next: [DiscoveredController]) {
+        let live = Set(next.map { ObjectIdentifier($0.controller) })
+        padIndexByController = padIndexByController.filter { live.contains($0.key) }
+        for dc in next {
+            let key = ObjectIdentifier(dc.controller)
+            guard padIndexByController[key] == nil,
+                  let free = Self.lowestFreeIndex(Set(padIndexByController.values)) else { continue }
+            padIndexByController[key] = free
+        }
+    }
+
+    /// The lowest wire pad index not already taken, or nil when all `GamepadWire.maxPads` are in
+    /// use (pf-client-core's `lowest_free_index`).
+    private static func lowestFreeIndex(_ taken: Set<UInt8>) -> UInt8? {
+        (0..<UInt8(GamepadWire.maxPads)).first { !taken.contains($0) }
+    }
+
+    /// The wire pad index a forwarded controller streams on, or nil when it isn't forwarded.
+    public func padIndex(for controller: DiscoveredController) -> UInt8? {
+        padIndexByController[ObjectIdentifier(controller.controller)]
+    }
+
+    /// Drop every pad-index assignment and recompute from the current forwarded set — called when
+    /// a streaming session begins so the assignment starts fresh (a controller pinned before the
+    /// session forwards as pad 0, not whatever index it held for the Settings list). pf-client-core
+    /// assigns indices at slot-open time; this reproduces that session-scoped start.
+    public func resetForwardingAssignment() {
+        padIndexByController.removeAll()
+        reselect()
     }
 
     private static func describe(_ c: GCController, id: String) -> DiscoveredController {
         let extended = c.extendedGamepad
-        let kind = padKind(extended)
+        let kind = padKind(extended, productCategory: c.productCategory)
         return DiscoveredController(
             id: id,
             name: c.vendorName ?? c.productCategory,
@@ -174,28 +238,40 @@ public final class GamepadManager: ObservableObject {
             hasLight: c.light != nil,
             hasHaptics: c.haptics != nil,
             hasMotion: c.motion != nil,
-            // GCDualSenseGamepad's triggers are GCDualSenseAdaptiveTrigger by declaration; the
-            // DualShock 4 has none.
-            hasAdaptiveTriggers: kind == .dualSense,
+            // GCDualSenseGamepad's triggers are GCDualSenseAdaptiveTrigger by declaration (the
+            // Edge included); the DualShock 4 has none.
+            hasAdaptiveTriggers: kind == .dualSense || kind == .dualSenseEdge,
             batteryLevel: c.battery.flatMap { $0.batteryLevel >= 0 ? $0.batteryLevel : nil },
             isCharging: c.battery?.batteryState == .charging,
             controller: c)
     }
 
     /// Resolve a physical controller's matching virtual-pad type from its GameController
-    /// subclass. Detection order (all are `: GCExtendedGamepad`): DualSense first, then
-    /// DualShock 4, then any Xbox pad, else fall back to Xbox 360. A non-extended / absent
-    /// profile also falls back to `.xbox360` (it's never forwarded anyway).
+    /// subclass (+ the product-category string where the subclass is shared). Detection order
+    /// (all are `: GCExtendedGamepad`): DualSense family first (the Edge is a
+    /// `GCDualSenseGamepad` too — its distinct product category splits it out), then
+    /// DualShock 4, any Xbox pad, then Nintendo Switch pads by category (GameController has no
+    /// dedicated subclass for them). A non-extended / absent profile falls back to `.xbox360`
+    /// (it's never forwarded anyway).
     private static func padKind(
-        _ extended: GCExtendedGamepad?
+        _ extended: GCExtendedGamepad?,
+        productCategory: String
     ) -> PunktfunkConnection.GamepadType {
         guard let extended else { return .xbox360 }
+        let category = productCategory.lowercased()
         // Deployment floor (macOS 14 / iOS 17 / tvOS 17) clears every introduction version
         // here, so no `@available` guard is needed — matching the unguarded
         // `GCDualSenseGamepad` use elsewhere in the package.
-        if extended is GCDualSenseGamepad { return .dualSense }
+        if extended is GCDualSenseGamepad {
+            return category.contains("edge") ? .dualSenseEdge : .dualSense
+        }
         if extended is GCDualShockGamepad { return .dualShock4 }
         if extended is GCXboxGamepad { return .xboxOne }
+        // Nintendo Switch Pro Controller / a paired Joy-Con set (a full pad surface). Single
+        // Joy-Cons ("Joy-Con (L)" / "(R)") stay on the Xbox 360 fallback — half a pad.
+        if category.contains("switch pro") || category.contains("joy-con (l/r)") {
+            return .switchPro
+        }
         return .xbox360
     }
 }

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

@@ -140,7 +140,9 @@ public final class GamepadMenuInput {
         let stick = gamepad.leftThumbstick
         let x = stick.xAxis.value
         let y = stick.yAxis.value
-        if abs(x) > abs(y), abs(x) > deadzone {
+        // Horizontal wins an exact |x| == |y| diagonal tie (>=), matching the SDL core and Android
+        // nav so a perfect 45° push resolves to the same direction on every client.
+        if abs(x) >= abs(y), abs(x) > deadzone {
             return x > 0 ? .right : .left
         } else if abs(y) > deadzone {
             return y > 0 ? .up : .down

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

@@ -1,10 +1,14 @@
 // The gamepad wire contract shared by capture (GamepadCapture), feedback (GamepadFeedback),
-// and the tests — button bits, axis ids, and the touchpad/motion unit conversions.
+// and the tests — the pad count, button bits, axis ids, and the touchpad/motion unit conversions.
 
 import Foundation
 
 /// The gamepad wire contract (mirrors `punktfunk_core::input::gamepad`).
 public enum GamepadWire {
+    /// Gamepads addressable on the wire — the pad index rides the low byte of `flags` on every
+    /// per-pad event, 0...15 (`punktfunk_core::input::MAX_PADS`).
+    public static let maxPads: Int = 16
+
     public static let dpadUp: UInt32 = 0x0001
     public static let dpadDown: UInt32 = 0x0002
     public static let dpadLeft: UInt32 = 0x0004
@@ -22,11 +26,27 @@ public enum GamepadWire {
     public static let y: UInt32 = 0x8000
     /// DualSense touchpad click (Moonlight's extended-button bit position).
     public static let touchpadClick: UInt32 = 0x10_0000
+    /// Misc / capture button — Xbox-Series Share, DualSense Create, Steam-Deck quick-access
+    /// (Moonlight's extended-button namespace; `input::gamepad::BTN_MISC1`). The host routes it to
+    /// the DualSense mute / Steam quick-access menu; a plain virtual xpad has no such button.
+    public static let misc1: UInt32 = 0x0020_0000
+    /// Back-grip paddles (Xbox Elite P1–P4 / DualSense Edge / Steam-Deck L4-L5-R4-R5), in
+    /// Moonlight's extended-button namespace (`input::gamepad::BTN_PADDLE1..4`, R4/L4/R5/L5).
+    /// Defined for wire completeness and pinned by the tests; `GamepadCapture.buttonMask` does not
+    /// read them yet — the GameController `paddleButton1..4` ↔ BTN_PADDLE physical correspondence
+    /// needs confirming on a real Elite pad first (see the gamepad-review-cleanup plan, G22), so
+    /// they are intentionally absent from `allButtons` until that forwarding lands.
+    public static let paddle1: UInt32 = 0x0001_0000
+    public static let paddle2: UInt32 = 0x0002_0000
+    public static let paddle3: UInt32 = 0x0004_0000
+    public static let paddle4: UInt32 = 0x0008_0000
 
+    /// Every button `buttonMask`/`sendGuide` can set — walked by `sync`'s transition diff and by
+    /// `flush` on release. Paddles are excluded until their capture lands (see above).
     public static let allButtons: [UInt32] = [
         dpadUp, dpadDown, dpadLeft, dpadRight, start, back,
         leftStickClick, rightStickClick, leftShoulder, rightShoulder, guide,
-        a, b, x, y, touchpadClick,
+        a, b, x, y, touchpadClick, misc1,
     ]
 
     public static let axisLSX: UInt32 = 0

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

@@ -119,8 +119,19 @@ final class RumbleRenderer: @unchecked Sendable {
         static let manual = Policy(staleAfter: nil)
     }
 
+    /// 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.
+    /// Device mode ignores `retarget`'s controller and always renders one combined motor
+    /// (a phone body has a single actuator).
+    enum Actuator {
+        case controller
+        case device
+    }
+
     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.
     /// A PLAIN pattern player on purpose: the controller haptics server (gamecontrollerd)
@@ -198,8 +209,9 @@ final class RumbleRenderer: @unchecked Sendable {
         ((0, 0), DispatchTime(uptimeNanoseconds: 0))
     #endif
 
-    init(policy: Policy = .session) {
+    init(policy: Policy = .session, actuator: Actuator = .controller) {
         self.policy = policy
+        self.actuator = actuator
     }
 
     /// `onBackend`, if given, is invoked (on the internal queue) with a human-readable name of the
@@ -468,6 +480,10 @@ final class RumbleRenderer: @unchecked Sendable {
     /// high = right/light — the Xbox/XInput convention the wire carries); one combined
     /// engine otherwise, driven by whichever amplitude is stronger.
     private func setup() {
+        if actuator == .device {
+            setupDevice()
+            return
+        }
         guard let haptics = controller?.haptics else {
             // No haptics engine at all — an Xbox controller on an OS/firmware that doesn't expose
             // rumble through GameController (works on Android via the standard Vibrator path, but
@@ -517,10 +533,41 @@ final class RumbleRenderer: @unchecked Sendable {
         }
     }
 
+    /// Device-actuator mode: one combined motor on this device's own Taptic Engine. Only an
+    /// iPhone has one — everything else (iPad, Mac, TV) reports no haptic hardware and latches
+    /// off (nothing to retry; the settings toggle is hidden there anyway, this is the backstop).
+    private func setupDevice() {
+        #if os(iOS)
+        guard CHHapticEngine.capabilitiesForHardware().supportsHaptics else {
+            log.info("rumble: this device has no haptic actuator — device rumble unavailable")
+            broken = true
+            reportHealth("This device has no haptic actuator.")
+            return
+        }
+        do {
+            low = startMotor(try CHHapticEngine(), sharpness: RumbleTuning.sharpnessCombined)
+        } catch {
+            log.warning("rumble: device haptic engine creation failed: \(error, privacy: .public)")
+        }
+        if low == nil {
+            // Same shape as the controller path: haptics exist but the engine couldn't be built
+            // right now — back off and retry, don't latch off.
+            scheduleRetryBackoff()
+        }
+        #else
+        broken = true
+        #endif
+    }
+
     private func makeMotor(
         _ haptics: GCDeviceHaptics, _ locality: GCHapticsLocality, sharpness: Float
     ) -> Motor? {
         guard let engine = haptics.createEngine(withLocality: locality) else { return nil }
+        return startMotor(engine, sharpness: sharpness)
+    }
+
+    /// Configure + start an engine (controller-locality or the device's own) into a [`Motor`].
+    private func startMotor(_ engine: CHHapticEngine, sharpness: Float) -> Motor? {
         // A controller's motors carry no audio, so keep this engine OUT of the app's audio session
         // (the default is to join it). Streaming keeps an AVAudioSession active the whole time;
         // letting a haptics-only engine join it is a needless coupling that can get its
@@ -546,7 +593,7 @@ final class RumbleRenderer: @unchecked Sendable {
             try engine.start()
             return Motor(engine: engine, sharpness: sharpness)
         } catch {
-            log.warning("haptic engine setup failed (\(locality.rawValue, privacy: .public)): \(error, privacy: .public)")
+            log.warning("haptic engine setup failed: \(error, privacy: .public)")
             return nil
         }
     }

clients/apple/Sources/PunktfunkKit/Input/InputCapture.swift

@@ -85,6 +85,12 @@ public final class InputCapture {
     /// its Esc suppression need it in both states).
     private var cmdKeysDown: Set<UInt32> = []
 
+    /// Physical Control/Option/Shift keys currently held (Windows VKs, both L/R sides). iPad only:
+    /// the ⌃⌥⇧Q release chord is recognized from the HID stream here (iOS has no NSEvent monitor,
+    /// like the ⌘⎋ toggle), so it needs the live modifier state — tracked in both forwarding states,
+    /// exactly like `cmdKeysDown`, and flushed by `releaseAll` when GC delivery stops.
+    private var chordModifiersDown: Set<UInt32> = []
+
     /// While true, mouse/keyboard flow to the host and key NSEvents are swallowed
     /// locally; while false the user is interacting with the local UI (dragging the
     /// window, clicking the HUD) and nothing is forwarded. Main-queue only.
@@ -119,6 +125,21 @@ public final class InputCapture {
     public var onDisconnect: (() -> Void)?
     public var onCycleStats: (() -> Void)?
 
+    #if os(iOS)
+    /// Windows VKs of the three modifier classes in the ⌃⌥⇧Q release chord, both L/R sides:
+    /// control (0xA2/0xA3), option (0xA4/0xA5), shift (0xA0/0xA1). Used to sift the HID key stream.
+    private static let chordModifierVKs: Set<UInt32> = [0xA2, 0xA3, 0xA4, 0xA5, 0xA0, 0xA1]
+
+    /// Whether Control AND Option AND Shift are all currently held (either side of each counts) —
+    /// the modifier precondition for the iPad ⌃⌥⇧Q release chord.
+    private var hasReleaseChordModifiers: Bool {
+        let m = chordModifiersDown
+        return (m.contains(0xA2) || m.contains(0xA3)) // control
+            && (m.contains(0xA4) || m.contains(0xA5)) // option
+            && (m.contains(0xA0) || m.contains(0xA1)) // shift
+    }
+    #endif
+
     /// Fired when a newer InputCapture takes the process-global GC handler slots (the
     /// singletons hold ONE handler each): the preempted owner must drop its capture
     /// state — its handlers are gone, so it would otherwise sit "captured" with dead
@@ -294,6 +315,7 @@ public final class InputCapture {
     /// in another app would otherwise stay "held" here forever — hijacking Esc).
     private func releaseAll() {
         cmdKeysDown.removeAll()
+        chordModifiersDown.removeAll()
         suppressedVK = nil
         for vk in pressedVKs {
             connection.send(.key(vk, down: false))
@@ -576,6 +598,13 @@ public final class InputCapture {
                     self.cmdKeysDown.remove(vk)
                 }
             }
+            #if os(iOS)
+            // Track Control/Option/Shift for the ⌃⌥⇧Q release chord below — in both forwarding
+            // states (like `cmdKeysDown`) so a modifier held before capture engaged still counts.
+            if Self.chordModifierVKs.contains(vk) {
+                if pressed { self.chordModifiersDown.insert(vk) } else { self.chordModifiersDown.remove(vk) }
+            }
+            #endif
             // The ⌘⎋ toggle's Esc — checked before the forwarding gate, because in the
             // engage direction forwarding is already true when this fires.
             if vk == self.suppressedVK {
@@ -592,6 +621,18 @@ public final class InputCapture {
             }
             #endif
             guard self.forwarding else { return }
+            #if os(iOS)
+            // ⌃⌥⇧Q releases the captured mouse/keyboard (cross-client parity — the same combo the
+            // macOS keyDown monitor handles). Recognized only while forwarding (nothing to release
+            // otherwise). The Q is latched (`suppressedVK`) so its keyUp can't type into the host;
+            // the ⌃⌥⇧ modifiers were forwarded as they went down and are flushed by the release
+            // path (setCaptured(false) → releaseAll). VK 0x51 is layout-independent (physical Q).
+            if pressed, vk == 0x51, self.hasReleaseChordModifiers {
+                self.suppressedVK = 0x51
+                self.onReleaseCapture?()
+                return
+            }
+            #endif
             // Release direction of the toggle: GC's Esc-down can beat the NSEvent
             // monitor — never type Esc into the host while ⌘ is held (⌘⎋ is reserved).
             if vk == 0x1B, !self.cmdKeysDown.isEmpty {

clients/apple/Sources/PunktfunkKit/Input/KeyMaps.swift

@@ -118,3 +118,44 @@ extension InputCapture {
         ]
     #endif
 }
+
+#if os(iOS)
+/// US-layout character → Windows VK for the on-screen keyboard (`StreamLayerUIView`'s
+/// UIKeyInput). Unlike every other key source, `insertText` delivers CHARACTERS, not key
+/// positions, so this is the inverse of a US layout: `shift` means "wrap in VK_LSHIFT so the
+/// host types the shifted symbol". Same contract as `hidToVK`: emit only VKs the host's
+/// vk_to_evdev knows; anything unmapped is dropped by the caller.
+enum SoftKeyMap {
+    static func vk(for ch: Character) -> (vk: UInt32, shift: Bool)? {
+        guard let ascii = ch.asciiValue else { return nil }
+        switch ascii {
+        case UInt8(ascii: "a")...UInt8(ascii: "z"): return (UInt32(ascii) - 0x20, false)
+        case UInt8(ascii: "A")...UInt8(ascii: "Z"): return (UInt32(ascii), true)
+        case UInt8(ascii: "0")...UInt8(ascii: "9"): return (UInt32(ascii), false)
+        case 0x0A, 0x0D: return (0x0D, false) // return
+        case 0x09: return (0x09, false) // tab
+        case 0x20: return (0x20, false) // space
+        default: return symbols[ch]
+        }
+    }
+
+    /// US punctuation, plain and shifted, on the OEM VKs (mirrors `hidToVK`'s OEM block) plus
+    /// the shifted digit row.
+    private static let symbols: [Character: (vk: UInt32, shift: Bool)] = [
+        "-": (0xBD, false), "_": (0xBD, true),
+        "=": (0xBB, false), "+": (0xBB, true),
+        "[": (0xDB, false), "{": (0xDB, true),
+        "]": (0xDD, false), "}": (0xDD, true),
+        "\\": (0xDC, false), "|": (0xDC, true),
+        ";": (0xBA, false), ":": (0xBA, true),
+        "'": (0xDE, false), "\"": (0xDE, true),
+        "`": (0xC0, false), "~": (0xC0, true),
+        ",": (0xBC, false), "<": (0xBC, true),
+        ".": (0xBE, false), ">": (0xBE, true),
+        "/": (0xBF, false), "?": (0xBF, true),
+        "!": (0x31, true), "@": (0x32, true), "#": (0x33, true), "$": (0x34, true),
+        "%": (0x35, true), "^": (0x36, true), "&": (0x37, true), "*": (0x38, true),
+        "(": (0x39, true), ")": (0x30, true),
+    ]
+}
+#endif

clients/apple/Sources/PunktfunkKit/Input/TouchMouse.swift

@@ -3,7 +3,8 @@
 // identical. Two mouse modes share one gesture vocabulary — tap = left click · two-finger
 // tap = right click · two-finger drag = scroll · tap-then-press-and-drag = held left drag
 // (text selection / window moves) · three-finger tap = cycles the stats overlay tiers
-// (off → compact → normal → detailed, matching Android):
+// (off → compact → normal → detailed, matching Android) · three-finger swipe up/down =
+// summon/dismiss the local soft keyboard for typing on the host (`onKeyboardGesture`):
 //
 //  * trackpad (default): the cursor STAYS PUT on touch-down and moves by the finger's
 //    relative delta with mild acceleration — swipe to nudge, lift and re-swipe to walk it
@@ -61,6 +62,9 @@ final class TouchMouse {
         static let accelGain: CGFloat = 0.6
         static let accelSpeedFloor: CGFloat = 0.3
         static let accelMax: CGFloat = 3.0
+        /// Three-finger vertical swipe: the fraction of the view height the centroid must
+        /// travel to summon (up) / dismiss (down) the local soft keyboard.
+        static let keyboardSwipeFraction: CGFloat = 0.10
 
         /// Acceleration multiplier for a finger speed in physical px per ms.
         static func accel(forSpeed speed: CGFloat) -> CGFloat {
@@ -72,6 +76,9 @@ final class TouchMouse {
     var send: ((PunktfunkInputEvent) -> Void)?
     /// View-space point → host-mode pixels through the letterbox (pointer mode's moves).
     var hostPoint: ((CGPoint) -> StreamLayerUIView.HostPoint?)?
+    /// Three-finger vertical swipe crossed the threshold: `true` = show the local soft
+    /// keyboard (swipe up), `false` = dismiss it (swipe down). Fires at most once per gesture.
+    var onKeyboardGesture: ((Bool) -> Void)?
 
     /// No gesture in flight (all fingers up) — the view uses this to release its mode latch.
     var isIdle: Bool { !sessionActive && lastPos.isEmpty }
@@ -95,6 +102,11 @@ final class TouchMouse {
     private var carryY: CGFloat = 0
     /// Scroll anchor (centroid) — re-anchored every time a notch fires.
     private var scrollAnchor = CGPoint.zero
+    // Keyboard-swipe state: the 3+-finger centroid anchor (per finger count, like the scroll
+    // anchor) and a once-per-gesture latch.
+    private var kbCount = 0
+    private var kbAnchor = CGPoint.zero
+    private var kbFired = false
     // Tap-drag arming: a quick tap leaves a window in which the next nearby touch drags.
     private var lastTapUp: TimeInterval = 0
     private var lastTapPoint = CGPoint.zero
@@ -114,6 +126,8 @@ final class TouchMouse {
             maxFingers = 0
             moved = false
             scrolling = false
+            kbCount = 0
+            kbFired = false
             // A touch landing just after a quick tap nearby = tap-and-drag: hold the left
             // button for this whole gesture (laptop-trackpad convention).
             dragHeld = first.timestamp - lastTapUp < Tuning.tapDragWindow
@@ -140,8 +154,13 @@ final class TouchMouse {
         for touch in touches where lastPos[ObjectIdentifier(touch)] != nil {
             lastPos[ObjectIdentifier(touch)] = touch.location(in: view)
         }
-        if lastPos.count >= 2 {
+        // Dropping below three fingers forgets the keyboard-swipe anchor, so a 3→2→3 bounce
+        // re-anchors instead of reading the count change as swipe travel.
+        if lastPos.count < 3 { kbCount = 0 }
+        if lastPos.count == 2 {
             scrollByCentroid()
+        } else if lastPos.count >= 3 {
+            keyboardSwipe(in: view)
         } else if !scrolling, let touch = touches.first(where: {
             lastPos[ObjectIdentifier($0)] != nil
         }) {
@@ -208,9 +227,9 @@ final class TouchMouse {
 
     // MARK: - Per-event work
 
-    /// Two fingers (or more) → scroll by the centroid delta; never move the cursor. Fires a
-    /// notch per `scrollNotchPt` of pan and re-anchors on fire; finger up scrolls up, finger
-    /// right scrolls right (the host WHEEL(120) convention).
+    /// Two fingers → scroll by the centroid delta; never move the cursor. Fires a notch per
+    /// `scrollNotchPt` of pan and re-anchors on fire; finger up scrolls up, finger right
+    /// scrolls right (the host WHEEL(120) convention).
     private func scrollByCentroid() {
         let n = CGFloat(lastPos.count)
         let cx = lastPos.values.reduce(0) { $0 + $1.x } / n
@@ -233,6 +252,38 @@ final class TouchMouse {
         }
     }
 
+    /// Three+ fingers → the keyboard swipe, never scroll (the documented vocabulary is
+    /// TWO-finger scroll; 3+ only fell into the scroll path as an accident of its old `>= 2`
+    /// bound). The centroid is anchored per finger count — real fingers never land or lift in
+    /// the same event, so a count change must re-anchor rather than read as travel — and the
+    /// gesture fires at most once, when the vertical travel crosses the threshold: up = show
+    /// the local soft keyboard, down = dismiss it.
+    private func keyboardSwipe(in view: UIView) {
+        let n = CGFloat(lastPos.count)
+        let cx = lastPos.values.reduce(0) { $0 + $1.x } / n
+        let cy = lastPos.values.reduce(0) { $0 + $1.y } / n
+        if lastPos.count != kbCount {
+            kbCount = lastPos.count
+            kbAnchor = CGPoint(x: cx, y: cy)
+        } else {
+            let dy = cy - kbAnchor.y
+            // Real centroid travel disqualifies the tap classification in `ended` (else a
+            // sub-threshold swipe would still fire the three-finger stats tap).
+            if abs(dy) > Tuning.tapSlop || abs(cx - kbAnchor.x) > Tuning.tapSlop { moved = true }
+            if !kbFired, abs(dy) >= view.bounds.height * Tuning.keyboardSwipeFraction {
+                kbFired = true
+                onKeyboardGesture?(dy < 0) // finger up → show, finger down → dismiss
+            }
+        }
+        // Leaving the scroll state stale would read the 3→2 centroid jump as a wheel notch;
+        // clearing it makes a return to two fingers re-anchor fresh. Same for the trackpad's
+        // tracked finger: its prev position froze while 3+ fingers were down, so dropping
+        // straight back to one finger must re-anchor (zero delta), not replay the whole
+        // 3-finger phase as one cursor jump.
+        scrolling = false
+        trackKey = nil
+    }
+
     /// One finger (and the gesture never became a scroll — dropping back from two fingers to
     /// one must not jerk the cursor).
     private func singleFinger(_ touch: UITouch, in view: UIView) {

clients/apple/Sources/PunktfunkKit/Support/DefaultsKeys.swift

@@ -11,6 +11,15 @@ public enum DefaultsKey {
     public static let streamWidth = "punktfunk.width"
     public static let streamHeight = "punktfunk.height"
     public static let streamHz = "punktfunk.hz"
+    /// Match-window resolution policy (design/midstream-resolution-resize.md D1/D2): when on, the
+    /// stream mode FOLLOWS the session view — the connect asks for the view's pixel size and a
+    /// mid-session resize (a windowed macOS window, an iPad Stage Manager / Split View scene)
+    /// renegotiates the host's virtual display + encoder (`PunktfunkConnection.requestMode`), so a
+    /// windowed session streams native-resolution pixels instead of scaling. Off (default): the
+    /// explicit `streamWidth`/`streamHeight` are used and never auto-resized (a fullscreen session
+    /// is native either way, so this degenerates to Auto-native there). Read per session by the
+    /// stream views' `MatchWindowFollower`.
+    public static let matchWindow = "punktfunk.matchWindow"
     public static let compositor = "punktfunk.compositor"
     public static let gamepadType = "punktfunk.gamepadType"
     public static let gamepadID = "punktfunk.gamepadID"
@@ -88,6 +97,18 @@ public enum DefaultsKey {
     /// layout (the console launcher, gamepad-navigable settings, a coverflow-style library)
     /// whenever a gamepad is connected. On by default; see `GamepadUIEnvironment.isActive`.
     public static let gamepadUIEnabled = "punktfunk.gamepadUIEnabled"
+    /// iPhone: ALSO play the rumble the host addresses to controller 1 (wire pad 0) on this
+    /// device's own Taptic Engine — for phone-clip pads that ship without rumble motors, where
+    /// the phone body is the only actuator in the player's hands. Off by default (opt-in); read
+    /// once per session by `GamepadFeedback`. The toggle is shown only where the device actually
+    /// has a haptic actuator (no iPad/Mac/TV).
+    public static let rumbleOnDevice = "punktfunk.rumbleOnDevice"
+    /// Auto-wake on connect: when connecting to a saved host that isn't advertising on mDNS, fire
+    /// Wake-on-LAN and, if the dial fails, wait for it to come back before retrying (the "Waking…"
+    /// overlay). On by default. Turn off if a host that's already on just isn't seen on mDNS (a
+    /// routed/VPN host), so connects go straight through instead of waiting out the wake timeout.
+    /// The explicit "Wake Host" action stays available regardless. Read by ContentView.startSession.
+    public static let autoWake = "punktfunk.autoWake"
 }
 
 extension Notification.Name {

clients/apple/Sources/PunktfunkKit/Video/MatchWindowFollower.swift

@@ -0,0 +1,153 @@
+// Match-window resize follower (design/midstream-resolution-resize.md D1/D2, client C3).
+//
+// The presenting view feeds this its PHYSICAL-PIXEL size on every layout; it debounces to
+// resize-end, spaces requests ≥ 1 s apart, and asks the connection to switch the host's virtual
+// display + encoder to match (`PunktfunkConnection.requestMode`) — so a windowed macOS session or
+// an iPad Stage Manager / Split View scene streams native-resolution pixels instead of scaling.
+// The decode/present side needs nothing: VideoToolbox recreates its session on the keyframe-derived
+// format-description change (the first new-mode AU is an IDR with fresh parameter sets).
+//
+// The trigger discipline is the shared cross-client one (mirrors the session binary's
+// `resize_decision`): physical pixels rounded DOWN to even (the host rejects odd dimensions) and
+// clamped ≥ 320×200; debounce to resize-end; ≥ 1 s between requests; skip a size equal to the live
+// mode; and request each distinct size at most once — which both stops re-asking a rejected size
+// and keeps a host-side rollback (accepted, rebuild failed, corrective ack restored the old mode)
+// from looping request → rollback → request.
+
+import Foundation
+
+/// The pure, side-effect-free core of the Match-window trigger — so the normalize/skip discipline
+/// is unit-tested without a live connection or a UI (`MatchWindowTests`).
+public enum MatchWindow {
+    /// Even-floor + clamp a physical-pixel size to a host-valid mode dimension: the host's
+    /// `validate_dimensions` rejects odd sizes, and we never ask below 320×200.
+    public static func normalize(widthPx: Int, heightPx: Int) -> (width: UInt32, height: UInt32) {
+        let evenClamp: (Int, UInt32) -> UInt32 = { px, minimum in
+            let even = UInt32(max(px, 0)) / 2 * 2
+            return max(even, minimum)
+        }
+        return (evenClamp(widthPx, 320), evenClamp(heightPx, 200))
+    }
+
+    /// Whether to request `target` now (the debounce has already settled; spacing is the caller's
+    /// timer): `nil` to skip — equal to the live mode, or already requested once (a rejected size /
+    /// a host rollback must not loop). `target` is expected already-[normalize]d.
+    public static func request(
+        target: (width: UInt32, height: UInt32),
+        current: (width: UInt32, height: UInt32),
+        lastRequested: (width: UInt32, height: UInt32)?
+    ) -> (width: UInt32, height: UInt32)? {
+        if target.width == current.width, target.height == current.height { return nil }
+        if let lr = lastRequested, lr.width == target.width, lr.height == target.height { return nil }
+        return target
+    }
+}
+
+/// Owns the debounce timer + serialization state and drives `PunktfunkConnection.requestMode` from
+/// the stream view's layout callbacks. Main-actor: the views feed it on the main thread and it reads
+/// the connection's live mode there. Enabled per session from the `matchWindow` setting.
+@MainActor
+public final class MatchWindowFollower {
+    private weak var connection: PunktfunkConnection?
+    private let debounce: TimeInterval
+    private let minSpacing: TimeInterval
+    private var enabled: Bool
+
+    private var work: DispatchWorkItem?
+    private var pendingSize: (width: Int, height: Int)?
+    private var lastRequested: (width: UInt32, height: UInt32)?
+    private var lastRequestAt: Date?
+    /// The last size we reported via [`onResizeTarget`] — dedups the per-layout stream of a drag so
+    /// the UI is notified once per distinct target, and reset to `nil` when the window is back in
+    /// sync with the live mode (so a later resize re-reports).
+    private var lastSteered: (width: UInt32, height: UInt32)?
+
+    /// Fired (on the main actor) the instant the window starts differing from the live mode — i.e.
+    /// a resize is under way and a `Reconfigure` for `(width, height)` is imminent. Drives the
+    /// resize overlay's INSTANT feedback (blur + spinner) BEFORE the debounced request leaves; the
+    /// overlay clears when a decoded frame reaches this size (or on a timeout). Deduped per target.
+    public var onResizeTarget: ((_ width: UInt32, _ height: UInt32) -> Void)?
+
+    /// `debounce` = quiet time after the last size event before requesting (Win32 gets
+    /// `WM_EXITSIZEMOVE` for free; we debounce). `minSpacing` = floor between accepted requests
+    /// (a full host pipeline rebuild each). Defaults match the other clients.
+    public init(
+        connection: PunktfunkConnection,
+        enabled: Bool,
+        debounce: TimeInterval = 0.4,
+        minSpacing: TimeInterval = 1.0
+    ) {
+        self.connection = connection
+        self.enabled = enabled
+        self.debounce = debounce
+        self.minSpacing = minSpacing
+    }
+
+    /// Turn following on/off live (a mid-session settings change; off cancels a pending request).
+    public func setEnabled(_ on: Bool) {
+        enabled = on
+        if !on {
+            work?.cancel()
+            work = nil
+            pendingSize = nil
+            lastSteered = nil
+        }
+    }
+
+    /// Feed the presenting view's current PHYSICAL-PIXEL size (its `bounds` × the backing/display
+    /// scale). Called from every layout pass; coalesced by the debounce so a drag-resize sends one
+    /// request at its end, never one per frame.
+    public func noteSize(widthPx: Int, heightPx: Int) {
+        guard enabled else { return }
+        pendingSize = (widthPx, heightPx)
+        schedule()
+        reportSteering(widthPx: widthPx, heightPx: heightPx)
+    }
+
+    /// Report the resize overlay's START signal (deduped): the moment the normalized window size
+    /// differs from the live mode we're steering toward a new size. No connection / no negotiated
+    /// mode yet → nothing to compare against, skip.
+    private func reportSteering(widthPx: Int, heightPx: Int) {
+        guard let connection else { return }
+        let target = MatchWindow.normalize(widthPx: widthPx, heightPx: heightPx)
+        let mode = connection.currentMode()
+        guard mode.width > 0, mode.height > 0 else { return }
+        if target.width == mode.width, target.height == mode.height {
+            lastSteered = nil // back in sync — a later change re-reports
+            return
+        }
+        if lastSteered?.width == target.width, lastSteered?.height == target.height { return }
+        lastSteered = target
+        onResizeTarget?(target.width, target.height)
+    }
+
+    private func schedule() {
+        work?.cancel()
+        let item = DispatchWorkItem { [weak self] in self?.fire() }
+        work = item
+        DispatchQueue.main.asyncAfter(deadline: .now() + debounce, execute: item)
+    }
+
+    private func fire() {
+        guard enabled, let connection, let size = pendingSize else { return }
+        // ≥ 1 s spacing: a request went out recently → re-arm the debounce and retry later rather
+        // than fire early (keeps at most ~one request outstanding — the accept ack round-trips in
+        // milliseconds, ahead of the host's rebuild).
+        if let last = lastRequestAt, Date().timeIntervalSince(last) < minSpacing {
+            schedule()
+            return
+        }
+        let target = MatchWindow.normalize(widthPx: size.width, heightPx: size.height)
+        let mode = connection.currentMode()
+        pendingSize = nil
+        guard let req = MatchWindow.request(
+            target: target,
+            current: (mode.width, mode.height),
+            lastRequested: lastRequested
+        ) else { return }
+        // Keep the current refresh — Match-window follows SIZE, not rate.
+        connection.requestMode(width: req.width, height: req.height, refreshHz: mode.refreshHz)
+        lastRequested = req
+        lastRequestAt = Date()
+    }
+}

clients/apple/Sources/PunktfunkKit/Video/MetalVideoPresenter.swift

@@ -124,7 +124,16 @@ float2 chromaUV(texture2d<float> lumaTex, texture2d<float> chromaTex, float2 uv)
 float3 sampleRgb(texture2d<float> lumaTex, texture2d<float> chromaTex, float2 uv,
                  constant CscUniform& csc) {
     constexpr sampler s(filter::linear, address::clamp_to_edge);
-    float3 yuv = float3(catmullRomLuma(lumaTex, s, uv),
+#ifdef PF_BILINEAR_LUMA
+    // DEBUG (PUNKTFUNK_BILINEAR_LUMA=1): plain bilinear luma — Catmull-Rom OFF. A/B lever to see if
+    // the bicubic overshoot contributes to edge fringing. NOTE: at a true 1:1 present both paths
+    // reduce to the identity texel, so if this toggle VISIBLY changes the picture, the present is
+    // NOT 1:1 (there's a resample); if it looks identical, the fringing is upstream (codec/source/OS).
+    float lumaY = lumaTex.sample(s, uv).r;
+#else
+    float lumaY = catmullRomLuma(lumaTex, s, uv);
+#endif
+    float3 yuv = float3(lumaY,
                         chromaTex.sample(s, chromaUV(lumaTex, chromaTex, uv)).rg);
     return saturate(float3(dot(csc.r0.xyz, yuv) + csc.r0.w,
                            dot(csc.r1.xyz, yuv) + csc.r1.w,
@@ -250,7 +259,16 @@ public final class MetalVideoPresenter {
         let pipelineHDR: MTLRenderPipelineState
         let pipelineHDRToneMap: MTLRenderPipelineState?
         do {
-            let library = try device.makeLibrary(source: shaderSource, options: nil)
+            // DEBUG A/B lever: PUNKTFUNK_BILINEAR_LUMA=1 compiles the shader with Catmull-Rom OFF
+            // (plain bilinear luma) by prepending a #define ahead of the source. Default (unset) is
+            // the normal bicubic path. Read at presenter creation — set it in the environment and
+            // relaunch to flip; the log line confirms which path built.
+            let bilinearLuma = ProcessInfo.processInfo.environment["PUNKTFUNK_BILINEAR_LUMA"] == "1"
+            let source = (bilinearLuma ? "#define PF_BILINEAR_LUMA 1\n" : "") + shaderSource
+            if bilinearLuma {
+                presenterLog.info("stage2: PUNKTFUNK_BILINEAR_LUMA=1 — Catmull-Rom luma DISABLED (bilinear)")
+            }
+            let library = try device.makeLibrary(source: source, options: nil)
             let vtx = library.makeFunction(name: "pf_vtx")
             let sdr = MTLRenderPipelineDescriptor()
             sdr.vertexFunction = vtx
@@ -590,8 +608,17 @@ public final class MetalVideoPresenter {
         let sig = "\(Int(decoded.width))x\(Int(decoded.height))→\(Int(drawable.width))x\(Int(drawable.height))|hdr\(hdrActive ? 1 : 0)"
         if sig != lastSizeSig {
             lastSizeSig = sig
+            // Explicit verdict: is the shader presenting 1:1 (decoded == drawable) or resampling? The
+            // scale ratio makes a residual match-window mismatch obvious. If this says 1:1 but the
+            // picture is still soft, the resample is downstream of us (macOS compositor — a scaled
+            // display mode, or a fractional-pixel window position), not the shader.
+            let sx = decoded.width > 0 ? drawable.width / decoded.width : 0
+            let sy = decoded.height > 0 ? drawable.height / decoded.height : 0
+            let verdict = decoded == drawable
+                ? "1:1 (no resample)"
+                : String(format: "RESAMPLE scale=%.4fx%.4f", sx, sy)
             let msg =
-                "stage2: decoded \(Int(decoded.width))x\(Int(decoded.height)) → drawable \(Int(drawable.width))x\(Int(drawable.height)) hdr=\(hdrActive)"
+                "stage2: decoded \(Int(decoded.width))x\(Int(decoded.height)) → drawable \(Int(drawable.width))x\(Int(drawable.height)) [\(verdict)] hdr=\(hdrActive)"
             presenterLog.info("\(msg, privacy: .public)")
         }
     }

clients/apple/Sources/PunktfunkKit/Video/ReanchorGate.swift

@@ -0,0 +1,99 @@
+// Swift wrapper around the punktfunk-core C ABI's post-loss re-anchor gate
+// (`punktfunk_reanchor_gate_*`, ABI v6). The shared Rust gate (crates/punktfunk-core/src/reanchor.rs)
+// is what the Linux/Windows desktop pump and the Android client use directly; the Swift clients reach
+// it across the C ABI so the freeze-until-reanchor policy is defined ONCE for every platform.
+//
+// Why a freeze at all: after unrecoverable loss the host keeps sending delta frames that reference a
+// picture the client never got. Hardware decoders (VideoToolbox included) don't reliably error on
+// that — they CONCEAL, returning a gray/garbage frame with a success status. Presenting those is the
+// visible "gray flash with motion" of the loss reports. The gate withholds concealed frames and holds
+// the last good picture on glass until a PROVEN clean re-anchor lands — an IDR (wire `FLAG_SOF`), an
+// RFI recovery anchor (`USER_FLAG_RECOVERY_ANCHOR`), or the 2nd of two intra-refresh recovery marks
+// (`USER_FLAG_RECOVERY_POINT`) — with a bounded backstop so a lost re-anchor can never freeze forever.
+// See punktfunk-planning design/client-reanchor-freeze-parity.md.
+//
+// Threading: one gate per session. Its calls arrive from two threads — the pump thread (`arm` on a
+// frame-index gap / a submit failure, `poll` per iteration) and a VideoToolbox decode thread
+// (`onDecoded` per decoded frame, `onNoOutput` on a decode error). The raw Rust gate is a plain
+// struct behind an opaque pointer with no internal synchronization, so every call is serialized under
+// `lock` here — the calls are cheap field updates, so contention is negligible. `@unchecked Sendable`:
+// the lock enforces the contract.
+
+import Foundation
+import PunktfunkCore
+
+final class ReanchorGate: @unchecked Sendable {
+    private let lock = NSLock()
+    /// The opaque `ReanchorGate *`. `var` so `reseed` can swap it at session start. Never NULL
+    /// (`punktfunk_reanchor_gate_new` never returns NULL).
+    private var ptr: OpaquePointer
+
+    /// Seed the baseline with the connection's current `framesDropped` so the first `poll` doesn't
+    /// read the session's starting drop count as a fresh loss.
+    init(framesDropped: UInt64) {
+        ptr = punktfunk_reanchor_gate_new(framesDropped)
+    }
+
+    deinit { punktfunk_reanchor_gate_free(ptr) }
+
+    /// Re-anchor the drop-count baseline to `framesDropped` for a (re)started session. The gate is
+    /// created in the pipeline's init (before a connection exists, seeded 0); `start` calls this once
+    /// the live connection's count is known so a mid-life connection's non-zero baseline isn't
+    /// mistaken for loss on the first poll.
+    func reseed(framesDropped: UInt64) {
+        lock.lock()
+        defer { lock.unlock() }
+        punktfunk_reanchor_gate_free(ptr)
+        ptr = punktfunk_reanchor_gate_new(framesDropped)
+    }
+
+    /// Arm the freeze: a loss was detected (a frame-index gap, or a decoder wedge). Zeroes the
+    /// recovery-mark count and (re)sets the backstop deadline.
+    func arm() {
+        lock.lock()
+        punktfunk_reanchor_gate_arm(ptr)
+        lock.unlock()
+    }
+
+    /// Fold one decoded frame. `flags` is the AU's wire `user_flags`. Returns true to PRESENT the
+    /// frame, false to WITHHOLD it as a post-loss concealment (hold the last good picture). Pass
+    /// `decoderKeyframe: false` — VideoToolbox doesn't flag IDRs, so the wire `FLAG_SOF` covers it.
+    func onDecoded(flags: UInt32, decoderKeyframe: Bool = false) -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        var present = false
+        _ = punktfunk_reanchor_gate_on_decoded(ptr, flags, decoderKeyframe, &present)
+        return present
+    }
+
+    /// A received AU produced no decoded frame (a VideoToolbox decode error). Returns true when the
+    /// no-output streak has tripped (the gate armed the freeze) and the caller should — throttled —
+    /// request a keyframe.
+    func onNoOutput() -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        var requestKf = false
+        _ = punktfunk_reanchor_gate_on_no_output(ptr, &requestKf)
+        return requestKf
+    }
+
+    /// Periodic fold of the session's `framesDropped` plus the overdue backstop. Returns true when the
+    /// caller should — throttled — request a keyframe (a drop-count climb armed a fresh freeze, or the
+    /// freeze is overdue and re-asks while it keeps holding).
+    func poll(framesDropped: UInt64) -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        var requestKf = false
+        _ = punktfunk_reanchor_gate_poll(ptr, framesDropped, &requestKf)
+        return requestKf
+    }
+
+    /// Whether the gate is currently withholding concealed frames (frozen on the last good picture).
+    var isHolding: Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        var holding = false
+        _ = punktfunk_reanchor_gate_is_holding(ptr, &holding)
+        return holding
+    }
+}

clients/apple/Sources/PunktfunkKit/Video/ResizeIndicator.swift

@@ -0,0 +1,63 @@
+// Resize-in-progress indicator state (design/midstream-resolution-resize.md — client UX).
+//
+// A mid-stream resize takes the host 0.3–2 s to rebuild its virtual display + encoder, and the
+// first new-mode frame is an IDR that the decoder re-inits on. Rather than let the stream scale
+// (stretch/blur) to the changing window during that gap, the client EMBRACES the delay: it shows a
+// deliberate blur + spinner the instant a resize starts and clears it the instant the sharp
+// new-resolution frame is on screen — so the wait reads as intentional, not as lag.
+//
+// This is driven ENTIRELY by signals the client already has (no new protocol):
+//   * START — the Match-window follower reports the size it is steering toward (instant, on the
+//     first resize layout, before the debounced request even leaves).
+//   * END — the decode pipeline reports each new-mode IDR's dimensions; when they reach the target
+//     the new picture is here.
+//   * TIMEOUT — the safety net for a switch that never delivers the exact target: the host rejected
+//     it (gamescope), capped it to an advertised mode, or a corrective ack landed a different size.
+//
+// Pure + side-effect-free so the transition logic is unit-tested without a live session or UI
+// (`ResizeIndicatorTests`); `SessionModel` owns an instance and mirrors `active` into a @Published.
+
+import Foundation
+
+/// The pure state of the resize overlay. `now` is a monotonic time in seconds (the caller passes
+/// `ProcessInfo.processInfo.systemUptime` or a test clock).
+public struct ResizeIndicator {
+    /// Whether the blur + spinner should be shown.
+    public private(set) var active = false
+    /// The size the follower is steering toward — cleared once a decoded frame reaches it.
+    private var target: (width: UInt32, height: UInt32)?
+    /// When the current `active` span began — the timeout is measured from here.
+    private var since: TimeInterval?
+    /// How long to keep the overlay up if the target frame never arrives (rejected / capped switch).
+    public var timeout: TimeInterval
+
+    public init(timeout: TimeInterval = 2.5) { self.timeout = timeout }
+
+    /// The follower is steering toward `width`×`height` — a resize is under way. Show the overlay now
+    /// (instant feedback). Called only for a genuine change (the follower skips a target equal to the
+    /// live mode), possibly many times as a drag moves through sizes; the timeout re-arms whenever the
+    /// target actually changes so a slow drag never trips it mid-gesture.
+    public mutating func steering(width: UInt32, height: UInt32, now: TimeInterval) {
+        if !active || target?.width != width || target?.height != height {
+            since = now
+        }
+        target = (width, height)
+        active = true
+    }
+
+    /// A decoded frame arrived at `width`×`height` (a new-mode IDR). Clears the overlay once it
+    /// matches the steered target — the sharp new-resolution picture is on glass.
+    public mutating func decoded(width: UInt32, height: UInt32) {
+        guard active, let t = target, t.width == width, t.height == height else { return }
+        active = false
+        since = nil
+    }
+
+    /// Timeout safety net: stop showing the overlay once `timeout` has elapsed with no matching frame
+    /// (a rejected or host-capped switch never delivers the exact target).
+    public mutating func tick(now: TimeInterval) {
+        guard active, let s = since, now - s >= timeout else { return }
+        active = false
+        since = nil
+    }
+}

clients/apple/Sources/PunktfunkKit/Video/SessionPresenter.swift

@@ -70,6 +70,15 @@ final class SessionPresenter {
     private var stage2Link: CADisplayLink?
     private var metalLayer: CAMetalLayer?
     private var connection: PunktfunkConnection?
+    /// The decoded frame's REAL pixel dimensions (ground truth, pushed by the view from the pump's
+    /// `onDecodedSize` new-mode-IDR callback). Used for the aspect-fit in `layout` in preference to
+    /// `connection.currentMode()`, which (a) lags a mid-stream resize — it only updates on the
+    /// `Reconfigured` ack, and a resize-END produces no bounds change to re-run `layout` afterward —
+    /// and (b) can disagree with what the host actually DELIVERED (Windows corrective-ack falls back
+    /// to an advertised mode). The pixels we're drawing are the only correct aspect source; a wrong
+    /// one here is the "black bars + stretched" resize artifact. nil until the first frame → `layout`
+    /// falls back to `currentMode()`. Main-thread only.
+    private var contentSize: CGSize?
 
     /// Start the presenter for `connection`. `baseLayer` is the view's AVSampleBufferDisplayLayer:
     /// stage-1 enqueues into it; stage-2 leaves it idle and composites an opaque CAMetalLayer
@@ -85,7 +94,8 @@ final class SessionPresenter {
         displayMeter: LatencyMeter? = nil,
         makeDisplayLink: (AnyObject, Selector) -> CADisplayLink,
         onFrame: (@Sendable (AccessUnit) -> Void)?,
-        onSessionEnd: (@Sendable () -> Void)?
+        onSessionEnd: (@Sendable () -> Void)?,
+        onDecodedSize: (@Sendable (Int, Int) -> Void)? = nil
     ) {
         stop()
         self.connection = connection
@@ -128,12 +138,14 @@ final class SessionPresenter {
             link.add(to: .main, forMode: .common)
             stage2Link = link
             syncFrameRate(hz: connection.currentMode().refreshHz)
-            pipeline.start(connection: connection, onFrame: onFrame, onSessionEnd: onSessionEnd)
+            pipeline.start(
+                connection: connection, onFrame: onFrame, onSessionEnd: onSessionEnd,
+                onDecodedSize: onDecodedSize)
         } else {
             let pump = StreamPump()
             pump.start(
                 connection: connection, layer: baseLayer,
-                onFrame: onFrame, onSessionEnd: onSessionEnd)
+                onFrame: onFrame, onSessionEnd: onSessionEnd, onDecodedSize: onDecodedSize)
             self.pump = pump
         }
     }
@@ -181,22 +193,45 @@ final class SessionPresenter {
         guard let metalLayer, let connection else { return }
         let mode = connection.currentMode()
         syncFrameRate(hz: mode.refreshHz) // track a mid-session Reconfigure's new refresh
-        let fit: CGRect = (mode.width > 0 && mode.height > 0)
-            ? AVMakeRect(
-                aspectRatio: CGSize(width: Int(mode.width), height: Int(mode.height)),
-                insideRect: bounds)
-            : bounds
+        // Aspect source: the ACTUAL decoded dims when known (survives a lagging `currentMode()` and a
+        // host that delivered a different size than requested), else the negotiated mode. The shader
+        // stretches the frame across the WHOLE drawable, so this rect's aspect is the only thing that
+        // keeps the picture undistorted — a stale aspect here is the post-resize black-bars+stretch.
+        let aspect: CGSize? = {
+            if let c = contentSize, c.width > 0, c.height > 0 { return c }
+            if mode.width > 0, mode.height > 0 {
+                return CGSize(width: Int(mode.width), height: Int(mode.height))
+            }
+            return nil
+        }()
+        let fit: CGRect = aspect.map { AVMakeRect(aspectRatio: $0, insideRect: bounds) } ?? bounds
+        // Snap the sublayer frame to the BACKING PIXEL GRID. AVMakeRect centers the aspect-fit rect,
+        // so its origin/size are usually fractional points; a metal sublayer whose frame doesn't land
+        // on whole device pixels is RESAMPLED by the macOS/UIKit compositor during composite — a
+        // uniform "everything looks soft" blur — even when the drawable itself is pixel-exact 1:1
+        // (verified via the stage2 "[1:1 (no resample)]" log while the picture was still soft). Round
+        // origin AND size to device pixels so the composite is a true 1:1 blit. Idempotent when the
+        // frame is already aligned (e.g. fullscreen fit == integer bounds), so it's a no-op there.
+        let scale = contentsScale > 0 ? contentsScale : 1
+        let snapped = CGRect(
+            x: (fit.origin.x * scale).rounded() / scale,
+            y: (fit.origin.y * scale).rounded() / scale,
+            width: (fit.width * scale).rounded() / scale,
+            height: (fit.height * scale).rounded() / scale)
         // No implicit resize animation; contentsScale tracks the view's backing/display scale.
         CATransaction.begin()
         CATransaction.setDisableActions(true)
         metalLayer.contentsScale = contentsScale
-        metalLayer.frame = fit
+        metalLayer.frame = snapped
         CATransaction.commit()
         // Hand the resulting pixel size to the render thread (it must not read layer geometry
-        // cross-thread) — this is what the presenter sizes its drawable to.
+        // cross-thread) — this is what the presenter sizes its drawable to. Uses the SNAPPED size so
+        // the drawable's texel count equals the on-screen device-pixel count exactly (1 texel ↔ 1
+        // device pixel); with the frame snapped, this equals the pre-snap rounded value, so the
+        // decoded↔drawable 1:1 the log confirmed is preserved.
         stage2?.setDrawableTarget(CGSize(
-            width: (fit.width * contentsScale).rounded(),
-            height: (fit.height * contentsScale).rounded()))
+            width: (snapped.width * scale).rounded(),
+            height: (snapped.height * scale).rounded()))
         #if os(tvOS)
         // Push the display's live EDR headroom alongside: > 1 means the TV is composited in an
         // HDR mode (the session's AVDisplayManager request landed — see StreamViewIOS), and HDR
@@ -206,10 +241,20 @@ final class SessionPresenter {
         #endif
     }
 
+    /// Record the decoded frame's real dimensions (the view hops the pump's `onDecodedSize` to main
+    /// and calls this) so `layout` aspect-fits to what's actually on screen instead of the possibly-
+    /// stale `currentMode()`. Only stores — the caller re-runs `layout` right after, because a
+    /// resize-END produces no bounds change to trigger one. No-op on a zero/unchanged size.
+    func setContentSize(_ size: CGSize) {
+        guard size.width > 0, size.height > 0, size != contentSize else { return }
+        contentSize = size
+    }
+
     /// Stop the active pump/pipeline (≤ one poll timeout; stage-2 joins its pump) and detach the
     /// stage-2 layer + link. Does not close the connection — that stays with whoever owns it.
     /// Idempotent.
     func stop() {
+        contentSize = nil // a new session re-derives it from its first frame
         pump?.stop()
         pump = nil
         stage2Link?.invalidate()

clients/apple/Sources/PunktfunkKit/Video/Stage2Pipeline.swift

@@ -259,6 +259,10 @@ public final class Stage2Pipeline {
     private let endToEndMeter: LatencyMeter?
     private let displayMeter: LatencyMeter?
     private let recovery = KeyframeRecovery()
+    /// Post-loss freeze-until-reanchor gate (shared core policy via the C ABI). Created here seeded 0;
+    /// `start` reseeds it to the live connection's drop count. Captured by the decoder callbacks
+    /// (which withhold concealed frames) and driven by the pump (arm on a gap, poll per iteration).
+    private let gate = ReanchorGate(framesDropped: 0)
     private var token = StopFlag()
     private var offsetNs: Int64 = 0
     /// Signalled when the pump thread exits, so `stop()` can join it (bounded) before `decoder.reset()`
@@ -306,21 +310,29 @@ public final class Stage2Pipeline {
         let ring = ring
         let recovery = recovery
         let renderSignal = renderSignal
+        let gate = gate
         self.decoder = VideoDecoder(
             onDecoded: { frame in
                 // Decode stage = received→decoded, both client CLOCK_REALTIME (offset 0 — no
                 // skew applies). Stamped at decode completion, so it covers every decoded frame,
-                // including ones the newest-wins ring drops before present.
+                // including ones the re-anchor gate withholds or the newest-wins ring drops.
                 decodeMeter?.record(
                     ptsNs: UInt64(frame.receivedNs), atNs: frame.decodedNs, offsetNs: 0)
+                // Freeze-until-reanchor: WITHHOLD a decoder-concealed post-loss frame (the gray/
+                // garbage VideoToolbox returns Ok for a reference-missing delta) — don't submit it,
+                // so the CAMetalLayer keeps its last good drawable on glass. The gate lifts (returns
+                // present) on a proven clean re-anchor (IDR / RFI anchor / 2nd recovery mark) or the
+                // bounded backstop. decoderKeyframe=false: VT doesn't flag IDRs, the wire FLAG_SOF does.
+                guard gate.onDecoded(flags: frame.flags) else { return }
                 ring.submit(frame)
                 // FRAME ARRIVAL is the render trigger (never the display link — see the header).
                 renderSignal.signal()
             },
-            // Async decode failure (a bad P-frame referencing a lost/corrupt IDR): the pump resets to
-            // re-gate on the next IDR, and we ask the host to send one now (infinite GOP — it wouldn't
+            // Async decode failure (a bad P-frame referencing a lost/corrupt IDR): fold it into the
+            // gate's no-output streak (which arms the freeze after a short run, matching the desktop),
+            // and when that trips ask the host for a fresh IDR now (infinite GOP — it wouldn't
             // otherwise come soon). Throttled in KeyframeRecovery.
-            onDecodeError: { _ in recovery.request() })
+            onDecodeError: { _ in if gate.onNoOutput() { recovery.request() } })
     }
 
     /// Start pulling AUs into the decoder. MAIN THREAD. `onFrame` fires per AU at receipt (the
@@ -329,10 +341,12 @@ public final class Stage2Pipeline {
     public func start(
         connection: PunktfunkConnection,
         onFrame: (@Sendable (AccessUnit) -> Void)?,
-        onSessionEnd: (@Sendable () -> Void)?
+        onSessionEnd: (@Sendable () -> Void)?,
+        onDecodedSize: (@Sendable (Int, Int) -> Void)? = nil
     ) {
         offsetNs = connection.clockOffsetNs
         recovery.bind(connection) // arm host-keyframe recovery for this session
+        gate.reseed(framesDropped: connection.framesDropped()) // baseline the freeze to this session
         token = StopFlag() // fresh token per start — a stop is permanent (like StreamPump)
 
         // Configure the decoder's chroma + the layer's initial colorimetry before the first frame. The
@@ -347,9 +361,13 @@ public final class Stage2Pipeline {
         let recovery = recovery
         let presenter = presenter
         let pumpStopped = pumpStopped
+        let reanchorGate = gate
         let thread = Thread {
             defer { pumpStopped.signal() } // let stop() join the pump (bounded) before decoder.reset()
             var format: CMVideoFormatDescription?
+            // Report coded dims to the resize overlay only on a CHANGE (new-mode IDR), not per
+            // loss-recovery IDR at the same size (see StreamPump).
+            var lastDecodedDims: CMVideoDimensions?
             var lastFramesDropped = connection.framesDropped()
             // Persistent recovery WANT, not a one-shot edge (see StreamPump for the full rationale):
             // keep asking until an IDR lands so a request swallowed by the throttle is re-sent.
@@ -375,6 +393,9 @@ public final class Stage2Pipeline {
                         awaitingIDR = true
                     }
                     if awaitingIDR { recovery.request() }
+                    // Freeze backstop: a drop-count climb arms the gate (in case the frame-index gap
+                    // below was itself lost), and an overdue freeze re-asks for the re-anchor.
+                    if reanchorGate.poll(framesDropped: dropped) { recovery.request() }
                     // Drain HDR mastering metadata (0xCE) and hand it to the PRESENTER (→ CAEDRMetadata).
                     // Polled UNCONDITIONALLY (not gated on connection.isHDR, the fixed Welcome flag): the
                     // host sends 0xCE only for HDR, INCLUDING a mid-session SDR→HDR transition (a game
@@ -384,9 +405,21 @@ public final class Stage2Pipeline {
                         presenter.setHdrMeta(meta)
                     }
                     guard let au = try connection.nextAU(timeoutMs: 100) else { return true }
+                    // Loss recovery (RFI): a forward frame-index gap fires a throttled reference-
+                    // frame-invalidation request so an RFI-capable host (AMD LTR / NVENC) recovers
+                    // with a cheap clean P-frame instead of a full IDR. The framesDropped-driven
+                    // recovery above stays the backstop for when the recovery frame itself is lost.
+                    // The same gap is the earliest, most precise signal to ARM the display freeze —
+                    // the following concealed frames are withheld until a clean re-anchor.
+                    if connection.noteFrameIndexGap(au.frameIndex) { reanchorGate.arm() }
                     onFrame?(au)
                     if let f = connection.videoCodec.formatDescription(fromKeyframe: au.data) {
                         format = f          // refreshed on every IDR (mode changes included)
+                        let dims = CMVideoFormatDescriptionGetDimensions(f)
+                        if lastDecodedDims?.width != dims.width || lastDecodedDims?.height != dims.height {
+                            lastDecodedDims = dims
+                            onDecodedSize?(Int(dims.width), Int(dims.height))
+                        }
                         awaitingIDR = false // a fresh IDR re-anchored decode — recovery complete
                     }
                     guard let f = format, !token.isStopped else { return true }

clients/apple/Sources/PunktfunkKit/Video/StreamPump.swift

@@ -21,12 +21,18 @@ final class StreamPump {
         connection: PunktfunkConnection,
         layer: AVSampleBufferDisplayLayer,
         onFrame: (@Sendable (AccessUnit) -> Void)?,
-        onSessionEnd: (@Sendable () -> Void)?
+        onSessionEnd: (@Sendable () -> Void)?,
+        onDecodedSize: (@Sendable (Int, Int) -> Void)? = nil
     ) {
         let token = token
         // Coalesced host keyframe requests (100 ms throttle — see KeyframeRecovery).
         let recovery = KeyframeRecovery()
         recovery.bind(connection)
+        // Post-loss freeze-until-reanchor (shared core policy via the C ABI). Stage-1 has no per-frame
+        // decode callback, so the gate is folded at ENQUEUE (from the AU's wire flags): a withheld
+        // frame is still enqueued but flagged DoNotDisplay so the layer's decoder keeps the reference
+        // chain fed while the last GOOD picture stays on glass — until a clean re-anchor lifts it.
+        let gate = ReanchorGate(framesDropped: connection.framesDropped())
         // The layer is non-Sendable but its enqueue/flush are documented thread-safe, and after
         // this point only the pump thread drives it — assert that so the @Sendable Thread closure
         // may capture it.
@@ -35,6 +41,9 @@ final class StreamPump {
 
         let thread = Thread {
             var format: CMVideoFormatDescription?
+            // Report the coded dims to the resize overlay only when they CHANGE (a new-mode IDR),
+            // not on every loss-recovery IDR at the same size — so it fires once per real switch.
+            var lastDecodedDims: CMVideoDimensions?
             var lastFramesDropped = connection.framesDropped()
             // Recovery is a persistent WANT, not a one-shot edge: set it on detected loss (or a
             // decoder reset), retry the throttled request EVERY iteration, and clear it only when a
@@ -73,12 +82,26 @@ final class StreamPump {
                         awaitingIDR = true
                     }
                     if awaitingIDR { recovery.request() }
+                    // Freeze backstop: a drop-count climb arms the gate (should the frame-index gap
+                    // below be lost too), and an overdue freeze re-asks for the re-anchor.
+                    if gate.poll(framesDropped: dropped) { recovery.request() }
 
                     guard let au = try connection.nextAU(timeoutMs: 100) else { return true }
+                    // Loss recovery (RFI): a forward frame-index gap fires a throttled reference-
+                    // frame-invalidation request so an RFI-capable host (AMD LTR / NVENC) recovers
+                    // with a cheap clean P-frame instead of a full IDR. The framesDropped-driven
+                    // recovery above stays the backstop for when the recovery frame itself is lost.
+                    // The same gap is the earliest, most precise signal to ARM the display freeze.
+                    if connection.noteFrameIndexGap(au.frameIndex) { gate.arm() }
                     onFrame?(au)
                     let idrFormat = connection.videoCodec.formatDescription(fromKeyframe: au.data)
                     if let f = idrFormat {
                         format = f          // refreshed on every IDR (mode changes included)
+                        let dims = CMVideoFormatDescriptionGetDimensions(f)
+                        if lastDecodedDims?.width != dims.width || lastDecodedDims?.height != dims.height {
+                            lastDecodedDims = dims
+                            onDecodedSize?(Int(dims.width), Int(dims.height))
+                        }
                         if awaitingIDR {
                             let ms = Int(Date().timeIntervalSince(awaitingSince) * 1000)
                             pumpLog.notice("video: recovery IDR received — resumed after \(ms, privacy: .public) ms")
@@ -93,6 +116,7 @@ final class StreamPump {
                         // delta into a failed layer can't recover it.
                         if !wasFailed { pumpLog.warning("video: display layer .failed — flushing + re-anchoring") }
                         layer.flush()
+                        gate.arm() // a wedged decoder is a loss — freeze until the re-anchor
                         if idrFormat == nil {
                             format = nil
                             awaitingIDR = true
@@ -103,6 +127,13 @@ final class StreamPump {
                           let sample = connection.videoCodec.sampleBuffer(au: au, format: f),
                           !token.isStopped // don't enqueue a stale frame after a restart
                     else { return true }
+                    // Freeze-until-reanchor: while holding, WITHHOLD this concealed post-loss frame by
+                    // flagging it DoNotDisplay — the layer still decodes it (keeping the reference
+                    // chain fed) but shows the last GOOD picture until a clean re-anchor lifts the
+                    // gate. Folded from the AU's wire flags (stage-1 has no decode callback).
+                    if !gate.onDecoded(flags: au.flags) {
+                        StreamPump.setDoNotDisplay(sample)
+                    }
                     layer.enqueue(sample)
                     return true
                 } catch {
@@ -119,6 +150,21 @@ final class StreamPump {
         thread.start()
     }
 
+    /// Flag a sample decode-but-don't-display (`kCMSampleAttachmentKey_DoNotDisplay`). Used to
+    /// withhold decoder-concealed post-loss frames while the re-anchor gate holds: the layer keeps
+    /// its reference chain fed without flipping the frozen picture. No-op if the attachments array
+    /// can't be materialized (then the frame just displays — the freeze degrades to the old behavior).
+    private static func setDoNotDisplay(_ sample: CMSampleBuffer) {
+        guard let attachments = CMSampleBufferGetSampleAttachmentsArray(
+            sample, createIfNecessary: true), CFArrayGetCount(attachments) > 0
+        else { return }
+        let dict = unsafeBitCast(CFArrayGetValueAtIndex(attachments, 0), to: CFMutableDictionary.self)
+        CFDictionarySetValue(
+            dict,
+            Unmanaged.passUnretained(kCMSampleAttachmentKey_DoNotDisplay).toOpaque(),
+            Unmanaged.passUnretained(kCFBooleanTrue).toOpaque())
+    }
+
     /// Stop pumping (≤ one poll timeout). Does not close the connection.
     func stop() {
         token.stop()

clients/apple/Sources/PunktfunkKit/Video/VideoDecoder.swift

@@ -27,19 +27,40 @@ public struct ReadyFrame: @unchecked Sendable {
     /// True when the stream is HDR (BT.2020 PQ): the buffer is 10-bit P010 and the presenter must
     /// configure EDR + BT.2020 PQ output. Derived from the decoded buffer's pixel format.
     public let isHDR: Bool
+    /// The AU's wire `user_flags` (`AccessUnit.flags`), threaded through the decode via the frame
+    /// context so the re-anchor gate can classify this decoded frame (IDR / RFI anchor / recovery
+    /// mark) at present time — the async decode callback has no other access to it. 0 when unknown.
+    public let flags: UInt32
+}
+
+/// Per-frame context threaded through the VideoToolbox frame refcon: the AU's receipt instant (for
+/// the decode-stage meter) and its wire `user_flags` (for the re-anchor gate). Retained across the
+/// async decode and reclaimed exactly once — by the output callback for every frame VideoToolbox
+/// accepts, or by `decode`'s error branch for a frame `DecodeFrame` rejected outright (the callback
+/// then never fires). A tiny per-frame allocation, the price of smuggling two values (a 64-bit
+/// instant plus the flags) through the single `void*` a bit-pattern scalar can't hold.
+private final class FrameContext {
+    let receivedNs: Int64
+    let flags: UInt32
+    init(receivedNs: Int64, flags: UInt32) {
+        self.receivedNs = receivedNs
+        self.flags = flags
+    }
 }
 
 /// The C output callback can't capture context, so VideoToolbox hands it the refcon we set at
-/// session creation — a pointer back to the owning `VideoDecoder`. The per-frame refcon carries
-/// the AU's `receivedNs` as a pointer bit pattern (a scalar smuggled through the C void*, never
-/// dereferenced) so the decode stage can be computed against decode-completion.
+/// session creation — a pointer back to the owning `VideoDecoder`. The per-frame refcon is the
+/// retained `FrameContext` set at submit; reclaim it here (balancing `passRetained`) and unpack the
+/// AU's receipt instant (for the decode stage) and wire flags (for the re-anchor gate).
 private let decoderOutputCallback: VTDecompressionOutputCallback = {
     refcon, frameRefcon, status, _, imageBuffer, pts, _ in
     guard let refcon else { return }
-    let receivedNs = frameRefcon.map { Int64(Int(bitPattern: $0)) } ?? 0
+    let ctx = frameRefcon.map { Unmanaged<FrameContext>.fromOpaque($0).takeRetainedValue() }
     Unmanaged<VideoDecoder>.fromOpaque(refcon)
         .takeUnretainedValue()
-        .handleDecoded(status: status, imageBuffer: imageBuffer, pts: pts, receivedNs: receivedNs)
+        .handleDecoded(
+            status: status, imageBuffer: imageBuffer, pts: pts,
+            receivedNs: ctx?.receivedNs ?? 0, flags: ctx?.flags ?? 0)
 }
 
 /// Owns a `VTDecompressionSession` rebuilt whenever the format description changes (every IDR /
@@ -117,16 +138,21 @@ public final class VideoDecoder: @unchecked Sendable {
               let sample = codec.sampleBuffer(au: au, format: newFormat)
         else { lock.unlock(); return false }
         var infoOut = VTDecodeInfoFlags()
+        // The AU's receipt instant + wire flags ride through as a retained context; the output
+        // callback reclaims it. Retain immediately before submit so no early return can leak it.
+        let ctx = FrameContext(receivedNs: au.receivedNs, flags: au.flags)
+        let refcon = Unmanaged.passRetained(ctx).toOpaque()
         let status = VTDecompressionSessionDecodeFrame(
             session,
             sampleBuffer: sample,
             flags: [._EnableAsynchronousDecompression],
-            // The AU's receipt instant rides through as a bit pattern (nil for 0 — the output
-            // callback maps that back to 0); the callback needs it to stamp the decode stage.
-            frameRefcon: UnsafeMutableRawPointer(bitPattern: Int(au.receivedNs)),
+            frameRefcon: refcon,
             infoFlagsOut: &infoOut)
         lock.unlock()
         if status != noErr {
+            // DecodeFrame rejected the frame outright — the output callback will NOT fire, so
+            // reclaim the context here (balancing passRetained) to avoid leaking it.
+            Unmanaged<FrameContext>.fromOpaque(refcon).release()
             onDecodeError(status)
             return false
         }
@@ -231,9 +257,10 @@ public final class VideoDecoder: @unchecked Sendable {
     }
 
     /// VT thread. Stamp decode-completion and enqueue, or report the error. `receivedNs` is the
-    /// AU's receipt instant threaded through the frame refcon (0 = unknown).
+    /// AU's receipt instant and `flags` its wire `user_flags`, both threaded through the frame refcon
+    /// (0 = unknown).
     fileprivate func handleDecoded(
-        status: OSStatus, imageBuffer: CVImageBuffer?, pts: CMTime, receivedNs: Int64
+        status: OSStatus, imageBuffer: CVImageBuffer?, pts: CMTime, receivedNs: Int64, flags: UInt32
     ) {
         guard status == noErr, let imageBuffer else {
             onDecodeError(status)
@@ -259,6 +286,6 @@ public final class VideoDecoder: @unchecked Sendable {
         onDecoded(
             ReadyFrame(
                 ptsNs: ptsNs, receivedNs: receivedNs, decodedNs: decodedNs,
-                pixelBuffer: imageBuffer, isHDR: isHDR))
+                pixelBuffer: imageBuffer, isHDR: isHDR, flags: flags))
     }
 }

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

@@ -87,6 +87,8 @@ public struct StreamView: NSViewRepresentable {
     private let onDisconnectRequest: (() -> Void)?
     private let onFrame: (@Sendable (AccessUnit) -> Void)?
     private let onSessionEnd: (@Sendable () -> Void)?
+    private let onResizeTarget: ((UInt32, UInt32) -> Void)?
+    private let onDecodedSize: (@Sendable (Int, Int) -> Void)?
     private let endToEndMeter: LatencyMeter?
     private let decodeMeter: LatencyMeter?
     private let displayMeter: LatencyMeter?
@@ -108,6 +110,8 @@ public struct StreamView: NSViewRepresentable {
         onDisconnectRequest: (() -> Void)? = nil,
         onFrame: (@Sendable (AccessUnit) -> Void)? = nil,
         onSessionEnd: (@Sendable () -> Void)? = nil,
+        onResizeTarget: ((UInt32, UInt32) -> Void)? = nil,
+        onDecodedSize: (@Sendable (Int, Int) -> Void)? = nil,
         endToEndMeter: LatencyMeter? = nil,
         decodeMeter: LatencyMeter? = nil,
         displayMeter: LatencyMeter? = nil
@@ -118,6 +122,8 @@ public struct StreamView: NSViewRepresentable {
         self.onDisconnectRequest = onDisconnectRequest
         self.onFrame = onFrame
         self.onSessionEnd = onSessionEnd
+        self.onResizeTarget = onResizeTarget
+        self.onDecodedSize = onDecodedSize
         self.endToEndMeter = endToEndMeter
         self.decodeMeter = decodeMeter
         self.displayMeter = displayMeter
@@ -131,6 +137,8 @@ public struct StreamView: NSViewRepresentable {
         view.endToEndMeter = endToEndMeter
         view.decodeMeter = decodeMeter
         view.displayMeter = displayMeter
+        view.onResizeTarget = onResizeTarget
+        view.onDecodedSize = onDecodedSize
         view.start(connection: connection, onFrame: onFrame, onSessionEnd: onSessionEnd)
         return view
     }
@@ -142,6 +150,8 @@ public struct StreamView: NSViewRepresentable {
         view.endToEndMeter = endToEndMeter
         view.decodeMeter = decodeMeter
         view.displayMeter = displayMeter
+        view.onResizeTarget = onResizeTarget
+        view.onDecodedSize = onDecodedSize
         // SwiftUI reuses the NSView across state changes — repoint the pump only when the
         // connection identity actually changed.
         if view.connection !== connection {
@@ -165,6 +175,15 @@ public final class StreamLayerView: NSView {
     /// stage-1 StreamPump → displayLayer path as the Metal-unavailable / DEBUG fallback.
     private let presenter = SessionPresenter()
     public private(set) var connection: PunktfunkConnection?
+    /// Match-window resize follower (C3) — non-nil while a session is active AND the `matchWindow`
+    /// setting is on (DEFAULT on, for pixel-exact windowed streaming); fed the view's physical-pixel
+    /// size on every relayout so the host mode tracks the window (1:1, no presenter resample).
+    private var matchFollower: MatchWindowFollower?
+    /// Last decoded frame size fed into the presenter's aspect-fit. A new-mode IDR after a resize
+    /// re-fits the metal sublayer to the REAL content aspect here — `layout()` only re-runs on a
+    /// bounds change and a resize-END has none, so without this the layer keeps its pre-resize aspect
+    /// and the shader stretches the new frame into it (black bars + squish). Main-thread only.
+    private var lastDecodedContentSize: CGSize?
     private let cursorCapture = CursorCapture()
     private var inputCapture: InputCapture?
     private var appObservers: [NSObjectProtocol] = []
@@ -201,6 +220,13 @@ public final class StreamLayerView: NSView {
     /// view can't do that itself (the connection's owner disconnects).
     public var onDisconnectRequest: (() -> Void)?
 
+    /// Resize overlay signals (design/midstream-resolution-resize.md client UX): `onResizeTarget`
+    /// (main thread, via the follower) fires the instant the window starts steering toward a new
+    /// size; `onDecodedSize` (PUMP thread) fires when a new-mode IDR's dims land. The owner drives
+    /// the blur+spinner from these — set before `start()`.
+    public var onResizeTarget: ((UInt32, UInt32) -> Void)?
+    public var onDecodedSize: (@Sendable (Int, Int) -> Void)?
+
     /// Main-thread only. False = input capture disabled outright (UI layered over the
     /// stream); flipping to true auto-engages once.
     public var captureEnabled = true {
@@ -618,6 +644,10 @@ public final class StreamLayerView: NSView {
         // (explicit VTDecompressionSession decode + a CAMetalLayer/display-link present) by
         // default, the stage-1 pump as the Metal-missing / DEBUG fallback. The link comes from
         // NSView.displayLink so it tracks the display this view is on.
+        // Intercept the pump's coded-dims callback: re-fit the metal sublayer to the real content
+        // aspect (main thread) BEFORE forwarding to the owner's overlay END-signal. Fires only on a
+        // size CHANGE (first frame + each resolved resize), so this is rare, not per-frame.
+        let overlayDecodedSize = onDecodedSize
         presenter.start(
             connection: connection,
             baseLayer: displayLayer,
@@ -626,15 +656,39 @@ public final class StreamLayerView: NSView {
             displayMeter: displayMeter,
             makeDisplayLink: { displayLink(target: $0, selector: $1) },
             onFrame: onFrame,
-            onSessionEnd: onSessionEnd)
+            onSessionEnd: onSessionEnd,
+            onDecodedSize: { [weak self] w, h in // resize overlay END signal (new-mode IDR dims)
+                DispatchQueue.main.async { self?.noteDecodedContentSize(width: w, height: h) }
+                overlayDecodedSize?(w, h)
+            })
+        // Match-window (C3): when ON, follow the window's pixel size so a windowed session streams
+        // 1:1 (pixel-exact) instead of the presenter resampling a fixed-mode frame into a
+        // non-matching window. The first real `layout()` feeds the initial size, so the stream
+        // converges to the window even though the connect used the explicit/display mode; entering
+        // fullscreen reports the full-display px, restoring a native-res 1:1 present there too.
+        // OPT-IN — `?? false` matches the Settings toggle (which also defaults off); an unset
+        // default keeps the explicit mode.
+        let follower = MatchWindowFollower(
+            connection: connection,
+            enabled: UserDefaults.standard.object(forKey: DefaultsKey.matchWindow) as? Bool ?? false)
+        follower.onResizeTarget = onResizeTarget // resize overlay START signal (instant, on the follower)
+        matchFollower = follower
         layoutPresenter()
         requestAutoCapture() // entering a session is the deliberate "capture me" moment
     }
 
     /// Aspect-fit the stage-2 metal sublayer to the view; refresh contentsScale on a
-    /// retina↔non-retina move (see SessionPresenter.layout).
+    /// retina↔non-retina move (see SessionPresenter.layout). Also feeds the Match-window follower
+    /// the view's physical-pixel size (bounds → backing), so a window resize / retina move follows.
     private func layoutPresenter() {
         presenter.layout(in: bounds, contentsScale: window?.backingScaleFactor ?? 1)
+        // Feed the follower only once in a window (backing scale is real then) and with real
+        // bounds — a pre-window layout would report point-sized dimensions.
+        if window != nil, bounds.width > 0, bounds.height > 0 {
+            let px = convertToBacking(bounds).size
+            matchFollower?.noteSize(
+                widthPx: Int(px.width.rounded()), heightPx: Int(px.height.rounded()))
+        }
     }
 
     public override func viewDidChangeBackingProperties() {
@@ -642,6 +696,18 @@ public final class StreamLayerView: NSView {
         layoutPresenter() // backing scale changed (e.g. moved to a non-retina display)
     }
 
+    /// A new decoded size landed (a new-mode IDR after a resize, or the session's first frame): push
+    /// it to the presenter's aspect-fit and re-layout NOW. A resize-END triggers no `layout()`, so
+    /// this is what makes the metal sublayer track the new content aspect instead of stretching the
+    /// new frame into the pre-resize box. Deduped so a same-size repeat is a no-op. Main thread.
+    private func noteDecodedContentSize(width: Int, height: Int) {
+        let size = CGSize(width: width, height: height)
+        guard size.width > 0, size.height > 0, size != lastDecodedContentSize else { return }
+        lastDecodedContentSize = size
+        presenter.setContentSize(size)
+        layoutPresenter()
+    }
+
     /// Stop pumping (≤ one poll timeout). Does not close the connection — that stays with
     /// whoever owns it (PunktfunkConnection.close() is safe alongside a draining pump).
     public func stop() {
@@ -650,6 +716,8 @@ public final class StreamLayerView: NSView {
         inputCapture?.stop()
         inputCapture = nil
         presenter.stop()
+        matchFollower = nil
+        lastDecodedContentSize = nil // the next session re-derives it from its first frame
         connection = nil
     }
 

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

@@ -24,7 +24,9 @@
 // (== locked): GCMouse forwards only WHILE locked, the UIKit indirect path (motion, buttons AND
 // scroll) only while NOT locked — so a pointer that emits both channels under lock can't double-send.
 // Hardware keyboard forwarding shares InputCapture with macOS — auto-engaged when streaming
-// starts, ⌘⎋ toggles (detected from the HID stream; there is no NSEvent monitor here).
+// starts, ⌘⎋ toggles and ⌃⌥⇧Q releases (both detected from the HID stream; there is no NSEvent
+// monitor here). ⌃⌥⇧Q is the cross-client Ctrl+Alt+Shift+Q — it un-captures so the Magic Keyboard
+// trackpad drives the local iPad UI again.
 //
 // The public type is named StreamView like its macOS twin (each is platform-gated), so
 // the SwiftUI app layer is identical on both platforms.
@@ -53,6 +55,8 @@ public struct StreamView: UIViewControllerRepresentable {
     private let onCaptureChange: ((Bool) -> Void)?
     private let onFrame: (@Sendable (AccessUnit) -> Void)?
     private let onSessionEnd: (@Sendable () -> Void)?
+    private let onResizeTarget: ((UInt32, UInt32) -> Void)?
+    private let onDecodedSize: (@Sendable (Int, Int) -> Void)?
     private let endToEndMeter: LatencyMeter?
     private let decodeMeter: LatencyMeter?
     private let displayMeter: LatencyMeter?
@@ -68,6 +72,8 @@ public struct StreamView: UIViewControllerRepresentable {
         onDisconnectRequest: (() -> Void)? = nil,
         onFrame: (@Sendable (AccessUnit) -> Void)? = nil,
         onSessionEnd: (@Sendable () -> Void)? = nil,
+        onResizeTarget: ((UInt32, UInt32) -> Void)? = nil,
+        onDecodedSize: (@Sendable (Int, Int) -> Void)? = nil,
         endToEndMeter: LatencyMeter? = nil,
         decodeMeter: LatencyMeter? = nil,
         displayMeter: LatencyMeter? = nil
@@ -77,6 +83,8 @@ public struct StreamView: UIViewControllerRepresentable {
         self.onCaptureChange = onCaptureChange
         self.onFrame = onFrame
         self.onSessionEnd = onSessionEnd
+        self.onResizeTarget = onResizeTarget
+        self.onDecodedSize = onDecodedSize
         self.endToEndMeter = endToEndMeter
         self.decodeMeter = decodeMeter
         self.displayMeter = displayMeter
@@ -89,6 +97,8 @@ public struct StreamView: UIViewControllerRepresentable {
         controller.endToEndMeter = endToEndMeter
         controller.decodeMeter = decodeMeter
         controller.displayMeter = displayMeter
+        controller.onResizeTarget = onResizeTarget
+        controller.onDecodedSize = onDecodedSize
         controller.start(connection: connection, onFrame: onFrame, onSessionEnd: onSessionEnd)
         return controller
     }
@@ -99,6 +109,8 @@ public struct StreamView: UIViewControllerRepresentable {
         controller.endToEndMeter = endToEndMeter
         controller.decodeMeter = decodeMeter
         controller.displayMeter = displayMeter
+        controller.onResizeTarget = onResizeTarget
+        controller.onDecodedSize = onDecodedSize
         if controller.connection !== connection {
             controller.start(connection: connection, onFrame: onFrame, onSessionEnd: onSessionEnd)
         }
@@ -147,6 +159,12 @@ public final class StreamViewController: StreamViewControllerBase {
     /// Capture state at the last resign, restored on the next foreground — otherwise the
     /// mouse/keyboard stay released after navigating out and nothing re-grabs them.
     private var wasCapturedOnResign = false
+    /// Match-window resize follower (C3) — non-nil while a session is active AND the `matchWindow`
+    /// setting is on (DEFAULT on, for pixel-exact scene streaming); fed the view's physical-pixel
+    /// size from `viewDidLayoutSubviews` so an iPad Stage Manager / Split View scene resize
+    /// renegotiates the host mode (1:1, no presenter resample). iOS only (iPhone naturally no-ops
+    /// its fixed full-screen scene; tvOS drives display modes via AVDisplayManager instead).
+    private var matchFollower: MatchWindowFollower?
     #endif
 
     /// Reads whether the scene's pointer is actually locked right now; nil = state
@@ -161,6 +179,18 @@ public final class StreamViewController: StreamViewControllerBase {
     }
 
     var onCaptureChange: ((Bool) -> Void)?
+    /// Resize-overlay START: forwarded to the Match-window follower so a scene resize drives the
+    /// blur+spinner the instant the window differs from the live mode (iOS only — tvOS has no
+    /// follower). See `MatchWindowFollower.onResizeTarget`.
+    var onResizeTarget: ((UInt32, UInt32) -> Void)?
+    /// Resize-overlay END: the presenter reports the coded dims of each new-mode IDR here, so the
+    /// overlay clears when a frame at the requested size actually decodes.
+    var onDecodedSize: (@Sendable (Int, Int) -> Void)?
+    /// Last decoded size fed into the presenter's aspect-fit. A new-mode IDR (an iPad scene resize,
+    /// or a tvOS AVDisplayManager mode switch) re-fits the metal sublayer to the REAL content aspect
+    /// here — `viewDidLayoutSubviews` only re-runs on a bounds change, which a resize-END lacks, so
+    /// without this the layer keeps its pre-resize aspect and stretches the new frame into it. Main.
+    private var lastDecodedContentSize: CGSize?
 
     var captureEnabled = true {
         didSet {
@@ -309,7 +339,19 @@ public final class StreamViewController: StreamViewControllerBase {
                 x: p.x, y: p.y, surfaceWidth: p.w, surfaceHeight: p.h)
         }
         streamView.onPointerButton = { [weak self] button, down in
-            guard let self, self.inputCapture?.gcMouseForwarding == false else { return }
+            guard let self else { return }
+            // Released → a trackpad/mouse click into the video RE-ENGAGES capture (the iPad
+            // analogue of macOS's `mouseDown → engageCapture(fromClick:)`, and the click-mirror of
+            // the ⌘⎋ / ⌃⌥⇧Q keyboard toggles). Only the button-DOWN engages; that click is the local
+            // engage gesture, so it's suppressed toward the host (`fromClick`) and never forwarded —
+            // its release is swallowed by InputCapture's suppress latch, whichever path delivers it.
+            // (Finger taps are untouched: touch always plays directly, so only the indirect pointer
+            // re-captures.) Captured already → the absolute path forwards the button as before.
+            if !self.captured {
+                if down, self.captureEnabled { self.setCaptured(true, fromClick: true) }
+                return
+            }
+            guard self.inputCapture?.gcMouseForwarding == false else { return }
             self.inputCapture?.sendMouseButton(button, pressed: down)
         }
         streamView.onScroll = { [weak self] dx, dy in
@@ -322,16 +364,38 @@ public final class StreamViewController: StreamViewControllerBase {
             guard let self else { return }
             self.setCaptured(!self.captured)
         }
+        // ⌃⌥⇧Q (cross-client parity with macOS/Windows/Linux) releases the captured pointer +
+        // keyboard so the Magic Keyboard trackpad returns to driving the local iPad UI. Detected
+        // from the HID stream in InputCapture (no NSEvent monitor on iOS); unlike the ⌘⎋ toggle it
+        // only ever RELEASES — re-pressing it while already released is a no-op (setCaptured guards).
+        capture.onReleaseCapture = { [weak self] in
+            self?.setCaptured(false)
+        }
         capture.onPreempted = { [weak self] in
             self?.setCaptured(false)
         }
         capture.start()
         inputCapture = capture
+        // Match-window (C3): when ON, follow the scene's pixel size so a resizable iPad scene
+        // streams 1:1 (pixel-exact) instead of the presenter resampling a fixed-mode frame into it.
+        // `viewDidLayoutSubviews` feeds it — covers Stage Manager / Split View resizes and rotation.
+        // iPhone is a fixed full-screen scene, so this naturally no-ops (reports the device mode).
+        // OPT-IN — `?? false` matches the Settings toggle (which also defaults off); an unset
+        // default keeps the explicit mode.
+        let follower = MatchWindowFollower(
+            connection: connection,
+            enabled: UserDefaults.standard.object(forKey: DefaultsKey.matchWindow) as? Bool ?? false)
+        follower.onResizeTarget = onResizeTarget
+        matchFollower = follower
         #endif
 
         // Presenter choice + lifecycle live in SessionPresenter (shared with macOS): stage-2
         // (explicit VTDecompressionSession decode + a CAMetalLayer/display-link present) by
         // default, the stage-1 pump as the Metal-missing / DEBUG fallback.
+        // Intercept the pump's coded-dims callback: re-fit the metal sublayer to the real content
+        // aspect (main thread) BEFORE forwarding to the owner's overlay END-signal. Fires only on a
+        // size CHANGE (first frame + each resolved resize), so this is rare, not per-frame.
+        let overlayDecodedSize = onDecodedSize
         presenter.start(
             connection: connection,
             baseLayer: streamView.displayLayer,
@@ -340,7 +404,11 @@ public final class StreamViewController: StreamViewControllerBase {
             displayMeter: displayMeter,
             makeDisplayLink: { CADisplayLink(target: $0, selector: $1) },
             onFrame: onFrame,
-            onSessionEnd: onSessionEnd)
+            onSessionEnd: onSessionEnd,
+            onDecodedSize: { [weak self] w, h in
+                DispatchQueue.main.async { self?.noteDecodedContentSize(width: w, height: h) }
+                overlayDecodedSize?(w, h)
+            })
         layoutMetalLayer()
 
         #if os(iOS)
@@ -376,6 +444,19 @@ public final class StreamViewController: StreamViewControllerBase {
         ) { [weak self] _ in
             self?.syncPointerLock()
         })
+        // The Stream menu's "Release Mouse" (⌃⌥⇧Q) posts this — the discoverable menu surface for
+        // the RELEASED state. While CAPTURED the combo is recognized from the HID stream in
+        // InputCapture (onReleaseCapture) before the menu sees it, so in practice this fires as a
+        // not-captured no-op (setCaptured guards it); wired for honesty + a non-GC fallback. Only the
+        // foreground-active scene's stream acts — the iPad analogue of macOS's key-window guard, so a
+        // second Stage Manager scene isn't released out from under the user.
+        observers.append(NotificationCenter.default.addObserver(
+            forName: .punktfunkReleaseCapture, object: nil, queue: .main
+        ) { [weak self] _ in
+            guard let self,
+                  self.view.window?.windowScene?.activationState == .foregroundActive else { return }
+            self.setCaptured(false)
+        })
 
         if captureEnabled {
             setCaptured(true) // entering a session is the deliberate "capture me" moment
@@ -411,6 +492,7 @@ public final class StreamViewController: StreamViewControllerBase {
         streamView.onPointerButton = nil
         streamView.onScroll = nil
         streamView.currentHostMode = nil
+        matchFollower = nil
         #endif
         #if os(tvOS)
         // Return the TV to the user's preferred mode — the home screen must not stay in the
@@ -419,12 +501,23 @@ public final class StreamViewController: StreamViewControllerBase {
         sessionDisplayManager = nil
         #endif
         presenter.stop()
+        lastDecodedContentSize = nil // the next session re-derives it from its first frame
         connection = nil
     }
 
     public override func viewDidLayoutSubviews() {
         super.viewDidLayoutSubviews()
         layoutMetalLayer()
+        #if os(iOS)
+        // Match-window (C3): feed the follower the view's physical-pixel size (points × scale).
+        let b = streamView.bounds
+        if b.width > 0, b.height > 0 {
+            let scale = renderScale
+            matchFollower?.noteSize(
+                widthPx: Int((b.width * scale).rounded()),
+                heightPx: Int((b.height * scale).rounded()))
+        }
+        #endif
         #if os(tvOS)
         applyDisplayCriteriaIfNeeded()
         #endif
@@ -485,12 +578,28 @@ public final class StreamViewController: StreamViewControllerBase {
         presenter.layout(in: streamView.bounds, contentsScale: renderScale)
     }
 
+    /// A new decoded size landed (a scene/mode resize's new IDR, or the first frame): push it to the
+    /// presenter's aspect-fit and re-layout NOW. A resize-END triggers no `viewDidLayoutSubviews`, so
+    /// this is what makes the metal sublayer track the new content aspect instead of stretching the
+    /// new frame into the pre-resize box. Deduped so a same-size repeat is a no-op. Main thread.
+    private func noteDecodedContentSize(width: Int, height: Int) {
+        let size = CGSize(width: width, height: height)
+        guard size.width > 0, size.height > 0, size != lastDecodedContentSize else { return }
+        lastDecodedContentSize = size
+        presenter.setContentSize(size)
+        layoutMetalLayer()
+    }
+
     #if os(iOS)
-    private func setCaptured(_ on: Bool) {
+    /// `fromClick` marks a click-driven engage (the released-state pointer click that re-captures):
+    /// that click's press/release are suppressed toward the host — it's the local engage gesture,
+    /// not a host click — exactly as macOS's `engageCapture(fromClick:)` does. Keyboard-driven
+    /// engages (⌘⎋) pass false so a normal click still reaches the host.
+    private func setCaptured(_ on: Bool, fromClick: Bool = false) {
         if on {
             // `connection != nil` is the session-active gate (presenter internals are opaque here).
             guard captureEnabled, !captured, connection != nil else { return }
-            inputCapture?.setForwarding(true)
+            inputCapture?.setForwarding(true, suppressClick: fromClick)
             captured = true
         } else {
             guard captured else { return }
@@ -589,6 +698,7 @@ final class StreamLayerUIView: UIView {
         let mouse = TouchMouse()
         mouse.send = { [weak self] event in self?.onTouchEvent?(event) }
         mouse.hostPoint = { [weak self] point in self?.hostPoint(from: point) }
+        mouse.onKeyboardGesture = { [weak self] show in self?.setSoftKeyboardVisible(show) }
         return mouse
     }()
     /// The finger route latched at gesture start — a Settings change mid-gesture applies to
@@ -599,6 +709,22 @@ final class StreamLayerUIView: UIView {
     func resetTouchInput() {
         touchMouse.reset()
         fingerRoute = nil
+        setSoftKeyboardVisible(false) // a stream that's gone takes its keyboard with it
+    }
+
+    /// The soft keyboard is keyed off first-responder status: the three-finger swipe
+    /// (TouchMouse) summons/dismisses it here, and the UIKeyInput conformance below turns
+    /// what it types into wire key events. Also the reason `canBecomeFirstResponder` is true
+    /// on iOS (tvOS anchors the responder chain on the CONTROLLER instead — see
+    /// StreamViewController.viewDidAppear).
+    override var canBecomeFirstResponder: Bool { true }
+
+    func setSoftKeyboardVisible(_ visible: Bool) {
+        if visible {
+            becomeFirstResponder()
+        } else if isFirstResponder {
+            resignFirstResponder()
+        }
     }
     #endif
 
@@ -770,4 +896,46 @@ final class StreamLayerUIView: UIView {
     }
     #endif
 }
+
+#if os(iOS)
+// The soft keyboard's output → wire key events. UIKeyInput is deliberately minimal (no
+// UITextInput): the stream needs keystrokes, not an editing buffer — insertions map through
+// `SoftKeyMap` to US-positional VKs (with a VK_LSHIFT wrap for shifted characters) and
+// characters outside the map (emoji, non-Latin scripts) are dropped, matching the wire's VK
+// contract. Events ride the same `onTouchEvent` path as the touch-driven mouse, so they're
+// gated on captureEnabled with everything else and can't leak past a trust prompt.
+extension StreamLayerUIView: UIKeyInput {
+    // Keep the IME literal — no autocorrect/smart substitutions; a remote desktop is not prose,
+    // and the host does its own text handling.
+    var autocorrectionType: UITextAutocorrectionType { get { .no } set {} }
+    var autocapitalizationType: UITextAutocapitalizationType { get { .none } set {} }
+    var spellCheckingType: UITextSpellCheckingType { get { .no } set {} }
+    var smartQuotesType: UITextSmartQuotesType { get { .no } set {} }
+    var smartDashesType: UITextSmartDashesType { get { .no } set {} }
+    var smartInsertDeleteType: UITextSmartInsertDeleteType { get { .no } set {} }
+    var keyboardType: UIKeyboardType { get { .asciiCapable } set {} }
+
+    var hasText: Bool { false }
+
+    func insertText(_ text: String) {
+        // A hardware keyboard's presses reach the host through GCKeyboard AND arrive here as
+        // UIKeyInput insertions while we're first responder — forwarding both would double
+        // every character, so the HID path owns keys whenever a hardware keyboard is attached.
+        guard GCKeyboard.coalesced == nil else { return }
+        for ch in text {
+            guard let key = SoftKeyMap.vk(for: ch) else { continue }
+            if key.shift { onTouchEvent?(.key(0xA0, down: true)) } // VK_LSHIFT
+            onTouchEvent?(.key(key.vk, down: true))
+            onTouchEvent?(.key(key.vk, down: false))
+            if key.shift { onTouchEvent?(.key(0xA0, down: false)) }
+        }
+    }
+
+    func deleteBackward() {
+        guard GCKeyboard.coalesced == nil else { return } // see insertText
+        onTouchEvent?(.key(0x08, down: true)) // VK_BACK
+        onTouchEvent?(.key(0x08, down: false))
+    }
+}
+#endif
 #endif

clients/apple/Tests/PunktfunkKitTests/GamepadWireTests.swift

@@ -3,6 +3,7 @@
 // player-LED-bits → GCControllerPlayerIndex map. All pure functions.
 
 import GameController
+import PunktfunkCore
 import XCTest
 
 @testable import PunktfunkKit
@@ -26,11 +27,16 @@ final class GamepadWireTests: XCTestCase {
         XCTAssertEqual(GamepadWire.x, 0x4000)
         XCTAssertEqual(GamepadWire.y, 0x8000)
         XCTAssertEqual(GamepadWire.touchpadClick, 0x10_0000)
+        XCTAssertEqual(GamepadWire.misc1, 0x0020_0000)
         // Every button is enumerated exactly once (releaseAll walks this list).
         let combined: UInt32 = GamepadWire.allButtons.reduce(0) { $0 | $1 }
-        XCTAssertEqual(combined, 0x0010_F7FF)
-        XCTAssertEqual(GamepadWire.allButtons.count, 16)
+        XCTAssertEqual(combined, 0x0030_F7FF)
+        XCTAssertEqual(GamepadWire.allButtons.count, 17)
         XCTAssertEqual(GamepadWire.allButtons.count, Set(GamepadWire.allButtons).count)
+        // Paddles are defined but not yet forwarded, so they stay out of allButtons for now.
+        for paddle in [GamepadWire.paddle1, GamepadWire.paddle2, GamepadWire.paddle3, GamepadWire.paddle4] {
+            XCTAssertFalse(GamepadWire.allButtons.contains(paddle))
+        }
         // Axis ids.
         XCTAssertEqual(GamepadWire.axisLSX, 0)
         XCTAssertEqual(GamepadWire.axisLSY, 1)
@@ -40,6 +46,79 @@ final class GamepadWireTests: XCTestCase {
         XCTAssertEqual(GamepadWire.axisRT, 5)
     }
 
+    func testButtonBitsMatchTheCABIVerbatim() {
+        // Assert EVERY wire constant against the generated C ABI header (punktfunk_core.h, the same
+        // source `punktfunk_core::input::gamepad` emits), so a Swift-side edit that drifts from the
+        // Rust contract fails CI — not just the handful spot-checked above. (Cross-cutting review
+        // finding G15: the button values were re-declared per client with only a 3-of-19 check.)
+        XCTAssertEqual(GamepadWire.dpadUp, UInt32(PUNKTFUNK_BTN_DPAD_UP))
+        XCTAssertEqual(GamepadWire.dpadDown, UInt32(PUNKTFUNK_BTN_DPAD_DOWN))
+        XCTAssertEqual(GamepadWire.dpadLeft, UInt32(PUNKTFUNK_BTN_DPAD_LEFT))
+        XCTAssertEqual(GamepadWire.dpadRight, UInt32(PUNKTFUNK_BTN_DPAD_RIGHT))
+        XCTAssertEqual(GamepadWire.start, UInt32(PUNKTFUNK_BTN_START))
+        XCTAssertEqual(GamepadWire.back, UInt32(PUNKTFUNK_BTN_BACK))
+        XCTAssertEqual(GamepadWire.leftStickClick, UInt32(PUNKTFUNK_BTN_LS_CLICK))
+        XCTAssertEqual(GamepadWire.rightStickClick, UInt32(PUNKTFUNK_BTN_RS_CLICK))
+        XCTAssertEqual(GamepadWire.leftShoulder, UInt32(PUNKTFUNK_BTN_LB))
+        XCTAssertEqual(GamepadWire.rightShoulder, UInt32(PUNKTFUNK_BTN_RB))
+        XCTAssertEqual(GamepadWire.guide, UInt32(PUNKTFUNK_BTN_GUIDE))
+        XCTAssertEqual(GamepadWire.a, UInt32(PUNKTFUNK_BTN_A))
+        XCTAssertEqual(GamepadWire.b, UInt32(PUNKTFUNK_BTN_B))
+        XCTAssertEqual(GamepadWire.x, UInt32(PUNKTFUNK_BTN_X))
+        XCTAssertEqual(GamepadWire.y, UInt32(PUNKTFUNK_BTN_Y))
+        XCTAssertEqual(GamepadWire.touchpadClick, UInt32(PUNKTFUNK_BTN_TOUCHPAD))
+        XCTAssertEqual(GamepadWire.misc1, UInt32(PUNKTFUNK_GAMEPAD_BTN_MISC1))
+        XCTAssertEqual(GamepadWire.paddle1, UInt32(PUNKTFUNK_GAMEPAD_BTN_PADDLE1))
+        XCTAssertEqual(GamepadWire.paddle2, UInt32(PUNKTFUNK_GAMEPAD_BTN_PADDLE2))
+        XCTAssertEqual(GamepadWire.paddle3, UInt32(PUNKTFUNK_GAMEPAD_BTN_PADDLE3))
+        XCTAssertEqual(GamepadWire.paddle4, UInt32(PUNKTFUNK_GAMEPAD_BTN_PADDLE4))
+        // Axis ids and pad count share the same header.
+        XCTAssertEqual(GamepadWire.axisLSX, UInt32(PUNKTFUNK_AXIS_LS_X))
+        XCTAssertEqual(GamepadWire.axisLSY, UInt32(PUNKTFUNK_AXIS_LS_Y))
+        XCTAssertEqual(GamepadWire.axisRSX, UInt32(PUNKTFUNK_AXIS_RS_X))
+        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))
+    }
+
+    func testPadIndexRidesFlagsOnEveryPerPadEvent() {
+        // The wire pad index is the low byte of `flags` (punktfunk_core::input) on button + axis.
+        let btn = PunktfunkInputEvent.gamepadButton(GamepadWire.a, down: true, pad: 3)
+        XCTAssertEqual(btn.kind, UInt8(PUNKTFUNK_INPUT_KIND_GAMEPAD_BUTTON.rawValue))
+        XCTAssertEqual(btn.code, GamepadWire.a)
+        XCTAssertEqual(btn.x, 1)
+        XCTAssertEqual(btn.flags, 3)
+        let axis = PunktfunkInputEvent.gamepadAxis(GamepadWire.axisRT, value: 200, pad: 5)
+        XCTAssertEqual(axis.kind, UInt8(PUNKTFUNK_INPUT_KIND_GAMEPAD_AXIS.rawValue))
+        XCTAssertEqual(axis.code, GamepadWire.axisRT)
+        XCTAssertEqual(axis.x, 200)
+        XCTAssertEqual(axis.flags, 5)
+        // Single-controller path stays byte-identical: pad 0 ⇒ flags 0, exactly as before.
+        XCTAssertEqual(PunktfunkInputEvent.gamepadButton(GamepadWire.a, down: false, pad: 0).flags, 0)
+        XCTAssertEqual(PunktfunkInputEvent.gamepadAxis(GamepadWire.axisLSX, value: 0, pad: 0).flags, 0)
+    }
+
+    func testArrivalAndRemoveWireLayout() {
+        // GamepadArrival (kind 14): code = the GamepadType wire byte, flags = pad index.
+        let arrival = PunktfunkInputEvent.gamepadArrival(
+            pref: PunktfunkConnection.GamepadType.dualSense.rawValue, pad: 2)
+        XCTAssertEqual(arrival.kind, UInt8(PUNKTFUNK_INPUT_KIND_GAMEPAD_ARRIVAL.rawValue))
+        XCTAssertEqual(arrival.code, PunktfunkConnection.GamepadType.dualSense.rawValue) // 2
+        XCTAssertEqual(arrival.flags, 2)
+        // The GamepadType raw values ARE the GamepadPref wire bytes the host resolves.
+        XCTAssertEqual(PunktfunkConnection.GamepadType.xbox360.rawValue, 1)
+        XCTAssertEqual(PunktfunkConnection.GamepadType.dualSense.rawValue, 2)
+        XCTAssertEqual(PunktfunkConnection.GamepadType.xboxOne.rawValue, 3)
+        XCTAssertEqual(PunktfunkConnection.GamepadType.dualShock4.rawValue, 4)
+        // GamepadRemove (kind 13): flags = pad index (the core stamps the per-pad seq).
+        let remove = PunktfunkInputEvent.gamepadRemove(pad: 7)
+        XCTAssertEqual(remove.kind, UInt8(PUNKTFUNK_INPUT_KIND_GAMEPAD_REMOVE.rawValue))
+        XCTAssertEqual(remove.flags, 7)
+        // 16 addressable pads (punktfunk_core::input::MAX_PADS).
+        XCTAssertEqual(GamepadWire.maxPads, 16)
+    }
+
     func testTouchpadConversionCorners() {
         // GC ±1 with +y up → wire 0...65535 with origin top-left, +y down.
         let topLeft = GamepadWire.touchpad(x: -1, y: 1)

clients/apple/Tests/PunktfunkKitTests/MatchWindowTests.swift

@@ -0,0 +1,43 @@
+// The Match-window trigger discipline (design/midstream-resolution-resize.md D2), as pure
+// functions — the same rules the session binary's `resize_decision` unit-tests: physical pixels
+// even-floored and clamped ≥ 320×200, skip a size equal to the live mode, and request each
+// distinct size at most once (so a rejected size / a host rollback can't loop).
+
+import XCTest
+
+@testable import PunktfunkKit
+
+final class MatchWindowTests: XCTestCase {
+    func testNormalizeEvenFloorsAndClamps() {
+        // Odd pixels floor to even (the host rejects odd dimensions).
+        let a = MatchWindow.normalize(widthPx: 1001, heightPx: 601)
+        XCTAssertEqual(a.width, 1000)
+        XCTAssertEqual(a.height, 600)
+        // Already-even sizes pass through.
+        let b = MatchWindow.normalize(widthPx: 2560, heightPx: 1440)
+        XCTAssertEqual(b.width, 2560)
+        XCTAssertEqual(b.height, 1440)
+        // Tiny / zero clamp to the host floor.
+        let c = MatchWindow.normalize(widthPx: 100, heightPx: 80)
+        XCTAssertEqual(c.width, 320)
+        XCTAssertEqual(c.height, 200)
+        let z = MatchWindow.normalize(widthPx: 0, heightPx: -4)
+        XCTAssertEqual(z.width, 320)
+        XCTAssertEqual(z.height, 200)
+    }
+
+    func testRequestSkipsEqualAndAlreadyRequested() {
+        // A new size (different from the live mode, not yet requested) → request it.
+        let r = MatchWindow.request(
+            target: (1000, 600), current: (1280, 720), lastRequested: (800, 500))
+        XCTAssertEqual(r?.width, 1000)
+        XCTAssertEqual(r?.height, 600)
+        // Equal to the live mode → nothing to do.
+        XCTAssertNil(MatchWindow.request(
+            target: (1280, 720), current: (1280, 720), lastRequested: nil))
+        // Already requested once → don't re-ask (covers a rejected size AND a host rollback:
+        // accepted → rebuild failed → corrective ack restored the old mode must not loop).
+        XCTAssertNil(MatchWindow.request(
+            target: (1000, 600), current: (1280, 720), lastRequested: (1000, 600)))
+    }
+}

clients/apple/Tests/PunktfunkKitTests/ResizeIndicatorTests.swift

@@ -0,0 +1,52 @@
+import XCTest
+
+@testable import PunktfunkKit
+
+final class ResizeIndicatorTests: XCTestCase {
+    func testInactiveUntilSteered() {
+        var r = ResizeIndicator()
+        XCTAssertFalse(r.active)
+        // A decoded frame with nothing pending is a no-op (session start / steady state).
+        r.decoded(width: 1920, height: 1080)
+        XCTAssertFalse(r.active)
+    }
+
+    func testSteeringActivatesAndDecodedTargetClears() {
+        var r = ResizeIndicator()
+        r.steering(width: 2560, height: 1440, now: 0)
+        XCTAssertTrue(r.active)
+        // A frame at a DIFFERENT size (the old mode still draining) doesn't clear it.
+        r.decoded(width: 1920, height: 1080)
+        XCTAssertTrue(r.active)
+        // The target frame lands → clear.
+        r.decoded(width: 2560, height: 1440)
+        XCTAssertFalse(r.active)
+    }
+
+    func testTimeoutClearsWhenTargetNeverArrives() {
+        var r = ResizeIndicator(timeout: 2.5)
+        r.steering(width: 2560, height: 1440, now: 10)
+        r.tick(now: 12) // 2 s < timeout — still up
+        XCTAssertTrue(r.active)
+        r.tick(now: 12.6) // 2.6 s ≥ timeout — a rejected/capped switch clears
+        XCTAssertFalse(r.active)
+    }
+
+    func testDragReArmsTimeoutOnEachNewTarget() {
+        var r = ResizeIndicator(timeout: 2.5)
+        r.steering(width: 2000, height: 1200, now: 0)
+        r.steering(width: 2200, height: 1200, now: 2) // target changed → since re-armed to 2
+        r.tick(now: 4) // only 2 s since the last change — still up (drag isn't a timeout)
+        XCTAssertTrue(r.active)
+        r.tick(now: 4.6) // 2.6 s since the last change → clears
+        XCTAssertFalse(r.active)
+    }
+
+    func testSteadyDragDoesNotResetTimeout() {
+        var r = ResizeIndicator(timeout: 2.5)
+        r.steering(width: 2560, height: 1440, now: 0)
+        r.steering(width: 2560, height: 1440, now: 1) // SAME target → since stays 0
+        r.tick(now: 2.6) // 2.6 s since the ORIGINAL steer → clears (not reset by the repeat)
+        XCTAssertFalse(r.active)
+    }
+}

clients/decky/bin/punktfunkrun.sh

@@ -12,7 +12,7 @@
 # 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)
+#   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)
@@ -36,24 +36,31 @@ set -u
 APPID="${PF_APPID:-io.unom.Punktfunk}"
 FLATPAK="${PF_FLATPAK:-flatpak}"
 
-if [ -z "${PF_HOST:-}" ]; then
-    echo "punktfunkrun: PF_HOST is not set (the plugin sets it as a launch option)" >&2
-    exit 2
-fi
-
 # exec so the flatpak client IS the game process — when it exits, Steam ends the "game" and
 # Gaming Mode reclaims focus automatically (no manual refocus needed).
 # --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).
 if [ -n "${PF_BROWSE:-}" ]; then
-    # The gamepad library launcher: browse the host's games on-screen, A streams one,
-    # session end returns to the launcher, B quits back to Gaming Mode.
+    # 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 $APPID --browse (console home)" >&2
+        exec "$FLATPAK" run --arch=x86_64 "$APPID" --browse --fullscreen
+    fi
     echo "punktfunkrun: library $APPID --browse $PF_HOST" >&2
     if [ -n "${PF_MGMT:-}" ]; then
         exec "$FLATPAK" run --arch=x86_64 "$APPID" --browse "$PF_HOST" --mgmt "$PF_MGMT" --fullscreen
     fi
     exec "$FLATPAK" run --arch=x86_64 "$APPID" --browse "$PF_HOST" --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
+    exit 2
+fi
 if [ -n "${PF_LAUNCH:-}" ]; then
     # A pinned game: the id rides the session Hello and the host launches that title.
     echo "punktfunkrun: streaming $APPID --connect $PF_HOST --launch $PF_LAUNCH" >&2

clients/decky/controller_config/punktfunk.vdf

@@ -0,0 +1,757 @@
+"controller_mappings"
+{
+	"version"		"3"
+	"revision"		"2"
+	"title"		"Punktfunk"
+	"description"		"Native touchscreen + full gamepad passthrough for the Punktfunk streaming client."
+	"creator"		"0"
+	"progenitor"		"template://controller_neptune_gamepad_fps.vdf"
+	"url"		"template://controller_neptune_gamepad_fps.vdf"
+	"export_type"		"unknown"
+	"controller_type"		"controller_neptune"
+	"controller_caps"		"23117823"
+	"major_revision"		"0"
+	"minor_revision"		"0"
+	"Timestamp"		"0"
+	"localization"
+	{
+		"english"
+		{
+			"title"		"Punktfunk"
+			"description"		"Native touchscreen + full gamepad for Punktfunk streaming."
+		}
+	}
+	"group"
+	{
+		"id"		"0"
+		"mode"		"four_buttons"
+		"name"		""
+		"description"		""
+		"inputs"
+		{
+			"button_a"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button A, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+			"button_b"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button B, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+			"button_x"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button X, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+			"button_y"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button Y, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+		}
+	}
+	"group"
+	{
+		"id"		"1"
+		"mode"		"dpad"
+		"name"		""
+		"description"		""
+		"inputs"
+		{
+			"dpad_north"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button dpad_up, , "
+						}
+						"settings"
+						{
+							"haptic_intensity"		"1"
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+			"dpad_south"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button dpad_down, , "
+						}
+						"settings"
+						{
+							"haptic_intensity"		"1"
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+			"dpad_east"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button dpad_right, , "
+						}
+						"settings"
+						{
+							"haptic_intensity"		"1"
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+			"dpad_west"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button dpad_left, , "
+						}
+						"settings"
+						{
+							"haptic_intensity"		"1"
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+		}
+	}
+	"group"
+	{
+		"id"		"2"
+		"mode"		"joystick_move"
+		"name"		""
+		"description"		""
+		"inputs"
+		{
+			"click"
+			{
+				"activators"
+				{
+					"Soft_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button JOYSTICK_RIGHT, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+		}
+	}
+	"group"
+	{
+		"id"		"3"
+		"mode"		"joystick_move"
+		"name"		""
+		"description"		""
+		"inputs"
+		{
+			"click"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button JOYSTICK_LEFT, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+		}
+		"settings"
+		{
+			"deadzone_inner_radius"		"7199"
+		}
+	}
+	"group"
+	{
+		"id"		"4"
+		"mode"		"trigger"
+		"name"		""
+		"description"		""
+		"inputs"
+		{
+		}
+		"settings"
+		{
+			"output_trigger"		"1"
+		}
+	}
+	"group"
+	{
+		"id"		"5"
+		"mode"		"trigger"
+		"name"		""
+		"description"		""
+		"inputs"
+		{
+		}
+		"settings"
+		{
+			"output_trigger"		"2"
+		}
+	}
+	"group"
+	{
+		"id"		"6"
+		"mode"		"joystick_move"
+		"name"		""
+		"description"		""
+		"inputs"
+		{
+			"click"
+			{
+				"activators"
+				{
+					"Soft_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button JOYSTICK_RIGHT, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+		}
+	}
+	"group"
+	{
+		"id"		"8"
+		"mode"		"joystick_move"
+		"name"		""
+		"description"		""
+		"inputs"
+		{
+			"click"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button JOYSTICK_RIGHT, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+		}
+	}
+	"group"
+	{
+		"id"		"9"
+		"mode"		"dpad"
+		"name"		""
+		"description"		""
+		"inputs"
+		{
+			"dpad_north"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button DPAD_UP, , "
+						}
+						"settings"
+						{
+							"haptic_intensity"		"1"
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+			"dpad_south"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button DPAD_DOWN, , "
+						}
+						"settings"
+						{
+							"haptic_intensity"		"1"
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+			"dpad_east"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button DPAD_RIGHT, , "
+						}
+						"settings"
+						{
+							"haptic_intensity"		"1"
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+			"dpad_west"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button DPAD_LEFT, , "
+						}
+						"settings"
+						{
+							"haptic_intensity"		"1"
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+		}
+		"settings"
+		{
+			"requires_click"		"0"
+			"haptic_intensity_override"		"0"
+		}
+	}
+	"group"
+	{
+		"id"		"10"
+		"mode"		"single_button"
+		"name"		""
+		"description"		""
+		"inputs"
+		{
+			"click"
+			{
+				"activators"
+				{
+					"Soft_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button START, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+		}
+	}
+	"group"
+	{
+		"id"		"11"
+		"mode"		"single_button"
+		"name"		""
+		"description"		""
+		"inputs"
+		{
+			"click"
+			{
+				"activators"
+				{
+					"Soft_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button SELECT, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+		}
+	}
+	"group"
+	{
+		"id"		"12"
+		"mode"		"mouse_joystick"
+		"name"		""
+		"description"		""
+		"inputs"
+		{
+			"click"
+			{
+				"activators"
+				{
+					"Soft_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button JOYSTICK_RIGHT, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+		}
+	}
+	"group"
+	{
+		"id"		"13"
+		"mode"		"flickstick"
+		"name"		""
+		"description"		""
+		"inputs"
+		{
+			"click"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button JOYSTICK_RIGHT, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+		}
+	}
+	"group"
+	{
+		"id"		"14"
+		"mode"		"flickstick"
+		"name"		""
+		"description"		""
+		"inputs"
+		{
+			"click"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button JOYSTICK_LEFT, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+		}
+	}
+	"group"
+	{
+		"id"		"15"
+		"mode"		"flickstick"
+		"name"		""
+		"description"		""
+		"inputs"
+		{
+			"click"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button JOYSTICK_RIGHT, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+		}
+	}
+	"group"
+	{
+		"id"		"16"
+		"mode"		"flickstick"
+		"name"		""
+		"description"		""
+		"inputs"
+		{
+			"click"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button JOYSTICK_LEFT, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+		}
+	}
+	"group"
+	{
+		"id"		"7"
+		"mode"		"switches"
+		"name"		""
+		"description"		""
+		"inputs"
+		{
+			"button_escape"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button start, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+			"button_menu"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button select, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+			"left_bumper"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button shoulder_left, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+			"right_bumper"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"xinput_button shoulder_right, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+			"button_back_left"
+			{
+				"activators"
+				{
+				}
+				"disabled_activators"
+				{
+				}
+			}
+			"button_back_right"
+			{
+				"activators"
+				{
+				}
+				"disabled_activators"
+				{
+				}
+			}
+			"button_back_left_upper"
+			{
+				"activators"
+				{
+				}
+				"disabled_activators"
+				{
+				}
+			}
+			"button_back_right_upper"
+			{
+				"activators"
+				{
+				}
+				"disabled_activators"
+				{
+				}
+			}
+			"always_on_action"
+			{
+				"activators"
+				{
+					"Full_Press"
+					{
+						"bindings"
+						{
+							"binding"		"controller_action ts_n, , "
+						}
+					}
+				}
+				"disabled_activators"
+				{
+				}
+			}
+		}
+	}
+	"preset"
+	{
+		"id"		"0"
+		"name"		"Default"
+		"group_source_bindings"
+		{
+			"7"		"switch active"
+			"0"		"button_diamond active"
+			"1"		"left_trackpad active"
+			"11"		"left_trackpad inactive"
+			"16"		"left_trackpad inactive"
+			"2"		"right_trackpad inactive"
+			"6"		"right_trackpad inactive"
+			"10"		"right_trackpad inactive"
+			"12"		"right_trackpad active"
+			"15"		"right_trackpad inactive"
+			"3"		"joystick active"
+			"14"		"joystick inactive"
+			"4"		"left_trigger active"
+			"5"		"right_trigger active"
+			"8"		"right_joystick active"
+			"13"		"right_joystick inactive"
+			"9"		"dpad active"
+		}
+	}
+	"settings"
+	{
+		"left_trackpad_mode"		"0"
+		"right_trackpad_mode"		"0"
+	}
+}

clients/decky/main.py

@@ -89,6 +89,93 @@ def _pins_path() -> Path:
     return _client_config_dir() / "decky-pinned.json"
 
 
+# --- Steam Input controller config injection (native touchscreen via the ts_n command) --------
+# The Deck's touchscreen only reaches the app as native wl_touch when a Steam Input layout with
+# the "Touchscreen Native Support" (controller_action ts_n) command is active for the game. We
+# ship that layout (controller_config/punktfunk.vdf, built on Steam's gamepad-fps template) and
+# point our shortcuts at it, EmuDeck-style: drop it in controller_base/templates/ (so it is also
+# a selectable "Punktfunk" template) AND set each account's configset entry for our shortcut's
+# game key to that template. Steam keys non-Steam games by their LOWERCASE NAME (verified on the
+# Deck: our "Punktfunk" shortcut → the "punktfunk" configset key), so both our shortcuts (same
+# name) share one entry. controller_neptune = the Deck's built-in controller type.
+CONTROLLER_TEMPLATE = "punktfunk.vdf"
+
+
+def _steam_root() -> Path:
+    """Steam's base dir on SteamOS (~/.steam/steam symlinks here)."""
+    return Path(decky.DECKY_USER_HOME) / ".local" / "share" / "Steam"
+
+
+def _controller_template_src() -> Path:
+    return Path(decky.DECKY_PLUGIN_DIR) / "controller_config" / CONTROLLER_TEMPLATE
+
+
+def _chown_like_parent(path: Path) -> None:
+    """The Decky backend runs as root, so files it CREATES in the deck-owned Steam tree land
+    root-owned — which would stop Steam (running as the user) from rewriting them. Match the
+    parent dir's owner so Steam retains write access. Best-effort."""
+    try:
+        st = path.parent.stat()
+        os.chown(path, st.st_uid, st.st_gid)
+    except OSError:
+        pass
+
+
+def _configset_dirs() -> list[Path]:
+    """Every Steam account's controller-config dir holding configset_controller_neptune.vdf."""
+    base = _steam_root() / "steamapps" / "common" / "Steam Controller Configs"
+    return [p / "config" for p in sorted(base.glob("*")) if (p / "config").is_dir()]
+
+
+def _upsert_configset_entry(text: str, key: str, source_type: str, source_val: str) -> str:
+    """Set the top-level ``"<key>" { "<source_type>" "<source_val>" }`` block in a
+    configset_controller_neptune.vdf, replacing any existing block for that key (case-insensitive)
+    or inserting one before the file's final closing brace. Targeted (only our key is touched) so
+    the hundreds of other game entries stay byte-for-byte intact. Creates the wrapping
+    ``"controller_config" { }`` skeleton when the file is empty/new."""
+    block = f'\t"{key}"\n\t{{\n\t\t"{source_type}"\t\t"{source_val}"\n\t}}\n'
+    if '"controller_config"' not in text:
+        return '"controller_config"\n{\n' + block + "}\n"
+
+    lower = text.lower()
+    needle = f'"{key.lower()}"'
+    # Find the key token that begins a top-level entry (its own line), then its "{ … }" block.
+    search_from = 0
+    while True:
+        idx = lower.find(needle, search_from)
+        if idx == -1:
+            break
+        # Must be a standalone key line (preceded only by whitespace back to a newline).
+        line_start = text.rfind("\n", 0, idx) + 1
+        if text[line_start:idx].strip() != "":
+            search_from = idx + len(needle)
+            continue
+        brace = text.find("{", idx)
+        if brace == -1:
+            break
+        depth = 0
+        i = brace
+        while i < len(text):
+            if text[i] == "{":
+                depth += 1
+            elif text[i] == "}":
+                depth -= 1
+                if depth == 0:
+                    break
+            i += 1
+        end = i + 1
+        # Consume the trailing newline after the block so we don't accumulate blank lines.
+        if end < len(text) and text[end] == "\n":
+            end += 1
+        return text[:line_start] + block + text[end:]
+
+    # Not present — insert before the last closing brace (the controller_config block's end).
+    last_close = text.rstrip().rfind("}")
+    if last_close == -1:
+        return text.rstrip() + "\n" + block
+    return text[:last_close] + block + text[last_close:]
+
+
 def _parse_library_tsv(stdout: str) -> list[dict]:
     """Parse the flatpak client's ``--library`` output: one ``id\\tstore\\ttitle`` line per
     game plus a trailing ``N game(s)`` count line (no tabs — it self-skips here). A title
@@ -726,10 +813,10 @@ class Plugin:
             return {"ok": False, "error": str(exc)}
 
     async def shortcut_art(self) -> dict:
-        """The Steam-shortcut artwork shipped with the plugin (``assets/``, generated by
-        ``scripts/gen-steam-art.py``): base64 PNGs for SetCustomArtworkForApp plus the
-        icon's absolute path for SetShortcutIcon (which wants a file, not bytes). Missing
-        files are simply omitted — artwork is cosmetic and must never block a launch."""
+        """The Steam-shortcut artwork shipped with the plugin (committed under ``assets/``):
+        base64 PNGs (grid/gridwide/hero/logo) for SetCustomArtworkForApp plus the icon's
+        absolute path for SetShortcutIcon (which wants a file, not bytes). Missing files are
+        simply omitted — artwork is cosmetic and must never block a launch."""
         art: dict = {}
         base = Path(decky.DECKY_PLUGIN_DIR) / "assets"
         for key, fname in (
@@ -746,6 +833,54 @@ class Plugin:
         art["icon_path"] = str(icon) if icon.exists() else ""
         return art
 
+    async def apply_controller_config(self, name: str = "Punktfunk") -> dict:
+        """Install our Steam Input layout (native touchscreen `ts_n` + gamepad passthrough) and
+        point the shortcut(s) at it, so the Deck touchscreen reaches the client as native touch
+        with zero manual controller setup. Best-effort + idempotent — a controller tweak must
+        never block a launch, so failures are reported, not raised. Both shortcuts share the same
+        name → the same lowercase configset key, so one entry per account covers both."""
+        src = _controller_template_src()
+        if not src.exists():
+            return {"ok": False, "error": "template-missing", "detail": str(src)}
+        key = name.strip().lower()
+        applied: list[str] = []
+        errors: list[str] = []
+        # 1) Ship it as a selectable template (also the safe fallback if Steam clobbers the
+        #    configset write on exit): controller_base/templates/punktfunk.vdf.
+        try:
+            tdir = _steam_root() / "controller_base" / "templates"
+            tdir.mkdir(parents=True, exist_ok=True)
+            dst = tdir / CONTROLLER_TEMPLATE
+            shutil.copyfile(src, dst)
+            _chown_like_parent(dst)
+            applied.append("template")
+        except OSError as e:
+            errors.append(f"template: {e}")
+        # 2) Point each Steam account's configset at that template for our game key.
+        dirs = _configset_dirs()
+        for d in dirs:
+            f = d / "configset_controller_neptune.vdf"
+            try:
+                text = f.read_text(encoding="utf-8") if f.exists() else ""
+                new = _upsert_configset_entry(text, key, "template", CONTROLLER_TEMPLATE)
+                if new != text:
+                    if f.exists():  # keep one recoverable backup before our first edit
+                        bak = f.with_name(f.name + ".pf-bak")
+                        if not bak.exists():
+                            shutil.copyfile(f, bak)
+                            _chown_like_parent(bak)
+                    existed = f.exists()
+                    f.write_text(new, encoding="utf-8")
+                    if not existed:  # a freshly-created file is root-owned — hand it to the user
+                        _chown_like_parent(f)
+                applied.append(f"configset:{d.parent.name}")
+            except OSError as e:
+                errors.append(f"{d.parent.name}: {e}")
+        decky.logger.info(
+            "apply_controller_config key=%s applied=%s errors=%s", key, applied, errors
+        )
+        return {"ok": not errors, "applied": applied, "errors": errors, "accounts": len(dirs)}
+
     async def runner_info(self) -> dict:
         """The wrapper-script path + flatpak app id the frontend needs to create the Steam
         shortcut. The shortcut invokes the script through ``/bin/sh`` (see steam.ts), so no

clients/decky/scripts/gen-steam-art.py

@@ -1,297 +0,0 @@
-#!/usr/bin/env python3
-"""Generate the Steam-shortcut artwork for the Decky plugin (committed, like the tray icons).
-
-The plugin registers a non-Steam shortcut ("Punktfunk") whose grid/hero/logo/icon Steam
-would otherwise render as a gray placeholder tile. These assets brand it: the lens mark
-(same geometry as scripts/gen-tray-icons.py / web's brand-mark.tsx) over the brand-navy
-gradient, plus a monoline "punktfunk" wordmark built from stroke segments ("punktfunk"
-needs only p·u·n·k·t·f). The frontend applies them via
-SteamClient.Apps.SetCustomArtworkForApp / SetShortcutIcon (src/steam.ts).
-
-Outputs (checked in; re-run only when the brand changes):
-  clients/decky/assets/grid.png       600 x 900   library capsule (portrait)
-  clients/decky/assets/gridwide.png   920 x 430   wide capsule (recent games / search)
-  clients/decky/assets/hero.png      1920 x 620   game-page banner
-  clients/decky/assets/logo.png     transparent   overlaid on the hero by Steam
-  clients/decky/assets/icon.png       256 x 256   list icon (SetShortcutIcon)
-
-Pure stdlib. Unlike the tiny tray icons this rasterizes big surfaces, so edges are
-antialiased analytically from signed distances (one sample per pixel) instead of 4x4
-supersampling.
-"""
-
-import math
-import struct
-import zlib
-from pathlib import Path
-
-HERE = Path(__file__).resolve().parent.parent  # clients/decky
-OUT = HERE / "assets"
-
-# Brand-mark geometry in its 1000-unit viewbox (identical to gen-tray-icons.py).
-R = 194.41
-C1 = (403.037, 597.262)  # light circle, behind
-C2 = (597.8075, 402.8525)  # deep circle, in front
-BB_MIN = (C1[0] - R, C2[1] - R)
-BB_MAX = (C2[0] + R, C1[1] + R)
-MARK_CENTER = ((BB_MIN[0] + BB_MAX[0]) / 2, (BB_MIN[1] + BB_MAX[1]) / 2)
-MARK_SPAN = BB_MAX[0] - BB_MIN[0]
-
-COL_LIGHT = (0xA7, 0x9F, 0xF8)
-COL_DEEP = (0x6C, 0x5B, 0xF3)
-COL_HI = (0xD2, 0xC9, 0xFB)
-WORD = (0xEF, 0xEC, 0xFD)  # wordmark: near-white lavender
-BG_TOP = (0x28, 0x1E, 0x46)
-BG_BOT = (0x12, 0x0D, 0x22)
-
-
-# ------------------------------------------------------------------------------------------
-# Wordmark: monoline glyphs as polylines in a unit box (y down; x-height top y=0, baseline
-# y=1, ascender to -0.5, descender to +1.5). Arcs are sampled into the polylines, so the
-# rasterizer only ever measures distance-to-segment; round caps/joins fall out of that.
-# ------------------------------------------------------------------------------------------
-def _arc(cx, cy, r, a0, a1, n=24):
-    """Polyline along a circle arc; degrees, 0 = +x, angles grow clockwise on screen."""
-    pts = []
-    for i in range(n + 1):
-        a = math.radians(a0 + (a1 - a0) * i / n)
-        pts.append((cx + r * math.cos(a), cy + r * math.sin(a)))
-    return pts
-
-
-GLYPHS = {
-    # letter: (advance, [polyline, ...])
-    "p": (1.05, [[(0, 0), (0, 1.5)], _arc(0.5, 0.5, 0.5, 0, 360)]),
-    "u": (1.05, [[(0, 0), (0, 0.5)], _arc(0.5, 0.5, 0.5, 0, 180), [(1, 0), (1, 0.5)]]),
-    "n": (1.05, [[(0, 0), (0, 1)], _arc(0.5, 0.5, 0.5, 180, 360), [(1, 0.5), (1, 1)]]),
-    "k": (1.0, [[(0, -0.5), (0, 1)], [(0, 0.62), (0.78, 0)], [(0.30, 0.38), (0.85, 1)]]),
-    "t": (0.85, [[(0.42, -0.42), (0.42, 1)], [(0, 0), (0.84, 0)]]),
-    "f": (
-        0.85,
-        [[(0.42, 1), (0.42, -0.15)] + _arc(0.75, -0.15, 0.33, 180, 270, 12), [(0, 0), (0.78, 0)]],
-    ),
-}
-GAP = 0.34  # inter-letter gap, in glyph units
-STROKE = 0.26  # stroke thickness, in glyph units
-ASCENT, DESCENT = -0.5, 1.5  # glyph-space vertical extent
-
-
-def word_segments(text):
-    """The word's stroke segments [(x1,y1,x2,y2)] in glyph units, plus its unit width."""
-    segs = []
-    x = 0.0
-    for ch in text:
-        adv, lines = GLYPHS[ch]
-        for line in lines:
-            for (x1, y1), (x2, y2) in zip(line, line[1:]):
-                segs.append((x + x1, y1, x + x2, y2))
-        x += adv + GAP
-    return segs, x - GAP
-
-
-def render_word_alpha(text, unit_px):
-    """Coverage (0..255) buffer of the word at `unit_px` pixels per glyph unit."""
-    segs, width_u = word_segments(text)
-    half = STROKE / 2 * unit_px
-    pad = half + 1.5
-    w = math.ceil(width_u * unit_px + 2 * pad)
-    h = math.ceil((DESCENT - ASCENT) * unit_px + 2 * pad)
-    ox, oy = pad, pad - ASCENT * unit_px
-    px_segs = [(ox + a * unit_px, oy + b * unit_px, ox + c * unit_px, oy + d * unit_px) for a, b, c, d in segs]
-    # Bucket segments per pixel column range so each pixel tests only nearby strokes.
-    buf = bytearray(w * h)
-    for x1, y1, x2, y2 in px_segs:
-        lo_x = max(0, math.floor(min(x1, x2) - pad))
-        hi_x = min(w, math.ceil(max(x1, x2) + pad))
-        lo_y = max(0, math.floor(min(y1, y2) - pad))
-        hi_y = min(h, math.ceil(max(y1, y2) + pad))
-        dx, dy = x2 - x1, y2 - y1
-        len2 = dx * dx + dy * dy
-        for py in range(lo_y, hi_y):
-            row = py * w
-            fy = py + 0.5
-            for px in range(lo_x, hi_x):
-                fx = px + 0.5
-                if len2 > 0:
-                    t = max(0.0, min(1.0, ((fx - x1) * dx + (fy - y1) * dy) / len2))
-                else:
-                    t = 0.0
-                d = math.hypot(fx - (x1 + t * dx), fy - (y1 + t * dy))
-                cov = 0.5 + (half - d)
-                if cov > 0:
-                    v = min(255, round(min(1.0, cov) * 255))
-                    if v > buf[row + px]:
-                        buf[row + px] = v
-    return buf, w, h
-
-
-# ------------------------------------------------------------------------------------------
-# Canvas: RGBA bytearray, straight alpha, painted back to front.
-# ------------------------------------------------------------------------------------------
-class Canvas:
-    def __init__(self, w, h):
-        self.w, self.h = w, h
-        self.buf = bytearray(w * h * 4)
-
-    def fill_gradient(self, top, bottom):
-        for y in range(self.h):
-            t = y / max(1, self.h - 1)
-            c = bytes(
-                (
-                    round(top[0] + (bottom[0] - top[0]) * t),
-                    round(top[1] + (bottom[1] - top[1]) * t),
-                    round(top[2] + (bottom[2] - top[2]) * t),
-                    255,
-                )
-            )
-            self.buf[y * self.w * 4 : (y + 1) * self.w * 4] = c * self.w
-
-    def _blend(self, i, rgb, a):
-        """`rgb` over the pixel at byte offset i with coverage a (0..1)."""
-        if a <= 0:
-            return
-        b = self.buf
-        ia = 1.0 - a
-        da = b[i + 3] / 255.0
-        oa = a + da * ia
-        if oa <= 0:
-            return
-        for k in range(3):
-            b[i + k] = round((rgb[k] * a + b[i + k] * da * ia) / oa)
-        b[i + 3] = round(oa * 255)
-
-    def glow(self, cx, cy, radius, rgb, strength):
-        """Soft gaussian-ish radial glow (for the mark's halo on the big surfaces)."""
-        lo_x = max(0, math.floor(cx - 2.2 * radius))
-        hi_x = min(self.w, math.ceil(cx + 2.2 * radius))
-        lo_y = max(0, math.floor(cy - 2.2 * radius))
-        hi_y = min(self.h, math.ceil(cy + 2.2 * radius))
-        for y in range(lo_y, hi_y):
-            for x in range(lo_x, hi_x):
-                d2 = ((x + 0.5 - cx) ** 2 + (y + 0.5 - cy) ** 2) / (radius * radius)
-                a = strength * math.exp(-2.5 * d2)
-                if a > 1 / 255:
-                    self._blend((y * self.w + x) * 4, rgb, a)
-
-    def mark(self, cx, cy, span):
-        """The lens mark centered at (cx, cy) with the given pixel span."""
-        scale = span / MARK_SPAN
-        c1 = (cx + (C1[0] - MARK_CENTER[0]) * scale, cy + (C1[1] - MARK_CENTER[1]) * scale)
-        c2 = (cx + (C2[0] - MARK_CENTER[0]) * scale, cy + (C2[1] - MARK_CENTER[1]) * scale)
-        r = R * scale
-        lo_x = max(0, math.floor(min(c1[0], c2[0]) - r - 2))
-        hi_x = min(self.w, math.ceil(max(c1[0], c2[0]) + r + 2))
-        lo_y = max(0, math.floor(min(c1[1], c2[1]) - r - 2))
-        hi_y = min(self.h, math.ceil(max(c1[1], c2[1]) + r + 2))
-        for y in range(lo_y, hi_y):
-            for x in range(lo_x, hi_x):
-                fx, fy = x + 0.5, y + 0.5
-                cov1 = min(1.0, max(0.0, 0.5 + r - math.hypot(fx - c1[0], fy - c1[1])))
-                cov2 = min(1.0, max(0.0, 0.5 + r - math.hypot(fx - c2[0], fy - c2[1])))
-                if cov1 <= 0 and cov2 <= 0:
-                    continue
-                i = (y * self.w + x) * 4
-                self._blend(i, COL_LIGHT, cov1)
-                self._blend(i, COL_DEEP, cov2)
-                self._blend(i, COL_HI, min(cov1, cov2))
-
-    def word(self, text, unit_px, cx, cy):
-        """The wordmark centered at (cx, cy); `unit_px` = pixels per glyph unit."""
-        alpha, w, h = render_word_alpha(text, unit_px)
-        ox = round(cx - w / 2)
-        # Optical vertical centering on the x-height band (0..1 in glyph units), not the
-        # ascender/descender box — the word reads centered that way.
-        pad = STROKE / 2 * unit_px + 1.5
-        band_mid = pad - ASCENT * unit_px + 0.5 * unit_px
-        oy = round(cy - band_mid)
-        for y in range(h):
-            ty = y + oy
-            if not 0 <= ty < self.h:
-                continue
-            for x in range(w):
-                a = alpha[y * w + x]
-                if a:
-                    tx = x + ox
-                    if 0 <= tx < self.w:
-                        self._blend((ty * self.w + tx) * 4, WORD, a / 255.0)
-
-    def round_corners(self, radius):
-        """Multiply alpha with a rounded-rect mask (icon)."""
-        for y in range(self.h):
-            for x in range(self.w):
-                dx = max(0.0, max(radius - (x + 0.5), (x + 0.5) - (self.w - radius)))
-                dy = max(0.0, max(radius - (y + 0.5), (y + 0.5) - (self.h - radius)))
-                if dx > 0 and dy > 0:
-                    cov = min(1.0, max(0.0, 0.5 + radius - math.hypot(dx, dy)))
-                    i = (y * self.w + x) * 4
-                    self.buf[i + 3] = round(self.buf[i + 3] * cov)
-
-    def png(self):
-        def chunk(tag, data):
-            return (
-                struct.pack(">I", len(data))
-                + tag
-                + data
-                + struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF)
-            )
-
-        ihdr = struct.pack(">IIBBBBB", self.w, self.h, 8, 6, 0, 0, 0)
-        raw = b"".join(
-            b"\x00" + bytes(self.buf[y * self.w * 4 : (y + 1) * self.w * 4]) for y in range(self.h)
-        )
-        return (
-            b"\x89PNG\r\n\x1a\n"
-            + chunk(b"IHDR", ihdr)
-            + chunk(b"IDAT", zlib.compress(raw, 9))
-            + chunk(b"IEND", b"")
-        )
-
-
-def save(name, canvas):
-    OUT.mkdir(parents=True, exist_ok=True)
-    out = OUT / name
-    out.write_bytes(canvas.png())
-    print(f"wrote {out.relative_to(HERE.parent.parent)} ({canvas.w}x{canvas.h})")
-
-
-def main():
-    # Portrait capsule: mark in the upper half, wordmark beneath.
-    c = Canvas(600, 900)
-    c.fill_gradient(BG_TOP, BG_BOT)
-    c.glow(300, 340, 260, COL_DEEP, 0.35)
-    c.mark(300, 340, 320)
-    c.word("punktfunk", 44, 300, 640)
-    save("grid.png", c)
-
-    # Wide capsule: mark left, wordmark right of it.
-    c = Canvas(920, 430)
-    c.fill_gradient(BG_TOP, BG_BOT)
-    c.glow(230, 215, 200, COL_DEEP, 0.35)
-    c.mark(230, 215, 240)
-    c.word("punktfunk", 40, 620, 220)
-    save("gridwide.png", c)
-
-    # Hero: ambient banner — the mark rides the right third; Steam overlays logo.png itself.
-    c = Canvas(1920, 620)
-    c.fill_gradient(BG_TOP, BG_BOT)
-    c.glow(1500, 310, 330, COL_DEEP, 0.4)
-    c.mark(1500, 310, 400)
-    save("hero.png", c)
-
-    # Logo (transparent): mark + wordmark side by side, overlaid on the hero by Steam.
-    c = Canvas(1120, 300)
-    c.mark(150, 150, 240)
-    c.word("punktfunk", 62, 660, 155)
-    save("logo.png", c)
-
-    # Icon: brand tile, rounded corners, mark only.
-    c = Canvas(256, 256)
-    c.fill_gradient(BG_TOP, BG_BOT)
-    c.glow(128, 128, 110, COL_DEEP, 0.3)
-    c.mark(128, 128, 190)
-    c.round_corners(36)
-    save("icon.png", c)
-
-
-if __name__ == "__main__":
-    main()

clients/decky/scripts/package.sh

@@ -26,8 +26,12 @@ cp main.py plugin.json package.json LICENSE "$DEST/"
 # The stream-launch wrapper (target of the Steam shortcut) — must stay executable.
 cp bin/punktfunkrun.sh "$DEST/bin/punktfunkrun.sh"
 chmod 0755 "$DEST/bin/punktfunkrun.sh"
-# Steam-shortcut artwork (grid/hero/logo/icon — scripts/gen-steam-art.py, committed).
+# Steam-shortcut artwork (grid/gridwide/hero/logo/icon — committed under assets/).
 cp assets/*.png "$DEST/assets/"
+# The Steam Input controller layout (native touchscreen `ts_n` + gamepad passthrough) the
+# backend installs (apply_controller_config → controller_base/templates + the shortcut config).
+mkdir -p "$DEST/controller_config"
+cp controller_config/punktfunk.vdf "$DEST/controller_config/punktfunk.vdf"
 [ -f decky.pyi ]  && cp decky.pyi  "$DEST/"
 [ -f README.md ]  && cp README.md  "$DEST/"
 

clients/decky/src/backend.ts

@@ -150,6 +150,14 @@ export const setPins = callable<[pins: PinnedGame[]], { ok: boolean; error?: str
 );
 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
+// shortcut(s) at it, so the Deck touchscreen reaches the client as native touch with no manual
+// controller setup. Best-effort + idempotent; keyed by the shared shortcut NAME (both shortcuts
+// use the same name → the same lowercase configset key), so one call covers both.
+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",

clients/decky/src/index.tsx

@@ -31,6 +31,7 @@ import {
 import { streamPin } from "./library";
 import { PunktfunkRoute, ROUTE } from "./page";
 import { PairModal } from "./pair";
+import { ensureGamepadUiShortcut } from "./steam";
 
 // ----------------------------------------------------------------------------------------
 // QAM panel — quick status + entry into the full page + one-tap stream for known hosts
@@ -196,6 +197,10 @@ const QamPanel: FC = () => {
 
 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.
+  void ensureGamepadUiShortcut();
   return {
     // `name` is the plugin's INTERNAL id — it must stay in sync with plugin.json (the loader
     // keys plugins by it), so it stays lowercase; user-facing strings say "Punktfunk".

clients/decky/src/steam.ts

@@ -1,14 +1,23 @@
-// Launch the stream as a Steam game so gamescope focuses + fullscreens it.
+// Launch Punktfunk as Steam games so gamescope focuses + fullscreens them.
 //
 // THE LAUNCH MECHANISM (verified against MoonDeck): gamescope only gives focus/fullscreen to
 // the window tree Steam launched via `reaper` (it detects the "current app" by AppID — see
-// gamescope#484). So we cannot launch the flatpak from the plugin backend; we register ONE
-// hidden non-Steam shortcut whose exe is `/bin/sh` running our wrapper script
-// (bin/punktfunkrun.sh), pass the per-session host as the shortcut's Steam launch options,
-// and start it with RunGame. The wrapper then execs
-// `flatpak run io.unom.Punktfunk --connect <host>` as a reaper descendant.
+// gamescope#484). So we cannot launch the flatpak from the plugin backend; we register non-Steam
+// shortcuts whose exe is `/bin/sh` running our wrapper script (bin/punktfunkrun.sh), and start
+// them with RunGame. The wrapper then execs the flatpak client as a reaper descendant.
+//
+// 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.
+//   • 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 { runnerInfo, shortcutArt, wake } from "./backend";
+import { applyControllerConfig, runnerInfo, shortcutArt, wake } 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
@@ -46,32 +55,33 @@ declare const collectionStore:
   | { SetAppsAsHidden?: (appIds: number[], hidden: boolean) => void }
   | undefined;
 
-// The shortcut used to be hidden ("implementation detail"); it is user-visible now — it
-// carries proper artwork and living in the library is how users relaunch their last host.
-// Existing installs still have theirs hidden, so unhide is applied every ensure (idempotent).
-function unhideShortcut(appId: number): void {
+/** Set a shortcut's library visibility (best-effort, deferred — the overview registers a moment
+ *  after AddShortcut). Hides the stateful stream shortcut; keeps the gamepad-UI one visible. */
+function setShortcutHidden(appId: number, hidden: boolean): void {
   const attempt = () => {
     try {
-      collectionStore?.SetAppsAsHidden?.([appId], false);
+      collectionStore?.SetAppsAsHidden?.([appId], hidden);
     } catch {
       /* overview not registered yet, or the API changed — cosmetic, ignore */
     }
   };
   attempt(); // succeeds immediately for an already-registered (reused) shortcut
   setTimeout(attempt, 2500); // fresh shortcut: retry once its app overview lands
+};
+
+// Bump when the shipped artwork changes so existing shortcuts re-apply it once (per appId).
+const ART_VERSION = 2;
+function artKey(appId: number): string {
+  return `punktfunk:shortcutArt:${appId}`;
 }
 
-// Bump when the shipped artwork changes so existing shortcuts re-apply it once.
-const ART_VERSION = 1;
-const ART_KEY = "punktfunk:shortcutArt";
-
 /**
- * Apply the plugin's grid/hero/logo/icon to the shortcut (idempotent, once per ART_VERSION).
- * Cosmetic and fully best-effort: any failure is swallowed and retried on the next launch.
+ * Apply the plugin's grid/hero/logo/icon to a shortcut (idempotent, once per ART_VERSION per
+ * appId). Cosmetic and fully best-effort: any failure is swallowed and retried on the next call.
  */
 async function applyArtwork(appId: number): Promise<void> {
   try {
-    if (localStorage.getItem(ART_KEY) === `${appId}:${ART_VERSION}`) {
+    if (localStorage.getItem(artKey(appId)) === `${ART_VERSION}`) {
       return;
     }
     const art = await shortcutArt();
@@ -89,13 +99,14 @@ async function applyArtwork(appId: number): Promise<void> {
     if (art.icon_path) {
       SteamClient.Apps.SetShortcutIcon(appId, art.icon_path);
     }
-    localStorage.setItem(ART_KEY, `${appId}:${ART_VERSION}`);
+    localStorage.setItem(artKey(appId), `${ART_VERSION}`);
   } catch (e) {
     console.warn("punktfunk: shortcut artwork not applied", e);
   }
 }
 
-// The shortcut name is user-visible (Steam overlay + library while streaming) — brand-case it.
+// The shortcut name is user-visible (Steam overlay + library) — brand-case it. BOTH shortcuts
+// share it so Steam keys them to the SAME controller config (configset key = lowercase name).
 const SHORTCUT_NAME = "Punktfunk";
 
 // The shortcut's exe is /bin/sh, NOT the script itself: Decky extracts plugin zips without
@@ -111,76 +122,128 @@ function gameIdFromAppId(appId: number): string {
   return ((BigInt(appId) << 32n) | 0x02000000n).toString();
 }
 
-// Persist our shortcut appId across reloads so we reuse ONE shortcut instead of churning the
-// library (the appId is stable for the life of the shortcut).
-const STORAGE_KEY = "punktfunk:shortcutAppId";
+// Persist each shortcut's appId across reloads so we reuse ONE per role instead of churning the
+// library (an appId is stable for the life of the shortcut). The STREAM key is the historical
+// one, so existing single-shortcut installs migrate into the (now hidden) stream role, and the
+// visible gamepad-UI shortcut is created alongside.
+const STORAGE_KEY_STREAM = "punktfunk:shortcutAppId";
+const STORAGE_KEY_UI = "punktfunk:uiAppId";
 
-function rememberAppId(appId: number) {
+function remember(key: string, appId: number) {
   try {
-    localStorage.setItem(STORAGE_KEY, String(appId));
+    localStorage.setItem(key, String(appId));
   } catch {
     /* ignore */
   }
 }
-function recallAppId(): number | null {
+function recall(key: string): number | null {
   try {
-    const v = localStorage.getItem(STORAGE_KEY);
+    const v = localStorage.getItem(key);
     return v ? Number(v) : null;
   } catch {
     return null;
   }
 }
 
+// Install the native-touch controller config once per plugin session (idempotent file writes in
+// the root backend). Keyed by the shared shortcut NAME, so this single call covers both
+// shortcuts. Gated in localStorage so we don't rewrite Steam's config dir on every launch; bump
+// CONFIG_VERSION to force a reinstall after the shipped .vdf changes.
+const CONFIG_KEY = "punktfunk:controllerConfig";
+const CONFIG_VERSION = 1;
+async function ensureControllerConfig(): Promise<void> {
+  try {
+    if (localStorage.getItem(CONFIG_KEY) === `${CONFIG_VERSION}`) {
+      return;
+    }
+    const r = await applyControllerConfig(SHORTCUT_NAME);
+    if (r?.ok) {
+      localStorage.setItem(CONFIG_KEY, `${CONFIG_VERSION}`);
+    } else {
+      console.warn("punktfunk: controller config not fully applied", r);
+    }
+  } catch (e) {
+    console.warn("punktfunk: controller config not applied", e);
+  }
+}
+
 /**
- * Ensure exactly one "Punktfunk" shortcut exists (exe = /bin/sh; the wrapper script is
- * appended per-launch via the launch options), branded and visible in the library, and
- * return its appId + the current runner path. Reuses the remembered shortcut, re-pointing
- * it each time — the plugin dir can change across reinstalls, pre-0.4 shortcuts pointed at
- * the script directly, and pre-0.7 shortcuts were hidden and artless.
+ * Ensure the STREAM shortcut (hidden, stateful) — the per-session launcher whose launch options
+ * are rewritten per stream. Branded, artworked, native-touch config applied, and HIDDEN (it is
+ * an implementation detail; the visible entry is the gamepad-UI shortcut). Returns its appId +
+ * the current runner path. Reuses/repoints the remembered shortcut (the plugin dir can change
+ * across reinstalls, and pre-two-shortcut installs had this one visible).
  */
-async function ensureShortcut(): Promise<{ appId: number; runner: string }> {
+async function ensureStreamShortcut(): Promise<{ appId: number; runner: string }> {
   const info = await runnerInfo();
   if (!info.exists) {
     throw new Error(`launch wrapper missing at ${info.runner}`);
   }
   const startDir = info.runner.replace(/\/[^/]*$/, ""); // the plugin's bin/ dir
+  void ensureControllerConfig(); // fire-and-forget — never blocks the launch
 
-  const remembered = recallAppId();
+  const remembered = recall(STORAGE_KEY_STREAM);
   if (remembered != null) {
-    // Re-point + rename the existing shortcut (cheap + idempotent — migrates old installs).
     SteamClient.Apps.SetShortcutExe(remembered, SHELL);
     SteamClient.Apps.SetShortcutStartDir(remembered, startDir);
     SteamClient.Apps.SetShortcutName(remembered, SHORTCUT_NAME);
-    unhideShortcut(remembered); // pre-0.7 installs hid it
-    void applyArtwork(remembered); // fire-and-forget — cosmetic, never blocks the launch
+    setShortcutHidden(remembered, true); // migrate pre-two-shortcut installs (were visible)
+    void applyArtwork(remembered);
     return { appId: remembered, runner: info.runner };
   }
 
   const appId = await SteamClient.Apps.AddShortcut(SHORTCUT_NAME, SHELL, startDir, "");
   SteamClient.Apps.SetShortcutName(appId, SHORTCUT_NAME);
-  unhideShortcut(appId);
-  void applyArtwork(appId); // fire-and-forget — cosmetic, never blocks the launch
-  rememberAppId(appId);
+  setShortcutHidden(appId, true);
+  void applyArtwork(appId);
+  remember(STORAGE_KEY_STREAM, appId);
   return { appId, runner: info.runner };
 }
 
 /**
- * Best-effort: turn Steam Input OFF for our shortcut so SDL's HIDAPI Steam Deck driver can open the
- * Deck's controls (paddles · trackpads · gyro) directly. There is no confirmed-stable SteamClient
- * API for this, so it is feature-detected and MUST never block or throw into the launch — the manual
- * toggle (game page → ⚙ → Controller Settings → Steam Input Off, surfaced in the plugin Settings) is
- * the documented source of truth. No-op when the optional API is absent.
+ * Ensure the GAMEPAD-UI shortcut (visible, stateless) — the library-facing "Punktfunk" entry
+ * that opens the client's console home (bare `--browse`: host picker + pairing + settings).
+ * Fixed launch options (no per-session state), branded, artworked, native-touch config applied,
+ * kept VISIBLE. Idempotent — call on plugin mount so the library entry always exists and stays
+ * repointed to the current plugin dir. Best-effort: returns null on any failure.
  */
-function disableSteamInputForShortcut(appId: number): void {
+export async function ensureGamepadUiShortcut(): Promise<number | null> {
   try {
-    const input = (
-      SteamClient as unknown as {
-        Input?: { SetSteamInputEnabledForApp?: (appId: number, enabled: boolean) => void };
-      }
-    ).Input;
-    input?.SetSteamInputEnabledForApp?.(appId, false);
-  } catch {
-    /* a controller tweak must never break the launch */
+    const info = await runnerInfo();
+    if (!info.exists) {
+      return 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.
+    const launchOpts = `PF_BROWSE=1 %command% "${info.runner}"`;
+
+    let appId = recall(STORAGE_KEY_UI);
+    if (appId != null) {
+      SteamClient.Apps.SetShortcutExe(appId, SHELL);
+      SteamClient.Apps.SetShortcutStartDir(appId, startDir);
+      SteamClient.Apps.SetShortcutName(appId, SHORTCUT_NAME);
+    } else {
+      appId = await SteamClient.Apps.AddShortcut(SHORTCUT_NAME, SHELL, startDir, "");
+      SteamClient.Apps.SetShortcutName(appId, SHORTCUT_NAME);
+      remember(STORAGE_KEY_UI, appId);
+    }
+    SteamClient.Apps.SetAppLaunchOptions(appId, launchOpts);
+    setShortcutHidden(appId, false); // the visible library entry
+    void applyArtwork(appId);
+    return appId;
+  } catch (e) {
+    console.warn("punktfunk: gamepad-UI shortcut not ensured", e);
+    return null;
+  }
+}
+
+/** Launch the stateless gamepad-UI shortcut (console home) from the plugin, e.g. a QAM button. */
+export async function launchGamepadUi(): Promise<void> {
+  const appId = await ensureGamepadUiShortcut();
+  if (appId != null) {
+    SteamClient.Apps.RunGame(gameIdFromAppId(appId), "", -1, 100);
   }
 }
 
@@ -210,9 +273,9 @@ export function isSafeLaunchId(id: string): boolean {
 
 /**
  * Launch a stream to `host:port` fullscreen in Gaming Mode (optionally straight into a
- * library title, or into the gamepad library launcher). Encodes the target into the
- * shortcut's launch options (so one generic shortcut serves every host and every pinned
- * game), then RunGame.
+ * 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.
  */
 export async function launchStream(
   host: string,
@@ -224,10 +287,7 @@ export async function launchStream(
   // 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 } = await ensureShortcut();
-  // Best-effort so the Deck's rich controls reach the client; no-op if the API is absent (the user
-  // disables Steam Input manually — see the Settings instruction).
-  disableSteamInputForShortcut(appId);
+  const { appId, runner } = await ensureStreamShortcut();
   const target = port && port !== 9777 ? `${host}:${port}` : host;
   const env = [`PF_HOST=${target}`];
   if (opts.browse) {
@@ -251,7 +311,7 @@ export async function launchStream(
 
 /** Stop the running stream shortcut (best-effort; the in-stream chord/back also works). */
 export function stopStream(): void {
-  const appId = recallAppId();
+  const appId = recall(STORAGE_KEY_STREAM);
   if (appId != null) {
     SteamClient.Apps.TerminateApp(gameIdFromAppId(appId), false);
   }

clients/linux/src/ui_settings.rs

@@ -29,7 +29,11 @@ const COMPOSITORS: &[&str] = &["auto", "kwin", "wlroots", "mutter", "gamescope"]
 /// Codec setting values (persisted) paired with their display labels below.
 const CODECS: &[&str] = &["auto", "hevc", "h264", "av1"];
 const CODEC_LABELS: &[&str] = &["Automatic", "HEVC (H.265)", "H.264 (AVC)", "AV1"];
-const DECODERS: &[&str] = &["auto", "vaapi", "software"];
+const DECODERS: &[&str] = &["auto", "vulkan", "vaapi", "software"];
+/// Touch-input model values (persisted) paired with their display labels below — the
+/// cross-client set (Android/Apple). Only meaningful on a touchscreen (Deck/tablet).
+const TOUCH_MODES: &[&str] = &["trackpad", "pointer", "touch"];
+const TOUCH_MODE_LABELS: &[&str] = &["Trackpad", "Direct pointer", "Touch passthrough"];
 
 /// punktfunk's own license (MIT OR Apache-2.0), shown on the About dialog's Legal page.
 const APP_LICENSE: &str = concat!(
@@ -264,21 +268,23 @@ pub fn show(
     let page = adw::PreferencesPage::new();
 
     let stream = adw::PreferencesGroup::builder().title("Stream").build();
-    let res_names: Vec<String> = RESOLUTIONS
-        .iter()
-        .map(|&(w, h)| {
-            if w == 0 {
-                "Native display".to_string()
-            } else {
-                format!("{w} × {h}")
-            }
-        })
+    // The D1 tri-state: Native, Match window (a virtual index 1, stored as the
+    // `match_window` flag), then the explicit sizes.
+    let res_names: Vec<String> = std::iter::once("Native display".to_string())
+        .chain(std::iter::once("Match window".to_string()))
+        .chain(
+            RESOLUTIONS
+                .iter()
+                .skip(1)
+                .map(|&(w, h)| format!("{w} × {h}")),
+        )
         .collect();
     let res_row = ChoiceRow::new(
         &dialog,
         inline,
         "Resolution",
-        "The host creates a virtual output at exactly this size",
+        "The host creates a virtual output at exactly this size — Match window follows \
+         the stream window, including mid-stream resizes",
         &res_names.iter().map(String::as_str).collect::<Vec<_>>(),
     );
     let hz_names: Vec<String> = REFRESH
@@ -318,10 +324,12 @@ pub fn show(
         &dialog,
         inline,
         "Video decoder",
-        "Automatic tries VAAPI hardware decode, then software",
+        "Automatic picks the best hardware decode for this GPU (VAAPI on AMD/Intel, \
+         Vulkan Video on NVIDIA), falling back to software",
         &[
-            "Automatic (VAAPI → software)",
-            "Hardware (VAAPI)",
+            "Automatic (hardware → software)",
+            "Vulkan Video",
+            "VAAPI",
             "Software",
         ],
     );
@@ -345,13 +353,14 @@ pub fn show(
     stream.add(stats_row.widget());
 
     let input = adw::PreferencesGroup::builder().title("Input").build();
-    // Which physical controller forwards as pad 0: automatic = the most recently connected
-    // real pad (Steam's virtual pad skipped). A pin is persisted by stable key
-    // (`Settings::forward_pad`), so it survives restarts — and disconnects: an offline
-    // pinned pad keeps its entry here instead of silently snapping back to Automatic.
+    // Controller forwarding: Automatic forwards EVERY real controller, each as its own pad
+    // (Steam's virtual pad skipped); pinning one restricts the session to that single
+    // controller (single-player). The pin is persisted by stable key (`Settings::forward_pad`),
+    // so it survives restarts — and disconnects: an offline pinned pad keeps its entry here
+    // instead of silently snapping back to Automatic.
     let pads = gamepads.pads();
     let saved_pin = settings.borrow().forward_pad.clone();
-    let mut pad_names = vec!["Automatic (most recent)".to_string()];
+    let mut pad_names = vec!["Automatic (all controllers)".to_string()];
     let mut pad_keys: Vec<String> = Vec::new();
     for p in &pads {
         let kind = p.kind_label();
@@ -377,7 +386,7 @@ pub fn show(
         if pads.is_empty() {
             "No controllers detected"
         } else {
-            "Exactly one controller is forwarded to the host"
+            "All controllers are forwarded, each as its own player; pick one to force single-player"
         },
         &pad_names.iter().map(String::as_str).collect::<Vec<_>>(),
     );
@@ -417,12 +426,21 @@ pub fn show(
             "Steam Deck",
         ],
     );
+    let touch_row = ChoiceRow::new(
+        &dialog,
+        inline,
+        "Touch input",
+        "How the touchscreen drives the host — Trackpad nudges a cursor (tap to click); \
+         Direct pointer jumps to your finger; Touch passthrough sends real touches",
+        TOUCH_MODE_LABELS,
+    );
     let inhibit_row = adw::SwitchRow::builder()
         .title("Capture system shortcuts")
         .subtitle("Forward Alt+Tab, Super, … to the host while input is captured")
         .build();
     input.add(forward_row.widget());
     input.add(pad_row.widget());
+    input.add(touch_row.widget());
     input.add(&inhibit_row);
 
     let audio = adw::PreferencesGroup::builder().title("Audio").build();
@@ -470,16 +488,26 @@ pub fn show(
     // Seed from the current settings.
     {
         let s = settings.borrow();
-        let res_i = RESOLUTIONS
-            .iter()
-            .position(|&(w, h)| w == s.width && h == s.height)
-            .unwrap_or(0);
+        let res_i = if s.match_window {
+            1
+        } else {
+            RESOLUTIONS
+                .iter()
+                .position(|&(w, h)| w == s.width && h == s.height)
+                .map(|i| if i == 0 { 0 } else { i + 1 })
+                .unwrap_or(0)
+        };
         res_row.set_selected(res_i as u32);
         let hz_i = REFRESH.iter().position(|&r| r == s.refresh_hz).unwrap_or(0);
         hz_row.set_selected(hz_i as u32);
         bitrate_row.set_value(f64::from(s.bitrate_kbps) / 1000.0);
         let pad_i = GAMEPADS.iter().position(|&g| g == s.gamepad).unwrap_or(0);
         pad_row.set_selected(pad_i as u32);
+        let touch_i = TOUCH_MODES
+            .iter()
+            .position(|&t| t == s.touch_mode)
+            .unwrap_or(0);
+        touch_row.set_selected(touch_i as u32);
         let comp_i = COMPOSITORS
             .iter()
             .position(|&c| c == s.compositor)
@@ -508,11 +536,19 @@ pub fn show(
     dialog.add(&page);
     dialog.connect_closed(move |_| {
         let mut s = settings.borrow_mut();
-        let (w, h) = RESOLUTIONS[(res_row.selected() as usize).min(RESOLUTIONS.len() - 1)];
-        (s.width, s.height) = (w, h);
+        // Index 1 is the virtual "Match window" option; 0 = Native, 2.. = explicit.
+        let res_i = (res_row.selected() as usize).min(RESOLUTIONS.len());
+        s.match_window = res_i == 1;
+        (s.width, s.height) = if res_i <= 1 {
+            (0, 0)
+        } else {
+            RESOLUTIONS[res_i - 1]
+        };
         s.refresh_hz = REFRESH[(hz_row.selected() as usize).min(REFRESH.len() - 1)];
         s.bitrate_kbps = (bitrate_row.value() * 1000.0) as u32;
         s.gamepad = GAMEPADS[(pad_row.selected() as usize).min(GAMEPADS.len() - 1)].to_string();
+        s.touch_mode =
+            TOUCH_MODES[(touch_row.selected() as usize).min(TOUCH_MODES.len() - 1)].to_string();
         s.forward_pad = chosen_pin.borrow().clone();
         s.compositor = COMPOSITORS[(compositor_row.selected() as usize).min(COMPOSITORS.len() - 1)]
             .to_string();

clients/probe/src/main.rs

@@ -39,6 +39,7 @@
 //! exits without connecting.
 //!
 //! Usage: `punktfunk-probe [--connect HOST:PORT] [--mode WxHxFPS] [--remode WxHxFPS:SECS]
+//!         [--rebitrate KBPS:SECS]
 //!         [--out FILE] [--bitrate KBPS] [--codec auto|h264|hevc|av1] [--audio-channels 2|6|8]
 //!         [--launch APP] [--name NAME] [--speed-test KBPS:MS]
 //!         [--input-test | --mic-test [--mic-burst] | --touch-test | --rich-input-test]
@@ -51,8 +52,8 @@ use punktfunk_core::config::Role;
 use punktfunk_core::input::{InputEvent, InputKind};
 use punktfunk_core::packet::FLAG_PROBE;
 use punktfunk_core::quic::{
-    endpoint, io, window_loss_ppm, Hello, LossReport, ProbeRequest, ProbeResult, Reconfigure,
-    Reconfigured, RequestKeyframe, Start, Welcome,
+    endpoint, io, window_loss_ppm, BitrateChanged, Hello, LossReport, ProbeRequest, ProbeResult,
+    Reconfigure, Reconfigured, RequestKeyframe, SetBitrate, Start, Welcome,
 };
 use punktfunk_core::transport::UdpTransport;
 use punktfunk_core::{CompositorPref, Mode, PunktfunkError, Session};
@@ -84,6 +85,11 @@ struct Args {
     pin: Option<[u8; 32]>,
     /// `--remode WxHxFPS:SECS` — request this mode SECS seconds into the stream.
     remode: Option<(Mode, u32)>,
+    /// `--rebitrate KBPS:SECS` — send a mid-stream [`SetBitrate`] (the adaptive-bitrate control
+    /// message) SECS seconds into the stream: the headless validator for the host's in-place
+    /// encoder rate retarget (Phase 3.2) / rebuild fallback. Wiggles the cursor around the switch
+    /// so a damage-driven idle desktop actually publishes frames through it.
+    rebitrate: Option<(u32, u32)>,
     /// `--pair PIN` — run the pairing ceremony instead of a session.
     pair: Option<String>,
     /// `--name LABEL` — how the host labels this client when pairing.
@@ -201,6 +207,10 @@ fn parse_args() -> Args {
         let (m, secs) = s.split_once(':')?;
         Some((parse_mode(m)?, secs.parse().ok()?))
     });
+    let rebitrate = get("--rebitrate").and_then(|s| {
+        let (kbps, secs) = s.split_once(':')?;
+        Some((kbps.parse().ok()?, secs.parse().ok()?))
+    });
     // A present-but-malformed --pin must abort, not silently downgrade to trust-on-first-use
     // (the user asked for verification; fail closed).
     let pin = match get("--pin") {
@@ -252,6 +262,7 @@ fn parse_args() -> Args {
         seconds: get("--seconds").and_then(|s| s.parse().ok()),
         pin,
         remode,
+        rebitrate,
         pair: get("--pair").map(String::from),
         name: get("--name").unwrap_or("punktfunk-probe").to_string(),
         compositor,
@@ -470,7 +481,10 @@ async fn session(args: Args) -> Result<()> {
             video_caps: {
                 // Always ask for per-AU host timings (0xCF) — this is a measurement tool, and the
                 // host/network split is exactly what it exists to report. Old hosts ignore the bit.
-                let mut caps = punktfunk_core::quic::VIDEO_CAP_HOST_TIMING;
+                // PROBE_SEQ: the shared-core reassembler windows probe-space frames, so the probe
+                // qualifies for `--speed-test` bursts; without the bit the host declines them.
+                let mut caps = punktfunk_core::quic::VIDEO_CAP_HOST_TIMING
+                    | punktfunk_core::quic::VIDEO_CAP_PROBE_SEQ;
                 if std::env::var_os("PUNKTFUNK_CLIENT_10BIT").is_some() {
                     caps |= punktfunk_core::quic::VIDEO_CAP_10BIT;
                 }
@@ -626,6 +640,64 @@ async fn session(args: Args) -> Result<()> {
                 other => tracing::error!(?other, "bad Reconfigured"),
             }
         });
+    } else if let Some((new_kbps, after_secs)) = args.rebitrate {
+        // Mid-stream adaptive-bitrate test: after a delay, send the SetBitrate the Automatic
+        // controller would and await the host's BitrateChanged ack. Host-side this exercises the
+        // in-place `reconfigure_bitrate` (no IDR) or the rebuild fallback — the host log says
+        // which. The cursor wiggle keeps a damage-driven idle desktop publishing frames through
+        // the whole window: the encode loop only drains bitrate requests between frames, and the
+        // post-switch AUs are what prove the stream carried on.
+        let mut rs = send;
+        let mut rr = recv;
+        let conn2 = conn.clone();
+        tokio::spawn(async move {
+            let wiggle = |i: u32| InputEvent {
+                kind: InputKind::MouseMove,
+                _pad: [0; 3],
+                code: 0,
+                x: if i % 2 == 0 { 2 } else { -2 },
+                y: 0,
+                flags: 0,
+            };
+            let end =
+                std::time::Instant::now() + std::time::Duration::from_secs(after_secs as u64 + 6);
+            let switch_at =
+                std::time::Instant::now() + std::time::Duration::from_secs(after_secs as u64);
+            let mut sent = false;
+            let mut i = 0u32;
+            while std::time::Instant::now() < end {
+                let _ = conn2.send_datagram(wiggle(i).encode().to_vec().into());
+                i += 1;
+                tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+                if !sent && std::time::Instant::now() >= switch_at {
+                    sent = true;
+                    tracing::info!(new_kbps, "requesting mid-stream bitrate change");
+                    if io::write_msg(
+                        &mut rs,
+                        &SetBitrate {
+                            bitrate_kbps: new_kbps,
+                        }
+                        .encode(),
+                    )
+                    .await
+                    .is_err()
+                    {
+                        tracing::error!("SetBitrate write failed");
+                        return;
+                    }
+                    match io::read_msg(&mut rr)
+                        .await
+                        .map(|b| BitrateChanged::decode(&b))
+                    {
+                        Ok(Ok(ack)) => tracing::info!(
+                            applied_kbps = ack.bitrate_kbps,
+                            "BITRATE CHANGE acked by host"
+                        ),
+                        other => tracing::error!(?other, "bad BitrateChanged"),
+                    }
+                }
+            }
+        });
     } else if let Some((target_kbps, duration_ms)) = args.speed_test {
         // Bandwidth probe: after the stream warms up, ask the host to burst FLAG_PROBE filler; measure
         // delivered WIRE packets (session-stat delta) vs. what the host reports putting on the wire.
@@ -639,11 +711,28 @@ async fn session(args: Args) -> Result<()> {
         } else {
             0
         };
+        let conn2 = conn.clone();
         tokio::spawn(async move {
             use std::sync::atomic::Ordering::Relaxed;
-            tokio::time::sleep(std::time::Duration::from_secs(2)).await; // let the stream warm up
-                                                                         // Baseline the packet-level counters right before the burst (video is paused during it,
-                                                                         // so the delta is pure probe traffic plus a sliver of resumed video in the settle).
+            // Warm up the stream — and generate desktop activity while doing so. Damage-driven
+            // capture paths (Windows IDD-push, a static headless desktop anywhere) publish NO
+            // frame until something composes, and the host's pipeline build waits for a first
+            // frame — so an idle virtual display would time the whole speed test out. A ±2 px
+            // cursor wiggle over the wire is injected host-side into the right session/desktop.
+            for i in 0..20u32 {
+                let mv = InputEvent {
+                    kind: InputKind::MouseMove,
+                    _pad: [0; 3],
+                    code: 0,
+                    x: if i % 2 == 0 { 2 } else { -2 },
+                    y: 0,
+                    flags: 0,
+                };
+                let _ = conn2.send_datagram(mv.encode().to_vec().into());
+                tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+            }
+            // Baseline the packet-level counters right before the burst (video is paused during it,
+            // so the delta is pure probe traffic plus a sliver of resumed video in the settle).
             let base_pkts = rxp.load(Relaxed);
             let base_bytes = rxb.load(Relaxed);
             tracing::info!(target_kbps, duration_ms, "requesting speed-test probe");
@@ -668,6 +757,15 @@ async fn session(args: Args) -> Result<()> {
                     return;
                 }
             };
+            // A declined burst comes back all-zero (duration_ms = 0) — e.g. the host predates
+            // speed tests. Say so instead of dividing a settle-window sliver by 1 ms.
+            if res.duration_ms == 0 {
+                tracing::error!(
+                    "SPEED TEST declined by host (all-zero ProbeResult) — host too old, or it \
+                     rejected the request; check the host log"
+                );
+                return;
+            }
             // The reliable result can beat the last UDP shards — let the tail arrive before reading.
             // Keep this short: video resumes the instant the burst ends, so a long settle counts
             // resumed-video packets against the probe (inflating recv past the host's wire count).
@@ -1150,7 +1248,8 @@ async fn session(args: Args) -> Result<()> {
         let cap_secs = args.seconds.unwrap_or(120);
         // Adaptive-FEC loss window: publish a fresh estimate every 750 ms for the LossReport task.
         let mut last_loss_report = std::time::Instant::now();
-        let (mut last_recovered, mut last_received, mut last_dropped) = (0u64, 0u64, 0u64);
+        let (mut last_recovered, mut last_late, mut last_received, mut last_dropped) =
+            (0u64, 0u64, 0u64, 0u64);
         loop {
             // Mirror packet-level receive counters for the speed-test reporter (reads their delta),
             // and publish a windowed loss estimate for the adaptive-FEC LossReport task.
@@ -1164,6 +1263,7 @@ async fn session(args: Args) -> Result<()> {
                     lp_dt.store(
                         window_loss_ppm(
                             s.fec_recovered_shards.wrapping_sub(last_recovered),
+                            s.fec_late_shards.wrapping_sub(last_late),
                             s.packets_received.wrapping_sub(last_received),
                             s.frames_dropped.wrapping_sub(last_dropped),
                         ),
@@ -1171,6 +1271,7 @@ async fn session(args: Args) -> Result<()> {
                     );
                     last_loss_report = std::time::Instant::now();
                     last_recovered = s.fec_recovered_shards;
+                    last_late = s.fec_late_shards;
                     last_received = s.packets_received;
                     last_dropped = s.frames_dropped;
                 }
@@ -1242,6 +1343,23 @@ async fn session(args: Args) -> Result<()> {
             s.flush().ok();
         }
 
+        // PUNKTFUNK_PERF: cumulative receive-path stage split for the whole run — where the
+        // receive core's time went (kernel drain vs AES-GCM open vs reassembly+FEC). This is
+        // the measurement tool's view of the client-pump wall the 2026-07-14 sweeps pinned.
+        if let Some(p) = session.take_pump_perf() {
+            let per_pkt = |ns: u64| ns.checked_div(p.packets).unwrap_or(0);
+            tracing::info!(
+                recv_ms = p.recv_ns / 1_000_000,
+                decrypt_ms = p.decrypt_ns / 1_000_000,
+                reasm_ms = p.reasm_ns / 1_000_000,
+                packets = p.packets,
+                pkts_per_batch = p.packets.checked_div(p.batches.max(1)).unwrap_or(0),
+                decrypt_ns_pkt = per_pkt(p.decrypt_ns),
+                reasm_ns_pkt = per_pkt(p.reasm_ns),
+                "receive stage split (whole run, PUNKTFUNK_PERF)"
+            );
+        }
+
         latencies_us.sort_unstable();
         let pct = |p: f64| -> u64 {
             if latencies_us.is_empty() {

clients/session/src/console.rs

@@ -29,6 +29,15 @@ use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex};
 use std::time::{Duration, Instant};
 
+/// A request-access connect awaiting the operator's approval on the host: stamped by the
+/// launch handler and consumed by `on_connected`, which persists the host as paired.
+struct PendingApproval {
+    name: String,
+    addr: String,
+    port: u16,
+    fp_hex: String,
+}
+
 pub fn run(target: Option<&str>) -> u8 {
     let identity = match trust::load_or_create_identity() {
         Ok(i) => i,
@@ -128,6 +137,14 @@ pub fn run(target: Option<&str>) -> u8 {
     // `{"ready":true}` and restores on exit) — plain CLI/gamescope runs stay silent.
     let json_status = arg_flag("--json-status");
     let settings_at_start = trust::Settings::load();
+
+    // Request-access hand-off: the launch handler stamps this when it starts a delegated-approval
+    // connect; `on_connected` reads it once the host lets us in and persists the host as PAIRED,
+    // so the next connect is an ordinary one. `None` for every normal launch, so `on_connected`
+    // then only touches last-used.
+    let pending_approval: Arc<Mutex<Option<PendingApproval>>> = Arc::new(Mutex::new(None));
+    let pending_cb = pending_approval.clone();
+
     let opts = pf_presenter::SessionOpts {
         window_title: window_label.map_or_else(
             || "Punktfunk".to_string(),
@@ -140,11 +157,24 @@ pub fn run(target: Option<&str>) -> u8 {
             trust::StatsVerbosity::Off if arg_flag("--stats") => trust::StatsVerbosity::Normal,
             v => v,
         },
+        touch_mode: settings_at_start.touch_mode(),
         json_status,
-        on_connected: Some(Box::new(|fingerprint: [u8; 32]| {
-            trust::touch_last_used(&trust::hex(&fingerprint));
+        on_connected: Some(Box::new(move |fingerprint: [u8; 32]| {
+            let fp_hex = trust::hex(&fingerprint);
+            trust::touch_last_used(&fp_hex);
+            // A request-access connect just succeeded → the operator approved us. Save the
+            // host as paired (it was unsaved/discovered), keyed to the fingerprint we pinned.
+            if let Some(p) = pending_cb.lock().unwrap().take() {
+                if p.fp_hex == fp_hex {
+                    trust::persist_host(&p.name, &p.addr, p.port, &fp_hex, true);
+                }
+            }
         })),
         overlay: Some(Box::new(overlay)),
+        window_size: crate::session_main::window_size(&settings_at_start),
+        // Latched at console start (like the stats tier above): toggling Match window in
+        // the console's settings screen applies from the next console launch.
+        match_window: crate::session_main::match_window(&settings_at_start),
     };
 
     let result =
@@ -156,21 +186,23 @@ pub fn run(target: Option<&str>) -> u8 {
                     fp_hex,
                     launch,
                     title,
+                    request_access,
                 } => {
                     let Some(pin) = trust::parse_hex32(&fp_hex) else {
-                        // The console only offers Connect on paired rows; a pinless
-                        // launch is a logic slip, never a silent TOFU.
+                        // Connect (and request-access) pin the host's advertised fingerprint;
+                        // a pinless launch is a logic slip, never a silent TOFU.
                         tracing::warn!(%addr, "launch without a stored pin — refusing");
                         return ActionOutcome::Handled;
                     };
-                    tracing::info!(%addr, %title, launch = launch.as_deref().unwrap_or("desktop"),
+                    tracing::info!(%addr, %title, request_access,
+                        launch = launch.as_deref().unwrap_or("desktop"),
                         "launching from the console");
                     // Settings re-load per launch: the console's own settings screen
                     // may have changed them since the last stream.
                     let settings = trust::Settings::load();
-                    ActionOutcome::Start(Box::new(session_params(
+                    let mut params = session_params(
                         &settings,
-                        addr,
+                        addr.clone(),
                         port,
                         pin,
                         identity.clone(),
@@ -179,7 +211,20 @@ pub fn run(target: Option<&str>) -> u8 {
                         native,
                         force_software,
                         vulkan,
-                    )))
+                    );
+                    if request_access {
+                        // The host PARKS the connect until the operator approves — outlast its
+                        // approval window (host `PENDING_APPROVAL_WAIT`), matching the desktop
+                        // shells' 185 s. On success `on_connected` persists the host as paired.
+                        params.connect_timeout = Duration::from_secs(185);
+                        *pending_approval.lock().unwrap() = Some(PendingApproval {
+                            name: title.clone(),
+                            addr,
+                            port,
+                            fp_hex: fp_hex.clone(),
+                        });
+                    }
+                    ActionOutcome::Start(Box::new(params))
                 }
                 OverlayAction::CancelConnect => ActionOutcome::Handled, // run-loop-side
                 OverlayAction::Quit => ActionOutcome::Quit,

clients/session/src/main.rs

@@ -164,6 +164,32 @@ mod session_main {
         }
     }
 
+    /// The window's starting size under Match-window: the persisted last size, so the
+    /// first connect's mode already matches the glass; `None` (policy off / never
+    /// stored) = the 1280×720 default.
+    pub(crate) fn window_size(settings: &trust::Settings) -> Option<(u32, u32)> {
+        (settings.match_window && settings.last_window_w > 0 && settings.last_window_h > 0)
+            .then_some((settings.last_window_w, settings.last_window_h))
+    }
+
+    /// The Match-window policy hook for the presenter loop
+    /// (design/midstream-resolution-resize.md D1/D2): `Some(persist)` turns the
+    /// debounced resize→`Reconfigure` machinery on; the callback stores each resize-end's
+    /// logical window size (load-modify-save, like the console settings screen) so the
+    /// next launch opens at it.
+    pub(crate) fn match_window(settings: &trust::Settings) -> Option<Box<dyn FnMut(u32, u32)>> {
+        settings.match_window.then(|| {
+            Box::new(|w: u32, h: u32| {
+                let mut s = trust::Settings::load();
+                if (s.last_window_w, s.last_window_h) != (w, h) {
+                    s.last_window_w = w;
+                    s.last_window_h = h;
+                    s.save();
+                }
+            }) as Box<dyn FnMut(u32, u32)>
+        })
+    }
+
     /// One JSON status line on stdout (the shell parses these; strings hand-escaped via
     /// the minimal rules a reason string can need). `pub(crate)`: browse mode emits its
     /// failure through the same contract when spawned with `--json-status`.
@@ -332,6 +358,7 @@ mod session_main {
                 trust::StatsVerbosity::Off if arg_flag("--stats") => trust::StatsVerbosity::Normal,
                 v => v,
             },
+            touch_mode: settings.touch_mode(),
             json_status: true,
             on_connected: Some(Box::new(|fingerprint: [u8; 32]| {
                 // This host's card carries the accent bar in the desktop client now.
@@ -343,6 +370,8 @@ mod session_main {
             overlay: Some(Box::new(pf_console_ui::SkiaOverlay::new())),
             #[cfg(not(feature = "ui"))]
             overlay: None,
+            window_size: window_size(&settings),
+            match_window: match_window(&settings),
         };
 
         let outcome =

clients/windows/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "punktfunk-client-windows"
-description = "Native Windows punktfunk/1 client — WinUI 3 (windows-reactor) shell, D3D11/SwapChainPanel present, FFmpeg decode, WASAPI audio, SDL3 gamepads"
+description = "Native Windows punktfunk/1 client — WinUI 3 (windows-reactor) shell, SDL3 gamepads; streaming runs in the spawned punktfunk-session binary"
 version.workspace = true
 edition.workspace = true
 rust-version.workspace = true
@@ -57,26 +57,19 @@ windows = { git = "https://github.com/microsoft/windows-rs", rev = "a4f7b2cb7c63
     "Win32_UI_WindowsAndMessaging",
 ] }
 
-# Video decode (same FFmpeg pin as the host/Linux client) — software HEVC on the GPU-less dev
-# box; D3D11VA hardware decode is a follow-up for the real-GPU box.
+# FFmpeg — used only to enumerate which codecs this client can decode (probe::decodable_codecs),
+# advertised to the host on the speed-test connect. Same pin as the host/Linux client. (Real
+# decode + present live in the spawned punktfunk-session binary.)
 ffmpeg-next = "8"
-opus = "0.3"
-
-# Audio render + mic capture (the WASAPI analogue of the Linux client's PipeWire backend).
-wasapi = "0.23"
-
-# Gamepads: capture + feedback (full DualSense fidelity needs hidapi). SDL3 is cross-platform;
-# built from source via the bundled CMake on Windows (no system SDL3).
-sdl3 = { version = "0.18", features = ["build-from-source", "hidapi"] }
 
+# Gamepad enumeration + pin persistence for Settings runs on pf-client-core's shared SDL service
+# (see the `gamepad` field in app/); the spawned punktfunk-session does the actual forwarding. SDL3
+# itself (built from source via the bundled CMake on Windows) is pulled transitively by
+# pf-client-core with the same `build-from-source,hidapi` features, so it is not a direct dep here.
 mdns-sd = "0.20"
 async-channel = "2"
-# The decoded-frame channel (session pump → render thread): crossbeam because the render loop
-# blocks with `recv_timeout`, which async-channel has no sync analogue of.
-crossbeam-channel = "0.5"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
-anyhow = "1"
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 

clients/windows/src/app/connect.rs

@@ -6,10 +6,7 @@
 use super::style::*;
 use super::{AppCtx, Screen, Svc, Target};
 use crate::discovery::DiscoveredHost;
-use crate::session::{self, SessionEvent, SessionParams, Stats};
-use crate::trust::{self, KnownHost, KnownHosts, Settings};
-use crate::video::DecoderPref;
-use punktfunk_core::config::{CompositorPref, GamepadPref, Mode};
+use crate::trust::{self, KnownHost, KnownHosts};
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::Arc;
 use std::time::Duration;
@@ -117,82 +114,6 @@ pub(crate) fn initiate_launch(
     );
 }
 
-/// The mode to request: explicit settings, with `0` fields resolved to the native size/refresh
-/// of the display our window is on (mirrors the Linux/Swift clients' native-display default).
-pub(crate) fn resolve_mode(s: &Settings) -> Mode {
-    let mut mode = Mode {
-        width: s.width,
-        height: s.height,
-        refresh_hz: s.refresh_hz,
-    };
-    if mode.width == 0 || mode.refresh_hz == 0 {
-        if let Some((w, h, hz)) = current_display_mode() {
-            if mode.width == 0 {
-                (mode.width, mode.height) = (w, h);
-            }
-            if mode.refresh_hz == 0 {
-                mode.refresh_hz = hz;
-            }
-        }
-    }
-    // No display info (headless session, RDP oddities) — a sane floor.
-    if mode.width == 0 {
-        (mode.width, mode.height) = (1920, 1080);
-    }
-    if mode.refresh_hz == 0 {
-        mode.refresh_hz = 60;
-    }
-    mode
-}
-
-/// The current mode (physical pixels + refresh) of the display our window occupies:
-/// `MonitorFromWindow` on the foreground window — ours, the user just clicked in it — then
-/// `EnumDisplaySettingsW(ENUM_CURRENT_SETTINGS)` on that monitor's device. Defaults to the
-/// primary display when we're not foreground (e.g. a scripted connect).
-fn current_display_mode() -> Option<(u32, u32, u32)> {
-    use windows::core::PCWSTR;
-    use windows::Win32::Graphics::Gdi::{
-        EnumDisplaySettingsW, GetMonitorInfoW, MonitorFromWindow, DEVMODEW, ENUM_CURRENT_SETTINGS,
-        MONITORINFO, MONITORINFOEXW,
-    };
-    use windows::Win32::UI::WindowsAndMessaging::GetForegroundWindow;
-    unsafe {
-        let monitor = MonitorFromWindow(
-            GetForegroundWindow(),
-            windows::Win32::Graphics::Gdi::MONITOR_DEFAULTTOPRIMARY,
-        );
-        let mut info = MONITORINFOEXW::default();
-        info.monitorInfo.cbSize = std::mem::size_of::<MONITORINFOEXW>() as u32;
-        if !GetMonitorInfoW(
-            monitor,
-            &mut info as *mut MONITORINFOEXW as *mut MONITORINFO,
-        )
-        .as_bool()
-        {
-            return None;
-        }
-        let mut dm = DEVMODEW {
-            dmSize: std::mem::size_of::<DEVMODEW>() as u16,
-            ..Default::default()
-        };
-        if !EnumDisplaySettingsW(
-            PCWSTR(info.szDevice.as_ptr()),
-            ENUM_CURRENT_SETTINGS,
-            &mut dm,
-        )
-        .as_bool()
-        {
-            return None;
-        }
-        // dmDisplayFrequency of 0/1 means "hardware default" — unusable as a mode request.
-        (dm.dmPelsWidth > 0 && dm.dmDisplayFrequency > 1).then_some((
-            dm.dmPelsWidth,
-            dm.dmPelsHeight,
-            dm.dmDisplayFrequency,
-        ))
-    }
-}
-
 /// Tunables that differ between the normal connect and the no-PIN "request access" flow.
 /// `Default` is the normal connect: short handshake budget, persist *unpaired* on TOFU, and the
 /// plain "Connecting" screen.
@@ -220,9 +141,7 @@ pub(crate) struct ConnectOpts {
     /// so it can't loop.
     wake_on_fail: bool,
     /// A library title id (`steam:570`, …) the host launches during the connect handshake —
-    /// the library page's tap-to-play. Spawn mode passes it as `--launch`; the legacy
-    /// in-process path has no launch plumbing (it predates the library and is slated for
-    /// deletion).
+    /// the library page's tap-to-play, passed to the spawned session child as `--launch`.
     launch: Option<String>,
 }
 
@@ -265,128 +184,11 @@ fn connect_with(
     opts: ConnectOpts,
 ) {
     // Session-always: every stream runs in the spawned punktfunk-session Vulkan binary.
-    // The in-process D3D11VA path below stays reachable via the "Streaming engine"
-    // setting / PUNKTFUNK_BUILTIN_STREAM=1 as the A/B baseline until its deletion.
-    if !super::use_builtin_stream(ctx) {
-        return connect_spawn(ctx, target, pin, set_screen, set_status, opts);
-    }
-    let s = ctx.settings.lock().unwrap().clone();
-    let gamepad_pref = match GamepadPref::from_name(&s.gamepad) {
-        Some(GamepadPref::Auto) | None => ctx.gamepad.auto_pref(),
-        Some(explicit) => explicit,
-    };
-    let handle = session::start(SessionParams {
-        host: target.addr.clone(),
-        port: target.port,
-        mode: resolve_mode(&s),
-        compositor: CompositorPref::from_name(&s.compositor).unwrap_or(CompositorPref::Auto),
-        gamepad: gamepad_pref,
-        bitrate_kbps: s.bitrate_kbps,
-        audio_channels: s.audio_channels,
-        mic_enabled: s.mic_enabled,
-        hdr_enabled: s.hdr_enabled,
-        decoder: DecoderPref::from_name(&s.decoder),
-        preferred_codec: s.preferred_codec(),
-        pin,
-        identity: ctx.identity.clone(),
-        connect_timeout: opts.connect_timeout,
-    });
-    set_status.call(String::new());
-    set_screen.call(if opts.awaiting_approval {
-        Screen::RequestAccess
-    } else {
-        Screen::Connecting
-    });
-
-    let tofu = pin.is_none();
-    let persist_paired = opts.persist_paired;
-    let cancel = opts.cancel;
-    let wake_on_fail = opts.wake_on_fail;
-    let ctx = ctx.clone();
-    let (shared, gamepad) = (ctx.shared.clone(), ctx.gamepad.clone());
-    let (ss, st) = (set_screen.clone(), set_status.clone());
-    let target = target.clone();
-    std::thread::spawn(move || loop {
-        let event = match handle.events.recv_blocking() {
-            Ok(e) => e,
-            Err(_) => {
-                gamepad.detach();
-                ss.call(Screen::Hosts);
-                break;
-            }
-        };
-        // A cancelled request-access connect that resolved late (the host approved or the park
-        // timed out after the user walked away): tear down silently. Cancel already returned the
-        // UI to the host list; dropping `event` (and with it any connector) closes the connection
-        // without popping a stream or a stray error over the screen a new session may own.
-        if cancel.as_ref().is_some_and(|c| c.load(Ordering::SeqCst)) {
-            break;
-        }
-        match event {
-            SessionEvent::Connected {
-                connector,
-                fingerprint,
-                ..
-            } => {
-                if persist_paired || tofu {
-                    // Request-access: the operator approved this device, so record the host as a
-                    // trusted PAIRED host — future connects are then silent (rule 1), exactly like
-                    // after a PIN ceremony. A plain TOFU connect persists it *unpaired* (pinned).
-                    let mut k = KnownHosts::load();
-                    k.upsert(KnownHost {
-                        name: target.name.clone(),
-                        addr: target.addr.clone(),
-                        port: target.port,
-                        fp_hex: trust::hex(&fingerprint),
-                        paired: persist_paired,
-                        last_used: None,
-                        mac: target.mac.clone(),
-                    });
-                    let _ = k.save();
-                }
-                trust::touch_last_used(&trust::hex(&fingerprint));
-                gamepad.attach(connector.clone());
-                *shared.stats.lock().unwrap() = Stats::default(); // clear any prior session's numbers
-                *shared.handoff.lock().unwrap() =
-                    Some((connector, handle.frames.clone(), handle.stop.clone()));
-                ss.call(Screen::Stream);
-            }
-            SessionEvent::Failed {
-                msg,
-                trust_rejected,
-            } => {
-                st.call(msg);
-                gamepad.detach();
-                if trust_rejected {
-                    // Pinned-fingerprint mismatch / pairing required → re-pair via the PIN screen.
-                    // The host ANSWERED, so this never takes the wake fallback.
-                    *shared.target.lock().unwrap() = target.clone();
-                    ss.call(Screen::Pair);
-                } else if wake_on_fail {
-                    // The dial-first attempt to a non-advertising host failed — it may genuinely
-                    // be asleep. NOW wake and wait (its resolved redial uses default opts, so a
-                    // second failure lands on the host list, not back here).
-                    wake_and_connect(&ctx, target.clone(), &ss, &st);
-                } else {
-                    ss.call(Screen::Hosts);
-                }
-                break;
-            }
-            SessionEvent::Ended(err) => {
-                // `None` = the user ended the session themselves (the disconnect shortcut) —
-                // return to the host list silently; an error banner would read as a failure.
-                st.call(err.unwrap_or_default());
-                gamepad.detach();
-                ss.call(Screen::Hosts);
-                break;
-            }
-            SessionEvent::Stats(s) => *shared.stats.lock().unwrap() = s,
-        }
-    });
+    connect_spawn(ctx, target, pin, set_screen, set_status, opts)
 }
 
 /// Spawn-mode connect: run the stream in the punktfunk-session binary and translate its
-/// stdout contract into the same navigation the in-process event loop drove. The child
+/// stdout contract into the app's connect-flow navigation. The child
 /// NEVER connects unpinned — a stored/ceremony pin, else the host's advertised
 /// fingerprint (TOFU: persisted once the child reports ready, which proves the host
 /// really holds that identity, mirroring the GTK shell); no fingerprint at all routes to
@@ -723,9 +525,7 @@ pub(crate) fn request_access_page(
             .on_click(move || {
                 // Return the UI immediately; trip the flag this request's event loop
                 // captured so it tears down silently when the connect resolves (see
-                // ConnectOpts::cancel). Spawn mode: killing the parked child IS the abort
-                // (builtin mode's in-process connect is blocking with none — it just
-                // resolves/times out later).
+                // ConnectOpts::cancel). Killing the parked session child IS the abort.
                 if let Some(c) = ctx.shared.cancel.lock().unwrap().as_ref() {
                     c.store(true, Ordering::SeqCst);
                 }

clients/windows/src/app/help.rs

@@ -1,8 +1,7 @@
 //! The Shortcuts screen: a short note on the in-stream capture model plus a reference of the
 //! keyboard shortcuts — reached from the Shortcuts button on the host list. The Windows
 //! counterpart of the GTK client's Keyboard Shortcuts window; the bindings themselves live in
-//! the session window (and [`crate::input`] for the legacy builtin path), so both clients
-//! document the same set.
+//! the session window, so both clients document the same set.
 
 use super::style::*;
 use super::Screen;
@@ -10,8 +9,7 @@ use windows_reactor::*;
 
 /// The in-stream keyboard shortcuts, in the GTK Shortcuts window's order: the chord, then what it
 /// does. Read-only — the keyboard bindings live in the session window (`pf-presenter`'s run
-/// loop; the legacy builtin path's in [`crate::input`]), the controller chord in its gamepad
-/// service.
+/// loop), the controller chord in its gamepad service.
 const STREAM_SHORTCUTS: &[(&str, &str)] = &[
     ("F11 / Alt+Enter", "Toggle fullscreen"),
     (

clients/windows/src/app/hosts.rs

@@ -189,14 +189,21 @@ fn status_row(online: Option<bool>, badge: &str, kind: Pill) -> Element {
 
 /// The in-tile rename editor (ContentDialog can't hold a text field): name box + save/cancel.
 /// No tap-to-connect while editing — a click into the box would bubble `Tapped` to the region.
+/// `initial` seeds the text box's displayed value and is CONSTANT for the life of the edit — the
+/// field is uncontrolled, its live value kept in `live` (read at Save). Driving a *controlled* box
+/// from an always-deferred `AsyncSetState` round-trip fights the caret on fast typing and can drop
+/// the last char if Save is clicked before the write lands; an uncontrolled box + a ref sidesteps
+/// both (and skips a full-page re-render per keystroke). See the seed block in `hosts_page`.
 fn rename_editor(
-    draft: &str,
+    initial: &str,
     fp: String,
+    live: HookRef<String>,
     set_rename: AsyncSetState<Option<(String, String)>>,
 ) -> Element {
     let commit = {
-        let (fp, draft, sr) = (fp.clone(), draft.to_string(), set_rename.clone());
+        let (fp, live, sr) = (fp.clone(), live.clone(), set_rename.clone());
         move || {
+            let draft = live.borrow();
             let name = draft.trim();
             if !name.is_empty() {
                 let mut known = KnownHosts::load();
@@ -209,12 +216,12 @@ fn rename_editor(
         }
     };
     let on_changed = {
-        let sr = set_rename.clone();
-        move |s: String| sr.call(Some((fp.clone(), s)))
+        let live = live.clone();
+        move |s: String| live.set(s)
     };
     card(
         vstack((
-            text_box(draft)
+            text_box(initial)
                 .placeholder_text("Host name")
                 .on_text_changed(on_changed),
             hstack((
@@ -240,6 +247,14 @@ pub(crate) fn hosts_page(props: &HostsProps, cx: &mut RenderCx) -> Element {
     let set_screen = &props.svc.set_screen;
     let set_status = &props.svc.set_status;
     let (manual, set_manual) = cx.use_state(String::new());
+    // The Add-host field's live value, read by Connect at click time. This page's `use_state` is
+    // unreliable as the click's source of truth: while the modal is open the page usually has no
+    // reason to re-render (you open it precisely because the host ISN'T being discovered, so no
+    // discovery tick fires), and the top-down reconcile skips this unchanged-props subtree — so a
+    // sync `set_manual` write never re-renders the Connect button to re-capture the address, and it
+    // would connect to the empty mount-time value. Mirror every keystroke into this stable ref (the
+    // pair-screen PIN pattern). `manual` still drives the text box's displayed value.
+    let manual_live = cx.use_ref(String::new());
     // "Add host" modal open state lives in ROOT (see `HostsProps`).
     let show_add = props.show_add;
     let set_show_add = &props.set_show_add;
@@ -249,6 +264,18 @@ pub(crate) fn hosts_page(props: &HostsProps, cx: &mut RenderCx) -> Element {
     let rename = props.rename.clone();
     let set_forget = &props.set_forget;
     let set_rename = &props.set_rename;
+    // The live rename draft, read at Save time (see `rename_editor`). Root `rename` carries only the
+    // INITIAL name, so it no longer round-trips per keystroke. Seed the draft each time the rename
+    // TARGET changes (start, cancel, or a switch to another host).
+    let rename_draft = cx.use_ref(String::new());
+    let rename_seed = cx.use_ref(Option::<String>::None);
+    {
+        let active = rename.as_ref().map(|(fp, _)| fp.clone());
+        if *rename_seed.borrow() != active {
+            rename_draft.set(rename.as_ref().map(|(_, n)| n.clone()).unwrap_or_default());
+            rename_seed.set(active);
+        }
+    }
     let hover = Hover {
         current: props.hover.clone(),
         set: props.set_hover.clone(),
@@ -393,8 +420,13 @@ pub(crate) fn hosts_page(props: &HostsProps, cx: &mut RenderCx) -> Element {
         for k in &known.hosts {
             // Rust 2021 (no let-chains): match the "this tile is being renamed" case explicitly.
             if matches!(&rename, Some((fp, _)) if fp == &k.fp_hex) {
-                let (fp, draft) = rename.clone().unwrap();
-                tiles.push(rename_editor(&draft, fp, set_rename.clone()));
+                let (fp, initial) = rename.clone().unwrap();
+                tiles.push(rename_editor(
+                    &initial,
+                    fp,
+                    rename_draft.clone(),
+                    set_rename.clone(),
+                ));
                 continue;
             }
             let target = Target {
@@ -595,14 +627,15 @@ pub(crate) fn hosts_page(props: &HostsProps, cx: &mut RenderCx) -> Element {
     // field). The scrim border fills the cell and is hit-testable, so it blocks the page behind;
     // it closes only via Cancel/Connect (a scrim tap would bubble `Tapped` up from the card too).
     let connect_manual = {
-        let (ctx2, ss, st, text, sa) = (
+        let (ctx2, ss, st, live, sa) = (
             ctx.clone(),
             set_screen.clone(),
             set_status.clone(),
-            manual.clone(),
+            manual_live.clone(),
             set_show_add.clone(),
         );
         move || {
+            let text = live.borrow();
             let text = text.trim();
             if text.is_empty() {
                 return;
@@ -640,7 +673,13 @@ pub(crate) fn hosts_page(props: &HostsProps, cx: &mut RenderCx) -> Element {
             text_box(manual)
                 .header("Address")
                 .placeholder_text("192.168.1.20  or  my-pc.local")
-                .on_text_changed(move |s| set_manual.call(s))
+                .on_text_changed({
+                    let live = manual_live.clone();
+                    move |s: String| {
+                        live.set(s.clone());
+                        set_manual.call(s);
+                    }
+                })
                 .margin(edges(0.0, 6.0, 0.0, 0.0)),
             hstack((
                 button("Connect")

clients/windows/src/app/licenses.rs

@@ -23,7 +23,7 @@ pub(crate) fn licenses_page(set_screen: &AsyncSetState<Screen>) -> Element {
 
     let app_card = card(
         vstack((
-            text_block("punktfunk").font_size(15.0).semibold(),
+            text_block("Punktfunk").font_size(15.0).semibold(),
             text_block("Licensed under MIT OR Apache-2.0, at your option.")
                 .font_size(12.0)
                 .wrap()

clients/windows/src/app/mod.rs

@@ -1,8 +1,8 @@
 //! The WinUI 3 (windows-reactor) application shell.
 //!
 //! Declarative React-like model: this root component routes on a `Screen` value held in
-//! `use_async_state` so background threads (discovery, the session pump) can drive navigation.
-//! Each screen lives in its own submodule:
+//! `use_async_state` so background threads (discovery, the spawned session's stdout reader) can
+//! drive navigation. Each screen lives in its own submodule:
 //!
 //! * [`hosts`] — saved/discovered/manual host list, plus per-host forget + speed test
 //! * [`connect`] — the trust gate and session lifecycle glue (connect / request-access flows)
@@ -10,7 +10,7 @@
 //! * [`speed`] — the per-host network speed test (probe burst over the real data plane)
 //! * [`settings`] — persisted preferences · [`licenses`] — the license notices screen ·
 //!   [`help`] — the in-stream keyboard-shortcuts reference (reached from the host list)
-//! * [`stream`] — the live stream: `SwapChainPanel` + D3D11 presenter + HUD overlay
+//! * [`stream`] — the stream status card (the stream itself runs in the spawned session window)
 //! * [`style`] — the shared look (cards, pills, monograms), following the windows-reactor
 //!   gallery: Mica backdrop, a centred max-width column, theme brushes (`ThemeRef`)
 //!
@@ -19,9 +19,6 @@
 //! marks it dirty and re-renders it; an `AsyncSetState` written from a background thread does
 //! NOT (the child is pruned when its props are unchanged) — so everything thread-driven
 //! (discovery, HUD stats, speed-test results) is held as *root* state and passed down as props.
-//! The present + decoded-frame handoff crosses to the UI thread through a `Mutex` side-channel
-//! and thread-locals (the windows-reactor SwapChainPanel sample's pattern), since the per-frame
-//! present must not go through state/rerender.
 
 mod connect;
 mod help;
@@ -35,17 +32,15 @@ mod stream;
 mod style;
 
 use crate::discovery::{self, DiscoveredHost};
-use crate::gamepad::GamepadService;
-use crate::session::Stats;
 use crate::trust::{KnownHosts, Settings};
 use hosts::HostsProps;
+use pf_client_core::gamepad::GamepadService;
 use punktfunk_core::client::NativeClient;
 use speed::{SpeedProps, SpeedState};
 use std::collections::HashMap;
 use std::sync::atomic::AtomicBool;
 use std::sync::{Arc, Mutex};
 use std::time::Duration;
-use stream::StreamProps;
 use windows_reactor::*;
 
 #[derive(Clone, PartialEq)]
@@ -88,7 +83,7 @@ pub(crate) struct Target {
 }
 
 /// Stable app services handed to the page components as props. Each routed screen that uses
-/// hooks (`hosts_page`/`pair_page`/`stream_page`/`speed_page`) is mounted as its own
+/// hooks (`hosts_page`/`pair_page`/`speed_page`/`library_page`) is mounted as its own
 /// `component(...)`, so its hooks live in an isolated slot list — calling them on the shared
 /// parent `cx` would change the hook order whenever the screen changes (reactor's
 /// Rules-of-Hooks guard aborts).
@@ -115,18 +110,12 @@ impl PartialEq for Svc {
     }
 }
 
-/// Cross-thread handoff from the session pump (off-thread) to the stream page (UI thread):
-/// the connector (input sends), the decoded-frame channel (render thread), and the session's
-/// stop flag (the disconnect shortcut trips it).
+/// Cross-thread shell state driven off the UI thread: the current target, the live spawned
+/// session child (Disconnect/Cancel kill it) and its latest stats line, plus the connect-flow
+/// cancel flag and the discovery/library/speed-test generation guards.
 #[derive(Default)]
 pub(crate) struct Shared {
-    #[allow(clippy::type_complexity)]
-    pub(crate) handoff:
-        Mutex<Option<(Arc<NativeClient>, crate::session::FrameRx, Arc<AtomicBool>)>>,
     pub(crate) target: Mutex<Target>,
-    /// Latest stream stats, written by the session's event loop and mirrored into reactor state
-    /// by the HUD poll thread to drive the overlay.
-    pub(crate) stats: Mutex<Stats>,
     /// The live session child (spawn mode) — the status page's Disconnect and the
     /// request-access Cancel kill it. A FRESH handle is installed per spawn.
     pub(crate) session: Mutex<crate::spawn::SessionChild>,
@@ -157,14 +146,6 @@ pub struct AppCtx {
     pub(crate) shared: Arc<Shared>,
 }
 
-/// The legacy in-process streaming path (SwapChainPanel + D3D11VA) instead of the
-/// spawned punktfunk-session window: the `PUNKTFUNK_BUILTIN_STREAM=1` env override — a
-/// developer A/B knob only (the former Settings "Streaming engine" pick is gone), removed
-/// with the legacy path once the Vulkan session is fully validated.
-pub(crate) fn use_builtin_stream(_ctx: &AppCtx) -> bool {
-    std::env::var_os("PUNKTFUNK_BUILTIN_STREAM").is_some_and(|v| v == "1")
-}
-
 pub fn run(identity: (String, String), gamepad: GamepadService) -> windows_reactor::Result<()> {
     let ctx = Arc::new(AppCtx {
         identity,
@@ -302,10 +283,9 @@ fn root(cx: &mut RenderCx, ctx: &Arc<AppCtx>) -> Element {
         }
     });
 
-    // HUD sample: the session event loop writes `shared.stats` and the input hooks track capture
-    // state; this poll thread mirrors both into root state so the stream page gets them as a
-    // *prop* (thread-driven state must be root state — see the module docs). The compare in
-    // `AsyncSetState::call` makes the idle case free.
+    // HUD sample: the spawned session child's latest `stats:` line, mirrored into root state so
+    // the stream status page gets it as a *prop* (thread-driven state must be root state — see the
+    // module docs). The compare in `AsyncSetState::call` makes the idle case free.
     cx.use_effect((), {
         let shared = ctx.shared.clone();
         let set_hud = set_hud.clone();
@@ -315,10 +295,6 @@ fn root(cx: &mut RenderCx, ctx: &Arc<AppCtx>) -> Element {
                 .spawn(move || loop {
                     std::thread::sleep(std::time::Duration::from_millis(400));
                     set_hud.call(stream::HudSample {
-                        stats: *shared.stats.lock().unwrap(),
-                        captured: crate::input::is_captured(),
-                        visible: crate::input::hud_visible(),
-                        present: crate::render::present_stats(),
                         stats_line: shared.stats_line.lock().unwrap().clone(),
                     });
                 })
@@ -525,16 +501,13 @@ fn root(cx: &mut RenderCx, ctx: &Arc<AppCtx>) -> Element {
                 state: library,
             },
         ),
-        // Spawn mode (the default): the stream runs in the punktfunk-session child's own
-        // window; this screen is a status page (no hooks — inline is sound). The legacy
-        // in-process SwapChainPanel page stays behind the "Streaming engine" setting /
-        // PUNKTFUNK_BUILTIN_STREAM=1.
-        Screen::Stream if !use_builtin_stream(ctx) => stream::session_page(ctx, &hud),
-        Screen::Stream => component(stream::stream_page, StreamProps { svc, hud }),
+        // The stream runs in the punktfunk-session child's own window; this screen is a
+        // status page (no hooks — inline is sound).
+        Screen::Stream => stream::session_page(ctx, &hud),
     };
 
-    // The Stream screen owns the SwapChainPanel + per-frame present; never wrap it in an animated
-    // opacity/offset layer. Everything else slides + fades in on navigation.
+    // The Stream screen is a plain status card (the session child owns the real stream window);
+    // it's shown without the navigation entrance tween. Everything else slides + fades in.
     if matches!(screen, Screen::Stream) {
         return body;
     }

clients/windows/src/app/pair.rs

@@ -14,21 +14,28 @@ pub(crate) fn pair_page(props: &Svc, cx: &mut RenderCx) -> Element {
     let set_screen = &props.set_screen;
     let set_status = &props.set_status;
     let (code, set_code) = cx.use_state(String::new());
+    // The PIN's live value, read directly by the click handler. This page's props (`Svc`) never
+    // change, and root wraps every screen in an animated `border` that compares equal once the
+    // entrance tween settles — so the top-down reconcile `can_skip_update`s this subtree and never
+    // re-renders the pair component off its *local* `use_state`. A button rebuilt only at mount
+    // would forever capture the empty mount-time PIN (pairing then fails as a "wrong PIN"). Mirror
+    // every keystroke into this stable ref instead, so the click reads exactly what was typed.
+    let live_pin = cx.use_ref(String::new());
     let target = ctx.shared.target.lock().unwrap().clone();
 
     let pair_btn = {
-        let (ctx2, ss, st, code2, target2) = (
+        let (ctx2, ss, st, live, target2) = (
             ctx.clone(),
             set_screen.clone(),
             set_status.clone(),
-            code.clone(),
+            live_pin.clone(),
             target.clone(),
         );
         button("Pair & Connect")
             .accent()
             .icon(Symbol::Accept)
             .on_click(move || {
-                let pin = code2.trim().to_string();
+                let pin = live.borrow().trim().to_string();
                 let (ctx3, ss, st, target3) =
                     (ctx2.clone(), ss.clone(), st.clone(), target2.clone());
                 std::thread::spawn(move || {
@@ -109,7 +116,16 @@ pub(crate) fn pair_page(props: &Svc, cx: &mut RenderCx) -> Element {
         text_box(code)
             .placeholder_text("PIN")
             .font_size(28.0)
-            .on_text_changed(move |s| set_code.call(s)),
+            .on_text_changed({
+                let live = live_pin.clone();
+                move |s: String| {
+                    // Record the live value for the click handler (the source of truth for the
+                    // PIN), and mirror it into `code` so the field stays correct if anything ever
+                    // does re-render this page (theme/DPI change).
+                    live.set(s.clone());
+                    set_code.call(s);
+                }
+            }),
         hstack((pair_btn, cancel_btn)).spacing(8.0),
         text_block(
             "Don\u{2019}t have a PIN? Request access instead and approve this device on the host \

clients/windows/src/app/settings.rs

@@ -55,6 +55,13 @@ const STATS_TIERS: &[(StatsVerbosity, &str)] = &[
     (StatsVerbosity::Normal, "Normal"),
     (StatsVerbosity::Detailed, "Detailed"),
 ];
+/// Touch-input presets: `(stored value, display label)` — how a touchscreen's fingers drive
+/// the host. The cross-client set (Android/Apple); only meaningful on a touchscreen device.
+const TOUCH_MODES: &[(&str, &str)] = &[
+    ("trackpad", "Trackpad"),
+    ("pointer", "Direct pointer"),
+    ("touch", "Touch passthrough"),
+];
 /// Host compositor presets: `(stored value, display label)`. Advisory — the host falls back to
 /// auto-detect when the choice is unavailable. Only meaningful against a Linux host.
 const COMPOSITORS: &[(&str, &str)] = &[
@@ -136,29 +143,37 @@ pub(crate) fn settings_page(
     let s = ctx.settings.lock().unwrap().clone();
 
     // --- Display ---------------------------------------------------------------------------
+    // The D1 tri-state: Native, Match window (a virtual index 1, stored as the
+    // `match_window` flag), then the explicit sizes.
     let (res_names, res_i) = {
-        let names: Vec<String> = RESOLUTIONS
-            .iter()
-            .map(|&(w, h)| {
-                if w == 0 {
-                    "Native display".into()
-                } else {
-                    format!("{w} \u{00D7} {h}")
-                }
-            })
+        let names: Vec<String> = std::iter::once("Native display".to_string())
+            .chain(std::iter::once("Match window".to_string()))
+            .chain(
+                RESOLUTIONS
+                    .iter()
+                    .skip(1)
+                    .map(|&(w, h)| format!("{w} \u{00D7} {h}")),
+            )
             .collect();
-        let i = RESOLUTIONS
-            .iter()
-            .position(|&(w, h)| w == s.width && h == s.height)
-            .unwrap_or(0);
+        let i = if s.match_window {
+            1
+        } else {
+            RESOLUTIONS
+                .iter()
+                .position(|&(w, h)| w == s.width && h == s.height)
+                .map(|i| if i == 0 { 0 } else { i + 1 })
+                .unwrap_or(0)
+        };
         (names, i)
     };
     let res_combo = setting_combo(ctx, "Resolution", res_names, res_i, |s, i| {
-        (s.width, s.height) = RESOLUTIONS[i];
+        s.match_window = i == 1;
+        (s.width, s.height) = if i <= 1 { (0, 0) } else { RESOLUTIONS[i - 1] };
     })
     .tooltip(
         "The host creates a virtual display at exactly this size. \u{201C}Native display\u{201D} \
-         resolves to the monitor this window is on at connect.",
+         resolves to the monitor this window is on at connect; \u{201C}Match window\u{201D} \
+         follows the stream window, including mid-stream resizes.",
     );
     let (hz_names, hz_i) = {
         let names: Vec<String> = REFRESH
@@ -259,12 +274,13 @@ pub(crate) fn settings_page(
     );
 
     // --- Input -----------------------------------------------------------------------------
-    // Which physical controller forwards as pad 0: automatic = the most recently connected.
-    // Persisted by stable key (`Settings::forward_pad`, GTK parity) so the pin survives
-    // restarts AND reaches the spawned session binary, whose service applies the same key.
+    // Controller forwarding: Automatic forwards EVERY real controller, each as its own pad;
+    // pinning one restricts the session to that single controller (single-player). Persisted
+    // by stable key (`Settings::forward_pad`, GTK parity) so the pin survives restarts AND
+    // reaches the spawned session binary, whose service applies the same key.
     let pads = ctx.gamepad.pads();
     let (fwd_names, fwd_i) = {
-        let mut names = vec!["Automatic (most recent)".to_string()];
+        let mut names = vec!["Automatic (all controllers)".to_string()];
         names.extend(pads.iter().map(|p| {
             let kind = p.kind_label();
             if kind.is_empty() {
@@ -293,16 +309,16 @@ pub(crate) fn settings_page(
                 } else {
                     keys.get(sel - 1).cloned()
                 };
-                // Apply live (the in-process service, legacy builtin streams) and persist —
-                // the spawned session reads `forward_pad` at connect.
+                // Apply live to the gamepad service and persist — the spawned session
+                // reads `forward_pad` at connect.
                 svc.set_pinned(key.clone());
                 let mut s = ctx2.settings.lock().unwrap();
                 s.forward_pad = key.unwrap_or_default();
                 s.save();
             })
             .tooltip(
-                "Exactly one controller is forwarded to the host; \u{201C}Automatic\u{201D} \
-                 picks the most recently connected.",
+                "Every connected controller is forwarded, each as its own player. Pick one \
+                 to force single-player \u{2014} only it reaches the host.",
             )
     };
     let (pad_names, pad_i) = presets(GAMEPADS, |v| {
@@ -315,6 +331,14 @@ pub(crate) fn settings_page(
         "The virtual pad the host creates. \u{201C}Automatic\u{201D} matches your physical \
          controller.",
     );
+    let (touch_names, touch_i) = presets(TOUCH_MODES, |v| *v == s.touch_mode);
+    let touch_combo = setting_combo(ctx, "Touch input", touch_names, touch_i, |s, i| {
+        s.touch_mode = TOUCH_MODES[i].0.to_string();
+    })
+    .tooltip(
+        "How a touchscreen drives the host: Trackpad nudges a cursor (tap to click), Direct \
+         pointer jumps to your finger, Touch passthrough sends real touches.",
+    );
     let shortcuts_toggle = setting_toggle(
         ctx,
         "Capture system shortcuts (Alt+Tab, Win, \u{2026})",
@@ -361,6 +385,16 @@ pub(crate) fn settings_page(
         "Adds \u{201C}Browse library\u{2026}\u{201D} to paired hosts \u{2014} pick a game and it \
          launches in the stream. Mirrors the Apple client's toggle.",
     );
+    // App identity + version at the top of the About card (the WinUI Settings convention; the About
+    // screen previously showed no version at all). CARGO_PKG_VERSION is the workspace version, baked
+    // in at compile time.
+    let about_identity = vstack((
+        text_block("Punktfunk").font_size(20.0).semibold(),
+        text_block(concat!("Version ", env!("CARGO_PKG_VERSION")))
+            .font_size(12.0)
+            .foreground(ThemeRef::SecondaryText),
+    ))
+    .spacing(2.0);
 
     // The selected section's content — per-control guidance lives on hover tooltips, so the
     // card is just the controls.
@@ -386,6 +420,7 @@ pub(crate) fn settings_page(
             settings_card(vec![
                 forward_combo.into(),
                 pad_combo.into(),
+                touch_combo.into(),
                 shortcuts_toggle.into(),
             ]),
         ),
@@ -395,7 +430,11 @@ pub(crate) fn settings_page(
         ),
         "about" => (
             "About",
-            settings_card(vec![library_toggle.into(), licenses_button.into()]),
+            settings_card(vec![
+                about_identity.into(),
+                library_toggle.into(),
+                licenses_button.into(),
+            ]),
         ),
         _ => (
             "Display",

clients/windows/src/app/speed.rs

@@ -4,7 +4,7 @@
 
 use super::style::*;
 use super::{Screen, Svc};
-use crate::session::run_speed_probe;
+use crate::probe::run_speed_probe;
 use windows_reactor::*;
 
 /// Speed-test lifecycle. Held as ROOT state (the probe worker completes it via

clients/windows/src/app/stream.rs

@@ -1,163 +1,20 @@
-//! The stream page: a `SwapChainPanel` whose composition swapchain is created (and bound) once on
-//! the UI thread, then handed — presenter and all — to the dedicated render thread
-//! ([`crate::render`]), which presents decoded frames at stream cadence. The page itself only
-//! forwards panel size/DPI changes and draws the status-chip HUD overlay (mode · decode path ·
-//! HDR · fps/goodput · end-to-end latency + stage equation · capture hint).
+//! The stream status page: streams run in the spawned `punktfunk-session` child's own window,
+//! so the shell shows a status card in the app's card language — host header, the child's live
+//! `stats:` line as a chip row + stage lines, the in-window shortcuts, and a Disconnect.
 
 use super::style::{edges, uniform};
-use super::Svc;
-use crate::present::Presenter;
-use crate::render::{self, RenderThread};
-use crate::session::Stats;
-use punktfunk_core::client::NativeClient;
-use punktfunk_core::config::Mode;
-use std::cell::RefCell;
 use std::sync::Arc;
 use windows_reactor::*;
 
-/// One HUD refresh: the latest session stats, the input hooks' capture state, and the render
-/// thread's display-side window. Mirrored into root state by the poll thread (`pf-hud`) and
-/// passed down as a prop.
+/// One HUD refresh: the session child's latest formatted `stats:` line, mirrored into root state
+/// by the poll thread (`pf-hud`) and passed down as a prop.
 #[derive(Clone, Default, PartialEq)]
 pub(crate) struct HudSample {
-    pub(crate) stats: Stats,
-    pub(crate) captured: bool,
-    /// Whether the stats overlay should be shown — the Settings default at stream start, then
-    /// whatever Ctrl+Alt+Shift+S last set (see [`crate::input::hud_visible`]). Carried in the
-    /// sample so a live toggle changes the sample and re-renders the page (the stream page is a
-    /// child component — only a changed prop re-renders it).
-    pub(crate) visible: bool,
-    /// The render thread's glass-side window (presents/s, skips, end-to-end p50/p95, display
-    /// stage p50) — see [`crate::render::present_stats`].
-    pub(crate) present: crate::render::PresentStats,
-    /// Spawn mode: the session child's latest formatted `stats:` line, for the status
-    /// page. Empty in builtin mode / before the first window.
+    /// The session child's latest formatted `stats:` line, for the status page. Empty before the
+    /// child's first stats window.
     pub(crate) stats_line: String,
 }
 
-/// Props for the stream page: the services plus the live HUD sample that drives the overlay
-/// (compared by value, so each new sample re-renders the overlay).
-#[derive(Clone)]
-pub(crate) struct StreamProps {
-    pub(crate) svc: Svc,
-    pub(crate) hud: HudSample,
-}
-
-impl PartialEq for StreamProps {
-    fn eq(&self, other: &Self) -> bool {
-        self.svc == other.svc && self.hud == other.hud
-    }
-}
-
-thread_local! {
-    /// Frames + host clock offset, stashed by the mount effect for `on_mounted` (which fires
-    /// later, once the native panel exists).
-    static PENDING: RefCell<Option<(crate::session::FrameRx, std::sync::Arc<std::sync::atomic::AtomicI64>)>> = const { RefCell::new(None) };
-    /// The live render thread; stopped + joined by the unmount cleanup (before panel teardown).
-    static RENDER: RefCell<Option<RenderThread>> = const { RefCell::new(None) };
-}
-
-/// The app window's DPI (96 when the window can't be found — then DIPs == pixels). Reactor's
-/// `on_resize` reports DIPs and exposes no CompositionScale, so the window DPI is the scale.
-fn window_dpi() -> u32 {
-    use windows::Win32::UI::HiDpi::GetDpiForWindow;
-    use windows::Win32::UI::WindowsAndMessaging::FindWindowW;
-    unsafe {
-        FindWindowW(None, windows::core::w!("Punktfunk"))
-            .ok()
-            .map(|h| GetDpiForWindow(h))
-            .filter(|d| *d > 0)
-            .unwrap_or(96)
-    }
-}
-
-pub(crate) fn stream_page(props: &StreamProps, cx: &mut RenderCx) -> Element {
-    let ctx = &props.svc.ctx;
-    // Take the connector + frames handoff once on mount; keep the connector alive (and for input)
-    // in a use_ref, stash frames for `on_mounted`, install the input hooks. The cleanup stops the
-    // render thread FIRST (it must not present into a panel that's tearing down), then removes
-    // the input hooks.
-    let connector_ref = cx.use_ref::<Option<Arc<NativeClient>>>(None);
-    cx.use_effect_with_cleanup((), {
-        let shared = ctx.shared.clone();
-        let (inhibit, show_stats) = {
-            let s = ctx.settings.lock().unwrap();
-            (s.inhibit_shortcuts, s.show_stats)
-        };
-        let connector_ref = connector_ref.clone();
-        move || {
-            if let Some((connector, frames, stop)) = shared.handoff.lock().unwrap().take() {
-                let mode = connector.mode();
-                let clock_offset = connector.clock_offset_shared();
-                connector_ref.set(Some(connector.clone()));
-                PENDING.with(|c| *c.borrow_mut() = Some((frames, clock_offset)));
-                crate::input::install(connector, mode, inhibit, show_stats, stop);
-            }
-            Some(|| {
-                RENDER.with(|c| {
-                    if let Some(mut rt) = c.borrow_mut().take() {
-                        rt.stop_and_join();
-                    }
-                });
-                PENDING.with(|c| c.borrow_mut().take());
-                crate::input::uninstall();
-            })
-        }
-    });
-
-    let mode = connector_ref.borrow().as_ref().map(|c| c.mode());
-    let host = ctx.shared.target.lock().unwrap().name.clone();
-    let mut layers: Vec<Element> = vec![swap_chain_panel()
-        .on_mounted(|panel| {
-            // Placeholder size — the first `on_resize` (fired after the first layout pass)
-            // resizes to the panel's real pixel size.
-            let dpi = window_dpi();
-            match Presenter::new(1280, 720, dpi) {
-                Ok(p) => {
-                    if let Err(e) = panel.set_swap_chain(p.swap_chain()) {
-                        tracing::error!(error = %e, "set_swap_chain");
-                        return;
-                    }
-                    if let Some((frames, clock_offset)) = PENDING.with(|c| c.borrow_mut().take()) {
-                        let shared = render::RenderShared::new(1280, 720, dpi);
-                        RENDER.with(|cell| {
-                            *cell.borrow_mut() =
-                                Some(render::spawn(p, frames, shared, clock_offset));
-                        });
-                        tracing::info!(dpi, "stream presenter bound — render thread started");
-                    }
-                }
-                Err(e) => tracing::error!(error = %e, "create presenter"),
-            }
-        })
-        .on_resize(|w, h| {
-            // DIPs → physical pixels; the presenter maps back via SetMatrixTransform.
-            let dpi = window_dpi();
-            let px = |v: f64| (v * f64::from(dpi) / 96.0).round() as u32;
-            RENDER.with(|cell| {
-                if let Some(rt) = cell.borrow().as_ref() {
-                    rt.shared().set_dpi(dpi);
-                    rt.shared().set_size(px(w), px(h));
-                }
-            });
-        })
-        .into()];
-    // The overlay follows the LIVE visibility (Settings default, then Ctrl+Alt+Shift+S): the page
-    // re-renders on every HUD sample (~400 ms), so a toggle takes effect promptly mid-stream.
-    if props.hud.visible {
-        layers.push(hud_overlay(&props.hud, mode, &host));
-    }
-    // Flash the shortcut key set for the first few seconds of every session, regardless of the
-    // HUD setting — so "how do I get back out" is answered the moment the stream comes up (parity
-    // with the GTK client's stream-start hint). Uptime drives it, so it needs no timer/state: the
-    // HUD poll re-renders the page each second and the banner drops once the session passes the
-    // threshold.
-    if props.hud.stats.uptime_secs < START_HINT_SECS {
-        layers.push(start_hint());
-    }
-    grid(layers).into()
-}
-
 /// Spawn mode's Stream screen: the stream runs in the punktfunk-session child's own
 /// window, so the shell shows a status card in the app's card language — monogram +
 /// host header, the child's live `stats:` line as a chip row + stage lines, the
@@ -277,164 +134,3 @@ pub(crate) fn session_page(ctx: &Arc<super::AppCtx>, hud: &HudSample) -> Element
         .vertical_alignment(VerticalAlignment::Center)
         .into()
 }
-
-/// How long the stream-start shortcut banner stays up (seconds of session uptime).
-const START_HINT_SECS: u32 = 6;
-
-/// The stream-start shortcut banner: the full client key set on a translucent pill, bottom-centre,
-/// shown for [`START_HINT_SECS`] at the start of every session (see the call site). Independent of
-/// the stats overlay, so it appears even with the HUD turned off.
-fn start_hint() -> Element {
-    border(
-        text_block(
-            "Click the stream to capture \u{00B7} Ctrl+Alt+Shift+Q releases \u{00B7} \
-             Ctrl+Alt+Shift+D disconnects \u{00B7} Ctrl+Alt+Shift+S stats \u{00B7} F11 fullscreen",
-        )
-        .font_size(12.0)
-        .semibold()
-        .foreground(Color::rgb(235, 235, 235)),
-    )
-    .background(Color::rgb(0, 0, 0))
-    .corner_radius(10.0)
-    .padding(edges(14.0, 8.0, 14.0, 8.0))
-    .opacity(0.82)
-    .horizontal_alignment(HorizontalAlignment::Center)
-    .vertical_alignment(VerticalAlignment::Bottom)
-    .margin(edges(0.0, 0.0, 0.0, 28.0))
-    .into()
-}
-
-/// A small chip for the dark HUD: coloured text on a translucent dark fill.
-fn hud_chip(text: &str, color: Color) -> Border {
-    border(
-        text_block(text)
-            .font_size(11.0)
-            .semibold()
-            .foreground(color),
-    )
-    .background(Color::rgb(38, 38, 38))
-    .corner_radius(8.0)
-    .padding(edges(8.0, 2.0, 8.0, 2.0))
-}
-
-/// The negotiated wire codec's display name (`quic::CODEC_*` bit → label).
-fn codec_name(bits: u8) -> &'static str {
-    match bits {
-        punktfunk_core::quic::CODEC_H264 => "H.264",
-        punktfunk_core::quic::CODEC_AV1 => "AV1",
-        _ => "HEVC",
-    }
-}
-
-/// `mm:ss` (or `h:mm:ss`) session time.
-fn fmt_uptime(secs: u32) -> String {
-    let (h, m, s) = (secs / 3600, secs / 60 % 60, secs % 60);
-    if h > 0 {
-        format!("{h}:{m:02}:{s:02}")
-    } else {
-        format!("{m}:{s:02}")
-    }
-}
-
-/// The streaming HUD overlay (top-right), unified stats vocabulary (design/stats-unification.md):
-/// a chip row (mode · codec · decode path · HDR), a stream line (received fps · goodput ·
-/// presenter fps), the end-to-end headline (capture→on-glass p50/p95, host-clock corrected), the
-/// stage equation (= host + network + decode + display when the host reports 0xCF timings, else
-/// the combined = host+network + decode + display; stage p50s), a session line
-/// (host · time · loss/skips), and the shortcut hints. Layered over the `SwapChainPanel` in the
-/// same grid cell.
-fn hud_overlay(hud: &HudSample, mode: Option<Mode>, host: &str) -> Element {
-    let stats = &hud.stats;
-    let present = &hud.present;
-    let res = mode
-        .map(|m| format!("{}\u{00D7}{}@{}", m.width, m.height, m.refresh_hz))
-        .unwrap_or_else(|| "\u{2014}".into());
-    let mut chips: Vec<Element> = vec![
-        hud_chip(&res, Color::rgb(235, 235, 235)).into(),
-        hud_chip(codec_name(stats.codec), Color::rgb(180, 190, 255)).into(),
-    ];
-    chips.push(if stats.hardware {
-        hud_chip("GPU decode", Color::rgb(120, 220, 150)).into()
-    } else {
-        hud_chip("CPU decode", Color::rgb(240, 190, 90)).into()
-    });
-    if stats.hdr {
-        chips.push(hud_chip("HDR", Color::rgb(255, 205, 90)).into());
-    }
-    // Received fps + goodput, plus the presenter's own rate (Moonlight's "Rendering frame rate"
-    // analog — how often the display actually gets a new frame).
-    let stream_line = format!(
-        "{:.0} fps \u{00B7} {:.1} Mb/s \u{00B7} display {} fps",
-        stats.fps, stats.mbps, present.fps
-    );
-    // The headline: end-to-end capture→displayed, measured directly post-Present (never the sum
-    // of the stage percentiles). `(same-host clock)` flags an uncorrected clock (offset == 0:
-    // same host, or the host skipped the skew handshake).
-    let mut e2e_line = format!(
-        "end-to-end {:.1} ms p50 \u{00B7} {:.1} p95 \u{00B7} capture\u{2192}on-glass",
-        present.e2e_p50_ms, present.e2e_p95_ms
-    );
-    if stats.same_host {
-        e2e_line.push_str(" (same-host clock)");
-    }
-    // The equation: the stages tile the headline interval per frame; the window p50s only
-    // approximately sum (percentiles aren't additive). With per-AU 0xCF host timings the opaque
-    // `host+network` term splits into `host` (host capture→sent) + `network` (the remainder);
-    // an old host emits none and the combined term stays.
-    let stage_line = if stats.split {
-        format!(
-            "= host {:.1} + network {:.1} + decode {:.1} + display {:.1}",
-            stats.host_ms, stats.net_ms, stats.decode_ms, present.display_p50_ms
-        )
-    } else {
-        format!(
-            "= host+network {:.1} + decode {:.1} + display {:.1}",
-            stats.hostnet_ms, stats.decode_ms, present.display_p50_ms
-        )
-    };
-    let mut session_bits: Vec<String> = Vec::new();
-    if !host.is_empty() {
-        session_bits.push(host.to_string());
-    }
-    // `lost` = unrecoverable network drops (session-cumulative); `skipped` = the render thread's
-    // newest-wins drops last window (expected when the stream outpaces the display).
-    session_bits.push(fmt_uptime(stats.uptime_secs));
-    session_bits.push(format!("{} lost", stats.dropped));
-    if present.skipped > 0 {
-        session_bits.push(format!("{} skipped", present.skipped));
-    }
-    let session_line = session_bits.join(" \u{00B7} ");
-    let hint = if hud.captured {
-        "Ctrl+Alt+Shift+Q releases the mouse \u{00B7} Ctrl+Alt+Shift+D disconnects \u{00B7} \
-         Ctrl+Alt+Shift+S stats \u{00B7} F11 fullscreen"
-    } else {
-        "Click the stream to capture \u{00B7} Ctrl+Alt+Shift+D disconnects \u{00B7} \
-         Ctrl+Alt+Shift+S stats \u{00B7} F11 fullscreen"
-    };
-    let dim = |t: &str| {
-        text_block(t)
-            .font_size(11.0)
-            .foreground(Color::rgb(210, 210, 210))
-    };
-    border(
-        vstack((
-            hstack(chips).spacing(6.0),
-            dim(&stream_line),
-            dim(&e2e_line),
-            dim(&stage_line),
-            dim(&session_line),
-            text_block(hint)
-                .font_size(11.0)
-                .foreground(Color::rgb(150, 150, 150)),
-        ))
-        .spacing(6.0),
-    )
-    .background(Color::rgb(0, 0, 0))
-    .corner_radius(10.0)
-    .padding(uniform(10.0))
-    .opacity(0.82)
-    .horizontal_alignment(HorizontalAlignment::Right)
-    .vertical_alignment(VerticalAlignment::Top)
-    .margin(uniform(12.0))
-    .into()
-}

clients/windows/src/audio.rs

@@ -1,308 +0,0 @@
-//! Audio: playback (decoded PCM → a WASAPI shared-mode render stream) and the microphone
-//! uplink (WASAPI capture → Opus → 0xCB datagrams, the inverse of the host's virtual mic).
-//!
-//! The WASAPI analogue of the Linux client's PipeWire backend. Playback mirrors the host's
-//! virtual-mic producer's adaptive jitter buffer: the session pump pushes 5 ms Opus-decoded
-//! chunks on the network clock; the WASAPI render thread pulls whole event-driven quanta on
-//! the device clock. Prime to ~3 quanta before producing, cap the ring so latency stays
-//! bounded, re-prime after a real drain.
-//!
-//! WASAPI objects are COM-apartment-bound and not `Send`, so they live on a dedicated thread
-//! (the same discipline as the host's `wasapi_cap`); only the channel + stop flag + join
-//! handle cross the boundary.
-
-use anyhow::{anyhow, Context, Result};
-use punktfunk_core::client::NativeClient;
-use std::collections::VecDeque;
-use std::sync::atomic::{AtomicBool, Ordering};
-use std::sync::mpsc::{Receiver, SyncSender, TrySendError};
-use std::sync::Arc;
-use std::time::Duration;
-use wasapi::{DeviceEnumerator, Direction, SampleType, StreamMode, WaveFormat};
-
-const SAMPLE_RATE: usize = 48_000;
-/// The microphone uplink stays stereo (the host's virtual mic is stereo). The render path is
-/// multichannel — its channel count + block align are runtime, driven by the host-resolved layout.
-const CHANNELS: usize = 2;
-/// Mic frames are 20 ms (960 samples/channel) — any size ≤ 120 ms is fine host-side.
-const MIC_FRAME: usize = 960;
-
-pub struct AudioPlayer {
-    pcm_tx: SyncSender<Vec<f32>>,
-    stop: Arc<AtomicBool>,
-    thread: Option<std::thread::JoinHandle<()>>,
-}
-
-impl AudioPlayer {
-    /// Spawn the WASAPI render thread for `channels` (2/6/8, canonical wire order
-    /// FL FR FC LFE RL RR SL SR). Failure (no render endpoint on this box) is survivable — the
-    /// caller streams video-only.
-    pub fn spawn(channels: u8) -> Result<AudioPlayer> {
-        // 64 × 5 ms = 320 ms of slack between the pump and the WASAPI loop.
-        let (pcm_tx, pcm_rx) = std::sync::mpsc::sync_channel::<Vec<f32>>(64);
-        let stop = Arc::new(AtomicBool::new(false));
-        let (ready_tx, ready_rx) = std::sync::mpsc::sync_channel::<Result<()>>(1);
-        let stop_t = stop.clone();
-        let thread = std::thread::Builder::new()
-            .name("punktfunk-audio".into())
-            .spawn(move || {
-                if let Err(e) = render_thread(pcm_rx, stop_t, ready_tx, channels) {
-                    tracing::warn!(error = format!("{e:#}"), "audio playback thread ended");
-                }
-            })
-            .context("spawn audio thread")?;
-        match ready_rx.recv_timeout(Duration::from_secs(3)) {
-            Ok(Ok(())) => {
-                tracing::info!(channels, "WASAPI render: 48 kHz f32 (default endpoint)");
-                Ok(AudioPlayer {
-                    pcm_tx,
-                    stop,
-                    thread: Some(thread),
-                })
-            }
-            Ok(Err(e)) => Err(e),
-            Err(_) => Err(anyhow!(
-                "wasapi render init timed out (no render endpoint?)"
-            )),
-        }
-    }
-
-    /// Queue one interleaved f32 chunk (in the session's channel layout). Drops the chunk if the
-    /// WASAPI side is wedged (the renderer conceals the gap; never block the session pump).
-    pub fn push(&self, pcm: Vec<f32>) {
-        if let Err(TrySendError::Disconnected(_)) = self.pcm_tx.try_send(pcm) {
-            // Thread already dead — Drop will reap it; nothing to do per-chunk.
-        }
-    }
-}
-
-impl Drop for AudioPlayer {
-    fn drop(&mut self) {
-        self.stop.store(true, Ordering::SeqCst);
-        if let Some(t) = self.thread.take() {
-            let _ = t.join();
-        }
-    }
-}
-
-fn render_thread(
-    pcm_rx: Receiver<Vec<f32>>,
-    stop: Arc<AtomicBool>,
-    ready: SyncSender<Result<()>>,
-    channels: u8,
-) -> Result<()> {
-    if let Err(e) = wasapi::initialize_mta()
-        .ok()
-        .context("CoInitializeEx (MTA)")
-    {
-        let _ = ready.send(Err(e));
-        return Ok(());
-    }
-    let res = (|| -> Result<()> {
-        // F32LE interleaved: channels × 4 bytes/sample. Stereo (channels == 2) is byte-identical
-        // to the old fixed path (mask 0x3, block align 8).
-        let block_align = channels as usize * 4;
-        let device = DeviceEnumerator::new()
-            .context("DeviceEnumerator")?
-            .get_default_device(&Direction::Render)
-            .context("default render endpoint")?;
-        let mut audio_client = device.get_iaudioclient().context("IAudioClient")?;
-        // The explicit dwChannelMask is the wire order (FL FR FC LFE RL RR SL SR); 5.1 = 0x3F,
-        // 7.1 = 0x63F. WASAPI delivers channels in ascending mask-bit order, which equals the wire
-        // order, so the render mapping is the identity — no permute. `autoconvert` (below) lets the
-        // audio engine downmix when the endpoint has fewer speakers.
-        let desired = WaveFormat::new(
-            32,
-            32,
-            &SampleType::Float,
-            SAMPLE_RATE,
-            channels as usize,
-            Some(punktfunk_core::audio::wasapi_channel_mask(channels)),
-        );
-        let (default_period, _min_period) =
-            audio_client.get_device_period().context("device period")?;
-        let mode = StreamMode::EventsShared {
-            autoconvert: true,
-            buffer_duration_hns: default_period,
-        };
-        audio_client
-            .initialize_client(&desired, &Direction::Render, &mode)
-            .context("initialize render client")?;
-        let h_event = audio_client.set_get_eventhandle().context("event handle")?;
-        let render_client = audio_client
-            .get_audiorenderclient()
-            .context("IAudioRenderClient")?;
-        audio_client.start_stream().context("start render stream")?;
-        let _ = ready.send(Ok(()));
-
-        // Adaptive jitter buffer, in f32-byte units (same shape as the host's virtual mic).
-        let mut ring: VecDeque<u8> = VecDeque::new();
-        let mut primed = false;
-        let mut out = Vec::new(); // per-quantum scratch, reused across iterations
-
-        while !stop.load(Ordering::Relaxed) {
-            if h_event.wait_for_event(100).is_err() {
-                continue;
-            }
-            // Drain everything the pump has queued into the ring.
-            while let Ok(chunk) = pcm_rx.try_recv() {
-                for s in chunk {
-                    ring.extend(s.to_le_bytes());
-                }
-            }
-            let avail_frames = audio_client
-                .get_available_space_in_frames()
-                .context("available space")? as usize;
-            if avail_frames == 0 {
-                continue;
-            }
-            let want_bytes = avail_frames * block_align;
-
-            // Prime to ~3 quanta; cap at ~1 quantum of slack beyond that; re-prime on drain.
-            let target = (3 * want_bytes).clamp(720 * block_align, 9600 * block_align);
-            let cap = target.max(want_bytes) + want_bytes;
-            if ring.len() > cap {
-                ring.drain(..ring.len() - cap);
-            }
-            if !primed && ring.len() >= target {
-                primed = true;
-            }
-
-            out.clear();
-            out.resize(want_bytes, 0);
-            if primed {
-                let n = ring.len().min(want_bytes);
-                for (dst, b) in out.iter_mut().zip(ring.drain(..n)) {
-                    *dst = b;
-                }
-            }
-            if ring.is_empty() {
-                primed = false;
-            }
-            render_client
-                .write_to_device(avail_frames, &out, None)
-                .context("write_to_device")?;
-        }
-        audio_client.stop_stream().ok();
-        Ok(())
-    })();
-    if let Err(ref e) = res {
-        let _ = ready.send(Err(anyhow!("{e:#}")));
-    }
-    res
-}
-
-/// The microphone uplink: capture the default input device, Opus-encode 20 ms chunks, ship
-/// them as 0xCB datagrams into the host's virtual mic source.
-pub struct MicStreamer {
-    stop: Arc<AtomicBool>,
-    thread: Option<std::thread::JoinHandle<()>>,
-}
-
-impl MicStreamer {
-    pub fn spawn(connector: Arc<NativeClient>) -> Result<MicStreamer> {
-        let stop = Arc::new(AtomicBool::new(false));
-        let stop_t = stop.clone();
-        let thread = std::thread::Builder::new()
-            .name("punktfunk-mic".into())
-            .spawn(move || {
-                if let Err(e) = mic_thread(&connector, stop_t) {
-                    tracing::warn!(error = format!("{e:#}"), "mic uplink thread ended");
-                }
-            })
-            .context("spawn mic thread")?;
-        Ok(MicStreamer {
-            stop,
-            thread: Some(thread),
-        })
-    }
-}
-
-impl Drop for MicStreamer {
-    fn drop(&mut self) {
-        self.stop.store(true, Ordering::SeqCst);
-        if let Some(t) = self.thread.take() {
-            let _ = t.join();
-        }
-    }
-}
-
-fn mic_thread(connector: &Arc<NativeClient>, stop: Arc<AtomicBool>) -> Result<()> {
-    wasapi::initialize_mta()
-        .ok()
-        .context("CoInitializeEx (MTA)")?;
-
-    let mut encoder = opus::Encoder::new(
-        SAMPLE_RATE as u32,
-        opus::Channels::Stereo,
-        opus::Application::Voip,
-    )
-    .map_err(|e| anyhow!("opus encoder: {e}"))?;
-    let _ = encoder.set_bitrate(opus::Bitrate::Bits(64_000));
-
-    let device = DeviceEnumerator::new()
-        .context("DeviceEnumerator")?
-        .get_default_device(&Direction::Capture)
-        .context("default capture endpoint (no microphone?)")?;
-    let mut audio_client = device.get_iaudioclient().context("IAudioClient")?;
-    let desired = WaveFormat::new(32, 32, &SampleType::Float, SAMPLE_RATE, CHANNELS, None);
-    let (default_period, _min_period) =
-        audio_client.get_device_period().context("device period")?;
-    let mode = StreamMode::EventsShared {
-        autoconvert: true,
-        buffer_duration_hns: default_period,
-    };
-    audio_client
-        .initialize_client(&desired, &Direction::Capture, &mode)
-        .context("initialize capture client")?;
-    let h_event = audio_client.set_get_eventhandle().context("event handle")?;
-    let capture_client = audio_client
-        .get_audiocaptureclient()
-        .context("IAudioCaptureClient")?;
-    audio_client
-        .start_stream()
-        .context("start capture stream")?;
-
-    let mut bytes: VecDeque<u8> = VecDeque::new();
-    let mut ring: VecDeque<f32> = VecDeque::new();
-    let mut out = vec![0u8; 4000];
-    let mut seq = 0u32;
-
-    while !stop.load(Ordering::Relaxed) {
-        if h_event.wait_for_event(100).is_err() {
-            continue;
-        }
-        loop {
-            match capture_client.get_next_packet_size() {
-                Ok(Some(0)) | Ok(None) => break,
-                Ok(Some(_n)) => {
-                    capture_client
-                        .read_from_device_to_deque(&mut bytes)
-                        .context("read capture")?;
-                }
-                Err(e) => return Err(anyhow!("get_next_packet_size: {e}")),
-            }
-        }
-        let whole = (bytes.len() / 4) * 4;
-        for c in bytes.drain(..whole).collect::<Vec<u8>>().chunks_exact(4) {
-            ring.push_back(f32::from_le_bytes([c[0], c[1], c[2], c[3]]));
-        }
-        // Ship every complete 20 ms stereo frame.
-        while ring.len() >= MIC_FRAME * CHANNELS {
-            let pcm: Vec<f32> = ring.drain(..MIC_FRAME * CHANNELS).collect();
-            match encoder.encode_float(&pcm, &mut out) {
-                Ok(len) => {
-                    let pts = std::time::SystemTime::now()
-                        .duration_since(std::time::UNIX_EPOCH)
-                        .map(|d| d.as_nanos() as u64)
-                        .unwrap_or(0);
-                    let _ = connector.send_mic(seq, pts, out[..len].to_vec());
-                    seq = seq.wrapping_add(1);
-                }
-                Err(e) => tracing::debug!(error = %e, "opus mic encode"),
-            }
-        }
-    }
-    audio_client.stop_stream().ok();
-    Ok(())
-}

clients/windows/src/gamepad.rs

@@ -1,669 +0,0 @@
-//! App-lifetime gamepad service over SDL3 (mirrors the Swift/GTK clients' `GamepadManager` +
-//! capture/feedback). Ported near-verbatim from the GTK Linux client — SDL3 is cross-platform,
-//! so the only Windows change is the build (`sdl3` is compiled from source via the bundled
-//! CMake, since there is no system SDL3).
-//!
-//! One worker thread owns SDL for the process lifetime: it tracks connected pads, selects the
-//! ONE controller forwarded as pad 0 (user pin, else the most recently connected), and — while
-//! a session is attached — forwards buttons/axes, DualSense touchpad contacts and motion
-//! samples (0xCC), and renders feedback: rumble on every pad, lightbar via SDL, and on a real
-//! DualSense the raw effects packet (adaptive-trigger blocks replayed verbatim, player LEDs).
-//! Held state is zeroed on the wire when the active pad switches or the session detaches, so
-//! nothing sticks down.
-//!
-//! This thread is also the single consumer of the rumble and HID-output pull planes.
-
-use punktfunk_core::client::NativeClient;
-use punktfunk_core::config::GamepadPref;
-use punktfunk_core::input::{gamepad as wire, InputEvent, InputKind};
-use punktfunk_core::quic::{HidOutput, RichInput};
-use std::collections::HashMap;
-use std::sync::mpsc::{Receiver, Sender};
-use std::sync::{Arc, Mutex};
-use std::time::Duration;
-
-/// Motion scale constants, shared convention with the other clients (`GamepadWire`): derived
-/// from hid-playstation's math over the host's fixed calibration blob. SDL hands us gyro in
-/// rad/s and accel in m/s²; the DualSense report wants raw LSBs.
-const GYRO_LSB_PER_RAD_S: f32 = 20.0 * 180.0 / std::f32::consts::PI;
-const ACCEL_LSB_PER_G: f32 = 10_000.0;
-const G: f32 = 9.80665;
-
-#[derive(Clone, Debug)]
-pub struct PadInfo {
-    /// Stable identity (`vid:pid:name`, the same format as `pf-client-core`'s `PadInfo::key`)
-    /// — persisted as `Settings::forward_pad` so the pin survives restarts AND reaches the
-    /// spawned session binary, whose own gamepad service applies the same key.
-    pub key: String,
-    pub name: String,
-    /// The virtual pad "Automatic" resolves to for this physical controller (DualSense → DualSense,
-    /// DS4 → DualShock 4, Xbox One/Series → Xbox One, else → Xbox 360).
-    pub pref: GamepadPref,
-}
-
-impl PadInfo {
-    /// True for a real DualSense — the only pad whose lightbar / player-LED / adaptive-trigger
-    /// feedback we replay as raw DS5 HID effect packets (a DS4 uses SDL's generic `set_led`).
-    fn is_dualsense(&self) -> bool {
-        self.pref == GamepadPref::DualSense
-    }
-
-    /// A short human label for the detected pad family, shown next to the name in the settings
-    /// GUI's controller list ("" for a generic pad the name already describes).
-    pub fn kind_label(&self) -> &'static str {
-        match self.pref {
-            GamepadPref::DualSense => "DualSense",
-            GamepadPref::DualShock4 => "DualShock 4",
-            GamepadPref::XboxOne => "Xbox One",
-            GamepadPref::SteamDeck => "Steam Deck",
-            GamepadPref::SteamController => "Steam Controller",
-            _ => "",
-        }
-    }
-}
-
-/// 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;
-    match t {
-        T::PS5 => GamepadPref::DualSense,
-        T::PS4 => GamepadPref::DualShock4,
-        T::XboxOne => GamepadPref::XboxOne,
-        _ => GamepadPref::Xbox360,
-    }
-}
-
-enum Ctl {
-    Attach(Arc<NativeClient>),
-    Detach,
-    Pin(Option<String>),
-}
-
-#[derive(Clone)]
-pub struct GamepadService {
-    pads: Arc<Mutex<Vec<PadInfo>>>,
-    active: Arc<Mutex<Option<PadInfo>>>,
-    // `Arc<Mutex<…>>` (not a bare `Sender`, which is `!Sync`) so the service is `Sync` — the
-    // WinUI app shares it across the UI thread and the session-pump thread (attach/detach).
-    ctl: Arc<Mutex<Sender<Ctl>>>,
-}
-
-impl GamepadService {
-    pub fn start() -> GamepadService {
-        let pads = Arc::new(Mutex::new(Vec::new()));
-        let active = Arc::new(Mutex::new(None));
-        let (ctl, ctl_rx) = std::sync::mpsc::channel();
-        let (p, a) = (pads.clone(), active.clone());
-        if let Err(e) = std::thread::Builder::new()
-            .name("punktfunk-gamepad".into())
-            .spawn(move || {
-                if let Err(e) = run(&p, &a, &ctl_rx) {
-                    tracing::warn!(error = %e, "gamepad service ended — pads disabled");
-                }
-            })
-        {
-            tracing::warn!(error = %e, "gamepad service failed to start");
-        }
-        GamepadService {
-            pads,
-            active,
-            ctl: Arc::new(Mutex::new(ctl)),
-        }
-    }
-
-    /// Connected controllers, most recently attached first (the settings GUI's list order).
-    pub fn pads(&self) -> Vec<PadInfo> {
-        self.pads.lock().unwrap().clone()
-    }
-
-    pub fn active(&self) -> Option<PadInfo> {
-        self.active.lock().unwrap().clone()
-    }
-
-    /// Pin the forwarded controller by stable key (`PadInfo::key`) — `None` = automatic.
-    /// The pin survives the pad disconnecting: it re-applies the moment a matching
-    /// controller shows up again (same semantics as `pf-client-core`'s service).
-    pub fn set_pinned(&self, key: Option<String>) {
-        let _ = self.ctl.lock().unwrap().send(Ctl::Pin(key));
-    }
-
-    pub fn attach(&self, connector: Arc<NativeClient>) {
-        let _ = self.ctl.lock().unwrap().send(Ctl::Attach(connector));
-    }
-
-    pub fn detach(&self) {
-        let _ = self.ctl.lock().unwrap().send(Ctl::Detach);
-    }
-
-    /// What "Automatic" resolves to right now — the virtual pad matching the physical one
-    /// (Swift parity); no pad connected leaves the host's own default.
-    pub fn auto_pref(&self) -> GamepadPref {
-        match self.active() {
-            Some(p) => p.pref,
-            None => GamepadPref::Auto,
-        }
-    }
-}
-
-fn send(connector: &NativeClient, kind: InputKind, code: u32, x: i32) {
-    let _ = connector.send_input(&InputEvent {
-        kind,
-        _pad: [0; 3],
-        code,
-        x,
-        y: 0,
-        flags: 0, // pad index 0 — single-pad model
-    });
-}
-
-fn button_bit(b: sdl3::gamepad::Button) -> Option<u32> {
-    use sdl3::gamepad::Button;
-    Some(match b {
-        Button::South => wire::BTN_A,
-        Button::East => wire::BTN_B,
-        Button::West => wire::BTN_X,
-        Button::North => wire::BTN_Y,
-        Button::Back => wire::BTN_BACK,
-        Button::Start => wire::BTN_START,
-        Button::Guide => wire::BTN_GUIDE,
-        Button::LeftStick => wire::BTN_LS_CLICK,
-        Button::RightStick => wire::BTN_RS_CLICK,
-        Button::LeftShoulder => wire::BTN_LB,
-        Button::RightShoulder => wire::BTN_RB,
-        Button::DPadUp => wire::BTN_DPAD_UP,
-        Button::DPadDown => wire::BTN_DPAD_DOWN,
-        Button::DPadLeft => wire::BTN_DPAD_LEFT,
-        Button::DPadRight => wire::BTN_DPAD_RIGHT,
-        Button::Touchpad => wire::BTN_TOUCHPAD,
-        // Back grips / paddles (Steam Deck L4/L5/R4/R5, Xbox Elite P1–P4) + the misc/Share button.
-        // PADDLE1/2/3/4 = R4/L4/R5/L5 (see the host `input::gamepad`).
-        Button::RightPaddle1 => wire::BTN_PADDLE1,
-        Button::LeftPaddle1 => wire::BTN_PADDLE2,
-        Button::RightPaddle2 => wire::BTN_PADDLE3,
-        Button::LeftPaddle2 => wire::BTN_PADDLE4,
-        Button::Misc1 => wire::BTN_MISC1,
-        _ => return None,
-    })
-}
-
-/// SDL axis → (wire axis id, wire value). SDL sticks are +y = down; the wire (XInput
-/// convention) is +y = up. SDL triggers span 0..32767; the wire wants 0..255.
-fn axis_value(axis: sdl3::gamepad::Axis, v: i16) -> (u32, i32) {
-    use sdl3::gamepad::Axis;
-    match axis {
-        Axis::LeftX => (wire::AXIS_LS_X, v as i32),
-        Axis::LeftY => (wire::AXIS_LS_Y, -(v as i32).max(-32767)),
-        Axis::RightX => (wire::AXIS_RS_X, v as i32),
-        Axis::RightY => (wire::AXIS_RS_Y, -(v as i32).max(-32767)),
-        Axis::TriggerLeft => (wire::AXIS_LT, (v as i32).clamp(0, 32767) >> 7),
-        Axis::TriggerRight => (wire::AXIS_RT, (v as i32).clamp(0, 32767) >> 7),
-    }
-}
-
-/// The DualSense effects packet (SDL `DS5EffectsState_t`, 47 bytes) — the same layout the 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.
-#[derive(Default)]
-struct Ds5Feedback;
-
-impl Ds5Feedback {
-    const RIGHT_TRIGGER: usize = 10;
-    const LEFT_TRIGGER: usize = 21;
-    const PAD_LIGHTS: usize = 43;
-    const LED_RGB: usize = 44;
-
-    fn trigger_packet(which: u8, effect: &[u8]) -> [u8; 47] {
-        let mut p = [0u8; 47];
-        let (flag, off) = if which == 1 {
-            (0x04, Self::RIGHT_TRIGGER)
-        } else {
-            (0x08, Self::LEFT_TRIGGER)
-        };
-        p[0] = flag;
-        let n = effect.len().min(11);
-        p[off..off + n].copy_from_slice(&effect[..n]);
-        p
-    }
-
-    fn lightbar_packet(r: u8, g: u8, b: u8) -> [u8; 47] {
-        let mut p = [0u8; 47];
-        p[1] = 0x04; // lightbar enable
-        p[Self::LED_RGB] = r;
-        p[Self::LED_RGB + 1] = g;
-        p[Self::LED_RGB + 2] = b;
-        p
-    }
-
-    fn player_packet(bits: u8) -> [u8; 47] {
-        let mut p = [0u8; 47];
-        p[1] = 0x10; // player-LED enable
-        p[Self::PAD_LIGHTS] = bits & 0x1F;
-        p
-    }
-}
-
-struct Worker {
-    subsystem: sdl3::GamepadSubsystem,
-    opened: HashMap<u32, sdl3::gamepad::Gamepad>,
-    /// Connection order; the most recently connected is the auto selection.
-    order: Vec<u32>,
-    /// The user pin by stable key (`PadInfo::key`); resolved to an instance id per lookup
-    /// so it re-applies whenever a matching pad (re)connects.
-    pinned: Option<String>,
-    attached: Option<Arc<NativeClient>>,
-    /// Wire state of the active pad — zeroed on the wire at switch/detach.
-    last_axis: [i32; 6],
-    held_buttons: Vec<u32>,
-    /// Touchpad contacts the host believes are down, keyed by `(surface, finger)` — lifted on pad
-    /// switch / detach. surface 0 = the legacy single touchpad, 1/2 = a Steam left/right pad.
-    held_touches: std::collections::HashSet<(u8, u8)>,
-    last_accel: [i16; 3],
-}
-
-impl Worker {
-    fn active_id(&self) -> Option<u32> {
-        self.pinned
-            .as_deref()
-            .and_then(|key| {
-                self.order
-                    .iter()
-                    .rev() // prefer the most recently connected pad with this identity
-                    .find(|&&id| self.pad_info(id).is_some_and(|p| p.key == key))
-                    .copied()
-            })
-            .or_else(|| self.order.last().copied())
-    }
-
-    fn pad_info(&self, id: u32) -> Option<PadInfo> {
-        let pad = self.opened.get(&id)?;
-        let mut pref = pref_for_type(
-            self.subsystem
-                .type_for_id(sdl3::sys::joystick::SDL_JoystickID(id)),
-        );
-        let (vid, pid) = (pad.vendor_id().unwrap_or(0), pad.product_id().unwrap_or(0));
-        // No SDL type for the Steam Deck / Steam Controller — detect Valve by VID/PID (Deck 0x1205,
-        // SC wired 0x1102, SC dongle 0x1142) so the host builds the virtual hid-steam pad.
-        if vid == 0x28DE && matches!(pid, 0x1205 | 0x1102 | 0x1142) {
-            pref = GamepadPref::SteamDeck;
-        }
-        let name = pad.name().unwrap_or_else(|| "Controller".into());
-        Some(PadInfo {
-            // Must match pf-client-core's `PadInfo::key` byte-for-byte — the persisted
-            // `forward_pad` is applied by BOTH services (this one and the session's).
-            key: format!("{vid:04x}:{pid:04x}:{name}"),
-            name,
-            pref,
-        })
-    }
-
-    /// Zero everything the host believes is held — on pad switch and detach.
-    fn flush_held(&mut self) {
-        if let Some(c) = &self.attached {
-            for b in self.held_buttons.drain(..) {
-                send(c, InputKind::GamepadButton, b, 0);
-            }
-            for (id, v) in self.last_axis.iter_mut().enumerate() {
-                if *v != 0 && *v != i32::MIN {
-                    send(c, InputKind::GamepadAxis, id as u32, 0);
-                }
-                *v = i32::MIN;
-            }
-            for (surface, finger) in self.held_touches.drain() {
-                let rich = if surface == 0 {
-                    RichInput::Touchpad {
-                        pad: 0,
-                        finger,
-                        active: false,
-                        x: 0,
-                        y: 0,
-                    }
-                } else {
-                    RichInput::TouchpadEx {
-                        pad: 0,
-                        surface,
-                        finger,
-                        touch: false,
-                        click: false,
-                        x: 0,
-                        y: 0,
-                        pressure: 0,
-                    }
-                };
-                let _ = c.send_rich_input(rich);
-            }
-        } else {
-            self.held_buttons.clear();
-            self.last_axis = [i32::MIN; 6];
-            self.held_touches.clear();
-        }
-    }
-
-    /// Sensors stream only while a session wants them (they cost USB/BT bandwidth).
-    fn set_sensors(&mut self, enabled: bool) {
-        let Some(id) = self.active_id() else { return };
-        if let Some(pad) = self.opened.get_mut(&id) {
-            use sdl3::sensor::SensorType;
-            for s in [SensorType::Gyroscope, SensorType::Accelerometer] {
-                if unsafe { pad.has_sensor(s) } {
-                    let _ = pad.sensor_set_enabled(s, enabled);
-                }
-            }
-        }
-    }
-
-    /// Forward one touchpad contact on the rich-input plane. A multi-touchpad pad (Steam Deck / Steam
-    /// Controller) sends `TouchpadEx` with the surface (SDL touchpad 0 = left → 1, 1 = right → 2) and
-    /// signed coordinates; a single-touchpad pad (DualSense) keeps the legacy `Touchpad` (unsigned).
-    fn forward_touch(
-        &mut self,
-        which: u32,
-        touchpad: u32,
-        finger: u8,
-        x: f32,
-        y: f32,
-        active: bool,
-    ) {
-        let Some(c) = self.attached.as_ref() else {
-            return;
-        };
-        let multi = self
-            .opened
-            .get(&which)
-            .map(|p| p.touchpads_count() >= 2)
-            .unwrap_or(false);
-        let (cx, cy) = (x.clamp(0.0, 1.0), y.clamp(0.0, 1.0));
-        let surface = if multi { (touchpad as u8) + 1 } else { 0 };
-        let rich = if multi {
-            RichInput::TouchpadEx {
-                pad: 0,
-                surface,
-                finger,
-                touch: active,
-                click: false,
-                x: (cx * 65535.0 - 32768.0) as i16,
-                y: (cy * 65535.0 - 32768.0) as i16,
-                pressure: 0,
-            }
-        } else {
-            RichInput::Touchpad {
-                pad: 0,
-                finger,
-                active,
-                x: (cx * 65535.0) as u16,
-                y: (cy * 65535.0) as u16,
-            }
-        };
-        let _ = c.send_rich_input(rich);
-        if active {
-            self.held_touches.insert((surface, finger));
-        } else {
-            self.held_touches.remove(&(surface, finger));
-        }
-    }
-}
-
-#[allow(clippy::too_many_lines)]
-fn run(
-    pads_out: &Mutex<Vec<PadInfo>>,
-    active_out: &Mutex<Option<PadInfo>>,
-    ctl: &Receiver<Ctl>,
-) -> Result<(), String> {
-    // Off-main-thread + no video subsystem: keep SDL away from signals, poll pads on its own
-    // thread.
-    sdl3::hint::set("SDL_NO_SIGNAL_HANDLERS", "1");
-    sdl3::hint::set("SDL_JOYSTICK_THREAD", "1");
-    // Let SDL's HIDAPI drivers open Valve Steam Controller / Steam Deck devices directly, so the
-    // paddles, both trackpads, and gyro arrive as first-class SDL gamepad inputs.
-    sdl3::hint::set("SDL_JOYSTICK_HIDAPI_STEAMDECK", "1");
-    sdl3::hint::set("SDL_JOYSTICK_HIDAPI_STEAM", "1");
-    let sdl = sdl3::init().map_err(|e| e.to_string())?;
-    let subsystem = sdl.gamepad().map_err(|e| e.to_string())?;
-    let mut pump = sdl.event_pump().map_err(|e| e.to_string())?;
-
-    let mut w = Worker {
-        subsystem,
-        opened: HashMap::new(),
-        order: Vec::new(),
-        pinned: None,
-        attached: None,
-        last_axis: [i32::MIN; 6],
-        held_buttons: Vec::new(),
-        held_touches: std::collections::HashSet::new(),
-        last_accel: [0; 3],
-    };
-
-    let publish = |w: &Worker| {
-        let mut list: Vec<PadInfo> = w.order.iter().filter_map(|&id| w.pad_info(id)).collect();
-        list.reverse(); // most recent first — the Settings list order
-        *pads_out.lock().unwrap() = list;
-        *active_out.lock().unwrap() = w.active_id().and_then(|id| w.pad_info(id));
-    };
-
-    loop {
-        // Control plane from the UI thread.
-        loop {
-            match ctl.try_recv() {
-                Ok(Ctl::Attach(c)) => {
-                    w.attached = Some(c);
-                    w.last_axis = [i32::MIN; 6];
-                    w.set_sensors(true);
-                }
-                Ok(Ctl::Detach) => {
-                    w.flush_held();
-                    w.set_sensors(false);
-                    w.attached = None;
-                }
-                Ok(Ctl::Pin(key)) => {
-                    let before = w.active_id();
-                    w.pinned = key;
-                    if w.active_id() != before {
-                        w.flush_held();
-                        if w.attached.is_some() {
-                            w.set_sensors(true);
-                        }
-                    }
-                    publish(&w);
-                }
-                Err(std::sync::mpsc::TryRecvError::Empty) => break,
-                Err(std::sync::mpsc::TryRecvError::Disconnected) => return Ok(()), // app gone
-            }
-        }
-
-        while let Some(event) = pump.poll_event() {
-            use sdl3::event::Event;
-            let active = w.active_id();
-            match event {
-                Event::ControllerDeviceAdded { which, .. } => {
-                    if !w.opened.contains_key(&which) {
-                        match w.subsystem.open(sdl3::sys::joystick::SDL_JoystickID(which)) {
-                            Ok(pad) => {
-                                tracing::info!(
-                                    name = pad.name().unwrap_or_default(),
-                                    "gamepad attached"
-                                );
-                                w.opened.insert(which, pad);
-                                w.order.push(which);
-                                if w.attached.is_some() && w.active_id() == Some(which) {
-                                    w.set_sensors(true);
-                                }
-                                publish(&w);
-                            }
-                            Err(e) => tracing::warn!(error = %e, "gamepad open failed"),
-                        }
-                    }
-                }
-                Event::ControllerDeviceRemoved { which, .. } => {
-                    if w.opened.remove(&which).is_some() {
-                        w.order.retain(|&id| id != which);
-                        if active == Some(which) {
-                            w.flush_held();
-                        }
-                        tracing::info!("gamepad detached");
-                        publish(&w);
-                    }
-                }
-                Event::ControllerButtonDown { which, button, .. }
-                    if active == Some(which) && w.attached.is_some() =>
-                {
-                    if let Some(bit) = button_bit(button) {
-                        w.held_buttons.push(bit);
-                        send(
-                            w.attached.as_ref().unwrap(),
-                            InputKind::GamepadButton,
-                            bit,
-                            1,
-                        );
-                    }
-                }
-                Event::ControllerButtonUp { which, button, .. }
-                    if active == Some(which) && w.attached.is_some() =>
-                {
-                    if let Some(bit) = button_bit(button) {
-                        w.held_buttons.retain(|&b| b != bit);
-                        send(
-                            w.attached.as_ref().unwrap(),
-                            InputKind::GamepadButton,
-                            bit,
-                            0,
-                        );
-                    }
-                }
-                Event::ControllerAxisMotion {
-                    which, axis, value, ..
-                } if active == Some(which) && w.attached.is_some() => {
-                    let (id, v) = axis_value(axis, value);
-                    if w.last_axis[id as usize] != v {
-                        w.last_axis[id as usize] = v;
-                        send(w.attached.as_ref().unwrap(), InputKind::GamepadAxis, id, v);
-                    }
-                }
-                // Touchpad contacts → the rich-input plane. One pad (DualSense) keeps the legacy
-                // `Touchpad`; two pads (Steam Deck / Steam Controller) send `TouchpadEx` per surface.
-                Event::ControllerTouchpadDown {
-                    which,
-                    touchpad,
-                    finger,
-                    x,
-                    y,
-                    ..
-                }
-                | Event::ControllerTouchpadMotion {
-                    which,
-                    touchpad,
-                    finger,
-                    x,
-                    y,
-                    ..
-                } if active == Some(which) && w.attached.is_some() => {
-                    w.forward_touch(which, touchpad as u32, finger as u8, x, y, true);
-                }
-                Event::ControllerTouchpadUp {
-                    which,
-                    touchpad,
-                    finger,
-                    x,
-                    y,
-                    ..
-                } if active == Some(which) && w.attached.is_some() => {
-                    w.forward_touch(which, touchpad as u32, finger as u8, x, y, false);
-                }
-                // Motion: accel events update the cache; each gyro event ships a sample (the
-                // DualSense reports both at ~250 Hz). Scale convention shared with the other
-                // clients — sign/scale derived, not yet live-verified.
-                Event::ControllerSensorUpdated {
-                    which,
-                    sensor,
-                    data,
-                    ..
-                } if active == Some(which) && w.attached.is_some() => {
-                    use sdl3::sensor::SensorType;
-                    match sensor {
-                        SensorType::Accelerometer => {
-                            for (i, v) in data.iter().enumerate() {
-                                w.last_accel[i] =
-                                    (v / G * ACCEL_LSB_PER_G).clamp(-32768.0, 32767.0) as i16;
-                            }
-                        }
-                        SensorType::Gyroscope => {
-                            let mut gyro = [0i16; 3];
-                            for (i, v) in data.iter().enumerate() {
-                                gyro[i] = (v * GYRO_LSB_PER_RAD_S).clamp(-32768.0, 32767.0) as i16;
-                            }
-                            let _ =
-                                w.attached
-                                    .as_ref()
-                                    .unwrap()
-                                    .send_rich_input(RichInput::Motion {
-                                        pad: 0,
-                                        gyro,
-                                        accel: w.last_accel,
-                                    });
-                        }
-                        _ => {}
-                    }
-                }
-                _ => {}
-            }
-        }
-
-        // Feedback planes (this thread is their single consumer). Rumble arrives as
-        // self-terminating v2 envelopes: the host renews an active level and lets an abandoned one
-        // lapse, so the SDL duration is the host's TTL — a lost stop (or a dead host) self-silences
-        // at the lease instead of droning. A legacy host (`ttl == None`) sends no lease → keep the
-        // proven 5 s duration and rely on its periodic re-send as before.
-        if let Some(connector) = w.attached.clone() {
-            while let Ok((pad, low, high, ttl)) = connector.next_rumble_ttl(Duration::ZERO) {
-                if pad == 0 {
-                    // Floor the lease so a jittered renewal can't gap the actuator between writes.
-                    let dur_ms = ttl.map_or(5_000, |ms| (ms as u32).max(240));
-                    if let Some(p) = w.active_id().and_then(|id| w.opened.get_mut(&id)) {
-                        // 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 on 0xCA, so the two together pinpoint host-game vs
-                        // client-render.
-                        if let Err(e) = p.set_rumble(low, high, dur_ms) {
-                            tracing::warn!(low, high, error = %e, "rumble: SDL set_rumble failed");
-                        } else {
-                            tracing::debug!(low, high, "rumble: rendered");
-                        }
-                    } else {
-                        tracing::debug!(low, high, "rumble: received but no active pad to render");
-                    }
-                }
-            }
-            while let Ok(hid) = connector.next_hidout(Duration::ZERO) {
-                let Some(id) = w.active_id() else { continue };
-                let is_ds = w.pad_info(id).is_some_and(|p| p.is_dualsense());
-                let Some(pad) = w.opened.get_mut(&id) else {
-                    continue;
-                };
-                match hid {
-                    HidOutput::Led { pad: 0, r, g, b } if is_ds => {
-                        let _ = pad.send_effect(&Ds5Feedback::lightbar_packet(r, g, b));
-                    }
-                    HidOutput::Led { pad: 0, r, g, b } => {
-                        let _ = pad.set_led(r, g, b);
-                    }
-                    HidOutput::PlayerLeds { pad: 0, bits } if is_ds => {
-                        let _ = pad.send_effect(&Ds5Feedback::player_packet(bits));
-                    }
-                    HidOutput::Trigger {
-                        pad: 0,
-                        which,
-                        ref effect,
-                    } if is_ds => {
-                        let _ = pad.send_effect(&Ds5Feedback::trigger_packet(which, effect));
-                    }
-                    _ => {}
-                }
-            }
-        }
-
-        std::thread::sleep(Duration::from_millis(if w.attached.is_some() {
-            2
-        } else {
-            30
-        }));
-    }
-}

clients/windows/src/gpu.rs

@@ -1,104 +1,14 @@
-//! The single Direct3D 11 device shared by the video decoder (D3D11VA hardware decode) and the
-//! presenter (the `SwapChainPanel` composition swapchain + the present draw).
+//! DXGI adapter enumeration for the Settings "GPU" picker.
 //!
-//! Zero-copy hardware decode requires FFmpeg to decode HEVC into `ID3D11Texture2D`s created by the
-//! **same** device the presenter binds as shader resources and draws with — a texture from one
-//! device can't be sampled by another. So the device is created once, here, and both subsystems
-//! pull it from a process-global `OnceLock` (initialised on whichever thread asks first: the
-//! session pump when it builds the decoder, or the UI thread when it builds the presenter).
-//!
-//! **Adapter selection** (matters on hybrid boxes — e.g. an Intel iGPU driving the panel next to
-//! an NVIDIA dGPU): `PUNKTFUNK_ADAPTER` (index or case-insensitive name substring, a debugging
-//! override) wins; else the persisted Settings GPU pick ([`crate::trust::Settings::adapter`], the
-//! Settings-page selector on multi-GPU boxes); else the adapter whose output owns the monitor our
-//! window is on — that's the adapter DWM composes that monitor with, so presents are copy-free
-//! and decode runs on the near GPU; else the default adapter. Deliberately NOT "the adapter with
-//! the best decoder": if the monitor's adapter can't decode the codec we demote to software,
-//! which beats a per-frame cross-adapter present copy. The device is cached **keyed by the
-//! resolved preference**, so a Settings change takes effect at the next session (the pump and the
-//! presenter both resolve at session start and read the same value) without an app restart.
-//!
-//! `PUNKTFUNK_D3D_DEBUG=1` adds the D3D11 debug layer (validation messages in the debugger /
-//! DebugView) — invaluable for present-path bugs, which D3D11 otherwise drops silently.
-//!
-//! **Thread-safety.** windows-rs COM interfaces are deliberately `!Send`/`!Sync` — thread-safety
-//! is per-object, not universal. An `ID3D11Device` and its immediate context become free-threaded
-//! once `ID3D11Multithread::SetMultithreadProtected(TRUE)` is set, which FFmpeg's D3D11VA backend
-//! does inside `av_hwdevice_ctx_init` (it installs an `ID3D11Multithread`-based default lock when we
-//! leave `AVD3D11VADeviceContext.lock` null). The decoder then uses FFmpeg's separate
-//! `ID3D11VideoContext` for decode while the presenter uses the immediate context for draw; under
-//! multithread protection D3D serialises the two internally, and decode/draw touch disjoint context
-//! state. That makes the `unsafe impl Send + Sync` below sound for exactly this usage.
+//! Streaming (decode + present) runs in the spawned `punktfunk-session` binary; the shell only
+//! needs the list of real (hardware) adapters to offer on a multi-GPU box (a hybrid laptop or an
+//! eGPU). The picked adapter description is persisted (`crate::trust::Settings::adapter`) and read
+//! by the session child at connect (`PUNKTFUNK_ADAPTER` remains the session binary's env override).
 
-use anyhow::{anyhow, Result};
-use std::sync::{Arc, Mutex};
 use windows::core::Interface;
-use windows::Win32::Graphics::Direct3D::{
-    D3D_DRIVER_TYPE, D3D_DRIVER_TYPE_HARDWARE, D3D_DRIVER_TYPE_UNKNOWN, D3D_DRIVER_TYPE_WARP,
-    D3D_FEATURE_LEVEL_11_0, D3D_FEATURE_LEVEL_11_1,
-};
-use windows::Win32::Graphics::Direct3D11::{
-    D3D11CreateDevice, ID3D11Device, ID3D11DeviceContext, ID3D11Multithread,
-    D3D11_CREATE_DEVICE_BGRA_SUPPORT, D3D11_CREATE_DEVICE_DEBUG, D3D11_CREATE_DEVICE_FLAG,
-    D3D11_CREATE_DEVICE_VIDEO_SUPPORT, D3D11_SDK_VERSION,
-};
 use windows::Win32::Graphics::Dxgi::{CreateDXGIFactory1, IDXGIAdapter, IDXGIFactory1};
 
-pub struct SharedDevice {
-    pub device: ID3D11Device,
-    pub context: ID3D11DeviceContext,
-    /// True when this is a real GPU (hardware) adapter — a precondition for D3D11VA decode. WARP
-    /// (the GPU-less dev box) creates fine for present but cannot hardware-decode HEVC, so the
-    /// decoder skips straight to the software path there.
-    pub hardware: bool,
-}
-
-// Sound for our usage — see the module docs: the device + immediate context are free-threaded under
-// the multithread protection FFmpeg installs, and decode (video context) / present (immediate
-// context) never share mutable context state.
-unsafe impl Send for SharedDevice {}
-unsafe impl Sync for SharedDevice {}
-
-/// The shared device, cached with the GPU preference it was resolved from (empty = automatic).
-/// Re-created when the preference changes — in practice only between sessions: within one session
-/// the decoder and the presenter both call [`shared`] at session start with the same value.
-static SHARED: Mutex<Option<(String, Arc<SharedDevice>)>> = Mutex::new(None);
-
-/// The user's decode/present GPU preference: the `PUNKTFUNK_ADAPTER` env (debugging override)
-/// wins, else the persisted Settings pick; empty = automatic.
-fn adapter_pref() -> String {
-    std::env::var("PUNKTFUNK_ADAPTER")
-        .ok()
-        .map(|s| s.trim().to_string())
-        .filter(|s| !s.is_empty())
-        .unwrap_or_else(|| crate::trust::Settings::load().adapter)
-}
-
-/// The process-shared D3D11 device for the current GPU preference, created (or re-created after
-/// a preference change) on demand. `None` only if D3D11 device creation fails for both a hardware
-/// adapter and WARP (effectively never — WARP is always present).
-pub fn shared() -> Option<Arc<SharedDevice>> {
-    let pref = adapter_pref();
-    let mut cached = SHARED.lock().unwrap();
-    if let Some((key, dev)) = cached.as_ref() {
-        if *key == pref {
-            return Some(dev.clone());
-        }
-    }
-    match create_device(&pref) {
-        Ok(d) => {
-            let d = Arc::new(d);
-            *cached = Some((pref, d.clone()));
-            Some(d)
-        }
-        Err(e) => {
-            tracing::error!(error = %e, "shared D3D11 device creation failed — no present/decode");
-            None
-        }
-    }
-}
-
-/// The adapter's human-readable description, for the logs.
+/// The adapter's human-readable description.
 fn adapter_name(adapter: &IDXGIAdapter) -> String {
     unsafe {
         adapter
@@ -112,7 +22,7 @@ fn adapter_name(adapter: &IDXGIAdapter) -> String {
     }
 }
 
-/// Every DXGI adapter, in enumeration order (`PUNKTFUNK_ADAPTER=<index>` uses these indices).
+/// Every DXGI adapter, in enumeration order.
 fn all_adapters() -> Vec<IDXGIAdapter> {
     let factory: IDXGIFactory1 = match unsafe { CreateDXGIFactory1() } {
         Ok(f) => f,
@@ -144,136 +54,3 @@ pub fn adapter_names() -> Vec<String> {
         .map(adapter_name)
         .collect()
 }
-
-/// Resolve an explicit adapter: a non-empty `pref` (index or case-insensitive name substring, from
-/// env or Settings) wins; else the adapter whose output owns the monitor the app window is on (see
-/// module docs); else `None` → the default adapter (also the headless-CLI path with no window).
-fn resolve_adapter(pref: &str) -> Option<IDXGIAdapter> {
-    let adapters = all_adapters();
-
-    if !pref.is_empty() {
-        let found = if let Ok(idx) = pref.parse::<usize>() {
-            adapters.get(idx).cloned()
-        } else {
-            let needle = pref.to_lowercase();
-            adapters
-                .iter()
-                .find(|a| adapter_name(a).to_lowercase().contains(&needle))
-                .cloned()
-        };
-        match &found {
-            Some(a) => tracing::info!(pref, adapter = %adapter_name(a), "GPU preference matched"),
-            None => tracing::warn!(pref, "GPU preference matched no adapter — using automatic"),
-        }
-        if found.is_some() {
-            return found;
-        }
-    }
-
-    // The adapter driving the monitor our window sits on: DWM composes that monitor with it, so
-    // presenting from it is copy-free (a hybrid box's other adapter would pay a cross-adapter
-    // copy per frame).
-    let monitor = unsafe {
-        use windows::Win32::Graphics::Gdi::{MonitorFromWindow, MONITOR_DEFAULTTONULL};
-        use windows::Win32::UI::WindowsAndMessaging::FindWindowW;
-        let hwnd = FindWindowW(None, windows::core::w!("Punktfunk")).ok()?;
-        MonitorFromWindow(hwnd, MONITOR_DEFAULTTONULL)
-    };
-    if monitor.is_invalid() {
-        return None;
-    }
-    for adapter in &adapters {
-        let mut oi = 0u32;
-        while let Ok(output) = unsafe { adapter.EnumOutputs(oi) } {
-            oi += 1;
-            if let Ok(desc) = unsafe { output.GetDesc() } {
-                if desc.Monitor == monitor {
-                    tracing::info!(adapter = %adapter_name(adapter), "using the window's monitor adapter");
-                    return Some(adapter.clone());
-                }
-            }
-        }
-    }
-    None
-}
-
-fn create_device(pref: &str) -> Result<SharedDevice> {
-    // Preference order: the resolved adapter (or the default hardware adapter) with video support
-    // (enables D3D11VA); the same without the VIDEO flag (a driver that rejects it still presents +
-    // software-decodes); finally WARP for the GPU-less box. BGRA_SUPPORT is required for the
-    // composition swapchain in every case. An explicit adapter requires D3D_DRIVER_TYPE_UNKNOWN.
-    let adapter = resolve_adapter(pref);
-    let attempts: [(Option<&IDXGIAdapter>, D3D_DRIVER_TYPE, bool, bool); 3] = match &adapter {
-        Some(a) => [
-            (Some(a), D3D_DRIVER_TYPE_UNKNOWN, true, true),
-            (Some(a), D3D_DRIVER_TYPE_UNKNOWN, false, true),
-            (None, D3D_DRIVER_TYPE_WARP, false, false),
-        ],
-        None => [
-            (None, D3D_DRIVER_TYPE_HARDWARE, true, true),
-            (None, D3D_DRIVER_TYPE_HARDWARE, false, true),
-            (None, D3D_DRIVER_TYPE_WARP, false, false),
-        ],
-    };
-    // The debug layer needs the SDK layers installed (Graphics Tools); when they're missing the
-    // creation fails, so each attempt retries without the flag rather than failing the ladder.
-    let debug = std::env::var("PUNKTFUNK_D3D_DEBUG").is_ok_and(|v| v == "1");
-    for (adapter, driver, video, hardware) in attempts {
-        let mut flags = D3D11_CREATE_DEVICE_BGRA_SUPPORT;
-        if video {
-            flags |= D3D11_CREATE_DEVICE_VIDEO_SUPPORT;
-        }
-        let flag_sets: &[D3D11_CREATE_DEVICE_FLAG] = if debug {
-            &[flags | D3D11_CREATE_DEVICE_DEBUG, flags]
-        } else {
-            &[flags]
-        };
-        for &flags in flag_sets {
-            let mut device = None;
-            let mut context = None;
-            let r = unsafe {
-                D3D11CreateDevice(
-                    adapter,
-                    driver,
-                    None,
-                    flags,
-                    Some(&[D3D_FEATURE_LEVEL_11_1, D3D_FEATURE_LEVEL_11_0]),
-                    D3D11_SDK_VERSION,
-                    Some(&mut device),
-                    None,
-                    Some(&mut context),
-                )
-            };
-            if r.is_ok() {
-                let (device, context) = (device.unwrap(), context.unwrap());
-                // Make the device + immediate context free-threaded: the decoder (D3D11VA video
-                // context, pump thread) and the presenter (immediate context, render thread) both
-                // touch this device. FFmpeg also sets this during hwdevice init, but doing it up
-                // front keeps the cross-thread `Send`/`Sync` sound from the moment the device exists.
-                if let Ok(mt) = context.cast::<ID3D11Multithread>() {
-                    unsafe {
-                        let _ = mt.SetMultithreadProtected(true); // returns the prior state; ignore
-                    }
-                }
-                tracing::info!(
-                    adapter = %adapter.map(adapter_name).unwrap_or_else(|| if hardware {
-                        "default".into()
-                    } else {
-                        "WARP (software)".into()
-                    }),
-                    video,
-                    debug = (flags & D3D11_CREATE_DEVICE_DEBUG).0 != 0,
-                    "shared D3D11 device created"
-                );
-                return Ok(SharedDevice {
-                    device,
-                    context,
-                    hardware,
-                });
-            }
-        }
-    }
-    Err(anyhow!(
-        "D3D11CreateDevice failed for both hardware and WARP"
-    ))
-}

clients/windows/src/input.rs

@@ -1,742 +0,0 @@
-//! Stream input: Win32 low-level keyboard + mouse hooks forwarding to the host while the WinUI
-//! window is focused and the pointer is captured.
-//!
-//! windows-reactor exposes no raw key-down/up or pointer-position/wheel events (only keyboard
-//! *accelerators* and pointer button-state), which is insufficient for a game stream. So this
-//! drops below XAML to `WH_KEYBOARD_LL` / `WH_MOUSE_LL`, installed on the UI thread when the
-//! stream page mounts and removed when it unmounts.
-//!
-//! **Pointer lock.** While captured the cursor is *locked* the way a game-streaming client locks
-//! it (Moonlight/Parsec): the OS cursor is hidden + confined to the window (`ClipCursor`), and
-//! every physical move is turned into a **relative** delta (`InputKind::MouseMove`) — we read the
-//! offset from the window centre, ship it (scaled screen→host through the Contain-fit factor, with
-//! sub-pixel remainder carried so slow drags aren't lost), then warp the cursor back to centre so
-//! it never reaches a screen edge. This is why the old absolute path froze: swallowing
-//! `WM_MOUSEMOVE` pinned the OS cursor, so `pt` never travelled and the absolute coordinate
-//! snapped to one point. Keys carry the **US-positional VK** for the pressed physical key (the
-//! punktfunk wire contract shared by every first-party client — see [`scan_to_positional_vk`]):
-//! the hook's layout-resolved `vkCode` must NOT go on the wire, or a non-US pair re-maps
-//! positions through two layouts (German: y↔z swapped, ü lands on ö).
-//!
-//! **Capture state machine** (parity with the GTK/Swift clients): capture engages at stream
-//! start, **Ctrl+Alt+Shift+Q** releases it (handing the cursor back to the local desktop), and a
-//! **click on the stream** re-engages it. Losing foreground also releases the lock so the cursor
-//! is never stranded; regaining it while still captured re-locks. When "capture system
-//! shortcuts" is off in Settings, Alt+Tab / Alt+Esc / Ctrl+Esc / the Win keys act on the local
-//! desktop instead of being forwarded. **Ctrl+Alt+Shift+D disconnects** the session (consumed
-//! locally, works captured or released while our window is foreground): it trips the session's
-//! stop flag, the pump winds down, and the event loop navigates back to the host list.
-//! **Ctrl+Alt+Shift+S** toggles the stats overlay live and **F11** toggles fullscreen — both are
-//! client-local shortcuts (consumed, never forwarded), matching the GTK client's stream key set.
-
-use punktfunk_core::client::NativeClient;
-use punktfunk_core::config::Mode;
-use punktfunk_core::input::{InputEvent, InputKind};
-use std::collections::HashSet;
-use std::sync::atomic::{AtomicBool, AtomicIsize, Ordering};
-use std::sync::{Arc, Mutex};
-use windows::core::BOOL;
-use windows::Win32::Foundation::{HWND, LPARAM, LRESULT, POINT, RECT, WPARAM};
-use windows::Win32::Graphics::Gdi::ClientToScreen;
-use windows::Win32::System::LibraryLoader::GetModuleHandleW;
-use windows::Win32::UI::Input::KeyboardAndMouse::{VK_D, VK_F11, VK_Q, VK_S};
-use windows::Win32::UI::Shell::{DefSubclassProc, RemoveWindowSubclass, SetWindowSubclass};
-use windows::Win32::UI::WindowsAndMessaging::{
-    CallNextHookEx, ClipCursor, EnumChildWindows, GetClientRect, GetForegroundWindow, SetCursor,
-    SetCursorPos, SetWindowsHookExW, ShowCursor, UnhookWindowsHookEx, HC_ACTION, HHOOK,
-    KBDLLHOOKSTRUCT, LLKHF_EXTENDED, LLMHF_INJECTED, MSLLHOOKSTRUCT, WH_KEYBOARD_LL, WH_MOUSE_LL,
-    WM_KEYUP, WM_LBUTTONDOWN, WM_LBUTTONUP, WM_MBUTTONDOWN, WM_MBUTTONUP, WM_MOUSEHWHEEL,
-    WM_MOUSEMOVE, WM_MOUSEWHEEL, WM_RBUTTONDOWN, WM_RBUTTONUP, WM_SETCURSOR, WM_SYSKEYUP,
-    WM_XBUTTONDOWN, WM_XBUTTONUP,
-};
-
-struct State {
-    connector: Arc<NativeClient>,
-    mode: Mode,
-    /// The session's stop flag (Ctrl+Alt+Shift+D trips it; the pump then ends the session).
-    stop: Arc<AtomicBool>,
-    /// Our window handle, stored as the raw `isize` so `State` is `Send` (`HWND` is not).
-    hwnd: isize,
-    /// User intent: forward input to the host (toggled by Ctrl+Alt+Shift+Q / click-to-capture).
-    captured: bool,
-    /// Forward system shortcuts (Alt+Tab, Win, …) to the host; off = they act locally.
-    inhibit_shortcuts: bool,
-    /// The OS pointer is currently locked (hidden + confined + recentering). Tracks the real
-    /// `ClipCursor`/`ShowCursor` state so we engage/disengage exactly once per transition.
-    locked: bool,
-    /// Lock geometry, captured when the lock engages: the confinement rect (screen coordinates,
-    /// also the click-to-capture hit test), its centre (the cursor is warped here after every
-    /// move), and the screen→host scale (the Contain-fit display scale's inverse). Stable while
-    /// locked — the window can't be moved or resized with the cursor confined inside it.
-    clip: RECT,
-    center_x: i32,
-    center_y: i32,
-    scale: f32,
-    /// Sub-pixel remainder of the screen→host scale, carried so slow drags aren't truncated away.
-    acc_x: f32,
-    acc_y: f32,
-    /// Modifier state, tracked from the hook's own event stream (see `kbd_proc`).
-    ctrl: bool,
-    alt: bool,
-    shift: bool,
-    held_keys: HashSet<u8>,
-    held_buttons: HashSet<u32>,
-}
-
-// `State` carries no `!Send` handle (hwnd is an `isize`), so the static is sound. The hook procs
-// run on the same UI thread that installs/removes the hooks, so the lock is uncontended.
-static STATE: Mutex<Option<State>> = Mutex::new(None);
-static KBD_HOOK: AtomicIsize = AtomicIsize::new(0);
-static MOUSE_HOOK: AtomicIsize = AtomicIsize::new(0);
-/// Mirror of `State::captured` for lock-free reads off the UI thread (the HUD poll).
-static CAPTURED: AtomicBool = AtomicBool::new(false);
-/// Live stats-overlay visibility. Seeded from `Settings::show_stats` at `install`, then toggled by
-/// Ctrl+Alt+Shift+S for the session (parity with the GTK client's live `s` toggle); the HUD poll
-/// reads it lock-free to drive the overlay.
-static HUD_VISIBLE: AtomicBool = AtomicBool::new(false);
-/// Whether the pointer lock currently wants the OS cursor hidden. Read lock-free by
-/// [`cursor_subclass_proc`] (which runs on the UI thread inside `WM_SETCURSOR`) so it can override
-/// WinUI's per-move arrow re-assertion — a one-shot `ShowCursor(false)` alone loses that race
-/// because the content island re-sets the arrow every time the pointer moves.
-static CURSOR_HIDDEN: AtomicBool = AtomicBool::new(false);
-/// Our `SetWindowSubclass` id on the WinUI window + its content-island children (any stable value;
-/// scopes the subclass so install/remove target exactly our proc).
-const CURSOR_SUBCLASS_ID: usize = 0x7066_6375; // 'pfcu'
-
-/// Whether stream input is currently captured (drives the HUD's release/capture hint).
-pub fn is_captured() -> bool {
-    CAPTURED.load(Ordering::Relaxed)
-}
-
-/// Whether the stats overlay should be shown: the Settings default at stream start, then whatever
-/// Ctrl+Alt+Shift+S last set for the session. Read by the HUD poll thread.
-pub fn hud_visible() -> bool {
-    HUD_VISIBLE.load(Ordering::Relaxed)
-}
-
-/// Set the capture intent and engage/release the pointer lock to match.
-fn set_captured(st: &mut State, on: bool) {
-    st.captured = on;
-    CAPTURED.store(on, Ordering::Relaxed);
-    set_locked(st, on);
-    if !on {
-        flush_held(st); // release held keys/buttons so nothing sticks on the host
-    }
-}
-
-/// Install the hooks for a streaming session. Call from the UI thread once the window is shown.
-/// `inhibit_shortcuts` forwards system shortcuts (Alt+Tab, Win, …) to the host; off = local.
-/// `show_stats` seeds the stats-overlay visibility that Ctrl+Alt+Shift+S then toggles live.
-/// `stop` is the session's stop flag, tripped by the disconnect shortcut.
-pub fn install(
-    connector: Arc<NativeClient>,
-    mode: Mode,
-    inhibit_shortcuts: bool,
-    show_stats: bool,
-    stop: Arc<AtomicBool>,
-) {
-    HUD_VISIBLE.store(show_stats, Ordering::Relaxed);
-    let hwnd = unsafe { GetForegroundWindow() };
-    let mut st = State {
-        connector,
-        mode,
-        stop,
-        hwnd: hwnd.0 as isize,
-        captured: false,
-        inhibit_shortcuts,
-        locked: false,
-        clip: RECT::default(),
-        center_x: 0,
-        center_y: 0,
-        scale: 1.0,
-        acc_x: 0.0,
-        acc_y: 0.0,
-        ctrl: false,
-        alt: false,
-        shift: false,
-        held_keys: HashSet::new(),
-        held_buttons: HashSet::new(),
-    };
-    // Capture immediately (the window is foreground at mount, like Moonlight grabbing on stream
-    // start).
-    set_captured(&mut st, true);
-    *STATE.lock().unwrap() = Some(st);
-    unsafe {
-        let hinst = GetModuleHandleW(None).ok();
-        if let Ok(h) = SetWindowsHookExW(WH_KEYBOARD_LL, Some(kbd_proc), hinst.map(Into::into), 0) {
-            KBD_HOOK.store(h.0 as isize, Ordering::SeqCst);
-        }
-        if let Ok(h) = SetWindowsHookExW(WH_MOUSE_LL, Some(mouse_proc), hinst.map(Into::into), 0) {
-            MOUSE_HOOK.store(h.0 as isize, Ordering::SeqCst);
-        }
-    }
-    tracing::info!(
-        inhibit_shortcuts,
-        "stream input hooks installed — pointer locked (Ctrl+Alt+Shift+Q toggles capture)"
-    );
-}
-
-/// Remove the hooks, release the pointer lock, and flush any held keys/buttons (so nothing
-/// sticks down on the host).
-pub fn uninstall() {
-    unsafe {
-        let k = KBD_HOOK.swap(0, Ordering::SeqCst);
-        if k != 0 {
-            let _ = UnhookWindowsHookEx(HHOOK(k as *mut _));
-        }
-        let m = MOUSE_HOOK.swap(0, Ordering::SeqCst);
-        if m != 0 {
-            let _ = UnhookWindowsHookEx(HHOOK(m as *mut _));
-        }
-    }
-    if let Some(mut st) = STATE.lock().unwrap().take() {
-        // Hand the cursor back + flush held state.
-        set_captured(&mut st, false);
-        // Drop the WM_SETCURSOR subclass so the long-lived app window (reused for the host list
-        // once the stream ends) is left pristine — set_captured already cleared CURSOR_HIDDEN.
-        remove_cursor_subclass(HWND(st.hwnd as *mut _));
-        // Fullscreen is a streaming-only mode: if F11 put us there, drop back to a normal window
-        // so the GUI (the host list) is never left borderless-fullscreen after the stream ends.
-        exit_fullscreen(HWND(st.hwnd as *mut _));
-    }
-}
-
-/// Release every held key/button on the host, so nothing sticks down when capture is dropped
-/// (toggled off) or the session ends.
-fn flush_held(st: &mut State) {
-    let c = st.connector.clone();
-    for vk in st.held_keys.drain() {
-        send(&c, InputKind::KeyUp, vk as u32, 0, 0, 0);
-    }
-    for b in st.held_buttons.drain() {
-        send(&c, InputKind::MouseButtonUp, b, 0, 0, 0);
-    }
-}
-
-/// Subclass proc on the WinUI window + its content-island children: while the pointer lock wants
-/// the cursor hidden ([`CURSOR_HIDDEN`]), answer `WM_SETCURSOR` ourselves with `SetCursor(None)`
-/// and return TRUE — halting WinUI's default handling before it re-asserts the arrow. This is what
-/// actually keeps the cursor hidden while captured; the sibling `ShowCursor(false)` cannot, because
-/// WinUI re-sets the arrow on every pointer move (the content island answers `WM_SETCURSOR` itself,
-/// which a low-level mouse hook never sees). When not hidden, we defer to the chain untouched.
-unsafe extern "system" fn cursor_subclass_proc(
-    hwnd: HWND,
-    msg: u32,
-    wparam: WPARAM,
-    lparam: LPARAM,
-    _id: usize,
-    _ref: usize,
-) -> LRESULT {
-    if msg == WM_SETCURSOR && CURSOR_HIDDEN.load(Ordering::Relaxed) {
-        unsafe {
-            let _ = SetCursor(None);
-        }
-        return LRESULT(1); // handled — suppress the framework's arrow re-assertion
-    }
-    unsafe { DefSubclassProc(hwnd, msg, wparam, lparam) }
-}
-
-unsafe extern "system" fn subclass_install_cb(child: HWND, _l: LPARAM) -> BOOL {
-    unsafe {
-        let _ = SetWindowSubclass(child, Some(cursor_subclass_proc), CURSOR_SUBCLASS_ID, 0);
-    }
-    BOOL(1) // keep enumerating
-}
-
-unsafe extern "system" fn subclass_remove_cb(child: HWND, _l: LPARAM) -> BOOL {
-    unsafe {
-        let _ = RemoveWindowSubclass(child, Some(cursor_subclass_proc), CURSOR_SUBCLASS_ID);
-    }
-    BOOL(1)
-}
-
-/// Install [`cursor_subclass_proc`] on the top-level WinUI window and every descendant — the video
-/// is a composition SwapChainPanel, so the pointer actually sits over WinUI's internal content-
-/// island child window, which is the window that receives `WM_SETCURSOR`. `EnumChildWindows`
-/// recurses into all descendants, so one pass covers it. Idempotent (re-installing the same
-/// id+proc just refreshes it), so it's safe to call on every lock engage.
-fn install_cursor_subclass(top: HWND) {
-    unsafe {
-        let _ = SetWindowSubclass(top, Some(cursor_subclass_proc), CURSOR_SUBCLASS_ID, 0);
-        let _ = EnumChildWindows(Some(top), Some(subclass_install_cb), LPARAM(0));
-    }
-}
-
-/// Remove our subclass from the top-level window and every descendant. Called on teardown so the
-/// long-lived app window (reused for the host list after the stream ends) is left pristine.
-fn remove_cursor_subclass(top: HWND) {
-    unsafe {
-        let _ = RemoveWindowSubclass(top, Some(cursor_subclass_proc), CURSOR_SUBCLASS_ID);
-        let _ = EnumChildWindows(Some(top), Some(subclass_remove_cb), LPARAM(0));
-    }
-}
-
-/// Engage or release the pointer lock: confine + hide + recentre on, free + show on off.
-/// Guarded so the `ClipCursor`/`ShowCursor` calls stay balanced (one each per transition).
-/// Engaging captures the lock geometry (rect, centre, screen→host scale) — see `State::clip`.
-fn set_locked(st: &mut State, on: bool) {
-    if on == st.locked {
-        return;
-    }
-    let hwnd = HWND(st.hwnd as *mut _);
-    unsafe {
-        if on {
-            let mut rc = RECT::default();
-            if GetClientRect(hwnd, &mut rc).is_ok() {
-                let mut tl = POINT {
-                    x: rc.left,
-                    y: rc.top,
-                };
-                let mut br = POINT {
-                    x: rc.right,
-                    y: rc.bottom,
-                };
-                let _ = ClientToScreen(hwnd, &mut tl);
-                let _ = ClientToScreen(hwnd, &mut br);
-                st.clip = RECT {
-                    left: tl.x,
-                    top: tl.y,
-                    right: br.x,
-                    bottom: br.y,
-                };
-                let _ = ClipCursor(Some(&st.clip as *const RECT));
-                st.center_x = (tl.x + br.x) / 2;
-                st.center_y = (tl.y + br.y) / 2;
-                // Screen px → host px: the Contain-fit display scale's inverse, so the host
-                // cursor tracks the physical mouse 1:1 on screen at any window size.
-                let (ww, wh) = ((br.x - tl.x).max(1) as f32, (br.y - tl.y).max(1) as f32);
-                let (vw, vh) = (st.mode.width.max(1) as f32, st.mode.height.max(1) as f32);
-                st.scale = (ww / vw).min(wh / vh).max(0.01);
-                let _ = SetCursorPos(st.center_x, st.center_y);
-            }
-            // Hide the OS cursor. ShowCursor(false) is the coarse gate; the subclass is what
-            // actually holds it hidden against WinUI's per-move arrow re-assertion — see
-            // cursor_subclass_proc / install_cursor_subclass.
-            let _ = ShowCursor(false);
-            CURSOR_HIDDEN.store(true, Ordering::Relaxed);
-            install_cursor_subclass(hwnd);
-            st.acc_x = 0.0;
-            st.acc_y = 0.0;
-        } else {
-            CURSOR_HIDDEN.store(false, Ordering::Relaxed);
-            let _ = ClipCursor(None);
-            let _ = ShowCursor(true);
-        }
-    }
-    st.locked = on;
-}
-
-/// The pre-fullscreen window placement, saved on entering fullscreen and restored on leaving it.
-/// Module-level (not a `toggle_fullscreen`-local static) so the F11 toggle and the stream-stop exit
-/// ([`uninstall`]) share the one saved placement, and its presence is also the "are we fullscreen?"
-/// flag for [`exit_fullscreen`]. Only ever touched on the UI thread (the hook proc / the stream
-/// page's unmount), but a Mutex keeps the static sound + `Sync`.
-static SAVED_PLACEMENT: Mutex<Option<windows::Win32::UI::WindowsAndMessaging::WINDOWPLACEMENT>> =
-    Mutex::new(None);
-
-/// Whether our top-level window is currently borderless-fullscreen. Entering strips
-/// `WS_OVERLAPPEDWINDOW`, so its absence is the flag — no extra state beyond [`SAVED_PLACEMENT`].
-fn is_fullscreen(hwnd: HWND) -> bool {
-    use windows::Win32::UI::WindowsAndMessaging::{
-        GetWindowLongPtrW, GWL_STYLE, WS_OVERLAPPEDWINDOW,
-    };
-    let overlapped = WS_OVERLAPPEDWINDOW.0 as isize;
-    unsafe { GetWindowLongPtrW(hwnd, GWL_STYLE) & overlapped == 0 }
-}
-
-/// Enter borderless fullscreen: remember the window placement, drop the frame
-/// (`WS_OVERLAPPEDWINDOW`), and size the window to cover the whole monitor. windows-reactor owns
-/// the WinUI window but exposes no fullscreen API, so we drive the HWND directly (parity with the
-/// GTK client's F11). The SwapChainPanel follows the resulting `WM_SIZE` like any window resize.
-fn enter_fullscreen(hwnd: HWND) {
-    use windows::Win32::Graphics::Gdi::{
-        GetMonitorInfoW, MonitorFromWindow, MONITORINFO, MONITOR_DEFAULTTOPRIMARY,
-    };
-    use windows::Win32::UI::WindowsAndMessaging::{
-        GetWindowLongPtrW, GetWindowPlacement, SetWindowLongPtrW, SetWindowPos, GWL_STYLE,
-        SWP_FRAMECHANGED, SWP_NOOWNERZORDER, SWP_NOZORDER, WINDOWPLACEMENT, WS_OVERLAPPEDWINDOW,
-    };
-    let overlapped = WS_OVERLAPPEDWINDOW.0 as isize;
-    unsafe {
-        let style = GetWindowLongPtrW(hwnd, GWL_STYLE);
-        let mut wp = WINDOWPLACEMENT {
-            length: std::mem::size_of::<WINDOWPLACEMENT>() as u32,
-            ..Default::default()
-        };
-        let mut mi = MONITORINFO {
-            cbSize: std::mem::size_of::<MONITORINFO>() as u32,
-            ..Default::default()
-        };
-        let mon = MonitorFromWindow(hwnd, MONITOR_DEFAULTTOPRIMARY);
-        if GetWindowPlacement(hwnd, &mut wp).is_ok() && GetMonitorInfoW(mon, &mut mi).as_bool() {
-            *SAVED_PLACEMENT.lock().unwrap() = Some(wp);
-            SetWindowLongPtrW(hwnd, GWL_STYLE, style & !overlapped);
-            let r = mi.rcMonitor;
-            let _ = SetWindowPos(
-                hwnd,
-                None,
-                r.left,
-                r.top,
-                r.right - r.left,
-                r.bottom - r.top,
-                SWP_NOZORDER | SWP_NOOWNERZORDER | SWP_FRAMECHANGED,
-            );
-        }
-    }
-}
-
-/// Leave borderless fullscreen: restore the frame style and the saved placement. A no-op when we
-/// aren't fullscreen (nothing saved), so it's safe to call unconditionally on stream stop.
-fn exit_fullscreen(hwnd: HWND) {
-    use windows::Win32::UI::WindowsAndMessaging::{
-        GetWindowLongPtrW, SetWindowLongPtrW, SetWindowPlacement, SetWindowPos, GWL_STYLE,
-        SWP_FRAMECHANGED, SWP_NOMOVE, SWP_NOOWNERZORDER, SWP_NOSIZE, SWP_NOZORDER,
-        WS_OVERLAPPEDWINDOW,
-    };
-    let Some(wp) = SAVED_PLACEMENT.lock().unwrap().take() else {
-        return; // never went fullscreen — nothing to restore
-    };
-    let overlapped = WS_OVERLAPPEDWINDOW.0 as isize;
-    unsafe {
-        let style = GetWindowLongPtrW(hwnd, GWL_STYLE);
-        SetWindowLongPtrW(hwnd, GWL_STYLE, style | overlapped);
-        let _ = SetWindowPlacement(hwnd, &wp);
-        let _ = SetWindowPos(
-            hwnd,
-            None,
-            0,
-            0,
-            0,
-            0,
-            SWP_NOMOVE | SWP_NOSIZE | SWP_NOZORDER | SWP_NOOWNERZORDER | SWP_FRAMECHANGED,
-        );
-    }
-}
-
-/// Toggle borderless fullscreen for our top-level window (F11), the classic Win32 dance split into
-/// [`enter_fullscreen`] / [`exit_fullscreen`] so the stream-stop path can force windowed too.
-fn toggle_fullscreen(hwnd: isize) {
-    let hwnd = HWND(hwnd as *mut _);
-    if is_fullscreen(hwnd) {
-        exit_fullscreen(hwnd);
-    } else {
-        enter_fullscreen(hwnd);
-    }
-}
-
-fn send(c: &NativeClient, kind: InputKind, code: u32, x: i32, y: i32, flags: u32) {
-    let _ = c.send_input(&InputEvent {
-        kind,
-        _pad: [0; 3],
-        code,
-        x,
-        y,
-        flags,
-    });
-}
-
-/// System shortcuts that act on the LOCAL desktop when "capture system shortcuts" is off:
-/// the Win keys, Alt+Tab, and Alt/Ctrl+Esc.
-fn is_system_shortcut(st: &State, vk: u16) -> bool {
-    match vk {
-        0x5B | 0x5C => true,       // L/R Win
-        0x09 => st.alt,            // Alt+Tab
-        0x1B => st.alt || st.ctrl, // Alt+Esc / Ctrl+Esc
-        _ => false,
-    }
-}
-
-unsafe extern "system" fn kbd_proc(code: i32, wparam: WPARAM, lparam: LPARAM) -> LRESULT {
-    if code == HC_ACTION as i32 {
-        let kb = unsafe { &*(lparam.0 as *const KBDLLHOOKSTRUCT) };
-        let msg = wparam.0 as u32;
-        let up = msg == WM_KEYUP || msg == WM_SYSKEYUP;
-        let vk = kb.vkCode as u16;
-        let mut guard = STATE.lock().unwrap();
-        if let Some(st) = guard.as_mut() {
-            // Track modifier state from the hook's own event stream — reliable even while we
-            // swallow these keys (GetAsyncKeyState doesn't reflect keys suppressed by our own LL
-            // hook, which is why the shortcut never fired). Handles the generic + L/R vk codes.
-            match kb.vkCode {
-                0x11 | 0xA2 | 0xA3 => st.ctrl = !up,  // (L/R)CONTROL
-                0x12 | 0xA4 | 0xA5 => st.alt = !up,   // (L/R)MENU (Alt)
-                0x10 | 0xA0 | 0xA1 => st.shift = !up, // (L/R)SHIFT
-                _ => {}
-            }
-            let foreground = unsafe { GetForegroundWindow() }.0 as isize == st.hwnd;
-            if foreground {
-                // Capture toggle: Ctrl+Alt+Shift+Q (consumed locally, never forwarded).
-                if !up && vk == VK_Q.0 && st.ctrl && st.alt && st.shift {
-                    let on = !st.captured;
-                    set_captured(st, on);
-                    tracing::info!(captured = on, "capture toggled (Ctrl+Alt+Shift+Q)");
-                    return LRESULT(1);
-                }
-                // Disconnect: Ctrl+Alt+Shift+D (consumed locally). Release capture immediately so
-                // the cursor is free while the session winds down and the UI navigates home.
-                if !up && vk == VK_D.0 && st.ctrl && st.alt && st.shift {
-                    set_captured(st, false);
-                    // Deliberate user exit → close with QUIT_CLOSE_CODE so the host tears the session
-                    // down immediately instead of holding the keep-alive linger for a reconnect.
-                    st.connector.disconnect_quit();
-                    st.stop.store(true, Ordering::SeqCst);
-                    tracing::info!("disconnect requested (Ctrl+Alt+Shift+D)");
-                    return LRESULT(1);
-                }
-                // Toggle the stats overlay: Ctrl+Alt+Shift+S (consumed locally). Seeded from
-                // Settings at install; this live toggle overrides it for the session — parity
-                // with the GTK client, where `s` flips the OSD without leaving the stream.
-                if !up && vk == VK_S.0 && st.ctrl && st.alt && st.shift {
-                    let on = !HUD_VISIBLE.load(Ordering::Relaxed);
-                    HUD_VISIBLE.store(on, Ordering::Relaxed);
-                    tracing::info!(hud = on, "stats overlay toggled (Ctrl+Alt+Shift+S)");
-                    return LRESULT(1);
-                }
-                // Toggle fullscreen: F11 (consumed locally, no modifiers — a client shortcut,
-                // never a wire key). Works captured or released. The window resize changes the
-                // client rect, so re-lock to recompute the pointer confinement + recentre.
-                if !up && vk == VK_F11.0 {
-                    toggle_fullscreen(st.hwnd);
-                    if st.locked {
-                        set_locked(st, false);
-                        set_locked(st, true);
-                    }
-                    tracing::info!("fullscreen toggled (F11)");
-                    return LRESULT(1);
-                }
-                if st.captured {
-                    // With shortcut capture off, hand Alt+Tab & co. to the local desktop —
-                    // neither forwarded nor swallowed.
-                    if !st.inhibit_shortcuts && is_system_shortcut(st, vk) {
-                        return unsafe { CallNextHookEx(None, code, wparam, lparam) };
-                    }
-                    // Wire key: the US-positional VK for this physical key (module docs), derived
-                    // from the scancode. `vkCode` is layout-semantic and only passes through for
-                    // keys the table doesn't cover — extended keys and everything outside the
-                    // typing area, where positional == semantic (plus injected events with
-                    // scanCode 0 from remapping tools, best-effort).
-                    let ext = (kb.flags.0 & LLKHF_EXTENDED.0) != 0;
-                    let v = if ext {
-                        vk as u8
-                    } else {
-                        scan_to_positional_vk(kb.scanCode as u16).unwrap_or(vk as u8)
-                    };
-                    if up {
-                        if st.held_keys.remove(&v) {
-                            send(&st.connector, InputKind::KeyUp, v as u32, 0, 0, 0);
-                        }
-                    } else {
-                        st.held_keys.insert(v);
-                        send(&st.connector, InputKind::KeyDown, v as u32, 0, 0, 0);
-                    }
-                    return LRESULT(1); // swallow so it reaches the host, not the local OS
-                }
-            }
-        }
-    }
-    unsafe { CallNextHookEx(None, code, wparam, lparam) }
-}
-
-/// Whether a screen point lies inside the window's CURRENT client area (the click-to-capture
-/// hit test — computed fresh per click, since the window can move/resize while released).
-fn in_client_area(hwnd: isize, pt: POINT) -> bool {
-    let hwnd = HWND(hwnd as *mut _);
-    let mut rc = RECT::default();
-    if unsafe { GetClientRect(hwnd, &mut rc) }.is_err() {
-        return false;
-    }
-    let mut tl = POINT {
-        x: rc.left,
-        y: rc.top,
-    };
-    let mut br = POINT {
-        x: rc.right,
-        y: rc.bottom,
-    };
-    unsafe {
-        let _ = ClientToScreen(hwnd, &mut tl);
-        let _ = ClientToScreen(hwnd, &mut br);
-    }
-    pt.x >= tl.x && pt.x < br.x && pt.y >= tl.y && pt.y < br.y
-}
-
-unsafe extern "system" fn mouse_proc(code: i32, wparam: WPARAM, lparam: LPARAM) -> LRESULT {
-    if code == HC_ACTION as i32 {
-        let ms = unsafe { &*(lparam.0 as *const MSLLHOOKSTRUCT) };
-        let msg = wparam.0 as u32;
-        let injected = (ms.flags & LLMHF_INJECTED) != 0;
-        let mut guard = STATE.lock().unwrap();
-        if let Some(st) = guard.as_mut() {
-            let foreground = unsafe { GetForegroundWindow() }.0 as isize == st.hwnd;
-            let want_lock = st.captured && foreground;
-            if want_lock != st.locked {
-                set_locked(st, want_lock); // sync to focus changes (e.g. lost foreground)
-            }
-            // Click-to-capture: after a Ctrl+Alt+Shift+Q release, a primary click on the stream
-            // re-engages capture. The click is consumed — it starts the grab, it isn't gameplay.
-            if !st.captured
-                && foreground
-                && msg == WM_LBUTTONDOWN
-                && !injected
-                && in_client_area(st.hwnd, ms.pt)
-            {
-                set_captured(st, true);
-                tracing::info!("capture re-engaged (click on stream)");
-                return LRESULT(1);
-            }
-            if st.locked {
-                // Skip the synthetic move our own SetCursorPos recentre generates.
-                if injected {
-                    return unsafe { CallNextHookEx(None, code, wparam, lparam) };
-                }
-                let c = st.connector.clone();
-                match msg {
-                    WM_MOUSEMOVE => {
-                        let dx = (ms.pt.x - st.center_x) as f32;
-                        let dy = (ms.pt.y - st.center_y) as f32;
-                        if dx != 0.0 || dy != 0.0 {
-                            st.acc_x += dx / st.scale;
-                            st.acc_y += dy / st.scale;
-                            let (hx, hy) = (st.acc_x.trunc() as i32, st.acc_y.trunc() as i32);
-                            st.acc_x -= hx as f32;
-                            st.acc_y -= hy as f32;
-                            if hx != 0 || hy != 0 {
-                                send(&c, InputKind::MouseMove, 0, hx, hy, 0);
-                            }
-                        }
-                        let _ = unsafe { SetCursorPos(st.center_x, st.center_y) };
-                    }
-                    WM_LBUTTONDOWN => button(st, 1, true),
-                    WM_LBUTTONUP => button(st, 1, false),
-                    WM_RBUTTONDOWN => button(st, 3, true),
-                    WM_RBUTTONUP => button(st, 3, false),
-                    WM_MBUTTONDOWN => button(st, 2, true),
-                    WM_MBUTTONUP => button(st, 2, false),
-                    WM_XBUTTONDOWN => button(st, 3 + ((ms.mouseData >> 16) as u16 as u32), true),
-                    WM_XBUTTONUP => button(st, 3 + ((ms.mouseData >> 16) as u16 as u32), false),
-                    WM_MOUSEWHEEL => send(
-                        &c,
-                        InputKind::MouseScroll,
-                        0,
-                        (ms.mouseData >> 16) as i16 as i32,
-                        0,
-                        0,
-                    ),
-                    WM_MOUSEHWHEEL => send(
-                        &c,
-                        InputKind::MouseScroll,
-                        1,
-                        (ms.mouseData >> 16) as i16 as i32,
-                        0,
-                        0,
-                    ),
-                    _ => {}
-                }
-                return LRESULT(1); // swallow inside the locked window
-            }
-        }
-    }
-    unsafe { CallNextHookEx(None, code, wparam, lparam) }
-}
-
-fn button(st: &mut State, id: u32, down: bool) {
-    let c = st.connector.clone();
-    if down {
-        st.held_buttons.insert(id);
-        send(&c, InputKind::MouseButtonDown, id, 0, 0, 0);
-    } else if st.held_buttons.remove(&id) {
-        send(&c, InputKind::MouseButtonUp, id, 0, 0, 0);
-    }
-}
-
-/// Set-1 make scancode → US-positional VK for the layout-**variant** typing area (letters, digit
-/// row, OEM punctuation, the ISO 102nd key) — the exact inverse of the host injector's positional
-/// table and the Windows analogue of the Linux client's `evdev_to_vk`. Keys not listed (F-row,
-/// nav cluster, numpad, modifiers — plus every E0-extended key, which the caller filters out)
-/// have layout-invariant VKs, so the hook's `vkCode` is already correct for them.
-fn scan_to_positional_vk(scan: u16) -> Option<u8> {
-    Some(match scan {
-        0x02..=0x0A => (scan - 0x02) as u8 + 0x31, // 1..9
-        0x0B => 0x30,                              // 0
-        0x0C => 0xBD,                              // -_  VK_OEM_MINUS (DE: ß)
-        0x0D => 0xBB,                              // =+  VK_OEM_PLUS
-        0x10 => 0x51,                              // Q
-        0x11 => 0x57,                              // W
-        0x12 => 0x45,                              // E
-        0x13 => 0x52,                              // R
-        0x14 => 0x54,                              // T
-        0x15 => 0x59,                              // Y position (QWERTZ: the Z key)
-        0x16 => 0x55,                              // U
-        0x17 => 0x49,                              // I
-        0x18 => 0x4F,                              // O
-        0x19 => 0x50,                              // P
-        0x1A => 0xDB,                              // [{  VK_OEM_4 (DE: ü)
-        0x1B => 0xDD,                              // ]}  VK_OEM_6
-        0x1E => 0x41,                              // A
-        0x1F => 0x53,                              // S
-        0x20 => 0x44,                              // D
-        0x21 => 0x46,                              // F
-        0x22 => 0x47,                              // G
-        0x23 => 0x48,                              // H
-        0x24 => 0x4A,                              // J
-        0x25 => 0x4B,                              // K
-        0x26 => 0x4C,                              // L
-        0x27 => 0xBA,                              // ;:  VK_OEM_1 (DE: ö)
-        0x28 => 0xDE,                              // '"  VK_OEM_7 (DE: ä)
-        0x29 => 0xC0,                              // `~  VK_OEM_3 (DE: ^)
-        0x2B => 0xDC,                              // \|  VK_OEM_5
-        0x2C => 0x5A,                              // Z position (QWERTZ: the Y key)
-        0x2D => 0x58,                              // X
-        0x2E => 0x43,                              // C
-        0x2F => 0x56,                              // V
-        0x30 => 0x42,                              // B
-        0x31 => 0x4E,                              // N
-        0x32 => 0x4D,                              // M
-        0x33 => 0xBC,                              // ,<  VK_OEM_COMMA
-        0x34 => 0xBE,                              // .>  VK_OEM_PERIOD
-        0x35 => 0xBF,                              // /?  VK_OEM_2
-        0x56 => 0xE2,                              // <>| VK_OEM_102 (ISO)
-        _ => return None,
-    })
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    /// The German-scramble regression pins: the physical keys a QWERTZ board labels Z/Y/ö/ü must
-    /// leave this client as their US-position VKs, regardless of the local layout's vkCode.
-    #[test]
-    fn positional_pins_for_the_qwertz_scramble() {
-        assert_eq!(scan_to_positional_vk(0x15), Some(0x59)); // QWERTZ Z key → VK_Y (US position)
-        assert_eq!(scan_to_positional_vk(0x2C), Some(0x5A)); // QWERTZ Y key → VK_Z (US position)
-        assert_eq!(scan_to_positional_vk(0x27), Some(0xBA)); // ö key → VK_OEM_1 (US ;: position)
-        assert_eq!(scan_to_positional_vk(0x1A), Some(0xDB)); // ü key → VK_OEM_4 (US [{ position)
-        assert_eq!(scan_to_positional_vk(0x28), Some(0xDE)); // ä key → VK_OEM_7 (US '" position)
-        assert_eq!(scan_to_positional_vk(0x0C), Some(0xBD)); // ß key → VK_OEM_MINUS (US -_ position)
-    }
-
-    /// Keys outside the layout-variant typing area stay un-mapped (vkCode passes through).
-    #[test]
-    fn invariant_keys_fall_through() {
-        for scan in [
-            0x01u16, 0x0E, 0x0F, 0x1C, 0x1D, 0x2A, 0x36, 0x38, 0x39, 0x3B, 0x45, 0x57,
-        ] {
-            assert_eq!(scan_to_positional_vk(scan), None, "scan 0x{scan:02X}");
-        }
-    }
-
-    /// Exactly the 48 typing-area keys are covered (10 digits + 26 letters + 12 OEM), and every
-    /// mapping is unique — two physical keys must never collapse onto one wire VK.
-    #[test]
-    fn table_covers_the_typing_area_bijectively() {
-        let mapped: Vec<(u16, u8)> = (0u16..=0xFF)
-            .filter_map(|sc| scan_to_positional_vk(sc).map(|vk| (sc, vk)))
-            .collect();
-        assert_eq!(mapped.len(), 48);
-        let mut vks: Vec<u8> = mapped.iter().map(|&(_, vk)| vk).collect();
-        vks.sort_unstable();
-        vks.dedup();
-        assert_eq!(vks.len(), 48, "duplicate wire VK in the positional table");
-    }
-}