fix(pf-vdisplay,pf-capture,pf-win-display): pre-split paths in the auto-merged v4 code

The rename-followed perf hunks still said crate::win_display:: (the pre-W6 layout) — point them at pf_win_display::win_display:: and widen the four helpers they call cross-crate. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
fix(pf-vdisplay,pf-win-display): v4 trait surface on the extracted driver.rs + cross-crate visibility
2026-07-17 16:13:15 +02:00 · 2026-07-17 16:11:34 +02:00 · 2026-07-17 16:09:57 +02:00 · 2026-07-17 16:08:16 +02:00 · 2026-07-17 15:38:12 +02:00 · 2026-07-17 15:38:11 +02:00
885 changed files with 212039 additions and 32842 deletions
@@ -153,9 +153,9 @@ jobs:
        # `// SAFETY:` proof. Both invariants are lint-gated (`unsafe_op_in_unsafe_fn` +
        # `undocumented_unsafe_blocks`); this step keeps them from regressing. (wdk-probe is a
        # toolchain-only probe crate and is excluded.)
-        run: cargo clippy -p pf-umdf-util -p pf-xusb -p pf-dualsense -p wdk-iddcx -p pf-vdisplay --all-targets -- -D warnings
-      - name: cargo fmt --check the safe-layer + gamepad drivers
-        run: cargo fmt -p pf-umdf-util -p pf-xusb -p pf-dualsense --check
+        run: cargo clippy -p pf-umdf-util -p pf-xusb -p pf-dualsense -p pf-mouse -p wdk-iddcx -p pf-vdisplay --all-targets -- -D warnings
+      - name: cargo fmt --check the safe-layer + gamepad/mouse drivers
+        run: cargo fmt -p pf-umdf-util -p pf-xusb -p pf-dualsense -p pf-mouse --check
      - name: Inspect /INTEGRITYCHECK (before) — expect FORCE_INTEGRITY set by wdk-build
        run: |
          # explicit --target (.cargo/config.toml) -> output under the triple subdir.
@@ -38,3 +38,8 @@ CLAUDE.md
 # Local flatpak-builder output (build-flatpak.sh) — ostree repo + build dir at the repo root.
 .flatpak-repo/
 .flatpak-build/
+
+# Nix build outputs (flake.nix) — `nix build` result symlinks + direnv cache. flake.lock IS tracked.
+/result
+/result-*
+.direnv/
@@ -2145,7 +2145,7 @@ dependencies = [

 [[package]]
 name = "latency-probe"
-version = "0.11.0"
+version = "0.12.0"

 [[package]]
 name = "lazy_static"
@@ -2277,7 +2277,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"

 [[package]]
 name = "loss-harness"
-version = "0.11.0"
+version = "0.12.0"
 dependencies = [
 "punktfunk-core",
 ]
@@ -2755,10 +2755,31 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"

 [[package]]
-name = "pf-client-core"
-version = "0.11.0"
+name = "pf-capture"
+version = "0.12.0"
 dependencies = [
 "anyhow",
+ "ashpd",
+ "libc",
+ "pf-driver-proto",
+ "pf-frame",
+ "pf-gpu",
+ "pf-host-config",
+ "pf-win-display",
+ "pf-zerocopy",
+ "pipewire",
+ "punktfunk-core",
+ "tokio",
+ "tracing",
+ "windows 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "pf-client-core"
+version = "0.12.0"
+dependencies = [
+ "anyhow",
+ "ash",
 "async-channel",
 "ffmpeg-next",
 "mdns-sd",
@@ -2766,6 +2787,7 @@ dependencies = [
 "pf-ffvk",
 "pipewire",
 "punktfunk-core",
+ "pyrowave-sys",
 "rustls",
 "sdl3",
 "serde",
@@ -2776,9 +2798,26 @@ dependencies = [
 "windows 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
 ]

+[[package]]
+name = "pf-clipboard"
+version = "0.12.0"
+dependencies = [
+ "anyhow",
+ "ashpd",
+ "futures-util",
+ "libc",
+ "punktfunk-core",
+ "quinn",
+ "tokio",
+ "tracing",
+ "wayland-client",
+ "wayland-protocols",
+ "windows 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
 [[package]]
 name = "pf-console-ui"
-version = "0.11.0"
+version = "0.12.0"
 dependencies = [
 "anyhow",
 "ash",
@@ -2797,18 +2836,105 @@ dependencies = [
 "bytemuck",
 ]

+[[package]]
+name = "pf-encode"
+version = "0.12.0"
+dependencies = [
+ "anyhow",
+ "ash",
+ "ffmpeg-next",
+ "libc",
+ "libloading",
+ "nvidia-video-codec-sdk",
+ "openh264",
+ "pf-frame",
+ "pf-gpu",
+ "pf-host-config",
+ "pf-zerocopy",
+ "punktfunk-core",
+ "pyrowave-sys",
+ "tracing",
+ "tracing-subscriber",
+ "windows 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
 [[package]]
 name = "pf-ffvk"
-version = "0.11.0"
+version = "0.12.0"
 dependencies = [
 "ash",
 "bindgen",
 "pkg-config",
 ]

+[[package]]
+name = "pf-frame"
+version = "0.12.0"
+dependencies = [
+ "anyhow",
+ "libc",
+ "pf-zerocopy",
+ "punktfunk-core",
+ "tracing",
+ "windows 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "pf-gpu"
+version = "0.12.0"
+dependencies = [
+ "anyhow",
+ "pf-host-config",
+ "pf-paths",
+ "serde",
+ "serde_json",
+ "tempfile",
+ "tracing",
+ "windows 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "pf-host-config"
+version = "0.12.0"
+
+[[package]]
+name = "pf-inject"
+version = "0.12.0"
+dependencies = [
+ "anyhow",
+ "ashpd",
+ "futures-util",
+ "libc",
+ "parking_lot",
+ "pf-capture",
+ "pf-driver-proto",
+ "pf-host-config",
+ "pf-paths",
+ "punktfunk-core",
+ "reis",
+ "tokio",
+ "tracing",
+ "usbip-sim",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-protocols",
+ "wayland-protocols-misc",
+ "wayland-protocols-wlr",
+ "wayland-scanner",
+ "windows 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "xkbcommon",
+]
+
+[[package]]
+name = "pf-paths"
+version = "0.12.0"
+dependencies = [
+ "tracing",
+]
+
 [[package]]
 name = "pf-presenter"
-version = "0.11.0"
+version = "0.12.0"
 dependencies = [
 "anyhow",
 "ash",
@@ -2821,6 +2947,62 @@ dependencies = [
 "windows-sys 0.61.2",
 ]

+[[package]]
+name = "pf-vdisplay"
+version = "0.12.0"
+dependencies = [
+ "anyhow",
+ "ashpd",
+ "bytemuck",
+ "futures-util",
+ "hex",
+ "libc",
+ "pf-driver-proto",
+ "pf-encode",
+ "pf-frame",
+ "pf-gpu",
+ "pf-host-config",
+ "pf-paths",
+ "pf-win-display",
+ "punktfunk-core",
+ "serde",
+ "serde_json",
+ "sha2",
+ "tokio",
+ "tracing",
+ "utoipa",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-scanner",
+ "windows 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "pf-win-display"
+version = "0.12.0"
+dependencies = [
+ "anyhow",
+ "pf-paths",
+ "punktfunk-core",
+ "serde_json",
+ "tracing",
+ "windows 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "pf-zerocopy"
+version = "0.12.0"
+dependencies = [
+ "anyhow",
+ "ash",
+ "khronos-egl",
+ "libc",
+ "libloading",
+ "serde",
+ "serde_json",
+ "tracing",
+]
+
 [[package]]
 name = "pin-project-lite"
 version = "0.2.17"
@@ -2992,7 +3174,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-client-android"
-version = "0.11.0"
+version = "0.12.0"
 dependencies = [
 "android_logger",
 "jni",
@@ -3008,7 +3190,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-client-linux"
-version = "0.11.0"
+version = "0.12.0"
 dependencies = [
 "anyhow",
 "async-channel",
@@ -3024,7 +3206,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-client-session"
-version = "0.11.0"
+version = "0.12.0"
 dependencies = [
 "anyhow",
 "pf-client-core",
@@ -3039,7 +3221,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-client-windows"
-version = "0.11.0"
+version = "0.12.0"
 dependencies = [
 "async-channel",
 "ffmpeg-next",
@@ -3058,7 +3240,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-core"
-version = "0.11.0"
+version = "0.12.0"
 dependencies = [
 "aes-gcm",
 "bytes",
@@ -3089,7 +3271,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-host"
-version = "0.11.0"
+version = "0.12.0"
 dependencies = [
 "aes",
 "aes-gcm",
@@ -3101,9 +3283,9 @@ dependencies = [
 "base64",
 "bytemuck",
 "cbc",
- "ffmpeg-next",
 "futures-util",
 "hex",
+ "hmac",
 "http-body-util",
 "hyper",
 "hyper-util",
@@ -3114,10 +3296,20 @@ dependencies = [
 "log",
 "mac_address",
 "mdns-sd",
- "nvidia-video-codec-sdk",
- "openh264",
 "opus",
+ "parking_lot",
+ "pf-capture",
+ "pf-clipboard",
 "pf-driver-proto",
+ "pf-encode",
+ "pf-frame",
+ "pf-gpu",
+ "pf-host-config",
+ "pf-inject",
+ "pf-paths",
+ "pf-vdisplay",
+ "pf-win-display",
+ "pf-zerocopy",
 "pipewire",
 "punktfunk-core",
 "quinn",
@@ -3161,7 +3353,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-probe"
-version = "0.11.0"
+version = "0.12.0"
 dependencies = [
 "anyhow",
 "mdns-sd",
@@ -3175,21 +3367,29 @@ dependencies = [

 [[package]]
 name = "punktfunk-tray"
-version = "0.11.0"
+version = "0.12.0"
 dependencies = [
 "anyhow",
 "ksni",
 "libc",
+ "punktfunk-core",
 "rustls",
 "serde",
 "serde_json",
- "sha2",
 "ureq",
 "windows 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
 "windows-service",
 "winresource",
 ]

+[[package]]
+name = "pyrowave-sys"
+version = "0.12.0"
+dependencies = [
+ "bindgen",
+ "cmake",
+]
+
 [[package]]
 name = "quick-error"
 version = "1.2.3"
@@ -6,10 +6,22 @@ members = [
    "crates/punktfunk-host/vendor/usbip-sim",
    "crates/punktfunk-tray",
    "crates/pf-client-core",
+    "crates/pf-clipboard",
    "crates/pf-presenter",
    "crates/pf-console-ui",
    "crates/pf-ffvk",
    "crates/pf-driver-proto",
+    "crates/pf-paths",
+    "crates/pf-host-config",
+    "crates/pf-gpu",
+    "crates/pf-zerocopy",
+    "crates/pf-frame",
+    "crates/pf-win-display",
+    "crates/pf-encode",
+    "crates/pf-capture",
+    "crates/pf-inject",
+    "crates/pf-vdisplay",
+    "crates/pyrowave-sys",
    "clients/probe",
    "clients/linux",
    "clients/session",
@@ -35,7 +47,7 @@ exclude = [
 ndk = { path = "clients/android/native/vendor/ndk" }

 [workspace.package]
-version = "0.11.0"
+version = "0.12.0"
 edition = "2021"
 rust-version = "1.82"
 license = "MIT OR Apache-2.0"
@@ -27,6 +27,10 @@
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <!-- Gamepad rumble feedback. -->
    <uses-permission android:name="android.permission.VIBRATE" />
+    <!-- Steam Controller 2 over direct BLE (Sc2BleLink talks Valve's vendor GATT service to the
+         bonded pad). A RUNTIME permission (NEARBY_DEVICES group); the capture engages only when
+         already granted — USB capture (wired / Puck dongle) needs no Bluetooth at all. -->
+    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

    <!-- We target phone + TV from day one: keep the app installable on TV (no touchscreen) and on
         devices without a gamepad. -->
@@ -40,6 +44,10 @@
         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" />
+    <!-- Steam Controller 2 capture: USB host for the wired pad / Puck dongle, Bluetooth for the
+         direct-BLE pad — both optional (the feature quietly disengages without them). -->
+    <uses-feature android:name="android.hardware.usb.host" android:required="false" />
+    <uses-feature android:name="android.hardware.bluetooth_le" 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
@@ -65,10 +73,16 @@
            android:name="android.game_mode_config"
            android:resource="@xml/game_mode_config" />

+        <!-- configChanges includes `keyboard` (not just keyboardHidden): claiming a Steam
+             Controller 2's USB HID interface removes its lizard-mode keyboard/mouse input
+             devices, which flips CONFIG_KEYBOARD (QWERTY→NOKEYS) — without `keyboard` declared,
+             Android RECREATES the activity, disposing StreamScreen and killing the stream the
+             moment the capture engages (tester-diagnosed on-glass, 2026-07-15). Releasing the
+             interfaces at session end brings the devices back — same flip, same need. -->
        <activity
            android:name=".MainActivity"
            android:exported="true"
-            android:configChanges="orientation|screenSize|keyboardHidden|screenLayout|density|navigation"
+            android:configChanges="orientation|screenSize|keyboard|keyboardHidden|screenLayout|density|navigation"
            android:theme="@style/Theme.PunktfunkAndroid">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
@@ -303,7 +303,8 @@ internal fun PairPinDialog(
                            if (fp.isNotEmpty()) {
                                onPaired(fp) // verified host fp — caller saves + connects
                            } else {
-                                err = "Pairing failed — wrong PIN, or the host isn't armed."
+                                // Cause-specific: wrong PIN vs not-armed vs unreachable.
+                                err = ConnectErrors.pairMessage(NativeBridge.nativeTakeLastError())
                            }
                        }
                    }
@@ -0,0 +1,69 @@
+package io.unom.punktfunk
+
+import io.unom.punktfunk.kit.NativeBridge
+
+/**
+ * Cause-specific user-facing messages for failed pair/connect attempts, keyed on the stable
+ * machine token from [NativeBridge.nativeTakeLastError]. One vocabulary for both the PIN
+ * ceremony and the request-access (delegated approval) path, so a dead network path is never
+ * reported as "wrong PIN" and an operator denial is never reported as a timeout — the exact
+ * collapse behind more than one support thread.
+ */
+object ConnectErrors {
+    /** Message for a failed SPAKE2 PIN ceremony ([NativeBridge.nativePair] returned `""`). */
+    fun pairMessage(token: String): String = when (token) {
+        "crypto" -> "Wrong PIN — check the PIN on the host's Pairing page and try again."
+        else -> shared(token) ?: transport(token)
+    }
+
+    /**
+     * Message for a failed connect / request-access ([NativeBridge.nativeConnect] returned `0`).
+     * [requestAccess] tunes the fallback wording for the delegated-approval path.
+     */
+    fun connectMessage(token: String, requestAccess: Boolean): String =
+        shared(token) ?: when (token) {
+            "crypto" ->
+                "The host's identity doesn't match the saved fingerprint — re-pair with this host."
+            "timeout", "io", "" ->
+                if (requestAccess) {
+                    "The request never reached the host, or nobody approved it in time — " +
+                        "check the network path (no VPN, no guest-Wi-Fi isolation) and the " +
+                        "host's console."
+                } else {
+                    transport(token)
+                }
+            else -> "Connection failed — check host/port and logcat."
+        }
+
+    /** The host's typed rejection reasons — identical wording across every punktfunk client. */
+    private fun shared(token: String): String? = when (token) {
+        "not-armed" ->
+            "Pairing isn't armed on the host — arm it on the host's Pairing page, then try again."
+        "bound-other" ->
+            "The host's pairing window is armed for a different device — arm it for this one."
+        "rate-limited" -> "Too many pairing attempts — wait a couple of seconds and try again."
+        "identity-required" ->
+            "The host requires pairing — pair this device (PIN or request access) first."
+        "denied" -> "The host declined this device's request."
+        "approval-timeout" ->
+            "Nobody approved the request on the host in time — approve this device in the " +
+                "host's console or web UI, then request access again."
+        "superseded" ->
+            "A newer request from this device replaced this one — approve the latest request " +
+                "on the host."
+        "wire-version" -> "Client and host versions don't match — update both to the same release."
+        "busy" -> "The host is busy with another session."
+        else -> null
+    }
+
+    /** Transport-level causes (nothing typed arrived from the host). */
+    private fun transport(token: String): String = when (token) {
+        "timeout" ->
+            "The host didn't answer — check that this device and the host are on the same " +
+                "network (no VPN on this device, no guest-Wi-Fi / AP isolation)."
+        "io" ->
+            "Couldn't reach the host — check that this device and the host are on the same " +
+                "network (no VPN on this device, no guest-Wi-Fi / AP isolation)."
+        else -> "Pairing failed — the host didn't answer or closed the connection (see logcat)."
+    }
+}
@@ -305,13 +305,17 @@ fun ConnectScreen(
                onConnected(handle)
            } else {
                discovery.start()
-                if (onFailure != null) {
-                    // Hand off to the wake-and-wait flow — clearing `attempt` above and setting
-                    // `waker.waking` here land in one recompose, so the overlay slides
+                val token = NativeBridge.nativeTakeLastError()
+                val unreachable = token == "timeout" || token == "io" || token.isEmpty()
+                if (onFailure != null && unreachable) {
+                    // Unreachable — 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"
+                    // A typed host rejection (busy / versions differ / pairing required) means the
+                    // host is awake — waking it would be nonsense; show the stated reason instead.
+                    status = ConnectErrors.connectMessage(token, requestAccess = false)
                }
            }
        }
@@ -416,7 +420,12 @@ fun ConnectScreen(
                }
                onConnected(handle)
            } else {
-                status = "Request timed out — approve this device in the host's console, then retry."
+                // Cause-specific: an operator denial, an approval timeout, and a request that
+                // never reached the host are different problems with different fixes.
+                status = ConnectErrors.connectMessage(
+                    NativeBridge.nativeTakeLastError(),
+                    requestAccess = true,
+                )
                discovery.start()
            }
        }
@@ -1,5 +1,6 @@
 package io.unom.punktfunk

+import android.content.Context
 import android.hardware.input.InputManager
 import android.os.Build
 import android.os.CombinedVibration
@@ -44,6 +45,7 @@ import androidx.compose.ui.Modifier
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.unit.dp
 import io.unom.punktfunk.kit.Gamepad
+import io.unom.punktfunk.kit.Sc2Capture
 import kotlinx.coroutines.delay

 /**
@@ -147,8 +149,38 @@ fun ControllersScreen(gamepadSetting: Int, onBack: () -> Unit) {
    ) {
        Text("Controllers", style = MaterialTheme.typography.headlineMedium)

+        // Steam Controller 2 detection: never an InputDevice (lizard mode is kb/mouse; the
+        // capture claims even those away), so it's enumerated on the capture side — USB device
+        // list + bonded BLE — and re-checked on USB hot-plug.
+        var sc2Generation by remember { mutableIntStateOf(0) }
+        DisposableEffect(Unit) {
+            val receiver = object : android.content.BroadcastReceiver() {
+                override fun onReceive(c: Context?, i: android.content.Intent?) { sc2Generation++ }
+            }
+            val filter = android.content.IntentFilter().apply {
+                addAction(android.hardware.usb.UsbManager.ACTION_USB_DEVICE_ATTACHED)
+                addAction(android.hardware.usb.UsbManager.ACTION_USB_DEVICE_DETACHED)
+            }
+            if (Build.VERSION.SDK_INT >= 33) {
+                context.registerReceiver(receiver, filter, Context.RECEIVER_NOT_EXPORTED)
+            } else {
+                @Suppress("UnspecifiedRegisterReceiverFlag")
+                context.registerReceiver(receiver, filter)
+            }
+            onDispose { runCatching { context.unregisterReceiver(receiver) } }
+        }
+        val sc2Probe = remember { Sc2Capture(context) }
+        val sc2Usb = remember(sc2Generation) { sc2Probe.findUsbDevice() }
+        val sc2Ble = remember(sc2Generation) {
+            if (context.checkSelfPermission(android.Manifest.permission.BLUETOOTH_CONNECT) ==
+                android.content.pm.PackageManager.PERMISSION_GRANTED
+            ) sc2Probe.pairedBleAddress() else null
+        }
+        val sc2Present = sc2Usb != null || sc2Ble != null
+
        Group("Gamepads") {
-            if (pads.isEmpty()) {
+            if (sc2Present) Sc2Row(sc2Usb, activity)
+            if (pads.isEmpty() && !sc2Present) {
                Text(
                    "No controller detected. punktfunk can only forward devices Android " +
                        "classifies as a gamepad or joystick — a pad connected through an adapter " +
@@ -214,6 +246,79 @@ fun ControllersScreen(gamepadSetting: Int, onBack: () -> Unit) {
    }
 }

+/**
+ * The Steam Controller 2 card — capture-side state, since a (claimed or lizard-mode) SC2 never
+ * appears as a gamepad InputDevice. Shows the transport, whether the capture is live (driving
+ * these menus now; streamed as-is in a session), and a grant button when USB access is missing.
+ */
+@Composable
+private fun Sc2Row(usbDev: android.hardware.usb.UsbDevice?, activity: MainActivity?) {
+    val context = LocalContext.current
+    val settingOn = remember { SettingsStore(context).load().sc2Capture }
+    val active = activity?.sc2MenuActive == true
+    val usbManager = context.getSystemService(Context.USB_SERVICE) as android.hardware.usb.UsbManager
+    val permitted = usbDev != null && usbManager.hasPermission(usbDev)
+    OutlinedCard(modifier = Modifier.fillMaxWidth()) {
+        Column(
+            modifier = Modifier.padding(16.dp),
+            verticalArrangement = Arrangement.spacedBy(6.dp),
+        ) {
+            Row(modifier = Modifier.fillMaxWidth(), verticalAlignment = Alignment.CenterVertically) {
+                Text(
+                    "Steam Controller 2",
+                    style = MaterialTheme.typography.bodyLarge,
+                    modifier = Modifier.weight(1f),
+                )
+                if (active) {
+                    Text(
+                        "navigating this UI",
+                        style = MaterialTheme.typography.labelSmall,
+                        color = MaterialTheme.colorScheme.primary,
+                    )
+                }
+            }
+            Text(
+                when {
+                    usbDev == null -> "Paired via Bluetooth"
+                    usbDev.productId == io.unom.punktfunk.kit.Sc2Device.PID_WIRED -> "Wired (USB)"
+                    else -> "Puck dongle (USB)"
+                },
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+            when {
+                !settingOn -> Text(
+                    "Passthrough is disabled in Settings — enable \"Steam Controller 2 " +
+                        "passthrough\" to capture it.",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+                active -> Text(
+                    "Captured — streams as-is: the host presents a real Steam Controller 2 " +
+                        "that its Steam drives directly (trackpads, gyro, haptics).",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+                usbDev != null && !permitted -> {
+                    Text(
+                        "Needs USB access to be captured.",
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                    OutlinedButton(onClick = { activity?.startSc2MenuNav(forceAsk = true) }) {
+                        Text("Grant USB access")
+                    }
+                }
+                else -> Text(
+                    "Detected — capture engages automatically.",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+        }
+    }
+}
+
 /** One detected gamepad: identity, what it streams as, and a rumble test. */
@Composable
 private fun PadRow(dev: InputDevice, forwarded: Boolean, gamepadSetting: Int) {
@@ -389,6 +494,8 @@ private fun prefLabel(pref: Int): String = when (pref) {
    Gamepad.PREF_STEAMDECK -> "Steam Deck"
    Gamepad.PREF_DUALSENSEEDGE -> "DualSense Edge"
    Gamepad.PREF_SWITCHPRO -> "Switch Pro"
+    Gamepad.PREF_STEAMCONTROLLER2 -> "Steam Controller 2"
+    Gamepad.PREF_STEAMCONTROLLER2_PUCK -> "Steam Controller 2 Puck"
    else -> "Automatic"
 }

@@ -351,7 +351,12 @@ fun GamepadPairPinDialog(pt: PendingTrust, identity: ClientIdentity?, onPaired:
                NativeBridge.nativePair(pt.host, pt.port, id.certPem, id.privateKeyPem, pin, name)
            }
            pairing = false
-            if (fp.isNotEmpty()) onPaired(fp) else err = "Pairing failed — wrong PIN, or the host isn't armed."
+            if (fp.isNotEmpty()) {
+                onPaired(fp)
+            } else {
+                // Cause-specific: wrong PIN vs not-armed vs unreachable.
+                err = ConnectErrors.pairMessage(NativeBridge.nativeTakeLastError())
+            }
        }
    }

@@ -10,6 +10,7 @@ import android.os.Looper
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.State
+import androidx.compose.runtime.derivedStateOf
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.ui.platform.LocalContext
@@ -46,6 +47,10 @@ fun isTvDevice(context: Context): Boolean {
@Composable
 fun rememberControllerConnected(): State<Boolean> {
    val context = LocalContext.current
+    // A menu-captured Steam Controller 2 counts as connected: it drives the console UI through
+    // the capture link, but never surfaces as an Android InputDevice (lizard mode is kb/mouse,
+    // and the claim removes even those) — the InputManager path below can't see it.
+    val activity = context as? MainActivity
    val connected = remember { mutableStateOf(Gamepad.firstPad() != null) }
    DisposableEffect(Unit) {
        val im = context.getSystemService(Context.INPUT_SERVICE) as InputManager
@@ -59,5 +64,7 @@ fun rememberControllerConnected(): State<Boolean> {
        connected.value = Gamepad.firstPad() != null
        onDispose { im.unregisterInputDeviceListener(listener) }
    }
-    return connected
+    return remember {
+        derivedStateOf { connected.value || activity?.sc2MenuActive == true }
+    }
 }
@@ -1,5 +1,12 @@
 package io.unom.punktfunk

+import android.app.PendingIntent
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.content.pm.PackageManager
+import android.hardware.usb.UsbManager
 import android.os.Build
 import android.os.Bundle
 import android.view.InputDevice
@@ -21,6 +28,9 @@ import io.unom.punktfunk.kit.GamepadRouter
 import io.unom.punktfunk.kit.Keymap
 import io.unom.punktfunk.kit.NativeBridge

+/** Broadcast action for the menu-time SC2 USB-permission grant (see [MainActivity.startSc2MenuNav]). */
+private const val SC2_MENU_PERMISSION = "io.unom.punktfunk.SC2_MENU_USB_PERMISSION"
+
 class MainActivity : ComponentActivity() {
    /**
     * The active stream session handle (0 = not streaming). Set by [StreamScreen] while it's shown.
@@ -74,6 +84,30 @@ class MainActivity : ComponentActivity() {
    /** The panel's highest-refresh display mode (0 = unknown/unsupported), resolved once at startup. */
    private var highRefreshModeId = 0

+    /**
+     * Menu-time Steam Controller 2 capture (UI mode — no router): a captured SC2 never produces
+     * ordinary gamepad events (lizard mode is kb/mouse; the claim removes even those), so this
+     * drives the console UI directly from the parsed reports via [sc2NavKey]. Runs while the app
+     * is foreground and NOT streaming; StreamScreen pauses it around its own stream-mode capture.
+     * [sc2MenuActive] is observed by the console-UI gate ([rememberControllerConnected]) and the
+     * Controllers screen.
+     */
+    private var sc2Menu: io.unom.punktfunk.kit.Sc2Capture? = null
+    var sc2MenuActive by mutableStateOf(false)
+        private set
+    private var sc2Receiver: BroadcastReceiver? = null
+    private var sc2PermissionAsked = false
+
+    /**
+     * Compose focus hook for the SC2's synthetic D-pad (set by [onCreate]'s composition). A
+     * synthetic KeyEvent dispatched from OUTSIDE the real input pipeline never reaches
+     * ViewRootImpl's focus-navigation stage — the one that grants initial focus for a real
+     * pad's first D-pad press — so on a phone in touch mode it lands on a focus-less window
+     * and does nothing (first on-glass run: only B worked, since it bypasses key events
+     * entirely). `FocusManager.moveFocus` is the public API for exactly this.
+     */
+    private var sc2MoveFocus: ((androidx.compose.ui.focus.FocusDirection) -> Boolean)? = null
+
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        lastPadIsGamepad = !isTvDevice(this)
@@ -91,13 +125,166 @@ class MainActivity : ComponentActivity() {
        // UI without a physical pad — `adb shell am start -n io.unom.punktfunk/.MainActivity --ez
        // pf_force_gamepad_ui true`. Never set in normal use; real activation is a connected pad / TV.
        val forceGamepadUi = intent?.getBooleanExtra("pf_force_gamepad_ui", false) ?: false
+        // SC2 hot-plug + the menu-time USB-permission grant both (re)start the menu capture.
+        val receiver = object : BroadcastReceiver() {
+            override fun onReceive(c: Context?, intent: Intent?) {
+                when (intent?.action) {
+                    UsbManager.ACTION_USB_DEVICE_ATTACHED -> {
+                        sc2PermissionAsked = false // a fresh attach may ask once again
+                        startSc2MenuNav()
+                    }
+                    SC2_MENU_PERMISSION -> {
+                        if (intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)) {
+                            startSc2MenuNav()
+                        }
+                    }
+                }
+            }
+        }
+        sc2Receiver = receiver
+        val filter = IntentFilter().apply {
+            addAction(UsbManager.ACTION_USB_DEVICE_ATTACHED)
+            addAction(SC2_MENU_PERMISSION)
+        }
+        if (Build.VERSION.SDK_INT >= 33) {
+            registerReceiver(receiver, filter, Context.RECEIVER_NOT_EXPORTED)
+        } else {
+            @Suppress("UnspecifiedRegisterReceiverFlag")
+            registerReceiver(receiver, filter)
+        }
        setContent {
            PunktfunkTheme {
+                // Focus hook for the SC2's synthetic navigation (see [sc2MoveFocus]). `Next` is
+                // the bootstrap: directional moves need an already-focused node, while one-
+                // dimensional traversal assigns initial focus when there is none.
+                val focusManager = androidx.compose.ui.platform.LocalFocusManager.current
+                androidx.compose.runtime.DisposableEffect(Unit) {
+                    sc2MoveFocus = { dir ->
+                        focusManager.moveFocus(dir) ||
+                            focusManager.moveFocus(androidx.compose.ui.focus.FocusDirection.Next)
+                    }
+                    onDispose { sc2MoveFocus = null }
+                }
                Surface(modifier = Modifier.fillMaxSize()) { App(forceGamepadUi = forceGamepadUi) }
            }
        }
    }

+    override fun onResume() {
+        super.onResume()
+        startSc2MenuNav()
+    }
+
+    override fun onPause() {
+        // Release the claim while backgrounded so the OS (and other apps) get the pad back.
+        stopSc2MenuNav()
+        super.onPause()
+    }
+
+    override fun onDestroy() {
+        sc2Receiver?.let { runCatching { unregisterReceiver(it) } }
+        sc2Receiver = null
+        stopSc2MenuNav()
+        super.onDestroy()
+    }
+
+    /**
+     * Engage the menu-time SC2 capture if possible: setting on, not streaming, and a wired/Puck
+     * pad attached (asking for USB permission at most once per attach — [forceAsk] re-arms the
+     * dialog, for the Controllers screen's explicit grant button) — else an already-paired BLE
+     * controller when BLUETOOTH_CONNECT is granted. Safe to call repeatedly.
+     */
+    fun startSc2MenuNav(forceAsk: Boolean = false) {
+        if (forceAsk) sc2PermissionAsked = false
+        if (streamHandle != 0L) return // StreamScreen owns the pad while streaming
+        if (sc2Menu?.isActive == true) return
+        if (!SettingsStore(this).load().sc2Capture) return
+        val cap = sc2Menu ?: io.unom.punktfunk.kit.Sc2Capture(this).also { c ->
+            c.onUiKey = { key, down -> runOnUiThread { sc2NavKey(key, down) } }
+            c.onActiveChanged = { on -> runOnUiThread { sc2MenuActive = on } }
+            sc2Menu = c
+        }
+        val usbManager = getSystemService(Context.USB_SERVICE) as UsbManager
+        val dev = cap.findUsbDevice()
+        when {
+            dev != null && usbManager.hasPermission(dev) -> cap.startUsb(dev)
+            dev != null && !sc2PermissionAsked -> {
+                sc2PermissionAsked = true
+                usbManager.requestPermission(
+                    dev,
+                    PendingIntent.getBroadcast(
+                        this, 1,
+                        Intent(SC2_MENU_PERMISSION).setPackage(packageName),
+                        // MUTABLE: the USB stack appends the grant extras to this intent.
+                        PendingIntent.FLAG_MUTABLE,
+                    ),
+                )
+            }
+            dev == null && checkSelfPermission(android.Manifest.permission.BLUETOOTH_CONNECT) ==
+                PackageManager.PERMISSION_GRANTED -> {
+                cap.pairedBleAddress()?.let { cap.startBle(it) }
+            }
+        }
+    }
+
+    /** Release the menu-time SC2 capture (backgrounded / stream taking over). Idempotent. */
+    fun stopSc2MenuNav() {
+        sc2Menu?.stop()
+        sc2MenuActive = false
+    }
+
+    /**
+     * One SC2 navigation key transition from the menu-time capture (main thread) — routed the
+     * same way [dispatchKeyEvent]'s not-streaming branch routes a real pad's buttons: B backs,
+     * A activates the focused element, everything else (D-pad, shoulders, Start/Select) goes to
+     * the framework's focus navigation. Also claims the console-UI glyphs for the pad.
+     */
+    private fun sc2NavKey(keyCode: Int, down: Boolean) {
+        if (streamHandle != 0L) return // raced a stream start — the wire path owns input now
+        lastPadIsGamepad = true
+        lastPadStyle = Gamepad.PadStyle.XBOX // Valve pads carry A/B/X/Y in Xbox positions
+        val action = if (down) KeyEvent.ACTION_DOWN else KeyEvent.ACTION_UP
+        // The console UI navigates through padKeyProbe (GamepadNavEffect's held-state + repeat
+        // machinery — A/X/Y/D-pad/Select), NOT the focus system: synthesized events must be
+        // offered there first, exactly like real ones in dispatchKeyEvent (tester-diagnosed:
+        // routing everything via super.dispatchKeyEvent bypassed the probe, so only B — which
+        // never rides key events — did anything). The probes gate on keycode only, so a
+        // synthetic KeyEvent satisfies them.
+        padKeyProbe?.let { if (it(KeyEvent(action, keyCode))) return }
+        when (keyCode) {
+            // B → back, on release (same edge the real-pad path uses).
+            KeyEvent.KEYCODE_BUTTON_B -> if (!down) onBackPressedDispatcher.onBackPressed()
+            // A → activate the focused element (the focus system understands DPAD_CENTER; the
+            // Compose node focused via the moveFocus hook receives it once the ComposeView
+            // holds view-focus).
+            KeyEvent.KEYCODE_BUTTON_A ->
+                super.dispatchKeyEvent(KeyEvent(action, KeyEvent.KEYCODE_DPAD_CENTER))
+            // D-pad → Compose's own focus API (a synthetic DPAD KeyEvent can't grant initial
+            // focus — see [sc2MoveFocus]); one move per press edge.
+            KeyEvent.KEYCODE_DPAD_UP -> if (down) moveSc2Focus(androidx.compose.ui.focus.FocusDirection.Up)
+            KeyEvent.KEYCODE_DPAD_DOWN -> if (down) moveSc2Focus(androidx.compose.ui.focus.FocusDirection.Down)
+            KeyEvent.KEYCODE_DPAD_LEFT -> if (down) moveSc2Focus(androidx.compose.ui.focus.FocusDirection.Left)
+            KeyEvent.KEYCODE_DPAD_RIGHT -> if (down) moveSc2Focus(androidx.compose.ui.focus.FocusDirection.Right)
+            else -> super.dispatchKeyEvent(KeyEvent(action, keyCode))
+        }
+    }
+
+    private fun moveSc2Focus(dir: androidx.compose.ui.focus.FocusDirection) {
+        val hook = sc2MoveFocus
+        if (hook == null || !hook(dir)) {
+            // No composition hook (shouldn't happen) — fall back to the raw key dispatch.
+            super.dispatchKeyEvent(KeyEvent(KeyEvent.ACTION_DOWN, dirToKey(dir)))
+            super.dispatchKeyEvent(KeyEvent(KeyEvent.ACTION_UP, dirToKey(dir)))
+        }
+    }
+
+    private fun dirToKey(dir: androidx.compose.ui.focus.FocusDirection): Int = when (dir) {
+        androidx.compose.ui.focus.FocusDirection.Up -> KeyEvent.KEYCODE_DPAD_UP
+        androidx.compose.ui.focus.FocusDirection.Down -> KeyEvent.KEYCODE_DPAD_DOWN
+        androidx.compose.ui.focus.FocusDirection.Left -> KeyEvent.KEYCODE_DPAD_LEFT
+        else -> KeyEvent.KEYCODE_DPAD_RIGHT
+    }
+
    /** Resolve the panel's highest-refresh mode (same resolution) once, for [setConsoleHighRefreshRate]. */
    private fun resolveHighRefreshMode() {
        @Suppress("DEPRECATION")
@@ -130,9 +317,9 @@ class MainActivity : ComponentActivity() {
                if (bit != 0) {
                    // 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.
+                    // inside the router: holding it briefly (~1 s, with an on-screen hint) 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.
                    gamepadRouter?.onButton(event, bit)
                    return true // consumed
                }
@@ -1,6 +1,8 @@
 package io.unom.punktfunk

 import android.content.Context
+import android.os.Build
+import android.util.Log
 import android.view.Display

 /**
@@ -90,6 +92,15 @@ data class Settings(
     * toggle is hidden on devices without a vibrator (TVs), where this would be a silent no-op.
     */
    val rumbleOnPhone: Boolean = false,
+
+    /**
+     * Capture a Steam Controller 2 (wired / Puck dongle over USB, or an already-paired BLE pad)
+     * and pass it through AS-IS: the host presents a real `28DE:1302` that its Steam drives
+     * directly (Linux hosts). ON by default — it engages only when such a controller is actually
+     * present at stream start, so it costs nothing otherwise; the toggle exists for the rare
+     * setup where the OS-level pad (lizard mode) is preferred.
+     */
+    val sc2Capture: Boolean = true,
 )

 /** [Settings.touchMode] values; persisted by name. */
@@ -151,6 +162,7 @@ class SettingsStore(context: Context) {
        lowLatencyMode = prefs.getBoolean(K_LOW_LATENCY, true),
        autoWakeEnabled = prefs.getBoolean(K_AUTO_WAKE, true),
        rumbleOnPhone = prefs.getBoolean(K_RUMBLE_ON_PHONE, false),
+        sc2Capture = prefs.getBoolean(K_SC2_CAPTURE, true),
    )

    fun save(s: Settings) {
@@ -172,6 +184,7 @@ class SettingsStore(context: Context) {
            .putBoolean(K_LOW_LATENCY, s.lowLatencyMode)
            .putBoolean(K_AUTO_WAKE, s.autoWakeEnabled)
            .putBoolean(K_RUMBLE_ON_PHONE, s.rumbleOnPhone)
+            .putBoolean(K_SC2_CAPTURE, s.sc2Capture)
            .apply()
    }

@@ -208,6 +221,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"
+        const val K_SC2_CAPTURE = "sc2_capture"

        /** Legacy Boolean the enum replaced — read once as the migration default, never written. */
        const val K_TRACKPAD = "trackpad_mode"
@@ -237,11 +251,25 @@ fun nativeDisplayMode(context: Context): Triple<Int, Int, Int> {
 */
 fun displaySupportsHdr(context: Context): Boolean {
    val display = runCatching { context.display }.getOrNull() ?: return false
-    @Suppress("DEPRECATION") // hdrCapabilities is the supported query on minSdk 31
-    val caps = display.hdrCapabilities ?: return false
-    return caps.supportedHdrTypes.any {
+    val types = buildSet {
+        // API 34+: the sanctioned per-mode query (Display.Mode.getSupportedHdrTypes). The
+        // deprecated Display-level hdrCapabilities can return EMPTY on Android 14+ devices
+        // (Pixel-class panels included), which would make a genuinely HDR display advertise
+        // no-HDR and pin the whole session to 8-bit SDR.
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+            display.mode.supportedHdrTypes.forEach { add(it) }
+        }
+        // Union the legacy query defensively — the supported one on minSdk 31, and some vendors
+        // populate only this on newer APIs.
+        @Suppress("DEPRECATION")
+        display.hdrCapabilities?.supportedHdrTypes?.forEach { add(it) }
+    }
+    // HDR10/HDR10+ only: the stream is BT.2020 PQ — a Dolby-Vision/HLG-only panel can't present it.
+    val supported = types.any {
        it == Display.HdrCapabilities.HDR_TYPE_HDR10 || it == Display.HdrCapabilities.HDR_TYPE_HDR10_PLUS
    }
+    Log.i("punktfunk", "display HDR types=$types → advertise HDR10=$supported")
+    return supported
 }

 /** Resolve [Settings] (with its 0=native placeholders) to the concrete mode to request. */
@@ -426,6 +426,14 @@ private fun ControlsSettings(s: Settings, update: (Settings) -> Unit, onOpenCont
                checked = s.rumbleOnPhone,
                onCheckedChange = { on -> update(s.copy(rumbleOnPhone = on)) },
            )
+            ToggleRow(
+                title = "Steam Controller 2 passthrough",
+                subtitle = "Capture a Steam Controller 2 (wired, Puck dongle, or paired " +
+                    "Bluetooth): it navigates these menus and streams as-is — Steam on the " +
+                    "host drives it like the physical pad (trackpads, gyro, haptics)",
+                checked = s.sc2Capture,
+                onCheckedChange = { on -> update(s.copy(sc2Capture = on)) },
+            )
        }
    }
 }
@@ -39,6 +39,7 @@ internal fun StatsOverlay(
    s: DoubleArray,
    verbosity: StatsVerbosity,
    decoderLabel: String = "",
+    codecLabel: String = "",
    modifier: Modifier = Modifier,
 ) {
    if (verbosity == StatsVerbosity.OFF || s.size < 10) return
@@ -66,7 +67,7 @@ internal fun StatsOverlay(
            statLine(decoderLabel, Color(0xFFB0D0FF))
        }
        if (detailed) {
-            videoFeedLine(s)?.let { statLine(it, Color.White) }
+            videoFeedLine(s, codecLabel)?.let { statLine(it, Color.White) }
        }
        if (latValid) {
            // Display stage (s[22]–s[25], from OnFrameRendered): when a render timestamp landed
@@ -151,14 +152,15 @@ private fun counterLine(s: DoubleArray, lostTotal: Long): String? {
 }

 /**
- * Format the negotiated video-feed descriptor from the trailing four stats doubles
- * `[bitDepth, colorPrimaries, colorTransfer, chromaFormatIdc]`, e.g.
- * `HEVC · 10-bit · HDR (BT.2020 PQ) · 4:2:0`. Returns `null` on a pre-video-feed layout (< 14 doubles)
+ * Format the negotiated video-feed descriptor from [codecLabel] plus the trailing four stats
+ * doubles `[bitDepth, colorPrimaries, colorTransfer, chromaFormatIdc]`, e.g.
+ * `AV1 · 10-bit · HDR (BT.2020 PQ) · 4:2:0`. Returns `null` on a pre-video-feed layout (< 14 doubles)
 * so the overlay simply omits the line. The codes are CICP / H.273: transfer 16 = PQ, 18 = HLG (else
- * SDR); primaries 9 = BT.2020, 1 = BT.709; chroma_format_idc 1 = 4:2:0, 2 = 4:2:2, 3 = 4:4:4. The
- * Android decoder is always HEVC (`video/hevc`).
+ * SDR); primaries 9 = BT.2020, 1 = BT.709; chroma_format_idc 1 = 4:2:0, 2 = 4:2:2, 3 = 4:4:4.
+ * [codecLabel] is the host-resolved codec (`nativeVideoCodecLabel`); a blank one falls back to
+ * `HEVC` (the pre-negotiation default) for the brief window before it's resolved.
 */
-private fun videoFeedLine(s: DoubleArray): String? {
+private fun videoFeedLine(s: DoubleArray, codecLabel: String): String? {
    if (s.size < 14) return null
    val bitDepth = s[10].toInt()
    val primaries = s[11].toInt()
@@ -175,5 +177,6 @@ private fun videoFeedLine(s: DoubleArray): String? {
        2 -> "4:2:2"
        else -> "4:2:0"
    }
-    return "HEVC · $depthLabel · $dynamicRange ($colorSpace) · $chromaLabel"
+    val codec = codecLabel.ifEmpty { "HEVC" }
+    return "$codec · $depthLabel · $dynamicRange ($colorSpace) · $chromaLabel"
 }
@@ -1,9 +1,14 @@
 package io.unom.punktfunk

 import android.Manifest
+import android.app.PendingIntent
+import android.content.BroadcastReceiver
 import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
 import android.content.pm.ActivityInfo
 import android.content.pm.PackageManager
+import android.hardware.usb.UsbManager
 import android.net.wifi.WifiManager
 import android.os.Build
 import android.text.InputType
@@ -18,10 +23,13 @@ import android.view.inputmethod.InputConnection
 import android.view.inputmethod.InputMethodManager
 import android.widget.Toast
 import androidx.activity.compose.BackHandler
+import androidx.compose.foundation.background
 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.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.LaunchedEffect
@@ -31,9 +39,11 @@ import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.input.pointer.pointerInput
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
 import androidx.compose.ui.viewinterop.AndroidView
 import androidx.core.content.ContextCompat
 import androidx.core.view.WindowCompat
@@ -43,6 +53,7 @@ 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.Sc2Capture
 import io.unom.punktfunk.kit.VideoDecoders
 import java.util.concurrent.atomic.AtomicBoolean
 import kotlinx.coroutines.delay
@@ -73,6 +84,7 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
    val initialSettings = remember { SettingsStore(context).load() }
    var stats by remember { mutableStateOf<DoubleArray?>(null) }
    var decoderLabel by remember { mutableStateOf("") }
+    var codecLabel by remember { mutableStateOf("") }
    var statsVerbosity by remember { mutableStateOf(initialSettings.statsVerbosity) }
    val statsOn = statsVerbosity != StatsVerbosity.OFF
    // Touch model is fixed per session (re-keys the gesture handler below if it ever changes).
@@ -88,6 +100,9 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
    LaunchedEffect(handle, statsOn) {
        NativeBridge.nativeSetVideoStatsEnabled(handle, statsOn)
        if (statsOn) {
+            // Codec is resolved at the handshake (Welcome) — fixed for the session, so read its
+            // label once up front (before the first snapshot renders the video-feed line).
+            if (codecLabel.isEmpty()) codecLabel = NativeBridge.nativeVideoCodecLabel(handle)
            while (true) {
                delay(1000)
                stats = NativeBridge.nativeVideoStats(handle)
@@ -157,6 +172,10 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
        }.onEach { it.setReferenceCounted(false) }
    }

+    // True while the gamepad exit chord (Select+Start+L1+R1) is held and counting down — drives the
+    // "hold to quit" hint overlay. Set from the router's onExitArmed (main thread).
+    var exitArming by remember { mutableStateOf(false) }
+
    DisposableEffect(handle) {
        window?.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
        wifiLocks.forEach { lock ->
@@ -199,6 +218,9 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
        // the same way the Back gesture does.
        activity?.requestStreamExit = { NativeBridge.nativeDisconnectQuit(handle); onDisconnect() }
        router.onExitChord = { activity?.requestStreamExit?.invoke() }
+        // Show a "hold to quit" hint the moment the chord completes (the router debounces the actual
+        // exit); it clears when the buttons release early or the hold elapses. Runs on the main thread.
+        router.onExitArmed = { armed -> exitArming = armed }
        activity?.setConsoleHighRefreshRate(false) // let the decoder's setFrameRate pick the panel rate
        // 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
@@ -212,13 +234,69 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
        // 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
+        // Steam Controller 2 as-is passthrough (opt-out): capture a wired/Puck USB pad — or an
+        // already-paired BLE one — and forward its raw reports; the host mirrors a real
+        // 28DE:1302 that its Steam drives directly, and Steam's rumble/settings writes come back
+        // through feedback.onHidRaw onto the physical controller. Engages only when such a pad is
+        // actually present; the wire slot is claimed lazily on its first state report.
+        // The menu-time capture (UI navigation) must let go before the stream-mode capture can
+        // claim the interfaces; it resumes in onDispose once the stream releases them.
+        activity?.stopSc2MenuNav()
+        val sc2 = if (initialSettings.sc2Capture) Sc2Capture(context, router) else null
+        var sc2UsbReceiver: BroadcastReceiver? = null
+        if (sc2 != null) {
+            feedback.onHidRaw = sc2::onHidRaw
+            val usbManager = context.getSystemService(Context.USB_SERVICE) as UsbManager
+            val usbDev = sc2.findUsbDevice()
+            when {
+                usbDev != null && usbManager.hasPermission(usbDev) -> sc2.startUsb(usbDev)
+                usbDev != null -> {
+                    // One-time system dialog; capture engages on grant (Android remembers the
+                    // grant for as long as the device stays attached).
+                    val action = "io.unom.punktfunk.SC2_USB_PERMISSION"
+                    val receiver = object : BroadcastReceiver() {
+                        override fun onReceive(c: Context?, intent: Intent?) {
+                            if (intent?.action != action) return
+                            val ok = intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)
+                            if (ok) sc2.startUsb(usbDev) else Log.i("punktfunk", "SC2 USB permission denied")
+                        }
+                    }
+                    sc2UsbReceiver = receiver
+                    ContextCompat.registerReceiver(
+                        context, receiver, IntentFilter(action), ContextCompat.RECEIVER_NOT_EXPORTED,
+                    )
+                    usbManager.requestPermission(
+                        usbDev,
+                        PendingIntent.getBroadcast(
+                            context, 0,
+                            Intent(action).setPackage(context.packageName),
+                            // MUTABLE: the USB stack appends the grant extras to this intent.
+                            PendingIntent.FLAG_MUTABLE,
+                        ),
+                    )
+                }
+                ContextCompat.checkSelfPermission(context, Manifest.permission.BLUETOOTH_CONNECT) ==
+                    PackageManager.PERMISSION_GRANTED -> {
+                    sc2.pairedBleAddress()?.let { addr ->
+                        Log.i("punktfunk", "SC2: no USB pad — using the paired BLE controller $addr")
+                        sc2.startBle(addr)
+                    }
+                }
+            }
+        }
        onDispose {
            closed.set(true) // from here the handle gets freed; surfaceDestroyed must not touch it
+            feedback.onHidRaw = null
            feedback.stop() // stop + join the poll threads BEFORE the router is released / handle freed
+            sc2UsbReceiver?.let { runCatching { context.unregisterReceiver(it) } }
+            sc2?.stop() // release the USB/BLE link + free the wire slot (host tears the pad down)
+            router.onExitArmed = null // don't poke Compose state from release()'s disarm while tearing down
            router.release() // flush every slot (nothing sticks host-side) + drop the hot-plug listener
            activity?.gamepadRouter = null
            activity?.streamHandle = 0L
            activity?.requestStreamExit = null
+            // Back in the menus: the SC2 (if present) resumes driving the console UI.
+            activity?.startSc2MenuNav()
            activity?.setConsoleHighRefreshRate(true) // back to the console UI's max refresh
            controller?.hide(WindowInsetsCompat.Type.ime()) // drop any keyboard left showing
            window?.setSoftInputMode(priorSoftInput)
@@ -292,9 +370,15 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
        // BEFORE the transparent gesture layer below, so it shows through and never eats touches.
        if (statsOn) {
            stats?.let {
-                StatsOverlay(it, statsVerbosity, decoderLabel, Modifier.align(Alignment.TopStart).padding(12.dp))
+                StatsOverlay(it, statsVerbosity, decoderLabel, codecLabel, Modifier.align(Alignment.TopStart).padding(12.dp))
            }
        }
+        // "Hold to quit" hint while the gamepad exit chord is armed — the exit debounces on a ~1 s
+        // hold, so without this cue a couch user reads the (deliberately no-longer-instant) chord as
+        // broken. Purely visual; it sits above the video and below the gesture layer.
+        if (exitArming) {
+            ExitChordHint(Modifier.align(Alignment.TopCenter).padding(top = 16.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(
@@ -321,6 +405,24 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
    }
 }

+/**
+ * The "hold to quit" cue shown while the gamepad exit chord (Select + Start + L1 + R1) is held. The
+ * chord no longer quits on a quick press — the router debounces it on a ~1 s hold — so this confirms
+ * the press registered and tells the user to keep holding. Purely visual; [GamepadRouter.onExitArmed]
+ * toggles its visibility.
+ */
+@Composable
+private fun ExitChordHint(modifier: Modifier = Modifier) {
+    Text(
+        "Hold to quit…",
+        modifier = modifier
+            .background(Color.Black.copy(alpha = 0.55f), RoundedCornerShape(8.dp))
+            .padding(horizontal = 14.dp, vertical = 8.dp),
+        color = Color.White,
+        fontSize = 15.sp,
+    )
+}
+
 /**
 * 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
@@ -214,6 +214,7 @@ internal fun StreamScene(verbosity: StatsVerbosity = StatsVerbosity.DETAILED) {
            ),
            verbosity = verbosity,
            decoderLabel = "c2.qti.hevc.decoder · low-latency",
+            codecLabel = "HEVC",
            modifier = Modifier.align(Alignment.TopStart).padding(12.dp),
        )
    }
@@ -36,6 +36,16 @@ object Gamepad {
    const val BTN_X = 0x4000
    const val BTN_Y = 0x8000

+    // Extended bits (Moonlight `buttonFlags2 << 16` namespace — `input.rs::gamepad`): the four
+    // back grips (Steam L4/L5/R4/R5 ≙ Elite P1–P4), touchpad click, and the misc/QAM button.
+    // Android's standard InputDevice path never produces these; the SC2 capture link does.
+    const val BTN_PADDLE1 = 0x10000
+    const val BTN_PADDLE2 = 0x20000
+    const val BTN_PADDLE3 = 0x40000
+    const val BTN_PADDLE4 = 0x80000
+    const val BTN_TOUCHPAD = 0x100000
+    const val BTN_MISC1 = 0x200000
+
    // Axis ids — must equal `input.rs::gamepad::AXIS_*`.
    const val AXIS_LS_X = 0
    const val AXIS_LS_Y = 1
@@ -54,6 +64,8 @@ object Gamepad {
    const val PREF_STEAMDECK = 6
    const val PREF_DUALSENSEEDGE = 7
    const val PREF_SWITCHPRO = 8
+    const val PREF_STEAMCONTROLLER2 = 9
+    const val PREF_STEAMCONTROLLER2_PUCK = 10

    // USB vendor ids of the controllers we can identify by VID/PID.
    private const val VID_SONY = 0x054C
@@ -81,6 +93,12 @@ object Gamepad {
    private val PID_STEAMDECK = setOf(0x1205)
    private val PID_STEAMCONTROLLER = setOf(0x1102, 0x1142)

+    // Steam Controller 2: wired (0x1302), BLE (0x1303), and Puck dongles (0x1304/0x1305).
+    // Sc2Capture normally claims these directly; the plain InputDevice path is only a degraded
+    // fallback. Keep Puck distinct so even that path requests the native multi-interface identity.
+    private val PID_STEAMCONTROLLER2 = setOf(0x1302, 0x1303)
+    private val PID_STEAMCONTROLLER2_PUCK = setOf(0x1304, 0x1305)
+
    // Microsoft Xbox One / Series product ids (wired + the common Bluetooth/dongle revisions). All
    // behave like Xbox 360 on the host minus the glyph identity, so they share one pref byte.
    private val PID_XBOXONE = setOf(
@@ -107,6 +125,9 @@ object Gamepad {
            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_VALVE && pid in PID_STEAMCONTROLLER2_PUCK ->
+                PREF_STEAMCONTROLLER2_PUCK
+            vid == VID_VALVE && pid in PID_STEAMCONTROLLER2 -> PREF_STEAMCONTROLLER2
            vid == VID_NINTENDO && pid in PID_SWITCHPRO -> PREF_SWITCHPRO
            else -> PREF_XBOX360
        }
@@ -51,9 +51,7 @@ class GamepadFeedback(
        const val TAG_LED: Byte = 0x01
        const val TAG_PLAYER_LEDS: Byte = 0x02
        const val TAG_TRIGGER: Byte = 0x03
-        // Fallback one-shot duration against a legacy host (no v2 TTL lease): the prior fixed value.
-        // A new host renews far below this, so it never actually holds this long there.
-        const val LEGACY_RUMBLE_MS = 60_000L
+        const val TAG_HID_RAW: Byte = 0x05
    }

    /** One controller's rumble binding — VibratorManager (API 31+) OR the legacy single Vibrator (API 28–30). */
@@ -94,25 +92,26 @@ class GamepadFeedback(
            while (running) {
                val ev = NativeBridge.nativeNextRumble(handle)
                if (ev < 0L) continue // timeout / closed
-                // 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.
+                // ev bits 49..52 = wire pad index; bits 32..47 = backstop duration (ms);
+                // 16..31 = low; 0..15 = high. These are EFFECTIVE commands from the core's shared
+                // rumble policy engine — it owns every lease/staleness/close decision (uniform
+                // across all clients; the old 60 s legacy-host exposure is gone) and emits
+                // explicit zeros, so apply verbatim: (0, 0) = cancel, non-zero = one-shot for
+                // the backstop (the hardware net under a stalled poll thread).
                val pad = ((ev ushr 49) and 0xFL).toInt()
-                val 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
+                val backstopMs = ((ev ushr 32) and 0xFFFF)
                renderRumble(
                    pad,
                    ((ev ushr 16) and 0xFFFF).toInt(),
                    (ev and 0xFFFF).toInt(),
-                    durationMs,
+                    backstopMs,
                )
            }
        }, "pf-rumble").apply { isDaemon = true; start() }

        hidoutThread = Thread({
-            val buf = ByteBuffer.allocateDirect(64)
+            // 128: the raw as-is passthrough events are [pad][kind tag][report kind][≤64 bytes].
+            val buf = ByteBuffer.allocateDirect(128)
            while (running) {
                val n = NativeBridge.nativeNextHidout(handle, buf)
                if (n < 0) continue // timeout / closed
@@ -210,12 +209,13 @@ class GamepadFeedback(

    /**
     * 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].
+     * addressed to wire pad [pad]. `durationMs` is the engine command's backstop — the one-shot's
+     * self-termination net under a stalled poll thread; the engine emits explicit zero commands at
+     * every policy stop (lease expiry, legacy staleness, session close), so cancel-on-zero is the
+     * real stop mechanism.
     */
    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
+        Log.i(TAG, "rumble pad=$pad low=$low high=$high backstopMs=$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
@@ -331,10 +331,32 @@ class GamepadFeedback(
                    "hidout pad=$pad Trigger which=$which effLen=$effLen mode=0x%02x (adaptive triggers unsupported on Android)".format(mode),
                )
            }
+            TAG_HID_RAW -> {
+                // As-is SC2 passthrough: a raw report the host's Steam wrote to the virtual pad —
+                // [kind: 0=output, 1=feature][report bytes, id first]. Handed to the capture link
+                // for verbatim replay on the physical controller; dropped when no link owns the pad.
+                val kind = buf.get().toInt() and 0xFF
+                val len = n - 3
+                if (len > 0) {
+                    val data = ByteArray(len)
+                    buf.get(data)
+                    onHidRaw?.invoke(pad, kind, data)
+                }
+            }
            else -> Log.d(TAG, "hidout: unknown kind, dropped")
        }
    }

+    /**
+     * Raw HID-report replay hook for the as-is Steam Controller 2 passthrough: invoked (on the
+     * hidout poll thread) with the wire pad index, the report kind (0 = output report, 1 =
+     * feature report), and the full report bytes (id first) the host's hidraw consumer wrote.
+     * `StreamScreen` wires this to the SC2 capture so Steam's rumble/settings land on the
+     * physical controller.
+     */
+    @Volatile
+    var onHidRaw: ((pad: Int, kind: Int, data: ByteArray) -> Unit)? = null
+
    /** hid-playstation 5-LED pattern → player index 1..4 (0 = off); falls back to a bit count. */
    private fun playerIndexForBits(bits: Int): Int = when (bits and 0x1F) {
        0b00000 -> 0
@@ -57,6 +57,14 @@ class GamepadRouter(context: Context, private val handle: Long, private val sett
     */
    var onExitChord: (() -> Unit)? = null

+    /**
+     * Invoked (main thread) with `true` the moment the exit chord completes and the hold countdown
+     * starts, and `false` when it's cancelled (a button lifted early) or the timer elapses. `StreamScreen`
+     * wires this to a "hold to quit" hint so the hold is discoverable — the chord no longer quits on a
+     * quick press, and without an on-screen cue that reads as the shortcut being broken.
+     */
+    var onExitArmed: ((armed: Boolean) -> 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
@@ -84,28 +92,37 @@ class GamepadRouter(context: Context, private val handle: Long, private val sett
     * 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.
+     * Start + L1 + R1) on any one pad ARMS a [EXIT_HOLD_MS] hold timer rather than leaving instantly
+     * ([onExitArmed] fires so the UI can show a "hold to quit" hint); [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()
-                }
+            // repeatCount guard: don't re-send a held button as auto-repeat.
+            KeyEvent.ACTION_DOWN -> slotButton(slot, bit, down = true, send = event.repeatCount == 0)
+            KeyEvent.ACTION_UP -> slotButton(slot, bit, down = false, send = true)
+        }
+    }
+
+    /**
+     * One button transition on [slot] — the shared body behind [onButton] and an [ExternalPad]'s
+     * transitions: forward the wire event, track held state, and arm/disarm the exit chord.
+     */
+    private fun slotButton(slot: Slot, bit: Int, down: Boolean, send: Boolean) {
+        if (down) {
+            if (send) 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()
+        } else {
+            if (send) 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()
            }
        }
    }
@@ -115,6 +132,7 @@ class GamepadRouter(context: Context, private val handle: Long, private val sett
        if (pendingExit != null) return // already counting down
        val r = Runnable {
            pendingExit = null
+            onExitArmed?.invoke(false) // countdown over — drop the hint whether or not we leave
            // 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()) {
@@ -126,12 +144,15 @@ class GamepadRouter(context: Context, private val handle: Long, private val sett
        }
        pendingExit = r
        mainHandler.postDelayed(r, EXIT_HOLD_MS)
+        onExitArmed?.invoke(true) // chord complete → show the "hold to quit" hint
    }

    /** Cancel a pending exit-chord hold timer. */
    private fun disarmExit() {
+        val wasArmed = pendingExit != null
        pendingExit?.let { mainHandler.removeCallbacks(it) }
        pendingExit = null
+        if (wasArmed) onExitArmed?.invoke(false) // released early — drop the hint
    }

    /**
@@ -152,8 +173,9 @@ class GamepadRouter(context: Context, private val handle: Long, private val sett

    /**
     * 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.
+     * holds no live slot (a pad that just unplugged — the update is then dropped) OR the slot is
+     * an [ExternalPad] (its synthetic id resolves to no InputDevice, so rumble binds naturally
+     * fall through to the capture link's own feedback path). Read from the feedback poll threads.
     */
    fun deviceForPad(pad: Int): InputDevice? {
        for ((deviceId, slot) in slots) {
@@ -162,6 +184,50 @@ class GamepadRouter(context: Context, private val handle: Long, private val sett
        return null
    }

+    /**
+     * A capture-link pad occupying a wire slot without an Android [InputDevice] — the as-is Steam
+     * Controller 2 passthrough (USB/BLE claimed directly, invisible to the input stack). Shares
+     * the real slots' lifecycle: a stable lowest-free index, Arrival-before-input, held-state
+     * flush + Remove on [close], and full participation in the emergency exit chord.
+     */
+    inner class ExternalPad internal constructor(private val syntheticId: Int, val index: Int) {
+        // Live lookup instead of a captured reference: after [close] (or a router release) the
+        // slot is gone from the table and every entry point below degrades to a safe no-op.
+        private val slot get() = slots[syntheticId]
+
+        /** One button transition (a wire [Gamepad].BTN_* bit). On-change only — the caller diffs. */
+        fun button(bit: Int, down: Boolean) {
+            slot?.let { slotButton(it, bit, down, send = true) }
+        }
+
+        /** One axis update ([Gamepad].AXIS_*: stick i16 +y=up / trigger 0..255). On-change only. */
+        fun axis(id: Int, value: Int) {
+            if (slot != null) NativeBridge.nativeSendGamepadAxis(handle, id, value, index)
+        }
+
+        /** One raw HID report, forwarded verbatim for the host's as-is virtual pad. */
+        fun hidReport(buf: java.nio.ByteBuffer, len: Int) {
+            if (slot != null) NativeBridge.nativeSendPadHidReport(handle, index, buf, len)
+        }
+
+        /** Flush held state, signal the removal, and free the wire index. Idempotent. */
+        fun close() = closeSlot(syntheticId)
+    }
+
+    /**
+     * Open a slot for a capture-link pad, declaring [pref] as its kind; null when all 16 wire
+     * indices are taken. Main thread (like the hot-plug callbacks).
+     */
+    fun openExternal(pref: Int): ExternalPad? {
+        val index = lowestFreeIndex() ?: return null
+        // Synthetic ids live below any real InputDevice id (those are positive), so they can't
+        // collide and InputDevice.getDevice(id) resolves them to null for the feedback path.
+        val syntheticId = EXTERNAL_ID_BASE - index
+        NativeBridge.nativeSendGamepadArrival(handle, pref, index)
+        slots[syntheticId] = Slot(index, Gamepad.AxisMapper(handle, index))
+        return ExternalPad(syntheticId, index)
+    }
+
    /**
     * Flush + drop every slot and unregister the hot-plug listener. Call on session teardown, AFTER
     * the feedback poll threads are joined (they read [deviceForPad]).
@@ -250,7 +316,14 @@ class GamepadRouter(context: Context, private val handle: Long, private val sett
        /** 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
+        /**
+         * How long the exit chord must be held before the stream leaves — long enough that an
+         * accidental brush of the four buttons doesn't quit, short enough to feel responsive (the
+         * on-screen hint covers the gap). Roughly matches SDL/Apple `DISCONNECT_HOLD`.
+         */
+        const val EXIT_HOLD_MS = 1000L
+
+        /** Synthetic slot-key base for [ExternalPad]s — below every real (positive) InputDevice id. */
+        const val EXTERNAL_ID_BASE = -1000
    }
 }
@@ -85,6 +85,16 @@ object NativeBridge {
        name: String,
    ): String

+    /**
+     * The machine token of the most recent failed [nativeConnect]/[nativePair], cleared on read
+     * (`""` when none) — call right after a `0` handle / `""` fingerprint. A typed host rejection
+     * yields its wire token ("not-armed", "denied", "approval-timeout", "superseded", "busy",
+     * "rate-limited", "bound-other", "identity-required", "wire-version"); transport-level causes
+     * yield "crypto" (wrong PIN / identity mismatch), "timeout", "io", or "error". Lets the UI say
+     * WHY instead of the old catch-all that blamed the PIN for dead network paths.
+     */
+    external fun nativeTakeLastError(): String
+
    /**
     * Signal a **deliberate** user disconnect on [handle] before [nativeClose]: the session closes
     * with `QUIT_CLOSE_CODE` so the host tears it down immediately instead of holding the keep-alive
@@ -151,6 +161,14 @@ object NativeBridge {
     */
    external fun nativeVideoMime(handle: Long): String

+    /**
+     * A short human label for the codec the host resolved (`"H.264"` / `"HEVC"` / `"AV1"` /
+     * `"PyroWave"`), for the stats HUD's video-feed line, or `""` on a `0` handle. Distinct from
+     * [nativeVideoMime] because the MIME collapses PyroWave onto `video/hevc` and can't name it.
+     * Fixed for the session (resolved at the handshake); read once. Cheap; UI-safe.
+     */
+    external fun nativeVideoCodecLabel(handle: Long): String
+
    /**
     * Start the decode thread rendering onto [surface] (a SurfaceView's surface). Decode runs
     * entirely in Rust (NDK AMediaCodec → ANativeWindow) — no per-frame JNI. [decoderName] is the
@@ -291,6 +309,14 @@ object NativeBridge {
    /** 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)

+    /**
+     * One raw HID input report from a client-captured controller (the as-is Steam Controller 2
+     * passthrough), forwarded verbatim on the rich-input plane. [buf] is a DIRECT ByteBuffer whose
+     * first [len] bytes are the report, id byte first (0x42/0x45/0x47 state, 0x43 battery, …);
+     * len is clamped to 64. Called from the capture thread at the controller's own report rate.
+     */
+    external fun nativeSendPadHidReport(handle: Long, pad: Int, buf: java.nio.ByteBuffer, len: Int)
+
    // ---- Host→client gamepad feedback: Rust pulls block ~100ms, Kotlin renders (see GamepadFeedback) ----

    /**
@@ -302,10 +328,11 @@ object NativeBridge {
    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 `[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.
+     * Block up to ~100 ms for the next HID-output event, written into [buf] (a direct ByteBuffer,
+     * capacity >= 128) 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…, raw as-is
+     * passthrough report=pad 05 kind report-bytes (kind 0 = output report, 1 = feature report).
+     * Returns the byte count, or -1 on timeout / session closed.
     */
    external fun nativeNextHidout(handle: Long, buf: java.nio.ByteBuffer): Int
 }
@@ -0,0 +1,241 @@
+package io.unom.punktfunk.kit
+
+import android.annotation.SuppressLint
+import android.bluetooth.BluetoothDevice
+import android.bluetooth.BluetoothGatt
+import android.bluetooth.BluetoothGattCallback
+import android.bluetooth.BluetoothGattCharacteristic
+import android.bluetooth.BluetoothGattDescriptor
+import android.bluetooth.BluetoothManager
+import android.bluetooth.BluetoothProfile
+import android.content.Context
+import android.util.Log
+import java.util.UUID
+import java.util.concurrent.atomic.AtomicBoolean
+
+/**
+ * BLE transport for a Steam Controller 2 paired directly with the device (no Puck). The standard
+ * HID service (0x1812) is claimed by the OS (and would feed the pad through the ordinary input
+ * stack in lizard-crippled form), so this talks Valve's vendor GATT service instead — the same
+ * approach Steam itself uses on hosts without a dongle.
+ *
+ * GATT operations are serialized by a small state machine (connect → MTU → discover → subscribe
+ * each notify char → lizard-off → ready); duplicate callbacks (the Android stack sometimes fires
+ * `onMtuChanged` twice) are ignored. Notified state reports arrive with the report-id byte
+ * stripped by the transport, so `0x45` (`ID_STATE_BLE`) is re-prepended for ≥40-byte payloads —
+ * the wire then carries the same id-first framing as USB.
+ *
+ * Requires BLUETOOTH_CONNECT (the caller gates on it); connection priority is bumped to HIGH to
+ * pull the connection interval from ~50 ms down to ~11 ms.
+ */
+@SuppressLint("MissingPermission")
+class Sc2BleLink(
+    private val context: Context,
+    private val onReport: (report: ByteArray, len: Int) -> Unit,
+    private val onClosed: () -> Unit,
+) {
+    private enum class State { IDLE, CONNECTING, MTU_REQUESTED, DISCOVERING, SUBSCRIBING, READY }
+
+    private val manager = context.getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager
+
+    private var gatt: BluetoothGatt? = null
+    private var writeChar: BluetoothGattCharacteristic? = null
+    private val pendingSubs = mutableListOf<BluetoothGattCharacteristic>()
+    private var subsIndex = 0
+    private val writeBusy = AtomicBoolean(false)
+    private var lizardTicker: Thread? = null
+
+    @Volatile private var state = State.IDLE
+
+    /** Bonded devices that look like a Steam Controller (name heuristic — BLE exposes no PID here). */
+    fun pairedControllers(): List<BluetoothDevice> = runCatching {
+        manager.adapter?.bondedDevices.orEmpty().filter { dev ->
+            val n = runCatching { dev.name }.getOrNull() ?: return@filter false
+            NAME_HINTS.any { n.contains(it, ignoreCase = true) }
+        }
+    }.getOrDefault(emptyList())
+
+    /** Connect to the bonded controller at [address]. Reports start flowing once READY. */
+    fun start(address: String): Boolean {
+        val adapter = manager.adapter ?: return false
+        if (!adapter.isEnabled) return false
+        val device = runCatching { adapter.getRemoteDevice(address) }.getOrNull() ?: return false
+        state = State.CONNECTING
+        gatt = device.connectGatt(context, false, callback, BluetoothDevice.TRANSPORT_LE)
+        return true
+    }
+
+    /**
+     * Replay one raw report from the host: output reports (rumble) ride WRITE_NO_RESPONSE so they
+     * can't queue behind acks at the 25 Hz resend rate; feature reports (settings) use an acked
+     * write. The report-id byte stays in the payload (the firmware's vendor-channel framing).
+     */
+    fun writeRaw(kind: Int, data: ByteArray) {
+        if (state != State.READY || data.isEmpty()) return
+        val g = gatt ?: return
+        val ch = writeChar ?: return
+        runCatching {
+            ch.value = data
+            ch.writeType = if (kind == 0) {
+                BluetoothGattCharacteristic.WRITE_TYPE_NO_RESPONSE
+            } else {
+                BluetoothGattCharacteristic.WRITE_TYPE_DEFAULT
+            }
+            g.writeCharacteristic(ch)
+        }
+    }
+
+    private fun sendLizardOff() {
+        if (state != State.READY) return
+        val g = gatt ?: return
+        val ch = writeChar ?: return
+        if (!writeBusy.compareAndSet(false, true)) return // previous acked write still in flight
+        runCatching {
+            ch.value = Sc2Device.DISABLE_LIZARD
+            ch.writeType = BluetoothGattCharacteristic.WRITE_TYPE_DEFAULT
+            if (!g.writeCharacteristic(ch)) writeBusy.set(false)
+        }.onFailure { writeBusy.set(false) }
+    }
+
+    /** Disconnect and stop the lizard ticker. Idempotent; does not fire [onClosed]. */
+    fun stop() {
+        lizardTicker?.interrupt()
+        lizardTicker = null
+        runCatching { gatt?.disconnect() }
+        runCatching { gatt?.close() }
+        gatt = null
+        writeChar = null
+        pendingSubs.clear()
+        subsIndex = 0
+        state = State.IDLE
+    }
+
+    private val callback = object : BluetoothGattCallback() {
+        override fun onConnectionStateChange(g: BluetoothGatt, status: Int, newState: Int) {
+            when (newState) {
+                BluetoothProfile.STATE_CONNECTED -> {
+                    // ~11 ms connection interval instead of the ~50 ms default — input latency.
+                    g.requestConnectionPriority(BluetoothGatt.CONNECTION_PRIORITY_HIGH)
+                    if (state == State.CONNECTING) {
+                        state = State.MTU_REQUESTED
+                        if (!g.requestMtu(DESIRED_MTU)) {
+                            state = State.DISCOVERING
+                            g.discoverServices()
+                        }
+                    }
+                }
+                BluetoothProfile.STATE_DISCONNECTED -> {
+                    val wasLive = state != State.IDLE
+                    runCatching { g.close() }
+                    gatt = null
+                    writeChar = null
+                    pendingSubs.clear()
+                    subsIndex = 0
+                    state = State.IDLE
+                    if (wasLive) onClosed()
+                }
+            }
+        }
+
+        override fun onMtuChanged(g: BluetoothGatt, mtu: Int, status: Int) {
+            if (state != State.MTU_REQUESTED) return // fired twice on some stacks — act once
+            state = State.DISCOVERING
+            g.discoverServices()
+        }
+
+        override fun onServicesDiscovered(g: BluetoothGatt, status: Int) {
+            if (state != State.DISCOVERING || status != BluetoothGatt.GATT_SUCCESS) return
+            val valve = g.getService(VALVE_SERVICE) ?: run {
+                Log.e(TAG, "Valve vendor service missing — not an SC2?")
+                return
+            }
+            pendingSubs.clear()
+            writeChar = null
+            for (ch in valve.characteristics) {
+                val short = shortUuid(ch.uuid) ?: continue
+                val canNotify = ch.properties and BluetoothGattCharacteristic.PROPERTY_NOTIFY != 0
+                val canWrite = ch.properties and (
+                    BluetoothGattCharacteristic.PROPERTY_WRITE or
+                        BluetoothGattCharacteristic.PROPERTY_WRITE_NO_RESPONSE
+                    ) != 0
+                if (canNotify && short in NOTIFY_LOW..NOTIFY_HIGH) pendingSubs.add(ch)
+                if (canWrite && short in WRITE_LOW..WRITE_HIGH && writeChar == null) writeChar = ch
+            }
+            subsIndex = 0
+            state = State.SUBSCRIBING
+            subscribeNext(g)
+        }
+
+        override fun onDescriptorWrite(g: BluetoothGatt, d: BluetoothGattDescriptor, status: Int) {
+            if (state == State.SUBSCRIBING) subscribeNext(g)
+        }
+
+        override fun onCharacteristicWrite(g: BluetoothGatt, ch: BluetoothGattCharacteristic, status: Int) {
+            writeBusy.set(false)
+        }
+
+        override fun onCharacteristicChanged(g: BluetoothGatt, ch: BluetoothGattCharacteristic) {
+            val data = ch.value ?: return
+            // BLE strips the report-id prefix; restore 0x45 on state-sized payloads so the raw
+            // wire framing matches USB. Short payloads (battery/status) pass through as-is.
+            if (data.size >= 40) {
+                val framed = ByteArray(data.size + 1)
+                framed[0] = Sc2Device.ID_STATE_BLE.toByte()
+                System.arraycopy(data, 0, framed, 1, data.size)
+                onReport(framed, framed.size)
+            } else {
+                onReport(data, data.size)
+            }
+        }
+    }
+
+    private fun subscribeNext(g: BluetoothGatt) {
+        if (subsIndex >= pendingSubs.size) {
+            state = State.READY
+            Log.i(TAG, "SC2 BLE link up (${pendingSubs.size} notify chars)")
+            sendLizardOff()
+            // The firmware watchdog re-enables lizard mode; refresh on SDL's cadence until the
+            // host's Steam takes over via the raw plane (its writes land through writeRaw too).
+            lizardTicker = Thread({
+                while (state == State.READY) {
+                    try {
+                        Thread.sleep(Sc2Device.LIZARD_REFRESH_MS)
+                    } catch (_: InterruptedException) {
+                        return@Thread
+                    }
+                    sendLizardOff()
+                }
+            }, "pf-sc2-lizard").apply { isDaemon = true; start() }
+            return
+        }
+        val ch = pendingSubs[subsIndex++]
+        g.setCharacteristicNotification(ch, true)
+        val cccd = ch.getDescriptor(CCCD) ?: return subscribeNext(g)
+        cccd.value = BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE
+        if (!g.writeDescriptor(cccd)) subscribeNext(g) // lose this one, try the rest
+    }
+
+    /** The 32-bit short id of a Valve vendor UUID, or null for foreign UUIDs. */
+    private fun shortUuid(uuid: UUID): Long? {
+        val s = uuid.toString()
+        if (!s.endsWith(VALVE_UUID_TAIL)) return null
+        return s.substring(0, 8).toLongOrNull(16)
+    }
+
+    private companion object {
+        const val TAG = "Sc2BleLink"
+
+        val VALVE_SERVICE: UUID = UUID.fromString("100f6c32-1735-4313-b402-38567131e5f3")
+        const val VALVE_UUID_TAIL = "-1735-4313-b402-38567131e5f3"
+        const val NOTIFY_LOW = 0x100f6c75L
+        const val NOTIFY_HIGH = 0x100f6c7aL
+        const val WRITE_LOW = 0x100f6cb5L
+        const val WRITE_HIGH = 0x100f6cbeL
+        val CCCD: UUID = UUID.fromString("00002902-0000-1000-8000-00805f9b34fb")
+
+        val NAME_HINTS = listOf("Steam Ctrl", "Steam Controller", "SteamController", "Valve")
+
+        /** Enough for a state payload (45 B) + ATT header with margin. */
+        const val DESIRED_MTU = 100
+    }
+}
@@ -0,0 +1,316 @@
+package io.unom.punktfunk.kit
+
+import android.content.Context
+import android.hardware.usb.UsbDevice
+import android.util.Log
+import java.nio.ByteBuffer
+
+/**
+ * One captured Steam Controller 2 — the glue between a transport link ([Sc2UsbLink] /
+ * [Sc2BleLink]) and one of two consumers:
+ *
+ * **Stream mode** (`router != null`, owned by StreamScreen):
+ * - **Raw plane (the point):** every input report is forwarded verbatim
+ *   ([GamepadRouter.ExternalPad.hidReport]) for the host's as-is virtual `28DE:1302` pad, which
+ *   Steam Input drives like the physical controller.
+ * - **Typed mirror:** buttons/sticks/triggers are ALSO diffed onto the ordinary per-transition
+ *   plane, so the emergency exit chord works, and a host that degraded the kind (no UHID → the
+ *   Xbox 360 pad) still gets a playable controller.
+ * - **Raw return:** the host's hidraw writes (Steam's `0x80` rumble output reports, lizard/IMU
+ *   feature settings) arrive via [GamepadFeedback.onHidRaw] → [onHidRaw] → the link, landing on
+ *   the real controller's motors/firmware.
+ *
+ * **UI mode** (`router == null`, owned by MainActivity while NOT streaming): the lizard-mode
+ * kb/mouse never produces gamepad events, so an uncaptured SC2 can't drive the console UI at
+ * all. Here the parsed state is edge-detected into [onUiKey] navigation transitions instead
+ * (D-pad + face buttons + Start/Select; the left stick synthesizes one D-pad step per push,
+ * mirroring MainActivity's stick-to-focus behavior for ordinary pads).
+ *
+ * The wire slot is claimed lazily on the FIRST state report — a Puck with no controller powered
+ * on stays invisible to the host — and released (with a wireless-disconnect event or on [stop])
+ * so pad indices never leak. Report callbacks arrive on the link's own thread; the router's slot
+ * table and chord timer are thread-safe for this (same contract as the feedback poll threads),
+ * and UI-mode consumers hop to the main thread themselves.
+ */
+class Sc2Capture(
+    context: Context,
+    private val router: GamepadRouter? = null,
+) {
+    private val usb = Sc2UsbLink(context, ::onReport, ::onLinkClosed)
+    private val ble = Sc2BleLink(context, ::onReport, ::onLinkClosed)
+    private var activeLink: Int = LINK_NONE
+
+    /** True when the USB link is a Puck dongle — the only transport whose wireless-status
+     *  reports are authoritative. A WIRED pad also emits them, truthfully reporting "no radio
+     *  link" — acting on that tore the slot down 255 ms after creation (first on-glass run). */
+    private var dongleLink = false
+
+    private var pad: GamepadRouter.ExternalPad? = null
+    private val rawBuf: ByteBuffer = ByteBuffer.allocateDirect(64)
+    /** Puck connect arrives before its first state report (and therefore before a wire pad exists).
+     * Preserve it so the native virtual Puck slot sees the same connect edge before state. */
+    private val pendingWireless = ByteArray(2)
+    private var pendingWirelessLen = 0
+
+    // Typed-mirror diff state (wire units).
+    private val state = Sc2Device.State()
+    private var wireButtons = 0
+    private val lastAxis = IntArray(6) { Int.MIN_VALUE }
+
+    /** Report ids seen so far — each logged once, for remote diagnosis of what the pad emits. */
+    private val seenIds = HashSet<Int>()
+
+    // UI-mode state (router == null): held navigation keys + the stick's current synth direction.
+    private var uiHeld = HashSet<Int>()
+    private var uiStickDir = 0
+
+    /**
+     * UI-mode sink: one navigation key transition (an Android `KeyEvent.KEYCODE_*`), invoked on
+     * the LINK thread — the consumer hops to the main thread. Set before [startUsb]/[startBle].
+     */
+    @Volatile
+    var onUiKey: ((keyCode: Int, down: Boolean) -> Unit)? = null
+
+    /**
+     * Fired (link thread) when the capture engages or drops — lets the app surface "SC2
+     * connected" in the console-UI gate and the Controllers screen.
+     */
+    @Volatile
+    var onActiveChanged: ((active: Boolean) -> Unit)? = null
+
+    val isActive: Boolean get() = activeLink != LINK_NONE
+
+    /** First attached SC2/Puck USB device, for the permission flow. */
+    fun findUsbDevice(): UsbDevice? = usb.findDevice()
+
+    /**
+     * The first already-bonded BLE Steam Controller's address, or null. The caller checks
+     * BLUETOOTH_CONNECT first (without it the bonded list reads as empty anyway).
+     */
+    fun pairedBleAddress(): String? = ble.pairedControllers().firstOrNull()?.address
+
+    /** Start capturing [dev] over USB (permission already granted). */
+    fun startUsb(dev: UsbDevice): Boolean {
+        if (activeLink != LINK_NONE) return false
+        val ok = usb.start(dev)
+        if (ok) {
+            activeLink = LINK_USB
+            dongleLink = dev.productId != Sc2Device.PID_WIRED
+            onActiveChanged?.invoke(true)
+        }
+        return ok
+    }
+
+    /** Start capturing the bonded BLE controller at [address]. */
+    fun startBle(address: String): Boolean {
+        if (activeLink != LINK_NONE) return false
+        val ok = ble.start(address)
+        if (ok) {
+            activeLink = LINK_BLE
+            onActiveChanged?.invoke(true)
+        }
+        return ok
+    }
+
+    /** Replay a host raw write on the physical pad — wire to [GamepadFeedback.onHidRaw]. */
+    fun onHidRaw(padIndex: Int, kind: Int, data: ByteArray) {
+        if (padIndex != pad?.index) return // addressed to some other controller
+        when (activeLink) {
+            LINK_USB -> usb.writeRaw(kind, data)
+            LINK_BLE -> ble.writeRaw(kind, data)
+        }
+    }
+
+    /** Stop the link and free the wire slot (host tears the virtual pad down). Idempotent. */
+    fun stop() {
+        val wasActive = activeLink != LINK_NONE
+        when (activeLink) {
+            LINK_USB -> usb.stop()
+            LINK_BLE -> ble.stop()
+        }
+        activeLink = LINK_NONE
+        dongleLink = false
+        releaseSlot()
+        releaseUiKeys()
+        if (wasActive) onActiveChanged?.invoke(false)
+    }
+
+    // ---- link callbacks (link thread) ----
+
+    private fun onReport(report: ByteArray, len: Int) {
+        val id = report[0].toInt() and 0xFF
+        if (seenIds.add(id)) Log.i(TAG, "SC2 report id=0x%02x seen (len=%d)".format(id, len))
+        // Wireless status: authoritative ONLY through a Puck dongle (powering the pad off frees
+        // its wire index + the host's virtual device). A wired/BLE pad emits it too — truthfully
+        // saying "no radio link" — and must NOT tear the slot down (SDL's wired path likewise
+        // marks the controller connected unconditionally and reconnects on any state report).
+        if ((id == Sc2Device.ID_WIRELESS || id == Sc2Device.ID_WIRELESS_X) && len >= 2) {
+            if (dongleLink) {
+                when (report[1].toInt() and 0xFF) {
+                    Sc2Device.WIRELESS_CONNECT -> {
+                        pendingWireless[0] = report[0]
+                        pendingWireless[1] = report[1]
+                        pendingWirelessLen = 2
+                    }
+                    Sc2Device.WIRELESS_DISCONNECT -> {
+                        pendingWirelessLen = 0
+                        Log.i(TAG, "Puck reports controller powered off — releasing wire slot")
+                        releaseSlot()
+                        releaseUiKeys()
+                    }
+                }
+            }
+            return
+        }
+        if (!Sc2Device.parseState(report, len, state)) {
+            // Battery/status and future report types still belong to the as-is stream.
+            forwardRaw(report, len)
+            return
+        }
+        if (router == null) {
+            mirrorUi()
+            return
+        }
+        val pref = if (dongleLink) {
+            Gamepad.PREF_STEAMCONTROLLER2_PUCK
+        } else {
+            Gamepad.PREF_STEAMCONTROLLER2
+        }
+        val p = pad ?: router.openExternal(pref)?.also {
+            pad = it
+            Log.i(
+                TAG,
+                "SC2 captured → wire pad ${it.index} (${if (dongleLink) "Puck" else "direct"} passthrough)",
+            )
+            if (pendingWirelessLen > 0) {
+                forwardRaw(pendingWireless, pendingWirelessLen)
+                pendingWirelessLen = 0
+            }
+        } ?: return // all 16 wire indices taken — drop until one frees
+        forwardRaw(report, len)
+        mirrorTyped(p)
+    }
+
+    private fun forwardRaw(report: ByteArray, len: Int) {
+        val p = pad ?: return
+        val n = len.coerceAtMost(rawBuf.capacity())
+        rawBuf.clear()
+        rawBuf.put(report, 0, n)
+        p.hidReport(rawBuf, n)
+    }
+
+    /** Diff the parsed state onto the per-transition plane (buttons + axes, on change only). */
+    private fun mirrorTyped(p: GamepadRouter.ExternalPad) {
+        val wired = Sc2Device.wireButtons(state.buttons)
+        var changed = wired xor wireButtons
+        while (changed != 0) {
+            val bit = changed and -changed // lowest changed bit
+            p.button(bit, wired and bit != 0)
+            changed = changed and bit.inv()
+        }
+        wireButtons = wired
+        axis(p, Gamepad.AXIS_LS_X, state.lsX)
+        axis(p, Gamepad.AXIS_LS_Y, state.lsY)
+        axis(p, Gamepad.AXIS_RS_X, state.rsX)
+        axis(p, Gamepad.AXIS_RS_Y, state.rsY)
+        axis(p, Gamepad.AXIS_LT, state.lt)
+        axis(p, Gamepad.AXIS_RT, state.rt)
+    }
+
+    private fun axis(p: GamepadRouter.ExternalPad, id: Int, v: Int) {
+        if (lastAxis[id] == v) return
+        lastAxis[id] = v
+        p.axis(id, v)
+    }
+
+    /**
+     * UI mode: edge-detect the parsed state into navigation key transitions. Buttons map to
+     * their Android keycodes (press AND release, so the focus system sees real holds); the left
+     * stick synthesizes ONE D-pad step per push past half deflection — the same single-move
+     * behavior MainActivity gives ordinary pads' sticks.
+     */
+    private fun mirrorUi() {
+        val sink = onUiKey ?: return
+        val held = HashSet<Int>(8)
+        var i = 0
+        while (i < UI_KEY_MAP.size) {
+            if (state.buttons and UI_KEY_MAP[i] != 0) held.add(UI_KEY_MAP[i + 1])
+            i += 2
+        }
+        for (key in held) if (key !in uiHeld) sink(key, true)
+        for (key in uiHeld) if (key !in held) sink(key, false)
+        uiHeld = held
+        // Left stick → a HELD D-pad direction (device convention: +y = up): pressed while
+        // deflected, released on centre/direction change. The console UI's probe machinery
+        // turns a held direction into its own auto-repeat, exactly like a physical D-pad; the
+        // focus-hook path moves once per press edge either way.
+        val dir = when {
+            state.lsX <= -STICK_NAV -> android.view.KeyEvent.KEYCODE_DPAD_LEFT
+            state.lsX >= STICK_NAV -> android.view.KeyEvent.KEYCODE_DPAD_RIGHT
+            state.lsY >= STICK_NAV -> android.view.KeyEvent.KEYCODE_DPAD_UP
+            state.lsY <= -STICK_NAV -> android.view.KeyEvent.KEYCODE_DPAD_DOWN
+            else -> 0
+        }
+        if (dir != uiStickDir) {
+            // The D-pad bits share these keycodes; don't release a direction the physical
+            // D-pad itself still holds (uiHeld tracks the button-sourced state).
+            if (uiStickDir != 0 && uiStickDir !in uiHeld) sink(uiStickDir, false)
+            if (dir != 0 && dir !in uiHeld) sink(dir, true)
+            uiStickDir = dir
+        }
+    }
+
+    /** Release every held UI-mode key (link drop / stop) so nothing sticks in the focus system. */
+    private fun releaseUiKeys() {
+        val sink = onUiKey
+        if (sink != null) {
+            for (key in uiHeld) sink(key, false)
+            if (uiStickDir != 0 && uiStickDir !in uiHeld) sink(uiStickDir, false)
+        }
+        uiHeld = HashSet()
+        uiStickDir = 0
+    }
+
+    private fun onLinkClosed() {
+        Log.i(TAG, "SC2 link closed (unplug / power-off)")
+        activeLink = LINK_NONE
+        dongleLink = false
+        releaseSlot()
+        releaseUiKeys()
+        onActiveChanged?.invoke(false)
+    }
+
+    private fun releaseSlot() {
+        pad?.close()
+        pad = null
+        wireButtons = 0
+        lastAxis.fill(Int.MIN_VALUE)
+        pendingWirelessLen = 0
+    }
+
+    private companion object {
+        const val TAG = "Sc2Capture"
+        const val LINK_NONE = 0
+        const val LINK_USB = 1
+        const val LINK_BLE = 2
+
+        /** Half deflection (device i16 range) — the stick-to-focus threshold. */
+        const val STICK_NAV = 16384
+
+        /** UI-mode mapping: SC2 button bit → Android keycode, as (bit, key) pairs. */
+        val UI_KEY_MAP = intArrayOf(
+            Sc2Device.DPAD_UP, android.view.KeyEvent.KEYCODE_DPAD_UP,
+            Sc2Device.DPAD_DOWN, android.view.KeyEvent.KEYCODE_DPAD_DOWN,
+            Sc2Device.DPAD_LEFT, android.view.KeyEvent.KEYCODE_DPAD_LEFT,
+            Sc2Device.DPAD_RIGHT, android.view.KeyEvent.KEYCODE_DPAD_RIGHT,
+            Sc2Device.A, android.view.KeyEvent.KEYCODE_BUTTON_A,
+            Sc2Device.B, android.view.KeyEvent.KEYCODE_BUTTON_B,
+            Sc2Device.X, android.view.KeyEvent.KEYCODE_BUTTON_X,
+            Sc2Device.Y, android.view.KeyEvent.KEYCODE_BUTTON_Y,
+            Sc2Device.LB, android.view.KeyEvent.KEYCODE_BUTTON_L1,
+            Sc2Device.RB, android.view.KeyEvent.KEYCODE_BUTTON_R1,
+            Sc2Device.MENU, android.view.KeyEvent.KEYCODE_BUTTON_START,
+            Sc2Device.VIEW, android.view.KeyEvent.KEYCODE_BUTTON_SELECT,
+        )
+    }
+}
@@ -0,0 +1,165 @@
+package io.unom.punktfunk.kit
+
+/**
+ * Steam Controller 2 (2026, Valve "Ibex" / SDL "Triton") protocol constants + the light state
+ * parser the CLIENT needs. The full report rides the wire verbatim (`nativeSendPadHidReport` →
+ * the host's as-is virtual pad); this parser only extracts what the client itself consumes: the
+ * button word for the typed mirror + exit chord, and sticks/triggers for the degrade path.
+ *
+ * Protocol ground truth: SDL's `SDL_hidapi_steam_triton.c` + `steam/controller_structs.h`
+ * (Valve-maintained), mirrored host-side in `punktfunk-host`'s `triton_proto.rs`.
+ */
+object Sc2Device {
+    const val VID_VALVE = 0x28DE
+
+    /** Wired controller. */
+    const val PID_WIRED = 0x1302
+
+    /** Direct BLE identity (transport handled by [Sc2BleLink], not USB). */
+    const val PID_BLE = 0x1303
+
+    /** The wireless Puck dongles (Proteus / Nereid) — controller on USB interfaces 2..5. */
+    const val PID_DONGLE_PROTEUS = 0x1304
+    const val PID_DONGLE_NEREID = 0x1305
+
+    val USB_PIDS = setOf(PID_WIRED, PID_DONGLE_PROTEUS, PID_DONGLE_NEREID)
+
+    /** Dongle interface range that carries controllers (SDL: "interfaces 2..5, currently"). */
+    val DONGLE_IFACES = 2..5
+
+    // Input report ids (`ETritonReportIDTypes`). State layouts share every offset the client
+    // reads (seq/buttons/triggers/sticks); 0x47 only diverges from byte 18 (trackpad timestamp).
+    const val ID_STATE = 0x42
+    const val ID_BATTERY = 0x43
+    const val ID_STATE_BLE = 0x45
+    const val ID_WIRELESS_X = 0x46
+    const val ID_STATE_TIMESTAMP = 0x47
+    const val ID_WIRELESS = 0x79
+
+    /** Wireless status payload byte: controller connected/disconnected through the Puck. */
+    const val WIRELESS_DISCONNECT = 1
+    const val WIRELESS_CONNECT = 2
+
+    // Button bits in the state report's u32 (SDL `TritonButtons`).
+    const val A = 0x00000001
+    const val B = 0x00000002
+    const val X = 0x00000004
+    const val Y = 0x00000008
+    const val QAM = 0x00000010
+    const val R3 = 0x00000020
+    const val VIEW = 0x00000040
+    const val R4 = 0x00000080
+    const val R5 = 0x00000100
+    const val RB = 0x00000200
+    const val DPAD_DOWN = 0x00000400
+    const val DPAD_RIGHT = 0x00000800
+    const val DPAD_LEFT = 0x00001000
+    const val DPAD_UP = 0x00002000
+    const val MENU = 0x00004000
+    const val L3 = 0x00008000
+    const val STEAM = 0x00010000
+    const val L4 = 0x00020000
+    const val L5 = 0x00040000
+    const val LB = 0x00080000
+    const val RPAD_CLICK = 0x00400000
+
+    /**
+     * The feature report that turns lizard mode (built-in keyboard/mouse emulation) off:
+     * `[report id 1][ID_SET_SETTINGS_VALUES 0x87][length 3][SETTING_LIZARD_MODE 9]
+     * [LIZARD_MODE_OFF u16]`, zero-padded to the 64-byte feature size. The firmware watchdog
+     * re-enables lizard mode after a few seconds of silence, so this is re-sent every
+     * [LIZARD_REFRESH_MS] (SDL's cadence) — and the host's Steam sends its own through the raw
+     * plane once it grabs the virtual pad, which lands here too.
+     */
+    val DISABLE_LIZARD: ByteArray = ByteArray(64).also {
+        it[0] = 0x01 // feature report id
+        it[1] = 0x87.toByte() // ID_SET_SETTINGS_VALUES
+        it[2] = 3 // one ControllerSetting {u8 num, u16 value}
+        it[3] = 9 // SETTING_LIZARD_MODE
+        // [4..6] = LIZARD_MODE_OFF (0) — already zero
+    }
+
+    /**
+     * Force firmware-calibrated signed i16 stick coordinates. Steam sends this during physical
+     * controller initialization (`SETTING_ENABLE_RAW_JOYSTICK` = 0x2e, value 0); without it a
+     * controller previously opened in raw mode reports ADC coordinates around 0..3200, which a
+     * Triton consumer interprets as only a few percent of full travel.
+     */
+    val NORMALIZE_JOYSTICKS: ByteArray = ByteArray(64).also {
+        it[0] = 0x01 // feature report id
+        it[1] = 0x87.toByte() // ID_SET_SETTINGS_VALUES
+        it[2] = 3 // one ControllerSetting {u8 num, u16 value}
+        it[3] = 0x2E // SETTING_ENABLE_RAW_JOYSTICK
+        // [4..6] = disabled (0) — firmware emits calibrated signed i16 values
+    }
+
+    const val LIZARD_REFRESH_MS = 3000L
+
+    /** Wire mapping: SC2 button bit → punktfunk `Gamepad.BTN_*`, the inverse of the host's
+     *  typed-fallback mapping (`triton_proto::from_gamepad`): paddles R4/L4/R5/L5 =
+     *  PADDLE1/2/3/4, QAM = MISC1, right-pad click = the touchpad wire bit. */
+    private val WIRE_MAP = intArrayOf(
+        A, Gamepad.BTN_A,
+        B, Gamepad.BTN_B,
+        X, Gamepad.BTN_X,
+        Y, Gamepad.BTN_Y,
+        LB, Gamepad.BTN_LB,
+        RB, Gamepad.BTN_RB,
+        VIEW, Gamepad.BTN_BACK,
+        MENU, Gamepad.BTN_START,
+        STEAM, Gamepad.BTN_GUIDE,
+        L3, Gamepad.BTN_LS_CLICK,
+        R3, Gamepad.BTN_RS_CLICK,
+        DPAD_UP, Gamepad.BTN_DPAD_UP,
+        DPAD_DOWN, Gamepad.BTN_DPAD_DOWN,
+        DPAD_LEFT, Gamepad.BTN_DPAD_LEFT,
+        DPAD_RIGHT, Gamepad.BTN_DPAD_RIGHT,
+        QAM, Gamepad.BTN_MISC1,
+        R4, Gamepad.BTN_PADDLE1,
+        L4, Gamepad.BTN_PADDLE2,
+        R5, Gamepad.BTN_PADDLE3,
+        L5, Gamepad.BTN_PADDLE4,
+        RPAD_CLICK, Gamepad.BTN_TOUCHPAD,
+    )
+
+    /** Translate an SC2 button word into the wire `Gamepad.BTN_*` bitmask. */
+    fun wireButtons(sc2: Int): Int {
+        var out = 0
+        var i = 0
+        while (i < WIRE_MAP.size) {
+            if (sc2 and WIRE_MAP[i] != 0) out = out or WIRE_MAP[i + 1]
+            i += 2
+        }
+        return out
+    }
+
+    /** The typed-mirror fields of one state report (buttons/sticks/triggers only). */
+    class State {
+        var buttons = 0 // SC2 bit layout
+        var lsX = 0; var lsY = 0 // i16, +y = up (device convention = wire convention)
+        var rsX = 0; var rsY = 0
+        var lt = 0; var rt = 0 // 0..255 (device 0..32767 scaled down)
+    }
+
+    /**
+     * Parse the client-consumed fields out of a state report (`0x42`/`0x45`/`0x47` — identical
+     * offsets for everything read here) into [out]. Returns false for non-state / short reports.
+     */
+    fun parseState(report: ByteArray, len: Int, out: State): Boolean {
+        if (len < 18) return false
+        when (report[0].toInt() and 0xFF) {
+            ID_STATE, ID_STATE_BLE, ID_STATE_TIMESTAMP -> {}
+            else -> return false
+        }
+        fun i16(o: Int) = ((report[o + 1].toInt() shl 8) or (report[o].toInt() and 0xFF)).toShort().toInt()
+        out.buttons = (report[2].toInt() and 0xFF) or
+            ((report[3].toInt() and 0xFF) shl 8) or
+            ((report[4].toInt() and 0xFF) shl 16) or
+            ((report[5].toInt() and 0xFF) shl 24)
+        out.lt = (i16(6).coerceIn(0, 32767)) shr 7
+        out.rt = (i16(8).coerceIn(0, 32767)) shr 7
+        out.lsX = i16(10); out.lsY = i16(12)
+        out.rsX = i16(14); out.rsY = i16(16)
+        return true
+    }
+}
@@ -0,0 +1,379 @@
+package io.unom.punktfunk.kit
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.hardware.usb.UsbConstants
+import android.hardware.usb.UsbDevice
+import android.hardware.usb.UsbDeviceConnection
+import android.hardware.usb.UsbEndpoint
+import android.hardware.usb.UsbInterface
+import android.hardware.usb.UsbManager
+import android.hardware.usb.UsbRequest
+import android.os.Build
+import android.util.Log
+import java.nio.ByteBuffer
+import java.util.concurrent.ConcurrentLinkedQueue
+import java.util.concurrent.TimeoutException
+
+/**
+ * USB transport for a Steam Controller 2 — wired (`28DE:1302`) or through the wireless Puck
+ * dongle (`1304`/`1305`). Claims the controller interface(s) — detaching the OS input stack, so
+ * the pad can't double-drive the ordinary InputDevice path — runs a multiplexed [UsbRequest]
+ * read loop, keeps lizard mode off on the firmware watchdog cadence, and replays the host's raw
+ * writes (Steam's rumble output reports / settings feature reports) back to the device.
+ *
+ * **The Puck claims ALL controller interfaces (2..5):** the dongle hosts up to four pads, one
+ * HID interface each, and there is no way to know which slot a controller bonded to — claiming
+ * only interface 2 read silence while Android's input stack kept the others (the round-2
+ * on-glass symptom: the pad surfaced as a generic InputDevice → Xbox360). Whichever interface
+ * streams state becomes the write target for rumble/settings.
+ *
+ * **Unplug is signalled, never inferred from silence:** a quiet controller is not a missing one
+ * (round 2's wired disconnect was the 5 s silence heuristic firing on an idle pad). The real
+ * signals are [UsbManager.ACTION_USB_DEVICE_DETACHED] for this device, or `requestWait`
+ * returning sustained hard errors (every transfer fails instantly once the fd is dead).
+ */
+class Sc2UsbLink(
+    private val context: Context,
+    private val onReport: (report: ByteArray, len: Int) -> Unit,
+    private val onClosed: () -> Unit,
+) {
+    private val usb = context.getSystemService(Context.USB_SERVICE) as UsbManager
+
+    /** One claimed interface: its endpoints + the read state the reader thread owns. */
+    private class Claim(
+        val iface: UsbInterface,
+        val epIn: UsbEndpoint,
+        val epOut: UsbEndpoint?,
+    ) {
+        val inBuf: ByteBuffer = ByteBuffer.allocate(64)
+        var inReq: UsbRequest? = null
+        var outReq: UsbRequest? = null
+        var outBusy = false
+        var reports = 0L
+    }
+
+    private var connection: UsbDeviceConnection? = null
+    private var device: UsbDevice? = null
+    private var claims: List<Claim> = emptyList()
+
+    /** The claim whose IN endpoint last produced data — where rumble/settings writes go.
+     *  Written by the reader thread, read by the feedback thread (feature control transfers). */
+    @Volatile private var activeClaim: Claim? = null
+
+    /** Pending OUT reports (Steam's forwarded haptics), submitted by the reader thread — only
+     *  one thread may drive a connection's [UsbRequest]s ([UsbDeviceConnection.requestWait]
+     *  returns ANY completed request; a second waiter would steal the reader's completions). */
+    private val outQueue = ConcurrentLinkedQueue<ByteArray>()
+
+    private var reader: Thread? = null
+    private var detachReceiver: BroadcastReceiver? = null
+
+    @Volatile private var running = false
+
+    /** First attached SC2 (wired or Puck), or null. Does not need USB permission to enumerate. */
+    fun findDevice(): UsbDevice? = usb.deviceList.values.firstOrNull {
+        it.vendorId == Sc2Device.VID_VALVE && it.productId in Sc2Device.USB_PIDS
+    }
+
+    /**
+     * Claim [dev]'s controller interface(s) and start the read loop. The caller has already
+     * obtained USB permission. Returns false when nothing could be claimed.
+     */
+    fun start(dev: UsbDevice): Boolean {
+        if (!usb.hasPermission(dev)) {
+            Log.e(TAG, "no USB permission for ${dev.deviceName}")
+            return false
+        }
+        val conn = usb.openDevice(dev) ?: run {
+            Log.e(TAG, "openDevice failed for ${dev.deviceName}")
+            return false
+        }
+        val claimed = claimControllerInterfaces(dev, conn)
+        if (claimed.isEmpty()) {
+            Log.e(TAG, "no claimable SC2 interface on ${dev.deviceName} (PID=0x%04x)".format(dev.productId))
+            conn.close()
+            return false
+        }
+        connection = conn
+        device = dev
+        claims = claimed
+        running = true
+        Log.i(
+            TAG,
+            "SC2 USB link up: PID=0x%04x ifaces=%s".format(
+                dev.productId,
+                claimed.joinToString {
+                    "%d(in=0x%02x out=%s)".format(
+                        it.iface.id, it.epIn.address,
+                        it.epOut?.let { e -> "0x%02x".format(e.address) } ?: "-",
+                    )
+                },
+            ),
+        )
+        // The REAL unplug signal — silence never is (an idle pad may simply stop streaming).
+        val receiver = object : BroadcastReceiver() {
+            override fun onReceive(c: Context?, intent: Intent?) {
+                if (intent?.action != UsbManager.ACTION_USB_DEVICE_DETACHED) return
+                val gone: UsbDevice? = intent.getParcelableExtra(UsbManager.EXTRA_DEVICE)
+                if (gone?.deviceName == dev.deviceName) {
+                    Log.i(TAG, "SC2 USB detached (${dev.deviceName})")
+                    if (running) {
+                        running = false
+                        onClosed()
+                    }
+                }
+            }
+        }
+        detachReceiver = receiver
+        val filter = IntentFilter(UsbManager.ACTION_USB_DEVICE_DETACHED)
+        if (Build.VERSION.SDK_INT >= 33) {
+            context.registerReceiver(receiver, filter, Context.RECEIVER_NOT_EXPORTED)
+        } else {
+            @Suppress("UnspecifiedRegisterReceiverFlag")
+            context.registerReceiver(receiver, filter)
+        }
+        claimed.forEach { configureInputMode(conn, it.iface.id) }
+        reader = Thread({ readLoop(conn, claimed) }, "pf-sc2-usb").apply {
+            isDaemon = true
+            start()
+        }
+        return true
+    }
+
+    /**
+     * Claim every candidate controller interface: the wired pad's single HID interface, or ALL
+     * of a Puck's controller slots (interfaces 2..5 — the controller may be bonded to any of
+     * them). `force = true` detaches the kernel/OS driver, so the pad also vanishes from
+     * Android's own input stack while captured.
+     */
+    private fun claimControllerInterfaces(dev: UsbDevice, conn: UsbDeviceConnection): List<Claim> {
+        val dongle = dev.productId != Sc2Device.PID_WIRED
+        val out = mutableListOf<Claim>()
+        for (i in 0 until dev.interfaceCount) {
+            val iface = dev.getInterface(i)
+            if (dongle && iface.id !in Sc2Device.DONGLE_IFACES) continue
+            val hidOrVendor = iface.interfaceClass == UsbConstants.USB_CLASS_HID ||
+                iface.interfaceClass == 0xFF
+            if (!hidOrVendor) continue
+            var inEp: UsbEndpoint? = null
+            var outEp: UsbEndpoint? = null
+            for (e in 0 until iface.endpointCount) {
+                val ep = iface.getEndpoint(e)
+                val usable = ep.type == UsbConstants.USB_ENDPOINT_XFER_INT ||
+                    ep.type == UsbConstants.USB_ENDPOINT_XFER_BULK
+                if (!usable) continue
+                if (ep.direction == UsbConstants.USB_DIR_IN && inEp == null) inEp = ep
+                if (ep.direction == UsbConstants.USB_DIR_OUT && outEp == null) outEp = ep
+            }
+            if (inEp == null) continue
+            if (conn.claimInterface(iface, true)) {
+                out.add(Claim(iface, inEp, outEp))
+            } else {
+                Log.w(TAG, "could not claim iface ${iface.id}")
+            }
+        }
+        return out
+    }
+
+    /**
+     * The multiplexed read loop: one IN request queued per claimed interface at all times, OUT
+     * writes submitted from [outQueue], completions routed via [UsbRequest.getClientData].
+     */
+    private fun readLoop(conn: UsbDeviceConnection, claims: List<Claim>) {
+        val live = claims.filter { c ->
+            val req = UsbRequest()
+            if (!req.initialize(conn, c.epIn)) {
+                Log.w(TAG, "UsbRequest.initialize(IN, iface ${c.iface.id}) failed")
+                return@filter false
+            }
+            req.clientData = c
+            c.inReq = req
+            c.epOut?.let { ep ->
+                val o = UsbRequest()
+                if (o.initialize(conn, ep)) {
+                    o.clientData = c
+                    c.outReq = o
+                } else {
+                    Log.w(TAG, "UsbRequest.initialize(OUT, iface ${c.iface.id}) failed — output reports via EP0")
+                }
+            }
+            c.inBuf.clear()
+            req.queue(c.inBuf)
+        }
+        if (live.isEmpty()) {
+            Log.e(TAG, "no IN request could be queued")
+            finishReader(claims)
+            return
+        }
+        val scratch = ByteArray(64)
+        var lastLizard = android.os.SystemClock.elapsedRealtime()
+        var errorsSince = 0L // elapsedRealtime of the first hard error in the current streak
+        try {
+            while (running) {
+                val now = android.os.SystemClock.elapsedRealtime()
+                if (now - lastLizard >= Sc2Device.LIZARD_REFRESH_MS) {
+                    // Refresh both required firmware modes. The raw-joystick setting is normally
+                    // persistent, but replaying it also repairs a host/driver that enabled ADC
+                    // coordinates after capture started.
+                    val target = activeClaim
+                    if (target != null) configureInputMode(conn, target.iface.id)
+                    else live.forEach { configureInputMode(conn, it.iface.id) }
+                    lastLizard = now
+                }
+                // Submit the next pending OUT report on the active (else first) interface.
+                val outTarget = (activeClaim ?: live.first()).takeIf { it.outReq != null && !it.outBusy }
+                if (outTarget != null) {
+                    outQueue.poll()?.let { data ->
+                        if (outTarget.outReq!!.queue(ByteBuffer.wrap(data))) outTarget.outBusy = true
+                    }
+                }
+                val done = try {
+                    conn.requestWait(READ_TIMEOUT_MS)
+                } catch (_: TimeoutException) {
+                    // A quiet controller is NOT an unplug — keep listening indefinitely; the
+                    // detach broadcast is the real signal.
+                    errorsSince = 0L
+                    continue
+                }
+                if (done == null) {
+                    // Hard error. On a real unplug these storm continuously (the detach
+                    // broadcast usually beats us to it); tolerate transient ones.
+                    if (errorsSince == 0L) errorsSince = now
+                    if (now - errorsSince >= ERROR_UNPLUG_MS) {
+                        Log.i(TAG, "SC2 USB request errors persisting ${now - errorsSince} ms — treating as unplug")
+                        break
+                    }
+                    continue
+                }
+                errorsSince = 0L
+                val claim = done.clientData as? Claim ?: continue
+                if (done === claim.inReq) {
+                    val n = claim.inBuf.position()
+                    if (n > 0) {
+                        claim.inBuf.flip()
+                        claim.inBuf.get(scratch, 0, n)
+                        if (claim.reports++ == 0L) {
+                            Log.i(
+                                TAG,
+                                "SC2 first report on iface %d: id=0x%02x len=%d".format(
+                                    claim.iface.id, scratch[0].toInt() and 0xFF, n,
+                                ),
+                            )
+                        }
+                        activeClaim = claim
+                        onReport(scratch, n)
+                    }
+                    claim.inBuf.clear()
+                    if (!claim.inReq!!.queue(claim.inBuf)) {
+                        Log.i(TAG, "re-queue(IN, iface ${claim.iface.id}) failed — treating as unplug")
+                        break
+                    }
+                } else if (done === claim.outReq) {
+                    claim.outBusy = false
+                }
+            }
+        } finally {
+            finishReader(claims)
+        }
+        if (running) {
+            running = false
+            onClosed()
+        }
+    }
+
+    private fun finishReader(claims: List<Claim>) {
+        for (c in claims) {
+            runCatching { c.inReq?.cancel(); c.inReq?.close() }
+            runCatching { c.outReq?.cancel(); c.outReq?.close() }
+            c.inReq = null
+            c.outReq = null
+        }
+    }
+
+    /**
+     * Replay one raw report from the host on the device: kind 0 = output report (Steam's `0x80`
+     * rumble & friends — the active interface's interrupt-OUT, else a `SET_REPORT(Output)`
+     * control transfer), kind 1 = feature report (`SET_REPORT(Feature)`). [data] is the full
+     * report, id byte first, exactly as hidapi framed it host-side.
+     */
+    fun writeRaw(kind: Int, data: ByteArray) {
+        if (data.isEmpty()) return
+        when (kind) {
+            0 -> {
+                if ((activeClaim ?: claims.firstOrNull())?.outReq != null) {
+                    // Interrupt-OUT rides UsbRequests submitted by the reader thread. Bounded,
+                    // newest-wins: these are level-styled commands the host re-sends anyway.
+                    while (outQueue.size >= 32) outQueue.poll()
+                    outQueue.offer(data)
+                } else {
+                    setReport(REPORT_TYPE_OUTPUT, data)
+                }
+            }
+            1 -> setReport(REPORT_TYPE_FEATURE, data)
+        }
+    }
+
+    private fun setReport(type: Int, data: ByteArray) {
+        val conn = connection ?: return
+        val ifId = (activeClaim ?: claims.firstOrNull())?.iface?.id ?: return
+        sendReport(conn, ifId, type, data)
+    }
+
+    private fun configureInputMode(conn: UsbDeviceConnection, ifaceId: Int) {
+        sendFeature(conn, ifaceId, Sc2Device.DISABLE_LIZARD)
+        sendFeature(conn, ifaceId, Sc2Device.NORMALIZE_JOYSTICKS)
+    }
+
+    private fun sendFeature(conn: UsbDeviceConnection, ifaceId: Int, data: ByteArray) {
+        sendReport(conn, ifaceId, REPORT_TYPE_FEATURE, data)
+    }
+
+    /**
+     * HID `SET_REPORT` control transfer with hidapi's report-id framing: a non-zero leading byte
+     * is the report id (sent in wValue AND kept in the payload); a zero leading byte means
+     * "unnumbered" (id 0 in wValue, id byte stripped from the payload). EP0 is independent of
+     * the interrupt endpoints, so this is safe alongside the reader thread's requestWait.
+     */
+    private fun sendReport(conn: UsbDeviceConnection, ifaceId: Int, type: Int, data: ByteArray) {
+        val id = data[0].toInt() and 0xFF
+        val payload = if (id == 0) data.copyOfRange(1, data.size) else data
+        conn.controlTransfer(
+            0x21, // host→device, class, interface
+            0x09, // SET_REPORT
+            (type shl 8) or id,
+            ifaceId,
+            payload,
+            payload.size,
+            WRITE_TIMEOUT_MS,
+        )
+    }
+
+    /** Stop the read loop and release the interfaces. Idempotent; does not fire [onClosed]. */
+    fun stop() {
+        running = false
+        detachReceiver?.let { runCatching { context.unregisterReceiver(it) } }
+        detachReceiver = null
+        runCatching { reader?.join(1000) }
+        reader = null
+        outQueue.clear()
+        activeClaim = null
+        for (c in claims) runCatching { connection?.releaseInterface(c.iface) }
+        claims = emptyList()
+        runCatching { connection?.close() }
+        connection = null
+        device = null
+    }
+
+    private companion object {
+        const val TAG = "Sc2UsbLink"
+        const val READ_TIMEOUT_MS = 100L
+        const val WRITE_TIMEOUT_MS = 250
+        /** Hard `requestWait` ERRORS (not timeouts) persisting this long = the fd is dead. */
+        const val ERROR_UNPLUG_MS = 2000L
+        const val REPORT_TYPE_OUTPUT = 0x02
+        const val REPORT_TYPE_FEATURE = 0x03
+    }
+}
@@ -0,0 +1,626 @@
+//! The event-driven async MediaCodec decode loop (default) + its feeder/dispatch/present helpers.
+
+use ndk::data_space::DataSpace;
+use ndk::media::media_codec::{AsyncNotifyCallback, MediaCodec, MediaCodecDirection};
+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::sync::atomic::{AtomicBool, AtomicI64, Ordering};
+use std::sync::{mpsc, Arc, Mutex};
+use std::time::{Duration, Instant};
+
+use super::display::{
+    apply_hdr_dataspace, install_render_callback, release_render_callback, DisplayTracker,
+};
+use super::latency::{note_decoded_pts, now_realtime_ns, take_flags};
+use super::setup::{
+    android_hdr_static_info, boost_hot_threads, boost_thread_priority, codec_mime,
+    configure_low_latency, create_codec, try_set_frame_rate,
+};
+use super::{DecodeOptions, FRAME_PARK_CAP, IN_FLIGHT_CAP, PENDING_SPLIT_CAP};
+
+/// One decoded output buffer ready to release: its codec buffer index + the pts the codec echoed
+/// (from the output callback's `BufferInfo`), used to pair the `decode` HUD stat, and the
+/// wall-clock instant the output callback fired — the spec's `decoded` point ("decoder output
+/// frame available"), stamped at the callback so the event-channel hop + coalescing wait in the
+/// loop never inflates the decode stage.
+struct OutputReady {
+    index: usize,
+    pts_us: u64,
+    decoded_ns: i128,
+}
+
+/// Events the async decode loop reacts to. The codec's async-notify callbacks (which run on its
+/// 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. 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).
+    OutputAvailable {
+        index: usize,
+        pts_us: u64,
+        decoded_ns: i128,
+    },
+    /// The output format changed — re-check the stream's colour signalling (HDR DataSpace).
+    FormatChanged,
+    /// The codec reported an error; `fatal` when neither recoverable nor transient.
+    Error { fatal: bool },
+}
+
+/// The event-driven async decode loop (default; see [`run`]/[`USE_ASYNC_DECODE`]). The codec drives
+/// us: an async-notify callback fires the instant an input buffer frees or a frame finishes
+/// decoding, so a decoded frame is presented immediately instead of waiting out a poll interval (the
+/// latency the sync loop left on the table). The callbacks run on the codec's internal looper thread
+/// and only *push events* — every `AMediaCodec` buffer op stays on this thread, which owns the codec,
+/// sidestepping the self-reference that would arise from a callback calling back into the codec it's
+/// stored in. A small `pf-decode-feed` thread blocks on the network so this loop never does.
+pub(super) fn run_async(
+    client: Arc<NativeClient>,
+    window: NativeWindow,
+    shutdown: Arc<AtomicBool>,
+    stats: Arc<crate::stats::VideoStats>,
+    opts: DecodeOptions,
+) {
+    let DecodeOptions {
+        decoder_name,
+        ll_feature,
+        low_latency_mode,
+        is_tv,
+    } = opts;
+    boost_thread_priority();
+    let mode = client.mode();
+    let mime = codec_mime(client.codec);
+    let mut codec = match create_codec(mime, decoder_name.as_deref()) {
+        Some(c) => c,
+        None => {
+            log::error!("decode: no {mime} decoder on this device");
+            return;
+        }
+    };
+    let codec_name = codec.name().unwrap_or_default();
+    stats.set_decoder(&codec_name, ll_feature);
+    log::info!(
+        "decode: codec mime = {mime}, decoder = {codec_name} (async, low-latency feature: {ll_feature})"
+    );
+
+    // The event channel: the callbacks + feeder push, this loop pulls. `Sender` is `Send`, so the
+    // callback closures (each capturing a clone) satisfy the async-notify `Send` bound.
+    let (ev_tx, ev_rx) = mpsc::channel::<DecodeEvent>();
+    // Install the callbacks BEFORE configure()/start() so we're in async mode from the first buffer.
+    // Each just forwards an index/flag — no codec access here (the codec owns these closures).
+    {
+        let out_tx = ev_tx.clone();
+        let in_tx = ev_tx.clone();
+        let fmt_tx = ev_tx.clone();
+        let err_tx = ev_tx.clone();
+        let cb = AsyncNotifyCallback {
+            on_input_available: Some(Box::new(move |idx| {
+                let _ = in_tx.send(DecodeEvent::InputAvailable(idx));
+            })),
+            on_output_available: Some(Box::new(move |idx, info| {
+                let _ = out_tx.send(DecodeEvent::OutputAvailable {
+                    index: idx,
+                    pts_us: info.presentation_time_us().max(0) as u64,
+                    // The `decoded` HUD point: stamp HERE, on the codec's looper thread, so the
+                    // decode stage ends when the frame actually became available — not after the
+                    // channel hop + whatever work the loop coalesces in front of presenting it.
+                    decoded_ns: now_realtime_ns(),
+                });
+            })),
+            on_format_changed: Some(Box::new(move |_fmt| {
+                let _ = fmt_tx.send(DecodeEvent::FormatChanged);
+            })),
+            on_error: Some(Box::new(move |e, code, _detail| {
+                let fatal = !code.is_recoverable() && !code.is_transient();
+                if fatal {
+                    log::error!("decode: fatal codec error — stream will stop: {e:?}");
+                } else {
+                    log::warn!("decode: codec error {e:?} (recoverable)");
+                }
+                let _ = err_tx.send(DecodeEvent::Error { fatal });
+            })),
+        };
+        if let Err(e) = codec.set_async_notify_callback(Some(cb)) {
+            log::error!("decode: set_async_notify_callback failed: {e}");
+            return;
+        }
+    }
+
+    // Build the low-latency format (identical keys to the sync path).
+    let mut format = MediaFormat::new();
+    format.set_str("mime", mime);
+    format.set_i32("width", mode.width as i32);
+    format.set_i32("height", mode.height as i32);
+    format.set_i32(
+        "max-input-size",
+        (mode.width * mode.height).max(2_000_000) as i32,
+    );
+    configure_low_latency(&mut format, &codec_name, low_latency_mode);
+    if client.color.is_hdr() {
+        match client.next_hdr_meta(Duration::from_millis(250)) {
+            Ok(meta) => {
+                format.set_buffer("hdr-static-info", &android_hdr_static_info(&meta));
+                log::info!("decode: HDR static metadata applied (KEY_HDR_STATIC_INFO)");
+            }
+            Err(_) => {
+                log::info!("decode: HDR session but no mastering metadata yet — DataSpace only")
+            }
+        }
+    }
+    if let Err(e) = codec.configure(&format, Some(&window), MediaCodecDirection::Decoder) {
+        log::error!("decode: configure failed: {e}");
+        return;
+    }
+    if let Err(e) = codec.start() {
+        log::error!("decode: start failed: {e}");
+        return;
+    }
+    log::info!(
+        "decode: decoder started (async) at {}x{}",
+        mode.width,
+        mode.height
+    );
+    // The forced TV mode switch (`is_tv` ⇒ ALWAYS strategy) is part of the experimental stack;
+    // off, every form factor gets the original soft seamless hint.
+    if mode.refresh_hz > 0
+        && !try_set_frame_rate(&window, mode.refresh_hz as f32, is_tv && low_latency_mode)
+    {
+        log::debug!(
+            "decode: set_frame_rate({} Hz) unavailable/declined (non-fatal)",
+            mode.refresh_hz
+        );
+    }
+
+    // Skew-corrected latency stats (spec: design/stats-unification.md). Receipt stamps (keyed by the
+    // pts we queue) live in a shared map: the feeder writes them at receipt, this loop pairs decoded
+    // output back to them. Behind a `Mutex` since two threads touch it — only ever locked while the
+    // HUD is visible.
+    let clock_offset = client.clock_offset_shared();
+    // Whether the adaptive-bitrate controller wants the `decode` stage as its decoder-backlog
+    // signal (Automatic, non-PyroWave): then `in_flight` is fed regardless of the HUD.
+    let measure_decode = client.wants_decode_latency();
+    let in_flight = Arc::new(Mutex::new(VecDeque::<(u64, i128)>::new()));
+    // Display stage (spec `display` + the capture→displayed headline): the rendered frame is
+    // parked in the tracker at release; the OnFrameRendered callback pairs it with
+    // SurfaceFlinger's render timestamp. `render_cb` is the callback's leaked Arc refcount,
+    // reclaimed after the codec is dropped below.
+    let tracker = DisplayTracker::new(stats.clone(), clock_offset.clone());
+    let render_cb = install_render_callback(&codec, &tracker);
+
+    // Feeder thread: block on the network so this loop doesn't (an AU's arrival becomes an event that
+    // wakes us immediately, with no input-side poll latency). It also records the `received` HUD stat.
+    let feeder = {
+        let client = client.clone();
+        let stats = stats.clone();
+        let in_flight = in_flight.clone();
+        let clock_offset = clock_offset.clone();
+        let shutdown = shutdown.clone();
+        let ev_tx = ev_tx.clone();
+        std::thread::Builder::new()
+            .name("pf-decode-feed".into())
+            .spawn(move || {
+                feeder_loop(
+                    client,
+                    stats,
+                    measure_decode,
+                    in_flight,
+                    clock_offset,
+                    shutdown,
+                    ev_tx,
+                );
+            })
+            .ok()
+    };
+    drop(ev_tx); // only the feeder + callbacks keep the channel alive now
+
+    // ADPF: same as the sync path — register this thread now, create the session lazily on the first
+    // presented frame (by when the pump + audio + feeder threads have registered their tids too).
+    let frame_period_ns = if mode.refresh_hz > 0 {
+        1_000_000_000i64 / mode.refresh_hz as i64
+    } else {
+        0
+    };
+    client.register_hot_thread();
+    let mut hint: Option<crate::adpf::HintSession> = None;
+    let mut hint_tried = false;
+
+    let mut free_inputs: VecDeque<usize> = VecDeque::new();
+    let mut pending_aus: VecDeque<Frame> = VecDeque::new();
+    let mut ready: Vec<OutputReady> = Vec::new();
+    let mut applied_ds: Option<DataSpace> = None;
+    let mut fed: u64 = 0;
+    let mut rendered: u64 = 0;
+    let mut discarded: u64 = 0;
+    // AUs larger than the codec input buffer, dropped whole (see `feed`/`feed_ready`).
+    let mut oversized_dropped: u64 = 0;
+    // 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.
+    let mut work_accum_ns: i64 = 0;
+    let mut fatal = false;
+
+    while !shutdown.load(Ordering::Relaxed) && !fatal {
+        // Block for the next event (idle wait — excluded from the work tally). The short timeout
+        // drives loss-recovery housekeeping when the pipeline is momentarily quiet.
+        let ev0 = match ev_rx.recv_timeout(Duration::from_millis(5)) {
+            Ok(ev) => Some(ev),
+            Err(mpsc::RecvTimeoutError::Timeout) => None,
+            Err(mpsc::RecvTimeoutError::Disconnected) => break,
+        };
+        let work_t0 = Instant::now();
+        let mut fmt_dirty = false;
+        let mut aus_dropped: u64 = 0;
+        if let Some(ev) = ev0 {
+            aus_dropped += u64::from(dispatch_event(
+                ev,
+                &mut pending_aus,
+                &mut free_inputs,
+                &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
+        // presentation across a decode burst, and batched feeding.
+        while let Ok(ev) = ev_rx.try_recv() {
+            aus_dropped += u64::from(dispatch_event(
+                ev,
+                &mut pending_aus,
+                &mut free_inputs,
+                &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
+        if fmt_dirty {
+            apply_hdr_dataspace(&codec, &window, &mut applied_ds);
+        }
+        feed_ready(
+            &codec,
+            &client,
+            &mut pending_aus,
+            &mut free_inputs,
+            &mut fed,
+            &mut oversized_dropped,
+        );
+        let had_output = !ready.is_empty();
+        present_ready(
+            &codec,
+            &client,
+            measure_decode,
+            &mut ready,
+            &stats,
+            &in_flight,
+            clock_offset.load(Ordering::Relaxed),
+            &tracker,
+            &mut rendered,
+            &mut discarded,
+            &mut gate,
+            &mut recovery_flags,
+        );
+
+        work_accum_ns += work_t0.elapsed().as_nanos() as i64;
+        if had_output {
+            if !hint_tried {
+                hint_tried = true;
+                let tids = client.hot_thread_ids();
+                // The pump/audio priority boost is part of the experimental low-latency stack; the
+                // ADPF session itself predates it and always runs (max-performance bias gated inside).
+                if low_latency_mode {
+                    boost_hot_threads(&tids);
+                }
+                hint = crate::adpf::HintSession::create(frame_period_ns, &tids, low_latency_mode);
+                log::info!(
+                    "decode: ADPF hint session {} — {} hot thread(s), target {frame_period_ns} ns",
+                    if hint.is_some() {
+                        "active"
+                    } else {
+                        "unavailable"
+                    },
+                    tids.len(),
+                );
+            }
+            if let Some(h) = &hint {
+                h.report_actual(work_accum_ns);
+            }
+            work_accum_ns = 0;
+            if rendered > 0 && rendered % 300 == 0 {
+                log::info!("decode: fed={fed} rendered={rendered} discarded={discarded}");
+            }
+        }
+        // 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();
+        }
+    }
+
+    let _ = codec.stop();
+    shutdown.store(true, Ordering::SeqCst); // ensure the feeder wakes and exits, then join it
+    if let Some(j) = feeder {
+        let _ = j.join();
+    }
+    drop(codec); // AMediaCodec_delete — after this no render callback can fire
+    if let Some(ud) = render_cb {
+        // SAFETY: the codec was dropped above; this registration's single reclaim.
+        unsafe { release_render_callback(ud) };
+    }
+    log::info!("decode: stopped (async, fed={fed} rendered={rendered} discarded={discarded})");
+}
+
+/// The `pf-decode-feed` thread: block on the connector for the next access unit so the async loop
+/// never has to. Records the `received` HUD stat (receipt point) — including the Phase-2 host/network
+/// split from any matching 0xCF host timings — then hands the AU to the loop via the event channel.
+/// Exits when `shutdown` is set, the session closes, or the loop's receiver is gone.
+fn feeder_loop(
+    client: Arc<NativeClient>,
+    stats: Arc<crate::stats::VideoStats>,
+    measure_decode: bool,
+    in_flight: Arc<Mutex<VecDeque<(u64, i128)>>>,
+    clock_offset: Arc<AtomicI64>,
+    shutdown: Arc<AtomicBool>,
+    ev_tx: mpsc::Sender<DecodeEvent>,
+) {
+    // Received AUs awaiting their 0xCF host timing (Phase-2 split), as (pts_ns, capture→received µs).
+    let mut pending_split: VecDeque<(u64, u64)> = VecDeque::new();
+    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);
+                // Park the receipt stamp (keyed by the pts the codec echoes) whenever the `decode`
+                // stage is consumed: the HUD, or the ABR decode signal (`measure_decode`). The
+                // HUD-only `received` point + host/network split stay gated on the overlay.
+                if stats.enabled() || measure_decode {
+                    let received_ns = now_realtime_ns();
+                    {
+                        let mut g = in_flight
+                            .lock()
+                            .unwrap_or_else(std::sync::PoisonError::into_inner);
+                        g.push_back((frame.pts_ns / 1000, received_ns));
+                        if g.len() > IN_FLIGHT_CAP {
+                            g.pop_front(); // stale — codec never echoed it back
+                        }
+                    }
+                    if stats.enabled() {
+                        let clock_offset = clock_offset.load(Ordering::Relaxed) as i128;
+                        let lat_ns = received_ns + clock_offset - frame.pts_ns as i128;
+                        let lat_us = (lat_ns > 0 && lat_ns < 10_000_000_000)
+                            .then_some((lat_ns / 1000) as u64);
+                        stats.note_received(frame.data.len(), lat_us, clock_offset != 0);
+                        if let Some(hostnet_us) = lat_us {
+                            pending_split.push_back((frame.pts_ns, hostnet_us));
+                            if pending_split.len() > PENDING_SPLIT_CAP {
+                                pending_split.pop_front();
+                            }
+                        }
+                        while let Ok(t) = client.next_host_timing(Duration::ZERO) {
+                            if let Some(i) = pending_split.iter().position(|&(p, _)| p == t.pts_ns)
+                            {
+                                let (_, hostnet_us) = pending_split.remove(i).unwrap();
+                                stats.note_host_split(
+                                    t.host_us as u64,
+                                    hostnet_us.saturating_sub(t.host_us as u64),
+                                );
+                            }
+                        }
+                    }
+                }
+                if ev_tx.send(DecodeEvent::Au(frame, gap)).is_err() {
+                    break; // the decode loop is gone
+                }
+            }
+            Err(PunktfunkError::NoFrame) => {} // timeout — re-check shutdown and poll again
+            Err(_) => break,                   // session closed
+        }
+    }
+}
+
+/// 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>,
+    free_inputs: &mut VecDeque<usize>,
+    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, 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
+                return true;
+            }
+        }
+        DecodeEvent::InputAvailable(i) => free_inputs.push_back(i),
+        DecodeEvent::OutputAvailable {
+            index,
+            pts_us,
+            decoded_ns,
+        } => ready.push(OutputReady {
+            index,
+            pts_us,
+            decoded_ns,
+        }),
+        DecodeEvent::FormatChanged => *fmt_dirty = true,
+        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());
+            }
+        }
+    }
+    false
+}
+
+/// Queue as many parked AUs as there are free input buffer slots (async mode: the indices come from
+/// `InputAvailable` callbacks, not a dequeue). Each AU is copied into its codec input buffer and
+/// submitted; an AU larger than the buffer is DROPPED (+ a recovery keyframe requested) — a
+/// truncated AU is corrupt input the decoder chews on silently, poisoning the reference chain.
+fn feed_ready(
+    codec: &MediaCodec,
+    client: &NativeClient,
+    pending_aus: &mut VecDeque<Frame>,
+    free_inputs: &mut VecDeque<usize>,
+    fed: &mut u64,
+    oversized_dropped: &mut u64,
+) {
+    while !pending_aus.is_empty() && !free_inputs.is_empty() {
+        let idx = free_inputs.pop_front().unwrap();
+        let frame = pending_aus.pop_front().unwrap();
+        let pts_us = frame.pts_ns / 1000;
+        let Some(dst) = codec.input_buffer(idx) else {
+            log::warn!("decode: input_buffer({idx}) returned None — dropping AU");
+            continue;
+        };
+        let au = &frame.data;
+        if au.len() > dst.len() {
+            // The slot was never queued, so it stays ours — recycle it for the next AU.
+            free_inputs.push_front(idx);
+            *oversized_dropped += 1;
+            log::warn!(
+                "decode: AU {} > input buffer {} — dropped ({} so far), requesting keyframe",
+                au.len(),
+                dst.len(),
+                *oversized_dropped
+            );
+            let _ = client.request_keyframe();
+            continue;
+        }
+        let n = au.len();
+        // SAFETY: `au` (wire AU) and `dst` (codec input buffer) are distinct allocations, both valid
+        // for `n` bytes; `MaybeUninit<u8>` is layout-identical to `u8`, so this initializes dst[..n].
+        unsafe {
+            std::ptr::copy_nonoverlapping(au.as_ptr(), dst.as_mut_ptr().cast::<u8>(), n);
+        }
+        if let Err(e) = codec.queue_input_buffer_by_index(idx, 0, n, pts_us, 0) {
+            log::warn!("decode: queue_input_buffer_by_index: {e}");
+        } else {
+            *fed += 1;
+        }
+    }
+}
+
+/// Present only the NEWEST ready output (render = true) and release the rest without rendering — a
+/// burst of stale frames on glass is worse than skipping to the freshest (the sync loop's newest-ready
+/// policy, callback-driven). Every dequeued buffer, rendered or not, is the HUD's `decoded`
+/// measurement point (it finished decoding either way); samples are recorded in pts order so the
+/// receipt-map eviction stays monotonic. The presented frame's `(pts, decoded stamp)` is parked in
+/// `tracker` for the OnFrameRendered callback — the `display` stage's other endpoint. `ready` is
+/// drained.
+#[allow(clippy::too_many_arguments)] // one call site; mirrors the sync loop's drain
+fn present_ready(
+    codec: &MediaCodec,
+    client: &NativeClient,
+    measure_decode: bool,
+    ready: &mut Vec<OutputReady>,
+    stats: &crate::stats::VideoStats,
+    in_flight: &Mutex<VecDeque<(u64, i128)>>,
+    clock_offset: i64,
+    tracker: &DisplayTracker,
+    rendered: &mut u64,
+    discarded: &mut u64,
+    gate: &mut ReanchorGate,
+    recovery_flags: &mut VecDeque<(u64, u32)>,
+) {
+    if ready.is_empty() {
+        return;
+    }
+    // Pair each output's decode stage (feeds the ABR decode signal always; the HUD histogram only
+    // while visible) — both consume the receipt map, so enter for either.
+    if stats.enabled() || measure_decode {
+        let mut g = in_flight
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        for o in ready.iter() {
+            note_decoded_pts(
+                client,
+                measure_decode,
+                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 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;
+                if stats.enabled() {
+                    tracker.note_rendered(o.pts_us, o.decoded_ns);
+                }
+            }
+            Ok(()) => {
+                *discarded += 1;
+                skipped += 1;
+            }
+            Err(e) => {
+                log::warn!(
+                    "decode: release_output_buffer_by_index({}, {render}): {e}",
+                    o.index
+                )
+            }
+        }
+    }
+    stats.note_skipped(skipped); // HUD `skipped` counter (newest-wins + held-off drops); no-op hidden
+}
@@ -0,0 +1,224 @@
+//! Display/frame-rendered tracking, render-callback registration, HDR dataspace mapping.
+
+use ndk::data_space::DataSpace;
+use ndk::media::media_codec::MediaCodec;
+use ndk::native_window::NativeWindow;
+use std::collections::VecDeque;
+use std::ffi::c_void;
+use std::sync::atomic::{AtomicI64, Ordering};
+use std::sync::{Arc, Mutex};
+
+use super::latency::now_realtime_ns;
+use super::RENDERED_CAP;
+
+/// `CLOCK_MONOTONIC` now in nanoseconds — the base of the `systemNano` render timestamp the
+/// `OnFrameRendered` callback reports (Android's `System.nanoTime`), read only to re-base that
+/// stamp onto `CLOCK_REALTIME` (see [`on_frame_rendered`]).
+fn now_monotonic_ns() -> i128 {
+    let mut ts = libc::timespec {
+        tv_sec: 0,
+        tv_nsec: 0,
+    };
+    // SAFETY: `clock_gettime` with a valid out-pointer is an always-safe syscall.
+    unsafe { libc::clock_gettime(libc::CLOCK_MONOTONIC, &mut ts) };
+    ts.tv_sec as i128 * 1_000_000_000 + ts.tv_nsec as i128
+}
+
+/// State shared between the decode loop and the `AMediaCodec` `OnFrameRendered` callback (which
+/// fires on a codec-internal thread): rendered frames awaiting their render timestamp, so the HUD
+/// gets the spec's `display` stage (decoded→displayed) and the `capture→displayed` end-to-end
+/// headline (`design/stats-unification.md` — this replaces Android's v1 `capture→decoded`
+/// endpoint whenever the platform delivers render callbacks).
+pub(super) struct DisplayTracker {
+    stats: Arc<crate::stats::VideoStats>,
+    /// Live host-minus-client clock offset (ns) for the skew-corrected end-to-end sample —
+    /// loaded per callback so mid-stream re-syncs apply. Holding the handle (not the client)
+    /// keeps the leaked render-callback refcount from pinning the whole session alive.
+    clock_offset: Arc<AtomicI64>,
+    /// `(pts_us, decoded_real_ns)` of frames released with `render = true`, in release order,
+    /// awaiting their callback. Pushes are HUD-gated by the caller, so this stays empty (and the
+    /// callback early-outs) while the overlay is hidden.
+    rendered: Mutex<VecDeque<(u64, i128)>>,
+}
+
+impl DisplayTracker {
+    pub(super) fn new(
+        stats: Arc<crate::stats::VideoStats>,
+        clock_offset: Arc<AtomicI64>,
+    ) -> Arc<DisplayTracker> {
+        Arc::new(DisplayTracker {
+            stats,
+            clock_offset,
+            rendered: Mutex::new(VecDeque::new()),
+        })
+    }
+
+    /// Park one just-rendered frame's `(pts, decoded stamp)` for the render callback to pair.
+    /// Caller gates on the HUD being visible.
+    pub(super) fn note_rendered(&self, pts_us: u64, decoded_ns: i128) {
+        let mut g = self
+            .rendered
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        g.push_back((pts_us, decoded_ns));
+        if g.len() > RENDERED_CAP {
+            g.pop_front(); // render callbacks stopped coming (allowed under load) — evict
+        }
+    }
+}
+
+/// Register [`on_frame_rendered`] on the codec (`AMediaCodec_setOnFrameRenderedCallback`,
+/// **API 33** — "Available since Android T" per the NDK header; only the *Java* listener dates
+/// back further). That sits above the API-28 floor, so the entry point is dlsym-resolved at
+/// runtime like [`try_set_frame_rate`] — hard-linking it (as 0.9.0 shipped) made
+/// `System.loadLibrary` fail on every pre-Android-13 device, taking down all of `NativeBridge`.
+/// The `ndk` wrapper has no binding and the call needs the raw codec pointer, which is what the
+/// vendored crate's public `as_ptr` patch is for. Returns the userdata pointer holding a leaked
+/// `Arc<DisplayTracker>` refcount; the caller MUST reclaim it with [`release_render_callback`]
+/// AFTER dropping the codec (`AMediaCodec_delete` is what guarantees no further callback can
+/// fire). `None` (nothing to reclaim) if the symbol is absent (API < 33) or the platform refused —
+/// the HUD then simply has no `display` stage, exactly the pre-callback behaviour.
+pub(super) fn install_render_callback(
+    codec: &MediaCodec,
+    tracker: &Arc<DisplayTracker>,
+) -> Option<*const DisplayTracker> {
+    // media_status_t AMediaCodec_setOnFrameRenderedCallback(
+    //     AMediaCodec*, AMediaCodecOnFrameRendered, void*)                            (API 33)
+    type SetOnFrameRenderedFn = unsafe extern "C" fn(
+        *mut ndk_sys::AMediaCodec,
+        ndk_sys::AMediaCodecOnFrameRendered,
+        *mut c_void,
+    ) -> ndk_sys::media_status_t;
+    // SAFETY: `dlopen` of `libmediandk.so`, which the `ndk` media wrapper already links — always
+    // mapped, so this only bumps its refcount (never closed — process-lifetime handle). `dlsym`
+    // returns null when the symbol is absent (device below API 33), checked before transmuting the
+    // non-null pointer to its fn-pointer type.
+    let set_on_frame_rendered = unsafe {
+        let lib = libc::dlopen(c"libmediandk.so".as_ptr(), libc::RTLD_NOW);
+        if lib.is_null() {
+            return None;
+        }
+        let sym = libc::dlsym(lib, c"AMediaCodec_setOnFrameRenderedCallback".as_ptr());
+        if sym.is_null() {
+            log::info!("decode: no render callback on this API level (<33) — no display stage");
+            return None;
+        }
+        std::mem::transmute::<*mut c_void, SetOnFrameRenderedFn>(sym)
+    };
+    let ud = Arc::into_raw(tracker.clone());
+    // SAFETY: `codec.as_ptr()` is the live codec this thread owns; `ud` outlives the registration
+    // (reclaimed only after the codec is deleted, per this function's contract).
+    let status = unsafe {
+        set_on_frame_rendered(codec.as_ptr(), Some(on_frame_rendered), ud as *mut c_void)
+    };
+    if status == ndk_sys::media_status_t::AMEDIA_OK {
+        Some(ud)
+    } else {
+        log::warn!("decode: setOnFrameRenderedCallback failed ({status:?}) — no display stage");
+        // SAFETY: registration failed, so the codec never took the reference — reclaim it now.
+        unsafe { drop(Arc::from_raw(ud)) };
+        None
+    }
+}
+
+/// Reclaim [`install_render_callback`]'s leaked `Arc` refcount.
+///
+/// # Safety
+/// Call exactly once, and only after the codec the callback was registered on has been dropped —
+/// deleting the codec stops its internal threads, so no callback can still be running (or run
+/// later) against this pointer.
+pub(super) unsafe fn release_render_callback(ud: *const DisplayTracker) {
+    drop(Arc::from_raw(ud));
+}
+
+/// The `AMediaCodecOnFrameRendered` trampoline: fires (possibly batched) on a codec-internal
+/// thread once per output frame actually placed on the output surface, with SurfaceFlinger's
+/// render timestamp. That timestamp (`system_nano`) is on `CLOCK_MONOTONIC`, so it is re-based
+/// onto `CLOCK_REALTIME` here — against monotonic-now at callback time, which also cancels any lag
+/// between the frame rendering and the (batchable) callback delivery — to subtract against the
+/// receipt/decode stamps and the host capture pts. Records the HUD's `displayed` point:
+/// `end-to-end` = capture→displayed (skew-corrected) and `display` = decoded→displayed
+/// (single-clock local). Panic-free by construction (poison-proof lock, saturating math) — an
+/// unwind out of an `extern "C"` fn would abort the process.
+unsafe extern "C" fn on_frame_rendered(
+    _codec: *mut ndk_sys::AMediaCodec,
+    userdata: *mut c_void,
+    media_time_us: i64,
+    system_nano: i64,
+) {
+    let t = &*(userdata as *const DisplayTracker);
+    if !t.stats.enabled() {
+        return; // HUD hidden — the ring is empty too (pushes are caller-gated)
+    }
+    let displayed_ns = now_realtime_ns() - (now_monotonic_ns() - system_nano as i128);
+    let pts_us = media_time_us.max(0) as u64;
+    // Pair the frame back to its release record, evicting older entries (their callbacks were
+    // dropped by the platform, or the entry predates a HUD toggle) — same monotonic-eviction
+    // discipline as `note_decoded_pts`.
+    let mut decoded_ns = None;
+    {
+        let mut g = t
+            .rendered
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        while let Some(&(p, d)) = g.front() {
+            if p > pts_us {
+                break; // future frame — leave it for its own callback
+            }
+            g.pop_front();
+            if p == pts_us {
+                decoded_ns = Some(d);
+                break;
+            }
+        }
+    }
+    let e2e_ns =
+        displayed_ns + t.clock_offset.load(Ordering::Relaxed) as i128 - pts_us as i128 * 1000;
+    let e2e_us = (e2e_ns > 0 && e2e_ns < 10_000_000_000).then_some((e2e_ns / 1000) as u64);
+    let display_us = decoded_ns.map(|d| ((displayed_ns - d).max(0) / 1000) as u64);
+    t.stats.note_displayed(e2e_us, display_us);
+}
+
+/// React to an output-format change by signalling the stream's HDR dataspace on the Surface (SDR
+/// streams leave the default alone). The AMediaCodec analogue of the sync loop's `OutputFormatChanged`
+/// handling; safe to call repeatedly (`applied_ds` dedups).
+pub(super) fn apply_hdr_dataspace(
+    codec: &MediaCodec,
+    window: &NativeWindow,
+    applied_ds: &mut Option<DataSpace>,
+) {
+    if let Some(ds) = hdr_dataspace(codec) {
+        if *applied_ds != Some(ds) {
+            match window.set_buffers_data_space(ds) {
+                Ok(()) => {
+                    *applied_ds = Some(ds);
+                    log::info!("decode: HDR stream → Surface dataspace {ds}");
+                }
+                Err(e) => {
+                    log::warn!("decode: set_buffers_data_space({ds}) failed (non-fatal): {e}")
+                }
+            }
+        }
+    }
+}
+
+/// 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).
+pub(super) fn hdr_dataspace(codec: &MediaCodec) -> Option<DataSpace> {
+    let fmt = codec.output_format();
+    let full_range = fmt.i32("color-range") == Some(1);
+    match fmt.i32("color-transfer") {
+        Some(6) => Some(if full_range {
+            DataSpace::Bt2020Pq
+        } else {
+            DataSpace::Bt2020ItuPq
+        }),
+        Some(7) => Some(if full_range {
+            DataSpace::Bt2020Hlg
+        } else {
+            DataSpace::Bt2020ItuHlg
+        }),
+        _ => None, // SDR (BT.709 / SDR_VIDEO) or unspecified
+    }
+}
@@ -0,0 +1,83 @@
+//! Decode-latency bookkeeping: realtime clock + decoded-pts / user-flags stat recording.
+
+use punktfunk_core::client::NativeClient;
+use std::collections::VecDeque;
+
+/// Wall-clock now in nanoseconds (CLOCK_REALTIME basis), to compare against the host-stamped
+/// capture `pts_ns` after the skew offset is applied.
+pub(super) fn now_realtime_ns() -> i128 {
+    use std::time::{SystemTime, UNIX_EPOCH};
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_nanos() as i128)
+        .unwrap_or(0)
+}
+
+/// HUD `decoded` point for one dequeued output frame, keyed by the echoed `presentationTimeUs`:
+/// build the end-to-end (capture→decoded, skew-corrected, clamped to (0, 10 s)) and `decode`
+/// (received→decoded, single-clock local, ≥ 0) samples and hand them to
+/// [`crate::stats::VideoStats::note_decoded`]. The pts keys the receipt stamp in `in_flight`;
+/// entries older than it are evicted (decode order == input order here — low-latency, no
+/// B-frames — so anything before it was dropped inside the codec or stamped before a flush).
+/// `decoded_ns` is the availability instant: the dequeue (sync loop) or the output callback's
+/// stamp (async loop).
+pub(super) fn note_decoded_pts(
+    client: &NativeClient,
+    measure_decode: bool,
+    stats: &crate::stats::VideoStats,
+    in_flight: &mut VecDeque<(u64, i128)>,
+    clock_offset: i64,
+    pts_us: u64,
+    decoded_ns: i128,
+) {
+    // Pair the echoed pts back to its receipt stamp, evicting stale (older) entries as we go.
+    let mut received_ns = None;
+    while let Some(&(p, r)) = in_flight.front() {
+        if p > pts_us {
+            break; // future frame — leave it for its own output buffer
+        }
+        in_flight.pop_front();
+        if p == pts_us {
+            received_ns = Some(r);
+            break;
+        }
+    }
+    let decode_us = received_ns.map(|r| ((decoded_ns - r).max(0) / 1000) as u64);
+    // Adaptive bitrate: the `decode` stage (received→decoded, single-clock local) IS the decoder-
+    // backlog signal — the only bottleneck the host-side network signals can't see (a fast LAN
+    // feeding a slower mobile decoder). Report it whenever the controller is armed, regardless of
+    // the HUD; `report_decode_us` is a cheap accumulate the pump windows.
+    if measure_decode {
+        if let Some(us) = decode_us {
+            client.report_decode_us(us.min(u32::MAX as u64) as u32);
+        }
+    }
+    // HUD histogram: only while the overlay is visible (a measure-only caller enters here for the
+    // ABR report alone). `end-to-end` = capture→decoded (skew-corrected) tiles the `decode` stage.
+    // pts_us is the truncated frame.pts_ns/1000 we queued, so ×1000 re-approximates capture time to
+    // < 1 µs — negligible against the ms-scale figures shown.
+    if stats.enabled() {
+        let e2e_ns = decoded_ns + clock_offset as i128 - pts_us as i128 * 1000;
+        let e2e_us = (e2e_ns > 0 && e2e_ns < 10_000_000_000).then_some((e2e_ns / 1000) as u64);
+        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.
+pub(super) 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
+}
@@ -0,0 +1,84 @@
+//! Android video decode (android-only): pull HEVC access units from the connector and render them
+//! to the SurfaceView via NDK `AMediaCodec` — hardware decode, zero per-frame JNI.
+//!
+//! One-in/one-out: the host opens every stream with an IDR carrying VPS/SPS/PPS **in-band**, so the
+//! decoder needs no out-of-band codec-specific data — we configure with mime + the negotiated
+//! WxH (from [`NativeClient::mode`]) and feed each access unit as it arrives. The decode thread owns
+//! the codec + window for its whole life; [`crate::session`] signals it to stop via the shared flag.
+
+mod async_loop;
+mod display;
+mod latency;
+mod setup;
+mod sync_loop;
+
+use async_loop::run_async;
+pub(crate) use setup::{codec_label, codec_mime};
+use sync_loop::run_sync;
+
+use ndk::native_window::NativeWindow;
+use punktfunk_core::client::NativeClient;
+use std::sync::atomic::AtomicBool;
+use std::sync::Arc;
+
+/// Cap on AUs parked in the async loop awaiting a free codec input slot. Matches the connector's
+/// own frame-channel depth; on sustained overflow the oldest is dropped and a keyframe requested
+/// (same recovery as a reassembler drop). In steady state this stays near-empty.
+const FRAME_PARK_CAP: usize = 16;
+
+/// Cap on the pts→received-timestamp map below: MediaCodec holds only a handful of frames in
+/// flight, so anything beyond this is stale (codec flushed / HUD toggled) and gets evicted.
+const IN_FLIGHT_CAP: usize = 64;
+
+/// Cap on received AUs awaiting their 0xCF host timing (Phase 2 host/network split): the timing
+/// datagram trails its AU by at most the wire, so a match lands within a frame or two — anything
+/// this deep is a lost datagram (or an old host that never sends any) and gets evicted.
+const PENDING_SPLIT_CAP: usize = 256;
+
+/// Cap on rendered frames parked in [`DisplayTracker`] awaiting their `OnFrameRendered` render
+/// timestamp: the callback trails its release by at most a vsync or two, so anything this deep
+/// means the platform stopped delivering render callbacks (allowed under load, per the docs) and
+/// gets evicted.
+const RENDERED_CAP: usize = 64;
+
+/// Whether low-latency mode uses the event-driven async decode loop (default) or the synchronous
+/// poll loop. Flip to `false` to A/B the two on the HUD (`design/…`); the async loop presents a
+/// decoded frame the instant it's ready instead of waiting out a poll interval. Only consulted when
+/// the user's "Low-latency mode" toggle is ON (now the default) — off, the sync loop always runs (the
+/// original pipeline, kept as the per-device escape hatch).
+const USE_ASYNC_DECODE: bool = true;
+
+/// Per-session decode configuration, resolved by the JNI layer (`nativeStartVideo`) and passed to
+/// the decode loop. Bundled so the loop entry points don't sprout a wide argument list.
+pub(crate) struct DecodeOptions {
+    /// The decoder Kotlin ranked from `MediaCodecList` (`VideoDecoders.pickDecoder`). `None`/empty ⇒
+    /// let the platform resolve the default decoder for the MIME.
+    pub decoder_name: Option<String>,
+    /// Whether Kotlin found the chosen decoder advertises `FEATURE_LowLatency` (queryable only via
+    /// the Java `CodecCapabilities` API) — surfaced on the HUD next to the decoder name.
+    pub ll_feature: bool,
+    /// The user's "Low-latency mode" master toggle. On (default) ⇒ the full fast pipeline: async
+    /// decode loop, per-SoC vendor keys, pipeline thread boosts, ADPF max-performance, forced TV
+    /// mode switch. Off ⇒ the original synchronous pre-overhaul pipeline, kept as the per-device
+    /// escape hatch.
+    pub low_latency_mode: bool,
+    /// TV form factor (Kotlin's `UiModeManager`): actively drive the HDMI output into the stream's
+    /// refresh mode, vs. the softer seamless hint on a phone/tablet.
+    pub is_tv: bool,
+}
+
+/// The decode entry point on the `pf-decode` thread: dispatches to the async or synchronous loop.
+/// Both run until `shutdown` is set or the session closes.
+pub fn run(
+    client: Arc<NativeClient>,
+    window: NativeWindow,
+    shutdown: Arc<AtomicBool>,
+    stats: Arc<crate::stats::VideoStats>,
+    opts: DecodeOptions,
+) {
+    if opts.low_latency_mode && USE_ASYNC_DECODE {
+        run_async(client, window, shutdown, stats, opts);
+    } else {
+        run_sync(client, window, shutdown, stats, opts);
+    }
+}
@@ -0,0 +1,254 @@
+//! Codec creation, low-latency config, thread/frame-rate tuning, HDR static-info encode.
+
+use ndk::media::media_codec::MediaCodec;
+use ndk::media::media_format::MediaFormat;
+use ndk::native_window::NativeWindow;
+use std::ffi::c_void;
+
+/// The MediaCodec MIME for the codec the host resolved (`Welcome.codec`). Shared by the decode
+/// thread and `nativeVideoMime` (which tells Kotlin what to rank decoders for). AV1 uses the
+/// AOSP `video/av01` type; anything not H.264/AV1 is treated as HEVC (every pre-negotiation host
+/// emitted HEVC).
+pub(crate) fn codec_mime(codec: u8) -> &'static str {
+    match codec {
+        punktfunk_core::quic::CODEC_H264 => "video/avc",
+        punktfunk_core::quic::CODEC_AV1 => "video/av01",
+        _ => "video/hevc",
+    }
+}
+
+/// A short human label for the codec the host resolved, for the stats HUD's video-feed line
+/// (`"H.264"` / `"HEVC"` / `"AV1"` / `"PyroWave"`). Mirrors [`codec_mime`]'s fallback: anything
+/// not H.264/AV1/PyroWave is reported as HEVC (every pre-negotiation host emitted HEVC). Kept
+/// beside [`codec_mime`] because the MIME collapses PyroWave onto `video/hevc` and so can't name it.
+pub(crate) fn codec_label(codec: u8) -> &'static str {
+    match codec {
+        punktfunk_core::quic::CODEC_H264 => "H.264",
+        punktfunk_core::quic::CODEC_AV1 => "AV1",
+        punktfunk_core::quic::CODEC_PYROWAVE => "PyroWave",
+        _ => "HEVC",
+    }
+}
+
+/// Create the decoder: prefer the specific codec Kotlin ranked from `MediaCodecList`
+/// (`from_codec_name`), falling back to the platform's default decoder for the MIME
+/// (`from_decoder_type`) if that name can't be created (codec busy / renamed across an OS update).
+pub(super) fn create_codec(mime: &str, preferred: Option<&str>) -> Option<MediaCodec> {
+    if let Some(name) = preferred.filter(|n| !n.is_empty()) {
+        if let Some(c) = MediaCodec::from_codec_name(name) {
+            return Some(c);
+        }
+        log::warn!(
+            "decode: from_codec_name({name}) failed — falling back to default {mime} decoder"
+        );
+    }
+    MediaCodec::from_decoder_type(mime)
+}
+
+/// Apply the low-latency MediaFormat keys for `codec_name`.
+///
+/// `aggressive` = the "Low-latency mode" master toggle. **Off** ⇒ the pre-overhaul key set,
+/// byte-for-byte — the standard `low-latency` key, the blind Qualcomm vendor twin, `priority = 0` AND
+/// `operating-rate = MAX` set together — kept as the per-device escape hatch (the profile every device
+/// streamed with before the overhaul). **On** (default) ⇒ the Moonlight-parity
+/// profile: MediaTek's `vdec-lowlatency` (unconditionally — ignored off MediaTek), the per-SoC
+/// vendor extension keys (gated on the decoder-name prefix the way Moonlight-Android does, since a
+/// key one vendor honours is meaningless on another), and one *mutually exclusive* clock hint.
+///
+/// Vendor keys mirror Moonlight's `MediaCodecHelper` (verified against current source): Qualcomm
+/// picture-order + low-latency, Exynos (also Google Tensor), Amlogic, HiSilicon, MediaTek. NVIDIA
+/// Tegra / Rockchip / Realtek expose no such key (nor does Moonlight) — they're covered by the
+/// standard key + clock hint + being ranked first in `VideoDecoders`.
+pub(super) fn configure_low_latency(format: &mut MediaFormat, codec_name: &str, aggressive: bool) {
+    // Standard key: request the no-reorder low-latency path where the platform decoder supports it.
+    format.set_i32("low-latency", 1);
+    if !aggressive {
+        // The original profile: the Qualcomm vendor twin set blind (unknown keys are ignored by
+        // other vendors' codecs), realtime priority, and the AOSP "unbounded" operating-rate
+        // sentinel — decode each frame at max clocks rather than pacing to the frame rate.
+        format.set_i32("vendor.qti-ext-dec-low-latency.enable", 1);
+        format.set_i32("priority", 0); // 0 = realtime
+        format.set_i32("operating-rate", i16::MAX as i32); // 32767 = "as fast as possible"
+        return;
+    }
+    // MediaTek's low-latency key — very common (mid/budget phones + many Google TV / Fire TV boxes).
+    // Set unconditionally like the standard key: MediaTek decoders honour it, others ignore it, so it
+    // covers MediaTek whatever the exact decoder name (omx.mtk / c2.mtk / an OEM rename). Moonlight
+    // does the same, and also relies on it for Amazon's Amlogic fork.
+    format.set_i32("vdec-lowlatency", 1);
+    let name = codec_name.to_ascii_lowercase();
+    let is = |prefix: &str| name.starts_with(prefix);
+    // Qualcomm Snapdragon (the most common phone SoC): picture-order forces decode-order output
+    // (kills the reorder buffer on decoders that predate the standard key); low-latency is the older
+    // vendor twin.
+    if is("omx.qcom") || is("c2.qti") {
+        format.set_i32("vendor.qti-ext-dec-picture-order.enable", 1);
+        format.set_i32("vendor.qti-ext-dec-low-latency.enable", 1);
+    }
+    // Samsung Exynos — also covers Google Tensor (Pixel 6+), whose hardware decoder is `c2.exynos.*`.
+    if is("omx.exynos") || is("c2.exynos") {
+        format.set_i32("vendor.rtc-ext-dec-low-latency.enable", 1);
+    }
+    // Amlogic — the Android TV boxes (onn 4K, Chromecast w/ Google TV, Homatics).
+    if is("omx.amlogic") || is("c2.amlogic") {
+        format.set_i32("vendor.low-latency.enable", 1);
+    }
+    // HiSilicon / Kirin (older Huawei; paired req/rdy keys).
+    if is("omx.hisi") || is("c2.hisi") {
+        format.set_i32(
+            "vendor.hisi-ext-low-latency-video-dec.video-scene-for-low-latency-req",
+            1,
+        );
+        format.set_i32(
+            "vendor.hisi-ext-low-latency-video-dec.video-scene-for-low-latency-rdy",
+            -1,
+        );
+    }
+    // NVIDIA Tegra (Shield TV) and Rockchip/Realtek (budget TV boxes / smart TVs) expose no
+    // low-latency vendor key (Moonlight has none either) — their decoders are already low-latency
+    // oriented, so the standard `low-latency` key + the clock hint below + being ranked first
+    // (see `VideoDecoders`) is their treatment.
+    //
+    // Clock hint, mutually exclusive (matching Moonlight): the AOSP "unbounded" operating-rate
+    // sentinel (Short.MAX) tells the decoder to run each frame at max clocks and finish ASAP rather
+    // than pace to the frame rate — shaving per-frame decode latency at a power/heat cost. Only
+    // Qualcomm is known to handle the sentinel; every other vendor mis-paces on it, so they get the
+    // plain realtime `priority` hint instead.
+    if decoder_supports_max_operating_rate(&name) {
+        format.set_i32("operating-rate", i16::MAX as i32); // 32767 = "as fast as possible"
+    } else {
+        format.set_i32("priority", 0); // 0 = realtime
+    }
+}
+
+/// Whether a decoder tolerates `operating-rate = Short.MAX` rather than regressing on it. Follows
+/// Moonlight's allowlist: Qualcomm decoders honour the sentinel (the Adreno 620 generation is the
+/// known exception Moonlight excludes by GPU model — undetectable from native code here, so it
+/// rides the master toggle as its escape hatch). Other vendors fall back to the plain `priority`
+/// hint above.
+fn decoder_supports_max_operating_rate(name_lower: &str) -> bool {
+    name_lower.starts_with("omx.qcom") || name_lower.starts_with("c2.qti")
+}
+
+/// Raise the pipeline's OTHER hot threads — the core's data-plane pump (UDP receive + FEC
+/// reassembly) and the audio decode thread — toward the display band, matching this decode thread's
+/// own boost. `setpriority(PRIO_PROCESS, tid)` targets any task in the process, so we do it from
+/// here once their tids are known (the same set ADPF hints), without a per-platform priority hook
+/// in the shared core. Slightly below the decode thread's -10 so the display path still wins.
+/// Best-effort; skips this thread (already boosted) and is non-fatal if the platform refuses.
+pub(super) fn boost_hot_threads(tids: &[i32]) {
+    // SAFETY: `gettid` is an always-safe syscall on the calling thread.
+    let self_tid = unsafe { libc::gettid() };
+    for &tid in tids {
+        if tid == self_tid {
+            continue;
+        }
+        // SAFETY: `setpriority` with PRIO_PROCESS + a live tid in our own process is an always-safe
+        // syscall; a refusal is reported via the return value, not UB.
+        unsafe {
+            if libc::setpriority(libc::PRIO_PROCESS, tid as libc::id_t, -8) != 0 {
+                log::debug!("decode: setpriority(-8) on hot tid {tid} failed (non-fatal)");
+            }
+        }
+    }
+}
+
+/// Best-effort: raise the decode thread toward Android's URGENT_DISPLAY band so background work
+/// can't preempt it under load (which shows up as late/dropped frames). Non-fatal if the platform
+/// refuses (foreground apps may set their own threads; the exact floor is policy-dependent).
+pub(super) fn boost_thread_priority() {
+    // SAFETY: `gettid`/`setpriority` on the calling thread are always-safe syscalls. PRIO_PROCESS
+    // with a TID targets that one task on Linux — the same idiom `Process.setThreadPriority` uses.
+    unsafe {
+        let tid = libc::gettid();
+        if libc::setpriority(libc::PRIO_PROCESS, tid as libc::id_t, -10) != 0 {
+            log::warn!(
+                "decode: setpriority(-10) failed (non-fatal): {}",
+                std::io::Error::last_os_error()
+            );
+        }
+    }
+}
+
+/// Set the surface's frame-rate hint to the stream's refresh so SurfaceFlinger picks a matching
+/// display mode and aligns vsync (no 60-in-120 judder). Both NDK entry points sit above our API-28
+/// floor, so both are dlsym-resolved at runtime (a hard import of a >floor symbol makes
+/// `dlopen`/`System.load` fail on every API-28/29 device, even where this path is never hit —
+/// mirrors [`crate::adpf`]):
+///   - On a **TV** (`is_tv`): `ANativeWindow_setFrameRateWithChangeStrategy` (**API 31**) with
+///     `changeFrameRateStrategy = ALWAYS`, which actively drives the HDMI output into the matching
+///     mode (e.g. 60↔120) instead of leaving the panel at its default and judder-matching. The
+///     forced switch may blank the panel briefly — acceptable once at stream start, not wanted on a
+///     phone. Falls through to the 2-arg hint on API 30.
+///   - Otherwise: `ANativeWindow_setFrameRate` (**API 30**) with `compatibility = DEFAULT` — the
+///     softer, seamless-preferred hint for phones/tablets and the universal fallback.
+///
+/// Returns `true` when the platform accepted a hint; `false` on API < 30 (symbols absent) or a
+/// decline.
+pub(super) fn try_set_frame_rate(window: &NativeWindow, frame_rate: f32, is_tv: bool) -> bool {
+    // int32_t ANativeWindow_setFrameRate(ANativeWindow*, float frameRate, int8_t compatibility)
+    type SetFrameRateFn = unsafe extern "C" fn(*mut c_void, f32, i8) -> i32;
+    // int32_t ANativeWindow_setFrameRateWithChangeStrategy(
+    //     ANativeWindow*, float frameRate, int8_t compatibility, int8_t changeFrameRateStrategy)
+    type SetFrameRateStrategyFn = unsafe extern "C" fn(*mut c_void, f32, i8, i8) -> i32;
+    // SAFETY: `dlopen` of the always-mapped `libandroid.so` (only bumps its refcount; never closed —
+    // process-lifetime handle). Each `dlsym` returns null when the symbol is absent (device below the
+    // symbol's API level), checked before transmuting the non-null pointer to its fn-pointer type.
+    // `window.ptr()` is the live `ANativeWindow` this `NativeWindow` owns for the call's duration.
+    unsafe {
+        let lib = libc::dlopen(c"libandroid.so".as_ptr(), libc::RTLD_NOW);
+        if lib.is_null() {
+            return false;
+        }
+        // TV: prefer the API-31 change-strategy form to force the mode switch (strategy 1 = ALWAYS,
+        // compatibility 0 = DEFAULT). Absent on API 30 ⇒ fall through to the 2-arg hint below.
+        if is_tv {
+            let sym = libc::dlsym(
+                lib,
+                c"ANativeWindow_setFrameRateWithChangeStrategy".as_ptr(),
+            );
+            if !sym.is_null() {
+                let set = std::mem::transmute::<*mut c_void, SetFrameRateStrategyFn>(sym);
+                return set(window.ptr().as_ptr().cast(), frame_rate, 0, 1) == 0;
+            }
+        }
+        let sym = libc::dlsym(lib, c"ANativeWindow_setFrameRate".as_ptr());
+        if sym.is_null() {
+            return false; // device API < 30 — no per-surface frame-rate hint
+        }
+        let set_frame_rate = std::mem::transmute::<*mut c_void, SetFrameRateFn>(sym);
+        set_frame_rate(window.ptr().as_ptr().cast(), frame_rate, 0) == 0
+    }
+}
+
+/// Serialize [`HdrMeta`](punktfunk_core::quic::HdrMeta) into Android's `KEY_HDR_STATIC_INFO`
+/// (`hdr-static-info`) layout: a 25-byte CTA-861.3 / `HDRStaticInfo.Type1` blob — descriptor id 0,
+/// then primaries in **R, G, B** order, white point, max/min display luminance, MaxCLL, MaxFALL, all
+/// **little-endian** `u16`. Two conversions vs our wire form: HdrMeta stores primaries in ST.2086
+/// **G, B, R** order (reorder to R, G, B), and `max_display_mastering_luminance` is in 0.0001-cd/m²
+/// units while Android wants **whole nits** (min stays 0.0001-nit). Chromaticities (1/50000) and
+/// MaxCLL/MaxFALL (nits) match 1:1.
+pub(super) fn android_hdr_static_info(m: &punktfunk_core::quic::HdrMeta) -> [u8; 25] {
+    let [g, b_, r] = m.display_primaries; // ST.2086 G, B, R
+    let max_nits = (m.max_display_mastering_luminance / 10_000).min(u16::MAX as u32) as u16;
+    let min_units = m.min_display_mastering_luminance.min(u16::MAX as u32) as u16;
+    let fields: [u16; 12] = [
+        r[0],
+        r[1],
+        g[0],
+        g[1],
+        b_[0],
+        b_[1], // R, G, B primaries
+        m.white_point[0],
+        m.white_point[1], // white point
+        max_nits,
+        min_units, // max (nits) / min (0.0001-nit) display luminance
+        m.max_cll,
+        m.max_fall, // MaxCLL / MaxFALL (nits)
+    ];
+    let mut out = [0u8; 25]; // out[0] = 0 (Type 1 descriptor id), already zero
+    for (i, v) in fields.iter().enumerate() {
+        out[1 + i * 2..3 + i * 2].copy_from_slice(&v.to_le_bytes());
+    }
+    out
+}
@@ -0,0 +1,547 @@
+//! The synchronous MediaCodec decode loop (the original poll path) + its feed/drain helpers.
+
+use ndk::data_space::DataSpace;
+use ndk::media::media_codec::{
+    DequeuedInputBufferResult, DequeuedOutputBufferInfoResult, MediaCodec, MediaCodecDirection,
+    OutputBuffer,
+};
+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::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use super::display::{
+    hdr_dataspace, install_render_callback, release_render_callback, DisplayTracker,
+};
+use super::latency::{note_decoded_pts, now_realtime_ns, take_flags};
+use super::setup::{
+    android_hdr_static_info, boost_hot_threads, boost_thread_priority, codec_mime,
+    configure_low_latency, create_codec, try_set_frame_rate,
+};
+use super::{DecodeOptions, IN_FLIGHT_CAP, PENDING_SPLIT_CAP};
+
+/// The synchronous poll loop — the original decode path: the only one when low-latency mode is off,
+/// and the [`USE_ASYNC_DECODE`] A/B fallback when it's on. Feeds and drains on this one thread; the
+/// only blocking wait is a short output dequeue while input is backed up.
+pub(super) fn run_sync(
+    client: Arc<NativeClient>,
+    window: NativeWindow,
+    shutdown: Arc<AtomicBool>,
+    stats: Arc<crate::stats::VideoStats>,
+    opts: DecodeOptions,
+) {
+    let DecodeOptions {
+        decoder_name,
+        ll_feature,
+        low_latency_mode,
+        is_tv,
+    } = opts;
+    boost_thread_priority();
+    let mode = client.mode();
+    // The MediaCodec MIME for the codec the host resolved (`Welcome.codec`). AMediaCodec needs no
+    // out-of-band extradata — the in-band VPS/SPS/PPS on every IDR configure it either way.
+    let mime = codec_mime(client.codec);
+    let codec = match create_codec(mime, decoder_name.as_deref()) {
+        Some(c) => c,
+        None => {
+            log::error!("decode: no {mime} decoder on this device");
+            return;
+        }
+    };
+    // The decoder's *actual* resolved name (Kotlin's pick, or the platform default when it fell
+    // back) drives both the HUD label and which vendor low-latency keys apply below.
+    let codec_name = codec.name().unwrap_or_default();
+    stats.set_decoder(&codec_name, ll_feature);
+    log::info!(
+        "decode: codec mime = {mime}, decoder = {codec_name} (low-latency feature: {ll_feature})"
+    );
+
+    let mut format = MediaFormat::new();
+    format.set_str("mime", mime);
+    format.set_i32("width", mode.width as i32);
+    format.set_i32("height", mode.height as i32);
+    // Generous input buffer so a large keyframe AU is never truncated.
+    format.set_i32(
+        "max-input-size",
+        (mode.width * mode.height).max(2_000_000) as i32,
+    );
+    // Standard + per-SoC vendor low-latency keys and the clock hints, gated on the resolved decoder
+    // name and the master toggle (see `configure_low_latency`).
+    configure_low_latency(&mut format, &codec_name, low_latency_mode);
+
+    // HDR static metadata (ST.2086 mastering + content light level): when an HDR session was
+    // negotiated, set KEY_HDR_STATIC_INFO so the display tone-maps from the source's real grade.
+    // MediaCodec wants it BEFORE configure(), and the host sends a 0xCE right after the handshake,
+    // so it's typically already queued; wait briefly otherwise. The Surface DataSpace (applied on
+    // OutputFormatChanged below) carries transfer/primaries regardless — this adds the luminance the
+    // tone-mapper needs. A non-HDR display still gets sensible SurfaceFlinger tone-mapping.
+    if client.color.is_hdr() {
+        match client.next_hdr_meta(Duration::from_millis(250)) {
+            Ok(meta) => {
+                format.set_buffer("hdr-static-info", &android_hdr_static_info(&meta));
+                log::info!("decode: HDR static metadata applied (KEY_HDR_STATIC_INFO)");
+            }
+            Err(_) => {
+                log::info!("decode: HDR session but no mastering metadata yet — DataSpace only")
+            }
+        }
+    }
+
+    if let Err(e) = codec.configure(&format, Some(&window), MediaCodecDirection::Decoder) {
+        log::error!("decode: configure failed: {e}");
+        return;
+    }
+    if let Err(e) = codec.start() {
+        log::error!("decode: start failed: {e}");
+        return;
+    }
+    log::info!(
+        "decode: {mime} decoder started at {}x{}",
+        mode.width,
+        mode.height
+    );
+    // Tell the display the stream's refresh so Android can pick a matching display mode and align
+    // vsync (no 60-in-120 judder on high-refresh panels). `ANativeWindow_setFrameRate` is NDK API 30,
+    // above our API-28 floor, so we resolve it at runtime (see `try_set_frame_rate`) rather than link
+    // it — a hard import would stop `libpunktfunk_android.so` loading at all on API 28/29. Absent
+    // there ⇒ we simply skip the hint (non-fatal; the stream renders fine without it).
+    // The forced TV mode switch (`is_tv` ⇒ ALWAYS strategy) is part of the experimental stack;
+    // off, every form factor gets the original soft seamless hint.
+    if mode.refresh_hz > 0
+        && !try_set_frame_rate(&window, mode.refresh_hz as f32, is_tv && low_latency_mode)
+    {
+        log::debug!(
+            "decode: set_frame_rate({} Hz) unavailable/declined (non-fatal)",
+            mode.refresh_hz
+        );
+    }
+
+    // ADPF: hint the platform that the whole video pipeline — this pf-decode feed/drain/present
+    // loop, the core's data-plane pump (UDP receive + FEC reassembly), and the audio thread — runs a
+    // per-frame real-time workload, so the CPU governor keeps those threads on fast cores at high
+    // clocks instead of down-clocking between frames or parking them on a little core. Snapdragon's
+    // ADPF backend responds well to this. We register this thread now but create the session lazily
+    // on the first presented frame: by then the pump + audio threads have registered their ids too,
+    // and ADPF `createSession` rejects a set with any not-yet-live/dead tid. No-op below API 33.
+    let frame_period_ns = if mode.refresh_hz > 0 {
+        1_000_000_000i64 / mode.refresh_hz as i64
+    } else {
+        0
+    };
+    client.register_hot_thread(); // this decode thread → the pipeline's hot-thread set
+    let mut hint: Option<crate::adpf::HintSession> = None;
+    let mut hint_tried = false;
+    // Accumulates the loop's productive (feed+drain) time between displayed frames; reported to ADPF
+    // once per rendered frame against the frame-period target.
+    let mut work_accum_ns: i64 = 0;
+
+    let mut fed: u64 = 0;
+    let mut rendered: u64 = 0;
+    let mut discarded: u64 = 0;
+    // AUs larger than the codec input buffer, dropped whole (see `feed`/`feed_ready`).
+    let mut oversized_dropped: u64 = 0;
+    // The AU waiting for a free codec input buffer. `feed` is non-blocking; on transient input
+    // 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;
+    // 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
+    // HUD flags it "(same-host clock)").
+    let clock_offset = client.clock_offset_shared();
+    // Display stage (spec `display` + the capture→displayed headline): frames released with
+    // render = true are parked in the tracker; the OnFrameRendered callback pairs them with
+    // SurfaceFlinger's render timestamp. `render_cb` is the callback's leaked Arc refcount,
+    // reclaimed after the codec is dropped below.
+    let tracker = DisplayTracker::new(stats.clone(), clock_offset.clone());
+    let render_cb = install_render_callback(&codec, &tracker);
+    // Receipt timestamps keyed by the pts we queue into the codec, so the decoded point (output-
+    // buffer dequeue — MediaCodec round-trips presentationTimeUs) can be paired back to its receipt
+    // for the `decode` stage. Fed while the HUD is visible OR the adaptive-bitrate controller wants
+    // the decode signal (`measure_decode`) — the decoder-backlog bottleneck the network can't see.
+    let measure_decode = client.wants_decode_latency();
+    let mut in_flight: VecDeque<(u64, i128)> = VecDeque::new();
+    // Phase-2 host/network split (design/stats-unification.md): received AUs awaiting their 0xCF
+    // host timing, as (pts_ns, capture→received µs). The timings are drained non-blockingly right
+    // where receipts are recorded and matched by pts; `network = hostnet − host` (saturating).
+    // Only fed while the HUD is visible; an old host never sends a 0xCF, so entries just age out.
+    let mut pending_split: VecDeque<(u64, u64)> = VecDeque::new();
+    // The dataspace we've signalled on the Surface so far (None = default/SDR). Set reactively once
+    // the decoder reports an HDR stream (see `drain`); avoids re-applying every format event.
+    let mut applied_ds: Option<DataSpace> = None;
+    // One thread feeds AND drains: the NDK AMediaCodec wrapper isn't documented thread-safe for
+    // cross-thread feed/drain, so instead of splitting threads the loop decouples the two — input
+    // dequeue is non-blocking (never stalls presentation of already-decoded frames) and the only
+    // blocking wait is a short output dequeue while input is backed up (decoder progress is exactly
+    // what frees the next input buffer).
+    while !shutdown.load(Ordering::Relaxed) {
+        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!(
+                            "decode: first AU {} bytes, head {:02x?}",
+                            p.len(),
+                            &p[..p.len().min(6)]
+                        );
+                    }
+                    // Receipt stamp for the `decode` stage pairing, parked in `in_flight` (keyed by
+                    // the pts the codec echoes on its output buffer) whenever it's needed: the HUD
+                    // being visible, or the ABR decode signal (`measure_decode`). The HUD-only
+                    // samplers (`received` point, host/network split) stay gated on the overlay so
+                    // the hidden steady state adds only a wall-clock read + the receipt push.
+                    if stats.enabled() || measure_decode {
+                        let received_ns = now_realtime_ns();
+                        in_flight.push_back((frame.pts_ns / 1000, received_ns));
+                        if in_flight.len() > IN_FLIGHT_CAP {
+                            in_flight.pop_front(); // stale — codec never echoed it back
+                        }
+                        // HUD stat, `received` point: host+network = client_now + (host−client) −
+                        // capture_pts.
+                        if stats.enabled() {
+                            let clock_offset = clock_offset.load(Ordering::Relaxed);
+                            let lat_ns = received_ns + clock_offset as i128 - frame.pts_ns as i128;
+                            let lat_us = (lat_ns > 0 && lat_ns < 10_000_000_000)
+                                .then_some((lat_ns / 1000) as u64);
+                            stats.note_received(frame.data.len(), lat_us, clock_offset != 0);
+                            // Phase-2 split: park this AU's capture→received sample, then match any
+                            // 0xCF host timings that have arrived — host = the host's own
+                            // capture→sent, network = our capture→received minus it (per-frame
+                            // tiling; saturating in case of clock jitter).
+                            if let Some(hostnet_us) = lat_us {
+                                pending_split.push_back((frame.pts_ns, hostnet_us));
+                                if pending_split.len() > PENDING_SPLIT_CAP {
+                                    pending_split.pop_front(); // 0xCF lost / old host — evict
+                                }
+                            }
+                            while let Ok(t) = client.next_host_timing(Duration::ZERO) {
+                                if let Some(i) =
+                                    pending_split.iter().position(|&(p, _)| p == t.pts_ns)
+                                {
+                                    let (_, hostnet_us) = pending_split.remove(i).unwrap();
+                                    stats.note_host_split(
+                                        t.host_us as u64,
+                                        hostnet_us.saturating_sub(t.host_us as u64),
+                                    );
+                                }
+                            }
+                        }
+                    }
+                    pending = Some(frame);
+                }
+                Err(PunktfunkError::NoFrame) => {} // timeout — still drain output below
+                Err(_) => break,                   // session closed
+            }
+        }
+        // Time the productive work (feed + drain) only — the `next_frame` poll wait above is idle
+        // and excluded, so ADPF sees this thread's real per-frame CPU cost, not the poll timeout.
+        let work_t0 = Instant::now();
+        if let Some(frame) = pending.take() {
+            if feed(
+                &codec,
+                &client,
+                &frame.data,
+                frame.pts_ns / 1000,
+                &mut oversized_dropped,
+            ) {
+                fed += 1;
+                if fed % 300 == 0 {
+                    log::info!("decode: fed={fed} rendered={rendered} discarded={discarded}");
+                }
+            } else {
+                // No input buffer free — transient back-pressure. Keep the AU and let `drain` block
+                // briefly below; a released output buffer is what recycles an input slot.
+                pending = Some(frame);
+            }
+        }
+        // Drain every iteration. When input is blocked, wait ~2 ms on output so the loop rides
+        // decoder progress instead of busy-spinning against a full input queue.
+        let wait = if pending.is_some() {
+            Duration::from_millis(2)
+        } else {
+            Duration::ZERO
+        };
+        let (r, d) = drain(
+            &codec,
+            &client,
+            measure_decode,
+            &window,
+            &mut applied_ds,
+            wait,
+            &stats,
+            &mut in_flight,
+            clock_offset.load(Ordering::Relaxed),
+            &tracker,
+            &mut gate,
+            &mut recovery_flags,
+        );
+        rendered += r;
+        discarded += d;
+
+        // ADPF: attribute this iteration's feed+drain time to the frame being produced, and report
+        // the accumulated per-frame work once one is actually presented (r > 0). Under back-pressure
+        // the short output-dequeue wait is included in the tally — for a latency-first client,
+        // biasing the governor toward "boost" is the desired behaviour. Cheap when `hint` is None
+        // (one `Instant` diff, no report).
+        work_accum_ns += work_t0.elapsed().as_nanos() as i64;
+        if r > 0 {
+            if !hint_tried {
+                // First presented frame: the pump + audio threads have registered their ids by now.
+                // Build one ADPF session over the whole pipeline's thread set (empty below API 33,
+                // or where the platform declines → `None`, and the loop runs unhinted).
+                hint_tried = true;
+                let tids = client.hot_thread_ids();
+                // The pump/audio priority boost is part of the experimental low-latency stack; the
+                // ADPF session itself predates it and always runs (max-performance bias gated inside).
+                if low_latency_mode {
+                    boost_hot_threads(&tids);
+                }
+                hint = crate::adpf::HintSession::create(frame_period_ns, &tids, low_latency_mode);
+                log::info!(
+                    "decode: ADPF hint session {} — {} hot thread(s), target {frame_period_ns} ns",
+                    if hint.is_some() {
+                        "active"
+                    } else {
+                        "unavailable"
+                    },
+                    tids.len(),
+                );
+            }
+            if let Some(h) = &hint {
+                h.report_actual(work_accum_ns);
+            }
+            work_accum_ns = 0;
+        }
+
+        // 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)");
+        }
+    }
+
+    let _ = codec.stop();
+    drop(codec); // AMediaCodec_delete — after this no render callback can fire
+    if let Some(ud) = render_cb {
+        // SAFETY: the codec was dropped above; this registration's single reclaim.
+        unsafe { release_render_callback(ud) };
+    }
+    log::info!("decode: stopped (fed={fed} rendered={rendered} discarded={discarded})");
+}
+
+/// Try to copy one access unit into a codec input buffer and queue it, without blocking. Returns
+/// `false` only on `TryAgainLater` (no input buffer free) — the caller keeps the AU pending and
+/// retries; a hard dequeue/queue error counts as consumed (retrying can't salvage the AU, and
+/// parking it forever would wedge the loop on a broken codec). An AU larger than the input
+/// buffer is DROPPED (+ a recovery keyframe requested), never truncated — a truncated AU is
+/// corrupt input the decoder chews on silently, poisoning the reference chain.
+fn feed(
+    codec: &MediaCodec,
+    client: &NativeClient,
+    au: &[u8],
+    pts_us: u64,
+    oversized_dropped: &mut u64,
+) -> bool {
+    match codec.dequeue_input_buffer(Duration::ZERO) {
+        Ok(DequeuedInputBufferResult::Buffer(mut buf)) => {
+            let n = {
+                let dst = buf.buffer_mut();
+                if au.len() > dst.len() {
+                    *oversized_dropped += 1;
+                    log::warn!(
+                        "decode: AU {} > input buffer {} — dropped ({} so far), requesting keyframe",
+                        au.len(),
+                        dst.len(),
+                        *oversized_dropped
+                    );
+                    let _ = client.request_keyframe();
+                    0 // return the slot with zero valid bytes — a no-op input, not corrupt data
+                } else {
+                    let n = au.len();
+                    // SAFETY: `au` and `dst` are distinct allocations (wire AU vs. codec buffer),
+                    // both valid for `n` bytes; `MaybeUninit<u8>` is layout-identical to `u8`, so
+                    // the cast write initializes exactly `dst[..n]`.
+                    unsafe {
+                        std::ptr::copy_nonoverlapping(
+                            au.as_ptr(),
+                            dst.as_mut_ptr().cast::<u8>(),
+                            n,
+                        );
+                    }
+                    n
+                }
+            };
+            if let Err(e) = codec.queue_input_buffer(buf, 0, n, pts_us, 0) {
+                log::warn!("decode: queue_input_buffer: {e}");
+            }
+            true
+        }
+        Ok(DequeuedInputBufferResult::TryAgainLater) => false, // caller keeps the AU pending
+        Err(e) => {
+            log::warn!("decode: dequeue_input_buffer: {e}");
+            true
+        }
+    }
+}
+
+/// Dequeue every ready output buffer and present only the NEWEST (render = true), discarding the
+/// rest (render = false) — when decode falls behind, a back-to-back burst of stale frames on glass
+/// is worse than skipping straight to the freshest one (the Apple client's 1-slot newest-ready
+/// ring, ported). `first_wait` is the timeout for the first dequeue only: zero normally, ~2 ms when
+/// the caller's input is blocked so the loop waits on decoder progress instead of busy-spinning.
+/// Returns `(rendered, discarded)`. Also reacts to `OutputFormatChanged` (which can interleave
+/// between buffers — handled without losing the held buffer) to signal HDR on the Surface.
+///
+/// Each dequeued buffer is also the HUD's `decoded` measurement point (rendered or not — the frame
+/// finished decoding either way): end-to-end = decoded + clock_offset − capture pts, and the
+/// `decode` stage pairs the buffer's echoed presentationTimeUs back to the receipt stamp in
+/// `in_flight` (single-clock local difference, no skew involved). The presented frame's
+/// `(pts, decoded stamp)` is additionally parked in `tracker` for the OnFrameRendered callback —
+/// the `display` stage's other endpoint.
+#[allow(clippy::too_many_arguments)] // one call site; mirrors the async loop's present_ready
+fn drain(
+    codec: &MediaCodec,
+    client: &NativeClient,
+    measure_decode: bool,
+    window: &NativeWindow,
+    applied_ds: &mut Option<DataSpace>,
+    first_wait: Duration,
+    stats: &crate::stats::VideoStats,
+    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. `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)) => {
+                // 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() || measure_decode {
+                    // The dequeue IS the sync loop's decoded-availability instant.
+                    let decoded_ns = now_realtime_ns();
+                    note_decoded_pts(
+                        client,
+                        measure_decode,
+                        stats,
+                        in_flight,
+                        clock_offset,
+                        pts_us,
+                        decoded_ns,
+                    );
+                    // The tracker's `display` stage is a HUD concern — park only when visible.
+                    stats.enabled().then_some((pts_us, decoded_ns))
+                } else {
+                    None
+                };
+                if let Some((stale, _)) = held.replace((buf, meta)) {
+                    // A newer frame is ready — drop the held one without rendering.
+                    if let Err(e) = codec.release_output_buffer(stale, false) {
+                        log::warn!("decode: release_output_buffer(discard): {e}");
+                    }
+                    discarded += 1;
+                    stats.note_skipped(1); // HUD `skipped` counter; no-op while hidden
+                }
+            }
+            Ok(DequeuedOutputBufferInfoResult::OutputFormatChanged) => {
+                // The decoder has parsed the SPS and now reports the stream's real colour signalling
+                // (the AMediaCodec analogue of VideoToolbox's format description on the Apple client).
+                // If it's HDR (BT.2020 PQ/HLG), tell the Surface so the compositor/display switch to
+                // HDR; SDR streams leave the default dataspace alone. The decoder itself picks a
+                // Main10 path from the SPS — no profile override needed. Keep looping (buffers
+                // follow, and any held buffer stays held across this event).
+                wait = Duration::ZERO;
+                if let Some(ds) = hdr_dataspace(codec) {
+                    if *applied_ds != Some(ds) {
+                        match window.set_buffers_data_space(ds) {
+                            Ok(()) => {
+                                *applied_ds = Some(ds);
+                                log::info!("decode: HDR stream → Surface dataspace {ds}");
+                            }
+                            Err(e) => log::warn!(
+                                "decode: set_buffers_data_space({ds}) failed (non-fatal): {e}"
+                            ),
+                        }
+                    }
+                }
+            }
+            // TryAgainLater / OutputBuffersChanged — nothing more to dequeue now.
+            Ok(_) => break,
+            Err(e) => {
+                log::warn!("decode: dequeue_output_buffer: {e}");
+                break;
+            }
+        }
+    }
+    // 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, 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}"),
+        }
+    }
+    (rendered, discarded)
+}
@@ -22,15 +22,21 @@ const PULL_TIMEOUT: Duration = Duration::from_millis(100);
 const TAG_LED: u8 = 0x01;
 const TAG_PLAYER_LEDS: u8 = 0x02;
 const TAG_TRIGGER: u8 = 0x03;
+const TAG_HID_RAW: u8 = 0x05;

-/// `NativeBridge.nativeNextRumble(handle): Long` — 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` (`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.
+/// `NativeBridge.nativeNextRumble(handle): Long` — block up to ~100 ms for the next EFFECTIVE
+/// rumble command from the core's shared policy engine (`design/rumble-root-fix.md` §D). The
+/// engine owns ALL rumble policy — v2 lease expiry, legacy-host staleness (a uniform 1 s, ending
+/// the old 60 s Android exposure), connection-close drain zeros — so Kotlin applies commands
+/// verbatim: `(0, 0)` = cancel now, non-zero = one-shot at this level.
+///
+/// Returns a packed positive long: bits 49..52 = wire `pad` index (0..15), bits 32..47 = the
+/// command's `backstop_ms` (≤ 5000 — the one-shot duration, i.e. the hardware net under a stalled
+/// poll thread; the engine emits explicit zeros at every policy stop, so it is never the stop
+/// mechanism), bits 16..31 = `low`, bits 0..15 = `high` (0..=0xFFFF). `-1` on timeout / session
+/// closed (all packed values are positive, so `-1` stays unambiguous). Kotlin routes the command
+/// 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,
@@ -42,24 +48,17 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextRumble(
        if handle == 0 {
            return -1;
        }
-        // SAFETY: live handle per the nativeConnect/nativeClose contract; next_rumble_ttl is &self on
-        // the Sync connector — safe alongside the decode/audio/input threads. Kotlin stops these poll
-        // threads (and joins them — unbounded) before nativeClose frees the handle.
+        // SAFETY: live handle per the nativeConnect/nativeClose contract; next_rumble_command is
+        // &self on the Sync connector — safe alongside the decode/audio/input threads. Kotlin
+        // stops these poll 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)) => {
-                // 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. 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),
-                };
-                (jlong::from(pad & 0xF) << 49)
-                    | lease_flag
-                    | ttl_bits
-                    | (jlong::from(low) << 16)
-                    | jlong::from(high)
+        match h.client.next_rumble_command(PULL_TIMEOUT) {
+            Ok(cmd) => {
+                (jlong::from(cmd.pad & 0xF) << 49)
+                    | (jlong::from(cmd.backstop_ms.min(0xFFFF) as u16) << 32)
+                    | (jlong::from(cmd.low) << 16)
+                    | jlong::from(cmd.high)
            }
            Err(_) => -1, // NoFrame (timeout) or Closed — Kotlin loops on its running flag
        }
@@ -143,6 +142,20 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextHidout(
                // rumble already rides the universal 0xCA plane).
                return -1;
            }
+            HidOutput::HidRaw { pad, kind, data } => {
+                // As-is SC2 passthrough: the host's hidraw consumer (Steam) wrote this report to
+                // the virtual pad; Kotlin replays it verbatim on the physical controller.
+                // `[pad][0x05][kind][report…]` — kind 0 = output report, 1 = feature report.
+                let n = 3 + data.len();
+                if cap < n {
+                    return -1; // reports are ≤ 64 bytes; Kotlin allocates 128
+                }
+                out[0] = pad;
+                out[1] = TAG_HID_RAW;
+                out[2] = kind;
+                out[3..n].copy_from_slice(&data);
+                n
+            }
        };
        n as jint
    })
@@ -11,6 +11,43 @@ use std::time::Duration;

 use super::{hex32, jni_guard, parse_hex32, SessionHandle};

+/// Machine token of the most recent `nativeConnect`/`nativePair` failure, taken (and cleared)
+/// by `nativeTakeLastError` so Kotlin can render a cause-specific message instead of the old
+/// catch-all "wrong PIN, or the host isn't armed" (which blamed the PIN for dead network paths
+/// — the moko0878-class support threads). The app runs one attempt at a time, so one slot
+/// suffices; a stale token is harmless (it is taken immediately after the failed call).
+static LAST_ERROR: Mutex<String> = Mutex::new(String::new());
+
+/// Stable token for a failed pair/connect cause, matched by Kotlin (`ConnectErrors.kt`):
+/// a typed host rejection yields its `RejectReason::as_str()` token ("not-armed", "denied",
+/// "approval-timeout", …); transport-level causes map to "crypto" / "timeout" / "io" / "error".
+fn note_error(e: &punktfunk_core::error::PunktfunkError) {
+    use punktfunk_core::error::PunktfunkError as E;
+    let token = match e {
+        E::Rejected(r) => r.as_str(),
+        E::Crypto => "crypto",
+        E::Timeout => "timeout",
+        E::Io(_) => "io",
+        _ => "error",
+    };
+    *LAST_ERROR.lock().unwrap() = token.to_string();
+}
+
+/// `NativeBridge.nativeTakeLastError(): String` — the machine token of the most recent failed
+/// `nativeConnect`/`nativePair`, cleared on read (`""` when none). Call right after a `0`
+/// handle / `""` fingerprint.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeTakeLastError<'local>(
+    env: JNIEnv<'local>,
+    _this: JObject<'local>,
+) -> jni::sys::jstring {
+    let token = std::mem::take(&mut *LAST_ERROR.lock().unwrap());
+    match env.new_string(token) {
+        Ok(s) => s.into_raw(),
+        Err(_) => JObject::null().into_raw(),
+    }
+}
+
 /// `NativeBridge.nativeGenerateIdentity(): String` — mint a fresh persistent self-signed identity.
 /// Returns `"<certPem>\n-----PUNKTFUNK-KEY-----\n<keyPem>"`, or `""` on failure (logged). Kotlin
 /// persists it (Keystore-wrapped) and only calls this again when the store is genuinely empty.
@@ -185,6 +222,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
        }
        Err(e) => {
            log::error!("nativeConnect to {host}:{port} failed: {e}");
+            note_error(&e);
            0
        }
    }
@@ -318,7 +356,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativePair<'local
            Ok(host_fp) => hex32(&host_fp),
            Err(e) => {
                // Crypto error == wrong PIN / MITM; anything else == transport/host reject.
+                // The token lets Kotlin say WHICH (`nativeTakeLastError`).
                log::error!("nativePair to {host}:{port} failed: {e}");
+                note_error(&e);
                String::new()
            }
        }
@@ -6,10 +6,11 @@
 //! conventions: buttons 1=left/2=middle/3=right/4=X1/5=X2; scroll axis 0=vertical/1=horizontal,
 //! signed 120-unit delta, +=up/right; keys are Windows VK (mapped from KEYCODE_* on the Kotlin side).

-use jni::objects::JObject;
+use jni::objects::{JByteBuffer, JObject};
 use jni::sys::{jboolean, jint, jlong};
 use jni::JNIEnv;
 use punktfunk_core::input::{InputEvent, InputKind};
+use punktfunk_core::quic::{RichInput, HID_REPORT_MAX};

 use super::SessionHandle;

@@ -236,3 +237,43 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepad
 ) {
    send_event(handle, InputKind::GamepadRemove, 0, 0, 0, pad as u32);
 }
+
+/// `NativeBridge.nativeSendPadHidReport(handle, pad, buf, len)` — one raw HID input report from a
+/// client-captured controller (the as-is Steam Controller 2 passthrough), forwarded verbatim on
+/// the rich-input plane (`RichInput::HidReport`, 0xCC). `buf` is a DIRECT ByteBuffer whose first
+/// `len` bytes are the report, id byte first (`0x42`/`0x45`/`0x47` state, `0x43` battery, …);
+/// `len` is clamped to the 64-byte wire body. Called from the capture thread at the controller's
+/// own report rate (~250–500 Hz) — the direct-buffer read avoids a JNI array copy per report.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPadHidReport(
+    env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    pad: jint,
+    buf: JByteBuffer,
+    len: jint,
+) {
+    if handle == 0 || len <= 0 {
+        return;
+    }
+    let cap = match env.get_direct_buffer_capacity(&buf) {
+        Ok(c) => c,
+        Err(_) => return,
+    };
+    let ptr = match env.get_direct_buffer_address(&buf) {
+        Ok(p) if !p.is_null() => p,
+        _ => return,
+    };
+    let n = (len as usize).min(cap).min(HID_REPORT_MAX);
+    let mut data = [0u8; HID_REPORT_MAX];
+    // SAFETY: `ptr`/`cap` describe the direct ByteBuffer's backing store, valid for this call;
+    // `n` is bounded by both the buffer capacity and the fixed wire body.
+    data[..n].copy_from_slice(unsafe { std::slice::from_raw_parts(ptr, n) });
+    // SAFETY: live handle per the nativeConnect/nativeClose contract; send_rich_input is &self.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_rich_input(RichInput::HidReport {
+        pad: (pad as u32 & 0xF) as u8,
+        len: n as u8,
+        data,
+    });
+}
@@ -102,6 +102,31 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoMime<'
    })
 }

+/// `NativeBridge.nativeVideoCodecLabel(handle): String` — a short human label for the codec the
+/// host resolved (`"H.264"` / `"HEVC"` / `"AV1"` / `"PyroWave"`), for the stats HUD's video-feed
+/// line. Distinct from [`Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoMime`] because the MIME
+/// collapses PyroWave onto `video/hevc` and can't name it. Empty string on a `0` handle. Cheap;
+/// safe on the UI thread. Android-gated (reads `crate::decode`), matching `nativeVideoMime`.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoCodecLabel<'local>(
+    env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    handle: jlong,
+) -> jstring {
+    jni_guard(std::ptr::null_mut(), || {
+        if handle == 0 {
+            return std::ptr::null_mut();
+        }
+        // SAFETY: live handle per the nativeConnect/nativeClose contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        match env.new_string(crate::decode::codec_label(h.client.codec)) {
+            Ok(s) => s.into_raw(),
+            Err(_) => std::ptr::null_mut(),
+        }
+    })
+}
+
 /// `NativeBridge.nativeVideoDecoderLabel(handle): String` — the resolved decoder identity for the
 /// HUD, e.g. `c2.qti.avc.decoder · low-latency`, or `""` before the decode thread has resolved one.
 /// One-shot (the decoder is fixed for the session); poll once after the HUD appears. Not
@@ -15,11 +15,36 @@
 			<string>MicroGamepad</string>
 		</dict>
 	</array>
-	<key>ITSAppUsesNonExemptEncryption</key>
-	<true/>
 	<key>NSBonjourServices</key>
 	<array>
 		<string>_punktfunk._udp</string>
 	</array>
+	<!-- Background keep-alive (opt-in, iOS/iPadOS): the ONLY sanctioned way to keep the long-lived
+	     QUIC socket + pump-thread set alive while backgrounded is the audio background mode, backed
+	     by the session's real, audible remote audio (AVAudioEngine keeps rendering). Video decode is
+	     dropped; a bounded timer auto-disconnects. Never silence-as-keepalive (App Review 2.5.4).
+	     tvOS ignores/tolerates the key; macOS is not gated by it. -->
+	<key>UIBackgroundModes</key>
+	<array>
+		<string>audio</string>
+	</array>
+	<!-- Live Activities (iOS/iPadOS): the Lock-Screen / Dynamic-Island session surface. Updated
+	     locally (pushType nil) from the alive app process — no aps-environment. tvOS/macOS ignore it. -->
+	<key>NSSupportsLiveActivities</key>
+	<true/>
+	<!-- Deep links: punktfunk://connect/<host-uuid>[?launch=<GameEntry.id>]. Emitted by the
+	     launcher widget and Siri/Shortcuts; routed by ContentView.onOpenURL into the existing
+	     connect path. Shared across all three targets (tvOS/macOS accept it harmlessly). -->
+	<key>CFBundleURLTypes</key>
+	<array>
+		<dict>
+			<key>CFBundleURLName</key>
+			<string>io.unom.punktfunk.deeplink</string>
+			<key>CFBundleURLSchemes</key>
+			<array>
+				<string>punktfunk</string>
+			</array>
+		</dict>
+	</array>
 </dict>
 </plist>
@@ -73,5 +73,15 @@
 	<array>
 		<string>$(AppIdentifierPrefix)io.unom.punktfunk</string>
 	</array>
+
+	<!-- App Group: same shared UserDefaults suite as iOS (Config/Punktfunk.entitlements). Shared
+	     here so a single HostStore code path (UserDefaults(suiteName:)) works on every platform;
+	     macOS widgets that read it arrive with M5. macOS App Groups use the plain group id under
+	     the App Store profile; a Developer-ID-signed build wants the team-prefixed form — the
+	     Dev-ID codesign step in release.yml must verify this value against the Dev-ID profile. -->
+	<key>com.apple.security.application-groups</key>
+	<array>
+		<string>group.io.unom.punktfunk</string>
+	</array>
 </dict>
 </plist>
@@ -20,5 +20,14 @@
 	     is true on iOS/tvOS too. -->
 	<key>com.apple.developer.networking.multicast</key>
 	<true/>
+	<!-- App Group: the shared UserDefaults suite (group.io.unom.punktfunk) that both the app and
+	     the Widget/Live-Activity extension read — the saved-host store moved there so a launcher
+	     widget can see it (HostStore reads UserDefaults(suiteName:)). Must be registered on the
+	     developer portal and enabled in the provisioning profile for BOTH app ids
+	     (io.unom.punktfunk + io.unom.punktfunk.widgets). tvOS carries the key harmlessly. -->
+	<key>com.apple.security.application-groups</key>
+	<array>
+		<string>group.io.unom.punktfunk</string>
+	</array>
 </dict>
 </plist>
@@ -9,13 +9,20 @@ let package = Package(
    platforms: [.macOS(.v14), .iOS(.v17), .tvOS(.v17)],
    products: [
        .library(name: "PunktfunkKit", targets: ["PunktfunkKit"]),
+        // Dependency-free foundation (stored-host model + JSON codec, settings keys, App-Group
+        // constant, deep-link grammar, Live Activity attributes). A separate PRODUCT so the widget
+        // extension — which must never link PunktfunkKit (Rust staticlib + presentation layer) —
+        // can link this and nothing else. PunktfunkKit re-exports it (see SharedReexport.swift).
+        .library(name: "PunktfunkShared", targets: ["PunktfunkShared"]),
        .executable(name: "PunktfunkClient", targets: ["PunktfunkClient"]),
    ],
    targets: [
        .binaryTarget(name: "PunktfunkCore", path: "PunktfunkCore.xcframework"),
+        // No dependencies by design — an extension process links this alone.
+        .target(name: "PunktfunkShared"),
        .target(
            name: "PunktfunkKit",
-            dependencies: ["PunktfunkCore"],
+            dependencies: ["PunktfunkCore", "PunktfunkShared"],
            // OSS attribution shown by the app's Acknowledgements screen. Bundled here (not in the
            // app target) so it rides along via Bundle.module in both `swift build` and the Xcode
            // app, which links the PunktfunkKit product. Refresh with
@@ -42,6 +49,14 @@ let package = Package(
        .executableTarget(name: "PunktfunkClient", 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"]),
+        .testTarget(
+            name: "PunktfunkKitTests",
+            dependencies: ["PunktfunkKit", "PunktfunkShared", "PunktfunkCore"],
+            resources: [
+                // PyroWave golden fixtures: host-encoded AUs + upstream-decoded reference
+                // planes (regenerate with punktfunk-host's `pyrowave_dump_golden` on a
+                // Vulkan box — see PyroWaveDecoderTests.swift).
+                .copy("PyroWaveFixtures")
+            ]),
    ]
 )
@@ -11,14 +11,56 @@
 		BB0000000000000000000005 /* PunktfunkKit in Frameworks */ = {isa = PBXBuildFile; productRef = BB0000000000000000000006 /* PunktfunkKit */; };
 		CC0000000000000000000005 /* PunktfunkKit in Frameworks */ = {isa = PBXBuildFile; productRef = CC0000000000000000000006 /* PunktfunkKit */; };
 		DD0000000000000000000003 /* SwiftUINavigationTransitions in Frameworks */ = {isa = PBXBuildFile; productRef = DD0000000000000000000002 /* SwiftUINavigationTransitions */; };
+		E295569A300948B9009F939C /* WidgetKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = E2955699300948B9009F939C /* WidgetKit.framework */; };
+		E295569C300948B9009F939C /* SwiftUI.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = E295569B300948B9009F939C /* SwiftUI.framework */; };
+		E2CAFE000000000000000001 /* PunktfunkShared in Frameworks */ = {isa = PBXBuildFile; productRef = E2CAFE000000000000000002 /* PunktfunkShared */; };
+		E29556A9300948BA009F939C /* PunktfunkWidgetsExtension.appex in Embed Foundation Extensions */ = {isa = PBXBuildFile; fileRef = E2955697300948B9009F939C /* PunktfunkWidgetsExtension.appex */; settings = {ATTRIBUTES = (RemoveHeadersOnCopy, ); }; };
 /* End PBXBuildFile section */

+/* Begin PBXContainerItemProxy section */
+		E29556A7300948BA009F939C /* PBXContainerItemProxy */ = {
+			isa = PBXContainerItemProxy;
+			containerPortal = AA000000000000000000000D /* Project object */;
+			proxyType = 1;
+			remoteGlobalIDString = E2955696300948B9009F939C;
+			remoteInfo = PunktfunkWidgetsExtension;
+		};
+/* End PBXContainerItemProxy section */
+
+/* Begin PBXCopyFilesBuildPhase section */
+		E29556AA300948BA009F939C /* Embed Foundation Extensions */ = {
+			isa = PBXCopyFilesBuildPhase;
+			buildActionMask = 2147483647;
+			dstPath = "";
+			dstSubfolderSpec = 13;
+			files = (
+				E29556A9300948BA009F939C /* PunktfunkWidgetsExtension.appex in Embed Foundation Extensions */,
+			);
+			name = "Embed Foundation Extensions";
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+/* End PBXCopyFilesBuildPhase section */
+
 /* Begin PBXFileReference section */
 		AA0000000000000000000001 /* Punktfunk.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = Punktfunk.app; sourceTree = BUILT_PRODUCTS_DIR; };
 		BB0000000000000000000001 /* Punktfunk-iOS.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = "Punktfunk-iOS.app"; sourceTree = BUILT_PRODUCTS_DIR; };
 		CC0000000000000000000001 /* Punktfunk-tvOS.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = "Punktfunk-tvOS.app"; sourceTree = BUILT_PRODUCTS_DIR; };
+		E2955697300948B9009F939C /* PunktfunkWidgetsExtension.appex */ = {isa = PBXFileReference; explicitFileType = "wrapper.app-extension"; includeInIndex = 0; path = PunktfunkWidgetsExtension.appex; sourceTree = BUILT_PRODUCTS_DIR; };
+		E2955699300948B9009F939C /* WidgetKit.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = WidgetKit.framework; path = System/Library/Frameworks/WidgetKit.framework; sourceTree = SDKROOT; };
+		E295569B300948B9009F939C /* SwiftUI.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = SwiftUI.framework; path = System/Library/Frameworks/SwiftUI.framework; sourceTree = SDKROOT; };
+		E295577B30094CE5009F939C /* PunktfunkWidgetsExtension.entitlements */ = {isa = PBXFileReference; lastKnownFileType = text.plist.entitlements; path = PunktfunkWidgetsExtension.entitlements; sourceTree = "<group>"; };
 /* End PBXFileReference section */

+/* Begin PBXFileSystemSynchronizedBuildFileExceptionSet section */
+		E29556AD300948BA009F939C /* Exceptions for "PunktfunkWidgets" folder in "PunktfunkWidgetsExtension" target */ = {
+			isa = PBXFileSystemSynchronizedBuildFileExceptionSet;
+			membershipExceptions = (
+				Info.plist,
+			);
+			target = E2955696300948B9009F939C /* PunktfunkWidgetsExtension */;
+		};
+/* End PBXFileSystemSynchronizedBuildFileExceptionSet section */
+
 /* Begin PBXFileSystemSynchronizedRootGroup section */
 		AA0000000000000000000002 /* App */ = {
 			isa = PBXFileSystemSynchronizedRootGroup;
@@ -30,6 +72,14 @@
 			path = Sources/PunktfunkClient;
 			sourceTree = "<group>";
 		};
+		E295569D300948B9009F939C /* PunktfunkWidgets */ = {
+			isa = PBXFileSystemSynchronizedRootGroup;
+			exceptions = (
+				E29556AD300948BA009F939C /* Exceptions for "PunktfunkWidgets" folder in "PunktfunkWidgetsExtension" target */,
+			);
+			path = PunktfunkWidgets;
+			sourceTree = "<group>";
+		};
 /* End PBXFileSystemSynchronizedRootGroup section */

 /* Begin PBXFrameworksBuildPhase section */
@@ -58,14 +108,27 @@
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
+		E2955694300948B9009F939C /* Frameworks */ = {
+			isa = PBXFrameworksBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+				E2CAFE000000000000000001 /* PunktfunkShared in Frameworks */,
+				E295569C300948B9009F939C /* SwiftUI.framework in Frameworks */,
+				E295569A300948B9009F939C /* WidgetKit.framework in Frameworks */,
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
 /* End PBXFrameworksBuildPhase section */

 /* Begin PBXGroup section */
 		AA0000000000000000000007 = {
 			isa = PBXGroup;
 			children = (
+				E295577B30094CE5009F939C /* PunktfunkWidgetsExtension.entitlements */,
 				AA0000000000000000000002 /* App */,
 				AA0000000000000000000003 /* Sources/PunktfunkClient */,
+				E295569D300948B9009F939C /* PunktfunkWidgets */,
+				E2955698300948B9009F939C /* Frameworks */,
 				AA0000000000000000000008 /* Products */,
 			);
 			sourceTree = "<group>";
@@ -76,10 +139,20 @@
 				AA0000000000000000000001 /* Punktfunk.app */,
 				BB0000000000000000000001 /* Punktfunk-iOS.app */,
 				CC0000000000000000000001 /* Punktfunk-tvOS.app */,
+				E2955697300948B9009F939C /* PunktfunkWidgetsExtension.appex */,
 			);
 			name = Products;
 			sourceTree = "<group>";
 		};
+		E2955698300948B9009F939C /* Frameworks */ = {
+			isa = PBXGroup;
+			children = (
+				E2955699300948B9009F939C /* WidgetKit.framework */,
+				E295569B300948B9009F939C /* SwiftUI.framework */,
+			);
+			name = Frameworks;
+			sourceTree = "<group>";
+		};
 /* End PBXGroup section */

 /* Begin PBXNativeTarget section */
@@ -114,10 +187,12 @@
 				BB000000000000000000000B /* Sources */,
 				BB0000000000000000000004 /* Frameworks */,
 				BB000000000000000000000C /* Resources */,
+				E29556AA300948BA009F939C /* Embed Foundation Extensions */,
 			);
 			buildRules = (
 			);
 			dependencies = (
+				E29556A8300948BA009F939C /* PBXTargetDependency */,
 			);
 			fileSystemSynchronizedGroups = (
 				AA0000000000000000000002 /* App */,
@@ -156,6 +231,29 @@
 			productReference = CC0000000000000000000001 /* Punktfunk-tvOS.app */;
 			productType = "com.apple.product-type.application";
 		};
+		E2955696300948B9009F939C /* PunktfunkWidgetsExtension */ = {
+			isa = PBXNativeTarget;
+			buildConfigurationList = E29556AE300948BA009F939C /* Build configuration list for PBXNativeTarget "PunktfunkWidgetsExtension" */;
+			buildPhases = (
+				E2955693300948B9009F939C /* Sources */,
+				E2955694300948B9009F939C /* Frameworks */,
+				E2955695300948B9009F939C /* Resources */,
+			);
+			buildRules = (
+			);
+			dependencies = (
+			);
+			fileSystemSynchronizedGroups = (
+				E295569D300948B9009F939C /* PunktfunkWidgets */,
+			);
+			name = PunktfunkWidgetsExtension;
+			packageProductDependencies = (
+				E2CAFE000000000000000002 /* PunktfunkShared */,
+			);
+			productName = PunktfunkWidgetsExtension;
+			productReference = E2955697300948B9009F939C /* PunktfunkWidgetsExtension.appex */;
+			productType = "com.apple.product-type.app-extension";
+		};
 /* End PBXNativeTarget section */

 /* Begin PBXProject section */
@@ -163,11 +261,15 @@
 			isa = PBXProject;
 			attributes = {
 				BuildIndependentTargetsInParallel = 1;
+				LastSwiftUpdateCheck = 2700;
 				LastUpgradeCheck = 2700;
 				TargetAttributes = {
 					AA0000000000000000000009 = {
 						CreatedOnToolsVersion = 26.0;
 					};
+					E2955696300948B9009F939C = {
+						CreatedOnToolsVersion = 27.0;
+					};
 				};
 			};
 			buildConfigurationList = AA000000000000000000000E /* Build configuration list for PBXProject "Punktfunk" */;
@@ -190,6 +292,7 @@
 				AA0000000000000000000009 /* Punktfunk */,
 				BB0000000000000000000009 /* Punktfunk-iOS */,
 				CC0000000000000000000009 /* Punktfunk-tvOS */,
+				E2955696300948B9009F939C /* PunktfunkWidgetsExtension */,
 			);
 		};
 /* End PBXProject section */
@@ -216,6 +319,13 @@
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
+		E2955695300948B9009F939C /* Resources */ = {
+			isa = PBXResourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
 /* End PBXResourcesBuildPhase section */

 /* Begin PBXSourcesBuildPhase section */
@@ -240,8 +350,23 @@
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
+		E2955693300948B9009F939C /* Sources */ = {
+			isa = PBXSourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
 /* End PBXSourcesBuildPhase section */

+/* Begin PBXTargetDependency section */
+		E29556A8300948BA009F939C /* PBXTargetDependency */ = {
+			isa = PBXTargetDependency;
+			target = E2955696300948B9009F939C /* PunktfunkWidgetsExtension */;
+			targetProxy = E29556A7300948BA009F939C /* PBXContainerItemProxy */;
+		};
+/* End PBXTargetDependency section */
+
 /* Begin XCBuildConfiguration section */
 		AA0000000000000000000010 /* Debug */ = {
 			isa = XCBuildConfiguration;
@@ -436,7 +561,6 @@
 				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.";
@@ -478,7 +602,6 @@
 				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.";
@@ -566,6 +689,97 @@
 			};
 			name = Release;
 		};
+		E29556AB300948BA009F939C /* Debug */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
+				ASSETCATALOG_COMPILER_WIDGET_BACKGROUND_COLOR_NAME = WidgetBackground;
+				CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE;
+				CLANG_CXX_LANGUAGE_STANDARD = "gnu++20";
+				CLANG_ENABLE_OBJC_WEAK = YES;
+				CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR;
+				CLANG_WARN_DOCUMENTATION_COMMENTS = YES;
+				CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR;
+				CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE;
+				CODE_SIGN_ENTITLEMENTS = PunktfunkWidgetsExtension.entitlements;
+				CODE_SIGN_STYLE = Automatic;
+				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = F4H37KF6WC;
+				GCC_C_LANGUAGE_STANDARD = gnu17;
+				GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR;
+				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
+				GENERATE_INFOPLIST_FILE = YES;
+				INFOPLIST_FILE = PunktfunkWidgets/Info.plist;
+				INFOPLIST_KEY_CFBundleDisplayName = PunktfunkWidgets;
+				INFOPLIST_KEY_NSHumanReadableCopyright = "";
+				IPHONEOS_DEPLOYMENT_TARGET = 27.0;
+				LD_RUNPATH_SEARCH_PATHS = (
+					"$(inherited)",
+					"@executable_path/Frameworks",
+					"@executable_path/../../Frameworks",
+				);
+				LOCALIZATION_PREFERS_STRING_CATALOGS = YES;
+				MARKETING_VERSION = 1.0;
+				PRODUCT_BUNDLE_IDENTIFIER = io.unom.punktfunk.widgets;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				REGISTER_APP_GROUPS = YES;
+				SDKROOT = iphoneos;
+				SKIP_INSTALL = YES;
+				STRING_CATALOG_GENERATE_SYMBOLS = YES;
+				SWIFT_APPROACHABLE_CONCURRENCY = YES;
+				SWIFT_EMIT_LOC_STRINGS = YES;
+				SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY = YES;
+				SWIFT_VERSION = 5.0;
+				TARGETED_DEVICE_FAMILY = "1,2";
+			};
+			name = Debug;
+		};
+		E29556AC300948BA009F939C /* Release */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
+				ASSETCATALOG_COMPILER_WIDGET_BACKGROUND_COLOR_NAME = WidgetBackground;
+				CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE;
+				CLANG_CXX_LANGUAGE_STANDARD = "gnu++20";
+				CLANG_ENABLE_OBJC_WEAK = YES;
+				CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR;
+				CLANG_WARN_DOCUMENTATION_COMMENTS = YES;
+				CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR;
+				CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE;
+				CODE_SIGN_ENTITLEMENTS = PunktfunkWidgetsExtension.entitlements;
+				CODE_SIGN_STYLE = Automatic;
+				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = F4H37KF6WC;
+				GCC_C_LANGUAGE_STANDARD = gnu17;
+				GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR;
+				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
+				GENERATE_INFOPLIST_FILE = YES;
+				INFOPLIST_FILE = PunktfunkWidgets/Info.plist;
+				INFOPLIST_KEY_CFBundleDisplayName = PunktfunkWidgets;
+				INFOPLIST_KEY_NSHumanReadableCopyright = "";
+				IPHONEOS_DEPLOYMENT_TARGET = 27.0;
+				LD_RUNPATH_SEARCH_PATHS = (
+					"$(inherited)",
+					"@executable_path/Frameworks",
+					"@executable_path/../../Frameworks",
+				);
+				LOCALIZATION_PREFERS_STRING_CATALOGS = YES;
+				MARKETING_VERSION = 1.0;
+				PRODUCT_BUNDLE_IDENTIFIER = io.unom.punktfunk.widgets;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				REGISTER_APP_GROUPS = YES;
+				SDKROOT = iphoneos;
+				SKIP_INSTALL = YES;
+				STRING_CATALOG_GENERATE_SYMBOLS = YES;
+				SWIFT_APPROACHABLE_CONCURRENCY = YES;
+				SWIFT_EMIT_LOC_STRINGS = YES;
+				SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY = YES;
+				SWIFT_VERSION = 5.0;
+				TARGETED_DEVICE_FAMILY = "1,2";
+				VALIDATE_PRODUCT = YES;
+			};
+			name = Release;
+		};
 /* End XCBuildConfiguration section */

 /* Begin XCConfigurationList section */
@@ -605,6 +819,15 @@
 			defaultConfigurationIsVisible = 0;
 			defaultConfigurationName = Release;
 		};
+		E29556AE300948BA009F939C /* Build configuration list for PBXNativeTarget "PunktfunkWidgetsExtension" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				E29556AB300948BA009F939C /* Debug */,
+				E29556AC300948BA009F939C /* Release */,
+			);
+			defaultConfigurationIsVisible = 0;
+			defaultConfigurationName = Release;
+		};
 /* End XCConfigurationList section */

 /* Begin XCLocalSwiftPackageReference section */
@@ -638,6 +861,10 @@
 			isa = XCSwiftPackageProductDependency;
 			productName = PunktfunkKit;
 		};
+		E2CAFE000000000000000002 /* PunktfunkShared */ = {
+			isa = XCSwiftPackageProductDependency;
+			productName = PunktfunkShared;
+		};
 		DD0000000000000000000002 /* SwiftUINavigationTransitions */ = {
 			isa = XCSwiftPackageProductDependency;
 			package = DD0000000000000000000001 /* XCRemoteSwiftPackageReference "swiftui-navigation-transitions" */;
@@ -0,0 +1,11 @@
+{
+  "colors" : [
+    {
+      "idiom" : "universal"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}
@@ -0,0 +1,35 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "platform" : "ios",
+      "size" : "1024x1024"
+    },
+    {
+      "appearances" : [
+        {
+          "appearance" : "luminosity",
+          "value" : "dark"
+        }
+      ],
+      "idiom" : "universal",
+      "platform" : "ios",
+      "size" : "1024x1024"
+    },
+    {
+      "appearances" : [
+        {
+          "appearance" : "luminosity",
+          "value" : "tinted"
+        }
+      ],
+      "idiom" : "universal",
+      "platform" : "ios",
+      "size" : "1024x1024"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}
@@ -0,0 +1,6 @@
+{
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}
@@ -0,0 +1,11 @@
+{
+  "colors" : [
+    {
+      "idiom" : "universal"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}
@@ -0,0 +1,186 @@
+// Home-Screen / Lock-Screen quick-launch widget (kind "PunktfunkHosts"). Reads the saved-host
+// store from the shared App-Group suite, sorts most-recent-first, and deep-links each host into a
+// session via `punktfunk://connect/<uuid>` — the app's onOpenURL routes it through the normal
+// connect path (trust policy / WoL / approval all apply).
+//
+// No reachability probing in v1 (a UDP check has no place in a timeline build; WoL handles offline
+// hosts on tap). Timeline is a single `.never` entry — the app pushes reloads on store changes
+// (HostStore → WidgetCenter.reloadTimelines).
+
+import SwiftUI
+import WidgetKit
+
+import PunktfunkShared
+
+// MARK: - Timeline
+
+struct HostsEntry: TimelineEntry {
+    let date: Date
+    let hosts: [StoredHost]
+}
+
+struct HostsProvider: TimelineProvider {
+    func placeholder(in context: Context) -> HostsEntry {
+        HostsEntry(date: .now, hosts: [])
+    }
+
+    func getSnapshot(in context: Context, completion: @escaping (HostsEntry) -> Void) {
+        completion(HostsEntry(date: .now, hosts: Self.loadHosts()))
+    }
+
+    func getTimeline(in context: Context, completion: @escaping (Timeline<HostsEntry>) -> Void) {
+        // Single entry, never auto-refresh: the app reloads this timeline whenever the store
+        // changes (a new host, a fresh connect reordering by recency).
+        let entry = HostsEntry(date: .now, hosts: Self.loadHosts())
+        completion(Timeline(entries: [entry], policy: .never))
+    }
+
+    /// Decode the shared-suite host JSON (same wire format the app writes), most-recent first.
+    static func loadHosts() -> [StoredHost] {
+        guard let data = AppGroup.defaults.data(forKey: DefaultsKey.hosts),
+              let hosts = try? JSONDecoder().decode([StoredHost].self, from: data)
+        else { return [] }
+        return hosts.sorted {
+            ($0.lastConnected ?? .distantPast) > ($1.lastConnected ?? .distantPast)
+        }
+    }
+}
+
+// MARK: - Widget
+
+struct HostsWidget: Widget {
+    var body: some WidgetConfiguration {
+        StaticConfiguration(kind: "PunktfunkHosts", provider: HostsProvider()) { entry in
+            HostsWidgetView(entry: entry)
+                .containerBackground(.fill.tertiary, for: .widget)
+        }
+        .configurationDisplayName("Punktfunk Hosts")
+        .description("Quick-launch your recent streaming hosts.")
+        .supportedFamilies([
+            .systemSmall, .systemMedium, .accessoryCircular, .accessoryRectangular,
+        ])
+    }
+}
+
+// MARK: - Views
+
+struct HostsWidgetView: View {
+    @Environment(\.widgetFamily) private var family
+    let entry: HostsEntry
+
+    var body: some View {
+        switch family {
+        case .systemMedium:
+            MediumHostsView(hosts: entry.hosts)
+        case .accessoryCircular:
+            CircularHostView(host: entry.hosts.first)
+        case .accessoryRectangular:
+            RectangularHostView(host: entry.hosts.first)
+        default: // systemSmall + fallback
+            SmallHostView(host: entry.hosts.first)
+        }
+    }
+}
+
+/// Deep link that connects to a stored host.
+private func connectURL(_ host: StoredHost) -> URL {
+    DeepLink.connect(host: host.id, launchID: nil).url
+}
+
+private struct SmallHostView: View {
+    let host: StoredHost?
+    var body: some View {
+        if let host {
+            VStack(alignment: .leading, spacing: 6) {
+                Image(systemName: "play.tv.fill")
+                    .font(.title2)
+                    .foregroundStyle(.tint)
+                Spacer(minLength: 0)
+                Text(host.displayName)
+                    .font(.headline)
+                    .lineLimit(2)
+                if let last = host.lastConnected {
+                    Text(last, format: .relative(presentation: .named))
+                        .font(.caption2)
+                        .foregroundStyle(.secondary)
+                }
+            }
+            .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
+            .widgetURL(connectURL(host))
+        } else {
+            EmptyHostView()
+        }
+    }
+}
+
+private struct MediumHostsView: View {
+    let hosts: [StoredHost]
+    var body: some View {
+        if hosts.isEmpty {
+            EmptyHostView()
+        } else {
+            VStack(alignment: .leading, spacing: 8) {
+                Text("Punktfunk")
+                    .font(.caption).bold()
+                    .foregroundStyle(.tint)
+                ForEach(hosts.prefix(4)) { host in
+                    Link(destination: connectURL(host)) {
+                        HStack {
+                            Image(systemName: "play.tv.fill")
+                                .foregroundStyle(.tint)
+                            Text(host.displayName)
+                                .font(.subheadline)
+                                .lineLimit(1)
+                            Spacer()
+                            if let last = host.lastConnected {
+                                Text(last, format: .relative(presentation: .named))
+                                    .font(.caption2)
+                                    .foregroundStyle(.secondary)
+                            }
+                        }
+                    }
+                }
+                Spacer(minLength: 0)
+            }
+            .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
+        }
+    }
+}
+
+private struct CircularHostView: View {
+    let host: StoredHost?
+    var body: some View {
+        ZStack {
+            AccessoryWidgetBackground()
+            Image(systemName: "play.tv.fill")
+        }
+        .widgetURL(host.map(connectURL))
+    }
+}
+
+private struct RectangularHostView: View {
+    let host: StoredHost?
+    var body: some View {
+        HStack {
+            Image(systemName: "play.tv.fill")
+            Text(host?.displayName ?? "Punktfunk")
+                .lineLimit(1)
+        }
+        .widgetURL(host.map(connectURL))
+    }
+}
+
+private struct EmptyHostView: View {
+    var body: some View {
+        VStack(spacing: 6) {
+            Image(systemName: "play.tv")
+                .font(.title2)
+                .foregroundStyle(.secondary)
+            Text("Open Punktfunk to add a host.")
+                .font(.caption)
+                .multilineTextAlignment(.center)
+                .foregroundStyle(.secondary)
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+    }
+}
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>NSExtension</key>
+	<dict>
+		<key>NSExtensionPointIdentifier</key>
+		<string>com.apple.widgetkit-extension</string>
+	</dict>
+</dict>
+</plist>
@@ -0,0 +1,20 @@
+// The widget extension's entry point. ONE extension target (bundle id io.unom.punktfunk.widgets,
+// iOS only) hosts both the launcher widgets and the Live Activity UI. It links PunktfunkShared and
+// NOTHING else — never PunktfunkKit (Rust staticlib + presentation layer would blow the widget
+// process's ~30 MB budget).
+//
+// These files are NOT part of the SwiftPM package (Package.swift doesn't declare a PunktfunkWidgets
+// target, so `swift build` ignores the directory). They compile only in the Xcode widget-extension
+// target you add pointing at this folder — see design/apple-live-activities-and-widgets.md §M1 and
+// the GUI checklist.
+
+import SwiftUI
+import WidgetKit
+
+@main
+struct PunktfunkWidgetBundle: WidgetBundle {
+    var body: some Widget {
+        HostsWidget()
+        PunktfunkSessionLiveActivity()
+    }
+}
@@ -0,0 +1,140 @@
+// The Live Activity UI (Lock Screen banner + Dynamic Island) for a running session. The app owns
+// the Activity's lifecycle (SessionActivityController); this is only its presentation, rendered in
+// the widget-extension process from the shared `PunktfunkSessionAttributes`.
+//
+// The End button runs `EndStreamIntent` (a LiveActivityIntent) IN THE APP's process, which posts
+// .punktfunkEndActiveSession → the app disconnects. Elapsed time ticks client-side via
+// Text(timerInterval:) — no per-second push.
+
+import ActivityKit
+import AppIntents
+import SwiftUI
+import WidgetKit
+
+import PunktfunkShared
+
+struct PunktfunkSessionLiveActivity: Widget {
+    var body: some WidgetConfiguration {
+        ActivityConfiguration(for: PunktfunkSessionAttributes.self) { context in
+            LockScreenView(context: context)
+                .activitySystemActionForegroundColor(.white)
+        } dynamicIsland: { context in
+            DynamicIsland {
+                DynamicIslandExpandedRegion(.leading) {
+                    Label {
+                        Text(context.attributes.hostName).font(.caption).lineLimit(1)
+                    } icon: {
+                        Image(systemName: "play.tv.fill")
+                    }
+                    .foregroundStyle(.tint)
+                }
+                DynamicIslandExpandedRegion(.trailing) {
+                    Text(timerInterval: context.state.startedAt...Date.distantFuture, countsDown: false)
+                        .font(.caption).monospacedDigit()
+                        .frame(maxWidth: 56)
+                        .foregroundStyle(.secondary)
+                }
+                DynamicIslandExpandedRegion(.center) {
+                    if let title = context.attributes.launchTitle {
+                        Text(title).font(.caption2).lineLimit(1).foregroundStyle(.secondary)
+                    }
+                }
+                DynamicIslandExpandedRegion(.bottom) {
+                    VStack(spacing: 6) {
+                        Text(context.state.modeLine)
+                            .font(.caption2).foregroundStyle(.secondary).lineLimit(1)
+                        StageLine(state: context.state)
+                        EndButton()
+                    }
+                }
+            } compactLeading: {
+                Image(systemName: "play.tv.fill").foregroundStyle(.tint)
+            } compactTrailing: {
+                Text(timerInterval: context.state.startedAt...Date.distantFuture, countsDown: false)
+                    .monospacedDigit()
+                    .frame(maxWidth: 44)
+            } minimal: {
+                Image(systemName: "play.tv.fill").foregroundStyle(.tint)
+            }
+        }
+    }
+}
+
+// MARK: - Lock Screen banner
+
+private struct LockScreenView: View {
+    let context: ActivityViewContext<PunktfunkSessionAttributes>
+
+    var body: some View {
+        HStack(alignment: .top, spacing: 12) {
+            Image(systemName: "play.tv.fill")
+                .font(.title2)
+                .foregroundStyle(.tint)
+            VStack(alignment: .leading, spacing: 3) {
+                HStack {
+                    Text(context.attributes.hostName).font(.headline).lineLimit(1)
+                    Spacer()
+                    Text(timerInterval: context.state.startedAt...Date.distantFuture, countsDown: false)
+                        .font(.subheadline).monospacedDigit()
+                        .foregroundStyle(.secondary)
+                }
+                if let title = context.attributes.launchTitle {
+                    Text(title).font(.caption).foregroundStyle(.secondary).lineLimit(1)
+                }
+                Text(context.state.modeLine)
+                    .font(.caption2).foregroundStyle(.secondary).lineLimit(1)
+                StageLine(state: context.state)
+            }
+            if context.state.stage == .background {
+                EndButton()
+            }
+        }
+        .padding()
+    }
+}
+
+// MARK: - Shared pieces
+
+/// The stage badge + (while backgrounded) the auto-disconnect countdown.
+private struct StageLine: View {
+    let state: PunktfunkSessionAttributes.ContentState
+
+    var body: some View {
+        switch state.stage {
+        case .streaming:
+            EmptyView()
+        case .background:
+            if let deadline = state.backgroundDeadline {
+                HStack(spacing: 3) {
+                    Text("Keeps running for")
+                    Text(timerInterval: Date()...deadline, countsDown: true)
+                        .monospacedDigit()
+                }
+                .font(.caption2)
+                .foregroundStyle(.secondary)
+            } else {
+                badge("Running in background", .orange)
+            }
+        case .reconnecting:
+            badge("Reconnecting…", .yellow)
+        case .ending:
+            badge("Session ended", .secondary)
+        }
+    }
+
+    private func badge(_ text: String, _ color: Color) -> some View {
+        Text(text).font(.caption2).foregroundStyle(color)
+    }
+}
+
+/// End-stream button — runs EndStreamIntent in the app process (LiveActivityIntent).
+private struct EndButton: View {
+    var body: some View {
+        Button(intent: EndStreamIntent()) {
+            Label("End", systemImage: "stop.fill")
+                .font(.caption).bold()
+        }
+        .tint(.red)
+        .buttonStyle(.bordered)
+    }
+}
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>com.apple.security.application-groups</key>
+	<array>
+		<string>group.io.unom.punktfunk</string>
+	</array>
+</dict>
+</plist>
@@ -0,0 +1,10 @@
+import Foundation
+import PunktfunkKit
+
+/// A fresh `pair=required`/unknown host pending a trust decision: drives both the "request access
+/// vs. pair with PIN" choice and the subsequent approval wait. `advertisedFingerprint` is the
+/// discovered host's advertised cert (nil for a manually-typed host → trust-on-first-use).
+struct ApprovalRequest {
+    let host: StoredHost
+    let advertisedFingerprint: Data?
+}
@@ -24,6 +24,7 @@ struct ContentView: View {
    @AppStorage(DefaultsKey.streamWidth) private var width = 1920
    @AppStorage(DefaultsKey.streamHeight) private var height = 1080
    @AppStorage(DefaultsKey.streamHz) private var hz = 60
+    @AppStorage(DefaultsKey.renderScale) private var renderScale = 1.0
    @AppStorage(DefaultsKey.compositor) private var compositor = 0
    @AppStorage(DefaultsKey.gamepadType) private var gamepadType = 0
    @AppStorage(DefaultsKey.bitrateKbps) private var bitrateKbps = 0
@@ -46,10 +47,20 @@ struct ContentView: View {
        case "h264": return PunktfunkConnection.codecH264
        case "hevc": return PunktfunkConnection.codecHEVC
        case "av1": return PunktfunkConnection.codecAV1
+        case "pyrowave": return PunktfunkConnection.codecPyroWave
        default: return 0
        }
    }
    @State private var showAddHost = false
+    /// A `punktfunk://` deep link (widget / Siri / Shortcuts) couldn't be honored — unknown host, or
+    /// a live session is already up. Surfaced as an informational alert (distinct from the
+    /// "Connection failed" one, which is for actual connect errors).
+    @State private var deepLinkNotice: String?
+    #if os(iOS)
+    /// Owns the Live Activity for the running session (Lock Screen / Dynamic Island). Driven from
+    /// the session model's published state below; iPhone/iPad only.
+    @State private var liveActivity = SessionActivityController()
+    #endif
    @State private var pairingTarget: StoredHost?
    /// A fresh `pair=required`/unknown host the user tapped: drives the choice between no-PIN
    /// delegated approval ("Request Access") and the SPAKE2 PIN ceremony (rule 3b).
@@ -91,6 +102,14 @@ struct ContentView: View {
    /// 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
+    /// Background keep-alive (Settings → General, iOS-only). Default OFF (today's freeze-on-background
+    /// is the default). When on, backgrounding a live session keeps audio + the connection alive and
+    /// drops video, auto-disconnecting after `backgroundTimeoutMinutes`.
+    @AppStorage(DefaultsKey.backgroundKeepAlive) private var backgroundKeepAlive = false
+    @AppStorage(DefaultsKey.backgroundTimeoutMinutes) private var backgroundTimeoutMinutes = 10
+    /// scenePhase drives the keep-alive: use THIS, not the willResignActive observers — resign-active
+    /// also fires for Control Center / app-switcher peeks, where the disconnect timer must not start.
+    @Environment(\.scenePhase) private var scenePhase
    private var gamepadUIActive: Bool {
        GamepadUIEnvironment.isActive(
            gamepadConnected: gamepadManager.active != nil, enabledSetting: gamepadUIEnabled)
@@ -112,7 +131,62 @@ struct ContentView: View {
        .onAppear {
            seedDefaultModeIfNeeded()
            autoConnectIfAsked()
+            #if os(iOS)
+            SessionActivityController.sweepOrphans() // end any Activity a prior killed launch left
+            #endif
        }
+        // Deep links (widget quick-launch, Siri/Shortcuts): route into the SAME connect path a card
+        // tap uses, so trust policy / WoL / the approval sheet all come along. Never starts a
+        // parallel session — this drives the one `model` ContentView owns.
+        .onOpenURL { handleDeepLink($0) }
+        #if os(iOS)
+        // Background keep-alive driver (opt-in). Only .background/.active matter; .inactive (a
+        // transient peek) is ignored so the disconnect timer never starts for a Control-Center pull.
+        .onChange(of: scenePhase) { _, phase in
+            switch phase {
+            case .background:
+                if backgroundKeepAlive, model.phase == .streaming {
+                    model.enterBackground(timeoutMinutes: backgroundTimeoutMinutes)
+                }
+            case .active:
+                model.exitBackground()
+            default:
+                break
+            }
+        }
+        // Live Activity lifecycle, driven from the model's published state.
+        .onChange(of: model.phase) { _, phase in
+            switch phase {
+            case .streaming:
+                if let host = model.activeHost {
+                    liveActivity.begin(
+                        hostID: host.id, hostName: host.displayName,
+                        launchTitle: nil, // no live foreground-app title mid-session (v1)
+                        modeLine: currentModeLine(), startedAt: Date())
+                }
+            case .idle:
+                liveActivity.end()
+            default:
+                break
+            }
+        }
+        .onChange(of: model.isBackgrounded) { _, backgrounded in
+            liveActivity.update {
+                $0.stage = backgrounded ? .background : .streaming
+                $0.backgroundDeadline = model.backgroundDeadline
+            }
+        }
+        // The Live Activity's / Shortcuts' End button runs EndStreamIntent in-process, which posts
+        // this — tear the session down deliberately (quit-close the host).
+        .onReceive(NotificationCenter.default.publisher(for: .punktfunkEndActiveSession)) { _ in
+            model.disconnect(deliberate: true)
+        }
+        // Connect App Intent (Siri/Shortcuts): route its punktfunk:// URL through the same handler
+        // as a widget tap.
+        .onReceive(NotificationCenter.default.publisher(for: .punktfunkOpenDeepLink)) { note in
+            if let url = note.object as? URL { handleDeepLink(url) }
+        }
+        #endif
        .onChange(of: model.phase) { _, phase in
            switch phase {
            case .streaming:
@@ -150,6 +224,9 @@ struct ContentView: View {
        #if !os(tvOS)
        .focusedSceneValue(\.sessionFocus, SessionFocus(
            isStreaming: model.connection != nil,
+            clipboardAvailable: model.connection?.hostSupportsClipboard == true,
+            clipboardOn: model.clipboardEnabled,
+            toggleClipboard: { model.toggleClipboardSync() },
            disconnect: { model.disconnect() }))
        #endif
        #if os(macOS)
@@ -261,6 +338,59 @@ struct ContentView: View {
                + "console (port 3000 → Pairing). This device connects automatically once you "
                + "approve it — no need to reconnect.")
        }
+        // Informational deep-link outcome (unknown host / already streaming). Not an error.
+        .alert("Can't open", isPresented: deepLinkNoticePresented) {
+            Button("OK", role: .cancel) {}
+        } message: {
+            Text(deepLinkNotice ?? "")
+        }
+    }
+
+    /// Presentation flag for the informational deep-link alert. Extracted from the `.alert` call so
+    /// the manual get/set Binding type-checks on its own instead of inflating the body chain's
+    /// budget (adding it inline tips SwiftUI's per-expression limit — see the split sections idiom).
+    private var deepLinkNoticePresented: Binding<Bool> {
+        Binding(get: { deepLinkNotice != nil }, set: { if !$0 { deepLinkNotice = nil } })
+    }
+
+    #if os(iOS)
+    /// The Live Activity mode line, e.g. "2560×1440 @120 · HEVC · HDR", from the live connection.
+    private func currentModeLine() -> String {
+        guard let c = model.connection else { return "" }
+        let codec: String
+        switch c.videoCodec {
+        case .h264: codec = "H.264"
+        case .hevc: codec = "HEVC"
+        case .av1: codec = "AV1"
+        case .pyrowave: codec = "PyroWave"
+        }
+        var line = "\(c.width)×\(c.height)"
+        if c.refreshHz > 0 { line += " @\(c.refreshHz)" }
+        line += " · \(codec)"
+        if c.isHDR { line += " · HDR" }
+        return line
+    }
+    #endif
+
+    /// Route a `punktfunk://` deep link into the existing connect path. Rules (per design):
+    /// unknown host → notice + no-op; a live session is up → ignore if it's the same host, else
+    /// tell the user to end the current one first (NEVER tear down a live session on a background
+    /// tap); otherwise the normal `connect` — trust policy, WoL and the approval sheet all apply.
+    private func handleDeepLink(_ url: URL) {
+        guard case let .connect(hostID, launchID)? = DeepLink(url) else { return }
+        guard let host = store.hosts.first(where: { $0.id == hostID }) else {
+            deepLinkNotice = "That host isn't saved on this device."
+            return
+        }
+        if model.phase != .idle {
+            guard model.activeHost?.id == hostID else {
+                let current = model.activeHost?.displayName ?? "a host"
+                deepLinkNotice = "Already streaming \(current). End that session first."
+                return
+            }
+            return // deep-linked to the host we're already on — nothing to do
+        }
+        connect(host, launchID: launchID)
    }

    private var home: some View {
@@ -609,6 +739,17 @@ struct ContentView: View {
    /// host is back online. `prepareWake` still runs here to LEARN/refresh the MAC now that the host
    /// is advertising (and is a harmless no-op otherwise). `onUnreachable` hands a plain connect
    /// failure back to the caller (the wake-wait fallback) instead of the error alert.
+    /// The stream mode to request = the chosen resolution × the render scale, aspect-preserved,
+    /// even, and clamped to the codec's max dimension. > 1 supersamples for sharpness (the presenter
+    /// downscales the larger decoded frame to this display); < 1 renders under native and upscales.
+    /// The match-window path applies the SAME scale to the live window size in `MatchWindowFollower`.
+    private func scaledMode() -> (width: UInt32, height: UInt32) {
+        RenderScale.apply(
+            baseWidth: width, baseHeight: height,
+            scale: renderScale,
+            maxDimension: RenderScale.maxDimension(codec: codec))
+    }
+
    private func startSessionDirect(
        _ host: StoredHost, launchID: String? = nil,
        allowTofu: Bool, requestAccess: Bool = false, approvalReq: ApprovalRequest? = nil,
@@ -620,7 +761,7 @@ struct ContentView: View {
        if let approvalReq { awaitingApproval = approvalReq }
        model.connect(
            to: host,
-            width: UInt32(clamping: width), height: UInt32(clamping: height),
+            width: scaledMode().width, height: scaledMode().height,
            hz: UInt32(clamping: hz),
            compositor: PunktfunkConnection.Compositor(
                rawValue: UInt32(clamping: compositor)) ?? .auto,
@@ -803,7 +944,7 @@ struct ContentView: View {
        }
        model.connect(
            to: host,
-            width: UInt32(clamping: width), height: UInt32(clamping: height),
+            width: scaledMode().width, height: scaledMode().height,
            hz: UInt32(clamping: hz),
            compositor: pref,
            gamepad: pad,
@@ -814,71 +955,3 @@ struct ContentView: View {
            autoTrust: true)
    }
 }
-
-#if os(macOS)
-/// Drives the hosting window in/out of native fullscreen from SwiftUI state, and mirrors the
-/// window's ACTUAL fullscreen state back into `isFullscreen` (the user can also toggle it with the
-/// green button / ⌃⌘F — ContentView keys the session view's safe-area handling off the real state,
-/// not the setting). Mounted invisibly in the view tree; on each `active` change it captures the
-/// window and toggles fullscreen only when the current state differs (so it never fights a toggle
-/// already in flight, and never touches a window the user fullscreened manually unless `active`
-/// says otherwise).
-private struct FullscreenController: NSViewRepresentable {
-    let active: Bool
-    @Binding var isFullscreen: Bool
-
-    /// Holds the window's fullscreen-transition observers so they're rebound on a window change
-    /// and removed on dismantle.
-    final class Coordinator {
-        var observers: [NSObjectProtocol] = []
-        weak var observedWindow: NSWindow?
-        deinit { observers.forEach(NotificationCenter.default.removeObserver(_:)) }
-    }
-
-    func makeCoordinator() -> Coordinator { Coordinator() }
-
-    func makeNSView(context: Context) -> NSView { NSView() }
-
-    func updateNSView(_ view: NSView, context: Context) {
-        let want = active
-        let isFullscreen = $isFullscreen
-        let coordinator = context.coordinator
-        DispatchQueue.main.async {
-            guard let window = view.window else { return }
-            observeTransitions(of: window, coordinator: coordinator)
-            let isFull = window.styleMask.contains(.fullScreen)
-            if isFullscreen.wrappedValue != isFull { isFullscreen.wrappedValue = isFull }
-            if want != isFull { window.toggleFullScreen(nil) }
-        }
-    }
-
-    /// `willEnter` (not did) so the video goes edge-to-edge while the title bar is already
-    /// animating away; `didExit` so the top inset returns only once the title bar is back —
-    /// no black gap in either direction.
-    private func observeTransitions(of window: NSWindow, coordinator: Coordinator) {
-        guard coordinator.observedWindow !== window else { return }
-        coordinator.observers.forEach(NotificationCenter.default.removeObserver(_:))
-        coordinator.observers.removeAll()
-        coordinator.observedWindow = window
-        let isFullscreen = $isFullscreen
-        for (name, value) in [
-            (NSWindow.willEnterFullScreenNotification, true),
-            (NSWindow.didExitFullScreenNotification, false),
-        ] {
-            coordinator.observers.append(NotificationCenter.default.addObserver(
-                forName: name, object: window, queue: .main
-            ) { _ in
-                isFullscreen.wrappedValue = value
-            })
-        }
-    }
-}
-#endif
-
-/// A fresh `pair=required`/unknown host pending a trust decision: drives both the "request access
-/// vs. pair with PIN" choice and the subsequent approval wait. `advertisedFingerprint` is the
-/// discovered host's advertised cert (nil for a manually-typed host → trust-on-first-use).
-private struct ApprovalRequest {
-    let host: StoredHost
-    let advertisedFingerprint: Data?
-}
@@ -0,0 +1,83 @@
+import PunktfunkKit
+import SwiftUI
+
+#if os(macOS)
+import AppKit
+
+/// Drives the hosting window in/out of native fullscreen from SwiftUI state, and mirrors the
+/// window's ACTUAL fullscreen state back into `isFullscreen` (the user can also toggle it with the
+/// green button / ⌃⌘F — ContentView keys the session view's safe-area handling off the real state,
+/// not the setting). Mounted invisibly in the view tree; on each `active` change it captures the
+/// window and toggles fullscreen only when the current state differs (so it never fights a toggle
+/// already in flight, and never touches a window the user fullscreened manually unless `active`
+/// says otherwise).
+struct FullscreenController: NSViewRepresentable {
+    let active: Bool
+    @Binding var isFullscreen: Bool
+
+    /// Holds the window's fullscreen-transition observers so they're rebound on a window change
+    /// and removed on dismantle.
+    final class Coordinator {
+        var observers: [NSObjectProtocol] = []
+        weak var observedWindow: NSWindow?
+        /// The last `active` value we DROVE the window to. We toggle only when `active` itself
+        /// changes (stream start/end) — never to correct a mismatch — so a deliberate mid-session
+        /// toggle (⌃⌘F / the green button) isn't snapped back on the next SwiftUI update.
+        var lastActive: Bool?
+        deinit { observers.forEach(NotificationCenter.default.removeObserver(_:)) }
+    }
+
+    func makeCoordinator() -> Coordinator { Coordinator() }
+
+    func makeNSView(context: Context) -> NSView { NSView() }
+
+    func updateNSView(_ view: NSView, context: Context) {
+        let want = active
+        let isFullscreen = $isFullscreen
+        let coordinator = context.coordinator
+        DispatchQueue.main.async {
+            guard let window = view.window else { return }
+            observeTransitions(of: window, coordinator: coordinator)
+            let isFull = window.styleMask.contains(.fullScreen)
+            if isFullscreen.wrappedValue != isFull { isFullscreen.wrappedValue = isFull }
+            // Drive the window only on an `active` EDGE (stream start/end), not to close a mismatch —
+            // so a user's ⌃⌘F / green-button toggle stays put. First pass (lastActive == nil) just
+            // records the state without toggling, so mounting never yanks a window into fullscreen.
+            if coordinator.lastActive != want {
+                coordinator.lastActive = want
+                if want != isFull { window.toggleFullScreen(nil) }
+            }
+        }
+    }
+
+    /// `willEnter` (not did) so the video goes edge-to-edge while the title bar is already
+    /// animating away; `didExit` so the top inset returns only once the title bar is back —
+    /// no black gap in either direction.
+    private func observeTransitions(of window: NSWindow, coordinator: Coordinator) {
+        guard coordinator.observedWindow !== window else { return }
+        coordinator.observers.forEach(NotificationCenter.default.removeObserver(_:))
+        coordinator.observers.removeAll()
+        coordinator.observedWindow = window
+        let isFullscreen = $isFullscreen
+        for (name, value) in [
+            (NSWindow.willEnterFullScreenNotification, true),
+            (NSWindow.didExitFullScreenNotification, false),
+        ] {
+            coordinator.observers.append(NotificationCenter.default.addObserver(
+                forName: name, object: window, queue: .main
+            ) { _ in
+                isFullscreen.wrappedValue = value
+            })
+        }
+        // The Stream menu's "Toggle Fullscreen" (⌃⌘F) and InputCapture's captured-state interception
+        // both post this; flip the KEY window only (posted app-wide, object nil). The transition
+        // observers above then mirror the real state back into the binding.
+        coordinator.observers.append(NotificationCenter.default.addObserver(
+            forName: .punktfunkToggleFullscreen, object: nil, queue: .main
+        ) { [weak window] _ in
+            guard let window, window.isKeyWindow else { return }
+            window.toggleFullScreen(nil)
+        })
+    }
+}
+#endif
@@ -20,6 +20,12 @@ struct AddHostSheet: View {
    @State private var address: String
    @State private var port: Int
    @State private var mac: String
+    #if os(macOS)
+    /// Share the clipboard with this host (macOS sessions only; design
+    /// clipboard-and-file-transfer.md §5.3). Off by default; honored only when the host
+    /// advertises the capability at connect.
+    @State private var clipboardSync: Bool
+    #endif
    #if os(tvOS)
    private enum EditField: String, Identifiable {
        case name, address, port, mac
@@ -41,6 +47,9 @@ struct AddHostSheet: View {
        _port = State(initialValue: Int(existing?.port ?? 9777))
        let stored = existing?.macAddresses ?? []
        _mac = State(initialValue: (stored.isEmpty ? suggestedMacs : stored).joined(separator: ", "))
+        #if os(macOS)
+        _clipboardSync = State(initialValue: existing?.clipboardSync ?? false)
+        #endif
    }

    var body: some View {
@@ -96,6 +105,9 @@ struct AddHostSheet: View {
                    #if os(iOS)
                    .textInputAutocapitalization(.never)
                    #endif
+                #if os(macOS)
+                Toggle("Share clipboard with this host", isOn: $clipboardSync)
+                #endif
            }
            #if !os(tvOS)
            .formStyle(.grouped)
@@ -147,6 +159,11 @@ struct AddHostSheet: View {
        host.address = address.trimmingCharacters(in: .whitespaces)
        host.port = UInt16(clamping: port)
        host.macAddresses = Self.parseMacs(mac)
+        #if os(macOS)
+        // nil when off: the key stays absent from the saved JSON (forward-compat, and "never
+        // opted in" and "opted out" read the same — off).
+        host.clipboardSync = clipboardSync ? true : nil
+        #endif
        onSave(host)
        dismiss()
    }
@@ -0,0 +1,102 @@
+// Siri / Shortcuts / Spotlight surface (design §M4). Deliberately thin: every action already has an
+// internal entry point — M0's deep-link router (connect / connect-and-launch), M3's in-process
+// end-session hook, and the existing Wake-on-LAN path — so these intents only wrap them.
+//
+// Gated os(iOS): the AppShortcutsProvider bundles `EndStreamIntent`, which is a LiveActivityIntent
+// (iPhone/iPad only). Connect/Wake themselves are plain AppIntents; they live here with the
+// provider rather than being split across platforms. `HostEntity` (the parameter type) is in
+// PunktfunkShared so the widget's configuration intent can share it.
+
+#if os(iOS)
+import AppIntents
+import Foundation
+import PunktfunkKit
+
+/// Load a full saved host (MACs, address) from the shared App-Group store by id — HostEntity only
+/// carries id + name.
+private func loadStoredHost(_ id: UUID) -> StoredHost? {
+    guard let data = AppGroup.defaults.data(forKey: DefaultsKey.hosts),
+          let hosts = try? JSONDecoder().decode([StoredHost].self, from: data)
+    else { return nil }
+    return hosts.first { $0.id == id }
+}
+
+/// Start a session with a stored host (optionally launching a title). Foregrounds the app and
+/// routes through the SAME `.onOpenURL` path a widget tap uses — trust policy, WoL and the approval
+/// sheet all apply, and its guards (unknown host, already-streaming) hold.
+struct ConnectToHostIntent: AppIntent {
+    static let title: LocalizedStringResource = "Connect to Host"
+    static let description = IntentDescription("Start a Punktfunk streaming session with a host.")
+    static let openAppWhenRun = true
+
+    @Parameter(title: "Host") var host: HostEntity
+    @Parameter(title: "Game ID", description: "Optional store id like steam:570")
+    var launchID: String?
+
+    func perform() async throws -> some IntentResult {
+        let url = DeepLink.connect(host: host.id, launchID: launchID).url
+        await MainActor.run {
+            NotificationCenter.default.post(name: .punktfunkOpenDeepLink, object: url)
+        }
+        return .result()
+    }
+}
+
+/// Wake a sleeping host (magic packet). No `openAppWhenRun` — usable in automations ("when I get
+/// home, wake the tower") without foregrounding the app.
+struct WakeHostIntent: AppIntent {
+    static let title: LocalizedStringResource = "Wake Host"
+    static let description = IntentDescription("Send a Wake-on-LAN magic packet to a host.")
+
+    @Parameter(title: "Host") var host: HostEntity
+
+    func perform() async throws -> some IntentResult {
+        guard let stored = loadStoredHost(host.id), !stored.wakeMacs.isEmpty else {
+            throw IntentError.noWakeAddress
+        }
+        PunktfunkConnection.wakeOnLAN(macs: stored.wakeMacs, lastKnownIP: stored.address)
+        return .result()
+    }
+}
+
+/// Errors surfaced to Siri/Shortcuts. `CustomLocalizedStringResourceConvertible` makes the message
+/// show as the intent's failure text.
+enum IntentError: Error, CustomLocalizedStringResourceConvertible {
+    case noWakeAddress
+
+    var localizedStringResource: LocalizedStringResource {
+        switch self {
+        case .noWakeAddress:
+            // One string LITERAL — LocalizedStringResource is ExpressibleByStringLiteral, but a
+            // `"…" + "…"` concatenation is a runtime String it can't convert.
+            return "That host has no saved Wake-on-LAN address yet. Connect to it once so Punktfunk can learn it."
+        }
+    }
+}
+
+/// Zero-setup Siri / Spotlight phrases. Parameterized phrases resolve a `HostEntity` by name; stays
+/// well under the 10-shortcut cap.
+struct PunktfunkShortcuts: AppShortcutsProvider {
+    static var appShortcuts: [AppShortcut] {
+        AppShortcut(
+            intent: ConnectToHostIntent(),
+            phrases: [
+                "Connect to \(\.$host) in \(.applicationName)",
+                "Stream \(\.$host) with \(.applicationName)",
+            ],
+            shortTitle: "Connect", systemImageName: "play.tv.fill")
+        AppShortcut(
+            intent: WakeHostIntent(),
+            phrases: [
+                "Wake \(\.$host) with \(.applicationName)",
+            ],
+            shortTitle: "Wake Host", systemImageName: "power")
+        AppShortcut(
+            intent: EndStreamIntent(),
+            phrases: [
+                "End the \(.applicationName) stream",
+            ],
+            shortTitle: "End Stream", systemImageName: "stop.fill")
+    }
+}
+#endif
@@ -0,0 +1,89 @@
+// Owns the ActivityKit Live Activity lifecycle for a streaming session (iPhone/iPad only). Driven
+// by ContentView from the session model's published state (phase / isBackgrounded / deadline) so
+// none of this leaks into the cross-platform SessionModel. Local updates only (`pushType: nil`) —
+// the app process is alive whenever there's a session to report, so there's no push token plumbing.
+//
+// Gated os(iOS): ActivityKit is iPhone/iPad only. Minimum deployment is iOS 17, so no @available
+// guards are needed (Activity has existed since 16.1).
+
+#if os(iOS)
+import ActivityKit
+import Foundation
+// PunktfunkKit re-exports PunktfunkShared (@_exported), so the app target sees PunktfunkSessionAttributes
+// without linking the Shared product directly — same pattern as StoredHost in HostStore.
+import PunktfunkKit
+
+@MainActor
+final class SessionActivityController {
+    private var activity: Activity<PunktfunkSessionAttributes>?
+    /// The last pushed state, so an update can mutate one field and keep the rest (notably
+    /// `startedAt`, which the Lock-Screen timer ticks from).
+    private var state: PunktfunkSessionAttributes.ContentState?
+
+    /// How far past the next expected update to mark the content stale — a frozen opt-out session
+    /// then greys out instead of showing a lying clock.
+    private static let staleWindow: TimeInterval = 90
+
+    var isActive: Bool { activity != nil }
+
+    /// End any Activity left over from a previous launch that was killed mid-session. Call once at
+    /// app start (ContentView.onAppear).
+    static func sweepOrphans() {
+        Task {
+            for activity in Activity<PunktfunkSessionAttributes>.activities {
+                await activity.end(nil, dismissalPolicy: .immediate)
+            }
+        }
+    }
+
+    /// Start the Live Activity for a freshly-streaming session. No-op if the user disabled Live
+    /// Activities for the app, or one is already up.
+    func begin(hostID: UUID, hostName: String, launchTitle: String?, modeLine: String, startedAt: Date) {
+        guard ActivityAuthorizationInfo().areActivitiesEnabled, activity == nil else { return }
+        let attributes = PunktfunkSessionAttributes(
+            hostID: hostID, hostName: hostName, launchTitle: launchTitle)
+        let initial = PunktfunkSessionAttributes.ContentState(
+            stage: .streaming, startedAt: startedAt, modeLine: modeLine)
+        state = initial
+        do {
+            activity = try Activity.request(
+                attributes: attributes,
+                content: content(initial),
+                pushType: nil)
+        } catch {
+            activity = nil
+            state = nil
+        }
+    }
+
+    /// Coalesced update: mutate the running state in place (keeps `startedAt` etc.) and push once.
+    /// No-op when there's no live Activity.
+    func update(_ mutate: (inout PunktfunkSessionAttributes.ContentState) -> Void) {
+        guard let activity, var next = state else { return }
+        mutate(&next)
+        state = next
+        Task { await activity.update(content(next)) }
+    }
+
+    /// End with a final "ended" state, dismissed a few seconds later.
+    func end() {
+        guard let activity, var final = state else {
+            self.activity = nil
+            state = nil
+            return
+        }
+        self.activity = nil
+        state = nil
+        final.stage = .ending
+        final.backgroundDeadline = nil
+        Task {
+            await activity.end(content(final), dismissalPolicy: .after(.now + 4))
+        }
+    }
+
+    private func content(_ s: PunktfunkSessionAttributes.ContentState)
+        -> ActivityContent<PunktfunkSessionAttributes.ContentState> {
+        ActivityContent(state: s, staleDate: Date().addingTimeInterval(Self.staleWindow))
+    }
+}
+#endif
@@ -139,6 +139,18 @@ final class SessionModel: ObservableObject {
    private var audio: SessionAudio?
    private var gamepadCapture: GamepadCapture?
    private var gamepadFeedback: GamepadFeedback?
+    #if os(macOS)
+    /// The live session's clipboard bridge (design/clipboard-and-file-transfer.md §5) — created
+    /// by `beginStreaming` when the per-host toggle is on and the host advertises
+    /// `HOST_CAP_CLIPBOARD`; stopped (off-main, drain joined) in `disconnect`.
+    private var clipboardSync: ClipboardSync?
+    #endif
+    /// Whether clipboard sync is live (host-acked `ClipState.enabled`) — drives the Stream menu
+    /// item's title and the settings footnote. Always false off-macOS.
+    @Published private(set) var clipboardEnabled = false
+    /// The host's last `ClipState.reason` (`CLIP_REASON_*`) — why an enable was refused
+    /// (backend unavailable / policy disabled / …); 0 = OK.
+    @Published private(set) var clipboardReason: UInt8 = 0
    #if os(tvOS)
    /// Siri Remote → host pointer while streaming (touch surface moves, press = left click,
    /// Play/Pause = right click) + the remote's deliberate exit (hold Back ≥ 1 s). See
@@ -148,6 +160,16 @@ final class SessionModel: ObservableObject {

    var isBusy: Bool { phase != .idle }

+    /// True while a streaming session is running in the background under the opt-in keep-alive
+    /// (audio plays, video dropped, timeout armed). Drives the Live Activity's stage/countdown (M3)
+    /// and is cleared on foreground or teardown. iOS/iPadOS only in practice.
+    @Published private(set) var isBackgrounded = false
+    /// When the backgrounded keep-alive will auto-disconnect (nil unless backgrounded) — drives the
+    /// Live Activity countdown. Set alongside `backgroundTimer`.
+    @Published private(set) var backgroundDeadline: Date?
+    /// Bounded auto-disconnect for a backgrounded keep-alive session. Fires on `.main`.
+    private var backgroundTimer: DispatchSourceTimer?
+
    /// `allowTofu` gates the trust-on-first-use prompt for an unpinned host: it is only true
    /// when the host EXPLICITLY advertised `pair=optional` (rule 3a). For any other unpinned host
    /// — `pair=required`, a manually-typed host, or a discovered host with no/unknown `pair`
@@ -239,6 +261,18 @@ final class SessionModel: ObservableObject {
            // from these + the soft `preferredCodec`; `resolvedCodec` reflects what it chose.
            var videoCodecs = PunktfunkConnection.codecH264 | PunktfunkConnection.codecHEVC
            if AV1.hardwareDecodeSupported { videoCodecs |= PunktfunkConnection.codecAV1 }
+            // PyroWave (wired LAN) is a pure opt-in: picking it in the codec setting both
+            // advertises the bit and prefers it — the host never auto-selects it, and the
+            // picker only offers it when the Metal decode probe passed (simdgroup floor ≈ A13;
+            // every M-series Mac and the ATV 4K gen 3 pass). The codec is 8-bit 4:2:0 SDR
+            // BT.709 by contract, so the opt-in also drops the HDR/10-bit/4:4:4 caps for this
+            // session — HDR sessions stay HEVC/AV1 (plan §4.7).
+            if preferredCodec == PunktfunkConnection.codecPyroWave, MetalWaveletDecoder.supported {
+                videoCodecs |= PunktfunkConnection.codecPyroWave
+                videoCaps &= ~(PunktfunkConnection.videoCap10Bit
+                    | PunktfunkConnection.videoCapHDR
+                    | PunktfunkConnection.videoCap444)
+            }
            let result = Result { try PunktfunkConnection(
                host: host.address, port: host.port,
                width: width, height: height, refreshHz: hz,
@@ -284,10 +318,15 @@ final class SessionModel: ObservableObject {
                        self.errorMessage = "\(host.displayName) is not paired yet. "
                            + "Pair with its PIN before streaming."
                    }
-                case .failure:
+                case .failure(let error):
                    self.phase = .idle
                    self.activeHost = nil
-                    if let onUnreachable, !requestAccess {
+                    if case PunktfunkClientError.rejected(let rejection) = error {
+                        // The host answered and stated its reason (declined / approval timed
+                        // out / busy / versions differ) — show that, and never wake-retry a
+                        // host that is demonstrably awake.
+                        self.errorMessage = "\(host.displayName): \(rejection.userMessage)"
+                    } else if let onUnreachable, !requestAccess {
                        // The caller owns recovery (wake-and-retry) — no error alert here; its
                        // own overlay explains what's happening.
                        onUnreachable()
@@ -315,6 +354,48 @@ final class SessionModel: ObservableObject {
        }
    }

+    // MARK: - Background keep-alive (opt-in, iOS)
+
+    /// Enter the backgrounded keep-alive state: keep audio playing, DROP video decode (no GPU work
+    /// off-screen), mute the mic (privacy), and arm a bounded auto-disconnect. The caller
+    /// (ContentView's scenePhase driver) gates this on the setting + `.streaming`; a no-op otherwise.
+    /// The video-drop seam is read by both pumps every iteration (`connection.isVideoDropped`).
+    func enterBackground(timeoutMinutes: Int) {
+        guard phase == .streaming, let conn = connection, !isBackgrounded else { return }
+        isBackgrounded = true
+        conn.setVideoDropped(true)
+        audio?.setMicMuted(true)
+        // Non-deliberate on fire (keep the host linger) so a user who returns late reconnects fast,
+        // exactly like today's network-drop path. min 1 minute guards a nonsense setting.
+        let minutes = max(1, timeoutMinutes)
+        backgroundDeadline = Date().addingTimeInterval(TimeInterval(minutes * 60))
+        let timer = DispatchSource.makeTimerSource(queue: .main)
+        timer.schedule(deadline: .now() + .seconds(minutes * 60))
+        timer.setEventHandler { [weak self] in
+            // The timer fires on `.main`, so the actor's executor is the main thread here.
+            MainActor.assumeIsolated { self?.disconnect(deliberate: false) }
+        }
+        backgroundTimer?.cancel()
+        backgroundTimer = timer
+        timer.resume()
+    }
+
+    /// Return to foreground: cancel the timeout, resume mic + video, and force a clean re-anchor —
+    /// request a fresh IDR (infinite GOP: it won't come on its own) and let the pump's freeze gate
+    /// withhold the concealed frames until it lands (it auto-arms on the resumed frame-index gap).
+    func exitBackground() {
+        guard isBackgrounded else { return }
+        isBackgrounded = false
+        backgroundDeadline = nil
+        backgroundTimer?.cancel()
+        backgroundTimer = nil
+        audio?.setMicMuted(false)
+        if let conn = connection {
+            conn.setVideoDropped(false)
+            conn.requestKeyframe()
+        }
+    }
+
    /// The user confirmed the fingerprint: returns it for pinning and enters streaming.
    func confirmTrust() -> Data? {
        guard case .awaitingTrust(let fingerprint) = phase else { return nil }
@@ -332,6 +413,11 @@ final class SessionModel: ObservableObject {
    func disconnect(deliberate: Bool = true) {
        statsTimer?.invalidate()
        statsTimer = nil
+        // Drop any armed background keep-alive (incl. the timeout that just fired us).
+        backgroundTimer?.cancel()
+        backgroundTimer = nil
+        isBackgrounded = false
+        backgroundDeadline = nil
        let audio = self.audio
        self.audio = nil
        // Gamepad capture is main-actor (releases held buttons on the wire while the
@@ -344,6 +430,12 @@ final class SessionModel: ObservableObject {
        #endif
        let feedback = gamepadFeedback
        gamepadFeedback = nil
+        #if os(macOS)
+        let clipboard = clipboardSync
+        clipboardSync = nil
+        #endif
+        clipboardEnabled = false
+        clipboardReason = 0
        if let conn = connection {
            // Drain-thread teardown waits the pullers out and close() waits out in-flight
            // polls + joins the Rust worker threads — keep all of it off the main actor,
@@ -351,6 +443,9 @@ final class SessionModel: ObservableObject {
            Task.detached {
                audio?.stop()
                feedback?.stop()
+                #if os(macOS)
+                clipboard?.stop() // disables sync on the wire while the connection is still up
+                #endif
                // Deliberate user quit → tell the host to skip the keep-alive linger (must precede close).
                if deliberate { conn.disconnectQuit() }
                conn.close()
@@ -359,6 +454,9 @@ final class SessionModel: ObservableObject {
            Task.detached {
                audio?.stop()
                feedback?.stop()
+                #if os(macOS)
+                clipboard?.stop()
+                #endif
            }
        }
        connection = nil
@@ -433,6 +531,14 @@ final class SessionModel: ObservableObject {
        let feedback = GamepadFeedback(connection: conn, manager: .shared)
        feedback.start()
        gamepadFeedback = feedback
+        #if os(macOS)
+        // Shared clipboard: opt-in per host AND host-advertised (older hosts / operator-disabled
+        // hosts never see a ClipControl). Same trust gate as audio — nothing is announced
+        // during the trust prompt.
+        if activeHost?.clipboardSync == true, conn.hostSupportsClipboard {
+            startClipboardSync(conn)
+        }
+        #endif
        #if os(tvOS)
        let pointer = SiriRemotePointer(connection: conn)
        pointer.onDisconnectRequest = { [weak self] in self?.disconnect() }
@@ -441,6 +547,40 @@ final class SessionModel: ObservableObject {
        #endif
    }

+    #if os(macOS)
+    /// Create + start the session's clipboard bridge and route its host acks into the published
+    /// UI state. `ClipboardSync.start()` sends the enable; the host's `.state` answer flips
+    /// `clipboardEnabled` (or leaves it false with a `clipboardReason` the UI can explain).
+    private func startClipboardSync(_ conn: PunktfunkConnection) {
+        let sync = ClipboardSync(connection: conn)
+        sync.onState = { [weak self] enabled, _, reason in
+            Task { @MainActor in
+                self?.clipboardEnabled = enabled
+                self?.clipboardReason = reason
+            }
+        }
+        sync.start()
+        clipboardSync = sync
+    }
+    #endif
+
+    /// Flip clipboard sync mid-session (the Stream menu). Off → on requires the host cap; on →
+    /// off tears the bridge down (off-main — the drain join must not block the main actor) and
+    /// tells the host, which drops any selection we own there. No-op off-macOS or while idle.
+    func toggleClipboardSync() {
+        #if os(macOS)
+        guard let conn = connection, phase == .streaming else { return }
+        if let sync = clipboardSync {
+            clipboardSync = nil
+            clipboardEnabled = false
+            clipboardReason = 0
+            Task.detached { sync.stop() }
+        } else if conn.hostSupportsClipboard {
+            startClipboardSync(conn)
+        }
+        #endif
+    }
+
    private func startStatsTimer() {
        lastFramesDropped = 0 // a fresh connection's cumulative drop counter starts at 0
        latencySplit.reset() // no stale receipts/samples from a previous session
@@ -21,6 +21,12 @@ import SwiftUI
 /// `.focusedSceneValue` so the Scene-level commands can drive it.
 struct SessionFocus {
    var isStreaming: Bool
+    /// The connected host advertises `HOST_CAP_CLIPBOARD` (gates the Share Clipboard item —
+    /// macOS-only UI, but the fact is platform-neutral).
+    var clipboardAvailable: Bool
+    /// Clipboard sync is live (host-acked) — drives the item's Stop/Share title.
+    var clipboardOn: Bool
+    var toggleClipboard: () -> Void
    var disconnect: () -> Void
 }

@@ -58,6 +64,15 @@ struct StreamCommands: Commands {
            }
            .keyboardShortcut("q", modifiers: [.control, .option, .shift])
            .disabled(session?.isStreaming != true)
+            #if os(macOS)
+            // Mid-session clipboard flip (design/clipboard-and-file-transfer.md §5.3). Greyed
+            // when the host doesn't advertise the cap (older host / operator policy off).
+            Button(session?.clipboardOn == true ? "Stop Sharing Clipboard" : "Share Clipboard") {
+                session?.toggleClipboard()
+            }
+            .keyboardShortcut("c", modifiers: [.control, .option, .shift])
+            .disabled(session?.isStreaming != true || session?.clipboardAvailable != true)
+            #endif
            Divider()
            Button("Disconnect") { session?.disconnect() }
                .keyboardShortcut("d", modifiers: [.control, .option, .shift])
@@ -79,6 +79,13 @@ enum SettingsOptions {
        if AV1.hardwareDecodeSupported {
            options.insert(("AV1", "av1"), at: 2)
        }
+        // PyroWave is the opt-in wired-LAN low-latency codec (100–400 Mbps all-intra wavelet,
+        // 8-bit SDR): selecting it advertises + prefers it for the session. Offered only when
+        // the Metal decode probe passes (same gate SessionModel advertises by) — elsewhere the
+        // host could never emit it.
+        if MetalWaveletDecoder.supported {
+            options.append(("PyroWave (wired LAN)", "pyrowave"))
+        }
        return options
    }()

@@ -440,6 +440,34 @@ extension SettingsView {
        }
    }

+    /// iOS/iPadOS only: keep a backgrounded session alive (audio background mode). Empty elsewhere
+    /// (tvOS backgrounding semantics differ; macOS isn't gated by the mode) so the shared `.general`
+    /// detail can reference it unconditionally.
+    @ViewBuilder var keepAliveSection: some View {
+        #if os(iOS)
+        Section {
+            Toggle("Keep streaming in background", isOn: $backgroundKeepAlive)
+            if backgroundKeepAlive {
+                Picker("Disconnect after", selection: $backgroundTimeoutMinutes) {
+                    Text("1 minute").tag(1)
+                    Text("5 minutes").tag(5)
+                    Text("10 minutes").tag(10)
+                    Text("30 minutes").tag(30)
+                }
+            }
+        } header: {
+            Text("Background")
+        } footer: {
+            Text("Off by default: backgrounding the app freezes the session. When on, audio keeps "
+                + "playing and the connection stays live (video is dropped to save power) after you "
+                + "switch away — and the session auto-disconnects after the time above so it can't "
+                + "run down your battery. Returning to the app resumes video instantly.")
+                .font(.geist(12, relativeTo: .caption))
+                .foregroundStyle(.secondary)
+        }
+        #endif
+    }
+
    @ViewBuilder var experimentalSection: some View {
        Section {
            Toggle("Show game library", isOn: $libraryEnabled)
@@ -49,6 +49,8 @@ struct SettingsView: View {
    @ObservedObject var gamepads = GamepadManager.shared
    @AppStorage(DefaultsKey.gamepadUIEnabled) var gamepadUIEnabled = true
    @AppStorage(DefaultsKey.autoWake) var autoWakeEnabled = true
+    @AppStorage(DefaultsKey.backgroundKeepAlive) var backgroundKeepAlive = false
+    @AppStorage(DefaultsKey.backgroundTimeoutMinutes) var backgroundTimeoutMinutes = 10
    #if DEBUG && !os(tvOS)
    @State var showControllerTest = false
    #endif
@@ -242,6 +244,7 @@ struct SettingsView: View {
                pointerSection
                compositorSection
                wakeSection
+                keepAliveSection // iOS-only content; empty on tvOS
            }
            .formStyle(.grouped)
            .navigationTitle("General")
@@ -11,32 +11,13 @@
 import Foundation
 import PunktfunkKit
 import SwiftUI
+#if canImport(WidgetKit)
+import WidgetKit
+#endif

-struct StoredHost: Identifiable, Codable, Hashable {
-    var id = UUID()
-    var name: String
-    var address: String
-    var port: UInt16 = 9777
-    /// SHA-256 of the host's certificate, set after the user explicitly trusted it.
-    var pinnedSHA256: Data?
-    /// Last time a streaming session actually started (nil until the first one).
-    var lastConnected: Date?
-    /// Management-API port for the library browser (distinct from the data-plane `port`). Optional
-    /// (NOT a defaulted non-optional) so older saved hosts — whose JSON lacks this key — still
-    /// decode: synthesized Decodable ignores property defaults but treats a missing Optional as
-    /// nil. Resolve via `effectiveMgmtPort`. (Auth is mTLS by the pinned identity — no token.)
-    var mgmtPort: UInt16?
-    /// Wake-on-LAN MAC address(es) of the host's wake-capable NIC(s), each `aa:bb:cc:dd:ee:ff`.
-    /// Learned from the host's mDNS `mac` TXT record while it's awake and persisted here, so the
-    /// client can send a magic packet to wake the host later (when it's asleep and no longer
-    /// advertising). Optional (same forward-compat reason as `mgmtPort`); nil until first learned.
-    var macAddresses: [String]?
-
-    var displayName: String { name.isEmpty ? address : name }
-    var effectiveMgmtPort: UInt16 { mgmtPort ?? punktfunkDefaultMgmtPort }
-    /// Wake-capable, in a form the wake helper accepts (empty when none learned yet).
-    var wakeMacs: [String] { macAddresses ?? [] }
-}
+// `StoredHost` (the model + its JSON codec) now lives in PunktfunkShared so the widget extension
+// can read the same store; PunktfunkKit re-exports it. The discovery-join helpers below stay here
+// because they reference PunktfunkKit's `DiscoveredHost`/`HostDiscovery`.

 extension StoredHost {
    /// True when a live mDNS advert (`DiscoveredHost`) describes THIS saved host — drives the
@@ -86,8 +67,14 @@ final class HostStore: ObservableObject {
    /// never advertises still reads Online. Not persisted (it's live reachability, not config).
    @Published var probedOnline: Set<StoredHost.ID> = []

+    /// The App-Group suite — shared with the Widget/Live-Activity extension so a launcher widget
+    /// sees the same saved hosts. Falls back to `.standard` in an un-entitled process (see
+    /// `AppGroup.defaults`).
+    private let defaults = AppGroup.defaults
+
    init() {
-        if let data = UserDefaults.standard.data(forKey: Self.key),
+        Self.migrateToAppGroupIfNeeded()
+        if let data = defaults.data(forKey: Self.key),
           let decoded = try? JSONDecoder().decode([StoredHost].self, from: data) {
            hosts = decoded
        } else {
@@ -95,6 +82,20 @@ final class HostStore: ObservableObject {
        }
    }

+    /// One-time move of the saved-host JSON from `UserDefaults.standard` (where every build before
+    /// the App Group wrote it) into the shared suite. Idempotent: only fires when the suite has no
+    /// hosts yet but standard does. The old value is LEFT in place — during a staged TestFlight
+    /// rollout an older build still reads `.standard`, so tombstoning it now would hide hosts from
+    /// the not-yet-updated app. Remove the standard copy a release later.
+    private static func migrateToAppGroupIfNeeded() {
+        let suite = AppGroup.defaults
+        let standard = UserDefaults.standard
+        guard suite !== standard else { return } // un-entitled fallback: nothing to migrate
+        guard suite.data(forKey: key) == nil,
+              let legacy = standard.data(forKey: key) else { return }
+        suite.set(legacy, forKey: key)
+    }
+
    func add(_ host: StoredHost) {
        hosts.append(host)
    }
@@ -112,7 +113,7 @@ final class HostStore: ObservableObject {

    func markConnected(_ hostID: UUID) {
        guard let i = hosts.firstIndex(where: { $0.id == hostID }) else { return }
-        hosts[i].lastConnected = Date()
+        hosts[i].lastConnected = Date() // didSet → persist() writes the shared suite + reloads widget
    }

    /// One reachability sweep, driving `probedOnline`: probe every saved host NOT currently
@@ -158,7 +159,17 @@ final class HostStore: ObservableObject {

    private func persist() {
        if let data = try? JSONEncoder().encode(hosts) {
-            UserDefaults.standard.set(data, forKey: Self.key)
+            defaults.set(data, forKey: Self.key)
        }
+        reloadHostsWidget() // the widget reads this store; any change refreshes its timeline
+    }
+
+    /// Ask WidgetKit to rebuild the hosts widget's timeline after any store change (add/remove/pin/
+    /// last-connected). iOS-only and a no-op where WidgetKit is absent; the widget uses
+    /// `.never`-refresh entries and relies on this push.
+    private func reloadHostsWidget() {
+        #if canImport(WidgetKit) && os(iOS)
+        WidgetCenter.shared.reloadTimelines(ofKind: "PunktfunkHosts")
+        #endif
    }
 }
@@ -212,14 +212,18 @@ struct PairSheet: View {
                case .failure(PunktfunkClientError.wrongPIN):
                    errorText = "Wrong PIN — check the host's web console (port 3000) "
                        + "and try again."
+                case .failure(PunktfunkClientError.rejected(let rejection)):
+                    // The host answered and said why (not armed / rate-limited / armed for
+                    // another device) — show that instead of the guessing-game fallback.
+                    errorText = rejection.userMessage
                case .failure(is ClientIdentityStore.IdentityError):
                    errorText = "Can't store this Mac's identity in the Keychain, so the "
                        + "pairing would not survive a relaunch. Unlock the login "
                        + "keychain and try again."
                case .failure:
-                    errorText = "Pairing failed. Is the host reachable, pairing armed "
-                        + "(web console → Pairing), and not mid-session? Retries are "
-                        + "rate-limited to one per 2 seconds."
+                    errorText = "Pairing failed — the host didn't answer. Is it running, "
+                        + "and is this device on the same network (no VPN, no guest-Wi-Fi "
+                        + "isolation)?"
                }
            }
        }
@@ -180,6 +180,23 @@ public final class SessionAudio {
        }
    }

+    /// Background keep-alive: silence the mic uplink while backgrounded (privacy — no room audio
+    /// leaves the device) and restore it on return. Pauses/resumes the capture engine; a no-op when
+    /// there's no uplink (playback-only / tvOS / mic disabled). The audio SESSION stays active for
+    /// background playback, so iOS may keep showing the recording indicator until a full reconfigure
+    /// — this stops the actual capture, which is the privacy-relevant part. Main thread.
+    public func setMicMuted(_ muted: Bool) {
+        stateLock.lock()
+        let capture = captureEngine
+        stateLock.unlock()
+        guard let capture else { return }
+        if muted {
+            capture.pause()
+        } else if !flag.isStopped {
+            try? capture.start()
+        }
+    }
+
    // MARK: - Playback (host → speaker)

    private func startPlayback(speakerUID: String) {
@@ -0,0 +1,361 @@
+// Shared clipboard, macOS client half (design/clipboard-and-file-transfer.md §5.2).
+//
+// Bridges NSPasteboard.general to the session's QUIC clipboard plane, both directions lazy:
+//
+// * **Local copy → host**: a changeCount poll announces the *format list* (`clipOffer`); the
+//   bytes cross only when a host app pastes (a `.fetchRequest` event, answered from the live
+//   pasteboard by `clipServe`).
+// * **Host copy → local**: a `.remoteOffer` writes one NSPasteboardItem whose
+//   NSPasteboardItemDataProvider fires only when a Mac app actually pastes — the provider then
+//   blocks (on its provider thread, never main) on a `clipFetch` round-trip.
+//
+// Password-manager respect: pasteboards marked `org.nspasteboard.ConcealedType` or
+// `org.nspasteboard.TransientType` are never announced, never fetchable. Echo suppression: the
+// changeCount of every write WE make is recorded so the announce poll skips it (§3.4).
+//
+// Phase 1 formats only (text / RTF / HTML / PNG). Files (NSFilePromiseProvider) ride Phase 2.
+#if os(macOS)
+import AppKit
+import Foundation
+
+/// One live session's clipboard bridge. Created by the session model when streaming begins on a
+/// host that advertises `HOST_CAP_CLIPBOARD` and whose per-host toggle is on; `stop()` before the
+/// connection closes. All pasteboard traffic runs on one dedicated drain thread plus the
+/// AppKit-owned provider threads (paste fulfillment).
+public final class ClipboardSync: NSObject {
+    /// Wire MIME ↔ NSPasteboard type for the Phase-1 vocabulary (§3.5), in announce order.
+    private static let wireToPasteboard: [(wire: String, type: NSPasteboard.PasteboardType)] = [
+        ("text/plain;charset=utf-8", .string),
+        ("text/rtf", .rtf),
+        ("text/html", .html),
+        ("image/png", .png),
+    ]
+    /// Pasteboard marker types that must never cross the wire (password managers mark secrets
+    /// with these — see nspasteboard.org).
+    private static let concealed = NSPasteboard.PasteboardType("org.nspasteboard.ConcealedType")
+    private static let transient = NSPasteboard.PasteboardType("org.nspasteboard.TransientType")
+
+    /// How long a blocked paste waits for the host's bytes before providing nothing (§5.2).
+    private static let fetchTimeout: TimeInterval = 10
+    /// Serve chunk size for host-side pastes of our data (bounds the per-call ABI copy).
+    private static let serveChunk = 4 << 20
+
+    private let connection: PunktfunkConnection
+    /// `CLIP_FLAG_*` sent with the enable (`CLIP_FLAG_FILES` when the session permits files —
+    /// always 0 in Phase 1).
+    private let controlFlags: UInt8
+
+    /// Host `.state` updates, delivered on the main queue — drives the toggle/footnote UI.
+    public var onState: ((_ enabled: Bool, _ policy: UInt8, _ reason: UInt8) -> Void)?
+
+    // Drain-thread state (touched only on the drain thread once started).
+    private var offerSeq: UInt32 = 0
+    private var lastSeenChangeCount = 0
+    /// The changeCount of the last pasteboard write WE made (echo suppression + "do we still
+    /// own the pasteboard" on teardown/clear).
+    private var ownedChangeCount = -1
+    /// The host offer currently installed on the local pasteboard (nil = none).
+    private var installedRemoteSeq: UInt32?
+
+    /// Outbound fetches a blocked paste is waiting on. Guarded by `fetchLock` — appended by the
+    /// drain thread (`.data` events), consumed by AppKit's provider threads.
+    private struct PendingFetch {
+        var buffer = Data()
+        let done = DispatchSemaphore(value: 0)
+        var failed = false
+    }
+    private let fetchLock = NSLock()
+    private var pendingFetches: [UInt32: PendingFetch] = [:]
+
+    private final class StopFlag: @unchecked Sendable {
+        private let lock = NSLock()
+        private var stopped = false
+        func stop() {
+            lock.lock()
+            stopped = true
+            lock.unlock()
+        }
+        var isStopped: Bool {
+            lock.lock()
+            defer { lock.unlock() }
+            return stopped
+        }
+    }
+    private let flag = StopFlag()
+    private let drainDone = DispatchSemaphore(value: 0)
+    private var started = false
+    /// Set by the app-activation observer, cleared by the drain loop: the user may have copied
+    /// elsewhere and is coming back to paste — announce immediately instead of waiting out the
+    /// poll interval.
+    private final class OneShot: @unchecked Sendable {
+        private let lock = NSLock()
+        private var raised = false
+        func raise() {
+            lock.lock()
+            raised = true
+            lock.unlock()
+        }
+        func takeIfRaised() -> Bool {
+            lock.lock()
+            defer { lock.unlock() }
+            let was = raised
+            raised = false
+            return was
+        }
+    }
+    private let checkNow = OneShot()
+    private var activationObserver: NSObjectProtocol?
+
+    public init(connection: PunktfunkConnection, allowFiles: Bool = false) {
+        self.connection = connection
+        self.controlFlags = 0 // CLIP_FLAG_FILES rides Phase 2
+        _ = allowFiles
+        super.init()
+    }
+
+    deinit { flag.stop() }
+
+    /// Enable sync with the host and start the drain thread. The host answers the enable with a
+    /// `.state` event (surfaced via `onState`) — `BACKEND_UNAVAILABLE` et al. arrive there.
+    public func start() {
+        guard !started else { return }
+        started = true
+        connection.clipControl(enabled: true, flags: controlFlags)
+        // Baseline: whatever is on the pasteboard when sync starts is announced immediately —
+        // the "copy first, then connect and paste" flow must work.
+        lastSeenChangeCount = -1
+        activationObserver = NotificationCenter.default.addObserver(
+            forName: NSApplication.didBecomeActiveNotification, object: nil, queue: nil
+        ) { [checkNow] _ in checkNow.raise() }
+        let connection = self.connection
+        let flag = self.flag
+        let thread = Thread { [weak self] in
+            var lastAnnounceCheck = Date.distantPast
+            while !flag.isStopped {
+                // Drain events (bounded burst so a chatty host can't starve the announce poll).
+                var drained = 0
+                while drained < 32, !flag.isStopped {
+                    let ev: PunktfunkConnection.ClipEvent?
+                    do {
+                        ev = try connection.nextClipboard(timeoutMs: drained == 0 ? 200 : 0)
+                    } catch {
+                        flag.stop() // session closed
+                        break
+                    }
+                    guard let ev else { break }
+                    drained += 1
+                    self?.handle(ev)
+                }
+                // Announce poll: every 500 ms, or immediately after app activation (§5.2).
+                let now = Date()
+                if now.timeIntervalSince(lastAnnounceCheck) >= 0.5
+                    || self?.checkNow.takeIfRaised() == true
+                {
+                    lastAnnounceCheck = now
+                    self?.announceIfChanged()
+                }
+            }
+            self?.drainDone.signal()
+        }
+        thread.name = "punktfunk-clipboard"
+        thread.qualityOfService = .utility
+        thread.start()
+    }
+
+    /// Disable sync and join the drain thread. Called off-main before `connection.close()`
+    /// (the same discipline as the audio/feedback drains). If the local pasteboard still holds
+    /// our remote-offer items, they are cleared — their providers die with us.
+    public func stop() {
+        guard started else { return }
+        started = false
+        if let obs = activationObserver {
+            NotificationCenter.default.removeObserver(obs)
+            activationObserver = nil
+        }
+        connection.clipControl(enabled: false, flags: 0)
+        flag.stop()
+        drainDone.wait()
+        // Fail every paste still blocked on us so no provider thread waits out its timeout.
+        fetchLock.lock()
+        for (_, pending) in pendingFetches {
+            pending.done.signal()
+        }
+        pendingFetches.removeAll()
+        fetchLock.unlock()
+        let pb = NSPasteboard.general
+        if installedRemoteSeq != nil, pb.changeCount == ownedChangeCount {
+            pb.clearContents()
+        }
+    }
+
+    // MARK: - Local copy → host (announce)
+
+    /// Announce the local pasteboard's format list when it changed (skipping our own writes and
+    /// concealed/transient pasteboards). Runs on the drain thread.
+    private func announceIfChanged() {
+        let pb = NSPasteboard.general
+        let count = pb.changeCount
+        guard count != lastSeenChangeCount else { return }
+        lastSeenChangeCount = count
+        if count == ownedChangeCount { return } // our own write (a remote offer) — never echo
+        installedRemoteSeq = nil // a local copy replaced the host's offer
+        let types = pb.types ?? []
+        if types.contains(Self.concealed) || types.contains(Self.transient) { return }
+        offerSeq &+= 1
+        let kinds = Self.wireToPasteboard
+            .filter { types.contains($0.type) }
+            .map { PunktfunkConnection.ClipKind(mime: $0.wire) }
+        // Empty = the pasteboard holds nothing we sync (or was cleared) — clears the host side.
+        connection.clipOffer(seq: offerSeq, kinds: kinds)
+    }
+
+    // MARK: - Event handling (drain thread)
+
+    private func handle(_ ev: PunktfunkConnection.ClipEvent) {
+        switch ev {
+        case let .state(enabled, policy, reason):
+            if let onState {
+                DispatchQueue.main.async { onState(enabled, policy, reason) }
+            }
+        case let .remoteOffer(seq, kinds):
+            installRemoteOffer(seq: seq, kinds: kinds)
+        case let .fetchRequest(reqId, seq, _, mime):
+            serveFetch(reqId: reqId, seq: seq, mime: mime)
+        case let .data(xferId, chunk, last):
+            fetchLock.lock()
+            if var pending = pendingFetches[xferId] {
+                pending.buffer.append(chunk)
+                pendingFetches[xferId] = pending
+                if last {
+                    pendingFetches[xferId]?.done.signal()
+                }
+            }
+            fetchLock.unlock()
+        case let .cancelled(id), let .error(id, _):
+            fetchLock.lock()
+            if var pending = pendingFetches[id] {
+                pending.failed = true
+                pendingFetches[id] = pending
+                pending.done.signal()
+            }
+            fetchLock.unlock()
+        }
+    }
+
+    // MARK: - Host copy → local (lazy install + blocked-paste fetch)
+
+    /// Write one NSPasteboardItem advertising the host's formats, each backed by a lazy data
+    /// provider — bytes cross only when a Mac app pastes. Empty `kinds` = the host cleared its
+    /// clipboard: drop our item if it's still current.
+    private func installRemoteOffer(seq: UInt32, kinds: [PunktfunkConnection.ClipKind]) {
+        let pb = NSPasteboard.general
+        let types = kinds.compactMap { kind in
+            Self.wireToPasteboard.first(where: { $0.wire == kind.mime })?.type
+        }
+        guard !types.isEmpty else {
+            if installedRemoteSeq != nil, pb.changeCount == ownedChangeCount {
+                pb.clearContents()
+                ownedChangeCount = pb.changeCount
+                lastSeenChangeCount = pb.changeCount
+            }
+            installedRemoteSeq = nil
+            return
+        }
+        let item = NSPasteboardItem()
+        item.setDataProvider(RemoteOfferProvider(sync: self, seq: seq), forTypes: types)
+        pb.clearContents()
+        pb.writeObjects([item])
+        installedRemoteSeq = seq
+        ownedChangeCount = pb.changeCount
+        lastSeenChangeCount = pb.changeCount
+    }
+
+    /// Blocked-paste fulfillment: fetch one wire format of host offer `seq` and wait (provider
+    /// thread) for the drain thread to assemble the chunks. Nil on timeout/cancel/error — the
+    /// paste then provides nothing rather than hanging (§3.4).
+    ///
+    /// `fetchLock` is held ACROSS the `clipFetch` so the pending entry exists before the drain
+    /// thread can process the first `.data` event (its `handle` takes `fetchLock` after
+    /// releasing the connection's clipboard lock — no cycle).
+    fileprivate func fetchBlocking(seq: UInt32, wireMime: String) -> Data? {
+        fetchLock.lock()
+        guard let xferId = connection.clipFetch(seq: seq, mime: wireMime) else {
+            fetchLock.unlock()
+            return nil
+        }
+        pendingFetches[xferId] = PendingFetch()
+        let done = pendingFetches[xferId]!.done
+        fetchLock.unlock()
+        let outcome = done.wait(timeout: .now() + Self.fetchTimeout)
+        fetchLock.lock()
+        let pending = pendingFetches.removeValue(forKey: xferId)
+        fetchLock.unlock()
+        if outcome == .timedOut {
+            connection.clipCancel(id: xferId)
+            return nil
+        }
+        guard let pending, !pending.failed else { return nil }
+        return pending.buffer
+    }
+
+    // MARK: - Host paste of our data (serve)
+
+    /// Answer a host paste of our offered data from the live pasteboard. A stale `seq` (the
+    /// local clipboard changed since that announce) is cancelled — never serve mismatched bytes.
+    private func serveFetch(reqId: UInt32, seq: UInt32, mime: String) {
+        let pb = NSPasteboard.general
+        guard seq == offerSeq, pb.changeCount == lastSeenChangeCount,
+            let type = Self.wireToPasteboard.first(where: { $0.wire == mime })?.type,
+            let data = pb.data(forType: type)
+        else {
+            connection.clipCancel(id: reqId)
+            return
+        }
+        var offset = 0
+        while offset < data.count {
+            let end = min(offset + Self.serveChunk, data.count)
+            connection.clipServe(
+                reqId: reqId, data: data.subdata(in: offset..<end), last: end == data.count)
+            offset = end
+        }
+        if data.isEmpty {
+            connection.clipServe(reqId: reqId, data: Data(), last: true)
+        }
+    }
+}
+
+/// The lazy paste hook: AppKit calls `provideDataForType` only when a Mac app actually pastes;
+/// the fetch then blocks this provider thread (never main) until the host's bytes arrive or the
+/// timeout provides nothing. One provider per installed remote offer — a dead sync (weak) or a
+/// superseded offer provides nothing.
+private final class RemoteOfferProvider: NSObject, NSPasteboardItemDataProvider {
+    private weak var sync: ClipboardSync?
+    private let seq: UInt32
+
+    init(sync: ClipboardSync, seq: UInt32) {
+        self.sync = sync
+        self.seq = seq
+    }
+
+    func pasteboard(
+        _ pasteboard: NSPasteboard?, item: NSPasteboardItem,
+        provideDataForType type: NSPasteboard.PasteboardType
+    ) {
+        guard let sync,
+            let wire = wireMime(for: type),
+            let data = sync.fetchBlocking(seq: seq, wireMime: wire)
+        else { return }
+        item.setData(data, forType: type)
+    }
+
+    private func wireMime(for type: NSPasteboard.PasteboardType) -> String? {
+        switch type {
+        case .string: return "text/plain;charset=utf-8"
+        case .rtf: return "text/rtf"
+        case .html: return "text/html"
+        case .png: return "image/png"
+        default: return nil
+        }
+    }
+}
+#endif
@@ -54,6 +54,12 @@ public func pair(
    switch rc {
    case PUNKTFUNK_STATUS_OK.rawValue: return Data(observed)
    case PUNKTFUNK_STATUS_CRYPTO.rawValue: throw PunktfunkClientError.wrongPIN
-    default: throw PunktfunkClientError.status(rc)
+    default:
+        // A typed host rejection (pairing not armed / rate-limited / armed for another
+        // device) carries its own reason — never report it as a bad PIN or dead network.
+        if let rejection = HostRejection(status: rc) {
+            throw PunktfunkClientError.rejected(rejection)
+        }
+        throw PunktfunkClientError.status(rc)
    }
 }
@@ -11,6 +11,9 @@
 // LaunchSpec schema in `crates/punktfunk-host/src/library.rs`.

 import Foundation
+// `punktfunkDefaultMgmtPort` (and StoredHost/DefaultsKey) now live in PunktfunkShared so the
+// dependency-free widget extension can share them; PunktfunkKit re-exports the module.
+import PunktfunkShared

 /// Cover art URLs (the public Steam CDN for Steam titles, user-supplied for custom entries).
 public struct Artwork: Codable, Hashable, Sendable {
@@ -64,10 +67,6 @@ public enum LibraryError: LocalizedError {
    }
 }

-/// The management API's default port — adjacent to the GameStream block; matches
-/// `mgmt::DEFAULT_PORT` on the host.
-public let punktfunkDefaultMgmtPort: UInt16 = 47990
-
 /// Stateless fetcher for a host's library.
 public enum LibraryClient {
    /// `GET https://<address>:<port>/api/v1/library`, authenticated by **mTLS**: the client
@@ -59,6 +59,68 @@ public enum PunktfunkClientError: Error {
    case wrongPIN
    case closed
    case status(Int32)
+    /// The host deliberately turned the attempt away and said why (its typed QUIC
+    /// application close) — distinct from `.connectFailed` (unreachable/timeout) so the UI
+    /// can show the stated reason instead of blaming the network.
+    case rejected(HostRejection)
+}
+
+/// Why a host turned a connect/pair attempt away — decoded from the
+/// `PUNKTFUNK_STATUS_REJECTED_*` block. Lets the UI say "approve the request on the host"
+/// or "pairing isn't armed" instead of a generic "could not connect".
+public enum HostRejection: Sendable {
+    case pairingNotArmed
+    case pairingBoundToOtherDevice
+    case pairingRateLimited
+    case identityRequired
+    case denied
+    case approvalTimeout
+    case superseded
+    case wireVersionMismatch
+    case busy
+
+    init?(status: Int32) {
+        switch status {
+        case PUNKTFUNK_STATUS_REJECTED_NOT_ARMED.rawValue: self = .pairingNotArmed
+        case PUNKTFUNK_STATUS_REJECTED_BOUND_OTHER.rawValue: self = .pairingBoundToOtherDevice
+        case PUNKTFUNK_STATUS_REJECTED_RATE_LIMITED.rawValue: self = .pairingRateLimited
+        case PUNKTFUNK_STATUS_REJECTED_IDENTITY_REQUIRED.rawValue: self = .identityRequired
+        case PUNKTFUNK_STATUS_REJECTED_DENIED.rawValue: self = .denied
+        case PUNKTFUNK_STATUS_REJECTED_APPROVAL_TIMEOUT.rawValue: self = .approvalTimeout
+        case PUNKTFUNK_STATUS_REJECTED_SUPERSEDED.rawValue: self = .superseded
+        case PUNKTFUNK_STATUS_REJECTED_WIRE_VERSION.rawValue: self = .wireVersionMismatch
+        case PUNKTFUNK_STATUS_REJECTED_BUSY.rawValue: self = .busy
+        default: return nil
+        }
+    }
+
+    /// User-facing sentence — wording shared with the desktop clients.
+    public var userMessage: String {
+        switch self {
+        case .pairingNotArmed:
+            return "Pairing isn't armed on the host — arm it on the host's Pairing page, "
+                + "then try again."
+        case .pairingBoundToOtherDevice:
+            return "The host's pairing window is armed for a different device — arm it "
+                + "for this one."
+        case .pairingRateLimited:
+            return "Too many pairing attempts — wait a couple of seconds and try again."
+        case .identityRequired:
+            return "The host requires pairing — pair this device (PIN or request access) first."
+        case .denied:
+            return "The host declined this device's request."
+        case .approvalTimeout:
+            return "Nobody approved the request on the host in time — approve this device "
+                + "in the host's console or web UI, then request access again."
+        case .superseded:
+            return "A newer request from this device replaced this one — approve the "
+                + "latest request on the host."
+        case .wireVersionMismatch:
+            return "Client and host versions don't match — update both to the same release."
+        case .busy:
+            return "The host is busy with another session."
+        }
+    }
 }

 /// `withCString` over an optional — nil maps to a NULL C pointer.
@@ -134,6 +196,10 @@ public final class PunktfunkConnection {
    /// Same role for the host-timing (0xCF) puller — its own plane in the core, drained
    /// non-blockingly by the app's 1 s stats tick (never contends with the blocking pullers).
    private let statsLock = NSLock()
+    /// Same role for the shared-clipboard drain thread (`nextClipboard` — its own plane in the
+    /// core). The clip *sends* (`clipControl`/`clipOffer`/`clipServe`…) share this lock too:
+    /// they're quick non-blocking enqueues, and a single lock keeps close() ordering simple.
+    private let clipboardLock = NSLock()

    /// Negotiated session mode (host-confirmed).
    public private(set) var width: UInt32 = 0
@@ -196,6 +262,11 @@ public final class PunktfunkConnection {
        /// Nintendo Switch Pro Controller (Linux UHID hid-nintendo hosts): correct Nintendo
        /// glyphs + positional layout on the host side.
        case switchPro = 8
+        /// New Steam Controller (2026, `28DE:1302`), passed through as-is on Linux hosts (raw
+        /// report mirroring; Steam Input is the consumer). Parity only on Apple — GameController
+        /// never surfaces the raw Valve device, so the client can't capture one; exists so the
+        /// resolved type round-trips and name parsing matches the host.
+        case steamController2 = 9

        /// Loose name parsing for env/dev hooks, mirroring the host's
        /// `GamepadPref::from_name`.
@@ -208,6 +279,8 @@ 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 "steamcontroller2", "steam-controller-2", "steamcon2", "sc2", "ibex":
+                self = .steamController2
            case "dualsenseedge", "dualsense-edge", "edge", "dsedge": self = .dualSenseEdge
            case "switchpro", "switch-pro", "switch", "procontroller", "pro-controller":
                self = .switchPro
@@ -268,9 +341,25 @@ public final class PunktfunkConnection {
    public private(set) var resolvedAudioChannels: UInt8 = 2

    /// The video codec the host resolved for this session (`Welcome.codec`, `PUNKTFUNK_CODEC_*`):
-    /// `2` = HEVC (default / older host), `1` = H.264, `4` = AV1. Build the decoder from THIS. The
-    /// resolved value honors the client's `preferredCodec` when the host could emit it.
+    /// `2` = HEVC (default / older host), `1` = H.264, `4` = AV1, `8` = PyroWave (only when this
+    /// client opted in). Build the decoder from THIS. The resolved value honors the client's
+    /// `preferredCodec` when the host could emit it.
    public private(set) var resolvedCodec: UInt8 = 2 // PUNKTFUNK_CODEC_HEVC
+
+    /// The session's negotiated wire shard payload (`Welcome.shard_payload`, bytes) — the
+    /// parse-window size for `USER_FLAG_CHUNK_ALIGNED` PyroWave AUs (plan §4.4). Other codecs
+    /// never need it.
+    public private(set) var shardPayload: UInt32 = 1408
+
+    /// The host capability bitfield (`Welcome.host_caps`): `PUNKTFUNK_HOST_CAP_GAMEPAD_STATE` /
+    /// `PUNKTFUNK_HOST_CAP_CLIPBOARD`. `0` for an older host that didn't say.
+    public private(set) var hostCaps: UInt8 = 0
+    /// Whether this host advertises the shared clipboard (`HOST_CAP_CLIPBOARD`) — the gate for
+    /// offering the clipboard toggle. Absent on an older host, or one whose operator policy
+    /// (`PUNKTFUNK_CLIPBOARD=off`) keeps the feature dark.
+    public var hostSupportsClipboard: Bool {
+        hostCaps & UInt8(PUNKTFUNK_HOST_CAP_CLIPBOARD) != 0
+    }
    /// The resolved codec as a `VideoCodec` (H.264 / HEVC / AV1) — drives the bitstream framing
    /// (Annex-B NAL parsing vs the AV1 OBU repack).
    public var videoCodec: VideoCodec { VideoCodec(wire: resolvedCodec) }
@@ -312,6 +401,10 @@ public final class PunktfunkConnection {
    ) throws {
        if let pin = pinSHA256, pin.count != 32 { throw PunktfunkClientError.invalidPin }
        var observed = [UInt8](repeating: 0, count: 32)
+        // Why a failed connect failed (PunktfunkStatus): lets a typed host rejection
+        // ("denied in the console", "approval timed out", "host busy") surface as
+        // `.rejected` instead of the undifferentiated `.connectFailed`.
+        var connectStatus: Int32 = 0
        // `videoCaps` advertises decode/present capability (PUNKTFUNK_VIDEO_CAP_10BIT | _HDR): the
        // host upgrades to a 10-bit / BT.2020 PQ stream only when set. 0 = 8-bit BT.709 SDR.
        // `launchID` (a host library id like "steam:570") asks the host to launch that title in
@@ -322,24 +415,29 @@ public final class PunktfunkConnection {
                    withOptionalCString(launchID) { launch in
                        if let pin = pinSHA256 {
                            return pin.withUnsafeBytes { p in
-                                punktfunk_connect_ex7(
+                                punktfunk_connect_ex8(
                                    cs, port, width, height, refreshHz, compositor.rawValue,
                                    gamepad.rawValue, bitrateKbps, videoCaps, audioChannels,
                                    videoCodecs, preferredCodec, launch,
                                    p.bindMemory(to: UInt8.self).baseAddress, &observed,
-                                    cert, key, timeoutMs)
+                                    cert, key, timeoutMs, &connectStatus)
                            }
                        }
-                        return punktfunk_connect_ex7(
+                        return punktfunk_connect_ex8(
                            cs, port, width, height, refreshHz, compositor.rawValue,
                            gamepad.rawValue, bitrateKbps, videoCaps, audioChannels,
                            videoCodecs, preferredCodec, launch,
-                            nil, &observed, cert, key, timeoutMs)
+                            nil, &observed, cert, key, timeoutMs, &connectStatus)
                    }
                }
            }
        }
-        guard handle != nil else { throw PunktfunkClientError.connectFailed }
+        guard handle != nil else {
+            if let rejection = HostRejection(status: connectStatus) {
+                throw PunktfunkClientError.rejected(rejection)
+            }
+            throw PunktfunkClientError.connectFailed
+        }
        hostFingerprint = Data(observed)
        var w: UInt32 = 0, h: UInt32 = 0, hz: UInt32 = 0
        _ = punktfunk_connection_mode(handle, &w, &h, &hz)
@@ -374,6 +472,12 @@ public final class PunktfunkConnection {
        var codec: UInt8 = 2 // PUNKTFUNK_CODEC_HEVC
        _ = punktfunk_connection_codec(handle, &codec)
        resolvedCodec = codec
+        var shard: UInt32 = 1408
+        _ = punktfunk_connection_shard_payload(handle, &shard)
+        shardPayload = shard
+        var caps: UInt8 = 0
+        _ = punktfunk_connection_host_caps(handle, &caps)
+        hostCaps = caps
    }

    /// A bandwidth speed-test measurement (see `startSpeedTest`). Partial until `done`.
@@ -447,6 +551,23 @@ public final class PunktfunkConnection {
        _ = punktfunk_connection_request_keyframe(h)
    }

+    /// Background-keep-alive video drop (opt-in). While true, both video pumps keep DRAINING
+    /// `nextAU()` (so QUIC flow control and host pacing stay healthy) but DISCARD each AU before any
+    /// VideoToolbox/Metal decode or render — the crash/jetsam-safe way to hold a backgrounded
+    /// session (audio keeps rendering; no GPU work off-screen). Set on `SessionModel.enterBackground`,
+    /// cleared on `exitBackground` (which then requests a fresh IDR; the pump's re-anchor gate
+    /// auto-arms on the resumed frame-index gap). Its own tiny lock — read on the pump thread every
+    /// iteration, written on the main actor; never contends the ABI/plane locks.
+    private let videoDropLock = NSLock()
+    private var videoDropped = false
+    public var isVideoDropped: Bool {
+        videoDropLock.lock(); defer { videoDropLock.unlock() }
+        return videoDropped
+    }
+    public func setVideoDropped(_ dropped: Bool) {
+        videoDropLock.lock(); videoDropped = dropped; videoDropLock.unlock()
+    }
+
    /// 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
@@ -491,6 +612,30 @@ public final class PunktfunkConnection {
        return out
    }

+    /// Report one decoded frame's decode-stage latency, in microseconds (the AU leaving `nextAU`
+    /// through its VideoToolbox output). This feeds the Automatic bitrate controller's decode
+    /// signal — the only one that sees this device's decoder — so the rate is capped at the real
+    /// decode limit instead of climbing to the network link ceiling and choking the decoder. Cheap;
+    /// silently dropped after close. Only worth calling when `wantsDecodeLatency()` is true.
+    public func reportDecodeUs(_ us: UInt32) {
+        abiLock.lock()
+        defer { abiLock.unlock() }
+        guard let h = handle, !closeRequested else { return }
+        _ = punktfunk_connection_report_decode_us(h, us)
+    }
+
+    /// Whether `reportDecodeUs` is worth calling this session: true only when the adaptive-bitrate
+    /// controller is armed (Automatic bitrate, non-PyroWave). Query once — constant for the session
+    /// — and skip the per-frame decode measurement entirely when it's false. False after close.
+    public func wantsDecodeLatency() -> Bool {
+        abiLock.lock()
+        defer { abiLock.unlock() }
+        guard let h = handle, !closeRequested else { return false }
+        var out = false
+        _ = punktfunk_connection_wants_decode_latency(h, &out)
+        return out
+    }
+
    /// The currently active session mode (updated by accepted `requestMode` switches).
    public func currentMode() -> (width: UInt32, height: UInt32, refreshHz: UInt32) {
        abiLock.lock()
@@ -649,6 +794,34 @@ public final class PunktfunkConnection {
        }
    }

+    /// Pull the next EFFECTIVE rumble command from the core's shared rumble policy engine — the
+    /// uniform replacement for per-platform rumble policy. The engine owns every decision
+    /// (v2 lease expiry, legacy-host staleness at a uniform 1 s, connection-close drain zeros),
+    /// so apply commands verbatim: `(0, 0)` = stop now, non-zero = run at this level.
+    /// `backstopMs` is a safety-net duration for duration-parameterized platform APIs — the
+    /// CoreHaptics renderer ignores it (its finite segment ceiling is the equivalent net).
+    /// Drain from the (single) feedback thread, alongside `nextHidOutput`.
+    public func nextRumbleCommand(timeoutMs: UInt32 = 0) throws
+        -> (pad: UInt16, low: UInt16, high: UInt16, backstopMs: UInt32)?
+    {
+        feedbackLock.lock()
+        defer { feedbackLock.unlock() }
+        guard let h = liveHandle() else { throw PunktfunkClientError.closed }
+
+        var pad: UInt16 = 0, low: UInt16 = 0, high: UInt16 = 0, backstop: UInt32 = 0
+        let rc = punktfunk_connection_next_rumble_cmd(h, &pad, &low, &high, &backstop, timeoutMs)
+        switch rc {
+        case statusOK:
+            return (pad, low, high, backstop)
+        case statusNoFrame:
+            return nil
+        case statusClosed:
+            throw PunktfunkClientError.closed
+        default:
+            throw PunktfunkClientError.status(rc)
+        }
+    }
+
    /// One DualSense feedback event a game wrote to the host's virtual pad — replay it on
    /// the real controller (GCDeviceLight, GCControllerPlayerIndex,
    /// GCDualSenseAdaptiveTrigger). Only a `.dualSense` session emits these.
@@ -712,6 +885,15 @@ public final class PunktfunkConnection {
    public static let codecH264: UInt8 = UInt8(PUNKTFUNK_CODEC_H264)
    public static let codecHEVC: UInt8 = UInt8(PUNKTFUNK_CODEC_HEVC)
    public static let codecAV1: UInt8 = UInt8(PUNKTFUNK_CODEC_AV1)
+    /// PyroWave (opt-in wired-LAN wavelet codec, 8-bit SDR): the host only ever resolves it
+    /// when the client both advertises the bit AND names it `preferredCodec` — never
+    /// auto-selected. Decoded by the Metal wavelet decoder, not VideoToolbox.
+    public static let codecPyroWave: UInt8 = UInt8(PUNKTFUNK_CODEC_PYROWAVE)
+
+    /// `AccessUnit.flags` bit: the AU is shard-aligned self-delimiting chunks (the wire's
+    /// `USER_FLAG_CHUNK_ALIGNED`, PyroWave datagram-aligned mode §4.4) — walk it
+    /// window-by-window at `shardPayload`. (The C `#define` doesn't import into Swift.)
+    public static let userFlagChunkAligned: UInt32 = 64

    /// Static HDR mastering metadata (SMPTE ST.2086 + content light level) the host sent for an HDR
    /// session. Mirrors the wire/ABI `PunktfunkHdrMeta`; primaries are in ST.2086 **G, B, R** order,
@@ -850,10 +1032,12 @@ public final class PunktfunkConnection {
        audioLock.lock()
        feedbackLock.lock()
        statsLock.lock()
+        clipboardLock.lock()
        abiLock.lock()
        let h = handle
        handle = nil
        abiLock.unlock()
+        clipboardLock.unlock()
        statsLock.unlock()
        feedbackLock.unlock()
        audioLock.unlock()
@@ -915,6 +1099,163 @@ public final class PunktfunkConnection {
        _ = punktfunk_connection_send_rich_input(h, &rich)
    }

+    // MARK: - Shared clipboard (design/clipboard-and-file-transfer.md §5)
+
+    /// One advertised clipboard format in a lazy offer — the format list crosses the wire,
+    /// the bytes only on a fetch.
+    public struct ClipKind: Sendable, Equatable {
+        public let mime: String
+        /// Best-effort size in bytes; `0` = unknown.
+        public let sizeHint: UInt64
+        public init(mime: String, sizeHint: UInt64 = 0) {
+            self.mime = mime
+            self.sizeHint = sizeHint
+        }
+    }
+
+    /// A shared-clipboard event from `nextClipboard`. The drain thread turns these into
+    /// NSPasteboard operations (`ClipboardSync`).
+    public enum ClipEvent: Sendable, Equatable {
+        /// The host copied: its lazy format list (empty = the host clipboard was cleared).
+        /// Fetch a format with `clipFetch(seq:mime:)` when a local app pastes.
+        case remoteOffer(seq: UInt32, kinds: [ClipKind])
+        /// Host ack / policy / backend update for `clipControl` (`CLIP_REASON_*`).
+        case state(enabled: Bool, policy: UInt8, reason: UInt8)
+        /// The host is pasting OUR offered data — answer with `clipServe(reqId:...)`.
+        case fetchRequest(reqId: UInt32, seq: UInt32, fileIndex: UInt32, mime: String)
+        /// Bytes for a fetch we started (`last` = final chunk).
+        case data(xferId: UInt32, chunk: Data, last: Bool)
+        /// A transfer was cancelled (either side).
+        case cancelled(id: UInt32)
+        /// A transfer failed (`status` = a PunktfunkStatus code).
+        case error(id: UInt32, status: Int32)
+    }
+
+    /// Enable/disable the shared clipboard for this session. Opt-in: nothing is announced or
+    /// served until enabled. The host answers with a `.state` event carrying the resolved
+    /// outcome (its operator policy is authoritative). Best-effort — a dropped call on a
+    /// closing session is fine.
+    public func clipControl(enabled: Bool, flags: UInt8 = 0) {
+        clipboardLock.lock()
+        defer { clipboardLock.unlock() }
+        guard let h = liveHandle() else { return }
+        _ = punktfunk_connection_clipboard_control(h, enabled, flags)
+    }
+
+    /// Announce that the local pasteboard changed — the lazy format-list offer (`seq` monotonic,
+    /// newest wins; empty `kinds` clears the host side). The bytes cross only if the host fetches.
+    public func clipOffer(seq: UInt32, kinds: [ClipKind]) {
+        clipboardLock.lock()
+        defer { clipboardLock.unlock() }
+        guard let h = liveHandle() else { return }
+        guard !kinds.isEmpty else {
+            _ = punktfunk_connection_clipboard_offer(h, seq, nil, 0)
+            return
+        }
+        // The C array borrows NUL-terminated strings for the duration of the call only.
+        let cStrings = kinds.map { strdup($0.mime) }
+        defer { cStrings.forEach { free($0) } }
+        let arr = zip(cStrings, kinds).map {
+            PunktfunkClipKind(mime: $0.map { UnsafePointer($0) }, size_hint: $1.sizeHint)
+        }
+        _ = arr.withUnsafeBufferPointer {
+            punktfunk_connection_clipboard_offer(h, seq, $0.baseAddress, UInt(arr.count))
+        }
+    }
+
+    /// Start pulling one format of the host's offer `seq` (a local app is pasting). Returns the
+    /// transfer id echoed on the resulting `.data`/`.error`/`.cancelled` events, or nil when the
+    /// session is closing.
+    public func clipFetch(seq: UInt32, mime: String, fileIndex: UInt32 = UInt32.max) -> UInt32? {
+        clipboardLock.lock()
+        defer { clipboardLock.unlock() }
+        guard let h = liveHandle() else { return nil }
+        var xfer: UInt32 = 0
+        let rc = mime.withCString {
+            punktfunk_connection_clipboard_fetch(h, seq, $0, fileIndex, &xfer)
+        }
+        return rc == statusOK ? xfer : nil
+    }
+
+    /// Provide bytes answering a `.fetchRequest` (the host is pasting our offered data). Call
+    /// repeatedly to stream; `last = true` completes the transfer. An empty final chunk is fine.
+    public func clipServe(reqId: UInt32, data: Data, last: Bool) {
+        clipboardLock.lock()
+        defer { clipboardLock.unlock() }
+        guard let h = liveHandle() else { return }
+        if data.isEmpty {
+            _ = punktfunk_connection_clipboard_serve(h, reqId, nil, 0, last)
+        } else {
+            data.withUnsafeBytes { p in
+                _ = punktfunk_connection_clipboard_serve(
+                    h, reqId, p.bindMemory(to: UInt8.self).baseAddress, UInt(data.count), last)
+            }
+        }
+    }
+
+    /// Cancel a clipboard transfer by id — an outbound fetch's `xferId` or an inbound
+    /// `.fetchRequest`'s `reqId`.
+    public func clipCancel(id: UInt32) {
+        clipboardLock.lock()
+        defer { clipboardLock.unlock() }
+        guard let h = liveHandle() else { return }
+        _ = punktfunk_connection_clipboard_cancel(h, id)
+    }
+
+    /// Pull the next shared-clipboard event; nil on timeout, throws `.closed` once the session
+    /// ended. Drain from a single dedicated thread (`ClipboardSync`) — the event's borrowed
+    /// payload is copied into the returned `ClipEvent` before the next poll can overwrite it.
+    public func nextClipboard(timeoutMs: UInt32) throws -> ClipEvent? {
+        clipboardLock.lock()
+        defer { clipboardLock.unlock() }
+        guard let h = liveHandle() else { throw PunktfunkClientError.closed }
+        var ev = PunktfunkClipEvent()
+        let rc = punktfunk_connection_next_clipboard(h, &ev, timeoutMs)
+        switch rc {
+        case statusOK:
+            return Self.decodeClipEvent(ev)
+        case statusNoFrame:
+            return nil
+        case statusClosed:
+            throw PunktfunkClientError.closed
+        default:
+            throw PunktfunkClientError.status(rc)
+        }
+    }
+
+    /// Copy a raw C clip event (whose `data` borrows a per-connection slot) into an owned Swift
+    /// value. Unknown kinds (a newer core) decode to nil and are skipped by the drain.
+    private static func decodeClipEvent(_ ev: PunktfunkClipEvent) -> ClipEvent? {
+        let payload = ev.data.map { Data(bytes: $0, count: Int(ev.len)) } ?? Data()
+        switch Int32(ev.kind) {
+        case PUNKTFUNK_CLIP_REMOTE_OFFER:
+            // One `mime\tsize_hint\n` line per advertised format.
+            let kinds = String(decoding: payload, as: UTF8.self)
+                .split(separator: "\n")
+                .compactMap { line -> ClipKind? in
+                    let parts = line.split(separator: "\t", maxSplits: 1)
+                    guard let mime = parts.first, !mime.isEmpty else { return nil }
+                    let hint = parts.count > 1 ? UInt64(parts[1]) ?? 0 : 0
+                    return ClipKind(mime: String(mime), sizeHint: hint)
+                }
+            return .remoteOffer(seq: ev.transfer_id, kinds: kinds)
+        case PUNKTFUNK_CLIP_STATE:
+            return .state(enabled: ev.enabled != 0, policy: ev.policy, reason: ev.reason)
+        case PUNKTFUNK_CLIP_FETCH_REQUEST:
+            return .fetchRequest(
+                reqId: ev.transfer_id, seq: ev.seq, fileIndex: ev.file_index,
+                mime: String(decoding: payload, as: UTF8.self))
+        case PUNKTFUNK_CLIP_DATA:
+            return .data(xferId: ev.transfer_id, chunk: payload, last: ev.last != 0)
+        case PUNKTFUNK_CLIP_CANCELLED:
+            return .cancelled(id: ev.transfer_id)
+        case PUNKTFUNK_CLIP_ERROR:
+            return .error(id: ev.transfer_id, status: ev.status)
+        default:
+            return nil
+        }
+    }
+
    deinit { close() }

    /// Snapshot the handle unless close is pending (callers hold their plane lock).
@@ -23,6 +23,7 @@ import Combine
 import CoreHaptics
 import Foundation
 import GameController
+import PunktfunkShared

 public final class GamepadFeedback {
    private let connection: PunktfunkConnection
@@ -154,21 +155,18 @@ public final class GamepadFeedback {
                    // meta, was unaffected). Pacing with a short sleep OUTSIDE the lock (below) keeps
                    // 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 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)] = [:]
+                    // Rumble arrives as EFFECTIVE commands from the core's shared policy engine
+                    // (design/rumble-root-fix.md §D): the engine owns leases, legacy staleness,
+                    // and close-drain zeros, and its per-pad mailbox already coalesces — a
+                    // stalled drain wakes to ONE current-level command per pad, and a stop can
+                    // never be shed by a queue. Apply verbatim, in order.
                    var rumbleBurst = 0
                    while rumbleBurst < 64, !flag.isStopped,
-                          let r = try connection.nextRumble2(timeoutMs: 0) {
-                        newestByPad[UInt8(truncatingIfNeeded: r.pad)] = (r.low, r.high, r.ttlMs)
+                          let c = try connection.nextRumbleCommand(timeoutMs: 0) {
+                        self?.routeRumble(
+                            pad: UInt8(truncatingIfNeeded: c.pad), low: c.low, high: c.high)
                        rumbleBurst += 1
                    }
-                    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.
                    var burst = 0
@@ -217,15 +215,15 @@ public final class GamepadFeedback {
        }
    }

-    /// Route one rumble envelope to its pad's renderer (drain thread). An update for a pad with no
+    /// Route one engine command to its pad's renderer (drain thread). A command 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) {
+    private func routeRumble(pad: UInt8, low: UInt16, high: UInt16) {
        let renderer = withRouting { rumbleByPad[pad] }
-        renderer?.apply(low: low, high: high, ttlMs: ttlMs)
+        renderer?.apply(low: low, high: high)
        // 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) }
+        if pad == 0 { deviceRumble?.apply(low: low, high: high) }
    }

    private func withRouting<R>(_ body: () -> R) -> R {
@@ -20,6 +20,7 @@
 import Combine
 import Foundation
 import GameController
+import PunktfunkShared

@MainActor
 public final class GamepadManager: ObservableObject {
@@ -6,6 +6,7 @@
 // the two combine without adding a second ObservableObject or an environment key nobody else needs.

 import Foundation
+import PunktfunkShared

 public enum GamepadUIEnvironment {
    /// `enabledSetting` is the user's Settings toggle (`DefaultsKey.gamepadUIEnabled`);
@@ -23,23 +23,6 @@ enum RumbleTuning {
    /// the churn that lost stops inside CoreHaptics. Newest level wins when the window opens;
    /// zero is never throttled.
    static let minRebakeSeconds: TimeInterval = 0.025
-    /// Session watchdog: silence the motors when no wire command arrived for this long. This is
-    /// the **legacy-host fallback only** — an old host sends no self-termination lease, so its
-    /// periodic re-send (every 500 ms) is the sole liveness signal and 3 vanished refreshes means
-    /// the channel or host died while audible. A v2 host instead supplies a per-command TTL (see
-    /// [`leaseSeconds`]); that deadline supersedes this watchdog.
-    static let sessionStaleSeconds: TimeInterval = 1.6
-
-    /// The legacy no-lease sentinel a v2 `ttl_ms` carries for an old host (mirrors the C ABI's
-    /// `PUNKTFUNK_RUMBLE_NO_TTL`). `UInt32.max` by construction.
-    static let noTTL: UInt32 = .max
-
-    /// Interpret a wire TTL (ms) from a rumble update: `nil` for the legacy no-lease sentinel
-    /// ([`noTTL`]) — the renderer falls back to [`sessionStaleSeconds`] — else the self-termination
-    /// lease in seconds (render the level for at most this long unless the host renews it).
-    static func leaseSeconds(ttlMs: UInt32) -> TimeInterval? {
-        ttlMs == noTTL ? nil : TimeInterval(ttlMs) / 1000
-    }
    /// Levels closer than this (≈0.4 % of full scale) are the same level — an identical host
    /// refresh must never rebuild a player.
    static let levelEpsilon: Float = 1.0 / 256.0
@@ -110,13 +93,15 @@ enum RumbleTuning {
 /// `@unchecked Sendable` is sound because every property is read and written only inside
 /// `queue` closures — the serial queue is the synchronization.
 final class RumbleRenderer: @unchecked Sendable {
-    /// What an un-refreshed nonzero target means. A live session ties motor life to wire
-    /// liveness (the host refreshes state every 500 ms); the controller test panel holds a
-    /// slider level indefinitely.
+    /// Who ends an un-refreshed nonzero target. Session mode applies the core policy engine's
+    /// commands verbatim — the engine (punktfunk-core `client/rumble.rs`) owns every lease,
+    /// staleness, and close decision and emits explicit zeros, so the renderer keeps NO
+    /// staleness policy of its own anymore. The controller test panel (`manual`) holds a slider
+    /// level indefinitely; both are identical renderer-side today, the distinction is kept for
+    /// the call sites' intent.
    struct Policy {
-        let staleAfter: TimeInterval?
-        static let session = Policy(staleAfter: RumbleTuning.sessionStaleSeconds)
-        static let manual = Policy(staleAfter: nil)
+        static let session = Policy()
+        static let manual = Policy()
    }

    /// Which physical actuator this renderer drives: the forwarded controller's haptics engine
@@ -160,13 +145,9 @@ final class RumbleRenderer: @unchecked Sendable {
    private var controller: GCController?
    private var low: Motor?
    private var high: Motor?
-    /// Wire-truth target (raw wire units) and when it was last confirmed by any command.
+    /// Wire-truth target (raw wire units) — the engine command's level, applied verbatim; the
+    /// core policy engine owns when it ends (explicit zero commands), so no deadline lives here.
    private var target: (low: UInt16, high: UInt16) = (0, 0)
-    private var lastCommand = DispatchTime(uptimeNanoseconds: 0)
-    /// The v2 envelope lease: the active level is authorized until here unless the host renews it
-    /// (`tick` silences at the deadline). `nil` against a legacy host (no lease — the
-    /// `sessionStaleSeconds` watchdog is the backstop) and while silent.
-    private var envelopeDeadline: DispatchTime?
    /// Runs while anything is (or should be) audible: staleness watchdog, segment re-arm,
    /// throttled-level catch-up, engine rebuild after a reset, HID keepalive. Nil while silent,
    /// so an idle controller costs no timer wakeups and no radio traffic.
@@ -247,17 +228,9 @@ final class RumbleRenderer: @unchecked Sendable {
    /// against a legacy host (no lease → the staleness watchdog is the backstop). Renewals at an
    /// unchanged level extend the deadline before the idempotence guard, so a held rumble never
    /// lapses mid-effect.
-    func apply(low lowAmp: UInt16, high highAmp: UInt16, ttlMs: UInt32 = RumbleTuning.noTTL) {
+    func apply(low lowAmp: UInt16, high highAmp: UInt16) {
        queue.async {
-            self.lastCommand = .now()
            let active = lowAmp != 0 || highAmp != 0
-            // v2 lease: a nonzero level gets an explicit deadline; a stop or a legacy update clears
-            // it. Set BEFORE the idempotence guard so an identical renewal still extends the lease.
-            if let lease = RumbleTuning.leaseSeconds(ttlMs: ttlMs), active {
-                self.envelopeDeadline = .now() + lease
-            } else {
-                self.envelopeDeadline = nil
-            }
            if active != self.wasActive {
                self.wasActive = active
                log.debug(
@@ -275,7 +248,6 @@ final class RumbleRenderer: @unchecked Sendable {
            self.ticker?.cancel()
            self.ticker = nil
            self.target = (0, 0)
-            self.envelopeDeadline = nil
            self.wasActive = false
            self.teardown()
            self.closeHID()
@@ -331,25 +303,11 @@ final class RumbleRenderer: @unchecked Sendable {
        healthSink?(problem)
    }

-    /// Watchdog + housekeeping heartbeat while audible.
+    /// Housekeeping heartbeat while audible: segment re-arm, HID keepalive, backoff retries.
+    /// Every liveness decision (lease expiry, legacy-host staleness, session close) lives in the
+    /// core policy engine now — it emits explicit zero commands, so the renderer never guesses
+    /// when a level should end.
    private func tick() {
-        if let deadline = envelopeDeadline {
-            // v2 host lease: silence the moment it lapses unrenewed. This firing in the wild is the
-            // observable signature of a host that stopped renewing (a dropped stop, or a dead host)
-            // — the whole point of the envelope model: the motor can't outlive the host's intent.
-            if target != (0, 0), DispatchTime.now() >= deadline {
-                log.warning("rumble: envelope expired unrenewed — silencing")
-                target = (0, 0)
-                envelopeDeadline = nil
-            }
-        } else if let after = policy.staleAfter, target != (0, 0), seconds(since: lastCommand) > after {
-            // Legacy host (no lease): it re-sends state every 500 ms, so this much silence means the
-            // channel (or host) died while a motor was on. A direct-connected pad would have been
-            // stopped by its game long ago — force the same outcome.
-            log.warning(
-                "rumble: no wire refresh for \(after, format: .fixed(precision: 1), privacy: .public)s — auto-silencing")
-            target = (0, 0)
-        }
        render()
    }

@@ -19,6 +19,7 @@
 #if os(iOS)
 import Foundation
 import PunktfunkCore
+import PunktfunkShared
 import UIKit

 /// How touchscreen fingers drive the host — persisted under `DefaultsKey.touchMode`, latched
@@ -0,0 +1,9 @@
+// PunktfunkShared holds what the app AND the widget extension both need — the stored-host model,
+// the settings-key names, the App-Group constant, the deep-link grammar, and the Live Activity
+// attributes — in a module that links neither the Rust core nor the presentation layer.
+//
+// Re-export it so every existing consumer of PunktfunkKit (`import PunktfunkKit`) keeps seeing
+// `StoredHost`, `DefaultsKey`, `punktfunkDefaultMgmtPort`, `DeepLink`, etc. with no call-site churn.
+// (Files INSIDE PunktfunkKit still `import PunktfunkShared` explicitly — Swift imports are
+// file-scoped; the re-export only reaches downstream modules.)
+@_exported import PunktfunkShared
@@ -8,6 +8,7 @@
 // tap, InputCapture's captured-state ⌃⌥⇧S) cycle it directly.

 import Foundation
+import PunktfunkShared

 /// How much of the streaming statistics overlay to show. The raw values are stable on disk —
 /// rename the cases freely, never the strings.
@@ -543,19 +543,24 @@ public enum AV1 {

 extension VideoCodec {
    /// Codec-dispatching format-description refresh: the AV1 path keys on an in-band sequence
-    /// header, the NAL codecs on in-band parameter sets — one call site in each pump.
+    /// header, the NAL codecs on in-band parameter sets — one call site in each pump. PyroWave
+    /// has no CoreMedia representation at all (its pump feeds the Metal wavelet decoder raw).
    public func formatDescription(fromKeyframe au: Data) -> CMVideoFormatDescription? {
-        self == .av1
-            ? AV1.formatDescription(fromKeyframe: au)
-            : AnnexB.formatDescription(fromIDR: au, codec: self)
+        switch self {
+        case .av1: return AV1.formatDescription(fromKeyframe: au)
+        case .pyrowave: return nil
+        default: return AnnexB.formatDescription(fromIDR: au, codec: self)
+        }
    }

    /// Codec-dispatching sample wrap (see `formatDescription(fromKeyframe:)`).
    public func sampleBuffer(
        au: AccessUnit, format: CMVideoFormatDescription
    ) -> CMSampleBuffer? {
-        self == .av1
-            ? AV1.sampleBuffer(au: au, format: format)
-            : AnnexB.sampleBuffer(au: au, format: format, codec: self)
+        switch self {
+        case .av1: return AV1.sampleBuffer(au: au, format: format)
+        case .pyrowave: return nil
+        default: return AnnexB.sampleBuffer(au: au, format: format, codec: self)
+        }
    }
 }
@@ -26,12 +26,18 @@ public enum VideoCodec: Equatable {
    case h264
    case hevc
    case av1
+    /// PyroWave wavelet (opt-in wired-LAN low-latency codec): not a NAL/OBU codec and not
+    /// VideoToolbox-decoded at all — the Metal wavelet decoder consumes the raw AUs
+    /// (Stage2Pipeline's PyroWave pump). Only ever resolved when this client both advertised
+    /// and preferred it.
+    case pyrowave

    /// Resolve from the wire `Welcome.codec` byte (`PUNKTFUNK_CODEC_*`; unknown → HEVC).
    public init(wire: UInt8) {
        switch wire {
        case 0x01: self = .h264 // PUNKTFUNK_CODEC_H264
        case 0x04: self = .av1 // PUNKTFUNK_CODEC_AV1
+        case 0x08: self = .pyrowave // PUNKTFUNK_CODEC_PYROWAVE
        default: self = .hevc // PUNKTFUNK_CODEC_HEVC — the default / older-host codec
        }
    }
@@ -147,8 +153,8 @@ public enum AnnexB {
            sets = [vps, sps, pps]
        case .h264:
            sets = [sps, pps]
-        case .av1:
-            return nil // OBU stream, no parameter-set NALs — handled in AV1.swift, never here
+        case .av1, .pyrowave:
+            return nil // no parameter-set NALs — dispatched in AV1.swift, never reaches here
        }

        var format: CMVideoFormatDescription?
@@ -184,8 +190,8 @@ public enum AnnexB {
                    parameterSetSizes: sizes,
                    nalUnitHeaderLength: 4,
                    formatDescriptionOut: &format)
-            case .av1:
-                break // unreachable — the .av1 arm above already returned
+            case .av1, .pyrowave:
+                break // unreachable — the arm above already returned
            }
        }
        return status == noErr ? format : nil
@@ -149,6 +149,28 @@ fragment float4 pf_frag(VOut in [[stage_in]],
    return float4(sampleRgb(lumaTex, chromaTex, in.uv, csc), 1.0);
 }

+// PyroWave planar SDR: three separate R8 planes (Y full-res, Cb/Cr half-res 4:2:0) from the
+// Metal wavelet decoder — the Metal twin of pf-presenter's planar_csc.frag. Same bicubic luma
+// and left-cosited chroma correction as the biplanar path (chromaUV self-disables at 4:4:4).
+fragment float4 pf_frag_planar(VOut in [[stage_in]],
+                               texture2d<float> lumaTex [[texture(0)]],
+                               texture2d<float> cbTex [[texture(1)]],
+                               texture2d<float> crTex [[texture(2)]],
+                               constant CscUniform& csc [[buffer(0)]]) {
+    constexpr sampler s(filter::linear, address::clamp_to_edge);
+#ifdef PF_BILINEAR_LUMA
+    float lumaY = lumaTex.sample(s, in.uv).r;
+#else
+    float lumaY = catmullRomLuma(lumaTex, s, in.uv);
+#endif
+    float2 cuv = chromaUV(lumaTex, cbTex, in.uv);
+    float3 yuv = float3(lumaY, cbTex.sample(s, cuv).r, crTex.sample(s, cuv).r);
+    float3 rgb = saturate(float3(dot(csc.r0.xyz, yuv) + csc.r0.w,
+                                 dot(csc.r1.xyz, yuv) + csc.r1.w,
+                                 dot(csc.r2.xyz, yuv) + csc.r2.w));
+    return float4(rgb, 1.0);
+}
+
 // HDR: 10-bit P010 / 4:4:4 (BT.2020, PQ-encoded Y′CbCr) → full-range PQ R′G′B′, output as-is —
 // the CAMetalLayer's itur_2100_PQ colour space + edrMetadata tell the compositor the samples are
 // PQ, so it does the PQ→display tone-map. No EOTF here. The rows fold in the exact 10-bit
@@ -215,8 +237,16 @@ public final class MetalVideoPresenter {
    /// tvOS only: the in-shader PQ→SDR tone-map fallback (pf_frag_hdr_tv → bgra8), used whenever
    /// the display is composited without HDR headroom — see `setDisplayHeadroom`. nil elsewhere.
    private let pipelineHDRToneMap: MTLRenderPipelineState?
+    /// PyroWave's 3-plane SDR path (pf_frag_planar → bgra8) — see `renderPlanar`.
+    private let pipelinePlanar: MTLRenderPipelineState
    private var textureCache: CVMetalTextureCache?

+    /// The PyroWave Metal decoder records on the presenter's device + queue: one device means
+    /// decode, CSC and present share textures with zero interop, and one queue means Metal's
+    /// hazard tracking orders a ring-slot rewrite after the render still sampling it.
+    var metalDevice: MTLDevice { device }
+    var metalQueue: MTLCommandQueue { queue }
+
    /// Current layer configuration — switched in `configure(hdr:)` when a frame's HDR-ness differs.
    /// Render-thread confined once the pipeline runs (Stage2Pipeline.start's one pre-thread
    /// `configure` call is ordered before the thread starts, so it doesn't race).
@@ -258,6 +288,7 @@ public final class MetalVideoPresenter {
        let pipelineSDR: MTLRenderPipelineState
        let pipelineHDR: MTLRenderPipelineState
        let pipelineHDRToneMap: MTLRenderPipelineState?
+        let pipelinePlanar: MTLRenderPipelineState
        do {
            // 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
@@ -292,6 +323,11 @@ public final class MetalVideoPresenter {
            #else
            pipelineHDRToneMap = nil
            #endif
+            let planar = MTLRenderPipelineDescriptor()
+            planar.vertexFunction = vtx
+            planar.fragmentFunction = library.makeFunction(name: "pf_frag_planar")
+            planar.colorAttachments[0].pixelFormat = .bgra8Unorm // PyroWave is 8-bit SDR
+            pipelinePlanar = try device.makeRenderPipelineState(descriptor: planar)
        } catch {
            return nil
        }
@@ -331,12 +367,14 @@ public final class MetalVideoPresenter {

        return MetalVideoPresenter(
            device: device, queue: queue, pipelineSDR: pipelineSDR, pipelineHDR: pipelineHDR,
-            pipelineHDRToneMap: pipelineHDRToneMap, textureCache: textureCache, layer: layer)
+            pipelineHDRToneMap: pipelineHDRToneMap, pipelinePlanar: pipelinePlanar,
+            textureCache: textureCache, layer: layer)
    }

    private init(
        device: MTLDevice, queue: MTLCommandQueue, pipelineSDR: MTLRenderPipelineState,
        pipelineHDR: MTLRenderPipelineState, pipelineHDRToneMap: MTLRenderPipelineState?,
+        pipelinePlanar: MTLRenderPipelineState,
        textureCache: CVMetalTextureCache, layer: CAMetalLayer
    ) {
        self.device = device
@@ -344,6 +382,7 @@ public final class MetalVideoPresenter {
        self.pipelineSDR = pipelineSDR
        self.pipelineHDR = pipelineHDR
        self.pipelineHDRToneMap = pipelineHDRToneMap
+        self.pipelinePlanar = pipelinePlanar
        self.textureCache = textureCache
        self.layer = layer
    }
@@ -514,6 +553,67 @@ public final class MetalVideoPresenter {
                pixelBuffer, plane: 1, format: tenBit ? .rg16Unorm : .rg8Unorm, cache: textureCache)
        else { return false }

+        #if os(tvOS)
+        // HDR splits by the display's headroom (kept in step with the layer by `configure` above):
+        // PQ passthrough into an HDR-composited display, the tone-map shader otherwise.
+        let hdrPipeline = hdrPassthroughActive ? pipelineHDR : (pipelineHDRToneMap ?? pipelineHDR)
+        let pipeline = hdrActive ? hdrPipeline : pipelineSDR
+        #else
+        let pipeline = hdrActive ? pipelineHDR : pipelineSDR
+        #endif
+        let decodedSize = CGSize(
+            width: CVPixelBufferGetWidth(pixelBuffer), height: CVPixelBufferGetHeight(pixelBuffer))
+        return encodePresent(
+            decodedSize: decodedSize, targetFromLayout: targetFromLayout, pipeline: pipeline,
+            presentAtMediaTime: presentAtMediaTime, onPresented: onPresented,
+            // Hold the CVMetalTextures + source pixel buffer (its IOSurface) alive until the GPU
+            // finishes sampling — releasing them at scope exit could free the backing mid-read.
+            keepAlive: [luma, chroma, pixelBuffer]
+        ) { encoder in
+            encoder.setFragmentTexture(CVMetalTextureGetTexture(luma), index: 0)
+            encoder.setFragmentTexture(CVMetalTextureGetTexture(chroma), index: 1)
+            encoder.setFragmentBytes(&csc, length: MemoryLayout<CscUniform>.stride, index: 0)
+        }
+    }
+
+    /// Draw one PyroWave planar frame (three R8 planes off the Metal wavelet decoder) and
+    /// present it. RENDER THREAD, same contract as `render` — PyroWave is 8-bit SDR, so the
+    /// layer always takes the plain SDR config, and the CSC rows arrive precomputed from the
+    /// stream's own sequence-header signaling (no CVPixelBuffer to inspect).
+    @discardableResult
+    func renderPlanar(
+        _ planes: WaveletPlanes,
+        presentAtMediaTime: CFTimeInterval? = nil,
+        onPresented: ((Int64?) -> Void)? = nil
+    ) -> Bool {
+        stagingLock.lock()
+        let targetFromLayout = drawableTarget
+        stagingLock.unlock()
+        configure(hdr: false)
+        var csc = planes.csc
+        return encodePresent(
+            decodedSize: CGSize(width: planes.width, height: planes.height),
+            targetFromLayout: targetFromLayout, pipeline: pipelinePlanar,
+            presentAtMediaTime: presentAtMediaTime, onPresented: onPresented,
+            // The ring textures stay valid by ring depth; retaining them here also pins the
+            // slot's set until the sample completes (mirrors the biplanar keep-alive).
+            keepAlive: [planes.y, planes.cb, planes.cr]
+        ) { encoder in
+            encoder.setFragmentTexture(planes.y, index: 0)
+            encoder.setFragmentTexture(planes.cb, index: 1)
+            encoder.setFragmentTexture(planes.cr, index: 2)
+            encoder.setFragmentBytes(&csc, length: MemoryLayout<CscUniform>.stride, index: 0)
+        }
+    }
+
+    /// The shared present tail of `render`/`renderPlanar`: size the drawable, encode one
+    /// fullscreen triangle with `pipeline` (`bind` supplies the fragment resources), schedule
+    /// the present and the on-glass callback.
+    private func encodePresent(
+        decodedSize: CGSize, targetFromLayout: CGSize, pipeline: MTLRenderPipelineState,
+        presentAtMediaTime: CFTimeInterval?, onPresented: ((Int64?) -> Void)?,
+        keepAlive: [Any], bind: (MTLRenderCommandEncoder) -> Void
+    ) -> Bool {
        // Size the drawable to the LAYER's pixels (its laid-out frame × contentsScale, pushed here by
        // SessionPresenter.layout via `setDrawableTarget` — not read off the layer, whose geometry the
        // main thread owns) so the Catmull-Rom shader performs the decoded→on-screen scale in one pass:
@@ -522,8 +622,6 @@ public final class MetalVideoPresenter {
        // Before the first layout (zero target) fall back to the decoded size. drawableSize does NOT
        // track bounds (defaults to 0), so set it BEFORE nextDrawable; re-set only on a change
        // (layout / Reconfigure / HDR flip — and every frame of a live resize, which is fine).
-        let decodedSize = CGSize(
-            width: CVPixelBufferGetWidth(pixelBuffer), height: CVPixelBufferGetHeight(pixelBuffer))
        let targetSize = (targetFromLayout.width > 0 && targetFromLayout.height > 0)
            ? targetFromLayout : decodedSize
        if layer.drawableSize != targetSize { layer.drawableSize = targetSize }
@@ -542,17 +640,8 @@ public final class MetalVideoPresenter {
        guard let encoder = commandBuffer.makeRenderCommandEncoder(descriptor: pass) else {
            return false
        }
-        #if os(tvOS)
-        // HDR splits by the display's headroom (kept in step with the layer by `configure` above):
-        // PQ passthrough into an HDR-composited display, the tone-map shader otherwise.
-        let hdrPipeline = hdrPassthroughActive ? pipelineHDR : (pipelineHDRToneMap ?? pipelineHDR)
-        encoder.setRenderPipelineState(hdrActive ? hdrPipeline : pipelineSDR)
-        #else
-        encoder.setRenderPipelineState(hdrActive ? pipelineHDR : pipelineSDR)
-        #endif
-        encoder.setFragmentTexture(CVMetalTextureGetTexture(luma), index: 0)
-        encoder.setFragmentTexture(CVMetalTextureGetTexture(chroma), index: 1)
-        encoder.setFragmentBytes(&csc, length: MemoryLayout<CscUniform>.stride, index: 0)
+        encoder.setRenderPipelineState(pipeline)
+        bind(encoder)
        encoder.drawPrimitives(type: .triangle, vertexStart: 0, vertexCount: 3)
        encoder.endEncoding()
        if let onPresented {
@@ -580,9 +669,8 @@ public final class MetalVideoPresenter {
        } else {
            commandBuffer.present(drawable)
        }
-        // Hold the CVMetalTextures + source pixel buffer (its IOSurface) alive until the GPU finishes
-        // sampling — releasing them at scope exit could free the backing mid-read.
-        commandBuffer.addCompletedHandler { _ in _ = (luma, chroma, pixelBuffer) }
+        // Keep the bound sources alive until the GPU finishes sampling (see the callers).
+        commandBuffer.addCompletedHandler { _ in _ = keepAlive }
        commandBuffer.commit()
        return true
    }
@@ -0,0 +1,604 @@
+// PyroWave native Metal decoder — the Apple twin of pf-client-core's Vulkan decoder
+// (crates/pf-client-core/src/video_pyrowave.rs), reimplemented on the presenter's own MTLDevice
+// so decode + CSC + present share one device with zero interop (design/pyrowave-codec-plan.md
+// §4.7). No upstream C/C++ ships in the app: the bitstream parse below reimplements
+// pyrowave_decoder.cpp's push_packet/decode_packet walk, and the two compute kernels
+// (MetalWaveletShaders.swift) are hand-ported from the vendored GLSL. The §4.2 upstream pin
+// covers this hand-port: a vendored bump means re-diffing two decode shaders and the two 8-byte
+// header structs, and it is already a protocol-version event.
+//
+// Wire shape (all fixed by the host encoder, punktfunk-host encode/linux/pyrowave.rs):
+// • One AU = one frame = a self-delimiting stream of packets. Each packet is one 32x32
+//   coefficient block for one (component, level, band), self-sized by its 8-byte
+//   BitstreamHeader; a per-frame START_OF_FRAME sequence header carries dims + total block
+//   count + the VUI bits (chroma 4:2:0, BT.709/BT.2020, limited/full).
+// • With `USER_FLAG_CHUNK_ALIGNED` (Phase 4) the AU is a whole number of `shard_payload`-sized
+//   windows, each 4-byte-prefixed (used-len u16 LE + kind u16 LE): kind 0 = whole packets,
+//   1/2/3 = FRAG chain for a packet bigger than one window. A missing shard of a partial frame
+//   arrives as an all-zero window (used = 0) → skipped, its blocks reconstruct as zeros
+//   (localized blur, the Phase-4 design intent). The reassembler enables partial delivery
+//   core-side automatically for PyroWave sessions.
+// • Decode acceptance mirrors upstream decode_is_ready(allow_partial=true): a frame with no
+//   SOF or with no more than half its blocks is dropped rather than decoded to garbage.
+//
+// GPU structure per frame (mirroring pyrowave_decoder.cpp's barriers): one concurrent compute
+// encoder with all ~42 dequant dispatches (each writes a distinct band layer — no intra-stage
+// hazards), then one concurrent encoder per iDWT level (5) — encoder boundaries provide the
+// write→sampled-read synchronization the Vulkan version expresses as pipeline barriers. The
+// output is a ring of 4 plane sets (Y full-res + Cb/Cr half-res R8Unorm); ring depth plus
+// same-queue hazard tracking keeps a set alive while the presenter still samples it (the same
+// scheme as the Vulkan client's ring).
+
+#if canImport(Metal)
+import Foundation
+import Metal
+import os
+
+private let waveletLog = Logger(subsystem: "io.unom.punktfunk", category: "pyrowave")
+
+/// The per-(component, level, band) 32x32-block table — the exact Swift port of
+/// `WaveletBuffers::init_block_meta` (pyrowave_common.cpp): the walk order (level 4→0,
+/// component 0→2 skipping level-0 chroma in 4:2:0, band (level==4 ? 0 : 1)→3) DEFINES the
+/// global `block_index` space the wire packets address, so it must match the encoder exactly.
+struct WaveletLayout {
+    static let decompositionLevels = 5
+    static let alignment = 32
+    static let minimumImageSize = 128
+
+    let width: Int
+    let height: Int
+    let alignedWidth: Int
+    let alignedHeight: Int
+    /// blockMeta[component][level][band] = (blockOffset32x32, blockStride32x32); -1 offset =
+    /// band not coded (level-0 chroma in 4:2:0).
+    let blockMeta: [[[(offset: Int, stride: Int)]]]
+    let blockCount32: Int
+
+    /// Band-image extent at `level` — mip `level` of the (aligned/2)-sized coefficient image.
+    /// Exact halving: the aligned dims are 32-aligned, so /2 is 16-aligned and survives 4 shifts.
+    func levelWidth(_ level: Int) -> Int { (alignedWidth / 2) >> level }
+    func levelHeight(_ level: Int) -> Int { (alignedHeight / 2) >> level }
+
+    init(width: Int, height: Int) {
+        self.width = width
+        self.height = height
+        let align = { (v: Int) in
+            max((v + Self.alignment - 1) & ~(Self.alignment - 1), Self.minimumImageSize)
+        }
+        alignedWidth = align(width)
+        alignedHeight = align(height)
+
+        var meta = [[[(offset: Int, stride: Int)]]](
+            repeating: [[(offset: Int, stride: Int)]](
+                repeating: [(offset: Int, stride: Int)](repeating: (-1, 0), count: 4),
+                count: Self.decompositionLevels),
+            count: 3)
+        var count32 = 0
+        let aw = alignedWidth
+        let ah = alignedHeight
+        for level in stride(from: Self.decompositionLevels - 1, through: 0, by: -1) {
+            for component in 0..<3 {
+                if level == 0 && component != 0 { continue } // 4:2:0: no top-level chroma
+                for band in (level == Self.decompositionLevels - 1 ? 0 : 1)..<4 {
+                    let levelW = (aw / 2) >> level
+                    let levelH = (ah / 2) >> level
+                    let blocksX8 = (levelW + 7) / 8
+                    let blocksY8 = (levelH + 7) / 8
+                    let blocksX32 = (levelW + 31) / 32
+                    meta[component][level][band] = (count32, blocksX32)
+                    // accumulate_block_mapping's 32x32 count.
+                    count32 += ((blocksX8 + 3) / 4) * ((blocksY8 + 3) / 4)
+                }
+            }
+        }
+        blockMeta = meta
+        blockCount32 = count32
+    }
+}
+
+/// One parsed frame, CPU side: the per-block payload offset table + the flat payload words the
+/// dequant kernel consumes (packet words INCLUDING each 8-byte header, as upstream uploads
+/// them), plus the sequence header's facts.
+struct ParsedWaveletFrame {
+    var layout: WaveletLayout
+    /// Per 32x32 block: u32 word offset into `payload`, or UInt32.max = block missing.
+    var offsets: [UInt32]
+    var payload: [UInt32]
+    var totalBlocks: Int
+    var decodedBlocks: Int
+    /// VUI bits from the sequence header (BitstreamSequenceHeader).
+    var bt2020: Bool
+    var fullRange: Bool
+
+    /// The frame's Y′CbCr→RGB signal for the presenter's planar CSC. PyroWave today is always
+    /// BT.709 limited (the host's fixed contract), but the sequence header signals it, so honor
+    /// what it says.
+    var cscSignal: CscRows.Signal {
+        CscRows.Signal(matrix: bt2020 ? 9 : 1, fullRange: fullRange)
+    }
+}
+
+enum WaveletBitstream {
+    /// Window kinds of the chunk-aligned framing (host WIN_* constants).
+    private static let winPacked: UInt16 = 0
+    private static let winFragFirst: UInt16 = 1
+    private static let winFragCont: UInt16 = 2
+    private static let winFragLast: UInt16 = 3
+
+    /// Parse one AU into the dequant kernel's inputs. `windowSize` > 0 with `chunkAligned`
+    /// walks the Phase-4 shard-window framing first; otherwise the AU is one packet stream.
+    /// nil = drop the frame (malformed, no SOF, or not enough blocks survived loss to be worth
+    /// decoding — upstream's `decoded_blocks > total/2` partial rule).
+    static func parse(au: Data, chunkAligned: Bool, windowSize: Int) -> ParsedWaveletFrame? {
+        var state = ParseState()
+        let ok = au.withUnsafeBytes { (raw: UnsafeRawBufferPointer) -> Bool in
+            guard let base = raw.baseAddress?.assumingMemoryBound(to: UInt8.self) else {
+                return false
+            }
+            let count = raw.count
+            if chunkAligned, windowSize >= 8 {
+                // Whole windows only; a trailing partial window would be a framing bug.
+                guard count % windowSize == 0 else { return false }
+                var frag: [UInt8] = []
+                var fragLive = false
+                var pos = 0
+                while pos < count {
+                    let win = UnsafeBufferPointer(start: base + pos, count: windowSize)
+                    pos += windowSize
+                    let used = Int(win[0]) | (Int(win[1]) << 8)
+                    let kind = UInt16(win[2]) | (UInt16(win[3]) << 8)
+                    // A zeroed (missing) shard or an overrun drops the window AND breaks any
+                    // fragment chain riding across it (mirrors video_pyrowave.rs push_window).
+                    guard used > 0, 4 + used <= windowSize else {
+                        frag.removeAll(keepingCapacity: true)
+                        fragLive = false
+                        continue
+                    }
+                    let body = UnsafeBufferPointer(start: win.baseAddress! + 4, count: used)
+                    switch kind {
+                    case winPacked:
+                        frag.removeAll(keepingCapacity: true)
+                        fragLive = false
+                        guard state.pushPackets(body) else { return false }
+                    case winFragFirst:
+                        frag.removeAll(keepingCapacity: true)
+                        frag.append(contentsOf: body)
+                        fragLive = true
+                    case winFragCont:
+                        if fragLive { frag.append(contentsOf: body) }
+                    case winFragLast:
+                        if fragLive {
+                            frag.append(contentsOf: body)
+                            let ok = frag.withUnsafeBufferPointer { state.pushPackets($0) }
+                            guard ok else { return false }
+                        }
+                        frag.removeAll(keepingCapacity: true)
+                        fragLive = false
+                    default:
+                        frag.removeAll(keepingCapacity: true)
+                        fragLive = false
+                    }
+                }
+                return true
+            }
+            return state.pushPackets(UnsafeBufferPointer(start: base, count: count))
+        }
+        guard ok, let frame = state.finish() else { return nil }
+        // Upstream decode_is_ready(allow_partial=true): with no SOF the frame is undecodable;
+        // at half the blocks or fewer it is presumed garbage.
+        guard frame.totalBlocks > 0, frame.decodedBlocks > frame.totalBlocks / 2 else {
+            return nil
+        }
+        return frame
+    }
+
+    /// Streaming packet-walk state (pyrowave_decoder.cpp push_packet + decode_packet). The
+    /// SOF sequence header arrives first in every host AU, which fixes the dims → layout →
+    /// offset-table size before any coefficient packet lands; a coefficient packet before the
+    /// SOF (its window was lost) is skipped — its block just stays missing.
+    private struct ParseState {
+        var layout: WaveletLayout?
+        var offsets: [UInt32] = []
+        var payload: [UInt32] = []
+        var totalBlocks = 0
+        var decodedBlocks = 0
+        var bt2020 = false
+        var fullRange = false
+        var sawSOF = false
+
+        mutating func pushPackets(_ buf: UnsafeBufferPointer<UInt8>) -> Bool {
+            guard let base = buf.baseAddress else { return true }
+            var pos = 0
+            let count = buf.count
+            while count - pos >= 8 {
+                let word0 = loadWord(base, pos)
+                let word1 = loadWord(base, pos + 4)
+                let extended = (word0 >> 31) & 1
+                if extended != 0 {
+                    // BitstreamSequenceHeader: w-1[0:14] h-1[14:28] seq[28:31] ext[31];
+                    // total[0:24] code[24:26] chroma[26] prim[27] trc[28] mtx[29] range[30]
+                    // siting[31].
+                    let code = (word1 >> 24) & 0x3
+                    guard code == 0 else { return false } // only START_OF_FRAME is defined
+                    let chromaRes = (word1 >> 26) & 1
+                    guard chromaRes == 0 else { return false } // host contract: 4:2:0
+                    let w = Int(word0 & 0x3fff) + 1
+                    let h = Int((word0 >> 14) & 0x3fff) + 1
+                    guard w >= 2, h >= 2, w % 2 == 0, h % 2 == 0 else { return false }
+                    if sawSOF {
+                        // One frame, one geometry — a second SOF must agree.
+                        guard layout?.width == w, layout?.height == h else { return false }
+                    } else {
+                        sawSOF = true
+                        let l = WaveletLayout(width: w, height: h)
+                        layout = l
+                        offsets = [UInt32](repeating: .max, count: l.blockCount32)
+                        payload.reserveCapacity(64 * 1024 / 4)
+                        totalBlocks = Int(word1 & 0xff_ffff)
+                        bt2020 = (word1 >> 29) & 1 != 0
+                        fullRange = (word1 >> 30) & 1 == 0 // YCBCR_RANGE_FULL = 0
+                    }
+                    pos += 8
+                    continue
+                }
+                // BitstreamHeader: ballot[0:16] payload_words[16:28] seq[28:31] ext[31];
+                // quant_code[0:8] block_index[8:32]. payload_words counts u32s INCLUDING the
+                // 8-byte header.
+                let payloadWords = Int((word0 >> 16) & 0xfff)
+                guard payloadWords >= 2, pos + payloadWords * 4 <= count else { return false }
+                let blockIndex = Int(word1 >> 8)
+                if let layout, blockIndex < layout.blockCount32 {
+                    // First write wins (duplicate packets are ignored, like upstream).
+                    if offsets[blockIndex] == .max {
+                        offsets[blockIndex] = UInt32(payload.count)
+                        decodedBlocks += 1
+                        payload.reserveCapacity(payload.count + payloadWords)
+                        for w in 0..<payloadWords {
+                            payload.append(loadWord(base, pos + w * 4))
+                        }
+                    }
+                } else if layout != nil {
+                    return false // out-of-bounds block index — corrupt stream
+                }
+                // No layout yet (SOF lost): skip the packet, the block stays missing.
+                pos += payloadWords * 4
+            }
+            // In the windowed framing, `used` delimits exactly; dense AUs must also consume
+            // fully (upstream errors on trailing bytes).
+            return pos == count
+        }
+
+        private func loadWord(_ base: UnsafePointer<UInt8>, _ offset: Int) -> UInt32 {
+            UInt32(base[offset])
+                | (UInt32(base[offset + 1]) << 8)
+                | (UInt32(base[offset + 2]) << 16)
+                | (UInt32(base[offset + 3]) << 24)
+        }
+
+        func finish() -> ParsedWaveletFrame? {
+            guard let layout else { return nil }
+            return ParsedWaveletFrame(
+                layout: layout, offsets: offsets, payload: payload,
+                totalBlocks: totalBlocks, decodedBlocks: decodedBlocks,
+                bt2020: bt2020, fullRange: fullRange)
+        }
+    }
+}
+
+/// One decoded frame's output planes, handed to the presenter's planar render path. The
+/// textures belong to the decoder's ring — ring depth (4) plus same-queue hazard tracking keep
+/// them valid while referenced. Public because it rides inside `ReadyImage`.
+public struct WaveletPlanes: @unchecked Sendable {
+    public let y: MTLTexture
+    public let cb: MTLTexture
+    public let cr: MTLTexture
+    public let csc: CscUniform
+    public var width: Int { y.width }
+    public var height: Int { y.height }
+}
+
+public final class MetalWaveletDecoder {
+    /// Matches the Vulkan client's ring: deep enough that a slot is never rewritten while the
+    /// presenter still samples it in practice; same-queue hazard tracking is the hard backstop.
+    private static let ringDepth = 4
+
+    /// Device-capability gate for advertisement (SessionModel) and the settings picker: the
+    /// dequant kernel needs simdgroup prefix sums with its 16 header lanes inside one
+    /// simdgroup, so compile the real kernels once and check the pipeline facts. Apple6 (A13)
+    /// and every Mac2 device pass the family check; the compile probe is authoritative.
+    public static let supported: Bool = {
+        guard let device = MTLCreateSystemDefaultDevice() else { return false }
+        guard device.supportsFamily(.apple6) || device.supportsFamily(.mac2) else { return false }
+        do {
+            let lib = try device.makeLibrary(source: waveletShaderSource, options: nil)
+            guard let dequant = lib.makeFunction(name: "wavelet_dequant") else { return false }
+            let p = try device.makeComputePipelineState(function: dequant)
+            var shift = false
+            let fc = MTLFunctionConstantValues()
+            fc.setConstantValue(&shift, type: .bool, index: 0)
+            _ = try lib.makeFunction(name: "idwt", constantValues: fc)
+            return p.threadExecutionWidth >= 16 && p.maxTotalThreadsPerThreadgroup >= 128
+        } catch {
+            waveletLog.info("pyrowave probe: kernels rejected (\(error, privacy: .public))")
+            return false
+        }
+    }()
+
+    private let device: MTLDevice
+    private let queue: MTLCommandQueue
+    private let dequantPipeline: MTLComputePipelineState
+    private let idwtPipeline: MTLComputePipelineState
+    private let idwtShiftPipeline: MTLComputePipelineState
+    private let mirrorSampler: MTLSamplerState
+
+    // Size-dependent state, rebuilt when the SOF dims change (this is also the mid-stream
+    // Reconfigure/resize path — the wavelet decoder is fixed-size per geometry).
+    private var layout: WaveletLayout?
+    /// coefficients[component][level]: 4-slice R16Float (levels 0–1) / R32Float (levels 2–4)
+    /// texture2d_array — the band images (precision-1 split, see MetalWaveletShaders).
+    private var coefficients: [[MTLTexture]] = []
+    /// llViews[component][level]: slice-0 (LL band) 2D write view of `coefficients` — the iDWT
+    /// output target chaining level L+1 into level L.
+    private var llViews: [[MTLTexture]] = []
+
+    private struct Slot {
+        var y: MTLTexture
+        var cb: MTLTexture
+        var cr: MTLTexture
+        var offsets: MTLBuffer
+        var payload: MTLBuffer
+    }
+
+    private var slots: [Slot] = []
+    private var nextSlot = 0
+
+    /// The current geometry (from the last SOF that built the resources) — the pump reports
+    /// decoded-size changes to the resize overlay from this. PUMP THREAD.
+    var decodedSize: (width: Int, height: Int)? {
+        layout.map { ($0.width, $0.height) }
+    }
+
+    /// The pump thread owns `decode`; everything mutable is confined to it.
+    init?(device: MTLDevice, queue: MTLCommandQueue) {
+        self.device = device
+        self.queue = queue
+        do {
+            let lib = try device.makeLibrary(source: waveletShaderSource, options: nil)
+            guard let dequantFn = lib.makeFunction(name: "wavelet_dequant") else { return nil }
+            dequantPipeline = try device.makeComputePipelineState(function: dequantFn)
+            var shift = false
+            let fcOff = MTLFunctionConstantValues()
+            fcOff.setConstantValue(&shift, type: .bool, index: 0)
+            idwtPipeline = try device.makeComputePipelineState(
+                function: try lib.makeFunction(name: "idwt", constantValues: fcOff))
+            shift = true
+            let fcOn = MTLFunctionConstantValues()
+            fcOn.setConstantValue(&shift, type: .bool, index: 0)
+            idwtShiftPipeline = try device.makeComputePipelineState(
+                function: try lib.makeFunction(name: "idwt", constantValues: fcOn))
+        } catch {
+            waveletLog.error("pyrowave: pipeline build failed (\(error, privacy: .public))")
+            return nil
+        }
+        guard dequantPipeline.threadExecutionWidth >= 16,
+              dequantPipeline.maxTotalThreadsPerThreadgroup >= 128
+        else { return nil }
+        // Upstream's mirror_repeat_sampler: mirrored repeat, NEAREST everything, normalized
+        // coords — the idwt gather footprint + coordinate nudge depend on exactly this.
+        let samp = MTLSamplerDescriptor()
+        samp.sAddressMode = .mirrorRepeat
+        samp.tAddressMode = .mirrorRepeat
+        samp.minFilter = .nearest
+        samp.magFilter = .nearest
+        samp.mipFilter = .notMipmapped
+        samp.normalizedCoordinates = true
+        guard let sampler = device.makeSamplerState(descriptor: samp) else { return nil }
+        mirrorSampler = sampler
+    }
+
+    /// Decode one AU. Synchronous CPU parse + async GPU decode: returns false when the frame
+    /// was dropped (malformed / SOF lost / not enough blocks); on true, `completion` fires on a
+    /// Metal callback thread once the planes are decoded (nil = the GPU pass errored).
+    /// PUMP THREAD only.
+    func decode(
+        au: Data, chunkAligned: Bool, windowSize: Int,
+        completion: @escaping @Sendable (WaveletPlanes?) -> Void
+    ) -> Bool {
+        guard
+            let frame = WaveletBitstream.parse(
+                au: au, chunkAligned: chunkAligned, windowSize: windowSize)
+        else { return false }
+
+        if layout?.width != frame.layout.width || layout?.height != frame.layout.height {
+            guard rebuild(layout: frame.layout) else { return false }
+        }
+        guard let layout, !slots.isEmpty else { return false }
+
+        var slot = slots[nextSlot]
+        // Grow the payload buffer to the frame (+16-byte zeroed guard: the kernel's 64-bit
+        // sign-window load and eager plane-byte prefetch may read past the payload end —
+        // upstream pads its Vulkan buffer for exactly this).
+        let payloadBytes = frame.payload.count * 4
+        if slot.payload.length < payloadBytes + 16 {
+            guard
+                let grown = device.makeBuffer(
+                    length: max(64 * 1024, (payloadBytes + 16) * 2), options: .storageModeShared)
+            else { return false }
+            slot.payload = grown
+            slots[nextSlot] = slot
+        }
+        frame.offsets.withUnsafeBytes { src in
+            slot.offsets.contents().copyMemory(
+                from: src.baseAddress!, byteCount: min(src.count, slot.offsets.length))
+        }
+        frame.payload.withUnsafeBytes { src in
+            slot.payload.contents().copyMemory(from: src.baseAddress!, byteCount: src.count)
+        }
+        memset(slot.payload.contents() + payloadBytes, 0, 16)
+
+        guard let cmd = queue.makeCommandBuffer() else { return false }
+
+        // Stage 1: dequant — every (component, level, band) block grid in one concurrent
+        // encoder (each dispatch writes its own band layer; no intra-stage hazards, exactly
+        // like the barrier-free Vulkan dispatch loop).
+        guard let dequant = cmd.makeComputeCommandEncoder(dispatchType: .concurrent) else {
+            return false
+        }
+        dequant.label = "pyrowave dequant"
+        dequant.setComputePipelineState(dequantPipeline)
+        dequant.setBuffer(slot.offsets, offset: 0, index: 0)
+        dequant.setBuffer(slot.payload, offset: 0, index: 1)
+        for level in 0..<WaveletLayout.decompositionLevels {
+            for component in 0..<3 {
+                if level == 0 && component != 0 { continue } // 4:2:0
+                for band in (level == WaveletLayout.decompositionLevels - 1 ? 0 : 1)..<4 {
+                    let meta = layout.blockMeta[component][level][band]
+                    let w = layout.levelWidth(level)
+                    let h = layout.levelHeight(level)
+                    var regs = DequantRegisters(
+                        resolution: SIMD2(Int32(w), Int32(h)),
+                        outputLayer: Int32(band),
+                        blockOffset32x32: Int32(meta.offset),
+                        blockStride32x32: Int32(meta.stride))
+                    dequant.setTexture(coefficients[component][level], index: 0)
+                    dequant.setBytes(
+                        &regs, length: MemoryLayout<DequantRegisters>.stride, index: 2)
+                    dequant.dispatchThreadgroups(
+                        MTLSize(width: (w + 31) / 32, height: (h + 31) / 32, depth: 1),
+                        threadsPerThreadgroup: MTLSize(width: 128, height: 1, depth: 1))
+                }
+            }
+        }
+        dequant.endEncoding()
+
+        // Stage 2: iDWT, coarsest level in — one encoder per level; the encoder boundary is
+        // the write→sampled-read barrier chaining each level's LL into the next.
+        for inputLevel in stride(from: WaveletLayout.decompositionLevels - 1, through: 0, by: -1) {
+            guard let idwt = cmd.makeComputeCommandEncoder(dispatchType: .concurrent) else {
+                return false
+            }
+            idwt.label = "pyrowave idwt L\(inputLevel)"
+            idwt.setSamplerState(mirrorSampler, index: 0)
+            // Resolution rides TRANSPOSED (the kernel transposes on load and store).
+            let rx = layout.levelHeight(inputLevel)
+            let ry = layout.levelWidth(inputLevel)
+            var regs = IdwtRegisters(
+                resolution: SIMD2(Int32(rx), Int32(ry)),
+                invResolution: SIMD2(1.0 / Float(rx), 1.0 / Float(ry)))
+            idwt.setBytes(&regs, length: MemoryLayout<IdwtRegisters>.stride, index: 0)
+            let grid = MTLSize(width: (rx + 15) / 16, height: (ry + 15) / 16, depth: 1)
+            let group = MTLSize(width: 64, height: 1, depth: 1)
+            if inputLevel == 0 {
+                // 4:2:0: the final full-res pass is luma only (chroma finished at level 1).
+                idwt.setComputePipelineState(idwtShiftPipeline)
+                idwt.setTexture(coefficients[0][0], index: 0)
+                idwt.setTexture(slot.y, index: 1)
+                idwt.dispatchThreadgroups(grid, threadsPerThreadgroup: group)
+            } else {
+                for component in 0..<3 {
+                    idwt.setTexture(coefficients[component][inputLevel], index: 0)
+                    if component != 0 && inputLevel == 1 {
+                        // 4:2:0 chroma emits its final half-res plane one level early.
+                        idwt.setComputePipelineState(idwtShiftPipeline)
+                        idwt.setTexture(component == 1 ? slot.cb : slot.cr, index: 1)
+                    } else {
+                        idwt.setComputePipelineState(idwtPipeline)
+                        idwt.setTexture(llViews[component][inputLevel - 1], index: 1)
+                    }
+                    idwt.dispatchThreadgroups(grid, threadsPerThreadgroup: group)
+                }
+            }
+            idwt.endEncoding()
+        }
+
+        let planes = WaveletPlanes(
+            y: slot.y, cb: slot.cb, cr: slot.cr,
+            csc: CscRows.rows(frame.cscSignal, depth: 8, msbPacked: false))
+        cmd.addCompletedHandler { buffer in
+            completion(buffer.error == nil ? planes : nil)
+        }
+        cmd.commit()
+        nextSlot = (nextSlot + 1) % Self.ringDepth
+        return true
+    }
+
+    /// (Re)allocate every size-dependent resource for `layout`'s geometry. Also the mid-stream
+    /// resize path: a Reconfigure shows up here as new SOF dims.
+    private func rebuild(layout newLayout: WaveletLayout) -> Bool {
+        waveletLog.info(
+            "pyrowave: building decoder \(newLayout.width)x\(newLayout.height) (aligned \(newLayout.alignedWidth)x\(newLayout.alignedHeight), \(newLayout.blockCount32) blocks)")
+        var coeff: [[MTLTexture]] = []
+        var lls: [[MTLTexture]] = []
+        for component in 0..<3 {
+            var perLevel: [MTLTexture] = []
+            var perLevelLL: [MTLTexture] = []
+            for level in 0..<WaveletLayout.decompositionLevels {
+                let desc = MTLTextureDescriptor()
+                desc.textureType = .type2DArray
+                desc.arrayLength = 4
+                // Upstream precision 1: fp16 storage for the two finest levels, fp32 for the
+                // coarse levels whose values feed every later reconstruction step.
+                desc.pixelFormat = level < 2 ? .r16Float : .r32Float
+                desc.width = newLayout.levelWidth(level)
+                desc.height = newLayout.levelHeight(level)
+                desc.usage = [.shaderRead, .shaderWrite]
+                desc.storageMode = .private
+                guard let tex = device.makeTexture(descriptor: desc) else { return false }
+                tex.label = "pyrowave coeff c\(component) L\(level)"
+                guard
+                    let ll = tex.makeTextureView(
+                        pixelFormat: desc.pixelFormat, textureType: .type2D,
+                        levels: 0..<1, slices: 0..<1)
+                else { return false }
+                ll.label = "pyrowave LL c\(component) L\(level)"
+                perLevel.append(tex)
+                perLevelLL.append(ll)
+            }
+            coeff.append(perLevel)
+            lls.append(perLevelLL)
+        }
+
+        var newSlots: [Slot] = []
+        for i in 0..<Self.ringDepth {
+            let plane = { (w: Int, h: Int, name: String) -> MTLTexture? in
+                let desc = MTLTextureDescriptor.texture2DDescriptor(
+                    pixelFormat: .r8Unorm, width: w, height: h, mipmapped: false)
+                desc.usage = [.shaderRead, .shaderWrite]
+                desc.storageMode = .private
+                let t = self.device.makeTexture(descriptor: desc)
+                t?.label = name
+                return t
+            }
+            guard
+                let y = plane(newLayout.width, newLayout.height, "pyrowave Y[\(i)]"),
+                let cb = plane(newLayout.width / 2, newLayout.height / 2, "pyrowave Cb[\(i)]"),
+                let cr = plane(newLayout.width / 2, newLayout.height / 2, "pyrowave Cr[\(i)]"),
+                let offsets = device.makeBuffer(
+                    length: max(newLayout.blockCount32 * 4, 4), options: .storageModeShared),
+                let payload = device.makeBuffer(length: 64 * 1024, options: .storageModeShared)
+            else { return false }
+            newSlots.append(Slot(y: y, cb: cb, cr: cr, offsets: offsets, payload: payload))
+        }
+
+        coefficients = coeff
+        llViews = lls
+        slots = newSlots
+        nextSlot = 0
+        layout = newLayout
+        return true
+    }
+
+    // MSL-side layouts (MetalWaveletShaders.swift) — keep in lockstep.
+    private struct DequantRegisters {
+        var resolution: SIMD2<Int32>
+        var outputLayer: Int32
+        var blockOffset32x32: Int32
+        var blockStride32x32: Int32
+    }
+
+    private struct IdwtRegisters {
+        var resolution: SIMD2<Int32>
+        var invResolution: SIMD2<Float>
+    }
+}
+#endif
@@ -0,0 +1,551 @@
+// PyroWave decode compute kernels — the Metal port of the vendored Vulkan shaders
+// (crates/pyrowave-sys/vendor/pyrowave/shaders/wavelet_dequant.comp + idwt.comp, upstream pin
+// 509e4f88, MIT © 2025 Hans-Kristian Arntzen). Runtime-compiled Swift strings per client
+// convention (no metallib build step — see GamepadChrome.swift's rationale); these are the
+// client's first compute pipelines.
+//
+// Port notes (design/pyrowave-codec-plan.md §4.7):
+// • Only the STORAGE_MODE 0 path exists: MSL device pointers replace the 8/16-bit-storage SSBO
+//   aliases; the texel-buffer (mode 1) and linear-image (mode 2) fallbacks are non-Apple IHV
+//   workarounds and are dropped, as is the fragment-iDWT path (Mali/Adreno only).
+// • Subgroup ops map 1:1: subgroupInclusiveAdd → simd_prefix_inclusive_sum, and the fixed
+//   32-wide Apple simdgroups take the GLSL's `SubgroupSize <= 32` scan branch; the shuffle-up
+//   and LDS fallbacks for exotic wave sizes are dead code here. The dequant kernel needs the
+//   16 header lanes inside ONE simdgroup — MetalWaveletDecoder's probe enforces
+//   threadExecutionWidth >= 16.
+// • Precision matches upstream's desktop default (PYROWAVE_PRECISION=1): float arithmetic,
+//   half2 threadgroup storage; the coefficient textures are R16Float for DWT levels 0–1 and
+//   R32Float for levels 2–4 (the low-res levels feed long reconstruction chains — upstream
+//   keeps them fp32 for exactly that reason).
+// • The gather + mirrored-repeat addressing in idwt is the precision-sensitive spot (upstream
+//   fought a Mali compiler bug there); the golden-frame PSNR fixtures are the guard.
+
+import Foundation
+
+let waveletShaderSource = """
+#include <metal_stdlib>
+using namespace metal;
+
+// ---------------------------------------------------------------------------------------------
+// Shared helpers (dwt_swizzle.h / constants.h / dwt_quant_scale.h)
+// ---------------------------------------------------------------------------------------------
+
+static inline int2 unswizzle8x8(uint index)
+{
+    uint y = extract_bits(index, 0, 1);
+    uint x = extract_bits(index, 1, 2);
+    y |= extract_bits(index, 3, 2) << 1;
+    x |= extract_bits(index, 5, 1) << 2;
+    return int2(int(x), int(y));
+}
+
+// GLSL bitfieldExtract(x, 0, n) where n may be 0; MSL extract_bits(bits=0) is not guaranteed
+// to return 0, so mask explicitly.
+static inline uint mask_lo(uint x, int n)
+{
+    return (n <= 0) ? 0u : (x & (0xffffffffu >> (32 - n)));
+}
+
+// pyrowave_common.hpp decode_quant: custom FP formulation, MaxScaleExp = 4.
+static inline float decode_quant(uint quant_code)
+{
+    int e = 4 - int(quant_code >> 3);
+    int m = int(quant_code) & 0x7;
+    return (1.0f / (8.0f * 1024.0f * 1024.0f)) * float((8 + m) * (1 << (20 + e)));
+}
+
+// dwt_quant_scale.h: per-8x8 quant scale, min 0.25, max ~2.2.
+static inline float decode_quant_scale(uint code)
+{
+    return float(code) / 8.0f + 0.25f;
+}
+
+// constants.h
+constant int QUANT_SCALE_OFFSET = 20;
+constant int QUANT_SCALE_BITS = 4;
+
+// ---------------------------------------------------------------------------------------------
+// wavelet_dequant — one 128-thread threadgroup decodes one 32x32 coefficient block
+// ---------------------------------------------------------------------------------------------
+
+struct DequantRegisters {
+    int2 resolution;
+    int output_layer;
+    int block_offset_32x32;
+    int block_stride_32x32;
+};
+
+struct DecodedPair { float4 col0; float4 col1; }; // GLSL mat2x4: m[j][i] -> colJ[i]
+
+// Bit-plane magnitude decode for one thread's 4x2 coefficient group (decode_payload in the
+// GLSL). `code_word` is the 8x8 block's 16-bit control word (2 bits of extra planes per 4x2
+// group), `q_bits` the base plane count, `offset` the block's plane-payload start byte,
+// `block_index` this thread's group (0..7). Nonzero magnitudes get the +0.5 deadzone
+// reconstruction bias.
+static DecodedPair decode_payload(const device uchar *payload_u8,
+                                  uint code_word, uint q_bits, uint offset, uint block_index)
+{
+    DecodedPair m;
+    m.col0 = float4(0.0f);
+    m.col1 = float4(0.0f);
+    if (code_word == 0)
+        return m;
+
+    int bit_offset = 2 * int(block_index);
+
+    uint lsbs = code_word & 0x5555u;
+    uint msbs = code_word & 0xaaaau;
+    uint msbs_shift = msbs >> 1;
+    msbs |= msbs_shift;
+
+    uint byte_offset =
+        popcount(mask_lo(lsbs, bit_offset)) +
+        popcount(mask_lo(msbs, bit_offset)) +
+        q_bits * block_index + offset;
+
+    uint payload = uint(payload_u8[byte_offset]);
+
+    uint local_control_word = extract_bits(code_word, uint(bit_offset), 2);
+    int decoded_abs[8] = {0, 0, 0, 0, 0, 0, 0, 0};
+    int plane_iterations = int(q_bits + local_control_word);
+
+    for (int q = plane_iterations - 1; q >= 0; q--)
+    {
+        for (int b = 0; b < 8; b++)
+        {
+            int decoded = int(extract_bits(payload, uint(b), 1));
+            decoded_abs[b] = insert_bits(decoded_abs[b], decoded, uint(q), 1);
+        }
+        byte_offset++;
+        payload = uint(payload_u8[byte_offset]);
+    }
+
+    for (int i = 0; i < 4; i++)
+    {
+        for (int j = 0; j < 2; j++)
+        {
+            float v = float(decoded_abs[i * 2 + j]);
+            if (v != 0.0f)
+                v += 0.5f;
+            if (j == 0) m.col0[i] = v; else m.col1[i] = v;
+        }
+    }
+    return m;
+}
+
+kernel void wavelet_dequant(
+    texture2d_array<float, access::write> uDequantImg [[texture(0)]],
+    const device uint *payload_offsets [[buffer(0)]],
+    const device uint *payload_u32 [[buffer(1)]],
+    constant DequantRegisters &registers [[buffer(2)]],
+    uint3 wg_id [[threadgroup_position_in_grid]],
+    uint local_index [[thread_index_in_threadgroup]],
+    uint simd_lane [[thread_index_in_simdgroup]],
+    uint simd_group [[simdgroup_index_in_threadgroup]],
+    uint simd_size [[threads_per_simdgroup]])
+{
+    // STORAGE_MODE 0's three aliased SSBO views over one buffer, as typed pointers.
+    const device ushort *payload_u16 = reinterpret_cast<const device ushort *>(payload_u32);
+    const device uchar *payload_u8 = reinterpret_cast<const device uchar *>(payload_u32);
+
+    threadgroup uint shared_sign_offset;
+    threadgroup uint shared_plane_byte_offsets[16];
+    threadgroup uint shared_sign_scan[128 / 4];
+
+    int block_index_32x32 = int(uint(registers.block_offset_32x32) +
+        wg_id.y * uint(registers.block_stride_32x32) +
+        wg_id.x);
+
+    uint block_local_index = extract_bits(local_index, 0, 3);
+    uint block_x = extract_bits(local_index, 3, 2);
+    uint block_y = extract_bits(local_index, 5, 2);
+    uint linear_block = block_y * 4 + block_x;
+
+    // Each thread individually decodes 8 values (a 4x2 group of its 8x8 block).
+    int2 local_coord = unswizzle8x8(block_local_index << 3);
+
+    int2 coord = int2(wg_id.xy) * 32;
+    coord += 8 * int2(int(block_x), int(block_y));
+    coord += local_coord;
+
+    uint offset_u32 = payload_offsets[block_index_32x32];
+
+    // Missing / lost block: zero coefficients (this is how a partial frame's holes decode).
+    if (offset_u32 == ~0u)
+    {
+        for (int j = 0; j < 2; j++)
+            for (int i = 0; i < 4; i++)
+                uDequantImg.write(float4(0.0f), uint2(coord + int2(i, j)), uint(registers.output_layer));
+        return;
+    }
+
+    uint ballot = payload_u32[offset_u32] & 0xffffu;
+    uint q_code = payload_u32[offset_u32 + 1] & 0xffu;
+
+    // Threads 0..15 (one per 8x8 block, all inside simdgroup 0) prefix-scan the per-block
+    // plane-payload byte costs into shared_plane_byte_offsets, and lane 15 records where the
+    // sign bitstream starts.
+    if (local_index < 16)
+    {
+        uint control_word = 0;
+        uint q_bits = 0;
+
+        if (extract_bits(ballot, local_index, 1) != 0)
+        {
+            uint local_code_offset = popcount(mask_lo(ballot, int(local_index)));
+            control_word = uint(payload_u16[offset_u32 * 2 + 4 + local_code_offset]);
+            q_bits = uint(payload_u8[offset_u32 * 4 + 8 + popcount(ballot) * 2 + local_code_offset]) & 0xfu;
+        }
+
+        uint lsbs = control_word & 0x5555u;
+        uint msbs = control_word & 0xaaaau;
+        uint msbs_shift = msbs >> 1;
+        msbs |= msbs_shift;
+        uint byte_cost = popcount(lsbs) + popcount(msbs) + q_bits * 8;
+
+        uint byte_scan = offset_u32 * 4 + 8 + 3 * popcount(ballot) + simd_prefix_inclusive_sum(byte_cost);
+        if (local_index == 15)
+            shared_sign_offset = 8 * byte_scan;
+        shared_plane_byte_offsets[local_index] = byte_scan - byte_cost;
+    }
+
+    threadgroup_barrier(mem_flags::mem_threadgroup);
+
+    DecodedPair v;
+    int significant_count;
+
+    if (extract_bits(ballot, linear_block, 1) != 0)
+    {
+        uint local_code_offset = popcount(mask_lo(ballot, int(linear_block)));
+
+        uint control_word = uint(payload_u16[offset_u32 * 2 + 4 + local_code_offset]);
+        uint control_word2 = uint(payload_u8[offset_u32 * 4 + 8 + popcount(ballot) * 2 + local_code_offset]);
+
+        v = decode_payload(payload_u8, control_word, control_word2 & 0xfu,
+            shared_plane_byte_offsets[linear_block], block_local_index);
+
+        significant_count = 0;
+        for (int j = 0; j < 2; j++)
+            for (int i = 0; i < 4; i++)
+                significant_count += int(((j == 0) ? v.col0[i] : v.col1[i]) != 0.0f);
+
+        float q = decode_quant(q_code);
+        float inv_scale = q * decode_quant_scale(extract_bits(control_word2, uint(QUANT_SCALE_OFFSET - 16), uint(QUANT_SCALE_BITS)));
+
+        v.col0 *= inv_scale;
+        v.col1 *= inv_scale;
+    }
+    else
+    {
+        v.col0 = float4(0.0f);
+        v.col1 = float4(0.0f);
+        significant_count = 0;
+    }
+
+    // Cross-threadgroup scan of significant-coefficient counts → each thread's first sign-bit
+    // position. Apple simdgroups are >= 16 wide, so this is the GLSL's `SubgroupSize <= 32`
+    // branch; the shuffle/LDS fallbacks are unnecessary.
+    int significant_scan = int(simd_prefix_inclusive_sum(uint(significant_count)));
+    if (simd_lane == simd_size - 1)
+        shared_sign_scan[simd_group] = uint(significant_scan);
+
+    threadgroup_barrier(mem_flags::mem_threadgroup);
+    uint num_simdgroups = (128 + simd_size - 1) / simd_size;
+    if (local_index < num_simdgroups)
+        shared_sign_scan[local_index] = simd_prefix_inclusive_sum(shared_sign_scan[local_index]);
+    threadgroup_barrier(mem_flags::mem_threadgroup);
+
+    uint sign_offset = shared_sign_offset + uint(significant_scan - significant_count);
+    if (simd_group != 0)
+        sign_offset += shared_sign_scan[simd_group - 1];
+
+    // Load 64 bits of sign stream and bit-align (may read one word past the payload — the
+    // buffer carries a 16-byte zeroed guard tail for exactly this).
+    uint sign_word = payload_u32[sign_offset / 32 + 0];
+    uint sign_word_upper = payload_u32[sign_offset / 32 + 1];
+
+    uint masked_sign_offset = sign_offset & 31u;
+    if (masked_sign_offset != 0)
+    {
+        sign_word >>= masked_sign_offset;
+        sign_word |= sign_word_upper << (32 - masked_sign_offset);
+    }
+
+    int sign_counter = 0;
+
+    for (int i = 0; i < 4; i++)
+    {
+        for (int j = 0; j < 2; j++)
+        {
+            float val = (j == 0) ? v.col0[i] : v.col1[i];
+            if (val != 0.0f)
+            {
+                val *= 1.0f - 2.0f * float(extract_bits(sign_word, uint(sign_counter), 1));
+                sign_counter++;
+                if (j == 0) v.col0[i] = val; else v.col1[i] = val;
+            }
+        }
+    }
+
+    for (int j = 0; j < 2; j++)
+        for (int i = 0; i < 4; i++)
+            uDequantImg.write(float4((j == 0) ? v.col0[i] : v.col1[i]),
+                              uint2(coord + int2(i, j)), uint(registers.output_layer));
+}
+
+// ---------------------------------------------------------------------------------------------
+// idwt — inverse CDF 9/7; one 64-thread threadgroup reconstructs one 32x32 output tile from the
+// four half-res band layers (LL/HL/LH/HH), with a 4-sample mirror apron. The caller passes the
+// band-image resolution TRANSPOSED (the kernel transposes on load and store, so one kernel does
+// both the horizontal and vertical passes).
+// ---------------------------------------------------------------------------------------------
+
+constant bool DCShift [[function_constant(0)]];
+
+struct IdwtRegisters {
+    int2 resolution;
+    float2 inv_resolution;
+};
+
+constant int APRON = 4;
+constant int APRON_HALF = APRON / 2;
+constant int BLOCK_SIZE = 32;
+constant int BLOCK_SIZE_HALF = BLOCK_SIZE >> 1;
+
+// CDF 9/7 lifting constants (dwt_common.h).
+constant float ALPHA = -1.586134342059924f;
+constant float BETA = -0.052980118572961f;
+constant float GAMMA = 0.882911075530934f;
+constant float DELTA = 0.443506852043971f;
+constant float K = 1.230174104914001f;
+constant float inv_K = 1.0f / 1.230174104914001f;
+
+constant int SHARED_ROWS = (BLOCK_SIZE + 2 * APRON) / 2;      // 20
+constant int SHARED_COLS = (BLOCK_SIZE + 2 * APRON) + 1;      // 41 (+1 avoids bank conflicts)
+
+static inline float2 load_shared(threadgroup half2 (&blk)[SHARED_ROWS][SHARED_COLS], int y, int x)
+{
+    return float2(blk[y][x]);
+}
+
+static inline void store_shared(threadgroup half2 (&blk)[SHARED_ROWS][SHARED_COLS], int y, int x, float2 v)
+{
+    blk[y][x] = half2(v);
+}
+
+// Even/odd-phase coordinate nudge so mirrored-repeat gather reproduces JPEG2000 whole-sample
+// mirroring at the image borders, then transpose (uv.yx) on load.
+static inline float2 generate_mirror_uv(int2 coord, bool even_x, bool even_y,
+                                        int2 resolution, float2 inv_resolution)
+{
+    coord.x -= int(even_x && coord.x < 0);
+    coord.y -= int(even_y && coord.y < 0);
+    coord += 1;
+    coord.x += int(!even_x && coord.x >= resolution.x);
+    coord.y += int(!even_y && coord.y >= resolution.y);
+    float2 uv = float2(coord) * inv_resolution;
+    return uv.yx;
+}
+
+static inline void write_shared_4x4(threadgroup half2 (&blk)[SHARED_ROWS][SHARED_COLS],
+                                    int2 coord, float4 t0, float4 t1, float4 t2, float4 t3)
+{
+    store_shared(blk, coord.y + 0, 2 * coord.x + 0, float2(t0.x, t2.x));
+    store_shared(blk, coord.y + 0, 2 * coord.x + 1, float2(t1.x, t3.x));
+    store_shared(blk, coord.y + 0, 2 * coord.x + 2, float2(t0.y, t2.y));
+    store_shared(blk, coord.y + 0, 2 * coord.x + 3, float2(t1.y, t3.y));
+    store_shared(blk, coord.y + 1, 2 * coord.x + 0, float2(t0.z, t2.z));
+    store_shared(blk, coord.y + 1, 2 * coord.x + 1, float2(t1.z, t3.z));
+    store_shared(blk, coord.y + 1, 2 * coord.x + 2, float2(t0.w, t2.w));
+    store_shared(blk, coord.y + 1, 2 * coord.x + 3, float2(t1.w, t3.w));
+}
+
+// textureGather(...).wxzy — Metal's gather returns the same counter-clockwise-from-(i0,j1)
+// component order as Vulkan, so the reorder is identical.
+static inline float4 gather_layer(texture2d_array<float, access::sample> tex, sampler smp,
+                                  float2 uv, uint layer)
+{
+    float4 g = tex.gather(smp, uv, layer);
+    return float4(g.w, g.x, g.z, g.y);
+}
+
+static void load_image_with_apron(texture2d_array<float, access::sample> tex, sampler smp,
+                                  threadgroup half2 (&blk)[SHARED_ROWS][SHARED_COLS],
+                                  uint local_index, uint2 wg_id,
+                                  int2 resolution, float2 inv_resolution)
+{
+    int2 base_coord = int2(wg_id) * BLOCK_SIZE_HALF - APRON_HALF;
+    int2 local_coord0 = 2 * unswizzle8x8(local_index);
+    int2 coord0 = base_coord + local_coord0;
+
+    // Band layers gathered in 0/2/1/3 order (LL/LH/HL/HH interleave for the 2x2 scatter).
+    float4 texels0 = gather_layer(tex, smp, generate_mirror_uv(coord0, true, true, resolution, inv_resolution), 0);
+    float4 texels1 = gather_layer(tex, smp, generate_mirror_uv(coord0, false, true, resolution, inv_resolution), 2);
+    float4 texels2 = gather_layer(tex, smp, generate_mirror_uv(coord0, true, false, resolution, inv_resolution), 1);
+    float4 texels3 = gather_layer(tex, smp, generate_mirror_uv(coord0, false, false, resolution, inv_resolution), 3);
+    write_shared_4x4(blk, local_coord0, texels0, texels1, texels2, texels3);
+
+    int2 local_coord_horiz = int2(BLOCK_SIZE_HALF + 2 * int(local_index % 2u), 2 * int(local_index / 2u));
+    if (local_coord_horiz.y < BLOCK_SIZE_HALF + 2 * APRON_HALF)
+    {
+        int2 c = base_coord + local_coord_horiz;
+        texels0 = gather_layer(tex, smp, generate_mirror_uv(c, true, true, resolution, inv_resolution), 0);
+        texels1 = gather_layer(tex, smp, generate_mirror_uv(c, false, true, resolution, inv_resolution), 2);
+        texels2 = gather_layer(tex, smp, generate_mirror_uv(c, true, false, resolution, inv_resolution), 1);
+        texels3 = gather_layer(tex, smp, generate_mirror_uv(c, false, false, resolution, inv_resolution), 3);
+        write_shared_4x4(blk, local_coord_horiz, texels0, texels1, texels2, texels3);
+    }
+
+    int2 local_coord_vert = local_coord_horiz.yx;
+    if (local_coord_vert.x < BLOCK_SIZE_HALF)
+    {
+        int2 c = base_coord + local_coord_vert;
+        texels0 = gather_layer(tex, smp, generate_mirror_uv(c, true, true, resolution, inv_resolution), 0);
+        texels1 = gather_layer(tex, smp, generate_mirror_uv(c, false, true, resolution, inv_resolution), 2);
+        texels2 = gather_layer(tex, smp, generate_mirror_uv(c, true, false, resolution, inv_resolution), 1);
+        texels3 = gather_layer(tex, smp, generate_mirror_uv(c, false, false, resolution, inv_resolution), 3);
+        write_shared_4x4(blk, local_coord_vert, texels0, texels1, texels2, texels3);
+    }
+
+    threadgroup_barrier(mem_flags::mem_threadgroup);
+}
+
+static void inverse_transform8x2(threadgroup half2 (&blk)[SHARED_ROWS][SHARED_COLS], uint local_index)
+{
+    const int SIZE = 8;
+    const int PADDED_SIZE = SIZE + 2 * APRON;
+    const int PADDED_SIZE_HALF = PADDED_SIZE / 2;
+    float2 values[PADDED_SIZE];
+
+    int2 local_coord = int2(8 * int(local_index % 4u), int(local_index / 4u));
+
+    for (int i = 0; i < PADDED_SIZE; i += 2)
+    {
+        float2 v0 = load_shared(blk, local_coord.y, local_coord.x + i + 0);
+        float2 v1 = load_shared(blk, local_coord.y, local_coord.x + i + 1);
+        values[i + 0] = v0 * K;
+        values[i + 1] = v1 * inv_K;
+    }
+
+    // CDF 9/7 inverse lifting steps.
+    for (int i = 2; i < PADDED_SIZE - 1; i += 2)
+        values[i] -= DELTA * (values[i - 1] + values[i + 1]);
+    for (int i = 3; i < PADDED_SIZE - 2; i += 2)
+        values[i] -= GAMMA * (values[i - 1] + values[i + 1]);
+    for (int i = 4; i < PADDED_SIZE - 3; i += 2)
+        values[i] -= BETA * (values[i - 1] + values[i + 1]);
+    for (int i = 5; i < PADDED_SIZE - 4; i += 2)
+        values[i] -= ALPHA * (values[i - 1] + values[i + 1]);
+
+    // Avoid WAR hazard.
+    threadgroup_barrier(mem_flags::mem_threadgroup);
+
+    for (int i = APRON_HALF; i < PADDED_SIZE_HALF - APRON_HALF; i++)
+    {
+        float2 a = values[2 * i + 0];
+        float2 b = values[2 * i + 1];
+
+        // Transpose the 2x2 block, transpose write.
+        float2 t0 = float2(a.x, b.x);
+        float2 t1 = float2(a.y, b.y);
+
+        int y_coord = (local_coord.x >> 1) + (i - APRON_HALF);
+        store_shared(blk, y_coord, 2 * local_coord.y + 0, t0);
+        store_shared(blk, y_coord, 2 * local_coord.y + 1, t1);
+    }
+}
+
+static void inverse_transform4x2(threadgroup half2 (&blk)[SHARED_ROWS][SHARED_COLS],
+                                 uint local_index, bool active_lane, int y_offset)
+{
+    const int SIZE = 4;
+    const int PADDED_SIZE = SIZE + 2 * APRON;
+    const int PADDED_SIZE_HALF = PADDED_SIZE / 2;
+    float2 values[PADDED_SIZE];
+
+    int2 local_coord = int2(4 * int(local_index % 8u), int(local_index / 8u) + y_offset);
+
+    if (active_lane)
+    {
+        for (int i = 0; i < PADDED_SIZE; i += 2)
+        {
+            float2 v0 = load_shared(blk, local_coord.y, local_coord.x + i + 0);
+            float2 v1 = load_shared(blk, local_coord.y, local_coord.x + i + 1);
+            values[i + 0] = v0 * K;
+            values[i + 1] = v1 * inv_K;
+        }
+
+        for (int i = 2; i < PADDED_SIZE - 1; i += 2)
+            values[i] -= DELTA * (values[i - 1] + values[i + 1]);
+        for (int i = 3; i < PADDED_SIZE - 2; i += 2)
+            values[i] -= GAMMA * (values[i - 1] + values[i + 1]);
+        for (int i = 4; i < PADDED_SIZE - 3; i += 2)
+            values[i] -= BETA * (values[i - 1] + values[i + 1]);
+        for (int i = 5; i < PADDED_SIZE - 4; i += 2)
+            values[i] -= ALPHA * (values[i - 1] + values[i + 1]);
+    }
+
+    threadgroup_barrier(mem_flags::mem_threadgroup);
+
+    if (active_lane)
+    {
+        for (int i = APRON_HALF; i < PADDED_SIZE_HALF - APRON_HALF; i++)
+        {
+            float2 a = values[2 * i + 0];
+            float2 b = values[2 * i + 1];
+
+            float2 t0 = float2(a.x, b.x);
+            float2 t1 = float2(a.y, b.y);
+
+            int y_coord = (local_coord.x >> 1) + (i - APRON_HALF);
+            store_shared(blk, y_coord, 2 * local_coord.y + 0, t0);
+            store_shared(blk, y_coord, 2 * local_coord.y + 1, t1);
+        }
+    }
+}
+
+kernel void idwt(
+    texture2d_array<float, access::sample> uTexture [[texture(0)]],
+    texture2d<float, access::write> uOutput [[texture(1)]],
+    sampler uSampler [[sampler(0)]],
+    constant IdwtRegisters &registers [[buffer(0)]],
+    uint3 wg_id [[threadgroup_position_in_grid]],
+    uint local_index [[thread_index_in_threadgroup]])
+{
+    threadgroup half2 shared_block[SHARED_ROWS][SHARED_COLS];
+
+    load_image_with_apron(uTexture, uSampler, shared_block, local_index, wg_id.xy,
+                          registers.resolution, registers.inv_resolution);
+
+    // Horizontal transform.
+    inverse_transform8x2(shared_block, local_index);
+
+    // Also need to transform the apron.
+    inverse_transform4x2(shared_block, local_index, local_index < 32, BLOCK_SIZE_HALF);
+
+    threadgroup_barrier(mem_flags::mem_threadgroup);
+
+    // Vertical transform.
+    inverse_transform8x2(shared_block, local_index);
+
+    threadgroup_barrier(mem_flags::mem_threadgroup);
+
+    int2 local_coord = unswizzle8x8(local_index);
+
+    for (int y = local_coord.y; y < BLOCK_SIZE_HALF; y += 8)
+    {
+        for (int x = local_coord.x; x < BLOCK_SIZE; x += 8)
+        {
+            float2 v = load_shared(shared_block, y, x);
+            if (DCShift)
+                v += 0.5f;
+            // Transposed store (wg_id.yx) — undoes the transpose-on-load; out-of-range writes
+            // at the aligned-size overhang are dropped by Metal (matching the Vulkan behavior).
+            int2 out0 = int2(2 * y + 0, x) + BLOCK_SIZE * int2(int(wg_id.y), int(wg_id.x));
+            int2 out1 = int2(2 * y + 1, x) + BLOCK_SIZE * int2(int(wg_id.y), int(wg_id.x));
+            uOutput.write(float4(v.x), uint2(out0));
+            uOutput.write(float4(v.y), uint2(out1));
+        }
+    }
+}
+"""
@@ -9,6 +9,7 @@
 #if canImport(Metal) && canImport(QuartzCore)
 import AVFoundation
 import Foundation
+import PunktfunkShared
 import QuartzCore
 #if os(tvOS)
 import UIKit
@@ -37,6 +37,8 @@
 #if canImport(Metal) && canImport(QuartzCore)
 import AVFoundation
 import Foundation
+import Metal
+import PunktfunkShared
 import QuartzCore

 /// PUNKTFUNK_PRESENT_DEBUG=1: the render thread prints a once-per-second line with the decode
@@ -249,6 +251,28 @@ private final class PresentDebugStats: @unchecked Sendable {
    }
 }

+/// Bridges the VideoToolbox decode-completion callback to the core Automatic-bitrate controller's
+/// decode signal. Created as a pipeline property so the decoder's `onDecoded` callback (built in
+/// `init`, before the connection exists) can capture it, then `start` binds the live connection +
+/// the arming flag once known — the same "reference captured in init, configured in start" shape as
+/// `recovery`/`gate`. `record` runs on VideoToolbox's callback thread; `bind` runs once on the main
+/// thread before the pump feeds the first AU, so the plain fields are safe (set-once, then read).
+private final class DecodeReport: @unchecked Sendable {
+    private weak var connection: PunktfunkConnection?
+    private var enabled = false
+    func bind(_ connection: PunktfunkConnection) {
+        self.connection = connection
+        self.enabled = connection.wantsDecodeLatency()
+    }
+    /// Report received→decoded for one frame, in µs. Both stamps are client `CLOCK_REALTIME`
+    /// (no skew). Skips when the controller isn't armed, so it's free to call on every decode.
+    func record(receivedNs: Int64, decodedNs: Int64) {
+        guard enabled, let c = connection else { return }
+        let us = (decodedNs - receivedNs) / 1000
+        if us > 0 { c.reportDecodeUs(UInt32(min(us, Int64(UInt32.max)))) }
+    }
+}
+
 public final class Stage2Pipeline {
    private let ring = ReadyRing()
    private let presenter: MetalVideoPresenter
@@ -257,8 +281,12 @@ public final class Stage2Pipeline {
    /// the pipeline's lifetime; SessionPresenter resolves it per session (see PresentPacing).
    private let pacing: PresentPacing
    private let endToEndMeter: LatencyMeter?
+    private let decodeMeter: LatencyMeter?
    private let displayMeter: LatencyMeter?
    private let recovery = KeyframeRecovery()
+    /// Feeds the core Automatic-bitrate controller's decode signal from the decode callback; `start`
+    /// binds the live connection + arming flag (see DecodeReport).
+    private let decodeReport = DecodeReport()
    /// 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).
@@ -306,11 +334,13 @@ public final class Stage2Pipeline {
        self.presenter = presenter
        self.pacing = pacing
        self.endToEndMeter = endToEndMeter
+        self.decodeMeter = decodeMeter
        self.displayMeter = displayMeter
        let ring = ring
        let recovery = recovery
        let renderSignal = renderSignal
        let gate = gate
+        let decodeReport = decodeReport
        self.decoder = VideoDecoder(
            onDecoded: { frame in
                // Decode stage = received→decoded, both client CLOCK_REALTIME (offset 0 — no
@@ -318,6 +348,10 @@ public final class Stage2Pipeline {
                // including ones the re-anchor gate withholds or the newest-wins ring drops.
                decodeMeter?.record(
                    ptsNs: UInt64(frame.receivedNs), atNs: frame.decodedNs, offsetNs: 0)
+                // Same interval, reported to the core bitrate controller so Automatic caps at this
+                // device's real decode limit instead of the network link ceiling. Every decoded
+                // frame (not just presented ones), so a newest-wins drop can't hide the backlog.
+                decodeReport.record(receivedNs: frame.receivedNs, decodedNs: frame.decodedNs)
                // 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
@@ -346,6 +380,7 @@ public final class Stage2Pipeline {
    ) {
        offsetNs = connection.clockOffsetNs
        recovery.bind(connection) // arm host-keyframe recovery for this session
+        decodeReport.bind(connection) // arm the Automatic-bitrate decode signal 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)

@@ -362,7 +397,21 @@ public final class Stage2Pipeline {
        let presenter = presenter
        let pumpStopped = pumpStopped
        let reanchorGate = gate
-        let thread = Thread {
+        // PyroWave rides a different decode half: no CMFormatDescription/VideoToolbox machinery
+        // (a wavelet AU has no parameter sets), no keyframe recovery or re-anchor freeze (the
+        // stream is all-intra and Phase 4's partial delivery WANTS lossy frames on glass as
+        // localized blur, not a freeze). The ready ring, render thread, pacing and meters are
+        // shared unchanged.
+        let thread: Thread
+        if connection.videoCodec == .pyrowave {
+            thread = Self.makePyroWavePump(
+                connection: connection, token: token, pumpStopped: pumpStopped,
+                ring: ring, renderSignal: renderSignal,
+                device: presenter.metalDevice, queue: presenter.metalQueue,
+                decodeMeter: decodeMeter,
+                onFrame: onFrame, onSessionEnd: onSessionEnd, onDecodedSize: onDecodedSize)
+        } else {
+            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
@@ -383,6 +432,15 @@ public final class Stage2Pipeline {
            while alive, !token.isStopped {
                alive = autoreleasepool { () -> Bool in
                do {
+                    // Background keep-alive: drain one AU (flow control + host pacing) and discard it
+                    // BEFORE any VideoToolbox decode or Metal render — no GPU work off-screen. The
+                    // decoder session is left intact; exitBackground requests a fresh IDR and the
+                    // re-anchor gate arms on the resumed frame-index gap so concealed frames are
+                    // withheld until it lands.
+                    if connection.isVideoDropped {
+                        _ = try connection.nextAU(timeoutMs: 100)
+                        return true
+                    }
                    // Loss recovery (the primary path). The reassembler drops unrecoverable AUs and the
                    // decoder conceals the reference-missing deltas — often WITHOUT an error callback —
                    // so key off the drop count climbing, then keep asking (awaitingIDR) until a fresh
@@ -445,6 +503,7 @@ public final class Stage2Pipeline {
                }
                }
            }
+            }
        }
        thread.name = "punktfunk-stage2-pump"
        thread.qualityOfService = .userInteractive
@@ -504,9 +563,7 @@ public final class Stage2Pipeline {
                let presentAt = vsyncEnabled
                    ? vsyncClock.nextVsync(after: CACurrentMediaTime()) : nil
                let renderStarted = CACurrentMediaTime()
-                let rendered = presenter.render(
-                    frame.pixelBuffer, isHDR: frame.isHDR, presentAtMediaTime: presentAt
-                ) { presentedNs in
+                let onGlass: (Int64?) -> Void = { presentedNs in
                    // Stage-3: the flip reached glass (or was dropped) — free the present slot,
                    // then re-signal so the freshest waiting ring frame goes out immediately.
                    if let gate {
@@ -525,6 +582,18 @@ public final class Stage2Pipeline {
                    displayMeter?.record(ptsNs: UInt64(frame.decodedNs), atNs: atNs, offsetNs: 0)
                    debugStats?.presented(atNs: presentedNs)
                }
+                // One present tail, two decode sources: the VideoToolbox biplanar buffer or the
+                // PyroWave Metal planes — the ring, pacing and meters are agnostic to which.
+                let rendered: Bool
+                switch frame.image {
+                case .video(let pixelBuffer, let isHDR):
+                    rendered = presenter.render(
+                        pixelBuffer, isHDR: isHDR, presentAtMediaTime: presentAt,
+                        onPresented: onGlass)
+                case .planar(let planes):
+                    rendered = presenter.renderPlanar(
+                        planes, presentAtMediaTime: presentAt, onPresented: onGlass)
+                }
                debugStats?.renderReturned(
                    ok: rendered, tookMs: (CACurrentMediaTime() - renderStarted) * 1000)
                if !rendered {
@@ -592,6 +661,100 @@ public final class Stage2Pipeline {
        renderSignal.signal() // wake the render thread so it can observe the stop and exit
    }

+    /// The PyroWave pump: AUs go straight into the Metal wavelet decoder (no VideoToolbox, no
+    /// format descriptions), decoded planes ride the same ready ring / render thread. All-intra
+    /// stream, so none of the VT pump's recovery machinery applies: keyframe/RFI requests are
+    /// silenced host-side for this codec, and a lossy (partial-delivery) frame is MEANT to
+    /// present as localized blur — never a freeze. Static + capture-by-parameter for the same
+    /// reason the VT pump avoids capturing `self` (a missed stop must not leak a live pipeline).
+    private static func makePyroWavePump(
+        connection: PunktfunkConnection, token: StopFlag, pumpStopped: DispatchSemaphore,
+        ring: ReadyRing, renderSignal: DispatchSemaphore,
+        device: MTLDevice, queue: MTLCommandQueue,
+        decodeMeter: LatencyMeter?,
+        onFrame: (@Sendable (AccessUnit) -> Void)?,
+        onSessionEnd: (@Sendable () -> Void)?,
+        onDecodedSize: (@Sendable (Int, Int) -> Void)?
+    ) -> Thread {
+        // The chunk-aligned parse window = the session's negotiated shard payload (Welcome);
+        // the 64-byte floor mirrors the Rust client's guard against a nonsense value.
+        let windowSize = max(64, Int(connection.shardPayload))
+        return Thread {
+            defer { pumpStopped.signal() }
+            // Compiles the two compute kernels on the session's first frames' thread — ~tens of
+            // ms, once per session. Failure = this device can't run the negotiated codec (the
+            // advertisement probe should have prevented this); end the session cleanly.
+            guard let decoder = MetalWaveletDecoder(device: device, queue: queue) else {
+                if !token.isStopped { onSessionEnd?() }
+                return
+            }
+            // Newest decoded frame index — a late partial (the reassembler's 30 ms fuse can
+            // deliver one behind a newer complete frame) must not travel back in time.
+            var newestIndex: UInt32?
+            var lastDims: (w: Int, h: Int)?
+            var alive = true
+            while alive, !token.isStopped {
+                alive = autoreleasepool { () -> Bool in
+                    do {
+                        // Background keep-alive: drain + discard before the Metal wavelet decode
+                        // (PyroWave is all-intra, so the resumed frame heals on its own — no IDR
+                        // request needed, just no GPU work off-screen).
+                        if connection.isVideoDropped {
+                            _ = try connection.nextAU(timeoutMs: 100)
+                            return true
+                        }
+                        guard let au = try connection.nextAU(timeoutMs: 100) else { return true }
+                        onFrame?(au)
+                        if let newest = newestIndex,
+                           Int32(bitPattern: au.frameIndex &- newest) <= 0 {
+                            return true // stale (or duplicate) frame — skip
+                        }
+                        guard !token.isStopped else { return true }
+                        let chunkAligned =
+                            au.flags & PunktfunkConnection.userFlagChunkAligned != 0
+                        let ptsNs = au.ptsNs
+                        let receivedNs = au.receivedNs
+                        let flags = au.flags
+                        let submitted = decoder.decode(
+                            au: au.data, chunkAligned: chunkAligned, windowSize: windowSize
+                        ) { planes in
+                            // Metal completed-handler thread — stamp + enqueue, don't block
+                            // (the exact contract of the VT output callback).
+                            guard let planes else { return }
+                            var ts = timespec()
+                            clock_gettime(CLOCK_REALTIME, &ts)
+                            let decodedNs =
+                                Int64(ts.tv_sec) * 1_000_000_000 + Int64(ts.tv_nsec)
+                            decodeMeter?.record(
+                                ptsNs: UInt64(receivedNs), atNs: decodedNs, offsetNs: 0)
+                            ring.submit(
+                                ReadyFrame(
+                                    ptsNs: ptsNs, receivedNs: receivedNs, decodedNs: decodedNs,
+                                    image: .planar(planes), flags: flags))
+                            renderSignal.signal()
+                        }
+                        if submitted {
+                            newestIndex = au.frameIndex
+                            // Decoded-size changes come from the SOF dims (this is also how a
+                            // mid-stream Reconfigure lands here) — report like the VT pump.
+                            if let size = decoder.decodedSize,
+                               lastDims?.w != size.width || lastDims?.h != size.height {
+                                lastDims = (size.width, size.height)
+                                onDecodedSize?(size.width, size.height)
+                            }
+                        }
+                        // A dropped AU (malformed / SOF lost / too few blocks) is just skipped:
+                        // every PyroWave frame is independently decodable, the next one heals.
+                        return true
+                    } catch {
+                        if !token.isStopped { onSessionEnd?() }
+                        return false // session closed
+                    }
+                }
+            }
+        }
+    }
+
    /// Convert a `CADisplayLink.targetTimestamp` (CACurrentMediaTime basis) to a `CLOCK_REALTIME`
    /// nanosecond instant — the present clock the AU pts + skew offset live in. Projects to the target
    /// present time (when the frame is actually on glass), not the moment we drew.
@@ -63,6 +63,14 @@ final class StreamPump {
            while alive, !token.isStopped {
                alive = autoreleasepool { () -> Bool in
                do {
+                    // Background keep-alive: drain one AU to keep QUIC flow control + host pacing
+                    // healthy, then discard it BEFORE any decode/enqueue — no VideoToolbox/Metal work
+                    // off-screen. Skips all recovery/gate bookkeeping too; exitBackground requests a
+                    // fresh IDR and the re-anchor gate re-arms on the resumed frame-index gap.
+                    if connection.isVideoDropped {
+                        _ = try connection.nextAU(timeoutMs: 100)
+                        return true
+                    }
                    // Loss recovery (the primary path). Under the host's infinite GOP the only
                    // recovery keyframe is one we request. The reassembler drops unrecoverable AUs
                    // (framesDropped); the decoder then *conceals* the reference-missing deltas — a
@@ -12,7 +12,23 @@ import CoreVideo
 import Foundation
 import VideoToolbox

-/// One decoded frame waiting to be presented. Owns a retained `CVPixelBuffer` until shown.
+/// A decoded frame's pixels — which present path they take. VideoToolbox codecs deliver a
+/// biplanar `CVPixelBuffer` (NV12/P010/444v/x444); the PyroWave Metal decoder delivers three
+/// separate R8 plane textures straight off its compute pass (there is no CVPixelBuffer — the
+/// planes never leave the GPU).
+public enum ReadyImage: @unchecked Sendable {
+    /// 8-bit NV12 / 4:4:4 biplanar (SDR) or 10-bit P010 / x444 (HDR), Metal-compatible.
+    /// `isHDR` = the stream is BT.2020 PQ and the presenter must configure EDR output.
+    case video(CVPixelBuffer, isHDR: Bool)
+    #if canImport(Metal)
+    /// PyroWave planar output (Y full-res + Cb/Cr half-res, 8-bit SDR) with its precomputed
+    /// CSC rows — presented by `MetalVideoPresenter.renderPlanar`.
+    case planar(WaveletPlanes)
+    #endif
+}
+
+/// One decoded frame waiting to be presented. Owns its image (a retained `CVPixelBuffer`, or
+/// the PyroWave ring textures) until shown.
 public struct ReadyFrame: @unchecked Sendable {
    /// Host capture clock (the AU's pts), in nanoseconds.
    public let ptsNs: UInt64
@@ -22,15 +38,26 @@ public struct ReadyFrame: @unchecked Sendable {
    public let receivedNs: Int64
    /// Client `CLOCK_REALTIME` instant decode completed, in nanoseconds.
    public let decodedNs: Int64
-    /// The decoded image — 8-bit NV12 biplanar (SDR) or 10-bit P010 biplanar (HDR), Metal-compatible.
-    public let pixelBuffer: CVPixelBuffer
-    /// 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 decoded image and which present path it takes.
+    public let image: ReadyImage
    /// 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
+
+    /// The VideoToolbox path's buffer; nil for a PyroWave planar frame. (Kept as the accessor
+    /// the decode round-trip tests assert against.)
+    public var pixelBuffer: CVPixelBuffer? {
+        if case .video(let buffer, _) = image { return buffer }
+        return nil
+    }
+
+    /// Whether this frame presents on the HDR path. PyroWave planar frames are 8-bit SDR by
+    /// contract.
+    public var isHDR: Bool {
+        if case .video(_, let hdr) = image { return hdr }
+        return false
+    }
 }

 /// Per-frame context threaded through the VideoToolbox frame refcon: the AU's receipt instant (for
@@ -286,6 +313,6 @@ public final class VideoDecoder: @unchecked Sendable {
        onDecoded(
            ReadyFrame(
                ptsNs: ptsNs, receivedNs: receivedNs, decodedNs: decodedNs,
-                pixelBuffer: imageBuffer, isHDR: isHDR, flags: flags))
+                image: .video(imageBuffer, isHDR: isHDR), flags: flags))
    }
 }
@@ -19,6 +19,7 @@
 #if os(macOS)
 import AppKit
 import AVFoundation
+import PunktfunkShared
 import SwiftUI
 import os

@@ -35,6 +35,7 @@
 import AVFoundation
 import GameController
 import PunktfunkCore
+import PunktfunkShared
 import SwiftUI
 import UIKit
 import os
@@ -0,0 +1,23 @@
+// The App-Group foundation shared by the app and its extensions (Widgets / Live Activity).
+//
+// PunktfunkShared is deliberately dependency-free: it links NEITHER PunktfunkKit (which drags in
+// the Rust staticlib + presentation layer) NOR any Apple UI framework. A widget process gets ~30 MB,
+// so everything an extension needs — the stored-host model + its JSON codec, the settings-key names,
+// the deep-link grammar, and (later) the Live Activity attributes — lives here and here only.
+
+import Foundation
+
+/// The one App-Group identifier, matched by `Config/*.entitlements`
+/// (`com.apple.security.application-groups`). Registered on the developer portal for both the app
+/// id (`io.unom.punktfunk`) and the widget extension id (`io.unom.punktfunk.widgets`).
+public enum AppGroup {
+    public static let suiteName = "group.io.unom.punktfunk"
+
+    /// The shared defaults suite. Non-nil in a correctly-entitled process; falls back to
+    /// `.standard` if the group is somehow unavailable (unsigned `swift run`, a misprovisioned
+    /// build) so the app still functions single-process rather than crashing — the widget just
+    /// won't see the same store there.
+    public static var defaults: UserDefaults {
+        UserDefaults(suiteName: suiteName) ?? .standard
+    }
+}
@@ -0,0 +1,57 @@
+// The `punktfunk://` deep-link grammar — the single builder/parser shared by the widget (which
+// emits links via `widgetURL`/`Link`) and the app (`ContentView.onOpenURL`, which routes them into
+// the existing connect path). Keeping both sides on one type means the wire format can't drift.
+//
+// Grammar (v1):
+//   punktfunk://connect/<host-uuid>                       — connect to a stored host
+//   punktfunk://connect/<host-uuid>?launch=<GameEntry.id> — connect and ask the host to launch it
+//
+// `launch` carries a `GameEntry.id` (e.g. "steam:570"); it is percent-encoded on build and decoded
+// on parse, so ids with reserved characters survive the round trip.
+
+import Foundation
+
+public enum DeepLink: Equatable {
+    /// Connect to a saved host; `launchID` is a `GameEntry.id` to launch on arrival, if any.
+    case connect(host: UUID, launchID: String?)
+
+    public static let scheme = "punktfunk"
+
+    /// Build the canonical URL for a route. Non-optional: every route is representable.
+    public var url: URL {
+        switch self {
+        case let .connect(host, launchID):
+            var comps = URLComponents()
+            comps.scheme = Self.scheme
+            comps.host = "connect"
+            comps.path = "/\(host.uuidString)"
+            if let launchID, !launchID.isEmpty {
+                comps.queryItems = [URLQueryItem(name: "launch", value: launchID)]
+            }
+            // URLComponents percent-encodes the query value; force-unwrap is safe for a URL we
+            // fully control (scheme/host/path are all valid).
+            return comps.url!
+        }
+    }
+
+    /// Parse an incoming URL, or nil if it isn't a recognized `punktfunk://` route. Tolerant of
+    /// case in the scheme and of a trailing slash on the path.
+    public init?(_ url: URL) {
+        guard url.scheme?.lowercased() == Self.scheme else { return nil }
+        guard let comps = URLComponents(url: url, resolvingAgainstBaseURL: false) else { return nil }
+
+        switch comps.host?.lowercased() {
+        case "connect":
+            // Path is "/<uuid>"; strip the leading slash and any trailing one.
+            let raw = comps.path
+                .trimmingCharacters(in: CharacterSet(charactersIn: "/"))
+            guard let host = UUID(uuidString: raw) else { return nil }
+            let launch = comps.queryItems?
+                .first(where: { $0.name == "launch" })?.value
+                .flatMap { $0.isEmpty ? nil : $0 }
+            self = .connect(host: host, launchID: launch)
+        default:
+            return nil
+        }
+    }
+}
@@ -1,7 +1,8 @@
 // One source of truth for the client's UserDefaults / @AppStorage keys. A magic-string key
 // duplicated across a setting's writer (a Settings @AppStorage) and reader (e.g. a stream view
 // reading UserDefaults) splits silently on a typo — the setting just stops taking effect. These
-// live in PunktfunkKit because both the app and the kit's views read them.
+// live in the dependency-free PunktfunkShared module (re-exported by PunktfunkKit) because the app,
+// the kit's views, AND the widget extension all read them — the widget needs `DefaultsKey.hosts`.

 import Foundation

@@ -27,8 +28,10 @@ public enum DefaultsKey {
    /// Requested audio channel count: 2 (stereo), 6 (5.1) or 8 (7.1). The host clamps to what it
    /// can capture; the resolved count drives the in-core decode + AVAudioEngine layout.
    public static let audioChannels = "punktfunk.audioChannels"
-    /// Preferred video codec: `"auto"` (host decides), `"hevc"`, or `"h264"`. A soft preference —
-    /// the host emits it when it can, else falls back. Drives the decoder via `Welcome.codec`.
+    /// Preferred video codec: `"auto"` (host decides), `"hevc"`, `"h264"`, `"av1"`, or
+    /// `"pyrowave"` (the opt-in wired-LAN wavelet codec — picking it advertises AND prefers it,
+    /// and forces the session SDR). A soft preference — the host emits it when it can, else
+    /// falls back. Drives the decoder via `Welcome.codec`.
    public static let codec = "punktfunk.codec"
    public static let micEnabled = "punktfunk.micEnabled"
    public static let speakerUID = "punktfunk.speakerUID"
@@ -109,6 +112,16 @@ public enum DefaultsKey {
    /// 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"
+    /// iOS/iPadOS: keep a streaming session ALIVE when the app is backgrounded (audio background
+    /// mode). Off by default (today's freeze-on-background is the default). When on, backgrounding a
+    /// live session keeps audio playing and the QUIC/pump live while DROPPING video decode, and a
+    /// bounded timer (`backgroundTimeoutMinutes`) auto-disconnects if the user doesn't return. Read
+    /// by ContentView's scenePhase driver. Hidden on tvOS/macOS.
+    public static let backgroundKeepAlive = "punktfunk.backgroundKeepAlive"
+    /// iOS/iPadOS: minutes a backgrounded keep-alive session runs before auto-disconnecting (a
+    /// battery/thermal/bandwidth backstop). Default 10; the UI offers 1/5/10/30. The auto-disconnect
+    /// is non-deliberate (host linger kept), so a late return reconnects fast. Read on enterBackground.
+    public static let backgroundTimeoutMinutes = "punktfunk.backgroundTimeoutMinutes"
 }

 extension Notification.Name {
@@ -118,4 +131,15 @@ extension Notification.Name {
    /// menus) — it exists so the menu item is honest whenever it CAN fire, and as the shortcut's
    /// discoverable menu-bar surface.
    public static let punktfunkReleaseCapture = Notification.Name("io.unom.punktfunk.release-capture")
+
+    /// Posted by the Live Activity's / Shortcuts' End-stream intent (`EndStreamIntent.perform`,
+    /// which runs in the app's process): the app tears the active session down deliberately
+    /// (quit-close the host). Same cross-process-signal pattern as `punktfunkReleaseCapture` —
+    /// the intent lives in PunktfunkShared and can't reach the app's `SessionModel` directly.
+    public static let punktfunkEndActiveSession = Notification.Name("io.unom.punktfunk.end-active-session")
+
+    /// Posted by the Connect App Intent (Siri/Shortcuts) with a `punktfunk://` URL as `object`:
+    /// the app routes it through the SAME `.onOpenURL` handler a widget tap uses (one router, one
+    /// set of guards). The intent uses `openAppWhenRun`, so the app is foregrounded to receive it.
+    public static let punktfunkOpenDeepLink = Notification.Name("io.unom.punktfunk.open-deep-link")
 }
@@ -0,0 +1,56 @@
+// The saved-host as an App Intents entity — the parameter type for the Connect/Wake intents and
+// the configurable single-host widget. Lives in the shared module (not the app) because widget
+// *configuration* intents execute in the EXTENSION process, so the entity can't be app-only.
+//
+// AppIntents is genuinely available on macOS (13+), so this is gated on `canImport(AppIntents)`
+// (unlike ActivityKit, whose macOS types are unavailable) — it compiles on every platform and the
+// entity query reads the same shared App-Group store the widget does.
+
+#if canImport(AppIntents)
+import AppIntents
+import Foundation
+
+public struct HostEntity: AppEntity, Identifiable {
+    public static let typeDisplayRepresentation = TypeDisplayRepresentation(name: "Host")
+    public static let defaultQuery = HostEntityQuery()
+
+    public let id: UUID
+    public let name: String
+
+    public init(id: UUID, name: String) {
+        self.id = id
+        self.name = name
+    }
+
+    public init(_ host: StoredHost) {
+        self.id = host.id
+        self.name = host.displayName
+    }
+
+    public var displayRepresentation: DisplayRepresentation {
+        DisplayRepresentation(title: "\(name)")
+    }
+}
+
+public struct HostEntityQuery: EntityQuery {
+    public init() {}
+
+    public func entities(for identifiers: [UUID]) async throws -> [HostEntity] {
+        Self.loadHosts().filter { identifiers.contains($0.id) }.map(HostEntity.init)
+    }
+
+    /// Sorted most-recent first — Siri/Shortcuts and the widget config picker suggest recent hosts.
+    public func suggestedEntities() async throws -> [HostEntity] {
+        Self.loadHosts().map(HostEntity.init)
+    }
+
+    static func loadHosts() -> [StoredHost] {
+        guard let data = AppGroup.defaults.data(forKey: DefaultsKey.hosts),
+              let hosts = try? JSONDecoder().decode([StoredHost].self, from: data)
+        else { return [] }
+        return hosts.sorted {
+            ($0.lastConnected ?? .distantPast) > ($1.lastConnected ?? .distantPast)
+        }
+    }
+}
+#endif
@@ -0,0 +1,68 @@
+// The Live Activity's attributes — the ONE type that must be identical in the app (which starts
+// and updates the Activity) and the widget extension (which renders it). Hence it lives in the
+// dependency-free shared module.
+//
+// Gated on `os(iOS)`, NOT `canImport(ActivityKit)`: ActivityKit *imports* on macOS but its types
+// are `@available(macOS, unavailable)`, so canImport would wrongly admit this on the macOS build.
+// Live Activities are iPhone/iPad only (iPadOS reports os(iOS)).
+//
+// Naming/shape is a runtime contract: an Activity started by one build is decoded by the extension
+// of the same build, so keep `ContentState` Codable-stable across releases the way `StoredHost` is.
+
+#if os(iOS)
+import ActivityKit
+import Foundation
+
+public struct PunktfunkSessionAttributes: ActivityAttributes {
+    // Static for the Activity's whole life (set at request time).
+    public let hostID: UUID
+    public let hostName: String
+    /// The title of the launched game, if the session started from the library; nil for a plain
+    /// host connect (nothing tracks the live foreground app mid-session).
+    public let launchTitle: String?
+
+    public init(hostID: UUID, hostName: String, launchTitle: String?) {
+        self.hostID = hostID
+        self.hostName = hostName
+        self.launchTitle = launchTitle
+    }
+
+    public struct ContentState: Codable, Hashable {
+        public enum Stage: String, Codable, Hashable {
+            case streaming     // foreground, live
+            case background    // backgrounded keep-alive (countdown running)
+            case reconnecting  // post-loss re-anchor hold
+            case ending        // torn down — final state before dismissal
+        }
+
+        public var stage: Stage
+        /// Session start — drives `Text(timerInterval:)` for a free client-side ticking clock (no
+        /// per-second push needed).
+        public var startedAt: Date
+        /// e.g. "2560×1440 @120 · HEVC · HDR". Updated only when it actually changes.
+        public var modeLine: String
+        /// Coarse, updated sparsely (every ~30 s) — never the 1 Hz stats firehose.
+        public var latencyMs: Int?
+        public var mbps: Double?
+        /// While backgrounded: when the keep-alive auto-disconnect fires — drives the countdown.
+        public var backgroundDeadline: Date?
+
+        public init(
+            stage: Stage, startedAt: Date, modeLine: String,
+            latencyMs: Int? = nil, mbps: Double? = nil, backgroundDeadline: Date? = nil
+        ) {
+            self.stage = stage
+            self.startedAt = startedAt
+            self.modeLine = modeLine
+            self.latencyMs = latencyMs
+            self.mbps = mbps
+            self.backgroundDeadline = backgroundDeadline
+        }
+    }
+}
+
+/// Kind string for the Live Activity — kept next to the attributes so app + extension agree.
+public enum PunktfunkActivity {
+    public static let kind = "PunktfunkSession"
+}
+#endif
@@ -0,0 +1,30 @@
+// App Intents that must compile into BOTH the app and the widget extension live here in the shared
+// module. Today that's `EndStreamIntent` — the Live Activity's "End stream" button (a
+// LiveActivityIntent runs in the APP's process) which M4 also surfaces to Siri/Shortcuts.
+//
+// Gated on os(iOS): LiveActivityIntent is part of ActivityKit's world (iPhone/iPad only). The M4
+// Connect/Wake intents that need the app's router live in the app target, not here.
+
+#if os(iOS)
+import AppIntents
+import Foundation
+
+/// Ends the active streaming session. Backs the Live Activity's End button and the Shortcuts /
+/// Siri "End the Punktfunk stream" phrase. `perform()` runs in the app's process (LiveActivityIntent)
+/// — it posts `.punktfunkEndActiveSession`, which the app's SessionModel owner observes and turns
+/// into `disconnect(deliberate: true)` (the user explicitly ended it → quit-close the host).
+@available(iOS 17.0, *)
+public struct EndStreamIntent: LiveActivityIntent {
+    public static let title: LocalizedStringResource = "End Punktfunk Stream"
+    public static let description = IntentDescription("Ends the active Punktfunk streaming session.")
+
+    public init() {}
+
+    public func perform() async throws -> some IntentResult {
+        await MainActor.run {
+            NotificationCenter.default.post(name: .punktfunkEndActiveSession, object: nil)
+        }
+        return .result()
+    }
+}
+#endif
@@ -0,0 +1,63 @@
+// The saved-host model + its on-disk JSON wire format — the widget/extension depends on BOTH, so
+// they live in the dependency-free shared module. The `ObservableObject` store that wraps them
+// (`HostStore`, with add/remove/pin/reachability) stays in the app target; discovery-join helpers
+// (`matches`, `advertises`) stay there too because they reference PunktfunkKit's `DiscoveredHost`.
+//
+// Wire-format stability: the JSON encoding of `StoredHost` is now a shared contract between the app
+// (writer) and the widget (reader). The `PunktfunkSharedTests` codec round-trip pins it — do not
+// rename the coding keys or make a stored `Optional` non-optional (older saved JSON must still
+// decode; synthesized Decodable treats a missing Optional as nil).
+
+import Foundation
+
+/// The management-API port default (distinct from the data-plane `port`). Lives here (not in
+/// PunktfunkKit's LibraryClient, which re-exports it) so `StoredHost.effectiveMgmtPort` can resolve
+/// it without the shared module taking a dependency on the kit.
+public let punktfunkDefaultMgmtPort: UInt16 = 47990
+
+public struct StoredHost: Identifiable, Codable, Hashable {
+    public var id = UUID()
+    public var name: String
+    public var address: String
+    public var port: UInt16 = 9777
+    /// SHA-256 of the host's certificate, set after the user explicitly trusted it.
+    public var pinnedSHA256: Data?
+    /// Last time a streaming session actually started (nil until the first one).
+    public var lastConnected: Date?
+    /// Management-API port for the library browser (distinct from the data-plane `port`). Optional
+    /// (NOT a defaulted non-optional) so older saved hosts — whose JSON lacks this key — still
+    /// decode: synthesized Decodable ignores property defaults but treats a missing Optional as
+    /// nil. Resolve via `effectiveMgmtPort`. (Auth is mTLS by the pinned identity — no token.)
+    public var mgmtPort: UInt16?
+    /// Wake-on-LAN MAC address(es) of the host's wake-capable NIC(s), each `aa:bb:cc:dd:ee:ff`.
+    /// Learned from the host's mDNS `mac` TXT record while it's awake and persisted here, so the
+    /// client can send a magic packet to wake the host later (when it's asleep and no longer
+    /// advertising). Optional (same forward-compat reason as `mgmtPort`); nil until first learned.
+    public var macAddresses: [String]?
+    /// Share the clipboard with this host (macOS sessions; design/clipboard-and-file-transfer.md
+    /// §5.3). Opt-in per host: nil/false = off (nil also keeps older saved JSON decoding — same
+    /// forward-compat reason as `mgmtPort`). Honored only when the host advertises
+    /// `HOST_CAP_CLIPBOARD`.
+    public var clipboardSync: Bool?
+
+    public init(
+        id: UUID = UUID(), name: String, address: String, port: UInt16 = 9777,
+        pinnedSHA256: Data? = nil, lastConnected: Date? = nil, mgmtPort: UInt16? = nil,
+        macAddresses: [String]? = nil, clipboardSync: Bool? = nil
+    ) {
+        self.id = id
+        self.name = name
+        self.address = address
+        self.port = port
+        self.pinnedSHA256 = pinnedSHA256
+        self.lastConnected = lastConnected
+        self.mgmtPort = mgmtPort
+        self.macAddresses = macAddresses
+        self.clipboardSync = clipboardSync
+    }
+
+    public var displayName: String { name.isEmpty ? address : name }
+    public var effectiveMgmtPort: UInt16 { mgmtPort ?? punktfunkDefaultMgmtPort }
+    /// Wake-capable, in a form the wake helper accepts (empty when none learned yet).
+    public var wakeMacs: [String] { macAddresses ?? [] }
+}
@@ -237,10 +237,11 @@ final class AV1Tests: XCTestCase {
        let ready = try XCTUnwrap(frame)
        XCTAssertEqual(ready.ptsNs, 42_000_000)
        XCTAssertFalse(ready.isHDR)
-        XCTAssertEqual(CVPixelBufferGetWidth(ready.pixelBuffer), 320)
-        XCTAssertEqual(CVPixelBufferGetHeight(ready.pixelBuffer), 180)
+        let buffer = try XCTUnwrap(ready.pixelBuffer, "a VT decode delivers a .video frame")
+        XCTAssertEqual(CVPixelBufferGetWidth(buffer), 320)
+        XCTAssertEqual(CVPixelBufferGetHeight(buffer), 180)
        XCTAssertEqual(
-            CVPixelBufferGetPixelFormatType(ready.pixelBuffer),
+            CVPixelBufferGetPixelFormatType(buffer),
            kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange, "SDR AV1 must decode to NV12")
        decoder.reset()
    }
@@ -0,0 +1,292 @@
+// PyroWave Metal decoder tests — two layers:
+//
+// 1. Bitstream/window-walk parser tests (pure CPU): hand-crafted packet streams assert the
+//    exact wire semantics of pyrowave_decoder.cpp's push_packet walk + the Phase-4
+//    chunk-aligned framing (4-byte window prefix, FRAG chains, zeroed missing shards).
+//
+// 2. Golden-frame PSNR tests (Metal GPU): host-encoded fixtures (crates/punktfunk-host
+//    encode/linux/pyrowave.rs `pyrowave_dump_golden`, run on a Vulkan box) decoded by the
+//    Metal port and PSNR-matched against upstream's own decoder output. Float wavelet math is
+//    not bit-exact across implementations (upstream ships precision variants), so the gate is
+//    PSNR, not equality. This is the §4.7 validation oracle for the hand-ported kernels —
+//    the gather/mirror addressing in idwt is the spot most likely to drift.
+
+#if canImport(Metal)
+import Metal
+import XCTest
+
+@testable import PunktfunkKit
+
+final class PyroWaveParserTests: XCTestCase {
+    // 256x144 → aligned 256x160; block space identical to the committed fixtures.
+    private let width = 256
+    private let height = 144
+
+    /// A BitstreamSequenceHeader (START_OF_FRAME) for `width`x`height`, 4:2:0 BT.709 limited.
+    private func sof(totalBlocks: Int, sequence: UInt32 = 1) -> [UInt8] {
+        let word0 =
+            UInt32(width - 1) | (UInt32(height - 1) << 14) | (sequence << 28) | (1 << 31)
+        // code=0 (SOF), chroma=0 (420), primaries/trc/matrix=0 (BT.709), range=1 (LIMITED),
+        // siting=0.
+        let word1 = UInt32(totalBlocks) | (1 << 30)
+        return le32(word0) + le32(word1)
+    }
+
+    /// A minimal coefficient packet: ballot=0 (all 8x8 blocks empty — legal and decodable),
+    /// payload_words=2 (header only).
+    private func packet(blockIndex: Int, sequence: UInt32 = 1) -> [UInt8] {
+        let word0 = UInt32(0) | (2 << 16) | (sequence << 28)
+        let word1 = UInt32(0) | (UInt32(blockIndex) << 8)
+        return le32(word0) + le32(word1)
+    }
+
+    private func le32(_ v: UInt32) -> [UInt8] {
+        [UInt8(v & 0xff), UInt8((v >> 8) & 0xff), UInt8((v >> 16) & 0xff), UInt8(v >> 24)]
+    }
+
+    /// Wrap bodies into `windowSize`-sized windows with the 4-byte used/kind prefix.
+    private func window(_ body: [UInt8], kind: UInt16, size: Int) -> [UInt8] {
+        precondition(body.count + 4 <= size)
+        var out = [UInt8(body.count & 0xff), UInt8(body.count >> 8)]
+        out += [UInt8(kind & 0xff), UInt8(kind >> 8)]
+        out += body
+        out += [UInt8](repeating: 0, count: size - out.count)
+        return out
+    }
+
+    func testLayoutMatchesUpstreamBlockSpace() {
+        // init_block_meta's walk for 256x144 (aligned 256x160): level extents halve from
+        // 128x80; per (comp,level,band) count32 = ceil(ceil(w/8)/4) * ceil(ceil(h/8)/4).
+        let layout = WaveletLayout(width: width, height: height)
+        XCTAssertEqual(layout.alignedWidth, 256)
+        XCTAssertEqual(layout.alignedHeight, 160)
+        XCTAssertEqual(layout.levelWidth(0), 128)
+        XCTAssertEqual(layout.levelHeight(0), 80)
+        XCTAssertEqual(layout.levelWidth(4), 8)
+        XCTAssertEqual(layout.levelHeight(4), 5)
+        // Hand-summed: L4 (8x5 → 1 block) × 3 comps × 4 bands = 12; L3 (16x10 → 1) × 9 = 9;
+        // L2 (32x20 → 1) × 9 = 9; L1 (64x40 → 2x2=4... ) — trust the invariant instead:
+        // every band's count is ceil(w8/4)*ceil(h8/4) and the total is their sum.
+        var expected = 0
+        for level in stride(from: 4, through: 0, by: -1) {
+            let w8 = (layout.levelWidth(level) + 7) / 8
+            let h8 = (layout.levelHeight(level) + 7) / 8
+            let per = ((w8 + 3) / 4) * ((h8 + 3) / 4)
+            for component in 0..<3 {
+                if level == 0 && component != 0 { continue }
+                expected += per * (level == 4 ? 4 : 3)
+            }
+        }
+        XCTAssertEqual(layout.blockCount32, expected)
+        // The finest luma level's stride is its 32-block row width.
+        XCTAssertEqual(layout.blockMeta[0][0][1].stride, (128 + 31) / 32)
+        // Level-0 chroma is not coded in 4:2:0.
+        XCTAssertEqual(layout.blockMeta[1][0][1].offset, -1)
+    }
+
+    func testDenseParseFillsOffsetsAndCountsBlocks() throws {
+        let layout = WaveletLayout(width: width, height: height)
+        var au = sof(totalBlocks: 4)
+        au += packet(blockIndex: 0)
+        au += packet(blockIndex: 3)
+        au += packet(blockIndex: 3) // duplicate — first wins, not double-counted
+        au += packet(blockIndex: layout.blockCount32 - 1)
+        let frame = try XCTUnwrap(
+            WaveletBitstream.parse(au: Data(au), chunkAligned: false, windowSize: 0))
+        XCTAssertEqual(frame.layout.width, width)
+        XCTAssertEqual(frame.totalBlocks, 4)
+        XCTAssertEqual(frame.decodedBlocks, 3)
+        XCTAssertEqual(frame.offsets[0], 0)
+        XCTAssertEqual(frame.offsets[3], 2) // u32 words: each header-only packet is 2 words
+        XCTAssertEqual(frame.offsets[1], UInt32.max)
+        XCTAssertEqual(frame.payload.count, 6)
+        XCTAssertFalse(frame.bt2020)
+        XCTAssertFalse(frame.fullRange) // range bit 1 = LIMITED
+    }
+
+    func testHalfOrFewerBlocksIsDropped() {
+        var au = sof(totalBlocks: 4)
+        au += packet(blockIndex: 0)
+        au += packet(blockIndex: 1)
+        // 2 of 4 decoded = exactly half — upstream requires MORE than half.
+        XCTAssertNil(WaveletBitstream.parse(au: Data(au), chunkAligned: false, windowSize: 0))
+    }
+
+    func testMissingSOFIsDropped() {
+        let au = packet(blockIndex: 0) + packet(blockIndex: 1)
+        XCTAssertNil(WaveletBitstream.parse(au: Data(au), chunkAligned: false, windowSize: 0))
+    }
+
+    func testTruncatedPacketIsRejected() {
+        var au = sof(totalBlocks: 1)
+        // Claims 4 payload words but only the 8-byte header follows.
+        let word0 = UInt32(0) | (4 << 16) | (1 << 28)
+        au += le32(word0) + le32(0)
+        XCTAssertNil(WaveletBitstream.parse(au: Data(au), chunkAligned: false, windowSize: 0))
+    }
+
+    func testWindowWalkPackedFragAndMissingShard() throws {
+        let size = 64
+        // Window 1: SOF + one packet, PACKED. Window 2: a FRAG chain carrying one packet split
+        // across two windows. Window 3: all zeros (a lost shard of a partial frame). Window 4:
+        // a PACKED packet — the chain break must not eat it.
+        let fragPacket = packet(blockIndex: 2)
+        var au = window(sof(totalBlocks: 3) + packet(blockIndex: 0), kind: 0, size: size)
+        au += window(Array(fragPacket[0..<5]), kind: 1, size: size)
+        au += window(Array(fragPacket[5...]), kind: 3, size: size)
+        au += [UInt8](repeating: 0, count: size) // missing shard
+        au += window(packet(blockIndex: 1), kind: 0, size: size)
+        let frame = try XCTUnwrap(
+            WaveletBitstream.parse(au: Data(au), chunkAligned: true, windowSize: size))
+        XCTAssertEqual(frame.decodedBlocks, 3)
+        XCTAssertEqual(frame.offsets[0], 0)
+        XCTAssertEqual(frame.offsets[2], 2)
+        XCTAssertEqual(frame.offsets[1], 4)
+    }
+
+    func testBrokenFragChainIsDiscarded() throws {
+        let size = 64
+        let fragPacket = packet(blockIndex: 2)
+        var au = window(sof(totalBlocks: 1) + packet(blockIndex: 0), kind: 0, size: size)
+        au += window(Array(fragPacket[0..<5]), kind: 1, size: size)
+        au += [UInt8](repeating: 0, count: size) // the chain's middle shard was lost
+        au += window(Array(fragPacket[5...]), kind: 3, size: size) // dangling LAST — dropped
+        let frame = try XCTUnwrap(
+            WaveletBitstream.parse(au: Data(au), chunkAligned: true, windowSize: size))
+        XCTAssertEqual(frame.decodedBlocks, 1)
+        XCTAssertEqual(frame.offsets[2], UInt32.max)
+    }
+}
+
+/// Golden-frame decode against the committed host-encoder fixtures. Skipped when the machine
+/// has no Metal device (headless CI) — everywhere else this is the hand-ported kernels' guard.
+final class PyroWaveGoldenTests: XCTestCase {
+    private static let fixtureDir = "PyroWaveFixtures"
+
+    private func fixture(_ name: String) throws -> Data {
+        let url = try XCTUnwrap(
+            Bundle.module.url(
+                forResource: name, withExtension: "bin", subdirectory: Self.fixtureDir),
+            "missing fixture \(name).bin — regenerate with pyrowave_dump_golden")
+        return try Data(contentsOf: url)
+    }
+
+    /// Completion box — the decode callback lands on a Metal thread.
+    private final class ResultBox: @unchecked Sendable {
+        let lock = NSLock()
+        var planes: WaveletPlanes?
+    }
+
+    /// Decode `au` synchronously and read all three planes back to CPU bytes.
+    private func decode(
+        au: Data, chunkAligned: Bool, windowSize: Int
+    ) throws -> (y: [UInt8], cb: [UInt8], cr: [UInt8]) {
+        let device = try XCTUnwrap(MTLCreateSystemDefaultDevice())
+        let queue = try XCTUnwrap(device.makeCommandQueue())
+        let decoder = try XCTUnwrap(MetalWaveletDecoder(device: device, queue: queue))
+        let done = expectation(description: "decode completes")
+        let box = ResultBox()
+        let submitted = decoder.decode(
+            au: au, chunkAligned: chunkAligned, windowSize: windowSize
+        ) { planes in
+            box.lock.lock()
+            box.planes = planes
+            box.lock.unlock()
+            done.fulfill()
+        }
+        XCTAssertTrue(submitted, "the fixture AU must parse")
+        wait(for: [done], timeout: 10)
+        box.lock.lock()
+        let result = box.planes
+        box.lock.unlock()
+        let planes = try XCTUnwrap(result, "the GPU pass must complete without error")
+        return (
+            try readback(planes.y, device: device, queue: queue),
+            try readback(planes.cb, device: device, queue: queue),
+            try readback(planes.cr, device: device, queue: queue)
+        )
+    }
+
+    private func readback(
+        _ texture: MTLTexture, device: MTLDevice, queue: MTLCommandQueue
+    ) throws -> [UInt8] {
+        let bytesPerRow = texture.width
+        let length = bytesPerRow * texture.height
+        let buffer = try XCTUnwrap(device.makeBuffer(length: length, options: .storageModeShared))
+        let cmd = try XCTUnwrap(queue.makeCommandBuffer())
+        let blit = try XCTUnwrap(cmd.makeBlitCommandEncoder())
+        blit.copy(
+            from: texture, sourceSlice: 0, sourceLevel: 0,
+            sourceOrigin: MTLOrigin(x: 0, y: 0, z: 0),
+            sourceSize: MTLSize(width: texture.width, height: texture.height, depth: 1),
+            to: buffer, destinationOffset: 0, destinationBytesPerRow: bytesPerRow,
+            destinationBytesPerImage: length)
+        blit.endEncoding()
+        cmd.commit()
+        cmd.waitUntilCompleted()
+        return [UInt8](UnsafeRawBufferPointer(start: buffer.contents(), count: length))
+    }
+
+    private func psnr(_ a: [UInt8], _ b: [UInt8]) -> Double {
+        precondition(a.count == b.count)
+        var sse = 0.0
+        for i in 0..<a.count {
+            let d = Double(a[i]) - Double(b[i])
+            sse += d * d
+        }
+        if sse == 0 { return .infinity }
+        let mse = sse / Double(a.count)
+        return 10 * log10(255.0 * 255.0 / mse)
+    }
+
+    private func assertMatchesReference(
+        _ decoded: (y: [UInt8], cb: [UInt8], cr: [UInt8]), prefix: String,
+        file: StaticString = #filePath, line: UInt = #line
+    ) throws {
+        for (name, plane, ref) in [
+            ("y", decoded.y, try fixture("\(prefix)-y")),
+            ("cb", decoded.cb, try fixture("\(prefix)-cb")),
+            ("cr", decoded.cr, try fixture("\(prefix)-cr")),
+        ] {
+            XCTAssertEqual(plane.count, ref.count, file: file, line: line)
+            let db = psnr(plane, [UInt8](ref))
+            print("pyrowave golden \(prefix) \(name): \(db) dB")
+            // The Metal port and upstream's decoder run the same math at the same precision
+            // tier; residual differences are float rounding + the gather/mirror edge handling.
+            // Well-matched ports measure ≫50 dB; 45 catches a real divergence long before it
+            // is visible.
+            XCTAssertGreaterThan(db, 45.0, "plane PSNR \(db) dB", file: file, line: line)
+        }
+    }
+
+    func testDenseGoldenFrame() throws {
+        try XCTSkipIf(!MetalWaveletDecoder.supported, "no capable Metal device")
+        let au = try fixture("au-dense")
+        let decoded = try decode(au: au, chunkAligned: false, windowSize: 0)
+        try assertMatchesReference(decoded, prefix: "ref-dense")
+    }
+
+    func testChunkAlignedGoldenFrame() throws {
+        try XCTSkipIf(!MetalWaveletDecoder.supported, "no capable Metal device")
+        let au = try fixture("au-chunked")
+        let decoded = try decode(au: au, chunkAligned: true, windowSize: 1408)
+        try assertMatchesReference(decoded, prefix: "ref-chunked")
+    }
+
+    /// Phase-4 partial delivery: zero a mid-AU window (a lost shard) — the frame must still
+    /// decode (blocks > half) and stay recognizably the same picture (holes reconstruct as
+    /// localized blur, not garbage).
+    func testPartialFrameStillDecodes() throws {
+        try XCTSkipIf(!MetalWaveletDecoder.supported, "no capable Metal device")
+        var au = try fixture("au-chunked")
+        let windows = au.count / 1408
+        try XCTSkipIf(windows < 3, "fixture too small to punch a hole in")
+        let hole = (windows / 2) * 1408
+        au.replaceSubrange(hole..<(hole + 1408), with: [UInt8](repeating: 0, count: 1408))
+        let decoded = try decode(au: au, chunkAligned: true, windowSize: 1408)
+        let ref = try fixture("ref-chunked-y")
+        let db = psnr(decoded.y, [UInt8](ref))
+        XCTAssertGreaterThan(db, 25.0, "lossy frame should still resemble the source (\(db) dB)")
+    }
+}
+#endif
--- a/Show More
+++ b/Show More