docs: zero-copy EGL/CUDA capture-crash hardening handoff

Describes a reproduced host SIGSEGV in cuGraphicsMapResources (inside
libnvidia-eglcore), reached via zerocopy::cuda / zerocopy::egl on the tiled
EGL/GL->CUDA capture path, when the KWin dmabuf is invalidated mid-map (observed
on .181 during a Game->Desktop switch under zero-copy, with the compositor itself
crashing). Pre-existing capture-layer issue, not the gamemode work. Issue
description + root cause + solution-space considerations only -- the next agent
plans the implementation.

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

.gitea/workflows/android-screenshots.yml

@@ -25,7 +25,8 @@ jobs:
           java-version: "21"
 
       - name: Android SDK
-        uses: android-actions/setup-android@v3
+        # SHA-pinned for parity with android.yml (third-party action). v3 = 9fc6c4e.
+        uses: android-actions/setup-android@9fc6c4e9069bf8d3d10b2204b1fb8f6ef7065407 # v3
 
       # No NDK/CMake — the screenshot unit tests are pure JVM. compileSdk 37 auto-downloads via AGP
       # if the platform channel lacks it (same note as android.yml).

.gitea/workflows/android.yml

@@ -1,5 +1,5 @@
 # Android client CI (Gitea Actions). Builds the Rust JNI core (clients/android/native) via
-# cargo-ndk for both shipping ABIs and assembles the debug APK (clients/android). Mirrors apple.yml
+# cargo-ndk for all three shipping ABIs and assembles the debug APK (clients/android). Mirrors apple.yml
 # but on a Linux runner — the NDK is cross-platform, so no self-hosted host is needed.
 #
 # Prereq: the runner needs ~6 GB free + internet (it pulls the Android SDK/NDK and the Gradle
@@ -40,10 +40,12 @@ jobs:
           fi
           RUSTUP="$(command -v rustup || echo "$HOME/.cargo/bin/rustup")"
           dirname "$RUSTUP" >> "$GITHUB_PATH"
-          "$RUSTUP" target add aarch64-linux-android x86_64-linux-android
+          "$RUSTUP" target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android
 
       - name: Android SDK
-        uses: android-actions/setup-android@v3
+        # SHA-pinned: this workflow's release job carries the signing keystore + Play service-account
+        # secrets, so a moved tag on a third-party action could exfiltrate them. v3 = 9fc6c4e.
+        uses: android-actions/setup-android@9fc6c4e9069bf8d3d10b2204b1fb8f6ef7065407 # v3
 
       - name: NDK r30 + platform 36 + build-tools + CMake (libopus cross-build)
         # cmake;3.22.1 installs cmake + ninja under $ANDROID_SDK/cmake/3.22.1/bin — the exact path
@@ -98,7 +100,7 @@ jobs:
           RELEASE_KEY_PASSWORD: ${{ secrets.RELEASE_KEY_PASSWORD }}
         run: |
           echo "${{ secrets.RELEASE_KEYSTORE_BASE64 }}" | base64 -d > release.jks
-          # AAB for Play; a universal APK (both ABIs) for direct sideload/testing — same upload key.
+          # AAB for Play; a universal APK (all ABIs) for direct sideload/testing — same upload key.
           ./gradlew :app:bundleRelease :app:assembleRelease --stacktrace
 
       # Publish BEFORE the Play upload so artifacts land even while the Play step is still failing.

.gitea/workflows/audit.yml

@@ -1,7 +1,10 @@
-# Supply-chain advisory scan for the (network-facing, crypto-heavy) Rust dependency tree.
-# Runs `cargo audit` against the RustSec advisory DB: weekly (catch newly-disclosed CVEs in
-# pinned deps), on every Cargo.lock change (catch a bad dep the moment it lands), and on demand.
-# To silence a known-unfixable advisory, add it to `.cargo/audit.toml` ([advisories] ignore = [...]).
+# Supply-chain advisory scan for BOTH dependency trees the project ships to users:
+#   * cargo-audit → the (network-facing, crypto-heavy) Rust tree, against the RustSec advisory DB.
+#   * bun audit   → the web management console (Nitro/Bun BFF) — the component that holds the login
+#                   gate, session sealing, and the mgmt bearer token, so its deps matter too.
+# Triggers: weekly (catch newly-disclosed CVEs in pinned deps), on every lockfile change (catch a bad
+# dep the moment it lands), and on demand.
+# To silence a known-unfixable Rust advisory, add it to `.cargo/audit.toml` ([advisories] ignore=[…]).
 name: audit
 
 on:
@@ -9,7 +12,7 @@ on:
     - cron: '0 6 * * 1'   # Mondays 06:00 UTC
   push:
     branches: [main]
-    paths: ['Cargo.lock', '.gitea/workflows/audit.yml']
+    paths: ['Cargo.lock', 'web/bun.lock', '.gitea/workflows/audit.yml']
   workflow_dispatch:
 
 jobs:
@@ -31,3 +34,25 @@ jobs:
           git config --global --add safe.directory "$PWD"
           command -v cargo-audit >/dev/null 2>&1 || cargo install --locked cargo-audit
           cargo audit
+
+  bun-audit:
+    runs-on: ubuntu-24.04
+    container:
+      image: oven/bun:1
+    timeout-minutes: 15
+    defaults:
+      run:
+        working-directory: web
+    steps:
+      # oven/bun's slim base lacks a CA bundle + git — actions/checkout's HTTPS fetch needs them
+      # (same preamble as web-screenshots.yml / ci.yml's web job).
+      - name: Install git + CA certs
+        working-directory: /
+        run: apt-get update && apt-get install -y --no-install-recommends ca-certificates git
+      - uses: actions/checkout@v4
+      # `bun audit` queries the registry advisory DB for the versions pinned in web/bun.lock. No
+      # install/build needed — it reads the manifest + lockfile. Fails the job on any advisory, the
+      # same fail-on-vulnerability stance as cargo-audit above; triage a finding by bumping the dep
+      # (or, if genuinely unfixable + inapplicable, pinning a resolution and noting why here).
+      - name: bun audit
+        run: bun audit

.gitea/workflows/ci.yml

@@ -28,8 +28,8 @@ jobs:
 
       # Best-effort caches (act_runner's built-in cache server). Keyed on Cargo.lock:
       # registry/git are download caches, target/ the incremental build. The target key
-      # carries the rustc version — rust-toolchain.toml pins the floating "stable"
-      # channel, so the file alone wouldn't invalidate stale incremental state.
+      # carries the rustc version — resolved via `rustc --version` (below) rather than parsed
+      # from rust-toolchain.toml, so a pin bump there invalidates stale incremental state too.
       - name: Cache keys
         run: echo "rustc=$(rustc --version | cut -d' ' -f2)" >> "$GITHUB_ENV"
       - uses: actions/cache@v4

.gitea/workflows/docker.yml

@@ -86,7 +86,10 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Sync compose file
-        uses: appleboy/scp-action@v0.1.7
+        # SHA-pinned (not tag-pinned): this action receives DEPLOY_SSH_KEY + host/user/port, so a
+        # moved tag would mean credential exfiltration. v0.1.7 = 917f8b8. Bump both the SHA and the
+        # trailing version together when upgrading.
+        uses: appleboy/scp-action@917f8b81dfc1ccd331fef9e2d61bdc6c8be94634 # v0.1.7
         with:
           host: ${{ secrets.DEPLOY_HOST }}
           username: ${{ secrets.DEPLOY_USER }}
@@ -97,7 +100,8 @@ jobs:
           overwrite: true
 
       - name: Pull and start docs
-        uses: appleboy/ssh-action@v1.2.5
+        # SHA-pinned: receives DEPLOY_SSH_KEY + REGISTRY_TOKEN (see the scp step above). v1.2.5 = 0ff4204.
+        uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5
         env:
           REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
         with:

Cargo.lock

@@ -2129,7 +2129,7 @@ dependencies = [
 
 [[package]]
 name = "latency-probe"
-version = "0.7.4"
+version = "0.8.0"
 
 [[package]]
 name = "lazy_static"
@@ -2261,7 +2261,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
 
 [[package]]
 name = "loss-harness"
-version = "0.7.4"
+version = "0.8.0"
 dependencies = [
  "punktfunk-core",
 ]
@@ -2908,7 +2908,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-android"
-version = "0.7.4"
+version = "0.8.0"
 dependencies = [
  "android_logger",
  "jni",
@@ -2922,7 +2922,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-linux"
-version = "0.7.4"
+version = "0.8.0"
 dependencies = [
  "anyhow",
  "async-channel",
@@ -2945,7 +2945,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-windows"
-version = "0.7.4"
+version = "0.8.0"
 dependencies = [
  "anyhow",
  "async-channel",
@@ -2968,7 +2968,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-core"
-version = "0.7.4"
+version = "0.8.0"
 dependencies = [
  "aes-gcm",
  "bytes",
@@ -2999,7 +2999,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-host"
-version = "0.7.4"
+version = "0.8.0"
 dependencies = [
  "aes",
  "aes-gcm",
@@ -3071,7 +3071,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-probe"
-version = "0.7.4"
+version = "0.8.0"
 dependencies = [
  "anyhow",
  "mdns-sd",
@@ -3085,7 +3085,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-tray"
-version = "0.7.4"
+version = "0.8.0"
 dependencies = [
  "anyhow",
  "ksni",

Cargo.toml

@@ -17,7 +17,7 @@ members = [
 exclude = ["packaging/linux/steam-deck-gadget/usbip-poc"]
 
 [workspace.package]
-version = "0.7.4"
+version = "0.8.0"
 edition = "2021"
 rust-version = "1.82"
 license = "MIT OR Apache-2.0"

README.md

@@ -29,6 +29,11 @@ protocol, FEC, and crypto, linked into the host and every client over a stable C
 - **Your device's exact mode.** For each client that connects, the host spins up a virtual display
   sized to that device — 1080p60 to a laptop, 1440p120 to a desktop, 4K to a TV, all at once. No
   letterboxing, no scaling, no rearranging your real monitors.
+- **Displays you configure, not just create.** Keep a game's display (and the game) alive across
+  disconnects so a reconnect drops straight back in; make the stream your sole desktop or extend
+  alongside your monitors; let several devices become monitors of one desktop; keep each client's
+  scaling. One-click presets in the console — a dedicated couch box, a shared desktop, a multi-monitor
+  workstation. See [Virtual displays](docs-site/content/docs/virtual-displays.md).
 - **A real virtual display on Windows, too.** On Linux the host uses per-compositor virtual outputs;
   on Windows you get the same on-the-fly virtual display — at the client's exact mode, no physical
   monitor or dummy HDMI plug, even on the secure desktop (UAC / lock screen). It also has **its own
@@ -52,7 +57,7 @@ protocol, FEC, and crypto, linked into the host and every client over a stable C
 | **Core** — `punktfunk-core` + C ABI (protocol · FEC · crypto · QUIC) | ✅ Complete & hardened |
 | **GameStream host** → stock Moonlight | ✅ Live end-to-end: pairing, RTSP, audio, per-client virtual output at native resolution, GPU zero-copy NVENC, gamepads |
 | **Native protocol** — `punktfunk/1` | ✅ Validated live: QUIC control + GF(2¹⁶) FEC/AES-GCM data plane, PIN pairing, mDNS discovery, mid-stream mode renegotiation |
-| **Windows host** (Windows 11 22H2+, x64) | 🟡 Implemented & shipping as a signed installer: DXGI/WGC capture · its own all-Rust IddCx **virtual display** (secure-desktop capable) · GPU encode (NVENC on NVIDIA, AMF/QSV on AMD/Intel, software H.264 without a GPU) · WASAPI audio · bundled virtual-gamepad drivers (no ViGEmBus) · HDR incl. Vulkan-game HDR. NVIDIA live-validated; AMD/Intel CI-green |
+| **Windows host** (Windows 11 22H2+, x64) | 🟡 Implemented & shipping as a signed installer: its own all-Rust IddCx **virtual display** (secure-desktop capable) with a **sealed IDD-push** capture path — finished frames pushed straight into its own driver, not screen-scraped (no DDA/WGC) · GPU encode (NVENC on NVIDIA, AMF/QSV on AMD/Intel, software H.264 without a GPU) · WASAPI audio · bundled virtual-gamepad drivers (no ViGEmBus) · HDR incl. Vulkan-game HDR. NVIDIA live-validated; AMD/Intel CI-green |
 | **macOS / iOS / tvOS client** (`clients/apple`) | ✅ Streaming live: VideoToolbox decode, controllers incl. DualSense, discovery, pairing, speed test |
 | **Linux client** (`clients/linux`, GTK4) | ✅ Streaming live: FFmpeg + VAAPI zero-copy decode, PipeWire audio, SDL3 controllers; ships as Flatpak/apt/rpm/Arch |
 | **Android client** (`clients/android`, phone + TV) | ✅ Streaming live: AMediaCodec decode + HDR10, AAudio audio, controllers, discovery, pairing |

api/openapi.json

@@ -10,7 +10,7 @@
       "name": "MIT OR Apache-2.0",
       "identifier": "MIT OR Apache-2.0"
     },
-    "version": "0.7.4"
+    "version": "0.8.0"
   },
   "paths": {
     "/api/v1/clients": {
@@ -138,6 +138,58 @@
         }
       }
     },
+    "/api/v1/display/layout": {
+      "put": {
+        "tags": [
+          "display"
+        ],
+        "summary": "Arrange virtual displays",
+        "description": "Set the **manual** desktop arrangement — per-identity-slot `(x, y)` offsets so a multi-monitor\ngroup (§6A/§6B) comes back where the operator placed it. Persisted into the policy's layout block\nand switched to manual mode; applied from the next connect (a live group re-applies on its next\nacquire). Locks in the current effective behavior as explicit fields, so arranging displays never\nsilently changes keep-alive/topology/conflict/identity. See `design/display-management.md` §6.2.",
+        "operationId": "setDisplayLayout",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DisplayLayoutRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Layout stored; the new settings state",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DisplaySettingsState"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Layout could not be persisted",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/v1/display/release": {
       "post": {
         "tags": [
@@ -216,7 +268,7 @@
           "display"
         ],
         "summary": "Set the display-management policy",
-        "description": "Persists a new policy (validated + clamped) and applies it from the next connect/teardown — a\nrunning session keeps the display it opened on. `keep_alive: forever` is rejected until the\ndisplay-lifecycle stage ships (it would keep physical monitors dark indefinitely with no release\npath yet).",
+        "description": "Persists a new policy (validated + clamped) and applies it from the next connect/teardown — a\nrunning session keeps the display it opened on. `keep_alive: forever` (the gaming-rig preset) is\nhonored (the display is Pinned; free it via `POST /display/release`).",
         "operationId": "setDisplaySettings",
         "requestBody": {
           "content": {
@@ -240,7 +292,7 @@
             }
           },
           "400": {
-            "description": "An option value is not yet supported (e.g. keep_alive forever)",
+            "description": "Malformed policy body",
             "content": {
               "application/json": {
                 "schema": {
@@ -1775,7 +1827,12 @@
           "backend",
           "mode",
           "state",
-          "sessions"
+          "sessions",
+          "group",
+          "display_index",
+          "x",
+          "y",
+          "topology"
         ],
         "properties": {
           "backend": {
@@ -1789,6 +1846,12 @@
             ],
             "description": "Short client label, when the owner tracks it."
           },
+          "display_index": {
+            "type": "integer",
+            "format": "int32",
+            "description": "This display's ordinal within its group, in acquire order (0-based).",
+            "minimum": 0
+          },
           "expires_in_ms": {
             "type": [
               "integer",
@@ -1798,6 +1861,21 @@
             "description": "Milliseconds until a lingering display is torn down (absent when active/pinned).",
             "minimum": 0
           },
+          "group": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Display group (shared desktop) id — several displays with the same group form one desktop (§6A).",
+            "minimum": 0
+          },
+          "identity_slot": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int32",
+            "description": "Stable per-client identity slot keying persistent config + manual layout (absent = shared/anonymous).",
+            "minimum": 0
+          },
           "mode": {
             "type": "string",
             "description": "`WIDTHxHEIGHT@HZ`."
@@ -1817,6 +1895,20 @@
           "state": {
             "type": "string",
             "description": "`active` | `lingering` | `pinned`."
+          },
+          "topology": {
+            "type": "string",
+            "description": "Effective topology for this display's group (`extend` | `primary` | `exclusive`)."
+          },
+          "x": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Desktop-space top-left `x` (auto-row or the console's manual arrangement, §6.2)."
+          },
+          "y": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Desktop-space top-left `y`."
           }
         }
       },
@@ -2128,10 +2220,30 @@
           }
         }
       },
+      "DisplayLayoutRequest": {
+        "type": "object",
+        "description": "Request body for `setDisplayLayout`: per-identity-slot desktop offsets, keyed by the identity-slot\nid as a string (the same id `/display/state` reports as `identity_slot`).",
+        "properties": {
+          "positions": {
+            "type": "object",
+            "description": "`{\"<identity_slot>\": {\"x\": …, \"y\": …}}` — where each arranged display's top-left sits.",
+            "additionalProperties": {
+              "$ref": "#/components/schemas/Position"
+            },
+            "propertyNames": {
+              "type": "string"
+            }
+          }
+        }
+      },
       "DisplayPolicy": {
         "type": "object",
         "description": "The user-facing display-management policy — what `display-settings.json` holds and what the mgmt\nAPI GETs/PUTs. When [`preset`](Self::preset) is not [`Preset::Custom`] the explicit fields are\nignored (the console writes one or the other); [`effective`](Self::effective) resolves both to a\nsingle [`EffectivePolicy`].",
         "properties": {
+          "game_session": {
+            "$ref": "#/components/schemas/GameSession",
+            "description": "How a game-launching session is served (`design/gamemode-and-dedicated-sessions.md` §5.2).\nOrthogonal to `preset`/lifecycle — preserved across preset changes; `#[serde(default)]` = `Auto`\nso existing `display-settings.json` files are untouched."
+          },
           "identity": {
             "$ref": "#/components/schemas/Identity"
           },
@@ -2188,7 +2300,7 @@
             "items": {
               "type": "string"
             },
-            "description": "Option names this build enforces right now (e.g. `keep_alive`, `topology`). The remaining\nstored options (`mode_conflict`, `identity`, `layout`) land in later stages — surfaced so the\nconsole can mark them \"coming soon\" instead of implying they already take effect."
+            "description": "Option names this build enforces right now. All five axes are now acted on (keep_alive +\ntopology since Stage 0-2, identity Stage 3, mode_conflict Stage 4, layout Stage 5) — the console\nreads this to know which controls are live vs. \"coming soon\" (per-backend nuance, e.g. layout\nposition apply being KWin-only, is reported per display in `/display/state`)."
           },
           "presets": {
             "type": "array",
@@ -2291,6 +2403,14 @@
           }
         }
       },
+      "GameSession": {
+        "type": "string",
+        "description": "How a session that **launches a game** (a library id on the Hello / apps.json / Decky pin) is\nserved (`design/gamemode-and-dedicated-sessions.md` §5.2). Orthogonal to the preset/lifecycle axes\n— a top-level [`DisplayPolicy`] field, NOT part of [`EffectivePolicy`], so a preset never clobbers\nit. Linux-only in effect (a launching Windows session opens into the one desktop).",
+        "enum": [
+          "auto",
+          "dedicated"
+        ]
+      },
       "GpuState": {
         "type": "object",
         "description": "Full GPU-selection state for the console: inventory, the persisted preference, what the next\nsession will use, and what is in use right now.",
@@ -2563,13 +2683,20 @@
           "paired_clients",
           "native_paired_clients",
           "pin_pending",
-          "pending_approvals"
+          "pending_approvals",
+          "kept_displays"
         ],
         "properties": {
           "audio_streaming": {
             "type": "boolean",
             "description": "True while the audio stream thread is running."
           },
+          "kept_displays": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Virtual displays being KEPT with no live session — lingering (keep-alive window) or pinned\n(`keep_alive: forever`). Non-zero means a display (and, exclusive, your physical monitors) is\nheld; the tray surfaces it + a one-click release. Active (in-use) displays are not counted.",
+            "minimum": 0
+          },
           "native_paired_clients": {
             "type": "integer",
             "format": "int32",

clients/android/README.md

@@ -16,7 +16,9 @@ couch (D-pad / gamepad focus navigation).
   pairing** (or TOFU on trusted LANs), then reconnects on a Keystore-wrapped, pinned identity.
 - **Compose UI** — Connect / Settings / Stream screens with Material You theming.
 
-Built for `arm64-v8a` + `x86_64`.
+Built for `arm64-v8a` + `armeabi-v7a` + `x86_64` — the 32-bit `armeabi-v7a` slice is what keeps the
+app installable on the many 32-bit Google TV / Android TV streamers (Walmart onn. 4K, Chromecast with
+Google TV, budget Amlogic boxes) that otherwise reject a 64-bit-only build as "not compatible".
 
 ## Get it
 
@@ -54,7 +56,7 @@ kit/              :kit — NativeBridge · native mDNS discovery · Gamepad · K
 
 **Prerequisites:** Android SDK + **NDK r30** (`30.0.14904198`), `platforms;android-37.0`,
 `build-tools;37.0.0`, **`cmake;3.22.1`** (builds libopus); **JDK 21** (AGP 9.2 runs on JDK 17–21, not
-a newer default); Rust with `rustup target add aarch64-linux-android x86_64-linux-android` and
+a newer default); Rust with `rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android` and
 `cargo install cargo-ndk`. Toolchain is pinned (AGP 9.2 · Gradle 9.4.1 · Kotlin 2.3.21 · Compose BOM
 2026.05.01 · compileSdk 37 · minSdk 31).
 

clients/android/app/build.gradle.kts

@@ -22,14 +22,34 @@ android {
         }
 
         applicationId = "io.unom.punktfunk"
-        minSdk = 31
+        // Android 9. Reaches older Android TV boxes (e.g. Amlogic streamers still on Android 9–11);
+        // the handful of API 31+ APIs we use are runtime-gated (Material You → brand palette, rumble
+        // → legacy Vibrator, NEARBY_WIFI/lights/ADPF already gated), so nothing is lost above 28.
+        minSdk = 28
         targetSdk = 36
         val vCode = (props.getProperty("VERSION_CODE") ?: System.getenv("VERSION_CODE"))
         versionCode = vCode?.toInt() ?: 1
         // versionName is the single project version, threaded from CI (a vX.Y.Z release or a
         // canary string). versionCode stays the monotonic run number (Play rejects regressions).
-        versionName = (props.getProperty("VERSION_NAME") ?: System.getenv("VERSION_NAME")) ?: "0.0.2"
-        ndk { abiFilters += listOf("arm64-v8a", "x86_64") }
+        // Local dev (no VERSION_NAME) falls back to the workspace version from the root Cargo.toml —
+        // the single source of truth — so an on-device build shows the real current version, not a
+        // stale placeholder.
+        val workspaceVersion = runCatching {
+            project.rootProject.file("../../Cargo.toml").readLines()
+                .dropWhile { !it.trim().startsWith("[workspace.package]") }
+                .firstOrNull { it.trim().startsWith("version") }
+                ?.substringAfter('=')?.trim()?.trim('"')
+        }.getOrNull()
+        versionName = (props.getProperty("VERSION_NAME") ?: System.getenv("VERSION_NAME"))
+            ?: workspaceVersion ?: "0.0.0"
+        // Ship 32-bit armeabi-v7a alongside 64-bit arm64-v8a: many Google TV / Android TV streamers
+        // (Walmart onn. 4K, Chromecast with Google TV, budget Amlogic boxes) run a 32-bit Android
+        // userspace, and because this app carries native code, Google Play (and a sideload installer)
+        // filters it as "not compatible" on those devices unless an armeabi-v7a variant is present.
+        // x86_64 stays for the emulator. Google keeps delivering to 32-bit TV devices (see the Aug
+        // 2025 "64-bit app compatibility for Google TV and Android TV" post) — the 64-bit lib is the
+        // required half; the 32-bit lib is what actually reaches the boxes people report failing.
+        ndk { abiFilters += listOf("arm64-v8a", "armeabi-v7a", "x86_64") }
     }
 
     signingConfigs {
@@ -97,9 +117,18 @@ dependencies {
     implementation("androidx.compose.ui:ui-tooling-preview")
     implementation("androidx.compose.foundation:foundation")
     implementation("androidx.compose.material3:material3")
-    implementation("androidx.compose.material:material-icons-core") // bottom-bar tab icons
+    implementation("androidx.compose.material:material-icons-core") // bottom-bar / rail tab icons
+    implementation("androidx.compose.material:material-icons-extended") // settings-category icons
     debugImplementation("androidx.compose.ui:ui-tooling")
 
+    // Cover-art loading for the game-library coverflow. Coil 2.x uses OkHttp under the hood, so we
+    // feed it the same mTLS OkHttpClient the library fetch uses (reaching the host's own art proxy).
+    implementation("io.coil-kt:coil-compose:2.7.0")
+
+    // Real backdrop blur for the floating console legends (RenderEffect on API 31+, a translucent
+    // scrim below). The gamepad UI's frosted pills sample + blur whatever scrolls behind them.
+    implementation("dev.chrisbanes.haze:haze:1.6.0")
+
     // Android TV components (we target phone + TV) land in the TV-UI milestone:
     //   implementation("androidx.tv:tv-material:1.1.0")
     // The manifest already declares leanback so the scaffold installs on TV.

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

@@ -36,12 +36,21 @@
     <application
         android:allowBackup="false"
         android:appCategory="game"
+        android:banner="@drawable/tv_banner"
         android:icon="@mipmap/ic_launcher"
         android:roundIcon="@mipmap/ic_launcher_round"
         android:label="@string/app_name"
         android:supportsRtl="true"
         android:theme="@style/Theme.PunktfunkAndroid">
 
+        <!-- Game Mode config (Android 13+): declare we support Performance mode and opt OUT of the
+             OEM interventions that would fight the negotiated stream — resolution downscaling and
+             FPS overrides. A game-streaming client renders exactly the host's mode; a platform
+             downscale/FPS-cap corrupts that. Ignored below API 33. -->
+        <meta-data
+            android:name="android.game_mode_config"
+            android:resource="@xml/game_mode_config" />
+
         <activity
             android:name=".MainActivity"
             android:exported="true"

clients/android/app/src/main/assets/GEIST-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2024 The Geist Project Authors (https://github.com/vercel/geist-font)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

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

@@ -2,40 +2,62 @@ package io.unom.punktfunk
 
 import androidx.compose.animation.AnimatedContent
 import androidx.compose.animation.AnimatedVisibility
+import androidx.compose.animation.Crossfade
 import androidx.compose.animation.ExperimentalAnimationApi
+import androidx.compose.animation.core.tween
 import androidx.compose.animation.fadeIn
 import androidx.compose.animation.fadeOut
 import androidx.compose.animation.scaleIn
 import androidx.compose.animation.scaleOut
 import androidx.compose.animation.slideInHorizontally
+import androidx.compose.animation.slideInVertically
 import androidx.compose.animation.slideOutHorizontally
+import androidx.compose.animation.slideOutVertically
 import androidx.compose.animation.togetherWith
 import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.BoxWithConstraints
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxHeight
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.systemBarsPadding
 import androidx.compose.material3.Icon
 import androidx.compose.material3.NavigationBar
 import androidx.compose.material3.NavigationBarItem
+import androidx.compose.material3.NavigationRail
+import androidx.compose.material3.NavigationRailItem
 import androidx.compose.material3.Scaffold
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.CompositionLocalProvider
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableLongStateOf
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.LocalConfiguration
 import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.platform.LocalDensity
+import androidx.compose.ui.unit.Density
+import androidx.compose.ui.unit.dp
 import io.unom.punktfunk.models.Tab
 
 @Composable
-fun App() {
+fun App(forceGamepadUi: Boolean = false) {
     val context = LocalContext.current
     val settingsStore = remember { SettingsStore(context) }
     var settings by remember { mutableStateOf(settingsStore.load()) }
     var streamHandle by remember { mutableLongStateOf(0L) } // 0 = not streaming
     var tab by remember { mutableStateOf(Tab.Connect) }
 
+    // Console (gamepad) mode mirrors the Apple client: the setting AND (a pad is attached OR this is
+    // a TV OR the dev force flag). Flips live as controllers connect/disconnect.
+    val tv = remember { isTvDevice(context) }
+    val controllerConnected by rememberControllerConnected()
+    val gamepadUi = gamepadUiActive(settings.gamepadUiEnabled, controllerConnected, tv, forceGamepadUi)
+
     AnimatedContent(
         targetState = streamHandle != 0L,
         transitionSpec = {
@@ -46,46 +68,154 @@ fun App() {
         if (isStreaming) {
             // Immersive: the stream takes the whole screen, no bottom bar.
             StreamScreen(streamHandle, micEnabled = settings.micEnabled, onDisconnect = { streamHandle = 0L })
+        } else if (gamepadUi) {
+            GamepadShell(
+                settings = settings,
+                onSettingsChange = { settings = it; settingsStore.save(it) },
+                onConnected = { streamHandle = it },
+            )
         } else {
-            Scaffold(
-                bottomBar = {
-                    NavigationBar {
-                        Tab.entries.forEach { t ->
-                            NavigationBarItem(
-                                selected = tab == t,
-                                onClick = { tab = t },
-                                icon = { Icon(t.icon, contentDescription = t.label) },
-                                label = { Text(t.label) },
-                            )
-                        }
-                    }
-                },
-            ) { innerPadding ->
-                Box(Modifier.fillMaxSize().padding(innerPadding)) {
-                    AnimatedContent(
-                        targetState = tab,
-                        transitionSpec = {
-                            if (targetState.ordinal > initialState.ordinal) {
+            // Adaptive nav: a bottom bar on phones; on tablets / large windows a side NavigationRail
+            // with its items centred vertically (the common Android tablet idiom, mirroring iPad's
+            // side navigation). A short landscape phone keeps the bottom bar (rail needs height too).
+            // Tabs slide along the axis the nav sits on: horizontally with the bottom bar (phone),
+            // vertically with the side rail (tablet), so the motion tracks the direction you moved.
+            val tabContent: @Composable (vertical: Boolean) -> Unit = { vertical ->
+                AnimatedContent(
+                    targetState = tab,
+                    transitionSpec = {
+                        val forward = targetState.ordinal > initialState.ordinal
+                        when {
+                            vertical && forward ->
+                                slideInVertically { it } + fadeIn() togetherWith
+                                        slideOutVertically { -it } + fadeOut()
+                            vertical ->
+                                slideInVertically { -it } + fadeIn() togetherWith
+                                        slideOutVertically { it } + fadeOut()
+                            forward ->
                                 slideInHorizontally { it } + fadeIn() togetherWith
                                         slideOutHorizontally { -it } + fadeOut()
-                            } else {
+                            else ->
                                 slideInHorizontally { -it } + fadeIn() togetherWith
                                         slideOutHorizontally { it } + fadeOut()
+                        }
+                    },
+                    label = "TabTransition"
+                ) { targetTab ->
+                    when (targetTab) {
+                        Tab.Connect -> ConnectScreen(settings = settings, onConnected = { streamHandle = it })
+                        Tab.Settings -> SettingsScreen(
+                            initial = settings,
+                            onChange = { settings = it; settingsStore.save(it) },
+                            onBack = { tab = Tab.Connect },
+                        )
+                    }
+                }
+            }
+
+            BoxWithConstraints(Modifier.fillMaxSize()) {
+                if (maxWidth >= 600.dp && maxHeight >= 480.dp) {
+                    Row(Modifier.fillMaxSize()) {
+                        NavigationRail(Modifier.fillMaxHeight()) {
+                            Spacer(Modifier.weight(1f)) // centre the rail items vertically
+                            Tab.entries.forEach { t ->
+                                NavigationRailItem(
+                                    selected = tab == t,
+                                    onClick = { tab = t },
+                                    icon = { Icon(t.icon, contentDescription = t.label) },
+                                    label = { Text(t.label) },
+                                )
+                            }
+                            Spacer(Modifier.weight(1f))
+                        }
+                        // The rail handles its own insets; the content pane insets itself (the screens
+                        // don't, since they used to rely on the Scaffold's padding).
+                        Box(Modifier.weight(1f).fillMaxHeight().systemBarsPadding()) { tabContent(true) }
+                    }
+                } else {
+                    Scaffold(
+                        bottomBar = {
+                            NavigationBar {
+                                Tab.entries.forEach { t ->
+                                    NavigationBarItem(
+                                        selected = tab == t,
+                                        onClick = { tab = t },
+                                        icon = { Icon(t.icon, contentDescription = t.label) },
+                                        label = { Text(t.label) },
+                                    )
+                                }
                             }
                         },
-                        label = "TabTransition"
-                    ) { targetTab ->
-                        when (targetTab) {
-                            Tab.Connect -> ConnectScreen(settings = settings, onConnected = { streamHandle = it })
-                            Tab.Settings -> SettingsScreen(
-                                initial = settings,
-                                onChange = { settings = it; settingsStore.save(it) },
-                                onBack = { tab = Tab.Connect },
-                            )
-                        }
+                    ) { innerPadding ->
+                        Box(Modifier.fillMaxSize().padding(innerPadding)) { tabContent(false) }
                     }
                 }
             }
         }
     }
 }
+
+/** Which console screen the gamepad shell is showing. */
+private enum class GamepadScreen { Home, Settings, Library }
+
+/**
+ * The console (gamepad) shell — the Android mirror of the Apple client's ContentView gamepad branch:
+ * a full-screen host carousel with X → Settings and Y → a saved host's library, all sharing
+ * [ConnectScreen]'s connect logic. No bottom bar; navigation is button-driven.
+ */
+@Composable
+fun GamepadShell(
+    settings: Settings,
+    onSettingsChange: (Settings) -> Unit,
+    onConnected: (Long) -> Unit,
+) {
+    val context = LocalContext.current
+    var screen by remember { mutableStateOf(GamepadScreen.Home) }
+    var libraryHost by remember { mutableStateOf<io.unom.punktfunk.kit.security.KnownHost?>(null) }
+
+    // On a TV, shrink the 10-foot UI so its elements aren't oversized. Density-aware: expand the
+    // effective dp footprint to at least CONSOLE_TV_MIN_WIDTH_DP (→ smaller elements) ONLY when the
+    // panel reports fewer dp than that; a low-density TV that's already spacious, and every phone /
+    // tablet, keep their real density unchanged. This is the "based on pixel density" scale the layout
+    // wanted — one uniform factor across text, cards, spacing, and insets.
+    val isTv = remember { isTvDevice(context) }
+    val baseDensity = LocalDensity.current
+    val screenWidthPx = LocalConfiguration.current.screenWidthDp * baseDensity.density
+    val fitDensity = screenWidthPx / CONSOLE_TV_MIN_WIDTH_DP
+    val consoleDensity = if (isTv && fitDensity < baseDensity.density) fitDensity else baseDensity.density
+
+    CompositionLocalProvider(LocalDensity provides Density(consoleDensity, baseDensity.fontScale)) {
+    // Cross-fade between console screens so switches are smooth. Each slot's controller nav is gated
+    // on being the CURRENT target (`s == screen`), so during the fade only the incoming screen drives
+    // the pad. All screens pin their legend at the same ConsoleLegendInset, so it reads as fixed while
+    // the content behind it fades.
+    Crossfade(targetState = screen, animationSpec = tween(240), label = "consoleScreen") { s ->
+        when (s) {
+            GamepadScreen.Home -> ConnectScreen(
+                settings = settings,
+                onConnected = onConnected,
+                gamepadUi = true,
+                onOpenSettings = { screen = GamepadScreen.Settings },
+                onOpenLibrary = { host -> libraryHost = host; screen = GamepadScreen.Library },
+                navGate = s == screen,
+            )
+            GamepadScreen.Settings -> GamepadSettingsScreen(
+                initial = settings,
+                onChange = onSettingsChange,
+                onBack = { screen = GamepadScreen.Home },
+                navActive = s == screen,
+            )
+            GamepadScreen.Library -> libraryHost?.let { host ->
+                LibraryScreen(
+                    host = host,
+                    onBack = { screen = GamepadScreen.Home; libraryHost = null },
+                    navActive = s == screen,
+                )
+            } ?: run { screen = GamepadScreen.Home }
+        }
+    }
+    }
+}
+
+/** Minimum effective dp width the console UI targets on a TV (bigger → the 10-foot UI shrinks). */
+private const val CONSOLE_TV_MIN_WIDTH_DP = 1180f

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

@@ -9,7 +9,9 @@ import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.height
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.rememberScrollState
 import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.foundation.verticalScroll
 import androidx.compose.material3.AlertDialog
 import androidx.compose.material3.Button
 import androidx.compose.material3.CircularProgressIndicator
@@ -33,6 +35,7 @@ import androidx.compose.ui.unit.dp
 import io.unom.punktfunk.kit.NativeBridge
 import io.unom.punktfunk.kit.security.ClientIdentity
 import io.unom.punktfunk.kit.security.KnownHost
+import io.unom.punktfunk.kit.security.KnownHostStore
 import io.unom.punktfunk.models.PendingTrust
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
@@ -320,32 +323,75 @@ internal fun AwaitingApprovalDialog(hostLabel: String, onCancel: () -> Unit) {
 }
 
 /**
- * Rename a saved host's label (discovered hosts are named by mDNS; this is how you give one a
- * friendly name like "Living Room" after pairing). Keyed by the host so reopening resets the field.
+ * Edit a saved host: name, address, port, and the Wake-on-LAN MAC. The MAC is auto-learned from the
+ * host's mDNS advert while it's online, but this is where you can enter or correct it (e.g. to wake a
+ * host you've only ever reached by address). [suggestedMacs] prefills the field from the live advert
+ * when nothing's been learned yet. Keyed by the host so reopening resets the fields. Mirrors the
+ * Apple client's edit form.
  */
 @Composable
-internal fun RenameHostDialog(
+internal fun EditHostDialog(
     target: KnownHost,
-    onRename: (String) -> Unit,
+    suggestedMacs: List<String>,
+    onSave: (KnownHost) -> Unit,
     onDismiss: () -> Unit,
 ) {
-    var newName by remember(target) { mutableStateOf(target.name) }
+    var name by remember(target) { mutableStateOf(target.name) }
+    var address by remember(target) { mutableStateOf(target.address) }
+    var port by remember(target) { mutableStateOf(target.port.toString()) }
+    var mac by remember(target) {
+        mutableStateOf(target.mac.ifEmpty { suggestedMacs }.joinToString(", "))
+    }
     AlertDialog(
         onDismissRequest = onDismiss,
-        title = { Text("Rename host") },
+        title = { Text("Edit host") },
         text = {
-            OutlinedTextField(
-                value = newName,
-                onValueChange = { newName = it },
-                label = { Text("Name") },
-                placeholder = { Text(target.address) },
-                singleLine = true,
-            )
+            Column(
+                modifier = Modifier.verticalScroll(rememberScrollState()),
+                verticalArrangement = Arrangement.spacedBy(12.dp),
+            ) {
+                OutlinedTextField(
+                    value = name,
+                    onValueChange = { name = it },
+                    label = { Text("Name") },
+                    placeholder = { Text(target.address) },
+                    singleLine = true,
+                )
+                OutlinedTextField(
+                    value = address,
+                    onValueChange = { address = it },
+                    label = { Text("Address") },
+                    singleLine = true,
+                )
+                OutlinedTextField(
+                    value = port,
+                    onValueChange = { v -> port = v.filter { it.isDigit() }.take(5) },
+                    label = { Text("Port") },
+                    singleLine = true,
+                    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
+                )
+                OutlinedTextField(
+                    value = mac,
+                    onValueChange = { mac = it },
+                    label = { Text("Wake-on-LAN MAC") },
+                    placeholder = { Text("auto-filled when the host is seen") },
+                    singleLine = true,
+                )
+            }
         },
         confirmButton = {
             TextButton(
-                enabled = newName.isNotBlank(),
-                onClick = { onRename(newName.trim()) },
+                enabled = address.isNotBlank(),
+                onClick = {
+                    onSave(
+                        target.copy(
+                            name = name.trim().ifEmpty { target.address },
+                            address = address.trim(),
+                            port = port.toIntOrNull() ?: target.port,
+                            mac = KnownHostStore.parseMacs(mac),
+                        ),
+                    )
+                },
             ) { Text("Save") }
         },
         dismissButton = {

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

@@ -84,7 +84,17 @@ private class RequestAccessState(val target: PendingTrust) {
 }
 
 @Composable
-fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
+fun ConnectScreen(
+    settings: Settings,
+    onConnected: (Long) -> Unit,
+    // Console (gamepad) mode: render the host carousel instead of the touch grid, sharing all of this
+    // screen's connect/trust/discovery logic. [onOpenSettings]/[onOpenLibrary] are the X/Y actions the
+    // gamepad shell owns (the touch UI reaches Settings via the bottom bar and has no library button).
+    gamepadUi: Boolean = false,
+    onOpenSettings: () -> Unit = {},
+    onOpenLibrary: (KnownHost) -> Unit = {},
+    navGate: Boolean = true, // false while the console home is cross-fading out
+) {
     val scope = rememberCoroutineScope()
     val context = LocalContext.current
     var host by remember { mutableStateOf("") }
@@ -124,6 +134,10 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
     val identityStore = remember { IdentityStore(context) }
     val knownHostStore = remember { KnownHostStore(context) }
     var savedHosts by remember { mutableStateOf(knownHostStore.all()) }
+    // Wakes a sleeping saved host and waits for it to reappear on mDNS before dialing (its overlay
+    // rides over both the touch and console home). Fire-and-forget WoL isn't enough — a cold boot can
+    // take a minute-plus to advertise again.
+    val waker = remember { WakeController(scope) }
     // Learn wake MAC(s) from live adverts for hosts we've saved (parity with the desktop clients),
     // so we can Wake-on-LAN them once they sleep. Runs only when the discovered set changes; the
     // prefs write is guarded (no-op when unchanged), and we refresh the saved list only if a MAC
@@ -156,8 +170,11 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
     var pendingTrust by remember { mutableStateOf<PendingTrust?>(null) }
     // A no-PIN "request access" connect in flight (the cancelable "Waiting for approval…" dialog).
     var awaiting by remember { mutableStateOf<RequestAccessState?>(null) }
-    // A saved host whose label is being edited (the Rename dialog).
-    var renameTarget by remember { mutableStateOf<KnownHost?>(null) }
+    // A saved host being edited (name / address / port / MAC).
+    var editTarget by remember { mutableStateOf<KnownHost?>(null) }
+    // A saved host whose console options menu (Wake / Edit / Forget) is open — reached with Up on the
+    // carousel (the console counterpart of the touch host card's overflow menu).
+    var optionsTarget by remember { mutableStateOf<KnownHost?>(null) }
 
     // Discovered hosts not already saved — a saved host (paired or TOFU) belongs in "Saved hosts",
     // not also in "Discovered", so we hide the overlap (matched by fingerprint when both carry it, so
@@ -184,25 +201,16 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
         }
     }
 
-    // Issue the actual connect with identity + (optional) pin. On a TOFU connect (pinHex null),
-    // pin the fingerprint the host presented (as an unpaired known host) so the next connect goes
-    // straight through and it appears in the saved-hosts list.
-    fun doConnect(targetHost: String, targetPort: Int, name: String, pinHex: String?) {
-        val id = identity
-        if (id == null) {
+    // The actual dial (identity already ready). On a TOFU connect (pinHex null), pin the fingerprint
+    // the host presented (as an unpaired known host) so the next connect goes straight through and it
+    // appears in the saved-hosts list.
+    fun doConnectDirect(targetHost: String, targetPort: Int, name: String, pinHex: String?) {
+        val id = identity ?: run {
             status = "Identity not ready yet — try again in a moment"
             return
         }
         connecting = true
         status = "Connecting to $targetHost:$targetPort…"
-        // Auto-wake: reconnecting to a saved host that may be asleep. If we learned its MAC while it
-        // was online and it isn't currently advertising, fire a magic packet first — the connect's
-        // own timeout gives a woken host time to come up (harmless if it's already awake).
-        knownHostStore.get(targetHost, targetPort)?.mac
-            ?.takeIf { it.isNotEmpty() && discovered.none { d -> d.host == targetHost && d.port == targetPort } }
-            ?.let { macs ->
-                scope.launch(Dispatchers.IO) { NativeBridge.nativeWakeOnLan(macs.joinToString(","), targetHost) }
-            }
         discovery.stop() // free the Wi-Fi radio before the stream session
         scope.launch {
             val handle = connectNative(id, targetHost, targetPort, pinHex ?: "", CONNECT_TIMEOUT_MS)
@@ -222,6 +230,47 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
         }
     }
 
+    // Wake-aware connect. If the target is a saved host with a learned MAC that ISN'T currently
+    // advertising (asleep/off), wake it and WAIT for it to reappear on mDNS (WakeController shows the
+    // "Waking…" overlay) before dialing — discovery stays running meanwhile so we can see it come
+    // back. A fire-and-forget packet + the connect timeout wasn't enough for a cold boot. Otherwise
+    // dial straight through.
+    fun doConnect(targetHost: String, targetPort: Int, name: String, pinHex: String?) {
+        if (identity == null) {
+            status = "Identity not ready yet — try again in a moment"
+            return
+        }
+        val kh = knownHostStore.get(targetHost, targetPort)
+        val macs = kh?.mac ?: emptyList()
+        // "Up" = a live advert that is THIS host — matched by fingerprint first (so it survives a DHCP
+        // address change on a cold boot), else by address:port. Returns the CURRENT advert so we can
+        // dial its live address rather than the stale saved one.
+        fun liveAdvert(): DiscoveredHost? =
+            if (kh != null) discovered.firstOrNull { kh.matches(it) }
+            else discovered.firstOrNull { it.host == targetHost && it.port == targetPort }
+        if (macs.isNotEmpty() && liveAdvert() == null) {
+            waker.start(
+                hostName = name,
+                connectsAfter = true,
+                macs = macs,
+                lastIp = targetHost,
+                isOnline = { liveAdvert() != null },
+                onOnline = {
+                    val live = liveAdvert()
+                    // Woke back on a new address? Re-key the saved record so it (and future connects)
+                    // point at the live one, then dial there.
+                    if (live != null && kh != null && (live.host != kh.address || live.port != kh.port)) {
+                        knownHostStore.update(kh.address, kh.port, kh.copy(address = live.host, port = live.port))
+                        savedHosts = knownHostStore.all()
+                    }
+                    doConnectDirect(live?.host ?: targetHost, live?.port ?: targetPort, name, pinHex)
+                },
+            )
+        } else {
+            doConnectDirect(targetHost, targetPort, name, pinHex)
+        }
+    }
+
     // The no-PIN "request access" path (delegated approval): open a normal identified connect that
     // the host PARKS until the operator clicks Approve in its console/web UI, showing a cancelable
     // "Waiting for approval…" dialog meanwhile. The SAME connection is admitted on approval (no
@@ -304,7 +353,62 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
 
     var showManualSheet by remember { mutableStateOf(false) }
 
-    Box(Modifier.fillMaxSize()) {
+    if (gamepadUi) {
+        // Console mode: the host carousel (saved → discovered → Add Host), driven by the pad. Shares
+        // every action above; the trailing Add Host tile opens the same manual-entry sheet.
+        val tiles = buildList {
+            savedHosts.forEach { kh ->
+                add(
+                    HomeTile(
+                        id = "saved-${kh.address}:${kh.port}",
+                        title = kh.name,
+                        subtitle = "${kh.address}:${kh.port}",
+                        filled = true,
+                        online = discovered.any { it.host == kh.address && it.port == kh.port },
+                        paired = kh.paired,
+                        knownHost = kh,
+                        activate = { connect(kh.address, kh.port) },
+                    ),
+                )
+            }
+            discoveredUnsaved.forEach { dh ->
+                add(
+                    HomeTile(
+                        id = "disc-${dh.host}:${dh.port}",
+                        title = dh.name,
+                        subtitle = "${dh.host}:${dh.port}",
+                        online = true,
+                        activate = { connect(dh.host, dh.port, dh) },
+                    ),
+                )
+            }
+            add(
+                HomeTile(
+                    id = "add",
+                    title = "Add Host",
+                    subtitle = "Register a host by address",
+                    isAdd = true,
+                    activate = { showManualSheet = true },
+                ),
+            )
+        }
+        GamepadHome(
+            tiles = tiles,
+            libraryEnabled = settings.libraryEnabled,
+            controllerName = io.unom.punktfunk.kit.Gamepad.firstPad()?.name,
+            // Stop the carousel from consuming the pad while a sheet/dialog/overlay owns the screen,
+            // while a connect is in flight (else a second A launches a concurrent connect that leaks a
+            // handle — the touch grid guards the same way with enabled=!connecting), or while the whole
+            // console home is cross-fading out.
+            navActive = navGate && !connecting && !showManualSheet && pendingTrust == null &&
+                awaiting == null && editTarget == null && optionsTarget == null && waker.waking == null,
+            onActivate = { it.activate() },
+            onOpenLibrary = { it.knownHost?.let(onOpenLibrary) },
+            onOpenSettings = onOpenSettings,
+            onOptions = { it.knownHost?.let { kh -> optionsTarget = kh } },
+        )
+    } else {
+        Box(Modifier.fillMaxSize()) {
         LazyVerticalGrid(
             columns = GridCells.Adaptive(minSize = 160.dp),
             modifier = Modifier.fillMaxSize(),
@@ -385,13 +489,22 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
                             knownHostStore.remove(kh.address, kh.port)
                             savedHosts = knownHostStore.all()
                         },
-                        onRename = { renameTarget = kh },
-                        // Explicit wake: offered only when the host is offline and we have a MAC to
-                        // target (a tap-to-connect already auto-wakes an offline saved host).
-                        onWake = if (kh.mac.isNotEmpty() &&
-                            discovered.none { it.host == kh.address && it.port == kh.port }
-                        ) {
-                            { scope.launch(Dispatchers.IO) { NativeBridge.nativeWakeOnLan(kh.mac.joinToString(","), kh.address) } }
+                        onEdit = { editTarget = kh },
+                        // Explicit wake-only: offered when the host is offline and we have a MAC. Runs
+                        // through the WakeController so it shows the "Waking…" overlay and waits for
+                        // the host to come online (matched by fingerprint, so a new DHCP address on a
+                        // cold boot still counts as "up") rather than firing a single silent packet.
+                        onWake = if (kh.mac.isNotEmpty() && discovered.none { kh.matches(it) }) {
+                            {
+                                waker.start(
+                                    hostName = kh.name,
+                                    connectsAfter = false,
+                                    macs = kh.mac,
+                                    lastIp = kh.address,
+                                    isOnline = { discovered.any { kh.matches(it) } },
+                                    onOnline = {},
+                                )
+                            }
                         } else {
                             null
                         },
@@ -451,80 +564,134 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
                 .align(Alignment.BottomEnd)
                 .padding(20.dp),
         )
+        }
     }
 
     if (showManualSheet) {
-        AddHostSheet(
-            hostName = hostName,
-            onHostNameChange = { hostName = it },
-            host = host,
-            onHostChange = { host = it },
-            port = port,
-            onPortChange = { port = it },
-            connecting = connecting,
-            modeLabel = "$w×$h@$hz",
-            onDismiss = { showManualSheet = false },
-            onConnect = { h2, p, n -> connect(h2, p, manualName = n) },
-        )
-    }
-
-    pendingTrust?.let { pt ->
-        when (pt.kind) {
-            PendingTrust.Kind.TRUST_NEW -> TrustNewHostDialog(
-                pt = pt,
-                onTrust = { pendingTrust = null; doConnect(pt.host, pt.port, pt.name, null) },
-                onPairInstead = { pendingTrust = pt.copy(kind = PendingTrust.Kind.PAIR) },
-                onDismiss = { pendingTrust = null },
-            )
-            PendingTrust.Kind.FP_CHANGED -> FingerprintChangedDialog(
-                pt = pt,
-                onRepair = { pendingTrust = pt.copy(kind = PendingTrust.Kind.PAIR) },
-                onDismiss = { pendingTrust = null },
-            )
-            PendingTrust.Kind.REQUEST_ACCESS -> RequestAccessDialog(
-                pt = pt,
-                onRequestAccess = { pendingTrust = null; requestAccess(pt) },
-                onUsePin = { pendingTrust = pt.copy(kind = PendingTrust.Kind.PAIR) },
-                onDismiss = { pendingTrust = null },
-            )
-            PendingTrust.Kind.PAIR -> PairPinDialog(
-                pt = pt,
-                identity = identity,
-                onPaired = { fp ->
-                    // Verified host fp — save as a paired known host, then connect pinned.
-                    knownHostStore.save(KnownHost(pt.host, pt.port, pt.name, fp, paired = true))
-                    savedHosts = knownHostStore.all()
-                    pendingTrust = null
-                    doConnect(pt.host, pt.port, pt.name, fp)
+        if (gamepadUi) {
+            // Console add-host: field list + on-screen controller keyboard. "Add" connects (which
+            // saves the host on TOFU/pair), exactly like the touch sheet's Connect.
+            GamepadAddHostScreen(
+                onAdd = { n, addr, p ->
+                    showManualSheet = false
+                    connect(addr, p, manualName = n)
                 },
-                onDismiss = { pendingTrust = null },
+                onDismiss = { showManualSheet = false },
+            )
+        } else {
+            AddHostSheet(
+                hostName = hostName,
+                onHostNameChange = { hostName = it },
+                host = host,
+                onHostChange = { host = it },
+                port = port,
+                onPortChange = { port = it },
+                connecting = connecting,
+                modeLabel = "$w×$h@$hz",
+                onDismiss = { showManualSheet = false },
+                onConnect = { h2, p, n -> connect(h2, p, manualName = n) },
             )
         }
     }
 
+    pendingTrust?.let { pt ->
+        // Same trust/pairing logic, console-styled + controller-navigable in gamepad mode.
+        val onPair = { pendingTrust = pt.copy(kind = PendingTrust.Kind.PAIR) }
+        val onSavePaired = { fp: String ->
+            knownHostStore.save(KnownHost(pt.host, pt.port, pt.name, fp, paired = true))
+            savedHosts = knownHostStore.all()
+            pendingTrust = null
+            doConnect(pt.host, pt.port, pt.name, fp)
+        }
+        when (pt.kind) {
+            PendingTrust.Kind.TRUST_NEW ->
+                if (gamepadUi) GamepadTrustNewDialog(pt, { pendingTrust = null; doConnect(pt.host, pt.port, pt.name, null) }, onPair, { pendingTrust = null })
+                else TrustNewHostDialog(pt, { pendingTrust = null; doConnect(pt.host, pt.port, pt.name, null) }, onPair, { pendingTrust = null })
+            PendingTrust.Kind.FP_CHANGED ->
+                if (gamepadUi) GamepadFingerprintChangedDialog(pt, onPair, { pendingTrust = null })
+                else FingerprintChangedDialog(pt, onPair, { pendingTrust = null })
+            PendingTrust.Kind.REQUEST_ACCESS ->
+                if (gamepadUi) GamepadRequestAccessDialog(pt, { pendingTrust = null; requestAccess(pt) }, onPair, { pendingTrust = null })
+                else RequestAccessDialog(pt, { pendingTrust = null; requestAccess(pt) }, onPair, { pendingTrust = null })
+            PendingTrust.Kind.PAIR ->
+                if (gamepadUi) GamepadPairPinDialog(pt, identity, onSavePaired, { pendingTrust = null })
+                else PairPinDialog(pt, identity, onSavePaired, { pendingTrust = null })
+        }
+    }
+
     awaiting?.let { req ->
-        AwaitingApprovalDialog(
-            hostLabel = req.target.name,
-            onCancel = {
-                req.cancelled.set(true)
-                awaiting = null
-                connecting = false
-                discovery.start() // the request may still be pending on the host; keep scanning
+        val onCancel = {
+            req.cancelled.set(true)
+            awaiting = null
+            connecting = false
+            discovery.start() // the request may still be pending on the host; keep scanning
+        }
+        if (gamepadUi) GamepadAwaitingApprovalDialog(req.target.name, onCancel)
+        else AwaitingApprovalDialog(hostLabel = req.target.name, onCancel = onCancel)
+    }
+
+    // Console host options (Up on a saved carousel tile): Wake / Edit / Forget.
+    optionsTarget?.let { kh ->
+        val offline = discovered.none { kh.matches(it) }
+        GamepadHostOptionsDialog(
+            hostName = kh.name,
+            canWake = kh.mac.isNotEmpty() && offline,
+            onWake = {
+                optionsTarget = null
+                waker.start(
+                    hostName = kh.name, connectsAfter = false, macs = kh.mac, lastIp = kh.address,
+                    isOnline = { discovered.any { kh.matches(it) } },
+                    onOnline = {},
+                )
             },
+            // A saved host always has a library (it's a knownHost) → offer it when the setting's on,
+            // so a TV remote reaches the library here instead of via the Y face button.
+            onLibrary = if (settings.libraryEnabled) {
+                { optionsTarget = null; onOpenLibrary(kh) }
+            } else {
+                null
+            },
+            onEdit = { optionsTarget = null; editTarget = kh },
+            onForget = {
+                knownHostStore.remove(kh.address, kh.port)
+                savedHosts = knownHostStore.all()
+                optionsTarget = null
+            },
+            onDismiss = { optionsTarget = null },
         )
     }
 
-    renameTarget?.let { kh ->
-        RenameHostDialog(
-            target = kh,
-            onRename = { newName ->
-                knownHostStore.rename(kh.address, kh.port, newName)
-                savedHosts = knownHostStore.all()
-                renameTarget = null
-            },
-            onDismiss = { renameTarget = null },
-        )
+    editTarget?.let { kh ->
+        // Prefill a not-yet-learned MAC from the host's live advert, mirroring Apple's
+        // `discovery.hosts.first { host.matches($0) }?.macAddresses`.
+        val suggested = discovered.firstOrNull { kh.matches(it) }?.mac ?: emptyList()
+        val onSaveHost: (KnownHost) -> Unit = { updated ->
+            knownHostStore.update(kh.address, kh.port, updated)
+            savedHosts = knownHostStore.all()
+            editTarget = null
+        }
+        if (gamepadUi) {
+            // Console edit: the same field list + on-screen keyboard as Add-Host, seeded from the
+            // host with an extra MAC row; the action SAVES instead of connecting.
+            GamepadAddHostScreen(
+                onAdd = { _, _, _ -> },
+                onDismiss = { editTarget = null },
+                editHost = kh,
+                suggestedMacs = suggested,
+                onSave = onSaveHost,
+            )
+        } else {
+            EditHostDialog(
+                target = kh,
+                suggestedMacs = suggested,
+                onSave = onSaveHost,
+                onDismiss = { editTarget = null },
+            )
+        }
     }
+
+    // Topmost: the "Waking…" overlay rides over both the touch grid and the console home.
+    WakeOverlay(waker, gamepadUi)
 }
 
 /**

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

@@ -1,6 +1,7 @@
 package io.unom.punktfunk
 
 import android.hardware.input.InputManager
+import android.os.Build
 import android.os.CombinedVibration
 import android.os.Handler
 import android.os.Looper
@@ -244,7 +245,7 @@ private fun PadRow(dev: InputDevice, forwarded: Boolean, gamepadSetting: Int) {
                 style = MaterialTheme.typography.bodySmall,
                 color = MaterialTheme.colorScheme.onSurfaceVariant,
             )
-            val canRumble = dev.vibratorManager.vibratorIds.isNotEmpty()
+            val canRumble = deviceHasVibrator(dev)
             if (canRumble) {
                 OutlinedButton(onClick = { testRumble(dev) }) { Text("Test rumble") }
             } else {
@@ -318,11 +319,27 @@ private fun Group(title: String, content: @Composable ColumnScope.() -> Unit) {
     }
 }
 
+/** Whether the controller reports a rumble motor — via VibratorManager (API 31+) or the legacy Vibrator. */
+private fun deviceHasVibrator(dev: InputDevice): Boolean =
+    if (Build.VERSION.SDK_INT >= 31) {
+        dev.vibratorManager.vibratorIds.isNotEmpty()
+    } else {
+        @Suppress("DEPRECATION")
+        dev.vibrator.hasVibrator()
+    }
+
 private fun testRumble(dev: InputDevice) {
-    val vm = dev.vibratorManager
-    if (vm.vibratorIds.isEmpty()) return
     runCatching {
-        vm.vibrate(CombinedVibration.createParallel(VibrationEffect.createOneShot(300, 200)))
+        if (Build.VERSION.SDK_INT >= 31) {
+            val vm = dev.vibratorManager
+            if (vm.vibratorIds.isEmpty()) return
+            vm.vibrate(CombinedVibration.createParallel(VibrationEffect.createOneShot(300, 200)))
+        } else {
+            @Suppress("DEPRECATION")
+            val v = dev.vibrator
+            if (!v.hasVibrator()) return
+            v.vibrate(VibrationEffect.createOneShot(300, 200))
+        }
     }
 }
 

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

@@ -0,0 +1,467 @@
+package io.unom.punktfunk
+
+import android.content.res.Configuration
+import androidx.activity.compose.BackHandler
+import androidx.compose.animation.core.animateFloatAsState
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.interaction.MutableInteractionSource
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxHeight
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.systemBarsPadding
+import androidx.compose.foundation.layout.widthIn
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.Button
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.ui.focus.FocusRequester
+import androidx.compose.ui.focus.focusRequester
+import androidx.compose.ui.platform.LocalConfiguration
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.text.input.KeyboardType
+import dev.chrisbanes.haze.HazeState
+import dev.chrisbanes.haze.hazeSource
+import io.unom.punktfunk.kit.security.KnownHost
+import io.unom.punktfunk.kit.security.KnownHostStore
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableIntStateOf
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.graphicsLayer
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.Dp
+import androidx.compose.ui.unit.dp
+
+// The gamepad-driven "Add Host" screen — the Android mirror of the Apple client's GamepadAddHostView
+// + GamepadKeyboard: three field rows (name / address / port) plus an Add action, navigated with the
+// vertical focus list; A on a field opens the on-screen keyboard so a host can be registered end to
+// end from the couch. One GamepadNavEffect2D owns BOTH modes (list vs keyboard) so they never fight
+// over the shared input probes. B peels one layer: close the keyboard, then cancel the screen.
+
+// Keyboard grid: digits, qwerty letters, hostname/address punctuation, then space / delete / done.
+private val KB_CHAR_ROWS = listOf("1234567890", "qwertyuiop", "asdfghjkl-", "zxcvbnm._:")
+private const val KB_ACTIONS_ROW = 4 // index of the [space, delete, done] row
+private const val KB_ROWS = 5
+
+private class Field(val id: String, val label: String, val value: String, val placeholder: String)
+
+@Composable
+fun GamepadAddHostScreen(
+    onAdd: (name: String, address: String, port: Int) -> Unit,
+    onDismiss: () -> Unit,
+    // Non-null → EDIT mode: fields seed from this host, a MAC row is added, and the action SAVES the
+    // edited record via [onSave] instead of connecting. [suggestedMacs] prefills a not-yet-learned MAC.
+    editHost: KnownHost? = null,
+    suggestedMacs: List<String> = emptyList(),
+    onSave: ((KnownHost) -> Unit)? = null,
+) {
+    val context = LocalContext.current
+    val isTv = remember { isTvDevice(context) }
+    val isEdit = editHost != null
+    val title = if (isEdit) "Edit Host" else "Add Host"
+    val actionLabel = if (isEdit) "Save" else "Add Host"
+    var name by remember { mutableStateOf(editHost?.name ?: "") }
+    var address by remember { mutableStateOf(editHost?.address ?: "") }
+    var port by remember { mutableStateOf(editHost?.port?.toString() ?: "9777") }
+    var mac by remember { mutableStateOf(editHost?.mac?.ifEmpty { suggestedMacs }?.joinToString(", ") ?: "") }
+    val canAdd = address.isNotBlank() && (port.toIntOrNull() ?: 0) > 0
+    fun commit() {
+        if (isEdit && editHost != null && onSave != null) {
+            onSave(
+                editHost.copy(
+                    name = name.trim().ifEmpty { editHost.address },
+                    address = address.trim(),
+                    port = port.toIntOrNull() ?: editHost.port,
+                    mac = KnownHostStore.parseMacs(mac),
+                ),
+            )
+        } else {
+            onAdd(name.trim(), address.trim(), port.toIntOrNull() ?: 9777)
+        }
+    }
+
+    // On a TV the OS provides a leanback on-screen keyboard for text fields, so use real (focusable)
+    // text fields + the system IME there. Our controller keyboard is for a phone-with-controller,
+    // where the phone's own soft keyboard needs a touch a pad can't provide.
+    if (isTv) {
+        TvAddHostForm(
+            title = title, actionLabel = actionLabel,
+            name = name, onName = { name = it },
+            address = address, onAddress = { address = it },
+            port = port, onPort = { port = it.filter(Char::isDigit).take(5) },
+            mac = if (isEdit) mac else null, onMac = { mac = it },
+            canAdd = canAdd,
+            onAdd = { commit() },
+            onDismiss = onDismiss,
+        )
+        return
+    }
+
+    var focus by remember { mutableIntStateOf(1) } // start on Address
+    var editing by remember { mutableStateOf<String?>(null) } // field id being typed, or null
+    var kbRow by remember { mutableIntStateOf(1) }
+    var kbCol by remember { mutableIntStateOf(0) }
+    val landscape = LocalConfiguration.current.orientation == Configuration.ORIENTATION_LANDSCAPE
+    val hazeState = remember { HazeState() }
+
+    val fields = buildList {
+        add(Field("name", "Name", name, "Optional — e.g. Living Room"))
+        add(Field("address", "Address", address, "IP or hostname"))
+        add(Field("port", "Port", port, "9777"))
+        if (isEdit) add(Field("mac", "Wake MAC", mac, "auto-filled when the host is seen"))
+    }
+    val actionIndex = fields.size // the Save/Add action sits just after the last field
+
+    fun openKeyboard(id: String) { editing = id; kbRow = 1; kbCol = 0 }
+    fun closeKeyboard() { editing = null }
+    fun editField(id: String, transform: (String) -> String) {
+        when (id) {
+            "name" -> name = transform(name)
+            "address" -> address = transform(address)
+            "port" -> port = transform(port).take(5)
+            "mac" -> mac = transform(mac)
+        }
+    }
+    fun allowed(id: String, c: Char): Boolean = when (id) {
+        "port" -> c.isDigit()
+        "address" -> c != ' '
+        else -> true
+    }
+    fun activateField() {
+        if (focus == actionIndex) {
+            if (canAdd) commit() else { focus = 1; openKeyboard("address") }
+        } else {
+            openKeyboard(fields[focus].id)
+        }
+    }
+    fun pressKey() {
+        val id = editing ?: return
+        if (kbRow < KB_ACTIONS_ROW) {
+            val c = KB_CHAR_ROWS[kbRow][kbCol.coerceIn(0, KB_CHAR_ROWS[kbRow].lastIndex)]
+            if (allowed(id, c)) editField(id) { it + c }
+        } else when (kbCol) {
+            0 -> if (allowed(id, ' ')) editField(id) { "$it " }
+            1 -> editField(id) { it.dropLast(1) }
+            else -> closeKeyboard()
+        }
+    }
+
+    BackHandler { if (editing != null) closeKeyboard() else onDismiss() }
+    GamepadNavEffect2D(
+        active = true,
+        onDirection = { dir ->
+            if (editing == null) {
+                when (dir) {
+                    NavDir.UP -> if (focus > 0) focus--
+                    NavDir.DOWN -> if (focus < actionIndex) focus++
+                    else -> {}
+                }
+            } else {
+                when (dir) {
+                    NavDir.UP -> if (kbRow > 0) { kbRow--; kbCol = kbCol.coerceIn(0, rowCols(kbRow) - 1) }
+                    NavDir.DOWN -> if (kbRow < KB_ROWS - 1) { kbRow++; kbCol = kbCol.coerceIn(0, rowCols(kbRow) - 1) }
+                    NavDir.LEFT -> if (kbCol > 0) kbCol--
+                    NavDir.RIGHT -> if (kbCol < rowCols(kbRow) - 1) kbCol++
+                }
+            }
+        },
+        onActivate = { if (editing == null) activateField() else pressKey() },
+        onTertiary = { if (editing != null) editField(editing!!) { it.dropLast(1) } },
+        onSecondary = { if (editing != null) closeKeyboard() },
+    )
+
+    val onFieldClick: (Int) -> Unit = { i -> if (focus == i) activateField() else focus = i }
+    val onAddClick: () -> Unit = { if (focus == actionIndex) activateField() else focus = actionIndex }
+    // Tappable (touch escape hatch): the legend doubles as buttons when there's no working controller.
+    val typeHints = listOf(
+        PadGlyph.hint('A', "Type") { pressKey() },
+        PadGlyph.hint('X', "Delete") { editing?.let { id -> editField(id) { it.dropLast(1) } } },
+        PadGlyph.hint('B', "Done") { closeKeyboard() },
+    )
+    val sideBySide = landscape && editing != null
+
+    Box(Modifier.fillMaxSize()) {
+        Box(Modifier.fillMaxSize().hazeSource(hazeState)) {
+            GamepadFormBackground(Modifier.fillMaxSize())
+
+            if (sideBySide) {
+                // Landscape + typing: fields and keyboard SIDE BY SIDE so the field being edited stays
+                // visible (stacked, the keyboard covered the whole short screen). The legend is NOT put
+                // under the keyboard here — it floats at the same fixed bottom-left spot as everywhere.
+                Row(
+                    Modifier.fillMaxSize().systemBarsPadding().padding(start = ConsoleEdgeInset, end = 20.dp, top = 8.dp, bottom = 8.dp),
+                    horizontalArrangement = Arrangement.spacedBy(18.dp),
+                ) {
+                    Column(
+                        Modifier.weight(1f).fillMaxHeight().verticalScroll(rememberScrollState()),
+                        verticalArrangement = Arrangement.spacedBy(8.dp),
+                    ) {
+                        ConsoleHeader(title, horizontalInset = false)
+                        fields.forEachIndexed { i, f -> FieldRow(f, focused = false, editing = editing == f.id) { onFieldClick(i) } }
+                        AddActionRow(actionLabel, enabled = canAdd, focused = false) { onAddClick() }
+                        Spacer(Modifier.height(64.dp)) // clear the floating legend at bottom-left
+                    }
+                    Column(
+                        Modifier.weight(1.15f).fillMaxHeight().verticalScroll(rememberScrollState()),
+                        verticalArrangement = Arrangement.spacedBy(10.dp),
+                    ) {
+                        KeyboardGrid(kbRow, kbCol, compact = true) { r, c -> kbRow = r; kbCol = c; pressKey() }
+                    }
+                }
+            } else {
+                // Portrait (or landscape not typing): the FORM SCROLLS so the Add button is never
+                // compressed by the keyboard; the keyboard sits below it; the legend floats (fixed).
+                Column(Modifier.fillMaxSize().systemBarsPadding().padding(horizontal = ConsoleEdgeInset)) {
+                    Column(
+                        Modifier.weight(1f).fillMaxWidth().verticalScroll(rememberScrollState()),
+                        verticalArrangement = Arrangement.spacedBy(8.dp),
+                    ) {
+                        ConsoleHeader(title, horizontalInset = false)
+                        if (editing == null && !landscape) {
+                            Text(
+                                "Hosts on this network appear automatically — add one by address for everything else.",
+                                style = MaterialTheme.typography.bodyMedium,
+                                color = Color.White.copy(alpha = 0.55f),
+                                modifier = Modifier.widthIn(max = 520.dp).padding(bottom = 8.dp),
+                            )
+                        }
+                        fields.forEachIndexed { i, f -> FieldRow(f, focused = focus == i && editing == null, editing = editing == f.id) { onFieldClick(i) } }
+                        AddActionRow(actionLabel, enabled = canAdd, focused = focus == actionIndex && editing == null) { onAddClick() }
+                        Spacer(Modifier.height(72.dp)) // last field clears the floating legend when scrolled
+                    }
+                    if (editing != null) {
+                        Spacer(Modifier.height(8.dp))
+                        // The keyboard fills to the bottom; its bottom frame is padded so the fixed
+                        // legend sits OVER that frame (bottom-left corner) rather than in a gap below.
+                        KeyboardGrid(kbRow, kbCol, compact = false, bottomInset = 52.dp) { r, c -> kbRow = r; kbCol = c; pressKey() }
+                    }
+                }
+            }
+        }
+
+        // Floating legend — ALWAYS at the same fixed bottom-start spot (portrait or landscape, keyboard
+        // open or not), so opening the keyboard never relocates it below the keys. Backdrop-blurred.
+        Box(
+            Modifier.align(Alignment.BottomStart)
+                .then(if (landscape) Modifier else Modifier.systemBarsPadding())
+                .padding(ConsoleLegendInset),
+        ) {
+            GamepadHintBar(
+                if (editing != null) {
+                    typeHints
+                } else {
+                    listOf(
+                        PadGlyph.hint('A', "Select") { activateField() },
+                        PadGlyph.hint('B', "Cancel", onClick = onDismiss),
+                    )
+                },
+                hazeState = hazeState,
+            )
+        }
+    }
+}
+
+/**
+ * Add-Host on a TV: real focusable text fields + the system (leanback) IME, driven by the OS. No
+ * custom keyboard or input probes — the native focus engine moves between fields and the Add button,
+ * and focusing a field pops the OS keyboard. B backs out.
+ */
+@Composable
+private fun TvAddHostForm(
+    title: String,
+    actionLabel: String,
+    name: String,
+    onName: (String) -> Unit,
+    address: String,
+    onAddress: (String) -> Unit,
+    port: String,
+    onPort: (String) -> Unit,
+    mac: String?, // non-null only in edit mode
+    onMac: (String) -> Unit,
+    canAdd: Boolean,
+    onAdd: () -> Unit,
+    onDismiss: () -> Unit,
+) {
+    BackHandler(onBack = onDismiss)
+    val firstFocus = remember { FocusRequester() }
+    Box(Modifier.fillMaxSize()) {
+        GamepadFormBackground(Modifier.fillMaxSize())
+        Column(
+            Modifier
+                .fillMaxSize()
+                .systemBarsPadding()
+                .padding(horizontal = 56.dp, vertical = 36.dp)
+                .widthIn(max = 720.dp)
+                .verticalScroll(rememberScrollState()),
+            verticalArrangement = Arrangement.spacedBy(16.dp),
+        ) {
+            Text(title, style = MaterialTheme.typography.headlineMedium, fontWeight = FontWeight.Bold, color = Color.White)
+            Text(
+                "Hosts on this network appear automatically — add one by address for everything else.",
+                style = MaterialTheme.typography.bodyMedium,
+                color = Color.White.copy(alpha = 0.55f),
+            )
+            OutlinedTextField(
+                value = name, onValueChange = onName, singleLine = true,
+                label = { Text("Name (optional)") },
+                modifier = Modifier.fillMaxWidth().focusRequester(firstFocus),
+            )
+            OutlinedTextField(
+                value = address, onValueChange = onAddress, singleLine = true,
+                label = { Text("Address") },
+                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Uri),
+                modifier = Modifier.fillMaxWidth(),
+            )
+            OutlinedTextField(
+                value = port, onValueChange = onPort, singleLine = true,
+                label = { Text("Port") },
+                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
+                modifier = Modifier.fillMaxWidth(),
+            )
+            if (mac != null) {
+                OutlinedTextField(
+                    value = mac, onValueChange = onMac, singleLine = true,
+                    label = { Text("Wake-on-LAN MAC") },
+                    placeholder = { Text("auto-filled when the host is seen") },
+                    modifier = Modifier.fillMaxWidth(),
+                )
+            }
+            Button(onClick = onAdd, enabled = canAdd, modifier = Modifier.fillMaxWidth()) {
+                Text(actionLabel)
+            }
+        }
+    }
+    LaunchedEffect(Unit) { runCatching { firstFocus.requestFocus() } }
+}
+
+private fun rowCols(row: Int): Int = if (row < KB_ACTIONS_ROW) KB_CHAR_ROWS[row].length else 3
+
+@Composable
+private fun FieldRow(f: Field, focused: Boolean, editing: Boolean, onClick: () -> Unit) {
+    val scale by animateFloatAsState(if (focused || editing) 1f else 0.98f, label = "fieldScale")
+    val shape = RoundedCornerShape(14.dp)
+    Row(
+        modifier = Modifier
+            .fillMaxWidth()
+            .graphicsLayer { scaleX = scale; scaleY = scale }
+            .clip(shape)
+            .background(if (focused || editing) Color(0x336656F2) else Color(0x14FFFFFF))
+            .border(1.dp, if (editing) Color(0xB38678F5) else Color.White.copy(alpha = if (focused) 0.28f else 0.06f), shape)
+            .clickable(interactionSource = remember { MutableInteractionSource() }, indication = null, onClick = onClick)
+            .padding(horizontal = 16.dp, vertical = 14.dp),
+        verticalAlignment = Alignment.CenterVertically,
+    ) {
+        Text(f.label, style = MaterialTheme.typography.bodyLarge, fontWeight = FontWeight.SemiBold, color = Color.White)
+        Spacer(Modifier.weight(1f))
+        Text(
+            f.value.ifEmpty { f.placeholder },
+            style = MaterialTheme.typography.bodyMedium.copy(fontFamily = FontFamily.Monospace),
+            color = if (f.value.isEmpty()) Color.White.copy(alpha = 0.35f) else Color.White,
+            maxLines = 1,
+            overflow = TextOverflow.Ellipsis,
+        )
+        if (editing) Text(" |", color = Color(0xFF8678F5))
+    }
+}
+
+@Composable
+private fun AddActionRow(label: String, enabled: Boolean, focused: Boolean, onClick: () -> Unit) {
+    val scale by animateFloatAsState(if (focused) 1f else 0.98f, label = "addScale")
+    val shape = RoundedCornerShape(14.dp)
+    Box(
+        modifier = Modifier
+            .fillMaxWidth()
+            .graphicsLayer { scaleX = scale; scaleY = scale }
+            .clip(shape)
+            .background(if (focused) Color(0x336656F2) else Color(0x14FFFFFF))
+            .border(1.dp, Color.White.copy(alpha = if (focused) 0.28f else 0.06f), shape)
+            .clickable(interactionSource = remember { MutableInteractionSource() }, indication = null, onClick = onClick)
+            .padding(vertical = 14.dp),
+        contentAlignment = Alignment.Center,
+    ) {
+        Text(
+            label,
+            style = MaterialTheme.typography.bodyLarge,
+            fontWeight = FontWeight.Bold,
+            color = if (enabled) Color(0xFF8678F5) else Color.White.copy(alpha = 0.35f),
+        )
+    }
+}
+
+@Composable
+private fun KeyboardGrid(
+    cursorRow: Int,
+    cursorCol: Int,
+    compact: Boolean,
+    bottomInset: Dp = 0.dp, // empty frame at the bottom of the glass for the floating legend to sit over
+    onKey: (Int, Int) -> Unit,
+) {
+    val shape = RoundedCornerShape(20.dp)
+    val gap = if (compact) 5.dp else 7.dp
+    Column(
+        Modifier
+            .fillMaxWidth()
+            .widthIn(max = 640.dp)
+            .clip(shape)
+            .background(Color(0x1FFFFFFF))
+            .border(1.dp, Color.White.copy(alpha = 0.12f), shape)
+            .padding(start = 12.dp, end = 12.dp, top = if (compact) 8.dp else 12.dp, bottom = 12.dp + bottomInset),
+        verticalArrangement = Arrangement.spacedBy(gap),
+    ) {
+        KB_CHAR_ROWS.forEachIndexed { r, chars ->
+            Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.spacedBy(gap)) {
+                chars.forEachIndexed { c, ch ->
+                    Keycap(ch.toString(), focused = cursorRow == r && cursorCol == c, compact = compact, modifier = Modifier.weight(1f)) { onKey(r, c) }
+                }
+            }
+        }
+        Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.spacedBy(gap)) {
+            Keycap("space", focused = cursorRow == KB_ACTIONS_ROW && cursorCol == 0, compact = compact, modifier = Modifier.weight(2f)) { onKey(KB_ACTIONS_ROW, 0) }
+            Keycap("⌫", focused = cursorRow == KB_ACTIONS_ROW && cursorCol == 1, compact = compact, modifier = Modifier.weight(1f)) { onKey(KB_ACTIONS_ROW, 1) }
+            Keycap("Done", focused = cursorRow == KB_ACTIONS_ROW && cursorCol == 2, compact = compact, modifier = Modifier.weight(1.5f)) { onKey(KB_ACTIONS_ROW, 2) }
+        }
+    }
+}
+
+@Composable
+private fun Keycap(label: String, focused: Boolean, compact: Boolean, modifier: Modifier = Modifier, onClick: () -> Unit) {
+    Box(
+        modifier = modifier
+            .height(if (compact) 34.dp else 44.dp)
+            .clip(RoundedCornerShape(9.dp))
+            .background(if (focused) Color(0xFF8678F5) else Color(0x14FFFFFF))
+            .clickable(interactionSource = remember { MutableInteractionSource() }, indication = null, onClick = onClick),
+        contentAlignment = Alignment.Center,
+    ) {
+        Text(
+            label,
+            style = MaterialTheme.typography.bodyLarge,
+            fontWeight = FontWeight.Medium,
+            color = if (focused) Color.Black else Color.White,
+            textAlign = TextAlign.Center,
+        )
+    }
+}

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

@@ -0,0 +1,345 @@
+package io.unom.punktfunk
+
+import androidx.compose.animation.core.LinearEasing
+import androidx.compose.animation.core.RepeatMode
+import androidx.compose.animation.core.animateFloat
+import androidx.compose.animation.core.infiniteRepeatable
+import androidx.compose.animation.core.rememberInfiniteTransition
+import androidx.compose.animation.core.tween
+import androidx.compose.foundation.Canvas
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.SportsEsports
+import androidx.compose.material3.Icon
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.graphics.BlendMode
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.graphics.Brush
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+import dev.chrisbanes.haze.HazeState
+import dev.chrisbanes.haze.hazeEffect
+import kotlin.math.PI
+import kotlin.math.cos
+import kotlin.math.max
+import kotlin.math.sin
+
+// The console chrome shared by the gamepad-driven screens — the Android mirror of the Apple client's
+// GamepadChrome.swift: a slow-drifting violet aurora backdrop, a bottom button-glyph hint bar, and a
+// connected-controller status chip. One look across every screen is what makes the console UI read
+// as a coherent mode rather than a set of themed pages.
+
+/** One drifting colour blob of the aurora field. Integer [sx]/[sy] keep the loop seamless at wrap. */
+private class AuroraBlob(
+    val color: Color,
+    val baseX: Float,
+    val baseY: Float,
+    val driftX: Float,
+    val driftY: Float,
+    val sx: Int,
+    val sy: Int,
+    val phase: Float,
+    val radiusFrac: Float,
+    val alpha: Float,
+)
+
+private val auroraBlobs = listOf(
+    AuroraBlob(Color(0xFF877AF5), 0.30f, 0.26f, 0.16f, 0.10f, 1, 1, 0.0f, 0.62f, 0.55f), // brand violet
+    AuroraBlob(Color(0xFF3E33B8), 0.78f, 0.68f, 0.13f, 0.14f, 1, 2, 2.4f, 0.68f, 0.58f), // deep indigo
+    AuroraBlob(Color(0xFF9E4CCC), 0.16f, 0.82f, 0.12f, 0.09f, 2, 1, 4.1f, 0.52f, 0.42f), // plum
+    AuroraBlob(Color(0xFF3862DB), 0.72f, 0.14f, 0.10f, 0.08f, 1, 3, 1.2f, 0.48f, 0.40f), // cool blue
+)
+
+/**
+ * The living console backdrop: soft violet-family blobs drifting over black on slow, seamless loops,
+ * finished with a centre-pooling vignette and top/bottom legibility scrims. A Compose approximation
+ * of the Apple client's MeshGradient aurora — same brand family, same "ambience, never content" role.
+ */
+@Composable
+fun GamepadAuroraBackground(modifier: Modifier = Modifier) {
+    val transition = rememberInfiniteTransition(label = "aurora")
+    // A full 0..2π sweep over ~96 s; integer per-blob multipliers make sin/cos continuous at the wrap
+    // so the field never visibly jumps when the animation restarts.
+    val angle by transition.animateFloat(
+        initialValue = 0f,
+        targetValue = (2 * PI).toFloat(),
+        animationSpec = infiniteRepeatable(tween(96_000, easing = LinearEasing), RepeatMode.Restart),
+        label = "angle",
+    )
+    Canvas(modifier) {
+        drawRect(Color.Black)
+        val span = max(size.width, size.height)
+        for (b in auroraBlobs) {
+            val cx = (b.baseX + b.driftX * sin(angle * b.sx + b.phase)) * size.width
+            val cy = (b.baseY + b.driftY * cos(angle * b.sy + b.phase)) * size.height
+            val r = span * b.radiusFrac
+            drawCircle(
+                brush = Brush.radialGradient(
+                    colors = listOf(b.color.copy(alpha = b.alpha), Color.Transparent),
+                    center = Offset(cx, cy),
+                    radius = r,
+                ),
+                center = Offset(cx, cy),
+                radius = r,
+                blendMode = BlendMode.Plus,
+            )
+        }
+        // Cinematic vignette: pool light centre, sink the corners.
+        drawRect(
+            Brush.radialGradient(
+                colors = listOf(Color.Transparent, Color.Black.copy(alpha = 0.44f)),
+                center = Offset(size.width / 2, size.height / 2),
+                radius = span * 0.92f,
+            ),
+        )
+        // Top/bottom legibility scrim for the pinned title + hint bar.
+        drawRect(
+            Brush.verticalGradient(
+                0.0f to Color.Black.copy(alpha = 0.40f),
+                0.30f to Color.Black.copy(alpha = 0.05f),
+                0.70f to Color.Black.copy(alpha = 0.06f),
+                1.0f to Color.Black.copy(alpha = 0.42f),
+            ),
+        )
+    }
+}
+
+/**
+ * The calm backdrop for the console FORM screens (settings, add-host) — deliberately still and quiet
+ * (unlike the launcher's drifting aurora), a deep indigo base with two soft brand glows so the glass
+ * rows have some colour + luminance to sit on. Mirrors the Apple client's GamepadFormBackground.
+ */
+@Composable
+fun GamepadFormBackground(modifier: Modifier = Modifier) {
+    Canvas(modifier) {
+        val span = max(size.width, size.height)
+        drawRect(Color(0xFF131126))
+        drawCircle(
+            brush = Brush.radialGradient(
+                colors = listOf(Color(0xE6635AAE), Color.Transparent),
+                center = Offset(size.width * 0.24f, size.height * 0.12f),
+                radius = span * 0.7f,
+            ),
+            center = Offset(size.width * 0.24f, size.height * 0.12f),
+            radius = span * 0.7f,
+        )
+        drawCircle(
+            brush = Brush.radialGradient(
+                colors = listOf(Color(0xBF343E96), Color.Transparent),
+                center = Offset(size.width * 0.82f, size.height * 0.9f),
+                radius = span * 0.7f,
+            ),
+            center = Offset(size.width * 0.82f, size.height * 0.9f),
+            radius = span * 0.7f,
+        )
+    }
+}
+
+/**
+ * The exact inset every console screen places its floating legend at (bottom-start), so the legend
+ * sits in the SAME spot across Home / Settings / Add-Host and appears pinned while the content behind
+ * it cross-fades between screens.
+ */
+val ConsoleLegendInset = PaddingValues(start = 24.dp, bottom = 24.dp)
+
+/** The shared horizontal inset for a console screen's heading (matches the legend's left edge). */
+val ConsoleEdgeInset = 24.dp
+
+/**
+ * The heading every console screen uses — one style, one inset, so titles line up across Home /
+ * Settings / Add-Host / Library. Callers place it at the top of their content (or float it, on Home).
+ */
+@Composable
+fun ConsoleHeader(title: String, modifier: Modifier = Modifier, horizontalInset: Boolean = true) {
+    // `horizontalInset = false` when the caller's container already pads to ConsoleEdgeInset (e.g. a
+    // LazyColumn contentPadding) — so the heading lands at the SAME 24dp on every screen either way.
+    val h = if (horizontalInset) ConsoleEdgeInset else 0.dp
+    Text(
+        title,
+        style = MaterialTheme.typography.headlineMedium,
+        fontWeight = FontWeight.Bold,
+        color = Color.White,
+        maxLines = 1,
+        overflow = TextOverflow.Ellipsis,
+        modifier = modifier.padding(start = h, end = h, top = 18.dp, bottom = 10.dp),
+    )
+}
+
+/**
+ * One glyph + label cell of a hint bar. [glyph] is the face letter; [color] its Xbox-convention hue.
+ * [onClick], when set, makes the cell tappable — a TOUCH escape hatch so a user without a working
+ * controller can still drive the console UI (and reach Settings to switch it off).
+ */
+class GamepadHint(
+    val glyph: Char,
+    val color: Color,
+    val text: String,
+    val onClick: (() -> Unit)? = null,
+    // Render as the D-pad-centre "select" button (a ring) instead of a lettered face-button disc —
+    // for a TV remote, which has no A/B/X/Y.
+    val select: Boolean = false,
+    // Render as the gamepad Select/View button (a small capsule).
+    val viewButton: Boolean = false,
+)
+
+/** Xbox-convention face-button colours, so the glyphs read at a glance across the room. */
+object PadGlyph {
+    val A = Color(0xFF6BBE45)
+    val B = Color(0xFFD14B4B)
+    val X = Color(0xFF4B7BD1)
+    val Y = Color(0xFFE0B23C)
+    fun hint(glyph: Char, text: String, onClick: (() -> Unit)? = null) = GamepadHint(
+        glyph, when (glyph) { 'A' -> A; 'B' -> B; 'X' -> X; 'Y' -> Y; else -> Color(0xFF9A93C7) }, text, onClick,
+    )
+}
+
+/** A round face-button badge: a coloured disc with the button letter, like a controller's face. */
+@Composable
+fun GamepadButtonGlyph(glyph: Char, color: Color, size: androidx.compose.ui.unit.Dp = 26.dp) {
+    Box(
+        modifier = Modifier
+            .size(size)
+            .clip(CircleShape)
+            .background(color),
+        contentAlignment = Alignment.Center,
+    ) {
+        Text(
+            glyph.toString(),
+            color = Color.White,
+            fontWeight = FontWeight.Bold,
+            fontSize = (size.value * 0.52f).sp,
+            textAlign = TextAlign.Center,
+        )
+    }
+}
+
+/** The D-pad-centre "select" button — a green (confirm) disc with a ring; the TV-remote glyph for A. */
+@Composable
+private fun SelectGlyph(size: androidx.compose.ui.unit.Dp = 26.dp) {
+    Box(
+        modifier = Modifier.size(size).clip(CircleShape).background(PadGlyph.A),
+        contentAlignment = Alignment.Center,
+    ) {
+        Box(Modifier.size(size * 0.46f).clip(CircleShape).border(2.dp, Color.White, CircleShape))
+    }
+}
+
+/** The remote's "Back" button — a back-arrow disc; the TV-remote glyph for B (back / cancel / done). */
+@Composable
+private fun BackGlyph(size: androidx.compose.ui.unit.Dp = 26.dp) {
+    GamepadButtonGlyph('↩', PadGlyph.B, size)
+}
+
+/** The gamepad "Select / View" button — a small capsule outline, matching its physical shape. */
+@Composable
+private fun ViewButtonGlyph(size: androidx.compose.ui.unit.Dp = 26.dp) {
+    Box(Modifier.size(size), contentAlignment = Alignment.Center) {
+        Box(
+            Modifier
+                .size(width = size * 0.74f, height = size * 0.46f)
+                .clip(RoundedCornerShape(50))
+                .border(1.6.dp, Color.White.copy(alpha = 0.85f), RoundedCornerShape(50)),
+        )
+    }
+}
+
+/**
+ * The pinned controls legend every gamepad screen shows along the bottom — worn as a self-contained
+ * translucent pill so it floats over the aurora rather than dissolving into it.
+ */
+@Composable
+fun GamepadHintBar(hints: List<GamepadHint>, modifier: Modifier = Modifier, hazeState: HazeState? = null) {
+    // On a TV D-pad remote (no A/B/X/Y), auto-swap the two universal pad glyphs every screen uses:
+    // A (confirm) → the select ring, B (back/cancel) → a back glyph. Screen-specific glyphs like the
+    // home's Up/Down handle themselves. Defaults to the gamepad look off an Activity (preview/tests).
+    val padIsGamepad = (LocalContext.current as? MainActivity)?.lastPadIsGamepad ?: true
+    val shape = RoundedCornerShape(50)
+    // With a haze source, blur the content behind the pill (real backdrop blur, API 31+; a translucent
+    // scrim below) + a light tint; otherwise fall back to a solid frosted fill.
+    val frosted = if (hazeState != null) {
+        modifier.clip(shape).hazeEffect(hazeState).background(Color(0x4014122A))
+    } else {
+        modifier.clip(shape).background(Color(0x8C14122A))
+    }
+    Row(
+        modifier = frosted
+            .border(1.dp, Color.White.copy(alpha = 0.14f), shape)
+            .padding(horizontal = 16.dp, vertical = 10.dp),
+        verticalAlignment = Alignment.CenterVertically,
+        horizontalArrangement = Arrangement.spacedBy(11.dp),
+    ) {
+        for (h in hints) {
+            val cb = h.onClick
+            val cell = if (cb != null) {
+                Modifier.clip(RoundedCornerShape(50)).clickable(onClick = cb).padding(horizontal = 4.dp, vertical = 5.dp)
+            } else {
+                Modifier
+            }
+            Row(modifier = cell, verticalAlignment = Alignment.CenterVertically) {
+                when {
+                    h.viewButton -> ViewButtonGlyph()
+                    h.select || (!padIsGamepad && h.glyph == 'A') -> SelectGlyph()
+                    !padIsGamepad && h.glyph == 'B' -> BackGlyph()
+                    else -> GamepadButtonGlyph(h.glyph, h.color)
+                }
+                Spacer(Modifier.width(6.dp))
+                Text(
+                    h.text,
+                    style = MaterialTheme.typography.labelLarge,
+                    color = Color.White.copy(alpha = 0.9f),
+                    maxLines = 1,
+                    softWrap = false, // never char-wrap a label when several hints crowd a narrow pill
+                )
+            }
+        }
+    }
+}
+
+/** "Which pad is driving this UI" — a quiet chip in the console top bar with the controller's name. */
+@Composable
+fun ControllerStatusChip(name: String, modifier: Modifier = Modifier) {
+    Row(
+        modifier = modifier
+            .clip(RoundedCornerShape(50))
+            .background(Color.White.copy(alpha = 0.08f))
+            .padding(horizontal = 12.dp, vertical = 7.dp),
+        verticalAlignment = Alignment.CenterVertically,
+    ) {
+        Icon(
+            Icons.Filled.SportsEsports,
+            contentDescription = null,
+            tint = Color.White.copy(alpha = 0.75f),
+            modifier = Modifier.size(16.dp),
+        )
+        Spacer(Modifier.width(7.dp))
+        Text(
+            name,
+            style = MaterialTheme.typography.labelMedium,
+            color = Color.White.copy(alpha = 0.75f),
+            maxLines = 1,
+        )
+    }
+}

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

@@ -0,0 +1,357 @@
+package io.unom.punktfunk
+
+import android.os.Build
+import androidx.activity.compose.BackHandler
+import androidx.compose.animation.core.animateFloatAsState
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.interaction.MutableInteractionSource
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.ColumnScope
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.heightIn
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.widthIn
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.CircularProgressIndicator
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableIntStateOf
+import androidx.compose.runtime.mutableStateListOf
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.graphicsLayer
+import androidx.compose.ui.platform.LocalConfiguration
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+import io.unom.punktfunk.kit.NativeBridge
+import io.unom.punktfunk.kit.security.ClientIdentity
+import io.unom.punktfunk.models.PendingTrust
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
+
+// Console-styled trust/pairing dialogs — the controller-navigable counterparts of the touch
+// AlertDialogs in ConnectDialogs.kt, shown while the gamepad UI is active. A dark glass card over a
+// scrim with focusable action buttons: D-pad left/right moves the focus, A activates it, B dismisses.
+
+/** One dialog action button. */
+class DialogAction(
+    val label: String,
+    val primary: Boolean = false,
+    val enabled: Boolean = true,
+    val onClick: () -> Unit,
+)
+
+/**
+ * The shared console-dialog scaffold: scrim + glass card with a title, [body], and a row of focusable
+ * [actions]. Owns its own controller nav (the presenting carousel drops its probes while a dialog is
+ * up, via ConnectScreen's `navActive`). B → [onDismiss].
+ */
+@Composable
+fun GamepadDialog(
+    title: String,
+    onDismiss: () -> Unit,
+    actions: List<DialogAction>,
+    body: @Composable ColumnScope.() -> Unit,
+) {
+    // Focus the primary action; buttons are stacked full-width, navigated up/down (fits long labels
+    // like "Request access" without the cramped-row wrapping a horizontal layout caused).
+    var focus by remember { mutableIntStateOf(actions.indexOfFirst { it.primary }.coerceAtLeast(0)) }
+    BackHandler(onBack = onDismiss)
+    GamepadNavEffect2D(
+        active = true,
+        onDirection = { dir ->
+            when (dir) {
+                NavDir.UP -> if (focus > 0) focus--
+                NavDir.DOWN -> if (focus < actions.lastIndex) focus++
+                else -> {}
+            }
+        },
+        onActivate = { actions.getOrNull(focus)?.takeIf { it.enabled }?.onClick?.invoke() },
+    )
+    // Cap the card to most of the screen and let the BODY scroll — in a short landscape window the
+    // title + body + buttons would otherwise overflow and compress/clip the bottom button.
+    val maxCardHeight = (LocalConfiguration.current.screenHeightDp * 0.92f).dp
+    Box(
+        Modifier.fillMaxSize().background(Color.Black.copy(alpha = 0.62f)),
+        contentAlignment = Alignment.Center,
+    ) {
+        Column(
+            Modifier
+                .padding(24.dp)
+                .widthIn(max = 520.dp)
+                .heightIn(max = maxCardHeight)
+                .clip(RoundedCornerShape(24.dp))
+                .background(Color(0xF01A1730))
+                .border(1.dp, Color.White.copy(alpha = 0.12f), RoundedCornerShape(24.dp))
+                .padding(28.dp),
+            verticalArrangement = Arrangement.spacedBy(14.dp),
+        ) {
+            Text(title, style = MaterialTheme.typography.headlineSmall, fontWeight = FontWeight.Bold, color = Color.White)
+            // The body scrolls; the title above and the buttons below stay pinned + always visible.
+            Column(
+                Modifier.weight(1f, fill = false).verticalScroll(rememberScrollState()),
+                verticalArrangement = Arrangement.spacedBy(10.dp),
+            ) {
+                body()
+            }
+            Spacer(Modifier.size(4.dp))
+            actions.forEachIndexed { i, a ->
+                DialogButton(a.label, focused = i == focus, primary = a.primary, enabled = a.enabled, onClick = a.onClick)
+            }
+        }
+    }
+}
+
+@Composable
+private fun DialogButton(label: String, focused: Boolean, primary: Boolean, enabled: Boolean, onClick: () -> Unit) {
+    val scale by animateFloatAsState(if (focused) 1.02f else 1f, label = "btnScale")
+    val shape = RoundedCornerShape(14.dp)
+    val bg = when {
+        focused -> Color(0xFF6656F2)
+        primary -> Color(0x336656F2)
+        else -> Color(0x14FFFFFF)
+    }
+    val fg = when {
+        !enabled -> Color.White.copy(alpha = 0.35f)
+        focused -> Color.White
+        primary -> Color(0xFF8678F5)
+        else -> Color.White.copy(alpha = 0.85f)
+    }
+    Box(
+        modifier = Modifier
+            .fillMaxWidth()
+            .graphicsLayer { scaleX = scale; scaleY = scale }
+            .clip(shape)
+            .background(bg)
+            .border(1.dp, Color.White.copy(alpha = if (focused) 0.3f else 0.08f), shape)
+            .clickable(
+                enabled = enabled,
+                interactionSource = remember { MutableInteractionSource() },
+                indication = null,
+                onClick = onClick,
+            )
+            .padding(horizontal = 20.dp, vertical = 13.dp),
+        contentAlignment = Alignment.Center,
+    ) {
+        Text(label, style = MaterialTheme.typography.labelLarge, fontWeight = FontWeight.SemiBold, color = fg, maxLines = 1)
+    }
+}
+
+/** Body text helper — a dimmed paragraph. */
+@Composable
+private fun DialogText(text: String) {
+    Text(text, style = MaterialTheme.typography.bodyMedium, color = Color.White.copy(alpha = 0.7f))
+}
+
+/**
+ * Console host options for a saved tile — Wake (offered only when offline + a MAC is known), Edit,
+ * Forget. Reached by pressing Up on a focused saved host in the carousel; the console counterpart of
+ * the touch host card's overflow menu.
+ */
+@Composable
+fun GamepadHostOptionsDialog(
+    hostName: String,
+    canWake: Boolean,
+    onWake: () -> Unit,
+    onLibrary: (() -> Unit)?, // non-null when the game library is enabled → reachable without Y
+    onEdit: () -> Unit,
+    onForget: () -> Unit,
+    onDismiss: () -> Unit,
+) {
+    GamepadDialog(
+        title = hostName,
+        onDismiss = onDismiss,
+        actions = buildList {
+            if (onLibrary != null) add(DialogAction("Library", primary = true, onClick = onLibrary))
+            if (canWake) add(DialogAction("Wake host", onClick = onWake))
+            add(DialogAction("Edit…", primary = onLibrary == null, onClick = onEdit))
+            add(DialogAction("Forget", onClick = onForget))
+            add(DialogAction("Cancel", onClick = onDismiss))
+        },
+    ) {
+        DialogText("Manage this saved host.")
+    }
+}
+
+@Composable
+fun GamepadTrustNewDialog(pt: PendingTrust, onTrust: () -> Unit, onPairInstead: () -> Unit, onDismiss: () -> Unit) {
+    GamepadDialog(
+        title = "Trust this host?",
+        onDismiss = onDismiss,
+        actions = listOf(
+            DialogAction("Cancel", onClick = onDismiss),
+            DialogAction("Pair with PIN", onClick = onPairInstead),
+            DialogAction("Trust (TOFU)", primary = true, onClick = onTrust),
+        ),
+    ) {
+        DialogText("First connection to ${pt.host}:${pt.port}.")
+        pt.advertisedFp?.let { DialogText("Fingerprint ${it.take(16)}…") }
+        DialogText(
+            "This host allows trust-on-first-use, but that can't tell an impostor from the real host. " +
+                "Pairing with a PIN is stronger — it proves both sides.",
+        )
+    }
+}
+
+@Composable
+fun GamepadFingerprintChangedDialog(pt: PendingTrust, onRepair: () -> Unit, onDismiss: () -> Unit) {
+    GamepadDialog(
+        title = "Host identity changed",
+        onDismiss = onDismiss,
+        actions = listOf(
+            DialogAction("Cancel", onClick = onDismiss),
+            DialogAction("Re-pair", primary = true, onClick = onRepair),
+        ),
+    ) {
+        DialogText(
+            "The pinned fingerprint for ${pt.host} no longer matches what it now advertises. This can " +
+                "mean a host reinstall — or an impostor. Re-pair with the host's PIN to continue.",
+        )
+    }
+}
+
+@Composable
+fun GamepadRequestAccessDialog(pt: PendingTrust, onRequestAccess: () -> Unit, onUsePin: () -> Unit, onDismiss: () -> Unit) {
+    GamepadDialog(
+        title = "Pairing required",
+        onDismiss = onDismiss,
+        actions = listOf(
+            DialogAction("Cancel", onClick = onDismiss),
+            DialogAction("Use a PIN", onClick = onUsePin),
+            DialogAction("Request access", primary = true, onClick = onRequestAccess),
+        ),
+    ) {
+        DialogText("${pt.host}:${pt.port} requires pairing before it will stream.")
+        DialogText(
+            "Request access and approve this device in the host's console (or web UI) — no PIN needed. " +
+                "Or pair with the 4-digit PIN the host displays.",
+        )
+    }
+}
+
+@Composable
+fun GamepadAwaitingApprovalDialog(hostLabel: String, onCancel: () -> Unit) {
+    GamepadDialog(
+        title = "Waiting for approval",
+        onDismiss = onCancel,
+        actions = listOf(DialogAction("Cancel", primary = true, onClick = onCancel)),
+    ) {
+        val deviceName = Build.MODEL ?: "this device"
+        Row(verticalAlignment = Alignment.CenterVertically, horizontalArrangement = Arrangement.spacedBy(12.dp)) {
+            CircularProgressIndicator(modifier = Modifier.size(20.dp), strokeWidth = 2.dp, color = Color.White)
+            Text("Approve this device on $hostLabel.", color = Color.White)
+        }
+        DialogText(
+            "Open the host's console (or web UI) and approve “$deviceName”. It connects automatically " +
+                "once you approve — no PIN needed.",
+        )
+    }
+}
+
+/**
+ * Console PIN pairing: four digit slots set with the D-pad (left/right selects a slot, up/down changes
+ * 0–9), then Pair. Runs [NativeBridge.nativePair] off the UI thread; on success hands the verified
+ * fingerprint to [onPaired]. No text keyboard needed — a PIN is four digits.
+ */
+@Composable
+fun GamepadPairPinDialog(pt: PendingTrust, identity: ClientIdentity?, onPaired: (String) -> Unit, onDismiss: () -> Unit) {
+    val scope = rememberCoroutineScope()
+    val digits = remember(pt) { mutableStateListOf(0, 0, 0, 0) }
+    var slot by remember(pt) { mutableIntStateOf(0) } // 0..3 = digit slots, 4 = Pair button
+    var pairing by remember(pt) { mutableStateOf(false) }
+    var err by remember(pt) { mutableStateOf<String?>(null) }
+    val name = remember { Build.MODEL ?: "Android" }
+
+    fun pair() {
+        val id = identity ?: return
+        pairing = true
+        err = null
+        val pin = digits.joinToString("")
+        scope.launch {
+            val fp = withContext(Dispatchers.IO) {
+                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."
+        }
+    }
+
+    BackHandler(onBack = { if (!pairing) onDismiss() })
+    GamepadNavEffect2D(
+        active = !pairing,
+        onDirection = { dir ->
+            when (dir) {
+                NavDir.LEFT -> if (slot > 0) slot--
+                NavDir.RIGHT -> if (slot < 4) slot++
+                NavDir.UP -> if (slot < 4) digits[slot] = (digits[slot] + 1) % 10
+                NavDir.DOWN -> if (slot < 4) digits[slot] = (digits[slot] + 9) % 10
+            }
+        },
+        onActivate = { if (slot == 4 && identity != null) pair() },
+    )
+
+    val maxCardHeight = (LocalConfiguration.current.screenHeightDp * 0.92f).dp
+    Box(Modifier.fillMaxSize().background(Color.Black.copy(alpha = 0.62f)), contentAlignment = Alignment.Center) {
+        Column(
+            Modifier.padding(24.dp).widthIn(max = 460.dp).heightIn(max = maxCardHeight)
+                .clip(RoundedCornerShape(24.dp))
+                .background(Color(0xF01A1730)).border(1.dp, Color.White.copy(alpha = 0.12f), RoundedCornerShape(24.dp))
+                .verticalScroll(rememberScrollState())
+                .padding(28.dp),
+            horizontalAlignment = Alignment.CenterHorizontally,
+            verticalArrangement = Arrangement.spacedBy(18.dp),
+        ) {
+            Text("Pair with PIN", style = MaterialTheme.typography.headlineSmall, fontWeight = FontWeight.Bold, color = Color.White)
+            Text(
+                "Enter the 4-digit PIN shown on the host — D-pad ↑↓ sets a digit, ←→ moves.",
+                style = MaterialTheme.typography.bodyMedium, color = Color.White.copy(alpha = 0.7f), textAlign = TextAlign.Center,
+            )
+            Row(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
+                repeat(4) { i -> PinSlot(digits[i], focused = slot == i && !pairing) }
+            }
+            err?.let { Text(it, color = Color(0xFFE0736F), style = MaterialTheme.typography.bodyMedium) }
+            DialogButton(
+                label = if (pairing) "Pairing…" else "Pair",
+                focused = slot == 4 && !pairing,
+                primary = true,
+                enabled = !pairing && identity != null,
+                onClick = { if (identity != null) pair() },
+            )
+        }
+    }
+}
+
+@Composable
+private fun PinSlot(value: Int, focused: Boolean) {
+    val shape = RoundedCornerShape(12.dp)
+    Box(
+        Modifier.size(54.dp, 66.dp).clip(shape)
+            .background(if (focused) Color(0x336656F2) else Color(0x14FFFFFF))
+            .border(if (focused) 2.dp else 1.dp, if (focused) Color(0xFF8678F5) else Color.White.copy(alpha = 0.1f), shape),
+        contentAlignment = Alignment.Center,
+    ) {
+        Text(value.toString(), fontSize = 30.sp, fontWeight = FontWeight.Bold, color = Color.White, fontFamily = FontFamily.Monospace)
+    }
+}

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

@@ -0,0 +1,328 @@
+package io.unom.punktfunk
+
+import android.content.res.Configuration
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.interaction.MutableInteractionSource
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.BoxWithConstraints
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.systemBarsPadding
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.pager.HorizontalPager
+import androidx.compose.foundation.pager.PageSize
+import androidx.compose.foundation.pager.rememberPagerState
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Add
+import androidx.compose.material.icons.filled.Lock
+import androidx.compose.material3.CircularProgressIndicator
+import androidx.compose.material3.Icon
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.BlurredEdgeTreatment
+import androidx.compose.ui.draw.blur
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Brush
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.graphicsLayer
+import androidx.compose.ui.platform.LocalConfiguration
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.util.lerp
+import dev.chrisbanes.haze.HazeState
+import dev.chrisbanes.haze.hazeSource
+import io.unom.punktfunk.kit.security.KnownHost
+import kotlin.math.absoluteValue
+import kotlinx.coroutines.launch
+
+// The gamepad-driven home — the Android mirror of the Apple client's GamepadHomeView: a distinct,
+// "10-foot" console-style host launcher shown INSTEAD of the touch grid while the console UI is
+// active. A center-snapping carousel of hosts (saved first, then discovered, then a trailing Add
+// Host tile), driven from the couch: A connects, X opens Settings, Y opens a saved host's library.
+
+/** One navigable launcher tile — a saved host, a discovered-but-unsaved host, or the Add Host action. */
+class HomeTile(
+    val id: String,
+    val title: String,
+    val subtitle: String,
+    val filled: Boolean = false,     // saved (solid monogram) vs discovered / action (tinted outline)
+    val online: Boolean = false,     // advertising on the LAN right now
+    val paired: Boolean = false,     // pinned identity (shows a lock)
+    val connecting: Boolean = false,
+    val isAdd: Boolean = false,      // the trailing Add Host tile (plus icon, not a monogram)
+    val knownHost: KnownHost? = null, // set for saved hosts → enables the library (Y)
+    val activate: () -> Unit,
+) {
+    // Any SAVED host offers the library (matches Apple) — the fetch itself returns a clear "pair
+    // first" message if the host hasn't authorized this device for its management API.
+    val hasLibrary: Boolean get() = knownHost != null
+}
+
+/**
+ * The console home. [tiles] is rebuilt by the caller from the live host stores; [onActivate] runs a
+ * tile's action, [onOpenLibrary]/[onOpenSettings] are the Y/X actions. Fully driven by D-pad / stick
+ * / face buttons (MainActivity already maps a pad's A→center, B→back, sticks→D-pad) and by touch.
+ */
+@Composable
+fun GamepadHome(
+    tiles: List<HomeTile>,
+    libraryEnabled: Boolean,
+    controllerName: String?,
+    // False while a sheet/dialog is on top → the carousel stops consuming the pad so the overlay
+    // can be driven instead.
+    navActive: Boolean,
+    onActivate: (HomeTile) -> Unit,
+    onOpenLibrary: (HomeTile) -> Unit,
+    onOpenSettings: () -> Unit,
+    // Up on a saved host opens its options (Wake / Edit / Forget). Only saved tiles carry a knownHost.
+    onOptions: (HomeTile) -> Unit = {},
+) {
+    // Equal inset for the pinned title + hint bar, measured from the safe-area edges (so the legend
+    // sits the same distance from the left and the bottom).
+    val landscape = LocalConfiguration.current.orientation == Configuration.ORIENTATION_LANDSCAPE
+
+    val pagerState = rememberPagerState(pageCount = { tiles.size })
+    val scope = rememberCoroutineScope()
+    // navTarget is the navigation authority — a controller move steps THIS, and the pager is pointed
+    // at it, so a fast repeat coalesces to the latest target instead of reading a lagging currentPage
+    // mid-animation (which is what let a flick overshoot by two).
+    var navTarget by remember { mutableStateOf(0) }
+    LaunchedEffect(pagerState.settledPage) { navTarget = pagerState.settledPage }
+    val current = tiles.getOrNull(navTarget)
+
+    GamepadNavEffect(
+        active = navActive && tiles.isNotEmpty(),
+        onMove = { dir ->
+            val target = (navTarget + dir).coerceIn(0, tiles.lastIndex)
+            if (target != navTarget) {
+                navTarget = target
+                scope.launch { pagerState.animateScrollToPage(target) }
+            }
+        },
+        onActivate = { tiles.getOrNull(navTarget)?.let(onActivate) }, // A / D-pad-center → Connect
+        onSecondary = { // Y (gamepad) → Library
+            tiles.getOrNull(navTarget)?.takeIf { libraryEnabled && it.hasLibrary }?.let(onOpenLibrary)
+        },
+        onTertiary = onOpenSettings, // X (gamepad) → Settings
+        // A TV remote has no A/B/X/Y: Up → Settings, Down → a saved host's Options (Wake / Library /
+        // Edit / Forget). A gamepad instead opens Options on its Select/View button.
+        onUp = onOpenSettings,
+        onDown = { tiles.getOrNull(navTarget)?.takeIf { it.knownHost != null }?.let(onOptions) },
+        onOptions = { tiles.getOrNull(navTarget)?.takeIf { it.knownHost != null }?.let(onOptions) },
+    )
+
+    // The legend follows the LAST-USED input: a real gamepad shows its A/X/Y face buttons + the
+    // Select/View button for Options; a TV D-pad remote (no face buttons) shows a select ring + Up
+    // (Settings) / Down (Options) arrows, with Library folded into Options. Input is universal either
+    // way. Each hint is also TAPPABLE (touch hatch).
+    val padIsGamepad = (LocalContext.current as? MainActivity)?.lastPadIsGamepad ?: false
+    val connectLabel = if (current?.isAdd == true) "Add Host" else "Connect"
+    val connectAction: () -> Unit = { tiles.getOrNull(navTarget)?.let(onActivate) }
+    val optionsAction: () -> Unit = { current?.let(onOptions) }
+    val arrowTint = Color(0xFF9A93C7)
+    val hints = buildList {
+        if (padIsGamepad) {
+            add(PadGlyph.hint('A', connectLabel, onClick = connectAction))
+            if (libraryEnabled && current?.hasLibrary == true) add(PadGlyph.hint('Y', "Library") {
+                tiles.getOrNull(navTarget)?.takeIf { it.hasLibrary }?.let(onOpenLibrary)
+            })
+            add(PadGlyph.hint('X', "Settings", onClick = onOpenSettings))
+            // The pad's Select/View button (drawn as its capsule glyph) opens host options.
+            if (current?.knownHost != null) add(GamepadHint(' ', arrowTint, "Options", onClick = optionsAction, viewButton = true))
+        } else {
+            add(GamepadHint(' ', PadGlyph.A, connectLabel, onClick = connectAction, select = true))
+            add(GamepadHint('↑', arrowTint, "Settings", onClick = { onOpenSettings() }))
+            if (current?.knownHost != null) add(GamepadHint('↓', arrowTint, "Options", onClick = optionsAction))
+        }
+    }
+
+    val hazeState = remember { HazeState() }
+
+    Box(Modifier.fillMaxSize()) {
+        // The whole backdrop (aurora + carousel) is the haze source, so the floating legend can blur
+        // whatever scrolls under it.
+        BoxWithConstraints(Modifier.fillMaxSize().hazeSource(hazeState)) {
+            GamepadAuroraBackground(Modifier.fillMaxSize())
+
+            // Carousel centred on the FULL screen — the title + legend FLOAT over it (below), so they
+            // no longer push the cards below the true centre.
+            val cardWidth = (maxWidth * 0.82f).coerceAtMost(360.dp)
+            val cardHeight = (maxHeight * 0.56f).coerceAtMost(216.dp)
+            val sidePad = ((maxWidth - cardWidth) / 2).coerceAtLeast(0.dp)
+            Box(Modifier.fillMaxSize().systemBarsPadding()) {
+                HorizontalPager(
+                    state = pagerState,
+                    pageSize = PageSize.Fixed(cardWidth),
+                    contentPadding = PaddingValues(horizontal = sidePad),
+                    pageSpacing = 22.dp,
+                    modifier = Modifier.fillMaxSize(),
+                    verticalAlignment = Alignment.CenterVertically,
+                ) { page ->
+                    val tile = tiles[page]
+                    // Real distance-from-centered (page + fractional drag), so the pop tracks the
+                    // live scroll: centered tile at full scale/brightness, neighbours recede + blur.
+                    val offset = ((pagerState.currentPage - page) + pagerState.currentPageOffsetFraction)
+                        .absoluteValue.coerceIn(0f, 1f)
+                    GamepadHostTile(
+                        tile = tile,
+                        modifier = Modifier
+                            .graphicsLayer {
+                                val s = lerp(1f, 0.86f, offset)
+                                scaleX = s
+                                scaleY = s
+                                alpha = lerp(1f, 0.5f, offset)
+                            }
+                            // Unbounded so the depth blur isn't hard-clipped at the card's rectangle
+                            // (the cut-off edge). No-op below API 31; a soft blur above.
+                            .blur(radius = (offset * 12f).dp, edgeTreatment = BlurredEdgeTreatment.Unbounded)
+                            .height(cardHeight)
+                            .clickable(
+                                interactionSource = remember { MutableInteractionSource() },
+                                indication = null,
+                            ) {
+                                if (page == navTarget) {
+                                    onActivate(tile)
+                                } else {
+                                    navTarget = page
+                                    scope.launch { pagerState.animateScrollToPage(page) }
+                                }
+                            },
+                    )
+                }
+            }
+        }
+
+        // Title floats over the top (out of the carousel's layout, so the cards stay centred). Uses
+        // the shared ConsoleHeader so it lines up with every other screen's heading.
+        Row(
+            Modifier.align(Alignment.TopStart).fillMaxWidth().systemBarsPadding()
+                .padding(end = ConsoleEdgeInset),
+            verticalAlignment = Alignment.CenterVertically,
+        ) {
+            ConsoleHeader("Select a Host", modifier = Modifier.weight(1f))
+            if (controllerName != null) ControllerStatusChip(controllerName)
+        }
+
+        // Legend floats bottom-start with a real backdrop blur of the content behind it. In LANDSCAPE
+        // it ignores the safe area (the nav-bar inset made the bottom gap look oversized).
+        Box(
+            Modifier
+                .align(Alignment.BottomStart)
+                .then(if (landscape) Modifier else Modifier.systemBarsPadding())
+                .padding(ConsoleLegendInset),
+        ) {
+            GamepadHintBar(hints, hazeState = hazeState)
+        }
+    }
+}
+
+/** One dark-glass landscape console tile — bigger and bolder than the touch grid's HostCard. */
+@Composable
+private fun GamepadHostTile(tile: HomeTile, modifier: Modifier = Modifier) {
+    val shape = RoundedCornerShape(26.dp)
+    val wash = if (tile.filled) {
+        Brush.verticalGradient(listOf(Color(0x336656F2), Color(0x14100C2A)))
+    } else {
+        Brush.verticalGradient(listOf(Color(0x1AFFFFFF), Color(0x0DFFFFFF)))
+    }
+    Column(
+        modifier = modifier
+            .fillMaxWidth()
+            .clip(shape)
+            .background(wash)
+            .border(1.dp, Color.White.copy(alpha = 0.16f), shape)
+            .padding(22.dp),
+    ) {
+        Row(Modifier.fillMaxWidth(), verticalAlignment = Alignment.Top) {
+            MonogramBadge(tile)
+            Spacer(Modifier.weight(1f))
+            Row(verticalAlignment = Alignment.CenterVertically) {
+                if (tile.paired) {
+                    Icon(
+                        Icons.Filled.Lock,
+                        contentDescription = "Paired",
+                        tint = Color.White.copy(alpha = 0.7f),
+                        modifier = Modifier.padding(end = 6.dp).size(15.dp),
+                    )
+                }
+                if (tile.online) {
+                    Box(
+                        Modifier.size(10.dp).clip(androidx.compose.foundation.shape.CircleShape)
+                            .background(Color(0xFF3CD070)),
+                    )
+                }
+            }
+        }
+        Spacer(Modifier.weight(1f))
+        Text(
+            tile.title,
+            style = MaterialTheme.typography.titleLarge,
+            fontWeight = FontWeight.Bold,
+            color = Color.White,
+            maxLines = 1,
+            overflow = TextOverflow.Ellipsis,
+        )
+        Text(
+            tile.subtitle,
+            style = MaterialTheme.typography.bodyMedium,
+            color = Color.White.copy(alpha = 0.55f),
+            maxLines = 1,
+            overflow = TextOverflow.Ellipsis,
+        )
+    }
+}
+
+@Composable
+private fun MonogramBadge(tile: HomeTile) {
+    val shape = RoundedCornerShape(15.dp)
+    val fill = if (tile.filled) {
+        Brush.verticalGradient(listOf(Color(0xFF6656F2), Color(0xFF8678F5)))
+    } else {
+        Brush.verticalGradient(listOf(Color(0x296656F2), Color(0x296656F2)))
+    }
+    Box(
+        modifier = Modifier.size(52.dp).clip(shape).background(fill),
+        contentAlignment = Alignment.Center,
+    ) {
+        when {
+            tile.connecting -> CircularProgressIndicator(
+                modifier = Modifier.size(24.dp),
+                strokeWidth = 2.dp,
+                color = Color.White,
+            )
+            tile.isAdd -> Icon(
+                Icons.Filled.Add,
+                contentDescription = null,
+                tint = if (tile.filled) Color.White else Color(0xFF8678F5),
+            )
+            else -> Text(
+                tile.title.trim().firstOrNull()?.uppercaseChar()?.toString() ?: "•",
+                style = MaterialTheme.typography.titleLarge,
+                fontWeight = FontWeight.Bold,
+                color = if (tile.filled) Color.White else Color(0xFF8678F5),
+            )
+        }
+    }
+}

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

@@ -0,0 +1,257 @@
+package io.unom.punktfunk
+
+import android.os.SystemClock
+import android.view.InputDevice
+import android.view.KeyEvent
+import android.view.MotionEvent
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberUpdatedState
+import androidx.compose.ui.platform.LocalContext
+import kotlin.math.abs
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.isActive
+
+// Controller navigation for the console carousels (host launcher + library coverflow). It taps the
+// SAME MainActivity input probes the Controllers debug screen uses (padMotionProbe / padKeyProbe) so
+// it sees the raw analog stick and consumes it BEFORE MainActivity's stick→D-pad focus synthesis —
+// which is what made carousel scrolling feel wrong: that path is edge-only (no hold-to-repeat, so a
+// held stick did nothing) and a flick could cross the threshold twice (double-move). Here the left
+// stick drives discrete moves with hysteresis (fire once when it crosses HIGH; re-arm only after it
+// falls back under LOW → a flick is exactly one move) and auto-repeat while held. The caller coalesces
+// the moves against a target index so a fast repeat walks smoothly instead of overshooting.
+
+private const val STICK_HIGH = 0.6f   // cross this to commit a move
+private const val STICK_LOW = 0.3f    // fall back under this to re-arm (hysteresis)
+private const val INITIAL_DELAY_MS = 420L // hold this long before the first auto-repeat
+private const val REPEAT_MS = 150L        // then repeat this often while held
+
+private class NavInputState {
+    @Volatile var stickX = 0f
+    @Volatile var stickY = 0f
+    @Volatile var hatX = 0f
+    @Volatile var hatY = 0f
+    @Volatile var dpadX = 0
+    @Volatile var dpadY = 0
+    fun reset() { stickX = 0f; stickY = 0f; hatX = 0f; hatY = 0f; dpadX = 0; dpadY = 0 }
+}
+
+/** A committed navigation direction from the stick / D-pad / HAT. */
+enum class NavDir { UP, DOWN, LEFT, RIGHT }
+
+/**
+ * Installs controller navigation for a console screen while [active]. [onMove] gets -1 (left) / +1
+ * (right) for each committed step; [onActivate] is A / D-pad-center / Enter, [onTertiary] is X,
+ * [onSecondary] is Y. B and the shoulders fall through to MainActivity (B → its BACK remap → the
+ * screen's BackHandler). [active] is set false while a sheet/dialog is on top so the carousel stops
+ * consuming the pad and the overlay can be navigated.
+ */
+@Composable
+fun GamepadNavEffect(
+    active: Boolean,
+    onMove: (Int) -> Unit,
+    onActivate: () -> Unit,
+    onSecondary: () -> Unit = {},
+    onTertiary: () -> Unit = {},
+    // D-pad Up (the carousel is horizontal) → e.g. Settings, since a TV remote has no X face button.
+    onUp: () -> Unit = {},
+    onDown: () -> Unit = {},
+    // Context/options menu — fired by the gamepad Select/View button OR a long-press of the select/OK
+    // button (the Android-TV context-menu convention). A short OK press is [onActivate].
+    onOptions: () -> Unit = {},
+) {
+    val activity = LocalContext.current as? MainActivity ?: return
+    val state = remember { NavInputState() }
+    // The effects below are keyed on `active` only (they must NOT restart on every recomposition), so
+    // they'd otherwise capture the FIRST callbacks — closing over a stale `tiles` (fewer hosts than are
+    // discovered later, which clamped navigation to that old count). rememberUpdatedState keeps the
+    // long-lived coroutine/probes pointed at the CURRENT callbacks.
+    val currentOnMove by rememberUpdatedState(onMove)
+    val currentOnActivate by rememberUpdatedState(onActivate)
+    val currentOnSecondary by rememberUpdatedState(onSecondary)
+    val currentOnTertiary by rememberUpdatedState(onTertiary)
+    val currentOnUp by rememberUpdatedState(onUp)
+    val currentOnDown by rememberUpdatedState(onDown)
+    val currentOnOptions by rememberUpdatedState(onOptions)
+
+    DisposableEffect(active) {
+        // Stable probe refs (see GamepadNavEffect2D) so onDispose only releases the slot if we still
+        // own it — a cross-fading-out screen mustn't null the incoming screen's probes.
+        val motionProbe: (MotionEvent) -> Boolean = probe@{ ev ->
+            if (ev.isFromSource(InputDevice.SOURCE_JOYSTICK) && ev.actionMasked == MotionEvent.ACTION_MOVE) {
+                state.stickX = ev.getAxisValue(MotionEvent.AXIS_X)
+                state.hatX = ev.getAxisValue(MotionEvent.AXIS_HAT_X)
+                return@probe true // consume → MainActivity's stick→D-pad synthesis stays out of it
+            }
+            false
+        }
+        val keyProbe: (KeyEvent) -> Boolean = probe@{ ev ->
+            val down = ev.action == KeyEvent.ACTION_DOWN
+            val edge = down && ev.repeatCount == 0
+            when (ev.keyCode) {
+                KeyEvent.KEYCODE_DPAD_LEFT -> { state.dpadX = if (down) -1 else 0; true }
+                KeyEvent.KEYCODE_DPAD_RIGHT -> { state.dpadX = if (down) 1 else 0; true }
+                // TV remote (no face buttons): Up → Settings, Down → a saved host's Options.
+                KeyEvent.KEYCODE_DPAD_UP -> { if (edge) currentOnUp(); true }
+                KeyEvent.KEYCODE_DPAD_DOWN -> { if (edge) currentOnDown(); true }
+                KeyEvent.KEYCODE_BUTTON_A, KeyEvent.KEYCODE_DPAD_CENTER,
+                KeyEvent.KEYCODE_ENTER, KeyEvent.KEYCODE_NUMPAD_ENTER -> { if (edge) currentOnActivate(); true }
+                // The gamepad Select / View / Share button → context options (a remote uses Down).
+                KeyEvent.KEYCODE_BUTTON_SELECT -> { if (edge) currentOnOptions(); true }
+                KeyEvent.KEYCODE_BUTTON_X -> { if (edge) currentOnTertiary(); true }
+                KeyEvent.KEYCODE_BUTTON_Y -> { if (edge) currentOnSecondary(); true }
+                else -> false // B / shoulders / etc. → MainActivity handles (B remaps to BACK)
+            }
+        }
+        if (active) {
+            activity.padMotionProbe = motionProbe
+            activity.padKeyProbe = keyProbe
+        }
+        onDispose {
+            if (activity.padMotionProbe === motionProbe) activity.padMotionProbe = null
+            if (activity.padKeyProbe === keyProbe) activity.padKeyProbe = null
+            state.reset()
+        }
+    }
+
+    LaunchedEffect(active) {
+        if (!active) return@LaunchedEffect
+        var committed = 0     // the direction currently held (hysteresis + repeat authority)
+        var fireAt = 0L       // uptime at/after which the next auto-repeat may fire
+        while (isActive) {
+            val now = SystemClock.uptimeMillis()
+            val hat = if (state.hatX <= -0.5f) -1 else if (state.hatX >= 0.5f) 1 else 0
+            val dir = when {
+                state.dpadX != 0 -> state.dpadX
+                hat != 0 -> hat
+                else -> {
+                    val x = state.stickX
+                    when {
+                        x >= STICK_HIGH -> 1
+                        x <= -STICK_HIGH -> -1
+                        abs(x) < STICK_LOW -> 0
+                        else -> committed // inside the hysteresis band → hold the committed value
+                    }
+                }
+            }
+            when {
+                dir == 0 -> committed = 0
+                dir != committed -> { currentOnMove(dir); committed = dir; fireAt = now + INITIAL_DELAY_MS }
+                now >= fireAt -> { currentOnMove(dir); fireAt = now + REPEAT_MS }
+            }
+            delay(16)
+        }
+    }
+}
+
+/**
+ * 2-D controller navigation for the console form screens (settings focus list, add-host, on-screen
+ * keyboard). Same hysteresis + hold-to-repeat as [GamepadNavEffect] but on both axes — the dominant
+ * stick axis (or the pressed D-pad/HAT) commits a [NavDir], and it re-arms only after the stick
+ * returns near centre (so a flick is one step). [onActivate] is A / center, [onTertiary] is X,
+ * [onSecondary] is Y. B is left to MainActivity's BACK remap → the screen's BackHandler (so B "peels
+ * one layer": close the keyboard, then the screen).
+ */
+@Composable
+fun GamepadNavEffect2D(
+    active: Boolean,
+    onDirection: (NavDir) -> Unit,
+    onActivate: () -> Unit,
+    onTertiary: () -> Unit = {},
+    onSecondary: () -> Unit = {},
+) {
+    val activity = LocalContext.current as? MainActivity ?: return
+    val state = remember { NavInputState() }
+    val currentOnDirection by rememberUpdatedState(onDirection)
+    val currentOnActivate by rememberUpdatedState(onActivate)
+    val currentOnTertiary by rememberUpdatedState(onTertiary)
+    val currentOnSecondary by rememberUpdatedState(onSecondary)
+
+    DisposableEffect(active) {
+        // Stable probe refs so onDispose only releases the slot if WE still own it — during a
+        // cross-fade both the outgoing and incoming screen are briefly composed, and the outgoing's
+        // teardown must not null out the incoming screen's just-installed probes.
+        val motionProbe: (MotionEvent) -> Boolean = probe@{ ev ->
+            if (ev.isFromSource(InputDevice.SOURCE_JOYSTICK) && ev.actionMasked == MotionEvent.ACTION_MOVE) {
+                state.stickX = ev.getAxisValue(MotionEvent.AXIS_X)
+                state.stickY = ev.getAxisValue(MotionEvent.AXIS_Y)
+                state.hatX = ev.getAxisValue(MotionEvent.AXIS_HAT_X)
+                state.hatY = ev.getAxisValue(MotionEvent.AXIS_HAT_Y)
+                return@probe true
+            }
+            false
+        }
+        val keyProbe: (KeyEvent) -> Boolean = probe@{ ev ->
+            val down = ev.action == KeyEvent.ACTION_DOWN
+            val edge = down && ev.repeatCount == 0
+            when (ev.keyCode) {
+                KeyEvent.KEYCODE_DPAD_LEFT -> { state.dpadX = if (down) -1 else 0; true }
+                KeyEvent.KEYCODE_DPAD_RIGHT -> { state.dpadX = if (down) 1 else 0; true }
+                KeyEvent.KEYCODE_DPAD_UP -> { state.dpadY = if (down) -1 else 0; true }
+                KeyEvent.KEYCODE_DPAD_DOWN -> { state.dpadY = if (down) 1 else 0; true }
+                KeyEvent.KEYCODE_BUTTON_A, KeyEvent.KEYCODE_DPAD_CENTER,
+                KeyEvent.KEYCODE_ENTER, KeyEvent.KEYCODE_NUMPAD_ENTER -> { if (edge) currentOnActivate(); true }
+                KeyEvent.KEYCODE_BUTTON_X -> { if (edge) currentOnTertiary(); true }
+                KeyEvent.KEYCODE_BUTTON_Y -> { if (edge) currentOnSecondary(); true }
+                else -> false // B / shoulders → MainActivity (B remaps to BACK → BackHandler)
+            }
+        }
+        if (active) {
+            activity.padMotionProbe = motionProbe
+            activity.padKeyProbe = keyProbe
+        }
+        onDispose {
+            if (activity.padMotionProbe === motionProbe) activity.padMotionProbe = null
+            if (activity.padKeyProbe === keyProbe) activity.padKeyProbe = null
+            state.reset()
+        }
+    }
+
+    LaunchedEffect(active) {
+        if (!active) return@LaunchedEffect
+        var committed: NavDir? = null
+        var fireAt = 0L
+        while (isActive) {
+            val now = SystemClock.uptimeMillis()
+            val raw = resolveDir(state)
+            val nearCentre = state.dpadX == 0 && state.dpadY == 0 &&
+                abs(state.hatX) < 0.5f && abs(state.hatY) < 0.5f &&
+                abs(state.stickX) < STICK_LOW && abs(state.stickY) < STICK_LOW
+            when {
+                raw == null && nearCentre -> committed = null
+                raw == null -> { /* in the hysteresis band → hold, don't fire */ }
+                raw != committed -> { currentOnDirection(raw); committed = raw; fireAt = now + INITIAL_DELAY_MS }
+                now >= fireAt -> { currentOnDirection(raw); fireAt = now + REPEAT_MS }
+            }
+            delay(16)
+        }
+    }
+}
+
+/** The direction currently past the commit threshold (D-pad/HAT first, then the dominant stick axis). */
+private fun resolveDir(s: NavInputState): NavDir? {
+    if (s.dpadY < 0) return NavDir.UP
+    if (s.dpadY > 0) return NavDir.DOWN
+    if (s.dpadX < 0) return NavDir.LEFT
+    if (s.dpadX > 0) return NavDir.RIGHT
+    if (s.hatY <= -0.5f) return NavDir.UP
+    if (s.hatY >= 0.5f) return NavDir.DOWN
+    if (s.hatX <= -0.5f) return NavDir.LEFT
+    if (s.hatX >= 0.5f) return NavDir.RIGHT
+    return if (abs(s.stickY) >= abs(s.stickX)) {
+        when {
+            s.stickY <= -STICK_HIGH -> NavDir.UP
+            s.stickY >= STICK_HIGH -> NavDir.DOWN
+            else -> null
+        }
+    } else {
+        when {
+            s.stickX <= -STICK_HIGH -> NavDir.LEFT
+            s.stickX >= STICK_HIGH -> NavDir.RIGHT
+            else -> null
+        }
+    }
+}

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

@@ -0,0 +1,313 @@
+package io.unom.punktfunk
+
+import android.content.res.Configuration
+import androidx.activity.compose.BackHandler
+import androidx.compose.animation.core.animateFloatAsState
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.interaction.MutableInteractionSource
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.systemBarsPadding
+import androidx.compose.foundation.layout.widthIn
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.itemsIndexed
+import androidx.compose.foundation.lazy.rememberLazyListState
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableIntStateOf
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.graphicsLayer
+import androidx.compose.ui.platform.LocalConfiguration
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+import dev.chrisbanes.haze.HazeState
+import dev.chrisbanes.haze.hazeSource
+
+// The gamepad-driven settings screen — the Android mirror of the Apple client's GamepadSettingsView:
+// the couch-relevant subset of the touch settings restyled as a console page and fully navigable with
+// a controller: up/down moves the focus bar, left/right steps the focused value, A cycles/toggles it,
+// B closes. Both write the same SharedPreferences, so values round-trip with the touch settings.
+
+private class GpRow(
+    val id: String,
+    val header: String?,
+    val label: String,
+    val value: String,
+    val detail: String,
+    val adjust: (Int) -> Boolean, // left/right; returns whether the value actually changed
+    val activate: () -> Unit,     // A → cycle forward (wrapping) / flip
+)
+
+@Composable
+fun GamepadSettingsScreen(
+    initial: Settings,
+    onChange: (Settings) -> Unit,
+    onBack: () -> Unit,
+    navActive: Boolean = true, // false while this screen is cross-fading out, so it drops the pad
+) {
+    var s by remember { mutableStateOf(initial) }
+    fun update(next: Settings) { s = next; onChange(next) }
+
+    val rows = buildSettingsRows(s, ::update)
+    var focus by remember { mutableIntStateOf(0) }
+    if (focus > rows.lastIndex) focus = rows.lastIndex
+    val listState = rememberLazyListState()
+
+    val landscape = LocalConfiguration.current.orientation == Configuration.ORIENTATION_LANDSCAPE
+
+    BackHandler(onBack = onBack)
+    GamepadNavEffect2D(
+        active = navActive,
+        onDirection = { dir ->
+            when (dir) {
+                NavDir.UP -> if (focus > 0) focus--
+                NavDir.DOWN -> if (focus < rows.lastIndex) focus++
+                NavDir.LEFT -> rows.getOrNull(focus)?.adjust(-1)
+                NavDir.RIGHT -> rows.getOrNull(focus)?.adjust(1)
+            }
+        },
+        onActivate = { rows.getOrNull(focus)?.activate() },
+    )
+    // Keep the focused row on screen, but only SCROLL when it's actually off-screen — so entering the
+    // screen (focus on the first row) leaves the "Settings" heading visible instead of jumping past it.
+    // +1 accounts for the heading being item 0.
+    LaunchedEffect(focus) {
+        runCatching {
+            val itemIndex = focus + 1
+            val info = listState.layoutInfo
+            val item = info.visibleItemsInfo.firstOrNull { it.index == itemIndex }
+            val offScreen = item == null ||
+                item.offset < info.viewportStartOffset ||
+                item.offset + item.size > info.viewportEndOffset - 96 // keep clear of the floating legend
+            if (offScreen) listState.animateScrollToItem(itemIndex)
+        }
+    }
+
+    val hazeState = remember { HazeState() }
+
+    Box(Modifier.fillMaxSize()) {
+        // Everything scrolls — including the heading — so nothing is pinned. Vital in landscape,
+        // where a fixed title + a fixed detail/legend strip ate most of the (short) height.
+        Box(Modifier.fillMaxSize().hazeSource(hazeState)) {
+            GamepadFormBackground(Modifier.fillMaxSize())
+            LazyColumn(
+                state = listState,
+                modifier = Modifier.fillMaxSize().systemBarsPadding(),
+                contentPadding = PaddingValues(start = 24.dp, end = 24.dp, top = 8.dp, bottom = 104.dp),
+                verticalArrangement = Arrangement.spacedBy(6.dp),
+            ) {
+            item(key = "__title") {
+                ConsoleHeader("Settings", horizontalInset = false)
+            }
+            itemsIndexed(rows, key = { _, r -> r.id }) { index, row ->
+                SettingRowView(row, focused = index == focus, onClick = {
+                    if (focus == index) row.activate() else focus = index
+                })
+            }
+            }
+        }
+
+        // Floating frosted legend — a real backdrop blur of the rows scrolling behind it (no dedicated
+        // strip). In landscape it ignores the safe area so it hugs the corner instead of the nav-bar inset.
+        Box(
+            Modifier
+                .align(Alignment.BottomStart)
+                .then(if (landscape) Modifier else Modifier.systemBarsPadding())
+                .padding(ConsoleLegendInset),
+        ) {
+            GamepadHintBar(
+                listOf(
+                    GamepadHint('↔', Color(0xFF9A93C7), "Adjust"),
+                    // Tappable too (touch escape hatch): Change cycles the focused row, Done leaves.
+                    PadGlyph.hint('A', "Change") { rows.getOrNull(focus)?.activate() },
+                    PadGlyph.hint('B', "Done", onClick = onBack),
+                ),
+                hazeState = hazeState,
+            )
+        }
+    }
+}
+
+@Composable
+private fun SettingRowView(row: GpRow, focused: Boolean, onClick: () -> Unit) {
+    val scale by animateFloatAsState(if (focused) 1f else 0.98f, label = "rowScale")
+    val shape = RoundedCornerShape(14.dp)
+    Column {
+        if (row.header != null) {
+            Text(
+                row.header.uppercase(),
+                style = MaterialTheme.typography.labelMedium,
+                color = Color.White.copy(alpha = 0.45f),
+                letterSpacing = 1.4.sp,
+                modifier = Modifier.padding(start = 16.dp, top = 14.dp, bottom = 4.dp),
+            )
+        }
+        Column(
+            modifier = Modifier
+                .fillMaxWidth()
+                .graphicsLayer { scaleX = scale; scaleY = scale }
+                .clip(shape)
+                .background(if (focused) Color(0x336656F2) else Color(0x14FFFFFF))
+                .border(1.dp, Color.White.copy(alpha = if (focused) 0.28f else 0.06f), shape)
+                .clickable(
+                    interactionSource = remember { MutableInteractionSource() },
+                    indication = null,
+                    onClick = onClick,
+                )
+                .padding(horizontal = 16.dp, vertical = 13.dp),
+        ) {
+            Row(Modifier.fillMaxWidth(), verticalAlignment = Alignment.CenterVertically) {
+                Text(
+                    row.label,
+                    style = MaterialTheme.typography.bodyLarge,
+                    fontWeight = FontWeight.SemiBold,
+                    color = Color.White,
+                    maxLines = 1,
+                )
+                Spacer(Modifier.weight(1f))
+                if (focused) Text("‹ ", color = Color.White.copy(alpha = 0.6f))
+                Text(
+                    row.value,
+                    style = MaterialTheme.typography.bodyMedium,
+                    color = if (focused) Color.White else Color.White.copy(alpha = 0.6f),
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                )
+                if (focused) Text(" ›", color = Color.White.copy(alpha = 0.6f))
+            }
+            // The focused row carries its own one-line description — no dedicated (space-eating)
+            // detail strip. It appears right where you're looking, and the row grows to fit.
+            if (focused && row.detail.isNotBlank()) {
+                Text(
+                    row.detail,
+                    style = MaterialTheme.typography.bodySmall,
+                    color = Color.White.copy(alpha = 0.6f),
+                    maxLines = 2,
+                    modifier = Modifier.padding(top = 6.dp),
+                )
+            }
+        }
+    }
+}
+
+/** Build the console settings rows from the current [Settings], writing through [update]. */
+private fun buildSettingsRows(s: Settings, update: (Settings) -> Unit): List<GpRow> {
+    fun <T> choice(
+        id: String, header: String?, label: String, detail: String,
+        options: List<Pair<T, String>>, current: T, write: (T) -> Unit,
+    ): GpRow {
+        val idx = options.indexOfFirst { it.first == current }
+        return GpRow(
+            id, header, label,
+            value = options.getOrNull(idx)?.second ?: "—",
+            detail = detail,
+            adjust = { delta ->
+                if (idx < 0) {
+                    options.firstOrNull()?.let { write(it.first) } != null
+                } else {
+                    val t = idx + delta
+                    if (t in options.indices) { write(options[t].first); true } else false
+                }
+            },
+            activate = {
+                val i = if (idx < 0) 0 else (idx + 1) % options.size
+                options.getOrNull(i)?.let { write(it.first) }
+            },
+        )
+    }
+    fun toggle(
+        id: String, header: String?, label: String, detail: String,
+        value: Boolean, write: (Boolean) -> Unit,
+    ): GpRow = GpRow(
+        id, header, label,
+        value = if (value) "On" else "Off",
+        detail = detail,
+        adjust = { delta -> val target = delta > 0; if (value != target) { write(target); true } else false },
+        activate = { write(!value) },
+    )
+
+    return listOf(
+        choice(
+            "resolution", "Stream", "Resolution",
+            "The host creates a virtual display at exactly this size — no scaling.",
+            RESOLUTION_OPTIONS.map { (w, h, lbl) -> (w to h) to lbl }, s.width to s.height,
+        ) { (w, h) -> update(s.copy(width = w, height = h)) },
+        choice(
+            "refresh", null, "Refresh rate", "Frame rate the host renders and streams at.",
+            REFRESH_OPTIONS, s.hz,
+        ) { update(s.copy(hz = it)) },
+        choice(
+            "bitrate", null, "Bitrate",
+            "Automatic uses the host's default. Run a speed test from the touch UI for an informed value.",
+            BITRATE_OPTIONS, s.bitrateKbps,
+        ) { update(s.copy(bitrateKbps = it)) },
+        choice(
+            "compositor", null, "Compositor",
+            "Which compositor drives the virtual output — honored only if available on the host.",
+            COMPOSITOR_OPTIONS.mapIndexed { i, lbl -> i to lbl }, s.compositor,
+        ) { update(s.copy(compositor = it)) },
+
+        choice(
+            "codec", "Video", "Video codec",
+            "A preference — the host falls back if it can't encode this one.",
+            CODEC_OPTIONS, s.codec,
+        ) { update(s.copy(codec = it)) },
+        toggle(
+            "hdr", null, "10-bit HDR",
+            "HDR10 — engages when the host sends HDR content and this display supports it.",
+            s.hdrEnabled,
+        ) { update(s.copy(hdrEnabled = it)) },
+
+        choice(
+            "audio", "Audio", "Audio channels", "The speaker layout requested from the host.",
+            AUDIO_CHANNEL_OPTIONS, s.audioChannels,
+        ) { update(s.copy(audioChannels = it)) },
+        toggle(
+            "mic", null, "Microphone", "Send this device's microphone to the host's virtual mic.",
+            s.micEnabled,
+        ) { update(s.copy(micEnabled = it)) },
+
+        choice(
+            "padType", "Controller", "Controller type",
+            "The virtual pad the host creates — Automatic matches this controller.",
+            GAMEPAD_OPTIONS.mapIndexed { i, lbl -> i to lbl }, s.gamepad,
+        ) { update(s.copy(gamepad = it)) },
+
+        toggle(
+            "hud", "Interface", "Statistics overlay",
+            "Show FPS, throughput and latency while streaming.",
+            s.statsHudEnabled,
+        ) { update(s.copy(statsHudEnabled = it)) },
+        toggle(
+            "library", null, "Game library",
+            "Browse a paired host's games with Y (experimental).",
+            s.libraryEnabled,
+        ) { update(s.copy(libraryEnabled = it)) },
+        toggle(
+            "gamepadUI", null, "Controller-optimized UI",
+            "Turn off to use the touch interface even with a controller connected.",
+            s.gamepadUiEnabled,
+        ) { update(s.copy(gamepadUiEnabled = it)) },
+    )
+}

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

@@ -0,0 +1,63 @@
+package io.unom.punktfunk
+
+import android.app.UiModeManager
+import android.content.Context
+import android.content.pm.PackageManager
+import android.content.res.Configuration
+import android.hardware.input.InputManager
+import android.os.Handler
+import android.os.Looper
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.State
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.ui.platform.LocalContext
+import io.unom.punktfunk.kit.Gamepad
+
+/**
+ * Whether the controller-optimized "console" home (the host carousel + gamepad chrome) should
+ * replace the touch UI — the Android mirror of the Apple client's `GamepadUIEnvironment.isActive`:
+ * the user's [enabled] setting AND (a controller is attached OR this is a TV OR the dev [forced]
+ * flag). A TV counts unconditionally — its remote/gamepad is the only input, so it's always the
+ * console UI (as long as the setting is on).
+ */
+fun gamepadUiActive(enabled: Boolean, controllerConnected: Boolean, tv: Boolean, forced: Boolean): Boolean =
+    enabled && (controllerConnected || tv || forced)
+
+/** True on a TV: the leanback/television feature or the TELEVISION ui-mode. */
+fun isTvDevice(context: Context): Boolean {
+    val pm = context.packageManager
+    if (pm.hasSystemFeature(PackageManager.FEATURE_LEANBACK) ||
+        pm.hasSystemFeature(PackageManager.FEATURE_TELEVISION)
+    ) {
+        return true
+    }
+    val uiMode = context.getSystemService(Context.UI_MODE_SERVICE) as? UiModeManager
+    return uiMode?.currentModeType == Configuration.UI_MODE_TYPE_TELEVISION
+}
+
+/**
+ * Live "is a game controller attached" state, updated as pads connect/disconnect via
+ * [InputManager]'s device listener — so the home screen flips to the console UI the instant a pad is
+ * plugged in or paired, and back to touch when it's removed. Mirrors the reactivity the Apple client
+ * gets from observing `GamepadManager.shared`.
+ */
+@Composable
+fun rememberControllerConnected(): State<Boolean> {
+    val context = LocalContext.current
+    val connected = remember { mutableStateOf(Gamepad.firstPad() != null) }
+    DisposableEffect(Unit) {
+        val im = context.getSystemService(Context.INPUT_SERVICE) as InputManager
+        val listener = object : InputManager.InputDeviceListener {
+            private fun refresh() { connected.value = Gamepad.firstPad() != null }
+            override fun onInputDeviceAdded(deviceId: Int) = refresh()
+            override fun onInputDeviceRemoved(deviceId: Int) = refresh()
+            override fun onInputDeviceChanged(deviceId: Int) = refresh()
+        }
+        im.registerInputDeviceListener(listener, Handler(Looper.getMainLooper()))
+        connected.value = Gamepad.firstPad() != null
+        onDispose { im.unregisterInputDeviceListener(listener) }
+    }
+    return connected
+}

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

@@ -0,0 +1,297 @@
+package io.unom.punktfunk
+
+import androidx.activity.compose.BackHandler
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.BoxWithConstraints
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.systemBarsPadding
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.pager.HorizontalPager
+import androidx.compose.foundation.pager.PageSize
+import androidx.compose.foundation.pager.rememberPagerState
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.CircularProgressIndicator
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableIntStateOf
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.TransformOrigin
+import androidx.compose.ui.graphics.graphicsLayer
+import androidx.compose.ui.layout.ContentScale
+import android.content.res.Configuration
+import androidx.compose.ui.platform.LocalConfiguration
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.zIndex
+import dev.chrisbanes.haze.HazeState
+import dev.chrisbanes.haze.hazeSource
+import kotlinx.coroutines.launch
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+import coil.ImageLoader
+import coil.compose.AsyncImage
+import coil.request.ImageRequest
+import io.unom.punktfunk.kit.library.DEFAULT_MGMT_PORT
+import io.unom.punktfunk.kit.library.GameEntry
+import io.unom.punktfunk.kit.library.LibraryClient
+import io.unom.punktfunk.kit.library.LibraryResult
+import io.unom.punktfunk.kit.library.mtlsHttpClient
+import io.unom.punktfunk.kit.security.IdentityStore
+import io.unom.punktfunk.kit.security.KnownHost
+import io.unom.punktfunk.kit.security.obtainIdentity
+import kotlin.math.PI
+import kotlin.math.absoluteValue
+import kotlin.math.cos
+import kotlin.math.sign
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+
+// The host game-library browser — the Android mirror of the Apple client's LibraryCoverflowView:
+// a gamepad-driven poster coverflow (centered cover flat + prominent, neighbours receding on a 3D
+// Y-tilt) fetched from the host's management API over mTLS. Reached with Y from a saved host.
+
+private sealed class LibState {
+    object Loading : LibState()
+    data class Ready(val games: List<GameEntry>, val loader: ImageLoader) : LibState()
+    data class Message(val text: String) : LibState() // unauthorized / empty / error
+}
+
+@Composable
+fun LibraryScreen(host: KnownHost, onBack: () -> Unit, navActive: Boolean = true) {
+    BackHandler(onBack = onBack)
+    val context = LocalContext.current
+    val hazeState = remember { HazeState() }
+    val landscape = LocalConfiguration.current.orientation == Configuration.ORIENTATION_LANDSCAPE
+    var state by remember { mutableStateOf<LibState>(LibState.Loading) }
+
+    LaunchedEffect(host.address, host.port, host.fpHex) {
+        state = LibState.Loading
+        state = withContext(Dispatchers.IO) {
+            val id = runCatching { obtainIdentity(IdentityStore(context)) }.getOrNull()
+                ?: return@withContext LibState.Message("Identity unavailable — re-pair may be required.")
+            when (val res = LibraryClient.fetch(
+                address = host.address,
+                mgmtPort = DEFAULT_MGMT_PORT,
+                certPem = id.certPem,
+                keyPem = id.privateKeyPem,
+                fpHex = host.fpHex,
+            )) {
+                is LibraryResult.Ok -> if (res.games.isEmpty()) {
+                    LibState.Message("No games found on this host.")
+                } else {
+                    val client = mtlsHttpClient(id.certPem, id.privateKeyPem, host.address, host.fpHex)
+                    LibState.Ready(res.games, ImageLoader.Builder(context).okHttpClient(client).build())
+                }
+                is LibraryResult.Unauthorized -> LibState.Message(res.message)
+                is LibraryResult.Error -> LibState.Message(res.message)
+            }
+        }
+    }
+
+    Box(Modifier.fillMaxSize()) {
+        Box(Modifier.fillMaxSize().hazeSource(hazeState)) {
+            GamepadAuroraBackground(Modifier.fillMaxSize())
+            Column(Modifier.fillMaxSize().systemBarsPadding()) {
+                ConsoleHeader("${host.name} — Library")
+                Box(Modifier.weight(1f).fillMaxWidth(), contentAlignment = Alignment.Center) {
+                    when (val s = state) {
+                        is LibState.Loading -> LoadingState()
+                        is LibState.Message -> MessageState(s.text)
+                        is LibState.Ready -> Coverflow(s.games, s.loader, navActive)
+                    }
+                }
+            }
+        }
+        // Floating legend at the shared spot — same landscape-aware inset as every other console
+        // screen (ignore the safe area in landscape, where the bottom edge isn't a tap target).
+        Box(
+            Modifier.align(Alignment.BottomStart)
+                .then(if (landscape) Modifier else Modifier.systemBarsPadding())
+                .padding(ConsoleLegendInset),
+        ) {
+            GamepadHintBar(listOf(PadGlyph.hint('B', "Close", onClick = onBack)), hazeState = hazeState)
+        }
+    }
+}
+
+@Composable
+private fun LoadingState() {
+    Column(horizontalAlignment = Alignment.CenterHorizontally, verticalArrangement = Arrangement.spacedBy(14.dp)) {
+        CircularProgressIndicator(color = Color.White)
+        Text("Loading library…", color = Color.White.copy(alpha = 0.7f), style = MaterialTheme.typography.bodyLarge)
+    }
+}
+
+@Composable
+private fun MessageState(text: String) {
+    Text(
+        text,
+        color = Color.White.copy(alpha = 0.75f),
+        style = MaterialTheme.typography.bodyLarge,
+        textAlign = TextAlign.Center,
+        modifier = Modifier.padding(horizontal = 24.dp),
+    )
+}
+
+@Composable
+private fun Coverflow(games: List<GameEntry>, loader: ImageLoader, navActive: Boolean) {
+    BoxWithConstraints(Modifier.fillMaxSize()) {
+        // Fit a 2:3 poster into the height the detail line leaves; clamp so it never dwarfs the screen.
+        val coverHeight = (maxHeight * 0.72f).coerceAtMost(360.dp)
+        val coverWidth = coverHeight * 2f / 3f
+        val sidePad = ((maxWidth - coverWidth) / 2).coerceAtLeast(0.dp)
+        val pagerState = rememberPagerState(pageCount = { games.size })
+        val scope = rememberCoroutineScope()
+        var navTarget by remember { mutableIntStateOf(0) }
+        LaunchedEffect(pagerState.settledPage) { navTarget = pagerState.settledPage }
+        val current = games.getOrNull(navTarget)
+
+        // Controller nav: the pad drives the coverflow (it wasn't captured before). Left/right steps a
+        // coalesced target the pager chases; A is reserved for launch (browse-only for now); B closes
+        // via the screen's BackHandler.
+        GamepadNavEffect(
+            active = navActive && games.isNotEmpty(),
+            onMove = { dir ->
+                val t = (navTarget + dir).coerceIn(0, games.lastIndex)
+                if (t != navTarget) { navTarget = t; scope.launch { pagerState.animateScrollToPage(t) } }
+            },
+            onActivate = { /* launch a title — browse-only for now */ },
+        )
+
+        Column(Modifier.fillMaxSize(), verticalArrangement = Arrangement.Center) {
+            HorizontalPager(
+                state = pagerState,
+                pageSize = PageSize.Fixed(coverWidth),
+                contentPadding = PaddingValues(horizontal = sidePad),
+                pageSpacing = 0.dp,          // translationX (below) does the spacing so covers sit closer
+                beyondViewportPageCount = 3, // render more neighbours so a denser fan is visible
+                modifier = Modifier.fillMaxWidth().height(coverHeight + 24.dp),
+                verticalAlignment = Alignment.CenterVertically,
+            ) { page ->
+                val signed = (pagerState.currentPage - page) + pagerState.currentPageOffsetFraction
+                val d = signed.absoluteValue
+                Poster(
+                    game = games[page],
+                    loader = loader,
+                    modifier = Modifier
+                        .zIndex(-d) // centred cover on top, neighbours stacked behind
+                        .width(coverWidth)
+                        .height(coverHeight)
+                        .graphicsLayer {
+                            // Centre at full size; EVERY neighbour settles to one size, so an even pitch
+                            // yields even VISUAL gaps. (A progressive shrink made the outer gaps grow —
+                            // the "edges spread apart while the centre gets crowded" look.)
+                            val scale = 1f - 0.28f * d.coerceAtMost(1f)
+                            scaleX = scale
+                            scaleY = scale
+                            alpha = (1f - 0.26f * d).coerceAtLeast(0.15f) // depth via fade, not size
+                            val rotDeg = signed.coerceIn(-2.5f, 2.5f) * 26f // tilt inward
+                            rotationY = rotDeg
+                            // Even neighbour pitch (0.8·cover) + a little extra outward push (ramped over
+                            // the first step so scrolling stays smooth) so the CENTRE card breathes.
+                            val base = signed * size.width * 0.2f - signed.coerceIn(-1f, 1f) * size.width * 0.14f
+                            // Counter-balance: a rotated card projects narrower (≈cos θ), which opens its
+                            // inner gap — pull it back toward centre by the half-width it loses so the
+                            // gaps stay even no matter the tilt.
+                            val halfW = size.width * scale * 0.5f
+                            val counter = sign(signed) * halfW * (1f - cos(rotDeg * (PI.toFloat() / 180f)))
+                            translationX = base + counter
+                            // Lower cameraDistance = stronger perspective (CSS `perspective`); the flat
+                            // 22 washed the tilt out. 9 makes the same angle read as real depth.
+                            cameraDistance = 9f * density
+                            transformOrigin = TransformOrigin(0.5f, 0.5f)
+                        },
+                )
+            }
+            Column(
+                Modifier.fillMaxWidth().padding(top = 14.dp),
+                horizontalAlignment = Alignment.CenterHorizontally,
+            ) {
+                Text(
+                    current?.title ?: " ",
+                    style = MaterialTheme.typography.titleLarge,
+                    fontWeight = FontWeight.Bold,
+                    color = Color.White,
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                )
+                if (current != null) {
+                    Text(
+                        if (current.isCustom) "CUSTOM" else "STEAM",
+                        style = MaterialTheme.typography.labelMedium,
+                        color = Color.White.copy(alpha = 0.5f),
+                        letterSpacing = 2.sp,
+                    )
+                }
+            }
+        }
+    }
+}
+
+/** One cover: walks the art candidates (portrait → header → hero) then a text placeholder. */
+@Composable
+private fun Poster(game: GameEntry, loader: ImageLoader, modifier: Modifier = Modifier) {
+    val candidates = game.art.posterCandidates
+    var idx by remember(game.id) { mutableStateOf(0) }
+    val shape = RoundedCornerShape(16.dp)
+    Box(
+        modifier = modifier
+            .clip(shape)
+            .background(Color(0xFF241F3D))
+            .border(1.dp, Color.White.copy(alpha = 0.12f), shape),
+        contentAlignment = Alignment.Center,
+    ) {
+        if (idx < candidates.size) {
+            AsyncImage(
+                model = ImageRequest.Builder(LocalContext.current).data(candidates[idx]).build(),
+                imageLoader = loader,
+                contentDescription = game.title,
+                contentScale = ContentScale.Crop,
+                modifier = Modifier.fillMaxSize(),
+                onError = { idx++ }, // this candidate failed — try the next, or fall to the placeholder
+            )
+        } else {
+            Text(
+                game.title,
+                style = MaterialTheme.typography.titleMedium,
+                fontWeight = FontWeight.SemiBold,
+                color = Color.White.copy(alpha = 0.75f),
+                textAlign = TextAlign.Center,
+                modifier = Modifier.padding(12.dp),
+            )
+        }
+        // Store badge, top-start.
+        Box(Modifier.fillMaxSize().padding(8.dp), contentAlignment = Alignment.TopStart) {
+            Text(
+                if (game.isCustom) "Custom" else "Steam",
+                style = MaterialTheme.typography.labelSmall,
+                color = Color.White,
+                modifier = Modifier
+                    .clip(RoundedCornerShape(50))
+                    .background(Color.Black.copy(alpha = 0.5f))
+                    .padding(horizontal = 8.dp, vertical = 3.dp),
+            )
+        }
+    }
+}

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

@@ -3,14 +3,21 @@ package io.unom.punktfunk
 import androidx.activity.compose.BackHandler
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.rememberScrollState
 import androidx.compose.foundation.verticalScroll
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.automirrored.filled.ArrowBack
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.remember
+import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.text.font.FontFamily
@@ -31,6 +38,13 @@ fun LicensesScreen(onBack: () -> Unit) {
             context.assets.open("THIRD-PARTY-NOTICES.txt").bufferedReader().use { it.readText() }
         }.getOrDefault("Third-party notices unavailable.")
     }
+    // The bundled brand typeface (Geist Sans) ships under the SIL Open Font License 1.1. The OFL
+    // requires the license travel with the font, so surface it here (mirrors the Apple client).
+    val fontLicense = remember {
+        runCatching {
+            context.assets.open("GEIST-OFL.txt").bufferedReader().use { it.readText() }
+        }.getOrNull()
+    }
     val version = remember {
         runCatching {
             @Suppress("DEPRECATION")
@@ -38,29 +52,52 @@ fun LicensesScreen(onBack: () -> Unit) {
         }.getOrNull()
     }
 
-    Column(
-        modifier = Modifier
-            .fillMaxSize()
-            .verticalScroll(rememberScrollState())
-            .padding(horizontal = 20.dp, vertical = 24.dp),
-        verticalArrangement = Arrangement.spacedBy(16.dp),
-    ) {
-        Text("Open-source licenses", style = MaterialTheme.typography.headlineMedium)
-        if (version != null) {
-            Text(
-                "punktfunk $version",
-                style = MaterialTheme.typography.bodyMedium,
-                color = MaterialTheme.colorScheme.onSurfaceVariant,
-            )
+    Column(Modifier.fillMaxSize()) {
+        // Pinned header with a visible Back affordance (Back-button/gesture still work via BackHandler).
+        Row(
+            modifier = Modifier.fillMaxWidth().padding(start = 4.dp, end = 12.dp, top = 8.dp, bottom = 4.dp),
+            verticalAlignment = Alignment.CenterVertically,
+        ) {
+            IconButton(onClick = onBack) {
+                Icon(Icons.AutoMirrored.Filled.ArrowBack, contentDescription = "Back")
+            }
+            Text("Open-source licenses", style = MaterialTheme.typography.headlineSmall)
+        }
+        Column(
+            modifier = Modifier
+                .fillMaxSize()
+                .verticalScroll(rememberScrollState())
+                .padding(horizontal = 20.dp)
+                .padding(bottom = 24.dp),
+            verticalArrangement = Arrangement.spacedBy(16.dp),
+        ) {
+            if (version != null) {
+                Text(
+                    "Punktfunk $version",
+                    style = MaterialTheme.typography.bodyMedium,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+            Text(
+                "Punktfunk is licensed under MIT OR Apache-2.0, at your option. It uses the open-source " +
+                    "components below, each under its own license.",
+                style = MaterialTheme.typography.bodyMedium,
+            )
+            Text(
+                notices,
+                style = MaterialTheme.typography.bodySmall.copy(fontFamily = FontFamily.Monospace),
+            )
+            if (fontLicense != null) {
+                Text("Bundled font", style = MaterialTheme.typography.titleMedium)
+                Text(
+                    "The Geist typeface is licensed under the SIL Open Font License 1.1.",
+                    style = MaterialTheme.typography.bodyMedium,
+                )
+                Text(
+                    fontLicense,
+                    style = MaterialTheme.typography.bodySmall.copy(fontFamily = FontFamily.Monospace),
+                )
+            }
         }
-        Text(
-            "punktfunk is licensed under MIT OR Apache-2.0, at your option. It uses the open-source " +
-                "components below, each under its own license.",
-            style = MaterialTheme.typography.bodyMedium,
-        )
-        Text(
-            notices,
-            style = MaterialTheme.typography.bodySmall.copy(fontFamily = FontFamily.Monospace),
-        )
     }
 }

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

@@ -1,5 +1,6 @@
 package io.unom.punktfunk
 
+import android.os.Build
 import android.os.Bundle
 import android.view.InputDevice
 import android.view.KeyEvent
@@ -10,6 +11,9 @@ import androidx.activity.compose.setContent
 import androidx.activity.enableEdgeToEdge
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.material3.Surface
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
 import io.unom.punktfunk.kit.Gamepad
 import io.unom.punktfunk.kit.Keymap
@@ -34,8 +38,30 @@ class MainActivity : ComponentActivity() {
     var padKeyProbe: ((KeyEvent) -> Boolean)? = null
     var padMotionProbe: ((MotionEvent) -> Boolean)? = null
 
+    /**
+     * Set by [StreamScreen] to its disconnect action. The emergency-exit chord (below) invokes it so a
+     * couch user with no keyboard/Back can always leave a stream.
+     */
+    var requestStreamExit: (() -> Unit)? = null
+
+    /** Currently-held forwarded pad buttons (bitmask of `Gamepad.BTN_*`), for chord detection. */
+    private var heldPadButtons = 0
+
+    /**
+     * Whether the last console input came from a real gamepad (face buttons / stick) vs. a TV D-pad
+     * remote (which has no A/B/X/Y). The console UI reads this to show glyphs the user recognises — pad
+     * face buttons, or a select glyph + arrows for a remote. Compose observes it (a snapshot state).
+     */
+    var lastPadIsGamepad by mutableStateOf(false)
+        private set
+
+    /** The panel's highest-refresh display mode (0 = unknown/unsupported), resolved once at startup. */
+    private var highRefreshModeId = 0
+
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
+        resolveHighRefreshMode()
+        setConsoleHighRefreshRate(true) // the console UI wants max refresh; streaming manages its own
         // Dark, transparent system bars regardless of the system theme — our UI is always dark, so
         // the status/nav bars blend with our surface and get light icons. (The no-arg edge-to-edge
         // picks the *system* light/dark, which left a black status bar over our dark background.)
@@ -43,13 +69,39 @@ class MainActivity : ComponentActivity() {
             statusBarStyle = SystemBarStyle.dark(android.graphics.Color.TRANSPARENT),
             navigationBarStyle = SystemBarStyle.dark(android.graphics.Color.TRANSPARENT),
         )
+        // Dev escape hatch (mirrors the Apple client's PUNKTFUNK_FORCE_GAMEPAD_UI): force the console
+        // 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
         setContent {
             PunktfunkTheme {
-                Surface(modifier = Modifier.fillMaxSize()) { App() }
+                Surface(modifier = Modifier.fillMaxSize()) { App(forceGamepadUi = forceGamepadUi) }
             }
         }
     }
 
+    /** Resolve the panel's highest-refresh mode (same resolution) once, for [setConsoleHighRefreshRate]. */
+    private fun resolveHighRefreshMode() {
+        @Suppress("DEPRECATION")
+        val disp = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) display else windowManager.defaultDisplay
+        highRefreshModeId = disp?.supportedModes?.maxWithOrNull(
+            compareBy({ it.refreshRate }, { it.physicalWidth * it.physicalHeight }),
+        )?.modeId ?: 0
+    }
+
+    /**
+     * Opt the CONSOLE UI into the panel's highest refresh mode. Some OEMs (Nothing OS among them) pin
+     * third-party apps to 60Hz unless they explicitly ask for more, which halves the smoothness of the
+     * UI's scrolling/animation on a 120/144Hz panel. [StreamScreen] turns this OFF while streaming so
+     * its own `ANativeWindow_setFrameRate` (matched to the video) governs the panel instead.
+     */
+    fun setConsoleHighRefreshRate(high: Boolean) {
+        if (highRefreshModeId == 0) return
+        window.attributes = window.attributes.apply {
+            preferredDisplayModeId = if (high) highRefreshModeId else 0
+        }
+    }
+
     override fun dispatchKeyEvent(event: KeyEvent): Boolean {
         val handle = streamHandle
         if (handle != 0L) {
@@ -60,9 +112,20 @@ class MainActivity : ComponentActivity() {
                 if (bit != 0) {
                     when (event.action) {
                         // repeatCount guard: don't re-send a held button as auto-repeat.
-                        KeyEvent.ACTION_DOWN ->
+                        KeyEvent.ACTION_DOWN -> {
                             if (event.repeatCount == 0) NativeBridge.nativeSendGamepadButton(handle, bit, true)
-                        KeyEvent.ACTION_UP -> NativeBridge.nativeSendGamepadButton(handle, bit, false)
+                            heldPadButtons = heldPadButtons or bit
+                            // Emergency exit: Select + Start + L1 + R1 held together leaves the stream
+                            // (a couch user has no keyboard/Back). Fired once per full chord.
+                            if (heldPadButtons and STREAM_EXIT_CHORD == STREAM_EXIT_CHORD) {
+                                heldPadButtons = 0
+                                requestStreamExit?.let { exit -> window.decorView.post { exit() } }
+                            }
+                        }
+                        KeyEvent.ACTION_UP -> {
+                            NativeBridge.nativeSendGamepadButton(handle, bit, false)
+                            heldPadButtons = heldPadButtons and bit.inv()
+                        }
                     }
                     return true // consumed
                 }
@@ -90,18 +153,29 @@ class MainActivity : ComponentActivity() {
                 }
             }
         } else {
+            // Note which input the console UI is being driven by, so its glyphs match (a TV remote's
+            // D-pad is not from SOURCE_GAMEPAD; a pad's face buttons / D-pad are).
+            if (event.action == KeyEvent.ACTION_DOWN && isConsoleNavKey(event.keyCode)) {
+                lastPadIsGamepad = event.isFromSource(InputDevice.SOURCE_GAMEPAD)
+            }
             // The Controllers debug screen sees pad events before the navigation remap below.
             padKeyProbe?.let { if (it(event)) return true }
             if (event.isFromSource(InputDevice.SOURCE_GAMEPAD)) {
                 // Not streaming: a game controller drives the Compose UI (TV + phone). Map the face
-                // buttons to the navigation keys the focus system understands; D-pad *keys* already
-                // move focus on their own, so they fall through to super untouched.
-                val mapped = when (event.keyCode) {
-                    KeyEvent.KEYCODE_BUTTON_A -> KeyEvent.KEYCODE_DPAD_CENTER // activate focused element
-                    KeyEvent.KEYCODE_BUTTON_B -> KeyEvent.KEYCODE_BACK // back / dismiss
-                    else -> 0
+                // buttons to the navigation the focus system / back stack understand; D-pad *keys*
+                // already move focus on their own, so they fall through to super untouched.
+                when (event.keyCode) {
+                    // B → back. Drive the OnBackPressedDispatcher directly rather than synthesising a
+                    // BACK KeyEvent: a synthetic event isn't "tracking", so the framework's default
+                    // onKeyUp(BACK) never calls onBackPressed() and Compose BackHandlers wouldn't fire.
+                    KeyEvent.KEYCODE_BUTTON_B -> {
+                        if (event.action == KeyEvent.ACTION_UP) onBackPressedDispatcher.onBackPressed()
+                        return true
+                    }
+                    // A → activate the focused element (the focus system understands DPAD_CENTER).
+                    KeyEvent.KEYCODE_BUTTON_A ->
+                        return super.dispatchKeyEvent(KeyEvent(event.action, KeyEvent.KEYCODE_DPAD_CENTER))
                 }
-                if (mapped != 0) return super.dispatchKeyEvent(KeyEvent(event.action, mapped))
             }
         }
         return super.dispatchKeyEvent(event)
@@ -137,6 +211,7 @@ class MainActivity : ComponentActivity() {
             if (dir != lastNavDir) {
                 lastNavDir = dir
                 if (dir != 0) {
+                    lastPadIsGamepad = true // a stick/HAT push can only come from a real gamepad
                     super.dispatchKeyEvent(KeyEvent(KeyEvent.ACTION_DOWN, dir))
                     super.dispatchKeyEvent(KeyEvent(KeyEvent.ACTION_UP, dir))
                     return true
@@ -147,4 +222,17 @@ class MainActivity : ComponentActivity() {
         }
         return super.dispatchGenericMotionEvent(event)
     }
+
+    /** Keys that drive the console UI — D-pad + face buttons; used to classify the last input source. */
+    private fun isConsoleNavKey(kc: Int): Boolean = when (kc) {
+        KeyEvent.KEYCODE_DPAD_UP, KeyEvent.KEYCODE_DPAD_DOWN, KeyEvent.KEYCODE_DPAD_LEFT,
+        KeyEvent.KEYCODE_DPAD_RIGHT, KeyEvent.KEYCODE_DPAD_CENTER, KeyEvent.KEYCODE_ENTER,
+        -> true
+        else -> KeyEvent.isGamepadButton(kc)
+    }
+
+    private companion object {
+        /** Emergency stream-exit chord: Select + Start + L1 + R1 held together. */
+        val STREAM_EXIT_CHORD = Gamepad.BTN_BACK or Gamepad.BTN_START or Gamepad.BTN_LB or Gamepad.BTN_RB
+    }
 }

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

@@ -41,6 +41,27 @@ data class Settings(
      * understand touch. Mirrors the Apple client's TouchInputMode.
      */
     val touchMode: TouchMode = TouchMode.TRACKPAD,
+    /**
+     * Swap the whole home screen for the controller-optimized "console" UI (the host carousel +
+     * gamepad chrome) whenever a controller is connected — mirrors the Apple client's
+     * `gamepadUIEnabled`. On by default; turn it off to keep the touch UI even with a pad attached.
+     * A TV (leanback) is always in this mode regardless (its remote/pad is the only input).
+     */
+    val gamepadUiEnabled: Boolean = true,
+    /**
+     * Show the experimental game-library browser (the coverflow reached with Y from a saved host).
+     * Fetched from the host's management API over mTLS; needs a paired host. Mirrors the Apple
+     * client's `libraryEnabled`.
+     */
+    val libraryEnabled: Boolean = true,
+    /**
+     * Aggressive decoder latency tuning — the master escape hatch. On (default): the decoder runs
+     * the full low-latency profile (per-SoC vendor keys + max-clock operating-rate on Qualcomm).
+     * Off: a conservative profile (the standard `low-latency` key only), for a device that thermally
+     * throttles or misbehaves under the aggressive clocks. Decoder ranking, the Wi-Fi low-latency
+     * lock and HDMI game-mode signalling stay on regardless — they're harmless.
+     */
+    val lowLatencyMode: Boolean = true,
 )
 
 /** [Settings.touchMode] values; persisted by name. */
@@ -67,6 +88,9 @@ class SettingsStore(context: Context) {
             ?.let { name -> TouchMode.entries.firstOrNull { it.name == name } }
             // Migration: the pre-enum Boolean "trackpad_mode" (true = trackpad, false = direct).
             ?: if (prefs.getBoolean(K_TRACKPAD, true)) TouchMode.TRACKPAD else TouchMode.POINTER,
+        gamepadUiEnabled = prefs.getBoolean(K_GAMEPAD_UI, true),
+        libraryEnabled = prefs.getBoolean(K_LIBRARY, true),
+        lowLatencyMode = prefs.getBoolean(K_LOW_LATENCY, true),
     )
 
     fun save(s: Settings) {
@@ -83,6 +107,9 @@ class SettingsStore(context: Context) {
             .putBoolean(K_MIC, s.micEnabled)
             .putBoolean(K_HUD, s.statsHudEnabled)
             .putString(K_TOUCH_MODE, s.touchMode.name)
+            .putBoolean(K_GAMEPAD_UI, s.gamepadUiEnabled)
+            .putBoolean(K_LIBRARY, s.libraryEnabled)
+            .putBoolean(K_LOW_LATENCY, s.lowLatencyMode)
             .apply()
     }
 
@@ -99,6 +126,9 @@ class SettingsStore(context: Context) {
         const val K_MIC = "mic_enabled"
         const val K_HUD = "stats_hud_enabled"
         const val K_TOUCH_MODE = "touch_mode"
+        const val K_GAMEPAD_UI = "gamepad_ui_enabled"
+        const val K_LIBRARY = "library_enabled"
+        const val K_LOW_LATENCY = "low_latency_mode"
 
         /** Legacy Boolean the enum replaced — read once as the migration default, never written. */
         const val K_TRACKPAD = "trackpad_mode"

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

@@ -5,44 +5,79 @@ import android.content.pm.PackageManager
 import androidx.activity.compose.BackHandler
 import androidx.activity.compose.rememberLauncherForActivityResult
 import androidx.activity.result.contract.ActivityResultContracts
+import androidx.compose.animation.AnimatedContent
+import androidx.compose.animation.core.tween
+import androidx.compose.animation.fadeIn
+import androidx.compose.animation.fadeOut
+import androidx.compose.animation.slideInHorizontally
+import androidx.compose.animation.slideOutHorizontally
+import androidx.compose.animation.togetherWith
+import androidx.compose.foundation.background
 import androidx.compose.foundation.clickable
 import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.BoxWithConstraints
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.ColumnScope
 import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxHeight
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
 import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.shape.RoundedCornerShape
 import androidx.compose.foundation.verticalScroll
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.automirrored.filled.ArrowBack
+import androidx.compose.material.icons.automirrored.filled.KeyboardArrowRight
+import androidx.compose.material.icons.filled.Info
+import androidx.compose.material.icons.filled.SportsEsports
+import androidx.compose.material.icons.filled.Tune
+import androidx.compose.material.icons.filled.Tv
+import androidx.compose.material.icons.filled.VolumeUp
 import androidx.compose.material3.DropdownMenuItem
 import androidx.compose.material3.ExperimentalMaterial3Api
 import androidx.compose.material3.ExposedDropdownMenuBox
 import androidx.compose.material3.ExposedDropdownMenuAnchorType
 import androidx.compose.material3.ExposedDropdownMenuDefaults
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.OutlinedCard
 import androidx.compose.material3.OutlinedTextField
 import androidx.compose.material3.Switch
 import androidx.compose.material3.Text
+import androidx.compose.material3.VerticalDivider
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
+import androidx.compose.runtime.saveable.rememberSaveable
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.vector.ImageVector
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.unit.dp
 import androidx.core.content.ContextCompat
 
 /**
- * Stream settings, grouped into Display / Host / Audio / Overlay cards. Edits are persisted
- * immediately via [onChange]; [onBack] returns to the connect screen. Resolution/refresh "Native"
- * resolve from the device display at connect time.
+ * Stream settings, organised as an iOS-Settings / Android-system-settings style list of category
+ * subpages. On a phone the category list pushes to a full-screen detail; on a tablet / large screen
+ * it becomes a two-pane list-detail (the list stays on the left, the detail on the right). Edits
+ * persist immediately via [onChange]; [onBack] returns to the connect screen.
  */
 @Composable
-fun SettingsScreen(initial: Settings, onChange: (Settings) -> Unit, onBack: () -> Unit) {
+fun SettingsScreen(
+    initial: Settings,
+    onChange: (Settings) -> Unit,
+    onBack: () -> Unit,
+) {
     var s by remember { mutableStateOf(initial) }
     val context = LocalContext.current
     var showLicenses by remember { mutableStateOf(false) }
@@ -52,13 +87,20 @@ fun SettingsScreen(initial: Settings, onChange: (Settings) -> Unit, onBack: () -
         onChange(next)
     }
 
-    BackHandler(onBack = onBack)
-
     // Mic uplink — turning it on requests RECORD_AUDIO; if denied, the toggle stays off.
     val micLauncher = rememberLauncherForActivityResult(
         ActivityResultContracts.RequestPermission(),
     ) { granted -> update(s.copy(micEnabled = granted)) }
+    val onMicChange: (Boolean) -> Unit = { on ->
+        when {
+            !on -> update(s.copy(micEnabled = false))
+            ContextCompat.checkSelfPermission(context, Manifest.permission.RECORD_AUDIO) ==
+                PackageManager.PERMISSION_GRANTED -> update(s.copy(micEnabled = true))
+            else -> micLauncher.launch(Manifest.permission.RECORD_AUDIO)
+        }
+    }
 
+    // Deep sub-screens replace the whole settings surface (they carry their own back).
     if (showLicenses) {
         LicensesScreen(onBack = { showLicenses = false })
         return
@@ -68,160 +110,322 @@ fun SettingsScreen(initial: Settings, onChange: (Settings) -> Unit, onBack: () -
         return
     }
 
-    Column(
-        modifier = Modifier
-            .fillMaxSize()
-            .verticalScroll(rememberScrollState())
-            .padding(horizontal = 20.dp, vertical = 24.dp),
-        verticalArrangement = Arrangement.spacedBy(24.dp),
-    ) {
-        Text("Settings", style = MaterialTheme.typography.headlineMedium)
+    // Selected category persists across rotation (stored by name — null = the bare list on a phone).
+    var selectedName by rememberSaveable { mutableStateOf<String?>(null) }
+    val selected = selectedName?.let { n -> SettingsCategory.entries.firstOrNull { it.name == n } }
 
-        val (nw, nh, nhz) = nativeDisplayMode(context)
+    BoxWithConstraints(Modifier.fillMaxSize()) {
+        val twoPane = maxWidth >= 640.dp
+        // A two-column layout must never show an empty detail — land on the first category.
+        LaunchedEffect(twoPane) {
+            if (twoPane && selected == null) selectedName = SettingsCategory.Display.name
+        }
 
-        SettingsGroup("Display") {
-            SettingDropdown(
-                label = "Resolution",
-                options = RESOLUTION_OPTIONS.map { (w, h, lbl) ->
-                    (w to h) to (if (w == 0) "$lbl ($nw × $nh)" else lbl)
-                },
-                selected = s.width to s.height,
-            ) { (w, h) -> update(s.copy(width = w, height = h)) }
-
-            SettingDropdown(
-                label = "Refresh rate",
-                options = REFRESH_OPTIONS.map { (hz, lbl) -> hz to (if (hz == 0) "$lbl ($nhz Hz)" else lbl) },
-                selected = s.hz,
-            ) { hz -> update(s.copy(hz = hz)) }
-
-            SettingDropdown(
-                label = "Bitrate",
-                options = BITRATE_OPTIONS,
-                selected = s.bitrateKbps,
-            ) { kbps -> update(s.copy(bitrateKbps = kbps)) }
-
-            SettingDropdown(
-                label = "Video codec",
-                options = CODEC_OPTIONS,
-                selected = s.codec,
-            ) { c -> update(s.copy(codec = c)) }
-
-            // HDR is only meaningful on a panel that can present HDR10; on an SDR display the toggle
-            // is disabled (and HDR is never advertised regardless) so the host doesn't send PQ the
-            // panel would mis-tone-map. The capability is fixed for the device, so read it once.
-            val hdrCapable = remember { displaySupportsHdr(context) }
-            ToggleRow(
-                title = "HDR",
-                subtitle = if (hdrCapable) {
-                    "Stream 10-bit HDR (BT.2020 PQ) when the host supports it"
-                } else {
-                    "This display can't present HDR10 — streams stay SDR"
-                },
-                checked = s.hdrEnabled && hdrCapable,
-                enabled = hdrCapable,
-                onCheckedChange = { on -> update(s.copy(hdrEnabled = on)) },
+        val detail: @Composable (SettingsCategory, (() -> Unit)?) -> Unit = { cat, back ->
+            CategoryDetail(
+                category = cat,
+                settings = s,
+                onChange = ::update,
+                context = context,
+                onMicChange = onMicChange,
+                onOpenControllers = { showControllers = true },
+                onOpenLicenses = { showLicenses = true },
+                onBack = back,
             )
         }
 
-        SettingsGroup("Host") {
-            SettingDropdown(
-                label = "Compositor",
-                options = COMPOSITOR_OPTIONS.mapIndexed { i, lbl -> i to lbl },
-                selected = s.compositor,
-            ) { c -> update(s.copy(compositor = c)) }
-
-            SettingDropdown(
-                label = "Controller type",
-                options = GAMEPAD_OPTIONS.mapIndexed { i, lbl -> i to lbl },
-                selected = s.gamepad,
-            ) { g -> update(s.copy(gamepad = g)) }
-
-            ClickableRow(
-                title = "Connected controllers",
-                subtitle = "What the app detects, with a live input test",
-                onClick = { showControllers = true },
-            )
-        }
-
-        SettingsGroup("Audio") {
-            SettingDropdown(
-                label = "Audio channels",
-                options = AUDIO_CHANNEL_OPTIONS,
-                selected = s.audioChannels,
-            ) { ch -> update(s.copy(audioChannels = ch)) }
-
-            ToggleRow(
-                title = "Microphone",
-                subtitle = "Send your mic to the host's virtual microphone",
-                checked = s.micEnabled,
-                onCheckedChange = { on ->
-                    when {
-                        !on -> update(s.copy(micEnabled = false))
-                        ContextCompat.checkSelfPermission(context, Manifest.permission.RECORD_AUDIO) ==
-                            PackageManager.PERMISSION_GRANTED -> update(s.copy(micEnabled = true))
-                        else -> micLauncher.launch(Manifest.permission.RECORD_AUDIO)
+        if (twoPane) {
+            BackHandler(onBack = onBack)
+            Row(Modifier.fillMaxSize()) {
+                CategoryList(
+                    selected = selected,
+                    twoPane = true,
+                    onSelect = { selectedName = it.name },
+                    modifier = Modifier.width(300.dp).fillMaxHeight(),
+                )
+                VerticalDivider()
+                Box(Modifier.weight(1f).fillMaxHeight()) {
+                    // Cross-fade the detail pane as the selected category changes.
+                    AnimatedContent(
+                        targetState = selected ?: SettingsCategory.Display,
+                        transitionSpec = { fadeIn(tween(200)) togetherWith fadeOut(tween(200)) },
+                        label = "SettingsPane",
+                    ) { cat -> detail(cat, null) }
+                }
+            }
+        } else {
+            // Compact: the category list pushes to a full-screen detail and back, like the iOS /
+            // Android system settings — a horizontal slide that tracks the drill-in direction.
+            BackHandler { if (selected != null) selectedName = null else onBack() }
+            AnimatedContent(
+                targetState = selected,
+                transitionSpec = {
+                    if (targetState != null) {
+                        slideInHorizontally { it } + fadeIn() togetherWith
+                            slideOutHorizontally { -it } + fadeOut()
+                    } else {
+                        slideInHorizontally { -it } + fadeIn() togetherWith
+                            slideOutHorizontally { it } + fadeOut()
                     }
                 },
-            )
-        }
-
-        SettingsGroup("Touch input") {
-            SettingDropdown(
-                label = "Touch input",
-                options = TOUCH_MODE_OPTIONS,
-                selected = s.touchMode,
-                onSelect = { mode -> update(s.copy(touchMode = mode)) },
-            )
-            Text(
-                "Trackpad: relative cursor like a laptop touchpad — tap to click, two-finger " +
-                    "tap right-clicks, two fingers scroll, tap-then-drag holds the button. " +
-                    "Direct pointer: the cursor jumps to your finger. Touch passthrough: real " +
-                    "multi-touch reaches the host, for apps that understand touch.",
-                style = MaterialTheme.typography.bodySmall,
-                color = MaterialTheme.colorScheme.onSurfaceVariant,
-                modifier = Modifier.padding(top = 6.dp),
-            )
-        }
-
-        SettingsGroup("Overlay") {
-            ToggleRow(
-                title = "Stats overlay",
-                subtitle = "Show FPS, throughput and latency while streaming (3-finger tap toggles it live)",
-                checked = s.statsHudEnabled,
-                onCheckedChange = { on -> update(s.copy(statsHudEnabled = on)) },
-            )
-        }
-
-        SettingsGroup("About") {
-            ClickableRow(
-                title = "Open-source licenses",
-                subtitle = "Third-party notices and credits",
-                onClick = { showLicenses = true },
-            )
+                label = "SettingsPush",
+            ) { sel ->
+                if (sel == null) {
+                    CategoryList(
+                        selected = null,
+                        twoPane = false,
+                        onSelect = { selectedName = it.name },
+                        modifier = Modifier.fillMaxSize(),
+                    )
+                } else {
+                    detail(sel) { selectedName = null }
+                }
+            }
         }
     }
 }
 
-/** A titled group of settings rendered inside an outlined card. */
+/** The top-level settings groups — each opens its own subpage (list on phone, split on tablet). */
+enum class SettingsCategory(val title: String, val icon: ImageVector) {
+    Display("Display", Icons.Filled.Tv),
+    Audio("Audio", Icons.Filled.VolumeUp),
+    Controls("Controls", Icons.Filled.SportsEsports),
+    Interface("Interface", Icons.Filled.Tune),
+    About("About", Icons.Filled.Info),
+}
+
+/** The category list — the settings root. Highlights the [selected] row when it drives a detail pane. */
 @Composable
-private fun SettingsGroup(title: String, content: @Composable ColumnScope.() -> Unit) {
-    Column(verticalArrangement = Arrangement.spacedBy(10.dp)) {
+private fun CategoryList(
+    selected: SettingsCategory?,
+    twoPane: Boolean,
+    onSelect: (SettingsCategory) -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    Column(
+        modifier
+            .verticalScroll(rememberScrollState())
+            .padding(horizontal = 12.dp, vertical = 20.dp),
+        verticalArrangement = Arrangement.spacedBy(2.dp),
+    ) {
         Text(
-            title,
-            style = MaterialTheme.typography.titleSmall,
-            color = MaterialTheme.colorScheme.primary,
-            modifier = Modifier.padding(start = 4.dp),
+            "Settings",
+            style = MaterialTheme.typography.headlineMedium,
+            modifier = Modifier.padding(start = 8.dp, bottom = 12.dp),
         )
-        OutlinedCard(modifier = Modifier.fillMaxWidth()) {
-            Column(
-                modifier = Modifier.padding(16.dp),
-                verticalArrangement = Arrangement.spacedBy(16.dp),
-                content = content,
-            )
+        SettingsCategory.entries.forEach { cat ->
+            val highlighted = twoPane && selected == cat
+            Row(
+                modifier = Modifier
+                    .fillMaxWidth()
+                    .clip(RoundedCornerShape(14.dp))
+                    .background(if (highlighted) MaterialTheme.colorScheme.secondaryContainer else Color.Transparent)
+                    .clickable { onSelect(cat) }
+                    .padding(horizontal = 14.dp, vertical = 15.dp),
+                verticalAlignment = Alignment.CenterVertically,
+            ) {
+                Icon(
+                    cat.icon,
+                    contentDescription = null,
+                    tint = MaterialTheme.colorScheme.primary,
+                    modifier = Modifier.padding(end = 16.dp),
+                )
+                Text(cat.title, style = MaterialTheme.typography.bodyLarge, modifier = Modifier.weight(1f))
+                if (!twoPane) {
+                    Icon(
+                        Icons.AutoMirrored.Filled.KeyboardArrowRight,
+                        contentDescription = null,
+                        tint = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+            }
         }
     }
 }
 
+/** One category's controls. [onBack] non-null (phone push) shows a back arrow; null (tablet pane) hides it. */
+@Composable
+private fun CategoryDetail(
+    category: SettingsCategory,
+    settings: Settings,
+    onChange: (Settings) -> Unit,
+    context: android.content.Context,
+    onMicChange: (Boolean) -> Unit,
+    onOpenControllers: () -> Unit,
+    onOpenLicenses: () -> Unit,
+    onBack: (() -> Unit)?,
+) {
+    Column(
+        Modifier
+            .fillMaxSize()
+            .verticalScroll(rememberScrollState())
+            .padding(horizontal = 20.dp, vertical = 16.dp),
+        verticalArrangement = Arrangement.spacedBy(20.dp),
+    ) {
+        Row(verticalAlignment = Alignment.CenterVertically) {
+            if (onBack != null) {
+                IconButton(onClick = onBack, modifier = Modifier.padding(end = 4.dp)) {
+                    Icon(Icons.AutoMirrored.Filled.ArrowBack, contentDescription = "Back")
+                }
+            }
+            Text(category.title, style = MaterialTheme.typography.headlineMedium)
+        }
+        when (category) {
+            SettingsCategory.Display -> DisplaySettings(settings, onChange, context)
+            SettingsCategory.Audio -> AudioSettings(settings, onChange, onMicChange)
+            SettingsCategory.Controls -> ControlsSettings(settings, onChange, onOpenControllers)
+            SettingsCategory.Interface -> InterfaceSettings(settings, onChange)
+            SettingsCategory.About -> AboutSettings(onOpenLicenses)
+        }
+    }
+}
+
+@Composable
+private fun DisplaySettings(s: Settings, update: (Settings) -> Unit, context: android.content.Context) {
+    val (nw, nh, nhz) = nativeDisplayMode(context)
+    SettingsCard {
+        SettingDropdown(
+            label = "Resolution",
+            options = RESOLUTION_OPTIONS.map { (w, h, lbl) -> (w to h) to (if (w == 0) "$lbl ($nw × $nh)" else lbl) },
+            selected = s.width to s.height,
+        ) { (w, h) -> update(s.copy(width = w, height = h)) }
+
+        SettingDropdown(
+            label = "Refresh rate",
+            options = REFRESH_OPTIONS.map { (hz, lbl) -> hz to (if (hz == 0) "$lbl ($nhz Hz)" else lbl) },
+            selected = s.hz,
+        ) { hz -> update(s.copy(hz = hz)) }
+
+        SettingDropdown(label = "Bitrate", options = BITRATE_OPTIONS, selected = s.bitrateKbps) { kbps ->
+            update(s.copy(bitrateKbps = kbps))
+        }
+
+        SettingDropdown(label = "Video codec", options = CODEC_OPTIONS, selected = s.codec) { c ->
+            update(s.copy(codec = c))
+        }
+
+        // HDR is only meaningful on a panel that can present HDR10; on an SDR display the toggle is
+        // disabled (and HDR is never advertised) so the host doesn't send PQ the panel mis-tone-maps.
+        val hdrCapable = remember { displaySupportsHdr(context) }
+        ToggleRow(
+            title = "HDR",
+            subtitle = if (hdrCapable) {
+                "Stream 10-bit HDR (BT.2020 PQ) when the host supports it"
+            } else {
+                "This display can't present HDR10 — streams stay SDR"
+            },
+            checked = s.hdrEnabled && hdrCapable,
+            enabled = hdrCapable,
+            onCheckedChange = { on -> update(s.copy(hdrEnabled = on)) },
+        )
+
+        SettingDropdown(
+            label = "Compositor",
+            options = COMPOSITOR_OPTIONS.mapIndexed { i, lbl -> i to lbl },
+            selected = s.compositor,
+        ) { c -> update(s.copy(compositor = c)) }
+
+        ToggleRow(
+            title = "Low-latency mode",
+            subtitle = "Run the decoder at max clocks for the lowest latency. Turn off only if a " +
+                "device overheats or glitches during long sessions.",
+            checked = s.lowLatencyMode,
+            onCheckedChange = { on -> update(s.copy(lowLatencyMode = on)) },
+        )
+    }
+}
+
+@Composable
+private fun AudioSettings(s: Settings, update: (Settings) -> Unit, onMicChange: (Boolean) -> Unit) {
+    SettingsCard {
+        SettingDropdown(label = "Audio channels", options = AUDIO_CHANNEL_OPTIONS, selected = s.audioChannels) { ch ->
+            update(s.copy(audioChannels = ch))
+        }
+        ToggleRow(
+            title = "Microphone",
+            subtitle = "Send your mic to the host's virtual microphone",
+            checked = s.micEnabled,
+            onCheckedChange = onMicChange,
+        )
+    }
+}
+
+@Composable
+private fun ControlsSettings(s: Settings, update: (Settings) -> Unit, onOpenControllers: () -> Unit) {
+    SettingsCard {
+        SettingDropdown(label = "Touch input", options = TOUCH_MODE_OPTIONS, selected = s.touchMode) { mode ->
+            update(s.copy(touchMode = mode))
+        }
+        Text(
+            "Trackpad: relative cursor like a laptop touchpad — tap to click, two-finger tap " +
+                "right-clicks, two fingers scroll, tap-then-drag holds the button. Direct pointer: " +
+                "the cursor jumps to your finger. Touch passthrough: real multi-touch reaches the " +
+                "host, for apps that understand touch.",
+            style = MaterialTheme.typography.bodySmall,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+        )
+    }
+    SettingsCard {
+        SettingDropdown(
+            label = "Controller type",
+            options = GAMEPAD_OPTIONS.mapIndexed { i, lbl -> i to lbl },
+            selected = s.gamepad,
+        ) { g -> update(s.copy(gamepad = g)) }
+        ClickableRow(
+            title = "Connected controllers",
+            subtitle = "What the app detects, with a live input test",
+            onClick = onOpenControllers,
+        )
+    }
+}
+
+@Composable
+private fun InterfaceSettings(s: Settings, update: (Settings) -> Unit) {
+    SettingsCard {
+        ToggleRow(
+            title = "Controller-optimized UI",
+            subtitle = "Switch to the console home (host carousel) when a controller is connected",
+            checked = s.gamepadUiEnabled,
+            onCheckedChange = { on -> update(s.copy(gamepadUiEnabled = on)) },
+        )
+        ToggleRow(
+            title = "Game library",
+            subtitle = "Browse a paired host's game library (press Y on a saved host)",
+            checked = s.libraryEnabled,
+            onCheckedChange = { on -> update(s.copy(libraryEnabled = on)) },
+        )
+        ToggleRow(
+            title = "Stats overlay",
+            subtitle = "Show FPS, throughput and latency while streaming (3-finger tap toggles it live)",
+            checked = s.statsHudEnabled,
+            onCheckedChange = { on -> update(s.copy(statsHudEnabled = on)) },
+        )
+    }
+}
+
+@Composable
+private fun AboutSettings(onOpenLicenses: () -> Unit) {
+    SettingsCard {
+        ClickableRow(
+            title = "Open-source licenses",
+            subtitle = "Third-party notices and credits",
+            onClick = onOpenLicenses,
+        )
+    }
+}
+
+/** A group of settings rendered inside an outlined card. */
+@Composable
+private fun SettingsCard(content: @Composable ColumnScope.() -> Unit) {
+    OutlinedCard(modifier = Modifier.fillMaxWidth()) {
+        Column(
+            modifier = Modifier.padding(16.dp),
+            verticalArrangement = Arrangement.spacedBy(16.dp),
+            content = content,
+        )
+    }
+}
+
 /** A title + subtitle on the left, a Switch on the right. [enabled] greys out the whole row. */
 @Composable
 private fun ToggleRow(
@@ -265,6 +469,12 @@ private fun ClickableRow(title: String, subtitle: String, onClick: () -> Unit) {
                 color = MaterialTheme.colorScheme.onSurfaceVariant,
             )
         }
+        Icon(
+            Icons.AutoMirrored.Filled.KeyboardArrowRight,
+            contentDescription = null,
+            tint = MaterialTheme.colorScheme.onSurfaceVariant,
+            modifier = Modifier.size(20.dp),
+        )
     }
 }
 

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

@@ -27,7 +27,7 @@ import kotlin.math.roundToInt
  * older layouts just omit those lines.
  */
 @Composable
-internal fun StatsOverlay(s: DoubleArray, modifier: Modifier = Modifier) {
+internal fun StatsOverlay(s: DoubleArray, decoderLabel: String = "", modifier: Modifier = Modifier) {
     if (s.size < 10) return
     val w = s[6].toInt()
     val h = s[7].toInt()
@@ -46,6 +46,14 @@ internal fun StatsOverlay(s: DoubleArray, modifier: Modifier = Modifier) {
             fontFamily = FontFamily.Monospace,
             fontSize = 12.sp,
         )
+        if (decoderLabel.isNotEmpty()) {
+            Text(
+                decoderLabel,
+                color = Color(0xFFB0D0FF),
+                fontFamily = FontFamily.Monospace,
+                fontSize = 12.sp,
+            )
+        }
         videoFeedLine(s)?.let { feed ->
             Text(
                 feed,

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

@@ -1,8 +1,11 @@
 package io.unom.punktfunk
 
 import android.Manifest
+import android.content.Context
 import android.content.pm.ActivityInfo
 import android.content.pm.PackageManager
+import android.net.wifi.WifiManager
+import android.os.Build
 import android.view.SurfaceHolder
 import android.view.SurfaceView
 import android.view.WindowManager
@@ -30,6 +33,7 @@ import androidx.core.view.WindowInsetsControllerCompat
 import io.unom.punktfunk.kit.Gamepad
 import io.unom.punktfunk.kit.GamepadFeedback
 import io.unom.punktfunk.kit.NativeBridge
+import io.unom.punktfunk.kit.VideoDecoders
 import java.util.concurrent.atomic.AtomicBoolean
 import kotlinx.coroutines.delay
 
@@ -55,15 +59,23 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
     // comes from Settings.
     val initialSettings = remember { SettingsStore(context).load() }
     var stats by remember { mutableStateOf<DoubleArray?>(null) }
+    var decoderLabel by remember { mutableStateOf("") }
     var showStats by remember { mutableStateOf(initialSettings.statsHudEnabled) }
     // Touch model is fixed per session (re-keys the gesture handler below if it ever changes).
     val touchMode = initialSettings.touchMode
+    // Master low-latency toggle, resolved once for the session and passed to the decoder at start.
+    val lowLatencyMode = initialSettings.lowLatencyMode
+    // TV form factor (leanback): the decoder actively switches the HDMI output mode to the stream
+    // refresh; a phone/tablet gets the softer seamless frame-rate hint instead.
+    val isTv = remember { context.packageManager.hasSystemFeature(PackageManager.FEATURE_LEANBACK) }
     LaunchedEffect(handle, showStats) {
         NativeBridge.nativeSetVideoStatsEnabled(handle, showStats)
         if (showStats) {
             while (true) {
                 delay(1000)
                 stats = NativeBridge.nativeVideoStats(handle)
+                // The decoder is fixed for the session; fetch its label once it's resolved.
+                if (decoderLabel.isEmpty()) decoderLabel = NativeBridge.nativeVideoDecoderLabel(handle)
             }
         } else {
             stats = null // drop the last snapshot so a re-show never flashes stale numbers
@@ -76,8 +88,29 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
     // main thread, so a plain flag is race-free; AtomicBoolean just makes the intent explicit.
     val closed = remember { AtomicBoolean(false) }
 
+    // A Wi-Fi low-latency lock held for the stream's duration: asks the Wi-Fi firmware to drop its
+    // power-save polling (a common source of tens-of-ms jitter). WIFI_MODE_FULL_LOW_LATENCY (API
+    // 29+) is the strongest; older releases fall back to FULL_HIGH_PERF. Needs no extra permission
+    // beyond ACCESS_WIFI_STATE (already declared). Non-reference-counted: one explicit acquire/release.
+    val wifiLock = remember(handle) {
+        val wm = context.applicationContext.getSystemService(Context.WIFI_SERVICE) as? WifiManager
+        val mode = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+            WifiManager.WIFI_MODE_FULL_LOW_LATENCY
+        } else {
+            @Suppress("DEPRECATION")
+            WifiManager.WIFI_MODE_FULL_HIGH_PERF
+        }
+        wm?.createWifiLock(mode, "punktfunk:stream")?.apply { setReferenceCounted(false) }
+    }
+
     DisposableEffect(handle) {
         window?.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
+        runCatching { wifiLock?.acquire() }
+        // HDMI Auto Low-Latency Mode: ask the display to drop its post-processing (game mode) —
+        // the biggest panel-side latency win on the TV boxes. No-op where ALLM isn't supported. API 30+.
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            window?.setPreferMinimalPostProcessing(true)
+        }
         controller?.let {
             it.systemBarsBehavior = WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE
             it.hide(WindowInsetsCompat.Type.systemBars())
@@ -91,6 +124,8 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
         activity?.requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE
         activity?.streamHandle = handle // route hardware keys to this session
         activity?.axisMapper = Gamepad.AxisMapper(handle) // route joystick axes
+        activity?.requestStreamExit = onDisconnect // Select+Start+L1+R1 chord leaves the stream
+        activity?.setConsoleHighRefreshRate(false) // let the decoder's setFrameRate pick the panel rate
         // Host→client feedback (rumble + DualSense lightbar/LEDs); poll threads stopped before close.
         val feedback = GamepadFeedback(handle).also { it.start() }
         onDispose {
@@ -99,8 +134,14 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
             activity?.axisMapper?.reset() // release-all so nothing sticks on the host
             activity?.axisMapper = null
             activity?.streamHandle = 0L
+            activity?.requestStreamExit = null
+            activity?.setConsoleHighRefreshRate(true) // back to the console UI's max refresh
             controller?.show(WindowInsetsCompat.Type.systemBars())
             window?.clearFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+                window?.setPreferMinimalPostProcessing(false)
+            }
+            runCatching { if (wifiLock?.isHeld == true) wifiLock.release() }
             // Release the landscape lock so the rest of the app follows the device/system again.
             activity?.requestedOrientation =
                 priorOrientation ?: ActivityInfo.SCREEN_ORIENTATION_UNSPECIFIED
@@ -121,7 +162,19 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
                 SurfaceView(ctx).apply {
                     holder.addCallback(object : SurfaceHolder.Callback {
                         override fun surfaceCreated(holder: SurfaceHolder) {
-                            NativeBridge.nativeStartVideo(handle, holder.surface)
+                            // Rank MediaCodecList decoders for the negotiated MIME (framework-only
+                            // API) and hand the chosen one to Rust, which creates it by name and
+                            // applies the per-SoC vendor low-latency keys.
+                            val mime = NativeBridge.nativeVideoMime(handle)
+                            val choice = VideoDecoders.pickDecoder(mime)
+                            NativeBridge.nativeStartVideo(
+                                handle,
+                                holder.surface,
+                                choice?.name ?: "",
+                                lowLatencyMode,
+                                choice?.lowLatencyFeature ?: false,
+                                isTv,
+                            )
                             NativeBridge.nativeStartAudio(handle)
                             if (micWanted) NativeBridge.nativeStartMic(handle)
                         }
@@ -146,7 +199,7 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
         // Live stats HUD (FPS / throughput / capture→client latency), drawn over the video but
         // BEFORE the transparent gesture layer below, so it shows through and never eats touches.
         if (showStats) {
-            stats?.let { StatsOverlay(it, Modifier.align(Alignment.TopStart).padding(12.dp)) }
+            stats?.let { StatsOverlay(it, decoderLabel, Modifier.align(Alignment.TopStart).padding(12.dp)) }
         }
         // Touch input per the Settings model: trackpad/direct-pointer mouse (the shared gesture
         // vocabulary) or real multi-touch passthrough — see TouchInput.kt.

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

@@ -41,5 +41,7 @@ fun PunktfunkTheme(content: @Composable () -> Unit) {
     } else {
         BrandDark
     }
-    MaterialTheme(colorScheme = scheme, content = content)
+    // Geist Sans across the whole type scale — the brand typeface the website and the Apple client
+    // already ship (see Type.kt).
+    MaterialTheme(colorScheme = scheme, typography = PunktfunkTypography, content = content)
 }

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

@@ -0,0 +1,44 @@
+package io.unom.punktfunk
+
+import androidx.compose.material3.Typography
+import androidx.compose.ui.text.font.Font
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.text.font.FontWeight
+
+// Geist — the punktfunk brand typeface (the same family the website and the Apple client ship).
+// Bundled as static OTF weights in res/font and applied to every Material 3 text style below, so the
+// Android UI carries the brand type identically to the other clients. Geist Sans only — Geist Mono
+// is intentionally not shipped (the licenses screen's technical block uses the platform monospace).
+//
+// Licensed under the SIL Open Font License 1.1 (see the Geist OFL entry in THIRD-PARTY-NOTICES.txt).
+val Geist = FontFamily(
+    Font(R.font.geist_regular, FontWeight.Normal),
+    Font(R.font.geist_medium, FontWeight.Medium),
+    Font(R.font.geist_semibold, FontWeight.SemiBold),
+    Font(R.font.geist_bold, FontWeight.Bold),
+)
+
+/**
+ * The default Material 3 type scale re-based on [Geist]. Material 3's [Typography] has no
+ * `defaultFontFamily` shortcut (that was Material 2), so each of the 15 roles is re-emitted with the
+ * Geist family while keeping Material's sizes, line heights, letter spacing and per-role weights.
+ */
+val PunktfunkTypography: Typography = Typography().run {
+    Typography(
+        displayLarge = displayLarge.copy(fontFamily = Geist),
+        displayMedium = displayMedium.copy(fontFamily = Geist),
+        displaySmall = displaySmall.copy(fontFamily = Geist),
+        headlineLarge = headlineLarge.copy(fontFamily = Geist),
+        headlineMedium = headlineMedium.copy(fontFamily = Geist),
+        headlineSmall = headlineSmall.copy(fontFamily = Geist),
+        titleLarge = titleLarge.copy(fontFamily = Geist),
+        titleMedium = titleMedium.copy(fontFamily = Geist),
+        titleSmall = titleSmall.copy(fontFamily = Geist),
+        bodyLarge = bodyLarge.copy(fontFamily = Geist),
+        bodyMedium = bodyMedium.copy(fontFamily = Geist),
+        bodySmall = bodySmall.copy(fontFamily = Geist),
+        labelLarge = labelLarge.copy(fontFamily = Geist),
+        labelMedium = labelMedium.copy(fontFamily = Geist),
+        labelSmall = labelSmall.copy(fontFamily = Geist),
+    )
+}

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

@@ -0,0 +1,125 @@
+package io.unom.punktfunk
+
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.setValue
+import io.unom.punktfunk.kit.NativeBridge
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.isActive
+import kotlinx.coroutines.launch
+
+/**
+ * Wake a sleeping host and WAIT for it to come back before proceeding — the Android mirror of the
+ * Apple client's `HostWaker`.
+ *
+ * A magic packet is fire-and-forget, and a cold box can take 20–60 s to POST, boot, and start
+ * advertising on mDNS again — far longer than a connect attempt will sit. So instead of firing one
+ * packet and immediately dialing (which just fails on a genuinely-asleep host), this drives a visible
+ * "Waking…" state: it (re-)sends the packet, polls the host's mDNS presence once a second via
+ * [isOnline], and on success runs [onOnline] (the real connect for a Wake-&-Connect, or nothing for
+ * a wake-only); on timeout it parks in a retry/cancel state. One wake at a time.
+ *
+ * [scope] is the composition's coroutine scope (main-dispatched), so [waking] mutations and the
+ * [isOnline]/[onOnline] callbacks all run on the main thread; only the blocking send is off-loaded.
+ */
+class WakeController(private val scope: CoroutineScope) {
+    /** null = idle; non-null drives [WakeOverlay]. */
+    data class Waking(
+        val hostName: String,
+        /** Whether coming online chains into a connect (Wake & Connect) vs. just stopping. */
+        val connectsAfter: Boolean,
+        val seconds: Int = 0,
+        val timedOut: Boolean = false,
+    )
+
+    var waking by mutableStateOf<Waking?>(null)
+        private set
+
+    private var loop: Job? = null
+
+    /** Captured so "Try Again" replays the exact same wait. */
+    private var replay: (() -> Unit)? = null
+
+    /**
+     * Wake the host and wait for [isOnline] to go true, then run [onOnline]. [macs]/[lastIp] target
+     * the magic packet. No-ops straight to [onOnline] when there's nothing to wake with or the host
+     * is already up (a race between the caller's check and here).
+     */
+    fun start(
+        hostName: String,
+        connectsAfter: Boolean,
+        macs: List<String>,
+        lastIp: String,
+        isOnline: () -> Boolean,
+        onOnline: () -> Unit,
+    ) {
+        if (macs.isEmpty() || isOnline()) {
+            cancel()
+            onOnline()
+            return
+        }
+        replay = { run(hostName, connectsAfter, macs, lastIp, isOnline, onOnline) }
+        replay?.invoke()
+    }
+
+    /** Stop waiting and dismiss the overlay (B / Cancel). */
+    fun cancel() {
+        loop?.cancel()
+        loop = null
+        replay = null
+        waking = null
+    }
+
+    /** Restart the wait after a timeout (A / Try Again). */
+    fun retry() {
+        replay?.invoke()
+    }
+
+    private fun run(
+        hostName: String,
+        connectsAfter: Boolean,
+        macs: List<String>,
+        lastIp: String,
+        isOnline: () -> Boolean,
+        onOnline: () -> Unit,
+    ) {
+        loop?.cancel()
+        waking = Waking(hostName = hostName, connectsAfter = connectsAfter)
+        loop = scope.launch {
+            var elapsed = 0
+            while (isActive) {
+                // Re-send periodically: a single packet can be missed, and some NICs only wake on a
+                // fresh packet after dropping into a deeper sleep state.
+                if (elapsed % RESEND_EVERY_S == 0) {
+                    val csv = macs.joinToString(",")
+                    launch(Dispatchers.IO) { NativeBridge.nativeWakeOnLan(csv, lastIp) }
+                }
+                if (isOnline()) {
+                    waking = null
+                    loop = null
+                    onOnline()
+                    return@launch
+                }
+                if (elapsed >= TIMEOUT_S) {
+                    waking = waking?.copy(timedOut = true)
+                    loop = null
+                    return@launch
+                }
+                delay(1000)
+                elapsed++
+                waking = waking?.copy(seconds = elapsed)
+            }
+        }
+    }
+
+    companion object {
+        /** How long to wait for the host to reappear before giving up (a cold boot can be a minute+). */
+        const val TIMEOUT_S = 90
+
+        /** Re-send the magic packet this often. */
+        const val RESEND_EVERY_S = 6
+    }
+}

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

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

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

@@ -59,7 +59,7 @@ fun HostCard(
     enabled: Boolean,
     onConnect: () -> Unit,
     onForget: (() -> Unit)?,
-    onRename: (() -> Unit)? = null,
+    onEdit: (() -> Unit)? = null,
     onWake: (() -> Unit)? = null,
 ) {
     // D-pad / controller focus highlight: a clickable card is focusable, but the default state
@@ -108,7 +108,7 @@ fun HostCard(
                 StatusPill(status)
             }
 
-            if (onForget != null || onRename != null || onWake != null) {
+            if (onForget != null || onEdit != null || onWake != null) {
                 var menu by remember { mutableStateOf(false) }
                 Box(modifier = Modifier.align(Alignment.TopEnd)) {
                     IconButton(enabled = enabled, onClick = { menu = true }) {
@@ -129,12 +129,12 @@ fun HostCard(
                                 },
                             )
                         }
-                        if (onRename != null) {
+                        if (onEdit != null) {
                             DropdownMenuItem(
-                                text = { Text("Rename") },
+                                text = { Text("Edit…") },
                                 onClick = {
                                     menu = false
-                                    onRename()
+                                    onEdit()
                                 },
                             )
                         }

clients/android/app/src/main/res/xml/game_mode_config.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Game Mode config (Android 13 / API 33+). We support the Performance game mode; and we opt OUT of
+  the two OEM interventions that would corrupt a game-streaming session:
+    - allowGameDownscaling=false: the client renders exactly the host's negotiated resolution; a
+      platform downscale would blur the stream.
+    - allowGameFpsOverride=false: the stream is paced to the host's frame rate; a platform FPS cap
+      would drop frames / add judder.
+  Ignored on releases below API 33.
+-->
+<game-mode-config xmlns:android="http://schemas.android.com/apk/res/android"
+    android:supportsPerformanceGameMode="true"
+    android:allowGameDownscaling="false"
+    android:allowGameFpsOverride="false" />

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

@@ -83,7 +83,7 @@ internal fun HostsScene() {
             }
             item(span = { GridItemSpan(maxLineSpan) }) { SectionLabel("Saved hosts") }
             items(SAVED) { h ->
-                HostCard(h.name, h.address, h.status, enabled = true, onConnect = {}, onForget = {}, onRename = {})
+                HostCard(h.name, h.address, h.status, enabled = true, onConnect = {}, onForget = {}, onEdit = {})
             }
             item(span = { GridItemSpan(maxLineSpan) }) {
                 Spacer(Modifier.height(12.dp))

clients/android/kit/build.gradle.kts

@@ -15,8 +15,10 @@ android {
     ndkVersion = ndkVer
 
     defaultConfig {
-        minSdk = 31
-        ndk { abiFilters += listOf("arm64-v8a", "x86_64") }
+        minSdk = 28 // Android 9 — reaches older TV boxes; API 31+ features are runtime-gated.
+        // Keep in lockstep with :app — 32-bit armeabi-v7a for the many 32-bit Google TV / Android TV
+        // boxes, 64-bit arm64-v8a for phones + modern TV, x86_64 for the emulator.
+        ndk { abiFilters += listOf("arm64-v8a", "armeabi-v7a", "x86_64") }
     }
     compileOptions {
         sourceCompatibility = JavaVersion.VERSION_21
@@ -28,6 +30,9 @@ android {
 kotlin { compilerOptions { jvmTarget.set(JvmTarget.JVM_21) } }
 
 dependencies {
+    // mTLS HTTPS client for the host's management API (the game-library fetch + cover-art loads).
+    // OkHttp lets us present the paired client cert and pin the host's self-signed cert by SHA-256.
+    implementation("com.squareup.okhttp3:okhttp:4.12.0")
     testImplementation("junit:junit:4.13.2") // JVM unit test for the pure TXT parser
 }
 
@@ -85,9 +90,11 @@ fun registerCargoNdk(taskName: String, release: Boolean) =
         // find their subtools.
         val cmd = mutableListOf(
             "$cargoBin/cargo", "ndk",
-            "-t", "arm64-v8a", "-t", "x86_64",
-            // Link against the minSdk-31 sysroot so libaaudio (API 26+) is found.
-            "--platform", "31",
+            "-t", "arm64-v8a", "-t", "armeabi-v7a", "-t", "x86_64",
+            // Link against the minSdk-28 sysroot: libaaudio (API 26) is present, and building at the
+            // floor makes the linker reject any accidental >28 hard import (the one API-30 call we
+            // make, ANativeWindow_setFrameRate, is dlsym-resolved — see decode::try_set_frame_rate).
+            "--platform", "28",
             "-o", file("src/main/jniLibs").absolutePath,
             "build", "-p", "punktfunk-client-android",
         )

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

@@ -8,6 +8,7 @@ import android.hardware.lights.LightsRequest
 import android.os.Build
 import android.os.CombinedVibration
 import android.os.VibrationEffect
+import android.os.Vibrator
 import android.os.VibratorManager
 import android.util.Log
 import android.view.InputDevice
@@ -16,7 +17,8 @@ import java.nio.ByteBuffer
 /**
  * Host→client gamepad feedback for one session (single-pad model — pad 0 only). Two daemon poll
  * threads drain the blocking native pulls and render in Kotlin: rumble → the controller's
- * `VibratorManager`; HID-output → lightbar / player-LED via `LightsManager` (API 33+); adaptive
+ * `VibratorManager` (API 31+) or its single legacy `Vibrator` on API 28–30; HID-output → lightbar /
+ * player-LED via `LightsManager` (API 33+); adaptive
  * triggers are parse-validated and logged (Android has no public adaptive-trigger API).
  *
  * Mirrors `nativeStartAudio`'s lifecycle: [start]/[stop] driven by the StreamScreen. [stop] flips a
@@ -40,6 +42,9 @@ class GamepadFeedback(private val handle: Long) {
     private var hidoutThread: Thread? = null
 
     private var vm: VibratorManager? = null
+    // API 28–30 fallback: the controller's single legacy Vibrator (no per-motor VibratorManager
+    // until API 31). Exactly one of [vm] / [legacy] is bound; rumble degrades to one blended motor.
+    private var legacy: Vibrator? = null
     private var vibratorIds: IntArray = IntArray(0)
     private var amplitudeControlled = false
 
@@ -81,6 +86,7 @@ class GamepadFeedback(private val handle: Long) {
         rumbleThread?.interrupt()
         hidoutThread?.interrupt()
         runCatching { vm?.cancel() } // drop any held rumble immediately
+        runCatching { legacy?.cancel() }
         // Join WITHOUT a timeout. These poll threads dereference the native session handle on every
         // pull (nativeNextRumble/nativeNextHidout), so they MUST be dead before StreamScreen's
         // onDispose reaches nativeClose, which frees that handle. A *bounded* join that times out
@@ -98,6 +104,7 @@ class GamepadFeedback(private val handle: Long) {
         rgbLight = null
         playerLight = null
         vm = null
+        legacy = null
         vibratorIds = IntArray(0)
     }
 
@@ -111,39 +118,65 @@ class GamepadFeedback(private val handle: Long) {
             Log.i(TAG, "rumble: no controller connected — rumble no-op (emulator path)")
             return
         }
-        val m = dev.vibratorManager
-        val ids = m.vibratorIds
-        if (ids.isEmpty()) {
-            Log.i(TAG, "rumble: controller '${dev.name}' has no vibrators — rumble no-op")
-            return
+        if (Build.VERSION.SDK_INT >= 31) {
+            val m = dev.vibratorManager
+            val ids = m.vibratorIds
+            if (ids.isEmpty()) {
+                Log.i(TAG, "rumble: controller '${dev.name}' has no vibrators — rumble no-op")
+                return
+            }
+            vm = m
+            vibratorIds = ids
+            amplitudeControlled = ids.all { m.getVibrator(it).hasAmplitudeControl() }
+            Log.i(TAG, "rumble: bound ${ids.size} vibrators amplitudeControl=$amplitudeControlled")
+        } else {
+            // API 28–30: no VibratorManager — fall back to the controller's single legacy Vibrator.
+            @Suppress("DEPRECATION")
+            val v = dev.vibrator
+            if (!v.hasVibrator()) {
+                Log.i(TAG, "rumble: controller '${dev.name}' has no vibrator — rumble no-op")
+                return
+            }
+            legacy = v
+            amplitudeControlled = v.hasAmplitudeControl()
+            Log.i(TAG, "rumble: bound legacy vibrator amplitudeControl=$amplitudeControlled")
         }
-        vm = m
-        vibratorIds = ids
-        amplitudeControlled = ids.all { m.getVibrator(it).hasAmplitudeControl() }
-        Log.i(TAG, "rumble: bound ${ids.size} vibrators amplitudeControl=$amplitudeControlled")
     }
 
     /** low = heavy/left motor, high = light/right motor; both 0..0xFFFF (the host's u16 amplitudes). */
     private fun renderRumble(low: Int, high: Int) {
         Log.i(TAG, "rumble low=$low high=$high") // verification line — BEFORE any no-op return
-        val m = vm ?: return
         val lo = toAmplitude(low)
         val hi = toAmplitude(high)
-        if (lo == 0 && hi == 0) {
-            m.cancel() // (0,0) = stop
+        val m = vm
+        if (m != null) {
+            if (lo == 0 && hi == 0) {
+                m.cancel() // (0,0) = stop
+                return
+            }
+            val combo = CombinedVibration.startParallel()
+            if (amplitudeControlled && vibratorIds.size >= 2) {
+                // ids[0] = light/right, ids[1] = heavy/left (XInput/Moonlight convention).
+                if (hi != 0) combo.addVibrator(vibratorIds[0], oneShot(hi))
+                if (lo != 0) combo.addVibrator(vibratorIds[1], oneShot(lo))
+            } else {
+                // Single motor or no amplitude control: blend both into one effect.
+                val a = (lo * 0.8 + hi * 0.33).toInt().coerceIn(1, 255)
+                for (id in vibratorIds) combo.addVibrator(id, oneShot(a))
+            }
+            runCatching { m.vibrate(combo.combine()) }
             return
         }
-        val combo = CombinedVibration.startParallel()
-        if (amplitudeControlled && vibratorIds.size >= 2) {
-            // ids[0] = light/right, ids[1] = heavy/left (XInput/Moonlight convention).
-            if (hi != 0) combo.addVibrator(vibratorIds[0], oneShot(hi))
-            if (lo != 0) combo.addVibrator(vibratorIds[1], oneShot(lo))
-        } else {
-            // Single motor or no amplitude control: blend both into one effect.
-            val a = (lo * 0.8 + hi * 0.33).toInt().coerceIn(1, 255)
-            for (id in vibratorIds) combo.addVibrator(id, oneShot(a))
+        // API 28–30 legacy single-motor path: blend both motors into one effect.
+        val lv = legacy ?: return
+        if (lo == 0 && hi == 0) {
+            lv.cancel() // (0,0) = stop
+            return
+        }
+        val a = (lo * 0.8 + hi * 0.33).toInt().coerceIn(1, 255)
+        runCatching {
+            lv.vibrate(if (amplitudeControlled) oneShot(a) else oneShot(VibrationEffect.DEFAULT_AMPLITUDE))
         }
-        runCatching { m.vibrate(combo.combine()) }
     }
 
     // 0..0xFFFF → 1..255 (high byte); a nonzero motor never collapses to 0.

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

@@ -104,14 +104,40 @@ object NativeBridge {
     external fun nativeWakeOnLan(macsCsv: String, lastIp: String): Boolean
 
     /**
-     * Start the HEVC decode thread rendering onto [surface] (a SurfaceView's surface). Decode runs
-     * entirely in Rust (NDK AMediaCodec → ANativeWindow) — no per-frame JNI. No-op if already started.
+     * The MediaCodec MIME the host resolved for this session (`"video/hevc"` / `"video/avc"` /
+     * `"video/av01"`), or `""` on a `0` handle. Kotlin ranks `MediaCodecList` decoders for this
+     * MIME (see [io.unom.punktfunk.kit.VideoDecoders]) before [nativeStartVideo]. Cheap; UI-safe.
      */
-    external fun nativeStartVideo(handle: Long, surface: android.view.Surface)
+    external fun nativeVideoMime(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
+     * decoder Kotlin ranked from `MediaCodecList` (`""` = let the platform resolve the default for
+     * the MIME); [lowLatencyMode] is the user's master toggle (default on → aggressive per-SoC
+     * tuning; off → conservative); [lowLatencyFeature] is whether [decoderName] advertised
+     * `FEATURE_LowLatency` (HUD label only). [isTv] drives an active HDMI mode switch to the stream
+     * refresh on TV boxes (vs. the softer seamless hint on phones). No-op if already started.
+     */
+    external fun nativeStartVideo(
+        handle: Long,
+        surface: android.view.Surface,
+        decoderName: String,
+        lowLatencyMode: Boolean,
+        lowLatencyFeature: Boolean,
+        isTv: Boolean,
+    )
 
     /** Stop + join the decode thread without closing the session. No-op on `0`. */
     external fun nativeStopVideo(handle: Long)
 
+    /**
+     * 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 (fixed for the session); poll once after
+     * the HUD appears.
+     */
+    external fun nativeVideoDecoderLabel(handle: Long): String
+
     /**
      * Drain ~1 s of live decode stats for the on-stream HUD, or `null` when no decode thread runs.
      * Returns 18 doubles (unified stats spec, `design/stats-unification.md`):

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

@@ -0,0 +1,85 @@
+package io.unom.punktfunk.kit
+
+import android.media.MediaCodecInfo.CodecCapabilities
+import android.media.MediaCodecList
+import android.os.Build
+
+/** The decoder Kotlin ranked for a MIME, handed to [NativeBridge.nativeStartVideo]. */
+data class DecoderChoice(val name: String, val lowLatencyFeature: Boolean)
+
+/**
+ * Rank the platform's `MediaCodecList` decoders for a video MIME and pick the best one for
+ * low-latency streaming, the way Moonlight-Android does. There is no NDK `MediaCodecList`, so this
+ * enumeration must live on the Kotlin (framework) side; Rust then creates the chosen decoder by
+ * name (`AMediaCodec_createCodecByName`) and derives the per-SoC vendor low-latency keys from it.
+ *
+ * Ranking (best first): hardware over software; a real SoC-vendor decoder (Qualcomm/Amlogic/…) over
+ * the generic AOSP software fallback; a decoder advertising `FEATURE_LowLatency` over one that
+ * doesn't. Known-bad software decoders (`omx.google.*`, `c2.android.*`, Qualcomm/Samsung SW HEVC)
+ * are dropped outright — matching Moonlight's blacklist.
+ */
+object VideoDecoders {
+    /** Decoder-name prefixes/names we never want, mirroring Moonlight's blacklist. */
+    private val BLOCKED_PREFIXES = listOf("omx.google.", "c2.android.", "avcdecoder", "omx.ffmpeg.")
+    private val BLOCKED_EXACT = listOf("omx.qcom.video.decoder.hevcswvdec", "omx.sec.hevc.sw.dec")
+
+    /**
+     * Real SoC-vendor decoder prefixes we prefer over the generic AOSP fallback, covering the common
+     * targets: Qualcomm Snapdragon and MediaTek (most phones + many TV boxes), Samsung Exynos (+
+     * Google Tensor, whose decoder is `c2.exynos.*`), NVIDIA Tegra (Shield TV), Amlogic / Rockchip /
+     * Realtek (TV boxes & smart TVs), and HiSilicon Kirin (older Huawei).
+     */
+    private val VENDOR_PREFIXES = listOf(
+        "omx.qcom", "c2.qti",
+        "omx.mtk", "c2.mtk",
+        "omx.exynos", "c2.exynos",
+        "omx.nvidia", "c2.nvidia",
+        "omx.amlogic", "c2.amlogic",
+        "omx.rk", "c2.rk",
+        "omx.realtek", "c2.realtek",
+        "omx.hisi", "c2.hisi",
+    )
+
+    /**
+     * Pick the best decoder for [mime] (`"video/hevc"` / `"video/avc"` / `"video/av01"`), or `null`
+     * to let the platform resolve its default. Enumerates once — call at stream start.
+     */
+    fun pickDecoder(mime: String): DecoderChoice? {
+        if (mime.isEmpty()) return null
+        val infos = runCatching { MediaCodecList(MediaCodecList.REGULAR_CODECS).codecInfos }
+            .getOrNull() ?: return null
+
+        var bestName: String? = null
+        var bestLowLatency = false
+        var bestScore = Int.MIN_VALUE
+        for (info in infos) {
+            if (info.isEncoder) continue
+            val name = info.name
+            val lower = name.lowercase()
+            if (BLOCKED_PREFIXES.any { lower.startsWith(it) } || lower in BLOCKED_EXACT) continue
+            val caps = runCatching { info.getCapabilitiesForType(mime) }.getOrNull() ?: continue
+
+            val hardware = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+                info.isHardwareAccelerated
+            } else {
+                // Pre-Q heuristic: the software decoders are the ones we can name (already blocked
+                // above), so anything surviving the blacklist is treated as hardware.
+                true
+            }
+            val lowLatency = Build.VERSION.SDK_INT >= Build.VERSION_CODES.R &&
+                runCatching { caps.isFeatureSupported(CodecCapabilities.FEATURE_LowLatency) }
+                    .getOrDefault(false)
+            val vendor = VENDOR_PREFIXES.any { lower.startsWith(it) }
+
+            val score = (if (hardware) 100 else 0) +
+                (if (vendor) 40 else 0) +
+                (if (lowLatency) 20 else 0)
+            if (score > bestScore) {
+                bestScore = score
+                bestName = name
+                bestLowLatency = lowLatency
+            }
+        }
+        return bestName?.let { DecoderChoice(it, bestLowLatency) }
+    }
+}

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

@@ -0,0 +1,195 @@
+package io.unom.punktfunk.kit.library
+
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import org.json.JSONArray
+import org.json.JSONObject
+import java.io.ByteArrayInputStream
+import java.security.KeyFactory
+import java.security.KeyStore
+import java.security.MessageDigest
+import java.security.PrivateKey
+import java.security.cert.CertificateFactory
+import java.security.cert.X509Certificate
+import java.security.spec.PKCS8EncodedKeySpec
+import java.util.Base64
+import java.util.concurrent.TimeUnit
+import javax.net.ssl.HostnameVerifier
+import javax.net.ssl.HttpsURLConnection
+import javax.net.ssl.KeyManagerFactory
+import javax.net.ssl.SSLContext
+import javax.net.ssl.TrustManager
+import javax.net.ssl.TrustManagerFactory
+import javax.net.ssl.X509TrustManager
+
+// Android game-library client — the mirror of the Apple client's LibraryClient.swift. Fetches a
+// host's unified game library from its management REST API (`GET /api/v1/library`) over **mTLS**: the
+// paired client presents its persistent cert/key (the same identity the host paired over QUIC), and
+// the host's self-signed cert is pinned by SHA-256(DER). Read-only. Mirrors the GameEntry/Artwork
+// schema in crates/punktfunk-host/src/library.rs.
+
+/** The management API's default port — matches `mgmt::DEFAULT_PORT` on the host and the Apple client. */
+const val DEFAULT_MGMT_PORT = 47990
+
+/** Cover-art URLs. Steam art arrives as host-relative proxy paths, resolved to absolute by [LibraryClient]. */
+data class Artwork(val portrait: String?, val header: String?, val hero: String?) {
+    /** Poster preference for a 2:3 tile: portrait capsule → header → hero (near-universal fallbacks). */
+    val posterCandidates: List<String> get() = listOfNotNull(portrait, header, hero)
+}
+
+/** One title in the unified library. [id] is store-qualified (`steam:<appid>` / `custom:<id>`). */
+data class GameEntry(val id: String, val store: String, val title: String, val art: Artwork) {
+    val isCustom: Boolean get() = store == "custom"
+}
+
+/** Fetch outcome — three states so the UI can guide setup (the common case is "not paired yet"). */
+sealed class LibraryResult {
+    data class Ok(val games: List<GameEntry>) : LibraryResult()
+    data class Unauthorized(val message: String) : LibraryResult()
+    data class Error(val message: String) : LibraryResult()
+}
+
+object LibraryClient {
+    /**
+     * `GET https://<address>:<mgmtPort>/api/v1/library`, authenticated by mTLS. [fpHex] is the pinned
+     * host-cert SHA-256 (64 hex, from the paired [io.unom.punktfunk.kit.security.KnownHost]); a blank
+     * value means the host was never connected/paired, so there's nothing authorized to browse.
+     * BLOCKING — call from a background dispatcher.
+     */
+    fun fetch(
+        address: String,
+        mgmtPort: Int = DEFAULT_MGMT_PORT,
+        certPem: String,
+        keyPem: String,
+        fpHex: String,
+    ): LibraryResult {
+        if (fpHex.isBlank()) {
+            return LibraryResult.Unauthorized(
+                "Connect to this host once first — the library uses the identity created on pairing to authenticate.",
+            )
+        }
+        val client = try {
+            mtlsHttpClient(certPem, keyPem, address, fpHex)
+        } catch (e: Exception) {
+            return LibraryResult.Error("Couldn't set up the secure connection: ${e.message}")
+        }
+        val base = "https://$address:$mgmtPort"
+        val req = Request.Builder().url("$base/api/v1/library").build()
+        return try {
+            client.newCall(req).execute().use { resp ->
+                when (resp.code) {
+                    200 -> LibraryResult.Ok(parse(resp.body?.string().orEmpty(), base))
+                    401 -> LibraryResult.Unauthorized(
+                        "The host didn't recognize this device. Pair with the host first — it authorizes paired clients by their certificate.",
+                    )
+                    else -> LibraryResult.Error("The management API returned HTTP ${resp.code}.")
+                }
+            }
+        } catch (e: Exception) {
+            LibraryResult.Error(
+                "Couldn't reach the host's management API: ${e.message}. It binds the LAN by default, so check the host is updated and reachable.",
+            )
+        }
+    }
+
+    private fun parse(json: String, base: String): List<GameEntry> {
+        val arr = JSONArray(json)
+        val out = ArrayList<GameEntry>(arr.length())
+        for (i in 0 until arr.length()) {
+            val o = arr.getJSONObject(i)
+            val art = o.optJSONObject("art") ?: JSONObject()
+            out.add(
+                GameEntry(
+                    id = o.optString("id"),
+                    store = o.optString("store"),
+                    title = o.optString("title"),
+                    art = Artwork(
+                        portrait = resolveArt(str(art, "portrait"), base),
+                        header = resolveArt(str(art, "header"), base),
+                        hero = resolveArt(str(art, "hero"), base),
+                    ),
+                ),
+            )
+        }
+        return out
+    }
+
+    /** A present, non-null, non-blank JSON string field, else null. */
+    private fun str(o: JSONObject, key: String): String? =
+        if (o.has(key) && !o.isNull(key)) o.optString(key).ifBlank { null } else null
+
+    /** Host-relative art path (`/api/v1/library/art/...`) → absolute against the host; else unchanged. */
+    private fun resolveArt(s: String?, base: String): String? =
+        if (s != null && s.startsWith("/")) base + s else s
+}
+
+/**
+ * An OkHttpClient that presents the paired client cert and pins the host's self-signed cert by
+ * SHA-256(DER) — reused for BOTH the library fetch and the cover-art loads (so a paired client
+ * reaches the host's own art proxy). The pinning trust manager trusts the host by fingerprint and
+ * defers to normal public trust for any other origin (an external CDN URL); the hostname verifier
+ * accepts the pinned host (whose self-signed cert has no matching SAN) and defers otherwise.
+ */
+fun mtlsHttpClient(certPem: String, keyPem: String, host: String, fpHex: String): OkHttpClient {
+    val clientCert = CertificateFactory.getInstance("X.509")
+        .generateCertificate(ByteArrayInputStream(certPem.toByteArray())) as X509Certificate
+    val privateKey = parsePrivateKey(keyPem)
+
+    val keyStore = KeyStore.getInstance("PKCS12").apply {
+        load(null, null)
+        setKeyEntry("client", privateKey, CharArray(0), arrayOf(clientCert))
+    }
+    val kmf = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm())
+    kmf.init(keyStore, CharArray(0))
+
+    // System default trust manager, for non-host (external CDN) origins.
+    val sysTmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm())
+    sysTmf.init(null as KeyStore?)
+    val sysTm = sysTmf.trustManagers.filterIsInstance<X509TrustManager>().first()
+
+    val pinned = fpHex.lowercase()
+    val trustManager = object : X509TrustManager {
+        override fun checkClientTrusted(chain: Array<X509Certificate>, authType: String) {}
+        override fun checkServerTrusted(chain: Array<X509Certificate>, authType: String) {
+            if (sha256Hex(chain[0].encoded) == pinned) return // the pinned host
+            sysTm.checkServerTrusted(chain, authType) // external CDN — normal public trust
+        }
+        override fun getAcceptedIssuers(): Array<X509Certificate> = sysTm.acceptedIssuers
+    }
+
+    val ssl = SSLContext.getInstance("TLS")
+    ssl.init(kmf.keyManagers, arrayOf<TrustManager>(trustManager), null)
+
+    val defaultVerifier = HttpsURLConnection.getDefaultHostnameVerifier()
+    val verifier = HostnameVerifier { hostname, session ->
+        hostname == host || defaultVerifier.verify(hostname, session)
+    }
+
+    return OkHttpClient.Builder()
+        .sslSocketFactory(ssl.socketFactory, trustManager)
+        .hostnameVerifier(verifier)
+        .connectTimeout(8, TimeUnit.SECONDS)
+        .readTimeout(15, TimeUnit.SECONDS)
+        .build()
+}
+
+/** Parse a PKCS#8 PEM private key (rcgen emits `-----BEGIN PRIVATE KEY-----`), trying EC then RSA/Ed25519. */
+private fun parsePrivateKey(pem: String): PrivateKey {
+    val body = pem
+        .replace(Regex("-----BEGIN [A-Z ]*PRIVATE KEY-----"), "")
+        .replace(Regex("-----END [A-Z ]*PRIVATE KEY-----"), "")
+        .replace(Regex("\\s"), "")
+    val der = Base64.getDecoder().decode(body)
+    val spec = PKCS8EncodedKeySpec(der)
+    for (alg in listOf("EC", "RSA", "Ed25519")) {
+        try {
+            return KeyFactory.getInstance(alg).generatePrivate(spec)
+        } catch (_: Exception) {
+            // try the next algorithm
+        }
+    }
+    throw IllegalArgumentException("unsupported private-key format (not EC/RSA/Ed25519 PKCS#8)")
+}
+
+private fun sha256Hex(der: ByteArray): String =
+    MessageDigest.getInstance("SHA-256").digest(der).joinToString("") { "%02x".format(it) }

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

@@ -74,6 +74,16 @@ class KnownHostStore(context: Context) {
         save(h.copy(name = newName))
     }
 
+    /**
+     * Edit a saved host, RE-KEYING if the address or port changed (the pref key IS `address:port`, so
+     * a plain [save] would otherwise leave a stale record under the old key). The caller passes an
+     * [updated] copy that preserves `fpHex`/`paired` (and sets `mac` from the edit form).
+     */
+    fun update(oldAddress: String, oldPort: Int, updated: KnownHost) {
+        if (oldAddress != updated.address || oldPort != updated.port) remove(oldAddress, oldPort)
+        save(updated)
+    }
+
     /** All trusted hosts, name-sorted — backs the saved-hosts list. */
     fun all(): List<KnownHost> =
         prefs.all.values.mapNotNull { (it as? String)?.let(::parse) }.sortedBy { it.name.lowercase() }
@@ -89,4 +99,22 @@ class KnownHostStore(context: Context) {
             mac = j.optString("mac", "").split(",").map { it.trim() }.filter { it.isNotEmpty() },
         )
     }.getOrNull()
+
+    companion object {
+        /**
+         * Parse a free-typed Wake-on-LAN field into normalized `aa:bb:cc:dd:ee:ff` entries (comma /
+         * space / newline separated). Anything that isn't six colon-separated hex octets is dropped;
+         * an empty result clears the host's MAC. Mirrors the Apple client's `AddHostSheet.parseMacs`.
+         */
+        fun parseMacs(s: String): List<String> = s
+            .split(',', ';', ' ', '\n', '\t')
+            .map { it.trim().lowercase() }
+            .filter { m ->
+                // Exactly six octets, each two literal hex digits. (Not toIntOrNull(16) — that accepts
+                // a leading +/- sign, so "aa:bb:cc:dd:ee:-1" would wrongly pass.)
+                m.split(":").let { o ->
+                    o.size == 6 && o.all { it.length == 2 && it.all { c -> c in '0'..'9' || c in 'a'..'f' } }
+                }
+            }
+    }
 }

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

@@ -0,0 +1,33 @@
+package io.unom.punktfunk.kit.security
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+/** Unit tests for the pure MAC-parsing helper backing the host edit form. */
+class KnownHostStoreTest {
+    @Test
+    fun parsesAndNormalizesSingleMac() {
+        assertEquals(listOf("aa:bb:cc:dd:ee:ff"), KnownHostStore.parseMacs("AA:BB:CC:DD:EE:FF"))
+    }
+
+    @Test
+    fun parsesMultipleSeparators() {
+        val expected = listOf("aa:bb:cc:dd:ee:ff", "11:22:33:44:55:66")
+        assertEquals(expected, KnownHostStore.parseMacs("aa:bb:cc:dd:ee:ff, 11:22:33:44:55:66"))
+        assertEquals(expected, KnownHostStore.parseMacs("aa:bb:cc:dd:ee:ff 11:22:33:44:55:66"))
+        assertEquals(expected, KnownHostStore.parseMacs("aa:bb:cc:dd:ee:ff\n11:22:33:44:55:66"))
+    }
+
+    @Test
+    fun dropsMalformedEntries() {
+        // Not six octets / bad hex / wrong width are all dropped; an empty field clears the MAC.
+        assertEquals(emptyList<String>(), KnownHostStore.parseMacs(""))
+        assertEquals(emptyList<String>(), KnownHostStore.parseMacs("not-a-mac"))
+        assertEquals(emptyList<String>(), KnownHostStore.parseMacs("aa:bb:cc:dd:ee"))     // 5 octets
+        assertEquals(emptyList<String>(), KnownHostStore.parseMacs("gg:bb:cc:dd:ee:ff"))  // non-hex
+        assertEquals(emptyList<String>(), KnownHostStore.parseMacs("aaa:bb:cc:dd:ee:ff")) // wrong width
+        assertEquals(emptyList<String>(), KnownHostStore.parseMacs("aa:bb:cc:dd:ee:-1")) // signed octet
+        assertEquals(emptyList<String>(), KnownHostStore.parseMacs("+a:-b:+c:-d:+e:-f")) // signed octets
+        assertEquals(listOf("aa:bb:cc:dd:ee:ff"), KnownHostStore.parseMacs("junk, aa:bb:cc:dd:ee:ff"))
+    }
+}

clients/android/native/Cargo.toml

@@ -34,7 +34,11 @@ android_logger = "0.14"
 # NDK bindings. "media" = AMediaCodec/ANativeWindow (video); "audio" = AAudio (audio playback).
 # Pure-Rust FFI to libmediandk/libnativewindow/libaaudio — no C++/libc++_shared to bundle. Decode +
 # audio run entirely in Rust on native threads (the "no async on the hot path" invariant).
-ndk = { version = "0.9", features = ["media", "audio", "nativewindow", "api-level-31"] }
+# api-level-28 matches the app's minSdk floor (Android 9). AAudio (26), AMediaCodec (21) and
+# ANativeWindow_setBuffersDataSpace (28) are all ≤28; the one API-30 call we make
+# (ANativeWindow_setFrameRate) is dlsym-resolved at runtime (see decode::try_set_frame_rate), not
+# linked, so the .so still loads on API 28/29.
+ndk = { version = "0.9", features = ["media", "audio", "nativewindow", "api-level-28"] }
 # setpriority/gettid to raise the decode thread toward URGENT_DISPLAY (see decode::boost_thread_priority).
 libc = "0.2"
 # Opus decode for the host→client audio plane (0xC9: 48 kHz stereo, 5 ms frames). Same crate the

clients/android/native/src/adpf.rs

@@ -28,6 +28,7 @@ type CreateSessionFn = unsafe extern "C" fn(*mut c_void, *const i32, usize, i64)
 type ReportFn = unsafe extern "C" fn(*mut c_void, i64) -> c_int;
 type UpdateTargetFn = unsafe extern "C" fn(*mut c_void, i64) -> c_int;
 type CloseFn = unsafe extern "C" fn(*mut c_void);
+type SetPreferPowerEfficiencyFn = unsafe extern "C" fn(*mut c_void, bool) -> c_int;
 
 /// The entry points we use, resolved once from `libandroid.so`, plus the process-wide manager.
 struct Api {
@@ -35,6 +36,9 @@ struct Api {
     report: ReportFn,
     update_target: UpdateTargetFn,
     close: CloseFn,
+    /// `APerformanceHint_setPreferPowerEfficiency` — NDK **API 35**, so `Option`al even when the
+    /// rest of ADPF resolved (a 33/34 device has the session API but not this one).
+    set_prefer_power_efficiency: Option<SetPreferPowerEfficiencyFn>,
     manager: *mut c_void,
 }
 
@@ -70,11 +74,20 @@ fn resolve_api() -> Option<Api> {
         if manager.is_null() {
             return None;
         }
+        // Optional (API 35): resolve if present, else `None` — the session still works without it.
+        let set_prefer_power_efficiency =
+            libc::dlsym(lib, c"APerformanceHint_setPreferPowerEfficiency".as_ptr());
+        let set_prefer_power_efficiency = (!set_prefer_power_efficiency.is_null()).then(|| {
+            std::mem::transmute::<*mut c_void, SetPreferPowerEfficiencyFn>(
+                set_prefer_power_efficiency,
+            )
+        });
         Some(Api {
             create_session: std::mem::transmute::<*mut c_void, CreateSessionFn>(create_session),
             report: std::mem::transmute::<*mut c_void, ReportFn>(report),
             update_target: std::mem::transmute::<*mut c_void, UpdateTargetFn>(update_target),
             close: std::mem::transmute::<*mut c_void, CloseFn>(close),
+            set_prefer_power_efficiency,
             manager,
         })
     }
@@ -103,6 +116,13 @@ impl HintSession {
         if session.is_null() {
             return None;
         }
+        // Tell the governor NOT to bias this session toward power efficiency (API 35+): our loop is
+        // latency-critical, so we want it kept on fast cores at high clocks over battery savings.
+        // Best-effort; absent below API 35.
+        if let Some(f) = api.set_prefer_power_efficiency {
+            // SAFETY: `session` is the live session just created; the fn takes it + a bool.
+            unsafe { f(session, false) };
+        }
         Some(Self { api, session })
     }
 

clients/android/native/src/audio.rs

@@ -18,8 +18,8 @@
 //! grown on XRuns (Google's anti-glitch technique).
 
 use ndk::audio::{
-    AudioCallbackResult, AudioDirection, AudioFormat, AudioPerformanceMode, AudioSharingMode,
-    AudioStream, AudioStreamBuilder,
+    AudioCallbackResult, AudioContentType, AudioDirection, AudioFormat, AudioPerformanceMode,
+    AudioSharingMode, AudioStream, AudioStreamBuilder, AudioUsage,
 };
 use punktfunk_core::client::NativeClient;
 use punktfunk_core::error::PunktfunkError;
@@ -235,6 +235,11 @@ impl AudioPlayback {
                 // captures + Opus-encodes in exactly this order.
                 .channel_count(channels as i32)
                 .format(AudioFormat::PCM_Float)
+                // Tag the stream as game audio (usage=Game / content=Movie): the audio HAL applies
+                // its low-latency game-audio routing/policy and it's grouped correctly with the
+                // game-mode profile. Advisory — ignored where the device has no such policy.
+                .usage(AudioUsage::Game)
+                .content_type(AudioContentType::Movie)
                 .performance_mode(AudioPerformanceMode::LowLatency)
                 .sharing_mode(sharing)
                 .data_callback(Box::new(callback))

clients/android/native/src/decode.rs

@@ -8,19 +8,25 @@
 
 use ndk::data_space::DataSpace;
 use ndk::media::media_codec::{
-    DequeuedInputBufferResult, DequeuedOutputBufferInfoResult, MediaCodec, MediaCodecDirection,
-    OutputBuffer,
+    AsyncNotifyCallback, DequeuedInputBufferResult, DequeuedOutputBufferInfoResult, MediaCodec,
+    MediaCodecDirection, OutputBuffer,
 };
 use ndk::media::media_format::MediaFormat;
-use ndk::native_window::{FrameRateCompatibility, NativeWindow};
+use ndk::native_window::NativeWindow;
 use punktfunk_core::client::NativeClient;
 use punktfunk_core::error::PunktfunkError;
 use punktfunk_core::session::Frame;
 use std::collections::VecDeque;
+use std::ffi::c_void;
 use std::sync::atomic::{AtomicBool, Ordering};
-use std::sync::Arc;
+use std::sync::{mpsc, Arc, Mutex};
 use std::time::{Duration, Instant};
 
+/// 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;
@@ -30,29 +36,80 @@ const IN_FLIGHT_CAP: usize = 64;
 /// this deep is a lost datagram (or an old host that never sends any) and gets evicted.
 const PENDING_SPLIT_CAP: usize = 256;
 
-/// The decode loop. Runs on the `pf-decode` thread until `shutdown` is set or the session closes.
+/// Whether to run the event-driven async decode loop (default) or the synchronous poll loop kept as
+/// a bring-up fallback. 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.
+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 (default on ⇒ full aggressive profile; off ⇒
+    /// conservative, an escape hatch for a device that throttles under the clocks).
+    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 USE_ASYNC_DECODE {
+        run_async(client, window, shutdown, stats, opts);
+    } else {
+        run_sync(client, window, shutdown, stats, opts);
+    }
+}
+
+/// The synchronous poll loop — the original decode path, kept as a bring-up fallback behind
+/// [`USE_ASYNC_DECODE`]. Feeds and drains on this one thread; the only blocking wait is a short
+/// output dequeue while input is backed up.
+#[allow(dead_code)]
+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`): HEVC or H.264. AMediaCodec
-    // needs no out-of-band extradata — the in-band VPS/SPS/PPS on every IDR configure it either way.
-    let mime = match client.codec {
-        punktfunk_core::quic::CODEC_H264 => "video/avc",
-        _ => "video/hevc",
-    };
-    let codec = match MediaCodec::from_decoder_type(mime) {
+    // 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;
         }
     };
-    log::info!("decode: codec mime = {mime}");
+    // 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);
@@ -63,23 +120,9 @@ pub fn run(
         "max-input-size",
         (mode.width * mode.height).max(2_000_000) as i32,
     );
-    // Ask for the low-latency decode path where the decoder supports it (no reordering buffer).
-    format.set_i32("low-latency", 1);
-    // Best-effort vendor twin of the standard key: older Qualcomm decoders only honor their own
-    // extension. Unknown keys are ignored by other vendors' codecs, so this is safe to set blind.
-    format.set_i32("vendor.qti-ext-dec-low-latency.enable", 1);
-    // Advisory low-latency hints (KEY_PRIORITY / KEY_OPERATING_RATE), ignored where unsupported:
-    // realtime priority + the target frame rate, so vendor decoders (e.g. Qualcomm) run at full
-    // clocks instead of a power-saving cadence that adds dequeue latency.
-    format.set_i32("priority", 0); // 0 = realtime
-                                   // Operating rate = the codec's clock hint. Setting it to the display rate merely asks the
-                                   // decoder to *sustain* that cadence — a Qualcomm decoder can meet 60/120 fps at a power-saving
-                                   // clock that adds a millisecond-plus of decode latency per frame. Setting it to the AOSP
-                                   // "unbounded" sentinel (Short.MAX) instead asks the decoder to run each frame at max clocks and
-                                   // finish ASAP, minimising per-frame decode latency — the right trade for a real-time stream
-                                   // (costs power/heat; the dial to lower if a device thermally throttles over a long session).
-                                   // Ignored where unsupported.
-    format.set_i32("operating-rate", i16::MAX as i32); // 32767 = "as fast as possible"
+    // 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.
@@ -113,11 +156,13 @@ pub fn run(
         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). minSdk 31 ≥ API 30, so the underlying
-    // ANativeWindow_setFrameRate is always present; non-fatal if the platform declines.
-    if let Err(e) = window.set_frame_rate(mode.refresh_hz as f32, FrameRateCompatibility::Default) {
-        log::warn!(
-            "decode: set_frame_rate({} Hz) failed (non-fatal): {e}",
+    // 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).
+    if mode.refresh_hz > 0 && !try_set_frame_rate(&window, mode.refresh_hz as f32, is_tv) {
+        log::debug!(
+            "decode: set_frame_rate({} Hz) unavailable/declined (non-fatal)",
             mode.refresh_hz
         );
     }
@@ -274,6 +319,7 @@ pub fn run(
                 // or where the platform declines → `None`, and the loop runs unhinted).
                 hint_tried = true;
                 let tids = client.hot_thread_ids();
+                boost_hot_threads(&tids);
                 hint = crate::adpf::HintSession::create(frame_period_ns, &tids);
                 log::info!(
                     "decode: ADPF hint session {} — {} hot thread(s), target {frame_period_ns} ns",
@@ -323,6 +369,609 @@ fn now_realtime_ns() -> i128 {
         .unwrap_or(0)
 }
 
+/// 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",
+    }
+}
+
+/// 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).
+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`. The standard AOSP `low-latency` key is
+/// always set (API 30+, harmless/ignored elsewhere). When `aggressive` (the "Low-latency mode"
+/// master toggle) we additionally set 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 clock
+/// hint. Off ⇒ the standard key only, a gentler profile for a device that throttles under max clocks.
+///
+/// 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`.
+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 {
+        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")
+}
+
+/// 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.
+struct OutputReady {
+    index: usize,
+    pts_us: u64,
+}
+
+/// 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.
+    Au(Frame),
+    /// An input buffer slot freed (index) — we can queue an AU into it.
+    InputAvailable(usize),
+    /// A decoded frame is ready (buffer index + echoed pts).
+    OutputAvailable { index: usize, pts_us: u64 },
+    /// 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.
+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,
+                });
+            })),
+            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();
+                log::warn!("decode: codec error {e:?} (fatal={fatal})");
+                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
+    );
+    if mode.refresh_hz > 0 && !try_set_frame_rate(&window, mode.refresh_hz as f32, is_tv) {
+        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_ns;
+    let in_flight = Arc::new(Mutex::new(VecDeque::<(u64, i128)>::new()));
+
+    // 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 shutdown = shutdown.clone();
+        let ev_tx = ev_tx.clone();
+        std::thread::Builder::new()
+            .name("pf-decode-feed".into())
+            .spawn(move || {
+                feeder_loop(
+                    client,
+                    stats,
+                    in_flight,
+                    clock_offset as i128,
+                    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;
+    let mut last_dropped = client.frames_dropped();
+    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 au_dropped = false;
+        if let Some(ev) = ev0 {
+            au_dropped |= dispatch_event(
+                ev,
+                &mut pending_aus,
+                &mut free_inputs,
+                &mut ready,
+                &mut fmt_dirty,
+                &mut fatal,
+            );
+        }
+        // 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() {
+            au_dropped |= dispatch_event(
+                ev,
+                &mut pending_aus,
+                &mut free_inputs,
+                &mut ready,
+                &mut fmt_dirty,
+                &mut fatal,
+            );
+        }
+        if fmt_dirty {
+            apply_hdr_dataspace(&codec, &window, &mut applied_ds);
+        }
+        feed_ready(&codec, &mut pending_aus, &mut free_inputs, &mut fed);
+        let had_output = !ready.is_empty();
+        present_ready(
+            &codec,
+            &mut ready,
+            &stats,
+            &in_flight,
+            clock_offset,
+            &mut rendered,
+            &mut discarded,
+        );
+
+        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();
+                boost_hot_threads(&tids);
+                hint = crate::adpf::HintSession::create(frame_period_ns, &tids);
+                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: request an IDR when the reassembler's unrecoverable-drop count climbs (or we
+        // dropped a parked AU on overflow), throttled so a multi-frame recovery gap doesn't flood the
+        // control stream.
+        let dropped = client.frames_dropped();
+        if dropped > last_dropped || au_dropped {
+            last_dropped = dropped;
+            let now = Instant::now();
+            if last_kf_req.is_none_or(|t| now.duration_since(t) >= Duration::from_millis(100)) {
+                last_kf_req = Some(now);
+                let _ = client.request_keyframe();
+            }
+        }
+    }
+
+    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();
+    }
+    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>,
+    in_flight: Arc<Mutex<VecDeque<(u64, i128)>>>,
+    clock_offset: i128,
+    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) => {
+                if stats.enabled() {
+                    let received_ns = now_realtime_ns();
+                    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);
+                    {
+                        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 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)).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).
+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,
+) -> bool {
+    match ev {
+        DecodeEvent::Au(f) => {
+            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 } => ready.push(OutputReady { index, pts_us }),
+        DecodeEvent::FormatChanged => *fmt_dirty = true,
+        DecodeEvent::Error { fatal: f } => {
+            if f {
+                *fatal = true;
+            }
+        }
+    }
+    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; a too-large AU is truncated (logged) rather than dropped.
+fn feed_ready(
+    codec: &MediaCodec,
+    pending_aus: &mut VecDeque<Frame>,
+    free_inputs: &mut VecDeque<usize>,
+    fed: &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;
+        let n = au.len().min(dst.len());
+        if n < au.len() {
+            log::warn!(
+                "decode: AU {} > input buffer {}, truncated",
+                au.len(),
+                dst.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. `ready` is drained.
+fn present_ready(
+    codec: &MediaCodec,
+    ready: &mut Vec<OutputReady>,
+    stats: &crate::stats::VideoStats,
+    in_flight: &Mutex<VecDeque<(u64, i128)>>,
+    clock_offset: i64,
+    rendered: &mut u64,
+    discarded: &mut u64,
+) {
+    if ready.is_empty() {
+        return;
+    }
+    if stats.enabled() {
+        let mut g = in_flight
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        for o in ready.iter() {
+            note_decoded_pts(stats, &mut g, clock_offset, o.pts_us);
+        }
+    }
+    let last = ready.len() - 1;
+    for (i, o) in ready.drain(..).enumerate() {
+        let render = i == last;
+        match codec.release_output_buffer_by_index(o.index, render) {
+            Ok(()) if render => *rendered += 1,
+            Ok(()) => *discarded += 1,
+            Err(e) => {
+                log::warn!(
+                    "decode: release_output_buffer_by_index({}, {render}): {e}",
+                    o.index
+                )
+            }
+        }
+    }
+}
+
+/// 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).
+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}")
+                }
+            }
+        }
+    }
+}
+
+/// 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.
+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).
@@ -340,6 +989,57 @@ fn boost_thread_priority() {
     }
 }
 
+/// 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.
+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
+    }
+}
+
 /// 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
@@ -470,7 +1170,22 @@ fn note_decoded(
     clock_offset: i64,
     buf: &OutputBuffer<'_>,
 ) {
-    let pts_us = buf.info().presentation_time_us().max(0) as u64;
+    note_decoded_pts(
+        stats,
+        in_flight,
+        clock_offset,
+        buf.info().presentation_time_us().max(0) as u64,
+    );
+}
+
+/// The [`note_decoded`] body keyed by the echoed `presentationTimeUs` directly — the async loop has
+/// the pts (from the output callback's `BufferInfo`) but no borrowed `OutputBuffer`, so it calls this.
+fn note_decoded_pts(
+    stats: &crate::stats::VideoStats,
+    in_flight: &mut VecDeque<(u64, i128)>,
+    clock_offset: i64,
+    pts_us: u64,
+) {
     let decoded_ns = now_realtime_ns();
     // Pair the echoed pts back to its receipt stamp, evicting stale (older) entries as we go.
     let mut received_ns = None;

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

@@ -2,20 +2,31 @@
 //! ~1 Hz decode-stats drain for the HUD.
 
 use jni::objects::JObject;
-use jni::sys::{jboolean, jdoubleArray, jlong, jsize};
+// Used only by the android-gated `nativeStartVideo`; on the host build that fn is cfg'd out.
+#[cfg(target_os = "android")]
+use jni::objects::JString;
+use jni::sys::{jboolean, jdoubleArray, jlong, jsize, jstring};
 use jni::JNIEnv;
 
 use super::{jni_guard, SessionHandle};
 
-/// `NativeBridge.nativeStartVideo(handle, surface)` — wrap the SurfaceView's `Surface` as an
-/// `ANativeWindow` and start the HEVC decode thread rendering onto it. No-op if already started.
+/// `NativeBridge.nativeStartVideo(handle, surface, decoderName, lowLatencyMode, lowLatencyFeature)`
+/// — wrap the SurfaceView's `Surface` as an `ANativeWindow` and start the decode thread rendering
+/// onto it. `decoderName` is the codec Kotlin ranked from `MediaCodecList` (`""` = let the platform
+/// resolve the default for the MIME); `lowLatencyMode` is the user's master toggle;
+/// `lowLatencyFeature` is whether that decoder advertised `FEATURE_LowLatency` (HUD label only).
+/// No-op if already started.
 #[cfg(target_os = "android")]
 #[no_mangle]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
-    env: JNIEnv,
+    mut env: JNIEnv,
     _this: JObject,
     handle: jlong,
     surface: JObject,
+    decoder_name: JString,
+    low_latency_mode: jboolean,
+    ll_feature: jboolean,
+    is_tv: jboolean,
 ) {
     use super::VideoThread;
     use std::sync::atomic::AtomicBool;
@@ -24,6 +35,12 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
     if handle == 0 {
         return;
     }
+    // The decoder name Kotlin picked (empty string / read failure ⇒ None ⇒ default resolver).
+    let decoder = env
+        .get_string(&decoder_name)
+        .ok()
+        .map(String::from)
+        .filter(|s| !s.is_empty());
     // SAFETY: live handle per the nativeConnect/nativeClose contract.
     let h = unsafe { &*(handle as *const SessionHandle) };
     let mut guard = h.video.lock().unwrap();
@@ -48,13 +65,67 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
     let client = h.client.clone();
     let sd = shutdown.clone();
     let st = h.stats.clone(); // session-lifetime stats (gate survives surface recreate)
+    let opts = crate::decode::DecodeOptions {
+        decoder_name: decoder,
+        ll_feature: ll_feature != 0,
+        low_latency_mode: low_latency_mode != 0,
+        is_tv: is_tv != 0,
+    };
     let join = std::thread::Builder::new()
         .name("pf-decode".into())
-        .spawn(move || crate::decode::run(client, window, sd, st))
+        .spawn(move || crate::decode::run(client, window, sd, st, opts))
         .ok();
     *guard = Some(VideoThread { shutdown, join });
 }
 
+/// `NativeBridge.nativeVideoMime(handle): String` — the MediaCodec MIME for the codec the host
+/// resolved (`"video/hevc"` / `"video/avc"` / `"video/av01"`), so Kotlin can rank `MediaCodecList`
+/// decoders for it before calling [`Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo`].
+/// Empty string on a `0` handle. Cheap; safe on the UI thread.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoMime<'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_mime(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
+/// android-gated — pure `jni` + a lock, so it links on the host build too (Kotlin only calls it on
+/// device).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoDecoderLabel<'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(h.stats.decoder_label()) {
+            Ok(s) => s.into_raw(),
+            Err(_) => std::ptr::null_mut(),
+        }
+    })
+}
+
 /// `NativeBridge.nativeStopVideo(handle)` — stop + join the decode thread (without closing the
 /// session). No-op on `0`.
 #[no_mangle]

clients/android/native/src/stats.rs

@@ -22,9 +22,21 @@ pub struct VideoStats {
     /// they (and the caller's latency computation — see `enabled`) early-out on this flag alone.
     /// Off until Kotlin shows the HUD.
     enabled: AtomicBool,
+    /// The resolved decoder identity for the HUD: the codec's actual `AMediaCodec` name (e.g.
+    /// `c2.qti.avc.decoder`) and whether it advertised `FEATURE_LowLatency`. Set once when the
+    /// decode thread creates the codec (`set_decoder`), read one-shot by `nativeVideoDecoderLabel`.
+    /// Separate from `inner` (never touched per-frame) so naming it costs nothing on the hot path.
+    decoder: Mutex<Option<DecoderInfo>>,
     inner: Mutex<Inner>,
 }
 
+/// The chosen decoder's identity, surfaced on the stats HUD so before/after latency comparisons
+/// name the codec that produced them.
+struct DecoderInfo {
+    name: String,
+    low_latency: bool,
+}
+
 struct Inner {
     window_start: Instant,
     frames: u64,
@@ -79,6 +91,7 @@ impl VideoStats {
     pub fn new() -> VideoStats {
         VideoStats {
             enabled: AtomicBool::new(false),
+            decoder: Mutex::new(None),
             inner: Mutex::new(Inner {
                 window_start: Instant::now(),
                 frames: 0,
@@ -121,6 +134,36 @@ impl VideoStats {
         }
     }
 
+    /// Record the resolved decoder identity for the HUD — the codec's real `AMediaCodec` name and
+    /// whether it reported `FEATURE_LowLatency`. Called once from the decode thread right after the
+    /// codec is created (before `configure`), overwriting any prior value on a surface recreate.
+    // Set only by the android-only decode thread; unreferenced on the host build — expected.
+    #[cfg_attr(not(target_os = "android"), allow(dead_code))]
+    pub fn set_decoder(&self, name: &str, low_latency: bool) {
+        let mut g = self
+            .decoder
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        *g = Some(DecoderInfo {
+            name: name.to_owned(),
+            low_latency,
+        });
+    }
+
+    /// The decoder label for the HUD, e.g. `c2.qti.avc.decoder · low-latency`, or `""` before the
+    /// decode thread has resolved one. Cheap (a lock + a string build); safe on the UI thread.
+    pub fn decoder_label(&self) -> String {
+        let g = self
+            .decoder
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        match &*g {
+            Some(d) if d.low_latency => format!("{} · low-latency", d.name),
+            Some(d) => d.name.clone(),
+            None => String::new(),
+        }
+    }
+
     /// Record one received access unit: its wire size and (if in range) its capture→received
     /// `host+network` stage sample. Receipt is the fps/goodput counting point per the spec.
     // Driven only by the android-only decode thread; unreferenced on the host build — expected.

clients/apple/Config/Punktfunk-macOS.entitlements

@@ -48,21 +48,21 @@
 	<key>com.apple.security.device.usb</key>
 	<true/>
 
-	<!-- Controller rumble via CoreHaptics: GCDeviceHaptics.createEngine → CHHapticEngine
-	     (GamepadFeedback's RumbleRenderer), and AVAudioEngine playback, reach the system
-	     audio-analytics daemon `com.apple.audioanalyticsd` over Mach. The sandbox denies that
-	     global-name lookup unless it's whitelisted here, and the framework's own precondition
-	     turns the denial into a HARD CRASH ("Process is sandboxed but
-	     com.apple.security.exception.mach-lookup.global-name doesn't contain
-	     com.apple.audioanalyticsd") the moment a controller's haptics engine starts. This
-	     temporary exception is the documented, App-Store-acceptable way to permit exactly that
-	     lookup — and ONLY that service (the key takes exact names, no wildcards). App Store:
-	     declare it in App Store Connect → App Sandbox Entitlement Usage Information ("CoreHaptics
-	     gamepad rumble contacts the system audio-analytics daemon"). -->
-	<key>com.apple.security.temporary-exception.mach-lookup.global-name</key>
-	<array>
-		<string>com.apple.audioanalyticsd</string>
-	</array>
+	<!-- NO mach-lookup temporary exception here — and none is needed. Build 0.4.2 (3384) shipped a
+	     `com.apple.security.temporary-exception.mach-lookup.global-name` = com.apple.audioanalyticsd
+	     exception on the THEORY that CoreHaptics controller rumble (CHHapticEngine — the session
+	     RumbleRenderer + MenuHaptics) hard-crashes under the App Sandbox without it, because the
+	     framework reaches the audio-analytics daemon over Mach and the sandbox denies that lookup.
+	     App Review REJECTED the exception under guideline 2.4.5(i) (review 2026-07-04). We then
+	     tested the premise directly on macOS: a CHHapticEngine start + full-intensity rumble on a
+	     real Xbox pad, in a genuinely ENFORCED sandbox (NSHomeDirectory redirected into the app
+	     container) with NO exception on the codesigned binary — and it ran WITHOUT crashing, rumble
+	     and all, even with a live AVAudioEngine stream running concurrently. CoreHaptics simply
+	     tolerates the denied audioanalyticsd lookup (it's telemetry, not a hard precondition). So
+	     controller rumble works fully sandboxed with none of these exceptions. Do NOT re-add one —
+	     it will be rejected again AND it buys nothing. (DualSense rumble separately goes over raw
+	     HID via device.usb/device.bluetooth — CoreHaptics genuinely doesn't drive Sony motors on
+	     macOS — but that path needs no exception either; see DualSenseHID.) -->
 
 	<!-- Keychain Sharing (unchanged from the shared file): a team-scoped access group so the
 	     punktfunk/1 client identity in the data-protection keychain is gated by the app's

clients/apple/Sources/PunktfunkClient/ContentView.swift

@@ -52,6 +52,9 @@ struct ContentView: View {
     @State private var awaitingApproval: ApprovalRequest?
     @State private var speedTestTarget: StoredHost?
     @State private var libraryTarget: StoredHost?
+    /// Wakes a sleeping host and waits for it to come back online before connecting (drives the
+    /// "Waking…" overlay). macOS-only in practice — WoL is gated off on iOS/tvOS.
+    @StateObject private var waker = HostWaker()
     #if !os(macOS)
     @State private var showSettings = false
     #endif
@@ -212,12 +215,18 @@ struct ContentView: View {
     }
 
     private var home: some View {
+        // The "Waking…" overlay rides over BOTH home UIs (and the pre-connect window is still
+        // `home`, so it covers the whole wake→online→connect sequence).
+        homeBase.overlay { WakeOverlay(waker: waker) }
+    }
+
+    @ViewBuilder private var homeBase: some View {
         #if os(macOS)
         Group {
             if gamepadUIActive {
                 GamepadHomeView(
                     store: store, model: model, discovery: discovery,
-                    libraryTarget: $libraryTarget,
+                    libraryTarget: $libraryTarget, waker: waker,
                     connect: { connect($0) }, connectDiscovered: connectDiscovered)
             } else {
                 HomeView(
@@ -225,7 +234,7 @@ struct ContentView: View {
                     showAddHost: $showAddHost, pairingTarget: $pairingTarget,
                     speedTestTarget: $speedTestTarget, libraryTarget: $libraryTarget,
                     connect: { connect($0) }, connectDiscovered: connectDiscovered,
-                    onPaired: handlePaired, onLaunchTitle: launchTitle)
+                    onPaired: handlePaired, onLaunchTitle: launchTitle, wake: { wakeOnly($0) })
             }
         }
         #elseif os(iOS)
@@ -233,7 +242,7 @@ struct ContentView: View {
             if gamepadUIActive {
                 GamepadHomeView(
                     store: store, model: model, discovery: discovery,
-                    libraryTarget: $libraryTarget,
+                    libraryTarget: $libraryTarget, waker: waker,
                     connect: { connect($0) }, connectDiscovered: connectDiscovered)
             } else {
                 HomeView(
@@ -242,7 +251,7 @@ struct ContentView: View {
                     speedTestTarget: $speedTestTarget, libraryTarget: $libraryTarget,
                     showSettings: $showSettings,
                     connect: { connect($0) }, connectDiscovered: connectDiscovered,
-                    onPaired: handlePaired, onLaunchTitle: launchTitle)
+                    onPaired: handlePaired, onLaunchTitle: launchTitle, wake: { wakeOnly($0) })
             }
         }
         #else
@@ -252,7 +261,7 @@ struct ContentView: View {
             speedTestTarget: $speedTestTarget, libraryTarget: $libraryTarget,
             showSettings: $showSettings,
             connect: { connect($0) }, connectDiscovered: connectDiscovered,
-            onPaired: handlePaired, onLaunchTitle: launchTitle)
+            onPaired: handlePaired, onLaunchTitle: launchTitle, wake: { wakeOnly($0) })
         #endif
     }
 
@@ -406,9 +415,37 @@ struct ContentView: View {
     /// delegated-approval connect (host parks it until the operator approves).
     private func startSession(
         _ host: StoredHost, launchID: String? = nil,
-        allowTofu: Bool, requestAccess: Bool = false
+        allowTofu: Bool, requestAccess: Bool = false, approvalReq: ApprovalRequest? = nil
+    ) {
+        let go = {
+            startSessionDirect(
+                host, launchID: launchID, allowTofu: allowTofu,
+                requestAccess: requestAccess, approvalReq: approvalReq)
+        }
+        // Asleep (not advertising) and we can wake it? Fire the magic packet and WAIT for it to come
+        // back online — a cold box takes far longer to boot than a connect will sit — showing the
+        // "Waking…" overlay meanwhile. Then connect. Otherwise dial straight away.
+        if PunktfunkConnection.wakeOnLANAvailable, !host.wakeMacs.isEmpty, !discovery.advertises(host) {
+            discovery.start() // so we can observe it reappear
+            waker.start(
+                host: host, connectsAfter: true, macs: host.wakeMacs, lastIP: host.address,
+                isOnline: { discovery.advertises(host) }, onOnline: go)
+        } else {
+            go()
+        }
+    }
+
+    /// The actual dial — reached directly when the host is awake, or from the waker once a woken
+    /// 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).
+    private func startSessionDirect(
+        _ host: StoredHost, launchID: String? = nil,
+        allowTofu: Bool, requestAccess: Bool = false, approvalReq: ApprovalRequest? = nil
     ) {
         prepareWake(for: host)
+        // The delegated-approval wait prompt only makes sense once we're actually dialing — set it
+        // here (after any wake), not before, so it never stacks under the "Waking…" overlay.
+        if let approvalReq { awaitingApproval = approvalReq }
         model.connect(
             to: host,
             width: UInt32(clamping: width), height: UInt32(clamping: height),
@@ -452,12 +489,24 @@ struct ContentView: View {
     /// as paired (see the `.streaming` branch of `onChange`).
     private func requestAccess(_ req: ApprovalRequest) {
         guard !model.isBusy else { return }
-        awaitingApproval = req
         // Pin the advertised certificate for a discovered host (impostor defence during the long
         // wait); a manually-typed host has no advertised fingerprint, so trust-on-first-use.
         var host = req.host
         host.pinnedSHA256 = req.advertisedFingerprint
-        startSession(host, allowTofu: false, requestAccess: true)
+        // `awaitingApproval` is set inside startSessionDirect (after any wake), so it never stacks
+        // under the "Waking…" overlay.
+        startSession(host, allowTofu: false, requestAccess: true, approvalReq: req)
+    }
+
+    /// Explicit wake-only (the touch card's "Wake Host" menu item / a future gamepad action): fire
+    /// the packet and wait for the host to come online, but don't connect — the user then sees it
+    /// go online and can connect.
+    private func wakeOnly(_ host: StoredHost) {
+        guard PunktfunkConnection.wakeOnLANAvailable, !host.wakeMacs.isEmpty else { return }
+        discovery.start()
+        waker.start(
+            host: host, connectsAfter: false, macs: host.wakeMacs, lastIP: host.address,
+            isOnline: { discovery.advertises(host) }, onOnline: {})
     }
 
     /// Picked a title in the (experimental) library: dismiss the browser and start a session that

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

@@ -1,67 +1,87 @@
-// "+" sheet: name (optional) + address + port → a card in the hosts grid. The first
-// actual connection runs the trust-on-first-use fingerprint prompt.
+// Add / edit a host: name (optional) + address + port + Wake-on-LAN MAC → a card in the grid.
+// The MAC prefills from what we already know — the host's stored MAC, or the live mDNS advert's if
+// it hasn't been learned yet — so it's usually already correct; type/paste it for a host we've
+// never seen advertise. The first actual connection still runs the trust-on-first-use prompt.
 
+import PunktfunkKit
 import SwiftUI
 
 struct AddHostSheet: View {
     @Environment(\.dismiss) private var dismiss
-    @State private var name = ""
-    @State private var address = ""
-    @State private var port = 9777
+
+    /// nil = add a new host; non-nil = edit this one (fields prefilled, identity/pin preserved).
+    let existing: StoredHost?
+    /// MAC(s) to offer when the host has none stored yet — the live advert's, so the field is
+    /// prefilled the moment the host is on the network, even before a connect has learned it.
+    let suggestedMacs: [String]
+    let onSave: (StoredHost) -> Void
+
+    @State private var name: String
+    @State private var address: String
+    @State private var port: Int
+    @State private var mac: String
     #if os(tvOS)
     private enum EditField: String, Identifiable {
-        case name, address, port
+        case name, address, port, mac
         var id: String { rawValue }
     }
-    @State private var editing: EditField?
+    @State private var editingField: EditField?
     #endif
 
-    let onAdd: (StoredHost) -> Void
+    private var isEditing: Bool { existing != nil }
+    private var actionTitle: String { isEditing ? "Save" : "Add Host" }
+    private var canSave: Bool { !address.trimmingCharacters(in: .whitespaces).isEmpty }
+
+    init(existing: StoredHost? = nil, suggestedMacs: [String] = [], onSave: @escaping (StoredHost) -> Void) {
+        self.existing = existing
+        self.suggestedMacs = suggestedMacs
+        self.onSave = onSave
+        _name = State(initialValue: existing?.name ?? "")
+        _address = State(initialValue: existing?.address ?? "")
+        _port = State(initialValue: Int(existing?.port ?? 9777))
+        let stored = existing?.macAddresses ?? []
+        _mac = State(initialValue: (stored.isEmpty ? suggestedMacs : stored).joined(separator: ", "))
+    }
 
     var body: some View {
         #if os(tvOS)
         // No inline text editing on tvOS — Settings-style value rows; pressing one
         // raises the SYSTEM fullscreen keyboard (TVTextEntry).
         VStack(spacing: 24) {
-            TVFieldRow(
-                label: "Name", value: name, placeholder: "Optional"
-            ) { editing = .name }
-            TVFieldRow(
-                label: "Address", value: address, placeholder: "IP or hostname"
-            ) { editing = .address }
-            TVFieldRow(
-                label: "Port", value: String(port), placeholder: ""
-            ) { editing = .port }
+            TVFieldRow(label: "Name", value: name, placeholder: "Optional") { editingField = .name }
+            TVFieldRow(label: "Address", value: address, placeholder: "IP or hostname") { editingField = .address }
+            TVFieldRow(label: "Port", value: String(port), placeholder: "") { editingField = .port }
+            TVFieldRow(label: "MAC", value: mac, placeholder: "Wake-on-LAN — auto-filled when known") { editingField = .mac }
             HStack(spacing: 32) {
                 Button("Cancel", role: .cancel) { dismiss() }
-                Button("Add Host") { add() }
-                    .disabled(address.trimmingCharacters(in: .whitespaces).isEmpty)
+                Button(actionTitle) { save() }.disabled(!canSave)
             }
             .padding(.top, 12)
         }
         .frame(maxWidth: 1000)
         .padding(60)
-        .navigationTitle("Add Host")
-        .fullScreenCover(item: $editing) { field in
+        .navigationTitle(isEditing ? "Edit Host" : "Add Host")
+        .fullScreenCover(item: $editingField) { field in
             switch field {
             case .name:
                 TVTextEntry(title: "Name (optional, e.g. Living Room)", text: name) {
                     name = $0
-                    editing = nil
+                    editingField = nil
                 }
             case .address:
                 TVTextEntry(title: "IP or hostname", text: address) {
                     address = $0.trimmingCharacters(in: .whitespaces)
-                    editing = nil
+                    editingField = nil
                 }
             case .port:
-                TVTextEntry(
-                    title: "Port", text: String(port), keyboardType: .numberPad
-                ) {
-                    if let value = Int($0), (1...65535).contains(value) {
-                        port = value
-                    }
-                    editing = nil
+                TVTextEntry(title: "Port", text: String(port), keyboardType: .numberPad) {
+                    if let value = Int($0), (1...65535).contains(value) { port = value }
+                    editingField = nil
+                }
+            case .mac:
+                TVTextEntry(title: "MAC address(es), comma-separated — aa:bb:cc:dd:ee:ff", text: mac) {
+                    mac = $0.trimmingCharacters(in: .whitespaces)
+                    editingField = nil
                 }
             }
         }
@@ -71,77 +91,77 @@ struct AddHostSheet: View {
                 TextField("Name", text: $name, prompt: Text("Optional — e.g. Living Room"))
                 TextField("Address", text: $address, prompt: Text("IP or hostname"))
                 TextField("Port", value: $port, format: .number.grouping(.never))
-                    #if os(tvOS)
-                    // tvOS floats the label above a non-empty field INSIDE the pill,
-                    // shoving the value off-center — the field is always prefilled
-                    // here, so drop the label there.
-                    .labelsHidden()
+                TextField("MAC", text: $mac, prompt: Text("Wake-on-LAN — auto-filled when known"))
+                    .autocorrectionDisabled()
+                    #if os(iOS)
+                    .textInputAutocapitalization(.never)
                     #endif
             }
             #if !os(tvOS)
-        .formStyle(.grouped)
-        #endif
+            .formStyle(.grouped)
+            // The grouped form's default system text is oversized next to the app's Geist
+            // typography — bring it down and on-brand so the panel doesn't read out of place.
+            .font(.geist(12, relativeTo: .callout))
+            .controlSize(.small)
+            #endif
             #if os(iOS)
-            // The detent below is sized to fit all 3 rows + the action button exactly, so the
-            // Form must NOT scroll/bounce inside it — lock it. (iOS 16+; safe at iOS 17.)
             .scrollDisabled(true)
             #endif
             #if os(macOS)
-            // macOS: UNCHANGED — Cancel + Spacer + Add in an HStack, both wired to the
-            // window's default/cancel keyboard actions. The 380-wide .fixedSize panel below
-            // keeps this compact and centered.
             HStack {
                 Button("Cancel", role: .cancel) { dismiss() }
                     .keyboardShortcut(.cancelAction)
                 Spacer()
-                Button("Add Host") { add() }
+                Button(actionTitle) { save() }
                     .glassProminentButtonStyle()
                     .keyboardShortcut(.defaultAction)
-                    .disabled(address.trimmingCharacters(in: .whitespaces).isEmpty)
+                    .disabled(!canSave)
             }
             .padding(16)
             #else
-            // iOS / iPadOS: NO Cancel — the sheet is dismissed by the drag indicator,
-            // swipe-down, or tap-outside. (AddHostSheet never sets interactiveDismissDisabled,
-            // so all three are live; if anyone adds it later, restore a Cancel here or there is
-            // no way back out.) A single FULL-WIDTH primary action reads as the one thing to do.
-            // The fill must be on the LABEL, not the Button: .frame(maxWidth:.infinity) on the
-            // Button only widens its hit area and leaves the styled capsule hugging the text —
-            // stretching the label is what makes the glass/bordered pill itself go edge-to-edge.
-            // .controlSize(.large) gives the tall, thumb-friendly height; .defaultAction lets a
-            // hardware keyboard / iPad Return submit.
-            Button { add() } label: {
-                Text("Add Host").frame(maxWidth: .infinity)
+            Button { save() } label: {
+                Text(actionTitle).frame(maxWidth: .infinity)
             }
                 .glassProminentButtonStyle()
                 .controlSize(.large)
                 .keyboardShortcut(.defaultAction)
-                .disabled(address.trimmingCharacters(in: .whitespaces).isEmpty)
+                .disabled(!canSave)
                 .padding(16)
             #endif
         }
         #if os(iOS)
-        // A short bottom sheet, not a full-screen modal. .height(320) hugs the 3-field grouped
-        // Form + the full-width action row, instead of the half-screen .medium it used to rest
-        // at. A single fixed detent is enough: the system keeps the content above the keyboard
-        // when Address/Port is focused, and on iPadOS this renders as a short bottom sheet (not a
-        // centered formSheet card). The Form itself is .scrollDisabled (above) so it can't
-        // bounce/scroll inside this fixed detent. (.height(_:) is iOS 16+, safe at iOS 17.)
-        .presentationDetents([.height(320)])
+        // Four fields + the action row — a touch taller than the 3-field add sheet used to be.
+        .presentationDetents([.height(392)])
         .presentationDragIndicator(.visible)
         #endif
         #if os(macOS)
-        .frame(width: 380)
+        .frame(width: 400)
         .fixedSize(horizontal: false, vertical: true)
         #endif
         #endif
     }
 
-    private func add() {
-        onAdd(StoredHost(
-            name: name.trimmingCharacters(in: .whitespaces),
-            address: address.trimmingCharacters(in: .whitespaces),
-            port: UInt16(clamping: port)))
+    private func save() {
+        var host = existing ?? StoredHost(name: "", address: "")
+        host.name = name.trimmingCharacters(in: .whitespaces)
+        host.address = address.trimmingCharacters(in: .whitespaces)
+        host.port = UInt16(clamping: port)
+        host.macAddresses = Self.parseMacs(mac)
+        onSave(host)
         dismiss()
     }
+
+    /// Split comma/space/newline-separated MACs, keep only well-formed `aa:bb:cc:dd:ee:ff` (six hex
+    /// octets, normalized lower-case); nil when none are valid, so clearing the field clears the
+    /// stored MAC.
+    static func parseMacs(_ s: String) -> [String]? {
+        let macs = s
+            .split(whereSeparator: { ",; \n\t".contains($0) })
+            .map { $0.trimmingCharacters(in: .whitespaces).lowercased() }
+            .filter { m in
+                let parts = m.split(separator: ":")
+                return parts.count == 6 && parts.allSatisfy { $0.count == 2 && UInt8($0, radix: 16) != nil }
+            }
+        return macs.isEmpty ? nil : macs
+    }
 }

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

@@ -58,16 +58,19 @@ struct GamepadAddHostView: View {
             .padding(.top, gamepadTitleTopPadding(compact: compact))
             .padding(.bottom, compact ? 4 : 8)
             .frame(maxWidth: .infinity)
-            .overlay(alignment: .topTrailing) { closeButton.padding(.trailing, 20) }
+            .overlay(alignment: .topTrailing) { closeButton.padding(.top, 20).padding(.trailing, 20) }
             .background { GamepadTrayScrim(edge: .top) }
         }
         .safeAreaInset(edge: .bottom, spacing: 0) {
             bottomTray
-                .padding(.horizontal, 22)
-                .padding(.vertical, compact ? 6 : 10)
+                // Equal distance from the left and bottom edges for the legend pill (see GamepadHomeView).
+                .padding(.horizontal, compact ? 12 : 18)
+                .padding(.bottom, compact ? 12 : 18)
+                .padding(.top, compact ? 6 : 10)
                 .background { GamepadTrayScrim(edge: .bottom) }
         }
-        .background { GamepadScreenBackground() }
+        // No aurora — the same clean Liquid-Glass-over-dark base as the gamepad settings screen.
+        .background { GamepadFormBackground() }
         // A port can't exceed 5 digits — cap while typing so the row can't grow absurd.
         .onChange(of: port) { _, value in
             if value.count > 5 { port = String(value.prefix(5)) }
@@ -165,14 +168,16 @@ struct GamepadAddHostView: View {
         }
         .padding(.horizontal, 16)
         .padding(.vertical, 13)
-        .background {
-            RoundedRectangle(cornerRadius: 14, style: .continuous)
-                .fill(.white.opacity(focused || editing == row.id ? 0.1 : 0))
-        }
+        // Liquid Glass rows, matching the settings screen; the focused (or actively edited) row
+        // takes the brand wash, and the edited row keeps its brand caret border.
+        .consoleGlass(
+            RoundedRectangle(cornerRadius: 14, style: .continuous),
+            tint: (focused || editing == row.id) ? Color.brand.opacity(0.30) : nil,
+            interactive: focused)
         .overlay {
             RoundedRectangle(cornerRadius: 14, style: .continuous)
                 .strokeBorder(
-                    editing == row.id ? Color.brand.opacity(0.7) : .white.opacity(focused ? 0.22 : 0),
+                    editing == row.id ? Color.brand.opacity(0.7) : .white.opacity(focused ? 0.28 : 0.06),
                     lineWidth: 1)
         }
         .scaleEffect(focused ? 1.0 : 0.98)

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

@@ -39,7 +39,9 @@ struct GamepadHint: Identifiable {
 }
 
 /// The pinned controls legend every gamepad screen shows bottom-leading (via `.safeAreaInset`).
-/// Same font/spacing everywhere so the legend reads as system chrome, not per-screen decoration.
+/// Same font/spacing everywhere so the legend reads as system chrome, not per-screen decoration —
+/// worn as a self-contained Liquid Glass pill (like the top-bar controller chip) so it floats over
+/// the backdrop instead of dissolving into it.
 struct GamepadHintBar: View {
     let hints: [GamepadHint]
 
@@ -57,39 +59,141 @@ struct GamepadHintBar: View {
         }
         .font(.geist(14, .semibold, relativeTo: .subheadline))
         .foregroundStyle(.white.opacity(0.85))
+        .padding(13)
+        .consoleGlass(Capsule())
+        .overlay(Capsule().strokeBorder(.white.opacity(0.12), lineWidth: 1))
     }
 }
 
-/// The console backdrop: a living "aurora" field in the brand's violet family — soft color blobs
-/// drifting on slow Lissajous paths over black, in the direction of Apple Music's animated player
-/// background but calmer (long 30–90 s periods, muted opacities, a legibility scrim on top, so it
-/// reads as ambience behind the cards, never as content). Deliberately pure SwiftUI rather than a
-/// .metal shader: these sources are built both by SwiftPM (`swift run`/tests) and by the Xcode
-/// project's synchronized folders, and a compiled metallib is only reliably bundled in one of the
-/// two — radial gradients driven by a TimelineView give the same look with none of that risk.
+/// The console backdrop: a living aurora in the brand's violet family, drifting slowly over black
+/// so it reads as ambience behind the cards, never as content. On iOS 18 / macOS 15+ it's an
+/// animated `MeshGradient` — a continuous silk of colour whose control points wander on slow,
+/// out-of-phase sinusoids — finished with an elliptical vignette (pools light in the centre, sinks
+/// the corners) and a top/bottom legibility scrim. Older OSes fall back to the original drifting
+/// radial-blob field, unchanged, so nothing regresses.
 ///
-/// Applied via `.background { }` — NOT as a ZStack sibling — so the `.ignoresSafeArea()` here
-/// can't inflate the caller's layout past the safe area (see the layout discipline note in
-/// GamepadHomeView's header). Honors Reduce Motion by freezing the field at a fixed phase.
+/// Deliberately pure SwiftUI, no `.metal`: these sources build under both SwiftPM (`swift run`/
+/// tests) and the Xcode project's synchronized folders, and a compiled metallib is only reliably
+/// bundled in one of the two. MeshGradient + TimelineView give the silky look with none of that
+/// risk. Applied via `.background { }` — NOT a ZStack sibling — so the `.ignoresSafeArea()` here
+/// can't inflate the caller's layout past the safe area (see the layout note in GamepadHomeView's
+/// header). Honors Reduce Motion by freezing the field at a fixed phase.
 struct GamepadScreenBackground: View {
     @Environment(\.accessibilityReduceMotion) private var reduceMotion
 
-    /// One drifting color blob: a base position + drift ellipse (unit coordinates), angular
-    /// speeds (rad/s — periods of 30–90 s), and a radius that slowly breathes.
+    var body: some View {
+        Group {
+            if reduceMotion {
+                composite(at: 0)
+            } else {
+                // 30 Hz is plenty for a field that drifts centimetres per minute, and halves the
+                // redraw cost of a battery-fed couch device vs. the display's native rate.
+                TimelineView(.animation(minimumInterval: 1.0 / 30.0)) { context in
+                    composite(at: context.date.timeIntervalSinceReferenceDate)
+                }
+            }
+        }
+        .ignoresSafeArea()
+    }
+
+    /// The colour field under a very slow warm/cool hue sway, an elliptical vignette, and the
+    /// title/hints legibility scrim.
+    private func composite(at t: TimeInterval) -> some View {
+        ZStack {
+            Color.black
+            colorField(at: t)
+                // ±8° over ~5 min — the whole field very slowly warms and cools.
+                .hueRotation(.degrees(sin(t * 0.021) * 8))
+            // Cinematic vignette: darker toward the edges so the cards sit in the pooled light.
+            // Soft (extends past the frame) so the corners deepen rather than crush to black.
+            EllipticalGradient(
+                colors: [.clear, .black.opacity(0.42)],
+                center: .center, startRadiusFraction: 0.25, endRadiusFraction: 1.15)
+            // Legibility grounding for the pinned title (top) and hint pill (bottom). This one
+            // darkens the aurora itself (it's the backdrop's bottom layer — nothing behind it to
+            // blur), so it stays a gradient, just a light one now.
+            LinearGradient(
+                stops: [
+                    .init(color: .black.opacity(0.38), location: 0),
+                    .init(color: .black.opacity(0.06), location: 0.32),
+                    .init(color: .black.opacity(0.08), location: 0.68),
+                    .init(color: .black.opacity(0.40), location: 1),
+                ],
+                startPoint: .top, endPoint: .bottom)
+        }
+    }
+
+    @ViewBuilder private func colorField(at t: TimeInterval) -> some View {
+        if #available(iOS 18, macOS 15, tvOS 18, *) {
+            MeshGradient(
+                width: 4, height: 4,
+                points: Self.meshPoints(at: t),
+                colors: Self.meshColors,
+                smoothsColors: true)
+        } else {
+            LegacyBlobField(t: t)
+        }
+    }
+
+    // MARK: - MeshGradient aurora (iOS 18 / macOS 15+)
+
+    /// Sixteen mesh colours (row-major, 4×4): dark-violet corners sink the frame, the edges carry
+    /// mid-tone violets, and the four interior points hold the bright brand family — a violet and a
+    /// blue-violet up top, a magenta-violet and a violet below — so warm pools on the left, cool on
+    /// the right, and the silk shifts temperature as those interior points drift.
+    private static let meshColors: [Color] = {
+        let corner = Color(red: 0.075, green: 0.060, blue: 0.160)
+        return [
+            corner, Color(red: 0.34, green: 0.27, blue: 0.72), Color(red: 0.30, green: 0.26, blue: 0.74), corner,
+            Color(red: 0.42, green: 0.20, blue: 0.54), Color(red: 0.49, green: 0.39, blue: 0.95), Color(red: 0.28, green: 0.31, blue: 0.84), Color(red: 0.16, green: 0.26, blue: 0.64),
+            Color(red: 0.45, green: 0.23, blue: 0.60), Color(red: 0.53, green: 0.31, blue: 0.75), Color(red: 0.35, green: 0.35, blue: 0.91), Color(red: 0.19, green: 0.28, blue: 0.70),
+            corner, Color(red: 0.22, green: 0.18, blue: 0.54), Color(red: 0.24, green: 0.20, blue: 0.58), corner,
+        ]
+    }()
+
+    /// The 4×4 control points at time `t`: every boundary point is PINNED to the frame (so the mesh
+    /// always fills edge-to-edge — a drifting edge point would shrink the mesh and expose the black
+    /// behind it), while only the four interior points wander on slow, out-of-phase sinusoids
+    /// (periods ~90–130 s) so the bright colour pools breathe without ever looking like they loop.
+    private static func meshPoints(at t: TimeInterval) -> [SIMD2<Float>] {
+        func wob(_ bx: Float, _ by: Float, _ a: Float,
+                 _ sx: Double, _ sy: Double, _ ph: Double) -> SIMD2<Float> {
+            SIMD2(bx + a * Float(sin(t * sx + ph)), by + a * Float(cos(t * sy + ph * 1.3)))
+        }
+        return [
+            SIMD2(0, 0), SIMD2(0.333, 0), SIMD2(0.667, 0), SIMD2(1, 0),
+            SIMD2(0, 0.333),
+                wob(0.333, 0.333, 0.11, 0.049, 0.063, 0.4),
+                wob(0.667, 0.333, 0.10, 0.055, 0.052, 2.1),
+            SIMD2(1, 0.333),
+            SIMD2(0, 0.667),
+                wob(0.333, 0.667, 0.10, 0.058, 0.049, 3.6),
+                wob(0.667, 0.667, 0.12, 0.047, 0.061, 5.0),
+            SIMD2(1, 0.667),
+            SIMD2(0, 1), SIMD2(0.333, 1), SIMD2(0.667, 1), SIMD2(1, 1),
+        ]
+    }
+}
+
+/// Pre-18/15 fallback for `GamepadScreenBackground`: the original drifting radial-blob field — four
+/// soft colour blobs on slow Lissajous paths, additively blended. Kept verbatim so older OSes see
+/// exactly the aurora they shipped with (the mesh path is the upgrade for OS 18/15+).
+private struct LegacyBlobField: View {
+    let t: TimeInterval
+
+    /// One drifting color blob: a base position + drift ellipse (unit coordinates), angular speeds
+    /// (rad/s — periods of 30–90 s), and a radius that slowly breathes.
     private struct Blob {
         let color: Color
         let center: CGPoint
         let drift: CGSize
         let speed: (x: Double, y: Double)
         let phase: (x: Double, y: Double)
-        /// Radius as a fraction of the view's larger dimension (+ breathing amplitude/speed).
         let radius: CGFloat
         let breathe: (amount: CGFloat, speed: Double)
         let opacity: Double
     }
 
-    /// The brand violet, a deeper indigo, a warmer plum, and a cool blue — related hues so the
-    /// field shifts within one temperature instead of strobing through the rainbow.
     private static let blobs: [Blob] = [
         Blob(color: Color(red: 0.53, green: 0.47, blue: 0.96), // brand violet
              center: CGPoint(x: 0.30, y: 0.24), drift: CGSize(width: 0.16, height: 0.10),
@@ -110,49 +214,18 @@ struct GamepadScreenBackground: View {
     ]
 
     var body: some View {
-        Group {
-            if reduceMotion {
-                field(at: 0)
-            } else {
-                // 30 Hz is plenty for centimeters-per-minute drift, and halves the redraw cost
-                // of a battery-fed couch device vs. the default display rate.
-                TimelineView(.animation(minimumInterval: 1.0 / 30.0)) { context in
-                    field(at: context.date.timeIntervalSinceReferenceDate)
-                }
-            }
-        }
-        .ignoresSafeArea()
-    }
-
-    private func field(at t: TimeInterval) -> some View {
         GeometryReader { geo in
             let side = max(geo.size.width, geo.size.height)
             ZStack {
-                Color.black
-                ZStack {
-                    ForEach(Self.blobs.indices, id: \.self) { i in
-                        blobView(Self.blobs[i], at: t, in: geo.size, side: side)
-                    }
+                ForEach(Self.blobs.indices, id: \.self) { i in
+                    blobView(Self.blobs[i], in: geo.size, side: side)
                 }
-                // ±10° over ~5 min — the whole field very slowly warms and cools.
-                .hueRotation(.degrees(sin(t * 0.021) * 10))
-                // Composite the additive blobs offscreen once instead of per-layer.
-                .drawingGroup()
-                // Legibility scrim: the title (top) and detail/hints (bottom) always sit on
-                // near-black, whatever the blobs are doing behind them.
-                LinearGradient(
-                    stops: [
-                        .init(color: .black.opacity(0.55), location: 0),
-                        .init(color: .black.opacity(0.15), location: 0.35),
-                        .init(color: .black.opacity(0.20), location: 0.65),
-                        .init(color: .black.opacity(0.60), location: 1),
-                    ],
-                    startPoint: .top, endPoint: .bottom)
             }
+            .drawingGroup()
         }
     }
 
-    private func blobView(_ blob: Blob, at t: TimeInterval, in size: CGSize, side: CGFloat) -> some View {
+    private func blobView(_ blob: Blob, in size: CGSize, side: CGFloat) -> some View {
         let x = blob.center.x + blob.drift.width * CGFloat(sin(t * blob.speed.x + blob.phase.x))
         let y = blob.center.y + blob.drift.height * CGFloat(cos(t * blob.speed.y + blob.phase.y))
         let r = side * blob.radius
@@ -168,28 +241,62 @@ struct GamepadScreenBackground: View {
     }
 }
 
-/// A darkening scrim behind a pinned tray (a screen title, the hints/detail bar, the keyboard
-/// tray): scrollable rows pass beneath those insets, so without this the tray text and the row
-/// underneath render interleaved. Fades toward the content so it reads as depth, not a bar.
+/// A blur gradient behind a pinned tray (a screen title, the hints/detail bar, the keyboard tray):
+/// scrollable rows pass beneath those insets, so without this the tray text and the row underneath
+/// render interleaved. Pure blur — a dark material faded out by a gradient mask, no dark tint — so
+/// the tray's text sits on a softly blurred backdrop that dissolves into the rows.
 struct GamepadTrayScrim: View {
     let edge: VerticalEdge
 
     var body: some View {
-        LinearGradient(
-            stops: [
-                .init(color: .black.opacity(0.92), location: 0),
-                .init(color: .black.opacity(0.85), location: 0.55),
-                .init(color: .black.opacity(0), location: 1),
-            ],
-            startPoint: edge == .top ? .top : .bottom,
-            endPoint: edge == .top ? .bottom : .top)
+        let fromEdge: UnitPoint = edge == .top ? .top : .bottom
+        let toContent: UnitPoint = edge == .top ? .bottom : .top
+        Rectangle()
+            .fill(.ultraThinMaterial)
+            // These trays always sit on the dark console UI; force dark so the material frosts dark
+            // (white text stays legible) regardless of the system appearance.
+            .environment(\.colorScheme, .dark)
+            // Fade the whole blur out toward the content so it dissolves rather than ending on a line.
+            .mask {
+                LinearGradient(
+                    stops: [
+                        .init(color: .black, location: 0),
+                        .init(color: .black.opacity(0.9), location: 0.5),
+                        .init(color: .clear, location: 1),
+                    ],
+                    startPoint: fromEdge, endPoint: toContent)
+            }
             // Grow past the tray so the fade-to-clear happens OUTSIDE its bounds — the tray's own
-            // text always sits on the near-opaque part, rows dim before they reach it.
+            // text always sits on the strong part, rows blur out before they reach it.
             .padding(edge == .top ? .bottom : .top, -32)
             .ignoresSafeArea()
     }
 }
 
+/// The calm backdrop for the gamepad UI's form screens (settings, add-host) — NOT the launcher's
+/// drifting aurora (this stays still and quiet), but deliberately NOT near-black either: Liquid
+/// Glass refracts whatever sits behind it, so over black the rows turn invisible. A deep indigo
+/// base plus two soft, static violet/indigo glows give the glass real colour and luminance to lens,
+/// so the rows read as glass while the screen stays restful.
+struct GamepadFormBackground: View {
+    var body: some View {
+        ZStack {
+            Color(red: 0.075, green: 0.062, blue: 0.150)
+            // Violet lift top-leading, cooler indigo bottom-trailing — resolution-independent
+            // (fraction radii) so the glow scale tracks the window on any screen.
+            EllipticalGradient(
+                colors: [Color(red: 0.40, green: 0.31, blue: 0.68).opacity(0.9), .clear],
+                center: UnitPoint(x: 0.26, y: 0.14),
+                startRadiusFraction: 0, endRadiusFraction: 0.78)
+            EllipticalGradient(
+                colors: [Color(red: 0.20, green: 0.24, blue: 0.58).opacity(0.75), .clear],
+                center: UnitPoint(x: 0.82, y: 0.9),
+                startRadiusFraction: 0, endRadiusFraction: 0.78)
+        }
+        .ignoresSafeArea()
+    }
+}
+
 /// "Which pad is driving this UI" — the active controller's name and battery, worn as a quiet
 /// chip in the launcher's top bar. Callers observe GamepadManager already, so this re-renders
 /// when the pad or its battery state changes.

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

@@ -44,8 +44,8 @@ private struct HomeTile: Identifiable {
     var hasLibrary = false
     /// Shows this SF symbol in the badge instead of the title monogram (the Add Host tile).
     var icon: String?
-    /// Whether the detail panel shows the online/paired pill (hosts yes, actions no).
-    var showsStatus = true
+    /// Offline saved host we hold a MAC for (and WoL is available) — activating it wakes first.
+    var canWake = false
     let activate: () -> Void
 }
 
@@ -54,6 +54,9 @@ struct GamepadHomeView: View {
     @ObservedObject var model: SessionModel
     @ObservedObject var discovery: HostDiscovery
     @Binding var libraryTarget: StoredHost?
+    /// Wake-and-wait driver — gates the carousel while its overlay is up, and the carousel's
+    /// activate routes an offline+wakeable host through it (see ContentView.startSession).
+    @ObservedObject var waker: HostWaker
     let connect: (StoredHost) -> Void
     let connectDiscovered: (DiscoveredHost) -> Void
 
@@ -84,8 +87,11 @@ struct GamepadHomeView: View {
         }
         .safeAreaInset(edge: .bottom, alignment: .leading, spacing: 0) {
             GamepadHintBar(hints: hints)
-                .padding(.leading, 22)
-                .padding(.vertical, compact ? 6 : 10)
+                // Equal distance from the left and bottom edges — the pill's corner inset was the
+                // real asymmetry (leading 22 vs bottom 10), not its internal padding.
+                .padding(.leading, compact ? 12 : 18)
+                .padding(.bottom, compact ? 12 : 18)
+                .padding(.top, compact ? 4 : 8)
         }
         .background { GamepadScreenBackground() }
         .onAppear { discovery.start() }
@@ -115,13 +121,13 @@ struct GamepadHomeView: View {
 
     @ViewBuilder private func hero(for size: CGSize) -> some View {
         let cardWidth = min(340, size.width * 0.84)
-        // 96 ≈ the carousel's own vertical breathing (+40) plus the detail line (~54); clamp so
-        // the strip + detail always fit the region the safe-area insets leave.
-        let cardHeight = min(compact ? 170 : 210, max(118, size.height - 96))
+        // 48 ≈ the carousel's own vertical breathing (+40) plus a small margin; clamp so the strip
+        // always fits the region the pinned title / hints safe-area insets leave. (The old detail
+        // line below the strip is gone — it only re-printed what the centered card already shows.)
+        let cardHeight = min(compact ? 176 : 224, max(118, size.height - 48))
         VStack(spacing: compact ? 8 : 10) {
             Spacer(minLength: 0)
             carousel(cardWidth: cardWidth, cardHeight: cardHeight)
-            detailPanel
             Spacer(minLength: 0)
         }
         .frame(maxWidth: .infinity, maxHeight: .infinity)
@@ -155,9 +161,9 @@ struct GamepadHomeView: View {
             onActivate: { $0.activate() },
             onSecondary: { openLibraryForSelected() },
             onTertiary: { showSettings = true },
-            // Stop consuming the controller while another screen is presented on top — otherwise
-            // the launcher navigates behind it (invisibly on iPhone, visibly on iPad's page sheet).
-            isActive: libraryTarget == nil && !showSettings && !showAddHost
+            // Stop consuming the controller while another screen (or the wake overlay) is on top —
+            // otherwise the launcher navigates behind it (invisibly on iPhone, visibly on iPad).
+            isActive: libraryTarget == nil && !showSettings && !showAddHost && waker.waking == nil
         ) { tile in
             hostCard(tile, size: CGSize(width: cardWidth, height: cardHeight))
         }
@@ -186,49 +192,14 @@ struct GamepadHomeView: View {
             }
     }
 
-    /// The "now focused" host, spelled out below the strip — empty (not hidden) so the layout
-    /// doesn't jump as the selection changes.
-    @ViewBuilder private var detailPanel: some View {
-        let tile = tiles.first { $0.id == selection }
-        VStack(spacing: 6) {
-            Text(tile?.title ?? " ")
-                .font(.geist(22, .bold, relativeTo: .title2))
-                .foregroundStyle(.white)
-                .lineLimit(1)
-            HStack(spacing: 10) {
-                Text(tile?.subtitle ?? " ")
-                    .font(.geist(13, relativeTo: .caption))
-                    .foregroundStyle(.white.opacity(0.6))
-                if let tile, tile.showsStatus {
-                    statusPill(online: tile.isOnline, paired: tile.isPaired)
-                }
-            }
-        }
-        .frame(maxWidth: .infinity)
-        .padding(.horizontal, 24)
-        .animation(.smooth(duration: 0.25), value: selection)
-    }
-
-    private func statusPill(online: Bool, paired: Bool) -> some View {
-        HStack(spacing: 6) {
-            Circle()
-                .fill(online ? Color.green : Color.white.opacity(0.35))
-                .frame(width: 6, height: 6)
-            Text(online ? "ONLINE" : "OFFLINE")
-            if paired { Text("· PAIRED") }
-        }
-        .font(.geist(11, .medium, relativeTo: .caption2))
-        .tracking(0.8)
-        .foregroundStyle(.white.opacity(0.55))
-    }
-
     // MARK: - Hint bar (pinned bottom-leading via safeAreaInset)
 
     private var hints: [GamepadHint] {
         let selected = tiles.first { $0.id == selection }
         var hints = [GamepadHint(
             glyph: buttonGlyph(\.buttonA, fallback: "a.circle"),
-            text: selected?.id == .addHost ? "Add Host" : "Connect")]
+            text: selected?.id == .addHost ? "Add Host"
+                : (selected?.canWake == true ? "Wake & Connect" : "Connect"))]
         if libraryEnabled, selected?.hasLibrary == true {
             hints.append(.init(glyph: buttonGlyph(\.buttonY, fallback: "y.circle"), text: "Library"))
         }
@@ -252,6 +223,8 @@ struct GamepadHomeView: View {
                 isConnecting: model.phase == .connecting && model.activeHost?.id == host.id,
                 filled: true,
                 hasLibrary: true,
+                canWake: PunktfunkConnection.wakeOnLANAvailable
+                    && !discovery.advertises(host) && !host.wakeMacs.isEmpty,
                 activate: { connect(host) })
         }
         let discovered = discovery.unsaved(among: store.hosts).map { d in
@@ -267,7 +240,6 @@ struct GamepadHomeView: View {
             title: "Add Host",
             subtitle: "Register a host by address",
             icon: "plus",
-            showsStatus: false,
             activate: { showAddHost = true })
         return saved + discovered + [add]
     }
@@ -291,14 +263,23 @@ private struct GamepadHostTile: View {
 
     var body: some View {
         VStack(alignment: .leading, spacing: 0) {
-            HStack(alignment: .top) {
+            HStack(alignment: .top, spacing: 8) {
                 monogramBadge
                 Spacer(minLength: 0)
-                if tile.isOnline {
-                    Circle()
-                        .fill(Color.green)
-                        .frame(width: 9, height: 9)
-                        .shadow(color: .green.opacity(0.7), radius: 5)
+                // The status the removed detail panel used to spell out, now on the card itself: a
+                // lock for a paired (pinned-identity) host + a green pip when it's live on the LAN.
+                HStack(spacing: 7) {
+                    if tile.isPaired {
+                        Image(systemName: "lock.fill")
+                            .font(.system(size: 11, weight: .semibold))
+                            .foregroundStyle(.white.opacity(0.5))
+                    }
+                    if tile.isOnline {
+                        Circle()
+                            .fill(Color.green)
+                            .frame(width: 9, height: 9)
+                            .shadow(color: .green.opacity(0.7), radius: 5)
+                    }
                 }
             }
             Spacer(minLength: 0)
@@ -315,11 +296,11 @@ private struct GamepadHostTile: View {
         }
         .padding(20)
         .frame(width: size.width, height: size.height, alignment: .leading)
-        .background {
-            RoundedRectangle(cornerRadius: 26, style: .continuous)
-                .fill(.ultraThinMaterial)
-                .environment(\.colorScheme, .dark)
-        }
+        // Liquid Glass console tile — a brand wash marks a saved host as primary; discovered /
+        // Add-Host tiles stay neutral glass with a dashed edge. Glass clips to the shape itself.
+        .consoleGlass(
+            RoundedRectangle(cornerRadius: 26, style: .continuous),
+            tint: tile.filled ? Color.brand.opacity(0.20) : nil)
         .overlay {
             RoundedRectangle(cornerRadius: 26, style: .continuous)
                 .strokeBorder(
@@ -328,7 +309,6 @@ private struct GamepadHostTile: View {
                         startPoint: .top, endPoint: .bottom),
                     style: StrokeStyle(lineWidth: 1, dash: tile.filled ? [] : [6, 5]))
         }
-        .clipShape(RoundedRectangle(cornerRadius: 26, style: .continuous))
         .shadow(color: .black.opacity(0.45), radius: 20, y: 14)
     }
 

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

@@ -26,8 +26,13 @@ struct HomeView: View {
     let onPaired: (StoredHost, Data) -> Void
     /// Picked a title in the (experimental) library — start a session that launches it.
     let onLaunchTitle: (StoredHost, String) -> Void
+    /// Explicit Wake-on-LAN of an offline host — fires the packet and waits for it to come online
+    /// (the "Waking…" overlay), without connecting. Routed through ContentView's HostWaker.
+    let wake: (StoredHost) -> Void
     /// Experimental game-library browser (gated) — the host-card "Browse Library…" action.
     @AppStorage(DefaultsKey.libraryEnabled) private var libraryEnabled = false
+    /// The host being edited (name / address / port / Wake-on-LAN MAC) — drives the edit sheet.
+    @State private var editTarget: StoredHost?
 
     var body: some View {
         NavigationStack {
@@ -126,6 +131,13 @@ struct HomeView: View {
         .sheet(isPresented: $showAddHost) {
             AddHostSheet { store.add($0) }
         }
+        .sheet(item: $editTarget) { host in
+            // Prefill the MAC from the live advert when the host hasn't stored one yet.
+            AddHostSheet(
+                existing: host,
+                suggestedMacs: discovery.hosts.first { host.matches($0) }?.macAddresses ?? [],
+                onSave: { store.update($0) })
+        }
         #if os(iOS)
         // SettingsView owns its own NavigationSplitView (sidebar + detail) and Done button, so it
         // is presented directly — wrapping it in a NavigationStack here would nest a split view in
@@ -155,13 +167,8 @@ struct HomeView: View {
             onForget: { store.forgetIdentity(host) },
             onRemove: { store.remove(host) },
             onBrowseLibrary: onBrowseLibrary,
-            onWake: {
-                let macs = host.wakeMacs
-                let ip = host.address
-                DispatchQueue.global(qos: .userInitiated).async {
-                    PunktfunkConnection.wakeOnLAN(macs: macs, lastKnownIP: ip)
-                }
-            })
+            onWake: { wake(host) },
+            onEdit: { editTarget = host })
     }
 
     private var discoveredSection: some View {

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

@@ -89,6 +89,8 @@ struct HostCardView: View {
     /// Send a Wake-on-LAN magic packet. Shown only when the host is offline and we have a stored
     /// MAC to target (a tap-to-connect already auto-wakes; this is the explicit "just wake it").
     var onWake: (() -> Void)? = nil
+    /// Open the edit sheet (name / address / port / Wake-on-LAN MAC).
+    var onEdit: (() -> Void)? = nil
 
     var body: some View {
         let m = CardMetrics.current
@@ -136,6 +138,9 @@ struct HostCardView: View {
         #endif
         .disabled(isBusy)
         .contextMenu {
+            if let onEdit {
+                Button("Edit…", systemImage: "pencil", action: onEdit)
+            }
             Button("Pair with PIN…", action: onPair)
             Button("Test Network Speed…", action: onSpeedTest)
             if let onBrowseLibrary {

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

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

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

@@ -18,23 +18,47 @@ struct ShotScene {
 
 @MainActor
 enum ShotScenes {
-    static let all: [ShotScene] = [
-        ShotScene(name: "01-stream", orientation: .landscape, colorScheme: .dark) {
-            AnyView(ShotStreamHero())
-        },
-        ShotScene(name: "02-hosts", orientation: .natural, colorScheme: .dark) {
-            AnyView(ShotHome())
-        },
-        ShotScene(name: "03-pair", orientation: .natural, colorScheme: .dark) {
-            AnyView(ShotPair())
-        },
-        ShotScene(name: "04-trust", orientation: .landscape, colorScheme: .dark) {
-            AnyView(ShotTrust())
-        },
-        ShotScene(name: "05-settings", orientation: .natural, colorScheme: .dark) {
-            AnyView(ShotSettings())
-        },
-    ]
+    static var all: [ShotScene] {
+        var scenes: [ShotScene] = [
+            ShotScene(name: "01-stream", orientation: .landscape, colorScheme: .dark) {
+                AnyView(ShotStreamHero())
+            },
+            ShotScene(name: "02-hosts", orientation: .natural, colorScheme: .dark) {
+                AnyView(ShotHome())
+            },
+            ShotScene(name: "03-pair", orientation: .natural, colorScheme: .dark) {
+                AnyView(ShotPair())
+            },
+            ShotScene(name: "04-trust", orientation: .landscape, colorScheme: .dark) {
+                AnyView(ShotTrust())
+            },
+            ShotScene(name: "05-settings", orientation: .natural, colorScheme: .dark) {
+                AnyView(ShotSettings())
+            },
+        ]
+        #if os(iOS) || os(macOS)
+        // The gamepad-mode console screens (no tvOS — native focus engine there). Dev-only shots
+        // for eyeballing the Liquid Glass host tiles + settings rows.
+        scenes += [
+            ShotScene(name: "06-gamepad-home", orientation: .natural, colorScheme: .dark) {
+                AnyView(ShotGamepadHome())
+            },
+            ShotScene(name: "07-gamepad-settings", orientation: .natural, colorScheme: .dark) {
+                AnyView(ShotGamepadSettings())
+            },
+            ShotScene(name: "08-gamepad-addhost", orientation: .natural, colorScheme: .dark) {
+                AnyView(ShotGamepadAddHost())
+            },
+            ShotScene(name: "09-waking", orientation: .natural, colorScheme: .dark) {
+                AnyView(ShotWaking())
+            },
+        ]
+        #endif
+        scenes.append(ShotScene(name: "10-edithost", orientation: .natural, colorScheme: .dark) {
+            AnyView(ShotEditHost())
+        })
+        return scenes
+    }
 }
 
 // MARK: - Mock data
@@ -75,7 +99,7 @@ private struct ShotHome: View {
             showAddHost: .constant(false), pairingTarget: .constant(nil),
             speedTestTarget: .constant(nil), libraryTarget: .constant(nil),
             connect: { _ in }, connectDiscovered: { _ in },
-            onPaired: { _, _ in }, onLaunchTitle: { _, _ in })
+            onPaired: { _, _ in }, onLaunchTitle: { _, _ in }, wake: { _ in })
         #else
         HomeView(
             store: store, model: model, discovery: discovery,
@@ -83,11 +107,77 @@ private struct ShotHome: View {
             speedTestTarget: .constant(nil), libraryTarget: .constant(nil),
             showSettings: .constant(false),
             connect: { _ in }, connectDiscovered: { _ in },
-            onPaired: { _, _ in }, onLaunchTitle: { _, _ in })
+            onPaired: { _, _ in }, onLaunchTitle: { _, _ in }, wake: { _ in })
         #endif
     }
 }
 
+// MARK: - Gamepad-mode console screens (dev-only glass preview)
+
+#if os(iOS) || os(macOS)
+private struct ShotGamepadHome: View {
+    @StateObject private var store = ShotMock.hostStore()
+    @StateObject private var model = SessionModel()
+    @StateObject private var discovery = HostDiscovery()
+    @StateObject private var waker = HostWaker()
+
+    var body: some View {
+        GamepadHomeView(
+            store: store, model: model, discovery: discovery,
+            libraryTarget: .constant(nil), waker: waker,
+            connect: { _ in }, connectDiscovered: { _ in })
+    }
+}
+
+private struct ShotGamepadSettings: View {
+    var body: some View { GamepadSettingsView() }
+}
+
+private struct ShotGamepadAddHost: View {
+    var body: some View { GamepadAddHostView(onAdd: { _ in }) }
+}
+
+private struct ShotWaking: View {
+    @StateObject private var store = ShotMock.hostStore()
+    @StateObject private var model = SessionModel()
+    @StateObject private var discovery = HostDiscovery()
+    @StateObject private var waker = HostWaker()
+
+    var body: some View {
+        GamepadHomeView(
+            store: store, model: model, discovery: discovery,
+            libraryTarget: .constant(nil), waker: waker,
+            connect: { _ in }, connectDiscovered: { _ in }
+        )
+        .overlay { WakeOverlay(waker: waker) }
+        .onAppear {
+            waker.debugSet(.init(
+                hostID: store.hosts.first?.id ?? UUID(),
+                hostName: "Battlestation", connectsAfter: true, seconds: 14))
+        }
+    }
+}
+#endif
+
+// MARK: - Edit host (add/edit sheet with the Wake-on-LAN MAC field)
+
+private struct ShotEditHost: View {
+    var body: some View {
+        ZStack {
+            ShotHome().blur(radius: 24).overlay(Color.black.opacity(0.45))
+            AddHostSheet(
+                existing: StoredHost(
+                    name: "Battlestation", address: "192.168.1.20", port: 9777,
+                    pinnedSHA256: ShotMock.fingerprint, macAddresses: ["a4:b1:c2:d3:e4:f5"]),
+                onSave: { _ in })
+                #if os(macOS)
+                .clipShape(RoundedRectangle(cornerRadius: 12))
+                .shadow(radius: 40, y: 16)
+                #endif
+        }
+    }
+}
+
 // MARK: - Settings
 
 private struct ShotSettings: View {

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

@@ -0,0 +1,112 @@
+// Wake a sleeping host and WAIT for it to come back before proceeding.
+//
+// A magic packet is fire-and-forget, and a cold box can take 20–60 s to POST, boot, and start
+// advertising on mDNS again — far longer than a connect attempt will sit. The old path fired a
+// packet and immediately dialed, so a genuinely-asleep host just failed. This drives a visible
+// "Waking…" state instead: it (re-)sends the packet, polls the host's mDNS presence once a second,
+// and on success runs `onOnline` (the real connect for a Wake-&-Connect, or nothing for an explicit
+// wake-only); on timeout it parks in a retry/cancel state. One wake at a time.
+
+import Foundation
+import PunktfunkKit
+import SwiftUI
+
+@MainActor
+final class HostWaker: ObservableObject {
+    struct Waking: Equatable {
+        let hostID: UUID
+        let hostName: String
+        /// Whether coming online chains into a connect (Wake & Connect) vs. just stopping.
+        let connectsAfter: Bool
+        var seconds = 0
+        var timedOut = false
+    }
+
+    /// nil = idle; non-nil drives `WakeOverlay`.
+    @Published private(set) var waking: Waking?
+
+    /// How long to wait for the host to reappear before giving up. Generous — a cold boot + service
+    /// start can be a minute-plus.
+    private let timeoutSeconds = 90
+    /// Re-send the packet this often: a single one can be missed, and some NICs only wake on a fresh
+    /// packet after dropping into a deeper sleep state.
+    private let resendEverySeconds = 6
+
+    private var loop: Task<Void, Never>?
+    /// Captured so "Try Again" replays the exact same wait.
+    private var replay: (() -> Void)?
+
+    /// Wake `host` and wait for `isOnline()` to go true, then run `onOnline`. `macs`/`lastIP` target
+    /// the magic packet. No-ops straight to `onOnline` when there's nothing to wake with or the host
+    /// is already up (a race between the caller's check and here).
+    func start(
+        host: StoredHost, connectsAfter: Bool,
+        macs: [String], lastIP: String?,
+        isOnline: @escaping () -> Bool, onOnline: @escaping () -> Void
+    ) {
+        guard !macs.isEmpty, !isOnline() else {
+            cancel()
+            onOnline()
+            return
+        }
+        replay = { [weak self] in
+            self?.run(host: host, connectsAfter: connectsAfter, macs: macs, lastIP: lastIP,
+                      isOnline: isOnline, onOnline: onOnline)
+        }
+        replay?()
+    }
+
+    /// Stop waiting and dismiss the overlay (B / Cancel).
+    func cancel() {
+        loop?.cancel()
+        loop = nil
+        replay = nil
+        waking = nil
+    }
+
+    /// Restart the wait after a timeout (A / Try Again).
+    func retry() { replay?() }
+
+    private func run(
+        host: StoredHost, connectsAfter: Bool, macs: [String], lastIP: String?,
+        isOnline: @escaping () -> Bool, onOnline: @escaping () -> Void
+    ) {
+        loop?.cancel()
+        waking = Waking(hostID: host.id, hostName: host.displayName, connectsAfter: connectsAfter)
+        let timeout = timeoutSeconds
+        let resend = resendEverySeconds
+        loop = Task { [weak self] in
+            var elapsed = 0
+            while !Task.isCancelled {
+                if elapsed % resend == 0 { Self.sendPacket(macs: macs, lastIP: lastIP) }
+                if isOnline() {
+                    guard let self, !Task.isCancelled else { return }
+                    self.waking = nil
+                    self.loop = nil
+                    onOnline()
+                    return
+                }
+                if elapsed >= timeout {
+                    self?.waking?.timedOut = true
+                    self?.loop = nil
+                    return
+                }
+                try? await Task.sleep(nanoseconds: 1_000_000_000)
+                elapsed += 1
+                self?.waking?.seconds = elapsed
+            }
+        }
+    }
+
+    /// Blocking sends (see PunktfunkConnection.wakeOnLAN) — off the main thread.
+    private static func sendPacket(macs: [String], lastIP: String?) {
+        DispatchQueue.global(qos: .userInitiated).async {
+            PunktfunkConnection.wakeOnLAN(macs: macs, lastKnownIP: lastIP)
+        }
+    }
+
+    #if DEBUG
+    /// Force a static waking state for the screenshot harness (no timers, no packets).
+    func debugSet(_ w: Waking) { waking = w }
+    #endif
+}

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

@@ -81,13 +81,17 @@ struct GamepadSettingsView: View {
                     .init(glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Done"),
                 ])
             }
-            .padding(.leading, 22)
+            // Equal distance from the left and bottom edges for the legend pill (see GamepadHomeView).
+            .padding(.leading, compact ? 12 : 18)
             .padding(.trailing, 22)
-            .padding(.vertical, compact ? 6 : 10)
+            .padding(.bottom, compact ? 12 : 18)
+            .padding(.top, compact ? 6 : 10)
             .frame(maxWidth: .infinity, alignment: .leading)
             .background { GamepadTrayScrim(edge: .bottom) }
         }
-        .background { GamepadScreenBackground() }
+        // No aurora here — the settings read as clean Liquid Glass over a quiet dark base, so the
+        // glass rows are the only material on the screen.
+        .background { GamepadFormBackground() }
         .onAppear {
             gamepads.refresh()
             gamepads.startDiscovery()
@@ -148,13 +152,14 @@ struct GamepadSettingsView: View {
             }
             .padding(.horizontal, 16)
             .padding(.vertical, 13)
-            .background {
-                RoundedRectangle(cornerRadius: 14, style: .continuous)
-                    .fill(.white.opacity(focused ? 0.1 : 0))
-            }
+            // Every row is Liquid Glass; the focused one takes a brand wash and reacts to press.
+            .consoleGlass(
+                RoundedRectangle(cornerRadius: 14, style: .continuous),
+                tint: focused ? Color.brand.opacity(0.30) : nil,
+                interactive: focused)
             .overlay {
                 RoundedRectangle(cornerRadius: 14, style: .continuous)
-                    .strokeBorder(.white.opacity(focused ? 0.22 : 0), lineWidth: 1)
+                    .strokeBorder(.white.opacity(focused ? 0.28 : 0.06), lineWidth: 1)
             }
             .scaleEffect(focused ? 1.0 : 0.98)
             .animation(.smooth(duration: 0.18), value: focused)

clients/apple/Sources/PunktfunkClient/Stores/HostStore.swift

@@ -98,6 +98,13 @@ final class HostStore: ObservableObject {
         hosts.removeAll { $0.id == host.id }
     }
 
+    /// Replace a saved host in place (the edit sheet) — matched by id, so identity/pin/last-connected
+    /// carried on the passed value are preserved.
+    func update(_ host: StoredHost) {
+        guard let i = hosts.firstIndex(where: { $0.id == host.id }) else { return }
+        hosts[i] = host
+    }
+
     func markConnected(_ hostID: UUID) {
         guard let i = hosts.firstIndex(where: { $0.id == hostID }) else { return }
         hosts[i].lastConnected = Date()

clients/apple/Sources/PunktfunkClient/Support/GlassStyle.swift

@@ -67,3 +67,41 @@ extension View {
         modifier(GlassProminentButton())
     }
 }
+
+// MARK: - Console glass (gamepad host tiles + settings rows)
+
+/// Liquid Glass tuned for the gamepad UI's dark "console" surfaces — the host-carousel tiles and
+/// the settings rows. Unlike `glassBackground` (floating-overlay only, per HIG), this deliberately
+/// clads content tiles / dense rows: a chosen part of the 10-foot console look. `tint` washes the
+/// glass toward a color (the brand violet on the focused / primary surface); `interactive` makes
+/// it flex on press. The pre-26 fallback is `.ultraThinMaterial` forced dark — these surfaces
+/// always sit on the near-black backdrop, so the material must stay dark even in a light appearance.
+private struct ConsoleGlass<S: Shape>: ViewModifier {
+    let shape: S
+    var tint: Color?
+    var interactive = false
+
+    func body(content: Content) -> some View {
+        if #available(iOS 26, macOS 26, tvOS 26, *) {
+            content.glassEffect(glass, in: shape)
+        } else {
+            content.background { shape.fill(.ultraThinMaterial).environment(\.colorScheme, .dark) }
+        }
+    }
+
+    @available(iOS 26, macOS 26, tvOS 26, *)
+    private var glass: Glass {
+        var g: Glass = .regular
+        if let tint { g = g.tint(tint) }
+        if interactive { g = g.interactive() }
+        return g
+    }
+}
+
+extension View {
+    /// Liquid Glass for a dark console surface (a host tile / settings row), or `.ultraThinMaterial`
+    /// (forced dark) pre-26. Pass the surface's shape explicitly — glass defaults to a Capsule.
+    func consoleGlass<S: Shape>(_ shape: S, tint: Color? = nil, interactive: Bool = false) -> some View {
+        modifier(ConsoleGlass(shape: shape, tint: tint, interactive: interactive))
+    }
+}

clients/apple/Sources/PunktfunkClient/Trust/PairSheet.swift

@@ -103,7 +103,7 @@ struct PairSheet: View {
                     TextField(
                         "PIN", text: $pin,
                         prompt: Text("Shown in the host's web console"))
-                        .font(.system(.title3, design: .monospaced))
+                        .font(.geistFixed(16)) // prominent, but on-brand mono (not oversized title3)
                         #if os(iOS)
                         .keyboardType(.numberPad)
                         #endif
@@ -134,6 +134,11 @@ struct PairSheet: View {
             }
             #if !os(tvOS)
         .formStyle(.grouped)
+        // Bring the grouped form's default system text down to the app's Geist scale so the sheet
+        // doesn't read oversized / out of place (matches AddHostSheet). The PIN field keeps its own
+        // explicit Geist Mono font.
+        .font(.geist(12, relativeTo: .callout))
+        .controlSize(.small)
         #endif
             HStack {
                 Button("Cancel", role: .cancel) {

clients/probe/src/main.rs

@@ -73,6 +73,14 @@ struct Args {
     /// `--rich-input-test` — drive the DualSense touchpad + motion over 0xCC (host needs
     /// `PUNKTFUNK_GAMEPAD=dualsense`); also logs the 0xCD HID-output feedback that comes back.
     rich_input_test: bool,
+    /// `--quit` — close the connection with the deliberate-quit code (`QUIT_CLOSE_CODE`) at end of
+    /// stream, so the host tears its virtual display down immediately (skips keep-alive linger). A
+    /// bare exit closes with code 0 → the host lingers for a reconnect. Tests the #2 quit path.
+    quit: bool,
+    /// `--seconds N` — cap the receive loop at N seconds, then end the session gracefully (reach the
+    /// `conn.close`). Without it the loop runs to the 120s cap. Lets a test bound a live-host stream so
+    /// the client-initiated close (with/without `--quit`) fires promptly.
+    seconds: Option<u64>,
     pin: Option<[u8; 32]>,
     /// `--remode WxHxFPS:SECS` — request this mode SECS seconds into the stream.
     remode: Option<(Mode, u32)>,
@@ -211,6 +219,8 @@ fn parse_args() -> Args {
         mic_burst: argv.iter().any(|a| a == "--mic-burst"),
         touch_test: argv.iter().any(|a| a == "--touch-test"),
         rich_input_test: argv.iter().any(|a| a == "--rich-input-test"),
+        quit: argv.iter().any(|a| a == "--quit"),
+        seconds: get("--seconds").and_then(|s| s.parse().ok()),
         pin,
         remode,
         pair: get("--pair").map(String::from),
@@ -1041,6 +1051,9 @@ async fn session(args: Args) -> Result<()> {
         let mut net_us_v: Vec<u64> = Vec::new();
         let mut last_rx = std::time::Instant::now();
         let started = std::time::Instant::now();
+        // Stream-duration cap: `--seconds N`, else the 120s default. Ending the loop here reaches the
+        // graceful `conn.close` below (with the deliberate-quit code if `--quit`).
+        let cap_secs = args.seconds.unwrap_or(120);
         // Adaptive-FEC loss window: publish a fresh estimate every 750 ms for the LossReport task.
         let mut last_loss_report = std::time::Instant::now();
         let (mut last_recovered, mut last_received, mut last_dropped) = (0u64, 0u64, 0u64);
@@ -1076,8 +1089,8 @@ async fn session(args: Args) -> Result<()> {
             {
                 break;
             }
-            if started.elapsed() > std::time::Duration::from_secs(120)
-                || last_rx.elapsed() > std::time::Duration::from_secs(8)
+            if started.elapsed() > std::time::Duration::from_secs(cap_secs)
+                || last_rx.elapsed() > std::time::Duration::from_secs(45)
             {
                 break;
             }
@@ -1208,7 +1221,18 @@ async fn session(args: Args) -> Result<()> {
         }
     }
 
-    conn.close(0u32.into(), b"done");
+    // `--quit` closes with the deliberate-quit code so the host skips the keep-alive linger; a normal
+    // exit uses code 0 (an unwanted-disconnect close → the host lingers for a reconnect).
+    let close_code = if args.quit {
+        punktfunk_core::quic::QUIT_CLOSE_CODE
+    } else {
+        0
+    };
+    conn.close(close_code.into(), b"done");
+    // Flush the CONNECTION_CLOSE frame before we exit: without this the process can drop the endpoint
+    // before quinn sends the close, so the host waits out the idle timeout instead of seeing the close
+    // CODE promptly (deliberate-quit vs. code 0). Bounded so a stuck flush can't hang the probe.
+    let _ = tokio::time::timeout(std::time::Duration::from_secs(2), ep.wait_idle()).await;
     result
 }
 

crates/punktfunk-core/src/client.rs

@@ -179,6 +179,10 @@ pub struct NativeClient {
     /// Speed-test accumulator, shared with the data-plane pump + control task.
     probe: Arc<Mutex<ProbeState>>,
     shutdown: Arc<AtomicBool>,
+    /// Deliberate-quit flag: [`NativeClient::disconnect_quit`] sets it, so the worker closes the QUIC
+    /// connection with [`crate::quic::QUIT_CLOSE_CODE`] (a user "stop") instead of code 0 — telling the
+    /// host to skip the keep-alive linger. A plain drop leaves it false → an unwanted-disconnect close.
+    quit: Arc<AtomicBool>,
     /// Cumulative count of access units the reassembler gave up on (FEC couldn't recover), mirrored
     /// from the data-plane pump's `Session`. A client video loop watches this for increases to request
     /// a recovery keyframe under infinite GOP — the correct loss trigger, since unrecoverable loss
@@ -331,6 +335,7 @@ impl NativeClient {
         let (ctrl_tx, ctrl_rx) = tokio::sync::mpsc::unbounded_channel::<CtrlRequest>();
         let (ready_tx, ready_rx) = std::sync::mpsc::channel::<Result<Negotiated>>();
         let shutdown = Arc::new(AtomicBool::new(false));
+        let quit = Arc::new(AtomicBool::new(false));
         let mode_slot = Arc::new(std::sync::Mutex::new(mode));
         let probe = Arc::new(Mutex::new(ProbeState::default()));
         let frames_dropped = Arc::new(AtomicU64::new(0));
@@ -338,6 +343,7 @@ impl NativeClient {
 
         let host = host.to_string();
         let shutdown_w = shutdown.clone();
+        let quit_w = quit.clone();
         let mode_slot_w = mode_slot.clone();
         let probe_w = probe.clone();
         let frames_dropped_w = frames_dropped.clone();
@@ -388,6 +394,7 @@ impl NativeClient {
                     ctrl_tx: ctrl_tx_pump,
                     ready_tx,
                     shutdown: shutdown_w,
+                    quit: quit_w,
                     mode_slot: mode_slot_w,
                     probe: probe_w,
                     frames_dropped: frames_dropped_w,
@@ -430,6 +437,7 @@ impl NativeClient {
             ctrl_tx,
             probe,
             shutdown,
+            quit,
             worker: Some(worker),
             frames_dropped,
             hot_tids,
@@ -764,6 +772,15 @@ impl NativeClient {
             .send(rich)
             .map_err(|_| PunktfunkError::Closed)
     }
+
+    /// Signal a **deliberate quit** (a user "stop", not a network drop): the worker closes the QUIC
+    /// connection with [`crate::quic::QUIT_CLOSE_CODE`] instead of code 0, so the host tears the
+    /// session's virtual display down immediately and skips the keep-alive linger. Then requests
+    /// shutdown. A plain `drop` (without this) closes with code 0 → the host lingers for a reconnect.
+    pub fn disconnect_quit(&self) {
+        self.quit.store(true, Ordering::SeqCst);
+        self.shutdown.store(true, Ordering::SeqCst);
+    }
 }
 
 impl Drop for NativeClient {
@@ -802,6 +819,8 @@ struct WorkerArgs {
     ctrl_tx: tokio::sync::mpsc::UnboundedSender<CtrlRequest>,
     ready_tx: std::sync::mpsc::Sender<Result<Negotiated>>,
     shutdown: Arc<AtomicBool>,
+    /// Deliberate-quit flag (see [`NativeClient::quit`]): the worker closes with the quit code if set.
+    quit: Arc<AtomicBool>,
     mode_slot: Arc<std::sync::Mutex<Mode>>,
     probe: Arc<Mutex<ProbeState>>,
     frames_dropped: Arc<AtomicU64>,
@@ -838,6 +857,7 @@ async fn worker_main(args: WorkerArgs) {
         ctrl_tx,
         ready_tx,
         shutdown,
+        quit,
         mode_slot,
         probe,
         frames_dropped,
@@ -1210,5 +1230,12 @@ async fn worker_main(args: WorkerArgs) {
     })
     .await;
 
-    conn.close(0u32.into(), b"client closed");
+    // Deliberate quit (a user "stop") closes with the quit code → the host skips the keep-alive
+    // linger; a plain drop / disconnect closes with 0 → the host lingers so a reconnect can resume.
+    let close_code = if quit.load(Ordering::SeqCst) {
+        crate::quic::QUIT_CLOSE_CODE
+    } else {
+        0
+    };
+    conn.close(close_code.into(), b"client closed");
 }

crates/punktfunk-core/src/quic.rs

@@ -122,6 +122,21 @@ pub const VIDEO_CAP_444: u8 = 0x04;
 /// stage. Purely observability — never changes what the host encodes.
 pub const VIDEO_CAP_HOST_TIMING: u8 = 0x08;
 
+/// QUIC application error code a punktfunk/1 client closes the control connection with on a
+/// **deliberate quit** (a user "stop", not a network drop). The host reads it off the connection's
+/// `ApplicationClosed` reason and tears the session's virtual display down immediately, skipping the
+/// keep-alive linger; any other close reason (idle timeout, reset, a bare code 0) still lingers so a
+/// reconnect can resume. Shared so host + every client agree on the code.
+pub const QUIT_CLOSE_CODE: u32 = 0x51;
+
+/// QUIC application error code the **host** closes the control connection with when a **dedicated game
+/// session's game process exits** (the nested gamescope died — the user quit the game), so a launcher
+/// client can distinguish "the game ended" from an error and return to its library cleanly rather than
+/// surfacing a failure (`design/gamemode-and-dedicated-sessions.md` §5.3). Sibling of
+/// [`QUIT_CLOSE_CODE`]; a client that doesn't special-case it still ends the session (every client
+/// returns to its launcher on session end), so it is purely refinement. Shared so host + clients agree.
+pub const APP_EXITED_CLOSE_CODE: u32 = 0x52;
+
 /// [`Hello::video_codecs`] bit: the client can decode H.264 / AVC. The GPU-less **software**
 /// encode path (openh264) emits H.264, so a client that wants to stream from a software host MUST
 /// advertise this.
@@ -1743,20 +1758,31 @@ pub mod endpoint {
     /// every `KEEP_ALIVE` keeps the path warm. The interval sits well under `MAX_IDLE` so
     /// several keepalives can be lost back-to-back (a wifi roam, a brief blip) without a false
     /// close, while a genuinely dead peer is still detected within `MAX_IDLE`.
+    /// The default control-connection idle timeout (disconnect-detection latency). A vanished client
+    /// is declared dead within this window — the Windows IDD-push path needs it short so a RECONNECT
+    /// recreates a fresh virtual monitor instead of joining the still-lingering old session; the Linux
+    /// path pairs it with the same-client reconnect preempt. Host-tunable via `server_with_identity_idle`.
+    pub const DEFAULT_IDLE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(8);
+
     fn stream_transport() -> Arc<quinn::TransportConfig> {
+        stream_transport_idle(DEFAULT_IDLE_TIMEOUT)
+    }
+
+    /// Transport config with a caller-chosen idle timeout (disconnect-detection latency). The
+    /// keep-alive interval tracks it at half the idle window (capped at the default 4s), so a live
+    /// path is PINGed at least twice per window and a single lost PING (wifi roam / brief blip) won't
+    /// false-close. `idle` is clamped to a ≥1s floor so a misconfigured tiny value can't tear live
+    /// sessions down. Active sessions are unaffected either way: video keeps the connection live and
+    /// the keep-alive holds it open through quiet control periods.
+    fn stream_transport_idle(idle: std::time::Duration) -> Arc<quinn::TransportConfig> {
         use std::time::Duration;
-        // 8s idle (was 20s): a vanished client is declared dead within 8s instead of 20, so its
-        // session tears down promptly — which the Windows IDD-push path needs so a RECONNECT recreates
-        // a fresh virtual monitor (a reused monitor's IddCx swap-chain dies) instead of joining the
-        // still-lingering old session. Active sessions are unaffected: video keeps the connection live,
-        // and the 4s keep-alive holds it open through quiet control periods.
-        const MAX_IDLE: Duration = Duration::from_secs(8);
-        const KEEP_ALIVE: Duration = Duration::from_secs(4);
+        let idle = idle.max(Duration::from_secs(1));
+        let keep_alive = (idle / 2).min(Duration::from_secs(4));
         let mut t = quinn::TransportConfig::default();
         t.max_idle_timeout(Some(
-            quinn::IdleTimeout::try_from(MAX_IDLE).expect("8s is a valid QUIC idle timeout"),
+            quinn::IdleTimeout::try_from(idle).expect("clamped idle timeout is a valid QUIC value"),
         ));
-        t.keep_alive_interval(Some(KEEP_ALIVE));
+        t.keep_alive_interval(Some(keep_alive));
         Arc::new(t)
     }
 
@@ -1767,23 +1793,36 @@ pub mod endpoint {
             .map_err(|e| anyhow_result::Error::msg(format!("self-signed cert: {e}")))?;
         let cert_der = rustls::pki_types::CertificateDer::from(cert.cert);
         let key_der = rustls::pki_types::PrivatePkcs8KeyDer::from(cert.key_pair.serialize_der());
-        server_from_der(cert_der, key_der.into(), addr)
+        server_from_der(cert_der, key_der.into(), addr, DEFAULT_IDLE_TIMEOUT)
     }
 
     /// Server endpoint from a persisted PEM identity (certificate + PKCS#8 private key) —
     /// the host's long-lived self-signed cert, so the fingerprint clients pin is stable
-    /// across restarts.
+    /// across restarts. Uses the [`DEFAULT_IDLE_TIMEOUT`]; see [`server_with_identity_idle`] to tune it.
     pub fn server_with_identity(
         addr: std::net::SocketAddr,
         cert_pem: &str,
         key_pem: &str,
+    ) -> anyhow_result::Result<quinn::Endpoint> {
+        server_with_identity_idle(addr, cert_pem, key_pem, DEFAULT_IDLE_TIMEOUT)
+    }
+
+    /// Like [`server_with_identity`] but with a host-chosen control-connection idle timeout — the
+    /// disconnect-detection latency (how long a vanished client takes to be declared dead). Shorter =
+    /// faster teardown/linger of a dropped session; the value is clamped to a ≥1s floor and its
+    /// keep-alive scales with it so a live session never false-closes.
+    pub fn server_with_identity_idle(
+        addr: std::net::SocketAddr,
+        cert_pem: &str,
+        key_pem: &str,
+        idle: std::time::Duration,
     ) -> anyhow_result::Result<quinn::Endpoint> {
         use rustls::pki_types::pem::PemObject;
         let cert_der = rustls::pki_types::CertificateDer::from_pem_slice(cert_pem.as_bytes())
             .map_err(|e| anyhow_result::Error::msg(format!("cert pem: {e}")))?;
         let key_der = rustls::pki_types::PrivateKeyDer::from_pem_slice(key_pem.as_bytes())
             .map_err(|e| anyhow_result::Error::msg(format!("key pem: {e}")))?;
-        server_from_der(cert_der, key_der, addr)
+        server_from_der(cert_der, key_der, addr, idle)
     }
 
     /// Fixed ALPN for the punktfunk/1 QUIC handshake. Pinning it rejects a cross-protocol peer at the
@@ -1796,6 +1835,7 @@ pub mod endpoint {
         cert_der: rustls::pki_types::CertificateDer<'static>,
         key_der: rustls::pki_types::PrivateKeyDer<'static>,
         addr: std::net::SocketAddr,
+        idle: std::time::Duration,
     ) -> anyhow_result::Result<quinn::Endpoint> {
         let _ = rustls::crypto::ring::default_provider().install_default();
         // Client auth is OFFERED but optional: a client that presents its self-signed
@@ -1810,7 +1850,7 @@ pub mod endpoint {
         let quic_cfg = quinn::crypto::rustls::QuicServerConfig::try_from(rustls_cfg)
             .map_err(|e| anyhow_result::Error::msg(format!("quic server config: {e}")))?;
         let mut server_config = quinn::ServerConfig::with_crypto(Arc::new(quic_cfg));
-        server_config.transport_config(stream_transport()); // keep-alive — see stream_transport
+        server_config.transport_config(stream_transport_idle(idle)); // keep-alive — see stream_transport_idle
         Ok(quinn::Endpoint::server(server_config, addr)?)
     }
 

crates/punktfunk-core/src/transport/qos.rs

@@ -66,12 +66,18 @@ impl MediaClass {
     }
 }
 
-/// Whether DSCP/QoS marking is enabled (`PUNKTFUNK_DSCP=1`). Off by default.
+/// Whether DSCP/QoS marking is enabled. Default **on for Android**, **off elsewhere**: on Wi-Fi
+/// (where most Android clients live) access points commonly map DSCP to WMM access categories, so
+/// tagging the video/audio sockets can win real airtime priority against other traffic on the link;
+/// on the wired paths the other clients use it's rarely honoured and some paths bleach or reject
+/// marked packets, so it stays opt-in there. `PUNKTFUNK_DSCP` overrides either way — `1`/`true`/`on`
+/// forces it on, `0`/`false`/`off` forces it off (e.g. to rule QoS out while debugging a flaky AP).
 pub(crate) fn dscp_enabled() -> bool {
-    matches!(
-        std::env::var("PUNKTFUNK_DSCP").as_deref(),
-        Ok("1") | Ok("true") | Ok("on")
-    )
+    match std::env::var("PUNKTFUNK_DSCP").as_deref() {
+        Ok("1") | Ok("true") | Ok("on") => true,
+        Ok("0") | Ok("false") | Ok("off") => false,
+        _ => cfg!(target_os = "android"),
+    }
 }
 
 /// Best-effort: tag `socket`'s outgoing packets for prioritized delivery of its media class. A no-op

crates/punktfunk-core/src/transport/udp.rs

@@ -416,7 +416,14 @@ impl UdpTransport {
     /// Bind `local` and `connect` to `peer`, so `send`/`recv` need no address and the
     /// kernel filters to this peer. Non-blocking, matching the [`Transport`] contract.
     pub fn connect(local: &str, peer: &str) -> std::io::Result<Self> {
-        let socket = UdpSocket::bind(local)?;
+        Self::from_socket(UdpSocket::bind(local)?, peer)
+    }
+
+    /// Adopt an already-bound socket for the data plane: `connect` it to `peer`, tune buffers +
+    /// QoS, go non-blocking. Lets the host bind the data port up front (e.g. a fixed `--data-port`)
+    /// and keep the *same* socket from handshake through streaming — no drop-then-rebind window in
+    /// which a concurrent session could steal a fixed port.
+    pub fn from_socket(socket: UdpSocket, peer: &str) -> std::io::Result<Self> {
         socket.connect(peer)?;
         super::qos::grow_socket_buffers(&socket);
         // The native data plane is video-dominant — tag it as the video class (opt-in via
@@ -438,7 +445,16 @@ impl UdpTransport {
         fallback_peer: &str,
         punch_timeout: std::time::Duration,
     ) -> std::io::Result<(Self, bool)> {
-        let socket = UdpSocket::bind(local)?;
+        Self::from_socket_punch(UdpSocket::bind(local)?, fallback_peer, punch_timeout)
+    }
+
+    /// [`connect_via_punch`](Self::connect_via_punch) on an already-bound socket — see
+    /// [`from_socket`](Self::from_socket) for why the host binds the data port up front.
+    pub fn from_socket_punch(
+        socket: UdpSocket,
+        fallback_peer: &str,
+        punch_timeout: std::time::Duration,
+    ) -> std::io::Result<(Self, bool)> {
         socket.set_read_timeout(Some(punch_timeout))?;
         let deadline = std::time::Instant::now() + punch_timeout;
         let mut buf = [0u8; 64];

crates/punktfunk-host/README.md

@@ -20,8 +20,9 @@ platform-facing around it.
 - **Per-client virtual displays at the exact WxH@Hz.** Linux uses per-compositor backends — **KWin**,
   **gamescope**, **Mutter**, and **Sway/wlroots**; Windows uses its own all-Rust IddCx virtual display,
   even on the secure desktop (UAC / lock screen).
-- **GPU zero-copy capture → encode.** dmabuf → CUDA/Vulkan → NVENC on Linux; DXGI/WGC → GPU encode on
-  Windows. Encoders auto-select by GPU vendor: **NVENC** (NVIDIA), **VAAPI** (Linux AMD/Intel),
+- **GPU zero-copy capture → encode.** dmabuf → CUDA/Vulkan → NVENC on Linux; on Windows the host
+  pushes frames straight into its own IDD (sealed IDD-push, no screen-scraping) → GPU encode.
+  Encoders auto-select by GPU vendor: **NVENC** (NVIDIA), **VAAPI** (Linux AMD/Intel),
   **AMF/QSV** (Windows AMD/Intel), or software H.264 as a floor. HDR/10-bit and HEVC 4:4:4 supported.
 - **Input injection.** Mouse/keyboard (libei / gamescope EIS / wlr / Windows SendInput) and virtual
   **gamepads** — Xbox 360/One, DualSense, DualShock 4 — with rumble and HID feedback back-channels.
@@ -70,7 +71,7 @@ src/
   main.rs            CLI + subcommand dispatch
   config.rs · session_plan.rs · session_tuning.rs · pipeline.rs   session setup + the frame pipeline
   vdisplay/          per-compositor virtual outputs (kwin · gamescope · mutter · wlroots)
-  capture/ · capture.rs    screen/dmabuf capture (+ Windows DXGI/WGC)
+  capture/ · capture.rs    screen/dmabuf capture (+ Windows IDD-push)
   encode/ · encode.rs      per-GPU encoders (nvenc · vaapi · ffmpeg_win (AMF/QSV) · sw)
   zerocopy/          dmabuf → CUDA → NVENC bridges (EGL/GL tiled, Vulkan LINEAR)
   inject/ · inject.rs      input backends (libei · wlr · uinput gamepads · UHID DualSense/DS4)

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

@@ -274,7 +274,10 @@ mod tests {
         );
         // No pretty-print newlines anywhere in the element stream, and no whitespace-only text
         // nodes between any adjacent tags.
-        assert!(!xml.contains('\n'), "applist must contain no newlines: {xml}");
+        assert!(
+            !xml.contains('\n'),
+            "applist must contain no newlines: {xml}"
+        );
         assert!(
             !xml.contains("> <"),
             "applist must contain no inter-element spaces: {xml}"

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

@@ -132,9 +132,9 @@ async fn h_launch(
         return xml(error_xml()).into_response();
     }
     let req_fp: Option<[u8; 32]> = match &peer {
-        Some(Extension(PeerCertFingerprint(Some(fp)))) => {
-            hex::decode(fp).ok().and_then(|v| <[u8; 32]>::try_from(v).ok())
-        }
+        Some(Extension(PeerCertFingerprint(Some(fp)))) => hex::decode(fp)
+            .ok()
+            .and_then(|v| <[u8; 32]>::try_from(v).ok()),
         _ => None,
     };
 
@@ -156,7 +156,9 @@ async fn h_launch(
             GsDecision::Serve => {}
             GsDecision::Join((w, h, f)) => {
                 forced_mode = Some((w, h, f));
-                tracing::info!("GameStream launch JOIN — admitting at the live session's mode {w}x{h}@{f}");
+                tracing::info!(
+                    "GameStream launch JOIN — admitting at the live session's mode {w}x{h}@{f}"
+                );
             }
             GsDecision::Reject => {
                 tracing::warn!(

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

@@ -246,14 +246,33 @@ fn open_gs_virtual_source(
         }
         #[cfg(not(target_os = "windows"))]
         {
+            // A client is (re)connecting → cancel any pending TV-session restore (review #3).
+            crate::vdisplay::cancel_pending_tv_restore();
             let active = crate::vdisplay::detect_active_session();
+            // A4: fold any compositor-instance change (idle-time Game↔Desktop switch) into the epoch
+            // before acquiring, so a GameStream reconnect never reuses a dead-instance node.
+            crate::vdisplay::observe_session_instance(&active);
             crate::vdisplay::apply_session_env(&active);
-            let c = crate::vdisplay::compositor_for_kind(active.kind)
-                .map(Ok)
-                .unwrap_or_else(crate::vdisplay::detect)
-                .context("detect compositor")?;
-            crate::vdisplay::apply_input_env(c);
-            c
+            // Dedicated game session (B0): a GameStream app whose launch RESOLVES to a command (library
+            // id / apps.json command), under `game_session=dedicated` with gamescope available, gets its
+            // own headless gamescope spawn at the client mode — same routing as the native plane. Gate on
+            // the resolved command so an unresolvable entry falls back to auto routing (review #9).
+            let has_launch = crate::library::resolve_session_launch(
+                app.and_then(|a| a.library_id.as_deref()),
+                app.and_then(|a| a.cmd.as_deref()),
+            )
+            .is_some();
+            if crate::vdisplay::wants_dedicated_game_session(has_launch) {
+                crate::vdisplay::apply_input_env(crate::vdisplay::Compositor::Gamescope, true);
+                crate::vdisplay::Compositor::Gamescope
+            } else {
+                let c = crate::vdisplay::compositor_for_kind(active.kind)
+                    .map(Ok)
+                    .unwrap_or_else(crate::vdisplay::detect)
+                    .context("detect compositor")?;
+                crate::vdisplay::apply_input_env(c, false);
+                c
+            }
         }
     };
     let mut vd = crate::vdisplay::open(compositor).context("open virtual display")?;
@@ -293,6 +312,10 @@ fn open_gs_virtual_source(
             height: cfg.height,
             refresh_hz: cfg.fps,
         },
+        // GameStream's deliberate quit is the Moonlight "Quit App" (nvhttp `h_cancel`), not a QUIC
+        // close code — wiring it to skip-linger is a follow-up, so this path keeps normal keep-alive
+        // (a fresh, never-set flag).
+        std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false)),
     )
     .context("create virtual output at client resolution")?;
     // HDR: pass the negotiated `cfg.hdr` (client asked for HDR AND the host can deliver it). On the
@@ -413,6 +436,54 @@ fn pace_layout(n: usize) -> (usize, usize) {
     (chunk_sz, steps)
 }
 
+/// One encoded frame handed from the encode loop to the packetizer thread: the frame's access
+/// units (owned buffers, each with its frame type) plus the shared 90 kHz RTP timestamp. FEC
+/// packetization runs on the packetizer thread — off the encode loop — so it never serializes
+/// behind encode (measured ~3 ms/frame at 4K, which capped GameStream's frame rate well below what
+/// the encoder alone can sustain).
+struct RawFrame {
+    aus: Vec<(Vec<u8>, FrameType)>,
+    ts: u32,
+}
+
+/// Packetizer thread: turns each [`RawFrame`]'s access units into wire datagrams (data + Reed–Solomon
+/// FEC parity shards) via the stateful [`VideoPacketizer`], then hands the batch to the paced sender.
+/// It sits between encode and send so the FEC never blocks the encode loop. Backpressure: the hand-off
+/// to the sender BLOCKS, so if the paced sender falls behind, the packetizer stalls and the
+/// encode→packetizer queue fills — the encode loop then drops the newest frame (see the loop) rather
+/// than stalling. Tallies goodput (bytes handed to the wire) into `goodput` for the encode loop's stats
+/// window. Exits when either neighbor's channel closes (session teardown / client gone).
+fn spawn_packetizer(
+    rx: std::sync::mpsc::Receiver<RawFrame>,
+    tx: std::sync::mpsc::SyncSender<PacketBatch>,
+    mut pk: VideoPacketizer,
+    goodput: Arc<std::sync::atomic::AtomicU64>,
+) -> Result<()> {
+    std::thread::Builder::new()
+        .name("punktfunk-pkt".into())
+        .spawn(move || {
+            // Above-normal, like the send thread — this stage is on the per-frame critical path.
+            crate::punktfunk1::boost_thread_priority(false);
+            while let Ok(frame) = rx.recv() {
+                let mut batch: PacketBatch = Vec::new();
+                for (au, ft) in frame.aus {
+                    batch.extend(pk.packetize(&au, ft, frame.ts));
+                }
+                if batch.is_empty() {
+                    continue;
+                }
+                let bytes: u64 = batch.iter().map(|p| p.len() as u64).sum();
+                // Blocking send: propagates the paced sender's backpressure upstream (see above).
+                if tx.send(batch).is_err() {
+                    break; // sender exited (client gone)
+                }
+                goodput.fetch_add(bytes, std::sync::atomic::Ordering::Relaxed);
+            }
+        })
+        .context("spawn packetizer thread")?;
+    Ok(())
+}
+
 /// Dedicated send thread: one [`PacketBatch`] per frame arrives on `rx`; its packets go out in
 /// `sendmmsg` chunks, paced so the frame's data spreads over ~3/4 of the frame interval
 /// (microburst shaping at chunk granularity — a real link drops line-rate bursts; the encode
@@ -544,7 +615,7 @@ fn stream_body(
         .ok()
         .and_then(|v| v.parse().ok())
         .unwrap_or(20);
-    let mut pk = VideoPacketizer::new(cfg.packet_size, fec_pct, cfg.min_fec);
+    let pk = VideoPacketizer::new(cfg.packet_size, fec_pct, cfg.min_fec);
 
     // Pace at the client's negotiated frame rate, re-encoding the last captured frame when the
     // compositor produced no new one. Compositors only emit frames on damage, so a static or
@@ -564,9 +635,15 @@ fn stream_body(
     let mut sent_batches: u64 = 0;
     let mut dropped_batches: u64 = 0;
 
-    // The send thread: one frame's batch at a time over a small bounded queue. Depth 2 means a
-    // slow send can buffer one frame while the next encodes; beyond that the NEWEST batch is
-    // dropped (the client recovers via FEC/RFI) rather than ever stalling the encode loop.
+    // Three-stage pipeline so FEC packetization never blocks encode: `encode loop → [raw AUs] →
+    // packetizer (FEC/RS) → [wire batch] → paced sender`, each stage on its own thread joined by a
+    // depth-2 bounded queue. Depth 2 means a slow stage can buffer one frame while the next is
+    // produced; beyond that the NEWEST frame is dropped (the client recovers via FEC/RFI) rather than
+    // stalling the encode loop. Backpressure chains up: a slow sender blocks the packetizer, which
+    // fills the encode→packetizer queue, which makes the encode loop drop — encode itself never
+    // waits. Goodput (bytes handed to the wire) is tallied by the packetizer into `goodput`, read at
+    // the encode loop's 1 s stats boundary (the old inline batch-byte sum moved with packetization).
+    let goodput = Arc::new(std::sync::atomic::AtomicU64::new(0));
     let (batch_tx, batch_rx) = std::sync::mpsc::sync_channel::<PacketBatch>(2);
     spawn_sender(
         sock.try_clone().context("clone video socket")?,
@@ -575,12 +652,14 @@ fn stream_body(
         running.clone(),
         drop_pct,
     )?;
+    let (raw_tx, raw_rx) = std::sync::mpsc::sync_channel::<RawFrame>(2);
+    spawn_packetizer(raw_rx, batch_tx, pk, goodput.clone())?;
 
     // Per-stage timing (PUNKTFUNK_PERF=1): max µs/stage per second + unique vs re-encoded frames,
     // to pinpoint stalls. `unique` counts genuinely-new captured frames (vs re-encoded holds).
     let perf = crate::config::config().perf;
-    let (mut mx_cap, mut mx_enc, mut mx_pkt, mut mx_send, mut mx_pkts, mut uniq) =
-        (0u128, 0u128, 0u128, 0u128, 0usize, 0u32);
+    let (mut mx_cap, mut mx_enc, mut mx_pkt, mut mx_send, mut uniq) =
+        (0u128, 0u128, 0u128, 0u128, 0u32);
     // Web-console stats accumulation (active when `perf` OR a capture is armed): per-stage vectors
     // for p50/p99, the goodput bytes queued to the sender this window, the previous window's
     // dropped-frame count for delta computation, and the registration id cached on the first sample.
@@ -592,7 +671,6 @@ fn stream_body(
     let mut sid: Option<u32> = None;
     let (mut v_cap, mut v_enc, mut v_pkt, mut v_send): (Vec<u32>, Vec<u32>, Vec<u32>, Vec<u32>) =
         (Vec::new(), Vec::new(), Vec::new(), Vec::new());
-    let mut bytes_win: u64 = 0;
     let mut last_dropped_batches: u64 = 0;
     // Absolute next-frame deadline — the single pacing clock for the loop.
     let mut next_frame = Instant::now();
@@ -614,6 +692,13 @@ fn stream_body(
     // ref-invalidation (cheap, no IDR spike) is never rate-limited — only full keyframes are.
     let keyframe_coalesce = frame_interval * 2;
     let mut last_keyframe: Option<Instant> = None;
+    // A frame dropped at the pipeline head (below) breaks the reference chain for the following
+    // P-frames: the client never receives it, but the encoder advanced its references past it, and —
+    // packetization being downstream now — a dropped frame consumes no frameIndex for the client to
+    // detect the gap. So the host re-anchors itself: a drop arms a keyframe on the next iteration,
+    // routed through the same coalesce gate as client IDR requests so a burst of drops (congestion)
+    // can't become an IDR storm.
+    let mut recover_after_drop = false;
 
     while running.load(Ordering::SeqCst) {
         let tick = Instant::now();
@@ -690,7 +775,9 @@ fn stream_body(
         // Honor a client recovery request. Prefer reference-frame invalidation (the encoder
         // re-references an older still-valid frame — no costly IDR spike); if the encoder can't
         // invalidate (range too old, or no NVENC RFI) it returns false and we force a keyframe.
-        let mut want_keyframe = false;
+        // A prior pipeline drop needs a fresh keyframe to re-anchor the reference chain (see below).
+        let mut want_keyframe = recover_after_drop;
+        recover_after_drop = false;
         if let Some((first, last)) = rfi_range.lock().unwrap().take() {
             // Prefer reference-frame invalidation when the encoder supports it (no costly IDR
             // spike); otherwise — or if the range is too old to invalidate — fall back to a keyframe.
@@ -723,41 +810,39 @@ fn stream_body(
 
         // 90 kHz RTP timestamp from wall-clock, so a variable capture rate stays correct.
         let ts = (stream_start.elapsed().as_secs_f64() * 90_000.0) as u32;
-        let mut batch: Vec<Vec<u8>> = Vec::new();
+        // Drain the encoder's access units (owned buffers) — FEC/packetization runs on the
+        // packetizer thread, off this loop, so it never serializes behind encode.
+        let mut aus: Vec<(Vec<u8>, FrameType)> = Vec::new();
         while let Some(au) = enc.poll().context("encoder poll")? {
             let ft = if au.keyframe {
                 FrameType::Idr
             } else {
                 FrameType::P
             };
-            batch.extend(pk.packetize(&au.data, ft, ts));
+            aus.push((au.data, ft));
         }
         let t_pkt = tick.elapsed();
 
-        // Hand the frame's packets to the send thread; never block here. A full queue means
-        // the sender is behind — drop this batch (FEC/RFI covers the client) and keep encoding.
-        let n = batch.len();
-        // Goodput this window = bytes actually queued to the sender (a dropped batch never reaches
-        // the wire, so it's excluded). Summed only when measuring, to keep the idle path free.
-        let batch_bytes: u64 = if measure {
-            batch.iter().map(|p| p.len() as u64).sum()
-        } else {
-            0
-        };
-        if n > 0 {
-            match batch_tx.try_send(batch) {
+        // Hand the frame's AUs to the pipeline; never block here. A full queue means the pipeline
+        // (packetizer, or the paced sender behind it) is behind — drop this frame (FEC/RFI covers the
+        // client) and keep encoding, so a downstream stall can never cap the encode rate.
+        if !aus.is_empty() {
+            match raw_tx.try_send(RawFrame { aus, ts }) {
                 Ok(()) => {
                     sent_batches += 1;
-                    bytes_win += batch_bytes;
                 }
                 Err(std::sync::mpsc::TrySendError::Full(_)) => {
                     dropped_batches += 1;
+                    recover_after_drop = true; // re-anchor the reference chain on the next frame
                     if dropped_batches.is_power_of_two() {
-                        tracing::warn!(dropped_batches, "video: send queue full — frame dropped");
+                        tracing::warn!(
+                            dropped_batches,
+                            "video: pipeline queue full — frame dropped"
+                        );
                     }
                 }
                 Err(std::sync::mpsc::TrySendError::Disconnected(_)) => {
-                    break; // sender exited (client gone)
+                    break; // packetizer/sender exited (client gone)
                 }
             }
         }
@@ -765,26 +850,33 @@ fn stream_body(
             let t_send = tick.elapsed();
             let cap_us = t_cap.as_micros();
             let enc_us = (t_enc - t_cap).as_micros();
-            let pkt_us = (t_pkt - t_enc).as_micros();
-            let send_us = (t_send - t_pkt).as_micros();
+            // `poll` = drain the encoder's AUs; `enqueue` = hand-off to the pipeline. FEC/packetize
+            // and the paced send now run on their own threads, off this loop — so both of these
+            // should be small; if they aren't, the encode loop is being stalled by pipeline
+            // backpressure (a full queue), which is the signal that a downstream stage can't keep up.
+            let poll_us = (t_pkt - t_enc).as_micros();
+            let enqueue_us = (t_send - t_pkt).as_micros();
             mx_cap = mx_cap.max(cap_us);
             mx_enc = mx_enc.max(enc_us);
-            mx_pkt = mx_pkt.max(pkt_us);
-            mx_send = mx_send.max(send_us);
-            mx_pkts = mx_pkts.max(n);
+            mx_pkt = mx_pkt.max(poll_us);
+            mx_send = mx_send.max(enqueue_us);
             v_cap.push(cap_us as u32);
             v_enc.push(enc_us as u32);
-            v_pkt.push(pkt_us as u32);
-            v_send.push(send_us as u32);
+            v_pkt.push(poll_us as u32);
+            v_send.push(enqueue_us as u32);
         }
 
         fps_count += 1;
         if fps_t.elapsed() >= Duration::from_secs(1) {
             let secs = fps_t.elapsed().as_secs_f64();
+            // Bytes handed to the wire this window, tallied by the packetizer thread (goodput).
+            let win_bytes = goodput.swap(0, std::sync::atomic::Ordering::Relaxed);
             if perf {
-                // Max µs/stage this second: cap=drain channel, enc=submit (zero-copy device
-                // copy + NVENC), pkt=poll+FEC+packetize, send=paced packet send. `uniq`=new
-                // captured frames (vs re-encoded). `pkts`=max packets in one frame (IDR spike).
+                // Max µs/stage this second on the ENCODE loop: cap=drain channel, enc=submit
+                // (zero-copy device copy + NVENC), pkt=poll (AU drain), send=enqueue to the pipeline.
+                // FEC/packetize and the paced send run on their own threads now, so pkt/send here
+                // should be near-zero — a nonzero value means encode is being stalled by pipeline
+                // backpressure. `uniq`=new captured frames (vs re-encoded).
                 tracing::info!(
                     fps = fps_count,
                     uniq,
@@ -792,7 +884,6 @@ fn stream_body(
                     pkt_us = mx_pkt,
                     send_us = mx_send,
                     cap_us = mx_cap,
-                    max_pkts = mx_pkts,
                     "video: streaming (perf)"
                 );
             } else {
@@ -805,7 +896,7 @@ fn stream_body(
             }
             // Web-console capture: build the aggregated sample. The host send side exposes no
             // receiver-side packet loss / FEC-recovery / send-buffer EAGAIN counters, so those stay
-            // 0 (not fabricated); `frames_dropped` is the per-frame send-queue overflow delta.
+            // 0 (not fabricated); `frames_dropped` is the per-frame pipeline-queue overflow delta.
             if stats.is_armed() {
                 let session_id = *sid.get_or_insert_with(|| {
                     stats.register_session(
@@ -844,7 +935,7 @@ fn stream_body(
                     ],
                     fps: (uniq as f64 / secs) as f32,
                     repeat_fps: (fps_count.saturating_sub(uniq) as f64 / secs) as f32,
-                    mbps: (bytes_win as f64 * 8.0 / secs / 1_000_000.0) as f32,
+                    mbps: (win_bytes as f64 * 8.0 / secs / 1_000_000.0) as f32,
                     bitrate_kbps: cfg.bitrate_kbps,
                     frames_dropped: dropped_batches.saturating_sub(last_dropped_batches) as u32,
                     packets_dropped: 0,
@@ -857,13 +948,11 @@ fn stream_body(
             mx_enc = 0;
             mx_pkt = 0;
             mx_send = 0;
-            mx_pkts = 0;
             uniq = 0;
             v_cap.clear();
             v_enc.clear();
             v_pkt.clear();
             v_send.clear();
-            bytes_win = 0;
             last_dropped_batches = dropped_batches;
             fps_count = 0;
             fps_t = Instant::now();
@@ -952,8 +1041,14 @@ mod tests {
             let (chunk, steps) = pace_layout(n);
             assert!(steps >= 1, "n={n}: at least one step");
             assert!(steps <= 12, "n={n}: step count {steps} exceeded the cap");
-            assert!(chunk >= 16, "n={n}: chunk {chunk} below the 16-packet floor");
-            assert!(chunk * steps >= n, "n={n}: {chunk}×{steps} must cover all packets");
+            assert!(
+                chunk >= 16,
+                "n={n}: chunk {chunk} below the 16-packet floor"
+            );
+            assert!(
+                chunk * steps >= n,
+                "n={n}: {chunk}×{steps} must cover all packets"
+            );
         }
         // Small frames stay on the floor: one 16-packet burst.
         assert_eq!(pace_layout(1), (16, 1));

crates/punktfunk-host/src/main.rs

@@ -418,6 +418,20 @@ fn real_main() -> Result<()> {
                 allow_pairing: true,
                 pairing_pin: None,
                 paired_store: None,
+                // Fixed data-plane port: bind it and stream direct (no hole-punch), removing the
+                // ~2.5 s punch-timeout on a firewalled host. Default (absent) = a random port +
+                // hole-punch. Also honors PUNKTFUNK_DATA_PORT.
+                data_port: get("--data-port")
+                    .map(str::to_string)
+                    .or_else(|| std::env::var("PUNKTFUNK_DATA_PORT").ok())
+                    .and_then(|s| s.parse().ok()),
+                // Disconnect-detection latency (QUIC control-connection idle timeout): --idle-timeout-ms
+                // overrides PUNKTFUNK_IDLE_TIMEOUT_MS; absent = the core default (8s).
+                idle_timeout: get("--idle-timeout-ms")
+                    .and_then(|s| s.trim().parse::<u64>().ok())
+                    .filter(|&ms| ms > 0)
+                    .map(std::time::Duration::from_millis)
+                    .or_else(punktfunk1::idle_timeout_from_env),
             })
         }
         // Windows service control: install/uninstall/start/stop/status + the SCM `run` entry point.
@@ -501,6 +515,13 @@ fn input_test() -> Result<()> {
 fn parse_serve(args: &[String]) -> Result<(mgmt::Options, punktfunk1::NativeServe, bool)> {
     let mut opts = mgmt::Options::default();
     let mut native_port: u16 = 9777; // the native plane always runs now
+
+    // Fixed data-plane UDP port: `Some(p)` binds p and streams direct (no hole-punch, no ~2.5 s
+    // punch-timeout on a firewalled host); `None` (default) = a random port + hole-punch. Env
+    // default, `--data-port` overrides.
+    let mut data_port: Option<u16> = std::env::var("PUNKTFUNK_DATA_PORT")
+        .ok()
+        .and_then(|s| s.parse().ok());
     let mut open = false;
     let mut gamestream = false;
     // Did the operator pin the mgmt bind themselves? If not, we LAN-expose the read surface below so
@@ -541,6 +562,13 @@ fn parse_serve(args: &[String]) -> Result<(mgmt::Options, punktfunk1::NativeServ
                     .parse()
                     .map_err(|_| anyhow::anyhow!("bad --native-port (want a port number)"))?
             }
+            "--data-port" => {
+                data_port = Some(
+                    next()?
+                        .parse()
+                        .map_err(|_| anyhow::anyhow!("bad --data-port (want a port number)"))?,
+                )
+            }
             // Opt into the GameStream/Moonlight-compat planes (off by default — they carry the
             // inherent on-path #5/#9 weaknesses; only for a trusted LAN).
             "--gamestream" | "--moonlight" => gamestream = true,
@@ -576,6 +604,7 @@ fn parse_serve(args: &[String]) -> Result<(mgmt::Options, punktfunk1::NativeServ
         // Advertise the mgmt port over mDNS so clients learn where to browse the library (rather than
         // assuming the default). `opts.bind.port()` is the real port even if the operator moved it.
         mgmt_port: opts.bind.port(),
+        data_port,
     };
     Ok((opts, native, gamestream))
 }
@@ -703,6 +732,10 @@ SERVE OPTIONS:
                                  reuse, security-review #5/#9); enable only on a TRUSTED LAN
     --native                     no-op (the native punktfunk/1 plane always runs in `serve` now)
     --native-port <PORT>         native QUIC port (default 9777)
+    --data-port <PORT>           pin the per-session video data plane to this fixed UDP port and
+                                 stream direct (no hole-punch) — open exactly this port in a host
+                                 firewall to avoid the ~2.5 s punch-timeout. Default (unset) or
+                                 PUNKTFUNK_DATA_PORT: a random port + hole-punch (crosses NAT)
     --open                       disable mandatory native pairing (default: pairing REQUIRED —
                                  an open host any LAN device can stream from is insecure)
 
@@ -714,6 +747,10 @@ PUNKTFUNK1-HOST OPTIONS:
     --max-sessions <N>           exit after N sessions; 0 = serve forever (default: 0)
     --max-concurrent <N>         stream at most N sessions at once (NVENC bound); overflow waits
                                  in the accept queue; 0 = unlimited (default: 4)
+    --data-port <PORT>           pin the video data plane to this fixed UDP port and stream direct
+                                 (no hole-punch; open exactly this port to skip the ~2.5 s punch-
+                                 timeout). Default or PUNKTFUNK_DATA_PORT: random port + hole-punch.
+                                 A fixed port fits one session; concurrent ones fall back to random
     --allow-tofu                 also accept UNPAIRED clients (trust-on-first-use) and advertise
                                  pair=optional. Default: pairing REQUIRED — the host rejects
                                  unpaired clients and logs a 4-digit pairing PIN at startup;

crates/punktfunk-host/src/mgmt.rs

@@ -160,6 +160,7 @@ fn api_router_parts() -> (Router<Arc<MgmtState>>, utoipa::openapi::OpenApi) {
                 .routes(routes!(set_display_settings))
                 .routes(routes!(get_display_state))
                 .routes(routes!(release_display))
+                .routes(routes!(set_display_layout))
                 .routes(routes!(get_status))
                 .routes(routes!(get_local_summary))
                 .routes(routes!(list_paired_clients))
@@ -381,6 +382,10 @@ struct LocalSummary {
     pin_pending: bool,
     /// Native pairing knocks awaiting the operator's approval (count only).
     pending_approvals: u32,
+    /// Virtual displays being KEPT with no live session — lingering (keep-alive window) or pinned
+    /// (`keep_alive: forever`). Non-zero means a display (and, exclusive, your physical monitors) is
+    /// held; the tray surfaces it + a one-click release. Active (in-use) displays are not counted.
+    kept_displays: u32,
 }
 
 /// A paired (certificate-pinned) Moonlight client.
@@ -988,9 +993,10 @@ struct DisplaySettingsState {
     effective: crate::vdisplay::policy::EffectivePolicy,
     /// Every named preset and what it expands to (for the picker's preview).
     presets: Vec<PresetInfo>,
-    /// Option names this build enforces right now (e.g. `keep_alive`, `topology`). The remaining
-    /// stored options (`mode_conflict`, `identity`, `layout`) land in later stages — surfaced so the
-    /// console can mark them "coming soon" instead of implying they already take effect.
+    /// Option names this build enforces right now. All five axes are now acted on (keep_alive +
+    /// topology since Stage 0-2, identity Stage 3, mode_conflict Stage 4, layout Stage 5) — the console
+    /// reads this to know which controls are live vs. "coming soon" (per-backend nuance, e.g. layout
+    /// position apply being KWin-only, is reported per display in `/display/state`).
     enforced: Vec<String>,
 }
 
@@ -1031,7 +1037,14 @@ fn display_settings_state() -> DisplaySettingsState {
         settings,
         configured,
         presets,
-        enforced: vec!["keep_alive".into(), "topology".into()],
+        enforced: vec![
+            "keep_alive".into(),
+            "topology".into(),
+            "mode_conflict".into(),
+            "identity".into(),
+            "layout".into(),
+            "game_session".into(),
+        ],
     }
 }
 
@@ -1057,9 +1070,8 @@ async fn get_display_settings() -> Json<DisplaySettingsState> {
 /// Set the display-management policy
 ///
 /// Persists a new policy (validated + clamped) and applies it from the next connect/teardown — a
-/// running session keeps the display it opened on. `keep_alive: forever` is rejected until the
-/// display-lifecycle stage ships (it would keep physical monitors dark indefinitely with no release
-/// path yet).
+/// running session keeps the display it opened on. `keep_alive: forever` (the gaming-rig preset) is
+/// honored (the display is Pinned; free it via `POST /display/release`).
 #[utoipa::path(
     put,
     path = "/display/settings",
@@ -1068,7 +1080,7 @@ async fn get_display_settings() -> Json<DisplaySettingsState> {
     request_body = crate::vdisplay::policy::DisplayPolicy,
     responses(
         (status = OK, description = "Policy stored; the new state", body = DisplaySettingsState),
-        (status = BAD_REQUEST, description = "An option value is not yet supported (e.g. keep_alive forever)", body = ApiError),
+        (status = BAD_REQUEST, description = "Malformed policy body", body = ApiError),
         (status = INTERNAL_SERVER_ERROR, description = "Policy could not be persisted", body = ApiError),
         (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
     )
@@ -1076,17 +1088,8 @@ async fn get_display_settings() -> Json<DisplaySettingsState> {
 async fn set_display_settings(
     ApiJson(policy): ApiJson<crate::vdisplay::policy::DisplayPolicy>,
 ) -> Response {
-    use crate::vdisplay::policy::KeepAlive;
-    // Reject options this build can't honor yet, so the console can't promise a behavior that won't
-    // happen. `keep_alive: forever` (directly or via the `gaming-rig` preset) needs the Pinned
-    // lifecycle + a release path; until then it would strand physical monitors dark.
-    if policy.effective().keep_alive == KeepAlive::Forever {
-        return api_error(
-            StatusCode::BAD_REQUEST,
-            "keep_alive `forever` (and the `gaming-rig` preset) is not available yet — it arrives \
-             with the display-lifecycle stage. Use a fixed duration for now.",
-        );
-    }
+    // `keep_alive: forever` (the gaming-rig preset) is now honored: the display is Pinned (Linux
+    // registry + Windows `MgrState::Pinned`) and freed via `POST /display/release` (the escape hatch).
     if let Err(e) = crate::vdisplay::policy::prefs().set(policy) {
         return api_error(
             StatusCode::INTERNAL_SERVER_ERROR,
@@ -1114,6 +1117,18 @@ struct ApiDisplayInfo {
     sessions: u32,
     /// Short client label, when the owner tracks it.
     client: Option<String>,
+    /// Display group (shared desktop) id — several displays with the same group form one desktop (§6A).
+    group: u32,
+    /// This display's ordinal within its group, in acquire order (0-based).
+    display_index: u32,
+    /// Desktop-space top-left `x` (auto-row or the console's manual arrangement, §6.2).
+    x: i32,
+    /// Desktop-space top-left `y`.
+    y: i32,
+    /// Stable per-client identity slot keying persistent config + manual layout (absent = shared/anonymous).
+    identity_slot: Option<u32>,
+    /// Effective topology for this display's group (`extend` | `primary` | `exclusive`).
+    topology: String,
 }
 
 /// The host's managed virtual displays right now.
@@ -1166,6 +1181,12 @@ async fn get_display_state() -> Json<DisplayStateResponse> {
                 expires_in_ms: d.expires_in_ms,
                 sessions: d.sessions,
                 client: d.client,
+                group: d.group,
+                display_index: d.display_index,
+                x: d.position.0,
+                y: d.position.1,
+                identity_slot: d.identity_slot,
+                topology: d.topology,
             })
             .collect(),
     })
@@ -1195,6 +1216,56 @@ async fn release_display(
     Json(ReleaseDisplayResult { released })
 }
 
+/// Request body for `setDisplayLayout`: per-identity-slot desktop offsets, keyed by the identity-slot
+/// id as a string (the same id `/display/state` reports as `identity_slot`).
+#[derive(Deserialize, ToSchema)]
+struct DisplayLayoutRequest {
+    /// `{"<identity_slot>": {"x": …, "y": …}}` — where each arranged display's top-left sits.
+    #[serde(default)]
+    positions: std::collections::BTreeMap<String, crate::vdisplay::policy::Position>,
+}
+
+/// Arrange virtual displays
+///
+/// Set the **manual** desktop arrangement — per-identity-slot `(x, y)` offsets so a multi-monitor
+/// group (§6A/§6B) comes back where the operator placed it. Persisted into the policy's layout block
+/// and switched to manual mode; applied from the next connect (a live group re-applies on its next
+/// acquire). Locks in the current effective behavior as explicit fields, so arranging displays never
+/// silently changes keep-alive/topology/conflict/identity. See `design/display-management.md` §6.2.
+#[utoipa::path(
+    put,
+    path = "/display/layout",
+    tag = "display",
+    operation_id = "setDisplayLayout",
+    request_body = DisplayLayoutRequest,
+    responses(
+        (status = OK, description = "Layout stored; the new settings state", body = DisplaySettingsState),
+        (status = INTERNAL_SERVER_ERROR, description = "Layout could not be persisted", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+async fn set_display_layout(ApiJson(req): ApiJson<DisplayLayoutRequest>) -> Response {
+    let store = crate::vdisplay::policy::prefs();
+    // Lock the current effective behavior into explicit fields + set the manual arrangement (pure
+    // transform, unit-tested in `policy.rs`) — so arranging displays is orthogonal to the other policy
+    // axes. (`effective` keep_alive is never `Forever` via the API — the settings PUT rejects it.)
+    let policy = store
+        .get()
+        .effective()
+        .with_manual_layout(req.positions, store.game_session());
+    if let Err(e) = store.set(policy) {
+        return api_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            &format!("persist display layout: {e:#}"),
+        );
+    }
+    tracing::info!(
+        positions = display_settings_state().settings.layout.positions.len(),
+        "management API: display layout updated"
+    );
+    Json(display_settings_state()).into_response()
+}
+
 /// Live host status
 #[utoipa::path(
     get,
@@ -1267,6 +1338,11 @@ async fn get_local_summary(State(st): State<Arc<MgmtState>>) -> Json<LocalSummar
         native_paired_clients,
         pin_pending: st.app.pairing.pin.awaiting_pin(),
         pending_approvals,
+        kept_displays: crate::vdisplay::registry::snapshot()
+            .displays
+            .iter()
+            .filter(|d| d.state == "lingering" || d.state == "pinned")
+            .count() as u32,
     })
 }
 
@@ -2716,48 +2792,48 @@ mod tests {
             .unwrap()
     }
 
-    /// The display-management endpoints: GET returns the policy surface (presets + effective +
-    /// the Stage-0 enforced list); PUT rejects `keep_alive: forever` (the `gaming-rig` preset)
-    /// *before* persisting, so this stays read-only against the global policy store.
+    /// The display-management GET surface (presets + effective + the enforced-axes list). READ-ONLY
+    /// on purpose: `prefs()` is a process-global `OnceLock`, so a PUT here would clobber it and race
+    /// other tests running in the same process. `keep_alive: forever` (gaming-rig) is now accepted
+    /// (not rejected) — that acceptance is covered on-glass (`.116`) + by the pure `policy` tests, and
+    /// the `forever` value is read off the surfaced preset below without writing.
     #[tokio::test]
-    async fn display_settings_surface_and_forever_rejected() {
+    async fn display_settings_surface() {
         let app = test_app(test_state(), None);
 
         let (status, body) = send(&app, get_req("/api/v1/display/settings")).await;
         assert_eq!(status, StatusCode::OK);
+        let presets = body["presets"].as_array().expect("presets array");
         assert_eq!(
-            body["presets"].as_array().map(|a| a.len()),
-            Some(5),
+            presets.len(),
+            5,
             "all five named presets are surfaced for the console picker"
         );
         assert!(
             body["effective"]["keep_alive"].is_object(),
             "the effective policy is echoed"
         );
+        // gaming-rig surfaces keep_alive: forever (no longer rejected) — read it off the preset list.
+        let gaming = presets
+            .iter()
+            .find(|p| p["id"] == "gaming-rig")
+            .expect("gaming-rig preset surfaced");
+        assert_eq!(
+            gaming["fields"]["keep_alive"]["mode"], "forever",
+            "gaming-rig is keep_alive: forever"
+        );
         let enforced: Vec<&str> = body["enforced"]
             .as_array()
             .unwrap()
             .iter()
             .filter_map(|v| v.as_str())
             .collect();
-        assert!(enforced.contains(&"keep_alive") && enforced.contains(&"topology"));
-
-        // `gaming-rig` expands to keep_alive: forever → rejected at Stage 0 (before any write).
-        let put = axum::http::Request::put("/api/v1/display/settings")
-            .header("content-type", "application/json")
-            .body(Body::from(
-                serde_json::json!({ "preset": "gaming-rig" }).to_string(),
-            ))
-            .unwrap();
-        let (status, body) = send(&app, put).await;
-        assert_eq!(status, StatusCode::BAD_REQUEST);
-        assert!(
-            body["error"]
-                .as_str()
-                .unwrap_or_default()
-                .contains("forever"),
-            "the rejection names the unsupported option"
-        );
+        // All five axes are enforced now (Stages 0-5).
+        assert!(enforced.contains(&"keep_alive"));
+        assert!(enforced.contains(&"topology"));
+        assert!(enforced.contains(&"mode_conflict"));
+        assert!(enforced.contains(&"identity"));
+        assert!(enforced.contains(&"layout"));
     }
 
     /// The display state/release endpoints are wired + auth-gated. On the test host no backend has

crates/punktfunk-host/src/punktfunk1.rs

@@ -75,6 +75,41 @@ pub struct Punktfunk1Options {
     pub pairing_pin: Option<String>,
     /// Paired-clients store path override (tests); `None` = the default config path.
     pub paired_store: Option<std::path::PathBuf>,
+    /// Fixed data-plane UDP port. `None`/`Some(0)` (default): bind a random ephemeral port and
+    /// **hole-punch** — wait ~2.5 s for the client's punch, then fall back to its reported address
+    /// (traverses NAT / a stateful inter-VLAN firewall with no forwarded port, at the cost of the
+    /// punch-timeout on a firewall that drops the punch). `Some(p)`: bind that fixed port and
+    /// stream **directly** to the client's reported address with no punch-wait — for a host whose
+    /// data port is fixed + firewall-opened/forwarded, this removes the punch-timeout delay. A
+    /// fixed port only fits one data plane at a time, so a concurrent session finding it busy
+    /// falls back to random + hole-punch (see [`bind_data_socket`]).
+    pub data_port: Option<u16>,
+    /// Control-connection idle timeout — the **disconnect-detection latency** (how long a vanished
+    /// client takes to be declared dead, which bounds how fast a dropped session tears down / lingers
+    /// and thus the reconnect-overlap window). `None` = the core default (8s). Set from
+    /// `PUNKTFUNK_IDLE_TIMEOUT_MS`; clamped to a ≥1s floor with a keep-alive that scales to it so a
+    /// live session never false-closes.
+    pub idle_timeout: Option<std::time::Duration>,
+}
+
+/// Bind the per-session data-plane UDP socket, honoring [`Punktfunk1Options::data_port`]. Returns
+/// `(socket, direct)`: `direct = true` (a successfully-bound fixed port) means "stream straight to
+/// the client's reported address, no hole-punch"; `false` (random port, or a busy fixed port) means
+/// "hole-punch". The socket is held from the handshake through streaming — no drop-then-rebind
+/// window in which a concurrent session could steal a fixed port.
+fn bind_data_socket(data_port: Option<u16>) -> std::io::Result<(std::net::UdpSocket, bool)> {
+    if let Some(p) = data_port.filter(|p| *p != 0) {
+        match std::net::UdpSocket::bind(("0.0.0.0", p)) {
+            Ok(sock) => return Ok((sock, true)),
+            Err(e) => tracing::warn!(
+                data_port = p,
+                error = %e,
+                "fixed --data-port is busy (a concurrent session already holds it?) — \
+                 falling back to a random port + hole-punch for this session"
+            ),
+        }
+    }
+    Ok((std::net::UdpSocket::bind("0.0.0.0:0")?, false))
 }
 
 /// The native (punktfunk/1) trust store + on-demand arming PIN, shared with the management API.
@@ -143,6 +178,9 @@ pub(crate) struct NativeServe {
     /// The management API's TCP port, advertised over mDNS so a client browses the game library on
     /// the same host IP (the unified `serve` always runs the mgmt API, so this is its bind port).
     pub mgmt_port: u16,
+    /// Fixed data-plane UDP port (`--data-port` / `PUNKTFUNK_DATA_PORT`); see
+    /// [`Punktfunk1Options::data_port`]. `None` = random port + hole-punch (the default).
+    pub data_port: Option<u16>,
 }
 
 /// Options for the native host when the unified `serve --native` runs it: real virtual capture,
@@ -153,6 +191,17 @@ pub(crate) struct NativeServe {
 /// overflow clients wait in the accept queue. Override with `--max-concurrent`.
 pub(crate) const DEFAULT_MAX_CONCURRENT: usize = 4;
 
+/// The control-connection idle timeout (disconnect-detection latency) from
+/// `PUNKTFUNK_IDLE_TIMEOUT_MS`; `None` (unset/invalid/zero) = the core default (8s). Clamped
+/// downstream to a ≥1s floor with a keep-alive that scales to it, so a live session never false-closes.
+pub(crate) fn idle_timeout_from_env() -> Option<std::time::Duration> {
+    std::env::var("PUNKTFUNK_IDLE_TIMEOUT_MS")
+        .ok()
+        .and_then(|s| s.trim().parse::<u64>().ok())
+        .filter(|&ms| ms > 0)
+        .map(std::time::Duration::from_millis)
+}
+
 pub(crate) fn native_serve_opts(cfg: &NativeServe) -> Punktfunk1Options {
     Punktfunk1Options {
         port: cfg.port,
@@ -165,6 +214,8 @@ pub(crate) fn native_serve_opts(cfg: &NativeServe) -> Punktfunk1Options {
         allow_pairing: false,
         pairing_pin: None,
         paired_store: None,
+        data_port: cfg.data_port,
+        idle_timeout: idle_timeout_from_env(),
     }
 }
 
@@ -178,10 +229,11 @@ pub(crate) async fn serve(
         .context("load host identity (~/.config/punktfunk)")?;
     let fingerprint = endpoint::fingerprint_of_pem(&identity.cert_pem)
         .map_err(|e| anyhow!("cert fingerprint: {e}"))?;
-    let ep = endpoint::server_with_identity(
+    let ep = endpoint::server_with_identity_idle(
         ([0, 0, 0, 0], opts.port).into(),
         &identity.cert_pem,
         &identity.key_pem,
+        opts.idle_timeout.unwrap_or(endpoint::DEFAULT_IDLE_TIMEOUT),
     )
     .map_err(|e| anyhow!("QUIC server endpoint: {e}"))?;
     tracing::info!(
@@ -233,6 +285,9 @@ pub(crate) async fn serve(
     // restores the box's autologin gaming session on idle, not per-disconnect — see
     // `vdisplay::restore_managed_session`). Held for serve()'s lifetime; dropping it stops it.
     let _restore_worker = crate::vdisplay::start_restore_worker();
+    // A3: recover a TV takeover stranded by a crashed previous host instance (persisted to
+    // $XDG_RUNTIME_DIR) — schedule a restore after a reconnect grace. No-op on a clean start.
+    crate::vdisplay::restore_takeover_on_startup();
     // Host-lifetime cover-art warmer: fetches + caches GOG/Xbox cover art (no-auth api.gog.com /
     // displaycatalog) off the hot path so `all_games()` (the library list + launch resolve) never
     // blocks on the network. A no-op on a host whose stores all carry their own art.
@@ -346,6 +401,13 @@ const HANDSHAKE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10
 /// code lets a client tell "host busy" apart from a transport failure.
 const REJECT_BUSY_CODE: u32 = 0x42;
 
+/// QUIC application error code a client closes with on a **deliberate quit** (a user "stop", not a
+/// network drop). The host reads it off the connection's `ApplicationClosed` reason and tears the
+/// session's virtual display down IMMEDIATELY, skipping the keep-alive linger — an unwanted disconnect
+/// (idle timeout / reset / any other code) still lingers so a reconnect can resume. Shared with the
+/// clients via `punktfunk_core::quic::QUIT_CLOSE_CODE`.
+const QUIT_CODE: u32 = punktfunk_core::quic::QUIT_CLOSE_CODE;
+
 /// Encoder bitrate (kbps) the host falls back to when the client expresses no preference
 /// (`Hello::bitrate_kbps == 0`) — the long-standing 20 Mbps default. A client that knows its
 /// link (e.g. after a speed test) requests an explicit rate instead.
@@ -656,6 +718,7 @@ async fn serve_session(
 
     let source = opts.source;
     let frames = opts.frames;
+    let data_port = opts.data_port;
     let handshake = async {
         let mut hello = Hello::decode(&first).map_err(|e| anyhow!("Hello decode: {e:?}"))?;
         anyhow::ensure!(
@@ -696,8 +759,32 @@ async fn serve_session(
         // A same-client reconnect never conflicts. THIS session registers in the live set once its
         // data plane is up (below the handshake), so a later client can see + steal it.
         {
-            use crate::vdisplay::admission::{admit, Admission};
-            match admit(endpoint::peer_fingerprint(&conn)) {
+            use crate::vdisplay::admission::{admit, preempt_same_identity, Admission};
+            let peer_fp = endpoint::peer_fingerprint(&conn);
+
+            // Same-client RECONNECT preempt (design §5.3 "preempts downstream"): if THIS client
+            // already has a live session, it's the zombie of an unwanted disconnect whose QUIC idle
+            // timer hasn't fired yet (detection lags a drop by up to `max_idle_timeout`). Signal it to
+            // stop and give it the release grace so it tears its display down — which, keep-alive on,
+            // lingers — and THIS reconnect REUSES that kept display below instead of landing on a
+            // fresh SECOND one. Independent of the mode_conflict arm (it's our OWN prior session, not
+            // a conflict with a different client), and it runs before we register ourselves so we
+            // never signal our own stop flag.
+            let own_zombies = preempt_same_identity(peer_fp);
+            if !own_zombies.is_empty() {
+                tracing::info!(
+                    count = own_zombies.len(),
+                    "reconnect: preempting this client's own zombie session(s) so the kept display is reused"
+                );
+                for z in &own_zombies {
+                    z.store(true, Ordering::SeqCst);
+                }
+                // Same blind release grace the steal path uses — lets the zombie's loops notice the
+                // stop flag and drop its display (→ Lingering) before we acquire below.
+                tokio::time::sleep(std::time::Duration::from_millis(1500)).await;
+            }
+
+            match admit(peer_fp) {
                 Admission::Separate => {}
                 Admission::Join(m) => {
                     tracing::info!(
@@ -742,8 +829,23 @@ async fn serve_session(
         let compositor = match source {
             Punktfunk1Source::Virtual => {
                 let pref = hello.compositor;
+                // Dedicated game session (B0): a launching client under `game_session=dedicated`
+                // (gamescope available) gets its own headless gamescope spawn at the client mode. Gate on
+                // whether the launch id actually RESOLVES to a command in the host's library — an unknown
+                // id must fall back to normal auto routing, not a blank "sleep infinity" gamescope
+                // (review #9). (dedicated is Linux-only; the resolver is the non-Windows launch_command.)
+                #[cfg(not(target_os = "windows"))]
+                let has_resolvable_launch = hello
+                    .launch
+                    .as_deref()
+                    .and_then(crate::library::launch_command)
+                    .is_some();
+                #[cfg(target_os = "windows")]
+                let has_resolvable_launch = false;
+                let dedicated =
+                    crate::vdisplay::wants_dedicated_game_session(has_resolvable_launch);
                 Some(
-                    tokio::task::spawn_blocking(move || resolve_compositor(pref))
+                    tokio::task::spawn_blocking(move || resolve_compositor(pref, dedicated))
                         .await
                         .context("resolve compositor task")??,
                 )
@@ -846,10 +948,12 @@ async fn serve_session(
             "encode chroma"
         );
 
-        // Reserve a UDP port for the data plane (bind, read it back, rebind in UdpTransport).
-        let probe = std::net::UdpSocket::bind("0.0.0.0:0")?;
-        let udp_port = probe.local_addr()?.port();
-        drop(probe);
+        // Reserve the data-plane UDP socket up front and HOLD it through streaming (no
+        // bind→read→drop→rebind window a concurrent session could race for a fixed port). A fixed
+        // `--data-port` yields `direct = true` (stream straight to the client's reported address,
+        // no punch-wait); otherwise a random ephemeral port + hole-punch.
+        let (data_sock, direct) = bind_data_socket(data_port)?;
+        let udp_port = data_sock.local_addr()?.port();
 
         let mut key = [0u8; 16];
         rand::thread_rng().fill_bytes(&mut key);
@@ -909,9 +1013,11 @@ async fn serve_session(
 
         let start = Start::decode(&io::read_msg(&mut recv).await?)
             .map_err(|e| anyhow!("Start decode: {e:?}"))?;
-        Ok::<_, anyhow::Error>((hello, welcome, udp_port, start, compositor))
+        Ok::<_, anyhow::Error>((
+            hello, welcome, udp_port, data_sock, direct, start, compositor,
+        ))
     };
-    let (hello, welcome, udp_port, start, compositor) =
+    let (hello, welcome, udp_port, data_sock, direct, start, compositor) =
         tokio::time::timeout(HANDSHAKE_TIMEOUT, handshake)
             .await
             .map_err(|_| anyhow!("handshake timed out after {HANDSHAKE_TIMEOUT:?}"))??;
@@ -1095,11 +1201,21 @@ async fn serve_session(
 
     // Stop signal: stream duration elapsed or the client went away.
     let stop = Arc::new(AtomicBool::new(false));
+    // Deliberate-quit signal: set (before `stop`, so the display lease reads it on teardown) when the
+    // client closed the connection with `QUIT_CODE` — a user "stop", which skips the keep-alive linger.
+    // A bare disconnect / idle timeout leaves it false → the display lingers for a reconnect.
+    let quit = Arc::new(AtomicBool::new(false));
     {
         let stop = stop.clone();
+        let quit = quit.clone();
         let conn = conn.clone();
         tokio::spawn(async move {
-            conn.closed().await;
+            let reason = conn.closed().await;
+            if matches!(&reason, quinn::ConnectionError::ApplicationClosed(ac)
+                if ac.error_code == quinn::VarInt::from_u32(QUIT_CODE))
+            {
+                quit.store(true, Ordering::SeqCst);
+            }
             stop.store(true, Ordering::SeqCst);
         });
     }
@@ -1110,11 +1226,20 @@ async fn serve_session(
     let _live_guard = {
         let id = endpoint::peer_fingerprint(&conn);
         let label = id
-            .map(|fp| fp.iter().take(4).map(|b| format!("{b:02x}")).collect::<String>())
+            .map(|fp| {
+                fp.iter()
+                    .take(4)
+                    .map(|b| format!("{b:02x}"))
+                    .collect::<String>()
+            })
             .unwrap_or_else(|| "client".to_string());
         crate::vdisplay::admission::register(
             id,
-            (welcome.mode.width, welcome.mode.height, welcome.mode.refresh_hz),
+            (
+                welcome.mode.width,
+                welcome.mode.height,
+                welcome.mode.refresh_hz,
+            ),
             stop.clone(),
             label,
         )
@@ -1218,6 +1343,7 @@ async fn serve_session(
         crate::encode::ChromaFormat::Yuv420
     };
     let stop_stream = stop.clone();
+    let quit_stream = quit.clone();
     let fec_target_dp = fec_target.clone(); // data-plane handle to the adaptive-FEC target
     let conn_stream = conn.clone(); // for sending the source's real HDR metadata (0xCE) mid-stream
                                     // Per-AU host-timing emission (0xCF): only when the client advertised the cap bit. All
@@ -1233,29 +1359,41 @@ async fn serve_session(
         .unwrap_or_else(|| conn.remote_address().ip().to_string());
     let result: Result<()> = async {
         tokio::task::spawn_blocking(move || -> Result<()> {
-            // Wait briefly for the client to hole-punch our data port, then stream to its OBSERVED
-            // source — so video traverses a NAT / stateful inter-VLAN firewall (the client and host
-            // can be on different subnets; control + side planes ride the client-initiated QUIC, but
-            // the raw video UDP needs the client to open the path first). Falls back to the
-            // client-reported address for clients that don't punch (flat-LAN, unchanged).
-            let (transport, punched) = match UdpTransport::connect_via_punch(
-                &format!("0.0.0.0:{udp_port}"),
-                &client_udp.to_string(),
-                std::time::Duration::from_millis(2500),
-            ) {
+            // Bring up the (already-bound) data-plane socket. Default: hole-punch — wait briefly
+            // for the client's punch, then stream to its OBSERVED source, so video traverses a
+            // NAT / stateful inter-VLAN firewall (control + side planes ride the client-initiated
+            // QUIC, but the raw video UDP needs the client to open the path first); falls back to
+            // the reported address for clients that don't punch (flat-LAN, unchanged). With a fixed
+            // `--data-port` (`direct`), skip the punch-wait and stream straight to the reported
+            // address — the operator declared a reachable, firewall-opened port, so there's no
+            // punch-timeout to pay. (Direct trusts the reported port: it can't cross a client-side
+            // NAT that remaps it.)
+            let bound = if direct {
+                UdpTransport::from_socket(data_sock, &client_udp.to_string()).map(|t| (t, false))
+            } else {
+                UdpTransport::from_socket_punch(
+                    data_sock,
+                    &client_udp.to_string(),
+                    std::time::Duration::from_millis(2500),
+                )
+            };
+            let (transport, punched) = match bound {
                 Ok(v) => v,
                 Err(e) => {
                     // Surface the failure here directly: a data-plane bind error would otherwise be
                     // reported only after teardown (and a teardown stall could swallow it entirely).
-                    tracing::error!(error = %e, %client_udp, udp_port, "data-plane socket bind/hole-punch failed");
+                    tracing::error!(error = %e, %client_udp, udp_port, "data-plane socket setup failed");
                     return Err(anyhow::Error::new(e)).context("bind data plane");
                 }
             };
             tracing::info!(
                 %client_udp,
+                udp_port,
+                direct,
                 punched,
-                "data plane bound (punched=true → streaming to the client's observed source; \
-                 false → no hole-punch seen, using the reported address)"
+                "data plane bound (direct=true → fixed --data-port, streaming to the reported \
+                 address with no hole-punch; else punched=true → the client's observed source, \
+                 false → no punch seen, the reported address)"
             );
             let mut session = Session::new(cfg, Box::new(transport))
                 .map_err(|e| anyhow!("host session: {e:?}"))?;
@@ -1277,6 +1415,7 @@ async fn serve_session(
                         mode,
                         seconds,
                         stop: stop_stream,
+                        quit: quit_stream,
                         reconfig: reconfig_rx,
                         keyframe: keyframe_rx,
                         compositor,
@@ -2102,17 +2241,24 @@ fn pick_compositor(
 /// [`pick_compositor`]): enumerate what's available, auto-detect the default, pick, and log
 /// whether the explicit request was honored or fell back. Runs blocking probes — call off the
 /// async reactor (`spawn_blocking`).
-fn resolve_compositor(pref: CompositorPref) -> Result<crate::vdisplay::Compositor> {
+fn resolve_compositor(
+    pref: CompositorPref,
+    dedicated_launch: bool,
+) -> Result<crate::vdisplay::Compositor> {
     use crate::vdisplay::Compositor;
     // Windows has a single virtual-display backend (SudoVDA); vdisplay::open ignores the compositor
     // arg there, so short-circuit the Linux session-detection state machine with a placeholder.
     #[cfg(target_os = "windows")]
     {
-        let _ = pref;
+        let _ = (pref, dedicated_launch);
         Ok(Compositor::Kwin)
     }
     #[cfg(not(target_os = "windows"))]
     {
+        // A client is (re)connecting → cancel any pending TV-session restore so the box stays in the
+        // streamed session (covers the keep-alive REUSE reconnect, which skips create_managed_session's
+        // own cancel — review #3). No-op when nothing is pending.
+        crate::vdisplay::cancel_pending_tv_restore();
         // Explicit operator override (legacy / CI / forcing a backend for a test) wins and is assumed
         // to come with a hand-set env — don't retarget the process env in that case.
         let overridden = crate::config::config().compositor.is_some();
@@ -2123,6 +2269,10 @@ fn resolve_compositor(pref: CompositorPref) -> Result<crate::vdisplay::Composito
             // every backend (video capture + input) this connect opens against the active session —
             // this is the state machine that lets one host follow a Bazzite box across Gaming↔Desktop.
             let active = crate::vdisplay::detect_active_session();
+            // A4: if the compositor instance changed since the last connect (an idle-time Game↔Desktop
+            // switch), bump the epoch + invalidate the old backend's kept displays so this connect never
+            // reuses a node id from the dead instance.
+            crate::vdisplay::observe_session_instance(&active);
             crate::vdisplay::apply_session_env(&active);
             tracing::info!(
                 active = ?active.kind,
@@ -2131,6 +2281,18 @@ fn resolve_compositor(pref: CompositorPref) -> Result<crate::vdisplay::Composito
             );
             crate::vdisplay::compositor_for_kind(active.kind)
         };
+        // Dedicated game session (design/gamemode-and-dedicated-sessions.md B0): a launching session
+        // under `game_session=dedicated` (gamescope confirmed available) forces its OWN headless
+        // gamescope spawn at the client's mode, overriding the detected desktop/game-mode backend. The
+        // env was already retargeted above (for XDG_RUNTIME_DIR / the PipeWire daemon); we just pin the
+        // backend + input to the spawn sub-mode. Skipped under an explicit operator compositor pin.
+        if dedicated_launch && !overridden {
+            crate::vdisplay::apply_input_env(Compositor::Gamescope, true);
+            tracing::info!(
+                "dedicated game session — routing to a headless gamescope spawn at the client mode"
+            );
+            return Ok(Compositor::Gamescope);
+        }
         let available = crate::vdisplay::available();
         let chosen = pick_compositor(pref, &available, detected).ok_or_else(|| {
         anyhow!("no usable compositor (no live graphical session for this uid; set PUNKTFUNK_COMPOSITOR or start a desktop/gaming session)")
@@ -2138,7 +2300,7 @@ fn resolve_compositor(pref: CompositorPref) -> Result<crate::vdisplay::Composito
         if !overridden {
             // Point input at the same backend and resolve the gamescope sub-mode (managed where the
             // session infra exists, attach to a foreign gamescope, else per-session bare spawn).
-            crate::vdisplay::apply_input_env(chosen);
+            crate::vdisplay::apply_input_env(chosen, false);
         }
         let avail_ids: Vec<&str> = available.iter().map(|c| c.id()).collect();
         match Compositor::from_pref(pref) {
@@ -2765,6 +2927,11 @@ fn session_watcher_loop(tx: std::sync::mpsc::Sender<SessionSwitch>, stop: Arc<At
             break;
         }
         let active = vdisplay::detect_active_session();
+        // A4: bump the session epoch + invalidate the old backend the moment the compositor instance
+        // changes (kind change OR same-kind restart) — even for a same-kind restart the watcher won't
+        // signal a full SessionSwitch for. Self-dedupes; the debounced SessionSwitch below still drives
+        // the in-place rebuild.
+        vdisplay::observe_session_instance(&active);
         let cur = active.kind;
         if cur == current {
             pending = None; // back to the current backend before debounce elapsed — no switch
@@ -2816,6 +2983,9 @@ struct SessionContext {
     seconds: u32,
     /// Session stop flag (set on disconnect / reconnect-preempt).
     stop: Arc<AtomicBool>,
+    /// Deliberate-quit flag (set when the client closed with `QUIT_CODE`): the display lease reads it
+    /// on teardown to skip the keep-alive linger for a user "stop" (vs. an unwanted disconnect).
+    quit: Arc<AtomicBool>,
     /// Accepted mid-stream mode switches — the pipeline is rebuilt at the new mode.
     reconfig: std::sync::mpsc::Receiver<punktfunk_core::Mode>,
     /// Client decode-recovery keyframe requests.
@@ -2875,6 +3045,7 @@ fn virtual_stream(ctx: SessionContext) -> Result<()> {
         mode,
         seconds,
         stop,
+        quit,
         reconfig,
         keyframe,
         compositor,
@@ -2924,8 +3095,8 @@ fn virtual_stream(ctx: SessionContext) -> Result<()> {
     #[cfg(target_os = "windows")]
     let _idd_setup_guard = (plan.capture == crate::session_plan::CaptureBackend::IddPush)
         .then(|| crate::vdisplay::manager::vdm().begin_idd_setup(stop.clone()));
-    let (mut capturer, mut enc, mut frame, mut interval) =
-        build_pipeline_with_retry(&mut vd, mode, bitrate_kbps, bit_depth, plan)?;
+    let (mut capturer, mut enc, mut frame, mut interval, mut cur_node_id) =
+        build_pipeline_with_retry(&mut vd, mode, bitrate_kbps, bit_depth, plan, &quit)?;
     // Setup done — release the IDD-push setup lock so the next reconnect can begin (and preempt us).
     #[cfg(target_os = "windows")]
     drop(_idd_setup_guard);
@@ -3071,8 +3242,11 @@ fn virtual_stream(ctx: SessionContext) -> Result<()> {
                 crate::vdisplay::apply_session_env(&crate::vdisplay::ActiveSession {
                     kind: sw.kind,
                     env: sw.env,
+                    compositor_pid: None,
                 });
-                crate::vdisplay::apply_input_env(sw.compositor);
+                // A mid-stream Game↔Desktop switch is not a fresh dedicated launch — route input at the
+                // switched-to backend's normal sub-mode.
+                crate::vdisplay::apply_input_env(sw.compositor, false);
                 // Switching INTO a desktop mid-stream: the xdg portal / systemd-user env may still
                 // point at the old session, so input would silently not land until a reconnect.
                 // Settle it (env push + KWin portal restart) before the injector reopens against it.
@@ -3093,17 +3267,19 @@ fn virtual_stream(ctx: SessionContext) -> Result<()> {
                             bitrate_kbps,
                             bit_depth,
                             plan,
+                            &quit,
                         )?;
                         Ok((new_vd, pipe))
                     })();
                 match rebuilt {
-                    Ok((new_vd, (new_cap, new_enc, new_frame, new_interval))) => {
+                    Ok((new_vd, (new_cap, new_enc, new_frame, new_interval, new_node_id))) => {
                         // Replace the pipeline first (drops the old capturer → old PipeWire stream +
                         // virtual output), then the factory (drops e.g. the old KWin connection).
                         capturer = new_cap;
                         enc = new_enc;
                         frame = new_frame;
                         interval = new_interval;
+                        cur_node_id = new_node_id;
                         vd = new_vd;
                         compositor = sw.compositor;
                         next = std::time::Instant::now();
@@ -3136,9 +3312,9 @@ fn virtual_stream(ctx: SessionContext) -> Result<()> {
             // Build the new pipeline BEFORE dropping the old one: the host already acked
             // the switch as accepted, so a rebuild failure must not kill an otherwise
             // healthy session — keep streaming the current mode and log instead.
-            match build_pipeline(&mut vd, new_mode, bitrate_kbps, bit_depth, plan) {
+            match build_pipeline(&mut vd, new_mode, bitrate_kbps, bit_depth, plan, &quit) {
                 Ok(next_pipe) => {
-                    (capturer, enc, frame, interval) = next_pipe;
+                    (capturer, enc, frame, interval, cur_node_id) = next_pipe;
                     cur_mode = new_mode;
                     next = std::time::Instant::now();
                 }
@@ -3205,6 +3381,27 @@ fn virtual_stream(ctx: SessionContext) -> Result<()> {
             // bounded retry is exhausted; the consecutive cap stops a flapping source from looping the
             // client through endless cold IDRs.
             Err(e) => {
+                // B2: a DEDICATED gamescope game session whose gamescope node is gone = the game
+                // exited (gamescope is a single-app compositor — it dies with its app). End the session
+                // CLEANLY — close with `APP_EXITED_CLOSE_CODE` so a launcher client returns to its
+                // library instead of surfacing a failure — rather than the capture-loss rebuild + 40 s
+                // timeout. Gated to the dedicated bare-spawn launch (`launch_is_nested`), so a normal
+                // Bazzite/desktop capture loss still rebuilds in place.
+                #[cfg(target_os = "linux")]
+                if launch.is_some()
+                    && crate::vdisplay::launch_is_nested(compositor)
+                    && crate::vdisplay::dedicated_game_exited(cur_node_id)
+                {
+                    tracing::info!(
+                        "dedicated game session: the game exited — ending the session cleanly"
+                    );
+                    quit.store(true, Ordering::SeqCst); // skip keep-alive linger — the game is gone
+                    conn.close(
+                        punktfunk_core::quic::APP_EXITED_CLOSE_CODE.into(),
+                        b"game exited",
+                    );
+                    break;
+                }
                 capture_rebuilds += 1;
                 if capture_rebuilds > MAX_CAPTURE_REBUILDS {
                     return Err(e).context("capture lost — rebuild attempts exhausted");
@@ -3222,14 +3419,18 @@ fn virtual_stream(ctx: SessionContext) -> Result<()> {
                 // appears — no reconnect.
                 const REBUILD_BUDGET: std::time::Duration = std::time::Duration::from_secs(40);
                 let rebuild_deadline = std::time::Instant::now() + REBUILD_BUDGET;
-                let (new_cap, new_enc, new_frame, new_interval) = loop {
+                let (new_cap, new_enc, new_frame, new_interval, new_node_id) = loop {
                     // Follow the active session unless an explicit PUNKTFUNK_COMPOSITOR pin forbids
                     // retargeting (then we stick to the pinned backend and just rebuild it).
                     if crate::config::config().compositor.is_none() {
                         let active = crate::vdisplay::detect_active_session();
+                        // A4: fold any compositor-instance change into the epoch/invalidation before we
+                        // rebuild, so the rebuild's acquire won't reuse a dead-instance node.
+                        crate::vdisplay::observe_session_instance(&active);
                         if let Some(c) = crate::vdisplay::compositor_for_kind(active.kind) {
                             crate::vdisplay::apply_session_env(&active);
-                            crate::vdisplay::apply_input_env(c);
+                            // Capture-loss rebuild follows the live box session, not a fresh dedicated launch.
+                            crate::vdisplay::apply_input_env(c, false);
                             if c != compositor {
                                 if matches!(
                                     c,
@@ -3257,6 +3458,7 @@ fn virtual_stream(ctx: SessionContext) -> Result<()> {
                         bitrate_kbps,
                         bit_depth,
                         plan,
+                        &quit,
                     ) {
                         Ok(p) => break p,
                         Err(e2) => {
@@ -3275,6 +3477,7 @@ fn virtual_stream(ctx: SessionContext) -> Result<()> {
                 enc = new_enc;
                 frame = new_frame;
                 interval = new_interval;
+                cur_node_id = new_node_id;
                 enc.request_keyframe(); // belt-and-suspenders; a fresh encoder opens on an IDR anyway
                 next = std::time::Instant::now();
                 tracing::info!(
@@ -3465,6 +3668,10 @@ type Pipeline = (
     Box<dyn crate::encode::Encoder>,
     crate::capture::CapturedFrame,
     std::time::Duration,
+    // The virtual output's PipeWire node id — used by the B2 dedicated game-exit probe to check THIS
+    // session's own node (scoped), not any gamescope node. `0` for backends without a PipeWire node
+    // (Windows IDD-push), which never take the dedicated-gamescope B2 path anyway.
+    u32,
 );
 
 /// Build the pipeline, retrying *transient* failures with bounded exponential backoff.
@@ -3483,6 +3690,7 @@ fn build_pipeline_with_retry(
     bitrate_kbps: u32,
     bit_depth: u8,
     plan: crate::session_plan::SessionPlan,
+    quit: &Arc<AtomicBool>,
 ) -> Result<Pipeline> {
     // ~10s first-frame wait per attempt. 8 gives a ~90s budget for the SLOW case: a host-managed
     // gamescope session cold-starting Steam Big Picture (the SteamOS/Bazzite takeover) can take
@@ -3509,7 +3717,7 @@ fn build_pipeline_with_retry(
     const MAX_ATTEMPTS: u32 = 8;
     let mut backoff = std::time::Duration::from_millis(500);
     for attempt in 1..=MAX_ATTEMPTS {
-        match build_pipeline(vd, mode, bitrate_kbps, bit_depth, plan) {
+        match build_pipeline(vd, mode, bitrate_kbps, bit_depth, plan, quit) {
             Ok(pipe) => {
                 if attempt > 1 {
                     tracing::info!(attempt, "pipeline up after retry");
@@ -3572,12 +3780,23 @@ fn build_pipeline(
     bitrate_kbps: u32,
     bit_depth: u8,
     plan: crate::session_plan::SessionPlan,
+    quit: &Arc<AtomicBool>,
 ) -> Result<Pipeline> {
     // Acquire through the registry (design/display-management.md): on Linux this pools the display
     // for keep-alive (reuse a kept one, or create + keep the backend's keepalive so it outlives the
     // session per policy); on Windows it delegates to `vd.create` (the manager already leases). The
-    // returned `VirtualOutput`'s keepalive is a registry lease — the capturer holds it as before.
-    let vout = crate::vdisplay::registry::acquire(vd, mode).context("create virtual output")?;
+    // returned `VirtualOutput`'s keepalive is a registry lease — the capturer holds it as before. The
+    // `quit` flag rides into the lease so a deliberate-quit teardown skips the keep-alive linger.
+    let vout = crate::vdisplay::registry::acquire(vd, mode, quit.clone())
+        .context("create virtual output")?;
+    // A2: if this was a REUSED kept display and its first frame fails, tear the (dead) pool entry down
+    // so the retry loop's next acquire creates fresh instead of re-wedging on the same corpse. Read the
+    // gen BEFORE `capture_virtual_output` consumes `vout`. (Linux-only — the pool is Linux.)
+    #[cfg(target_os = "linux")]
+    let reused_gen = vout.reused_gen;
+    // The virtual output's PipeWire node id — kept for the B2 dedicated game-exit probe (scoped to
+    // this session's own node). Read before `capture_virtual_output` consumes `vout`.
+    let node_id = vout.node_id;
     // The backend reports the refresh it actually achieved in `preferred_mode.2` (KWin may cap a
     // virtual output at 60 Hz if the custom-mode install was rejected). Pace the encoder + frame
     // clock to that, not the requested rate, so we don't emit phantom duplicate frames over a
@@ -3602,7 +3821,17 @@ fn build_pipeline(
         crate::capture::capture_virtual_output(vout, plan.output_format(), plan.capture)
             .context("capture virtual output")?;
     capturer.set_active(true);
-    let frame = capturer.next_frame().context("first frame")?;
+    let frame = match capturer.next_frame().context("first frame") {
+        Ok(f) => f,
+        Err(e) => {
+            // A reused kept display was dead — invalidate it so the next attempt creates fresh (A2).
+            #[cfg(target_os = "linux")]
+            if let Some(g) = reused_gen {
+                crate::vdisplay::registry::mark_failed(g);
+            }
+            return Err(e);
+        }
+    };
     // `bit_depth` is the handshake-negotiated value (8, or 10 = HEVC Main10 when the client
     // advertised VIDEO_CAP_10BIT and the host opted in). Threaded down from the Welcome.
     let enc = crate::encode::open_video(
@@ -3629,7 +3858,7 @@ fn build_pipeline(
         );
     }
     let interval = std::time::Duration::from_secs_f64(1.0 / effective_hz.max(1) as f64);
-    Ok((capturer, enc, frame, interval))
+    Ok((capturer, enc, frame, interval, node_id))
 }
 
 #[cfg(test)]
@@ -3650,6 +3879,43 @@ mod tests {
         assert!(adapt_fec(u32::MAX) <= FEC_MAX);
     }
 
+    #[test]
+    fn data_socket_defaults_to_random_hole_punch() {
+        // No fixed port (and the explicit-0 alias) → a random ephemeral port, and NOT direct: the
+        // caller hole-punches.
+        for req in [None, Some(0)] {
+            let (sock, direct) = bind_data_socket(req).expect("bind random data socket");
+            assert!(!direct, "req={req:?} must hole-punch, not stream direct");
+            assert_ne!(sock.local_addr().unwrap().port(), 0);
+        }
+    }
+
+    #[test]
+    fn data_socket_fixed_binds_direct_then_falls_back_when_busy() {
+        // Learn a currently-free port (bind :0, read it, drop — the same reserve-then-rebind the
+        // host itself uses; a race here would only make the assert below flaky, not wrong).
+        let free = std::net::UdpSocket::bind("0.0.0.0:0")
+            .unwrap()
+            .local_addr()
+            .unwrap()
+            .port();
+
+        // A free fixed port binds exactly it, in DIRECT mode (no hole-punch).
+        let (held, direct) = bind_data_socket(Some(free)).expect("bind fixed data socket");
+        assert!(direct, "a fixed --data-port must stream direct");
+        assert_eq!(held.local_addr().unwrap().port(), free);
+
+        // While it's held, a second session on the same fixed port can't bind it → it must fall
+        // back to a random port + hole-punch rather than fail (so concurrency never regresses).
+        let (fallback, direct2) = bind_data_socket(Some(free)).expect("busy fixed port falls back");
+        assert!(!direct2, "a busy fixed port must fall back to hole-punch");
+        assert_ne!(
+            fallback.local_addr().unwrap().port(),
+            free,
+            "the fallback must not reuse the busy fixed port"
+        );
+    }
+
     #[test]
     fn compositor_resolution_precedence() {
         use crate::vdisplay::Compositor::*;
@@ -3825,10 +4091,18 @@ mod tests {
     /// End-to-end through the C ABI — the exact contract platform clients (Swift) link:
     /// in-process punktfunk/1 host, `punktfunk_connect` (TOFU → pinned reconnect) →
     /// `punktfunk_connection_next_au` pulls verified frames → `punktfunk_connection_send_input`
+    /// In-process-host tests each spin up a host on a fixed loopback port and share the process-global
+    /// admission table, so they must NOT run concurrently: a same-identity connection in one test would
+    /// fire the reconnect-preempt (`preempt_same_identity`) against another test's live session and
+    /// close it. Serialize them on this lock. Poison-tolerant (`into_inner`) so a failing test doesn't
+    /// cascade a poison error into the others.
+    static SESSION_TEST_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
+
     /// enqueues → `punktfunk_connection_close`. Three sequential sessions against ONE host
     /// process prove the persistent listener, and a wrong pin is rejected.
     #[test]
     fn c_abi_connection_roundtrip() {
+        let _serial = SESSION_TEST_LOCK.lock().unwrap_or_else(|p| p.into_inner());
         use punktfunk_core::abi::{
             punktfunk_connect, punktfunk_connection_close, punktfunk_connection_mode,
             punktfunk_connection_send_input,
@@ -3847,6 +4121,8 @@ mod tests {
                 allow_pairing: false,
                 pairing_pin: None,
                 paired_store: None,
+                data_port: None,
+                idle_timeout: None,
             })
         });
         std::thread::sleep(std::time::Duration::from_millis(500));
@@ -4015,6 +4291,7 @@ mod tests {
     /// admitted to a session with no PIN and no reconnect.
     #[test]
     fn delegated_approval_admits_after_knock() {
+        let _serial = SESSION_TEST_LOCK.lock().unwrap_or_else(|p| p.into_inner());
         use punktfunk_core::client::NativeClient;
         use punktfunk_core::quic::endpoint;
 
@@ -4041,6 +4318,8 @@ mod tests {
                     allow_pairing: false,
                     pairing_pin: None,
                     paired_store: None, // unused: the shared `np` IS the store handle
+                    data_port: None,
+                    idle_timeout: None,
                 },
                 0, // no mgmt API in this test → advertise no `mgmt` mDNS port
                 np_host,
@@ -4124,6 +4403,7 @@ mod tests {
     /// identity gets a session on a pairing-required host; an anonymous client does not.
     #[test]
     fn pairing_ceremony_and_gate() {
+        let _serial = SESSION_TEST_LOCK.lock().unwrap_or_else(|p| p.into_inner());
         use punktfunk_core::client::NativeClient;
         use punktfunk_core::quic::endpoint;
 
@@ -4139,6 +4419,8 @@ mod tests {
                 allow_pairing: false,
                 pairing_pin: Some("4321".into()),
                 paired_store: Some(test_paired_path()),
+                data_port: None,
+                idle_timeout: None,
             })
         });
         std::thread::sleep(std::time::Duration::from_millis(500));

crates/punktfunk-host/src/vdisplay.rs

@@ -21,6 +21,29 @@ pub use punktfunk_core::Mode;
 #[cfg(target_os = "linux")]
 use std::os::fd::OwnedFd;
 
+/// Who owns a [`VirtualOutput`]'s lifecycle — the honest declaration that lets the registry
+/// (`design/gamemode-and-dedicated-sessions.md` Part A1) pool **only what it owns** instead of
+/// keeping outputs whose real lifecycle lives elsewhere (the gamescope managed/attach paths, which
+/// are governed by the gamescope module's own session machinery). Extends the CLAUDE.md invariant
+/// "the registry owns display lifecycle" with its converse: what the registry does not own, it must
+/// not pretend to keep.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum DisplayOwnership {
+    /// The registry owns the lifecycle: it may pool, linger, pin, and tear this display down (KWin,
+    /// Mutter, wlroots, gamescope **bare spawn**, and the Windows manager-delegated monitor). The
+    /// default — a backend that says nothing is registry-owned.
+    #[default]
+    Owned,
+    /// Someone else's display, merely mirrored: no keep-alive, no topology, no reuse (gamescope
+    /// **attach** to a foreign session). Codifies the design-doc §7 "attach = unmanaged pass-through"
+    /// row.
+    External,
+    /// A box-level session the gamescope module manages (the managed `gamescope-session-plus` /
+    /// SteamOS takeover). Passed through by the registry (its restore lifecycle is the gamescope
+    /// module's until Part A3 hands the registry a real keepalive + restore duty).
+    SessionManaged,
+}
+
 /// A created virtual output: a PipeWire source to capture, plus an owned keepalive whose drop
 /// tears the output down (releases the compositor-side resource).
 ///
@@ -44,6 +67,41 @@ pub struct VirtualOutput {
     pub win_capture: Option<crate::capture::dxgi::WinCaptureTarget>,
     /// Keeps the output — and whatever connection/thread backs it — alive; dropped on teardown.
     pub keepalive: Box<dyn Send>,
+    /// Who owns this display's lifecycle (`design/gamemode-and-dedicated-sessions.md` A1). The
+    /// registry pools/keep-alives only [`DisplayOwnership::Owned`] outputs; `External`/`SessionManaged`
+    /// pass through (the capturer holds the keepalive, teardown on drop). Defaults to `Owned`.
+    pub ownership: DisplayOwnership,
+    /// `Some(gen)` when [`registry::acquire`](crate::vdisplay::registry::acquire) handed this back as a
+    /// **reused** kept display (`design/gamemode-and-dedicated-sessions.md` A2), so the pipeline builder
+    /// can [`registry::mark_failed(gen)`](crate::vdisplay::registry::mark_failed) if the first frame
+    /// fails on it — tearing the corpse down so the retry loop's next acquire creates fresh instead of
+    /// re-wedging on the same dead node. `None` on a fresh create / non-poolable output. Linux-only (the
+    /// keep-alive pool is Linux).
+    #[cfg(target_os = "linux")]
+    pub reused_gen: Option<u64>,
+}
+
+impl VirtualOutput {
+    /// A registry-[owned](DisplayOwnership::Owned) output — the common case (KWin/Mutter/wlroots,
+    /// gamescope bare-spawn, Windows). Fills `ownership: Owned`; the caller sets the platform fields.
+    pub fn owned(
+        node_id: u32,
+        preferred_mode: Option<(u32, u32, u32)>,
+        keepalive: Box<dyn Send>,
+    ) -> VirtualOutput {
+        VirtualOutput {
+            node_id,
+            #[cfg(target_os = "linux")]
+            remote_fd: None,
+            preferred_mode,
+            #[cfg(target_os = "windows")]
+            win_capture: None,
+            keepalive,
+            ownership: DisplayOwnership::Owned,
+            #[cfg(target_os = "linux")]
+            reused_gen: None,
+        }
+    }
 }
 
 /// Pluggable virtual-output creation, per compositor.
@@ -64,6 +122,147 @@ pub trait VirtualDisplay: Send {
     /// Default: no-op — only the Windows pf-vdisplay backend uses it (Linux compositors own their virtual
     /// output identity). `None` = anonymous/unpaired/GameStream → the backend's auto (slot-based) identity.
     fn set_client_identity(&mut self, _fingerprint: Option<[u8; 32]>) {}
+    /// The stable identity slot the backend resolved for the most recent [`create`](Self::create) —
+    /// the per-client id the identity policy assigned (`Some`), or `None` for shared/anonymous. The
+    /// registry reads it right after `create` to key the display's group **arrangement** (manual
+    /// per-slot positions) and to label the mgmt `/display/state` slot. Default `None`: a backend
+    /// with no per-client identity (Mutter/wlroots/gamescope) always auto-rows. Only KWin (per-slot
+    /// output naming) reports a real slot on Linux.
+    fn last_identity_slot(&self) -> Option<u32> {
+        None
+    }
+    /// Place the most-recently-[created](Self::create) output at `(x, y)` in the desktop coordinate
+    /// space (design `display-management.md` §6.2 — layout). The registry, which owns the display
+    /// **group**, computes the position from the whole group (auto-row or the console's manual
+    /// arrangement) and calls this right after `create`. Default no-op: only backends that can position
+    /// an output (KWin) implement it; the registry never calls it for the desktop origin `(0, 0)`, so a
+    /// single-display / first-of-group session issues no positioning at all. Best-effort — a failure
+    /// leaves the compositor's default placement.
+    fn apply_position(&mut self, _x: i32, _y: i32) {}
+    /// Take the topology **restore** action this [`create`](Self::create) prepared — the work that
+    /// un-does an `exclusive`/`primary` topology change (e.g. re-enable the physical outputs KWin
+    /// disabled). The registry lifts it into the display **group** so it runs **once, when the group's
+    /// last display is torn down** (design §6.1 — per-group restore), not when this one session's
+    /// display drops: a sibling `exclusive` session must not have the physical re-enabled under it.
+    /// Called right after `create`; the backend must not also run it itself. Default `None` — a backend
+    /// whose topology auto-reverts (Mutter `APPLY_TEMPORARY`) or that changes nothing has nothing to
+    /// hand off.
+    fn take_topology_restore(&mut self) -> Option<Box<dyn FnOnce() + Send>> {
+        None
+    }
+    /// Tell the backend whether this create will be the **first** display in its group — i.e. no
+    /// sibling of the same backend is already live (design §6.1). A backend that *establishes* the
+    /// group's topology (Mutter's sole-monitor `exclusive` `ApplyMonitorsConfig`) applies it only when
+    /// first; a later sibling **extends** into the already-exclusive desktop instead of re-clobbering it
+    /// (a fresh sole-monitor config would disable the first session's virtual output). Set by the
+    /// registry right before [`create`](Self::create). Default no-op: KWin recognises siblings at
+    /// runtime by output name (first-slot-wins + a group-aware disable filter), and single-display
+    /// backends never have a sibling.
+    fn set_first_in_group(&mut self, _first: bool) {}
+    /// Will a [`create`](Self::create) for the CURRENT request produce a registry-poolable
+    /// ([`DisplayOwnership::Owned`], keep-alive-able) display? The registry consults this **before**
+    /// its keep-alive reuse lookup, so it never hands a kept display of one flavor to a request of
+    /// another — specifically a gamescope managed/attach acquire must not reuse a kept **bare-spawn**
+    /// (they share the backend name `"gamescope"`). Default `true`; only gamescope overrides it,
+    /// returning `false` when the env selects attach/managed (consistent with the `ownership` its
+    /// `create` will report). See `design/gamemode-and-dedicated-sessions.md` A1.
+    fn poolable_now(&self) -> bool {
+        true
+    }
+    /// The resolved launch command carried on this backend instance (set via
+    /// [`set_launch_command`](Self::set_launch_command)). The registry reads it to key keep-alive reuse
+    /// on `(backend, mode, launch)` (`design/gamemode-and-dedicated-sessions.md` A2) — a kept display
+    /// running game A must never be handed to a session that asked to launch game B. Default `None`
+    /// (backends that never nest a command); only gamescope reports its `cmd`.
+    fn launch_command(&self) -> Option<String> {
+        None
+    }
+    /// Is the kept display's `node_id` still live, checked **before** the registry REUSES it on a
+    /// reconnect (`design/gamemode-and-dedicated-sessions.md` A2)? A `false` tells the registry to tear
+    /// the dead entry down and create fresh instead of handing back a corpse (which would then fail
+    /// capture and burn a retry). Default `true` (honest optimism — the [`mark_failed`] path is the
+    /// backstop for a display that dies between this check and first frame). Only gamescope overrides
+    /// it (its nested session dies when the game exits, independently of any compositor); KWin/Mutter
+    /// nodes die only with their compositor, which the session-epoch invalidation (A4) already reaps.
+    ///
+    /// [`mark_failed`]: crate::vdisplay::registry::mark_failed
+    fn kept_display_alive(&mut self, _node_id: u32) -> bool {
+        true
+    }
+}
+
+/// The **session epoch** — bumped whenever session detection observes a different compositor
+/// *instance*: an [`ActiveKind`] change, **or** a new compositor PID for the same kind (the
+/// Desktop→Game→Desktop bounce that brings up a fresh KWin/gamescope with an unrelated node-id space).
+/// Pooled displays stamp the epoch at creation; the registry only reuses an entry whose epoch still
+/// matches, and its linger timer reaps entries from dead epochs — so a switch can never hand back a
+/// node id that now means nothing (`design/gamemode-and-dedicated-sessions.md` A4).
+static SESSION_EPOCH: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
+
+/// The current [session epoch](SESSION_EPOCH). Read by the registry at acquire (to stamp new entries
+/// and gate reuse) and by its linger timer (to reap dead-epoch zombies).
+pub fn session_epoch() -> u64 {
+    SESSION_EPOCH.load(std::sync::atomic::Ordering::Relaxed)
+}
+
+/// Bump the [session epoch](SESSION_EPOCH) — call when session detection sees a new compositor
+/// instance (kind change, or same-kind new PID). Returns the new value.
+pub fn bump_session_epoch() -> u64 {
+    SESSION_EPOCH.fetch_add(1, std::sync::atomic::Ordering::Relaxed) + 1
+}
+
+/// The last-observed compositor instance `(kind, pid)`, so [`observe_session_instance`] can tell a
+/// genuine instance change from a stable re-detect.
+static LAST_INSTANCE: std::sync::Mutex<Option<(ActiveKind, Option<u32>)>> =
+    std::sync::Mutex::new(None);
+
+/// Observe the freshly-[detected](detect_active_session) live session and, if the compositor
+/// *instance* changed since the last observation — a different [`ActiveKind`], **or** the same kind
+/// with a new PID (a compositor restart / Desktop→Game→Desktop bounce) — bump the [session
+/// epoch](SESSION_EPOCH) and [invalidate](registry::invalidate_backend) the previous backend's kept
+/// displays, so a reconnect can never reuse a node id from the dead instance (A4). Idempotent per
+/// instance; the first observation just records the baseline. Cheap on the steady state (one mutex
+/// read); the registry lock is taken only on an actual change. Call from every site that detects the
+/// session (the per-connect resolve, the mid-stream watcher, the capture-loss re-detect).
+pub fn observe_session_instance(active: &ActiveSession) {
+    let cur = (active.kind, active.compositor_pid);
+    let mut last = LAST_INSTANCE.lock().unwrap_or_else(|e| e.into_inner());
+    if let Some(prev) = *last {
+        // Only a **desktop** compositor (KWin / Mutter / wlroots) instance change bumps the epoch +
+        // invalidates its kept displays — its PipeWire node dies with the compositor. A **gamescope**
+        // session (`ActiveKind::Gaming`) is NOT the epoch's subject: the box's game-mode / managed
+        // gamescope isn't pooled, and dedicated **spawns** are independent nested sessions whose nodes
+        // outlive any active-session change. So a game-mode gamescope restart, a Gaming↔Gaming winning-PID
+        // flap (e.g. B1 stopping the autologin before a dedicated spawn), or a coexisting-gamescope set
+        // change must NOT bump/invalidate — that would tear down a live/kept dedicated session (review
+        // findings #6/#7/#10). Gate the whole action on a desktop kind being involved.
+        if prev != cur && (is_desktop_kind(prev.0) || is_desktop_kind(cur.0)) {
+            // Invalidate only the OLD backend, and only if it was a desktop compositor (never gamescope).
+            if is_desktop_kind(prev.0) {
+                if let Some(old) = compositor_for_kind(prev.0) {
+                    registry::invalidate_backend(old.id());
+                }
+            }
+            let epoch = bump_session_epoch();
+            tracing::info!(
+                from = ?prev.0,
+                to = ?cur.0,
+                epoch,
+                "desktop compositor instance changed — session epoch bumped"
+            );
+        }
+    }
+    *last = Some(cur);
+}
+
+/// Is `kind` a **desktop** compositor (KWin / Mutter / wlroots) — one whose kept PipeWire outputs die
+/// with the compositor instance, so the session epoch tracks it? `Gaming` (gamescope) and `None` are
+/// not (gamescope spawns are independent nested sessions — see [`observe_session_instance`]).
+fn is_desktop_kind(kind: ActiveKind) -> bool {
+    matches!(
+        kind,
+        ActiveKind::DesktopKde | ActiveKind::DesktopGnome | ActiveKind::DesktopWlroots
+    )
 }
 
 /// Compositors punktfunk knows how to drive (plan §6).
@@ -204,6 +403,10 @@ pub struct SessionEnv {
 pub struct ActiveSession {
     pub kind: ActiveKind,
     pub env: SessionEnv,
+    /// PID of the winning compositor process (`None` when nothing live). The session watcher compares
+    /// it across polls so a **same-kind** compositor restart (Desktop→Game→Desktop) bumps the session
+    /// epoch — a fresh instance's node-id space is unrelated to the old one's (A4).
+    pub compositor_pid: Option<u32>,
 }
 
 impl ActiveSession {
@@ -216,6 +419,7 @@ impl ActiveSession {
                 dbus_session_bus_address: default_bus(&default_runtime_dir()),
                 ..Default::default()
             },
+            compositor_pid: None,
         }
     }
 }
@@ -267,6 +471,9 @@ pub fn detect_active_session() -> ActiveSession {
     // `pkill -x` discipline (exact, ≤15 chars so untruncated).
     let mut kind = ActiveKind::None;
     let mut best = 0u8;
+    // The winning compositor's PID — kept so a same-kind compositor RESTART (a new PID) bumps the
+    // session epoch (A4), not just a kind change.
+    let mut winning_pid: Option<u32> = None;
     if let Ok(entries) = std::fs::read_dir("/proc") {
         for e in entries.flatten() {
             let name = e.file_name();
@@ -291,9 +498,22 @@ pub fn detect_active_session() -> ActiveSession {
                 "sway" | "Hyprland" | "hyprland" | "river" => (ActiveKind::DesktopWlroots, 4),
                 _ => continue,
             };
+            let pid = name.parse::<u32>().ok();
             if prio > best {
                 best = prio;
                 kind = k;
+                winning_pid = pid;
+            } else if prio == best {
+                // Deterministic tie-break among same-top-priority processes: keep the LOWEST pid, so a
+                // duplicate same-kind compositor (two `kwin_wayland`) can't make `winning_pid` flap with
+                // `/proc` enumeration order — which `observe_session_instance` would misread as a
+                // compositor restart and tear a live display down (re-review low-severity note).
+                if let (Some(p), Some(w)) = (pid, winning_pid) {
+                    if p < w {
+                        kind = k;
+                        winning_pid = Some(p);
+                    }
+                }
             }
         }
     }
@@ -321,6 +541,7 @@ pub fn detect_active_session() -> ActiveSession {
             dbus_session_bus_address: dbus,
             xdg_current_desktop,
         },
+        compositor_pid: winning_pid,
     }
 }
 
@@ -481,6 +702,7 @@ pub enum GamescopeMode {
 /// default is a per-session bare spawn — the path that nests the client's launch command.
 #[cfg(target_os = "linux")]
 fn pick_gamescope_mode(
+    dedicated_launch: bool,
     force_managed: bool,
     attach_env: bool,
     node_env: bool,
@@ -492,6 +714,11 @@ fn pick_gamescope_mode(
         GamescopeMode::Managed
     } else if attach_env || node_env {
         GamescopeMode::Attach
+    } else if dedicated_launch {
+        // A dedicated game session always spawns its own headless gamescope at the client's mode,
+        // nesting just the game — outranking managed-infra / foreign-attach, but not the explicit
+        // operator MANAGED/ATTACH/NODE overrides above (debug/CI). (design/gamemode-and-dedicated-sessions.md §5.3)
+        GamescopeMode::Spawn
     } else if session_env || managed_infra {
         GamescopeMode::Managed
     } else if foreign_gamescope {
@@ -511,7 +738,7 @@ fn pick_gamescope_mode(
 /// nesting the session's launch command — the plain-distro default). `PUNKTFUNK_GAMESCOPE_MANAGED`
 /// forces managed over all of it.
 #[cfg(target_os = "linux")]
-pub fn apply_input_env(chosen: Compositor) {
+pub fn apply_input_env(chosen: Compositor, dedicated_launch: bool) {
     let _env_guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
     let backend = match chosen {
         Compositor::Gamescope => "gamescope",
@@ -525,6 +752,7 @@ pub fn apply_input_env(chosen: Compositor) {
     std::env::set_var("PUNKTFUNK_INPUT_BACKEND", backend);
     if chosen == Compositor::Gamescope {
         let mode = pick_gamescope_mode(
+            dedicated_launch,
             std::env::var_os("PUNKTFUNK_GAMESCOPE_MANAGED").is_some(),
             std::env::var_os("PUNKTFUNK_GAMESCOPE_ATTACH").is_some(),
             std::env::var_os("PUNKTFUNK_GAMESCOPE_NODE").is_some(),
@@ -556,7 +784,34 @@ pub fn apply_input_env(chosen: Compositor) {
     }
 }
 #[cfg(not(target_os = "linux"))]
-pub fn apply_input_env(_chosen: Compositor) {}
+pub fn apply_input_env(_chosen: Compositor, _dedicated_launch: bool) {}
+
+/// Should a game-launching session get a **dedicated** headless gamescope (`game_session=dedicated`
+/// policy, `design/gamemode-and-dedicated-sessions.md` B0)? True only when the session carries a
+/// launch, the policy selects `dedicated`, AND gamescope is actually available (else it degrades to
+/// `auto` honestly). Computed at the handshake and threaded into [`apply_input_env`] /
+/// [`resolve_compositor`] as a value (no new env knob — the `ENV_LOCK` discipline).
+pub fn wants_dedicated_game_session(has_launch: bool) -> bool {
+    use policy::GameSession;
+    if !has_launch || policy::prefs().game_session() != GameSession::Dedicated {
+        return false;
+    }
+    #[cfg(target_os = "linux")]
+    {
+        if gamescope::is_available() {
+            true
+        } else {
+            tracing::info!(
+                "game_session=dedicated but gamescope is unavailable — falling back to auto routing"
+            );
+            false
+        }
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        false // Windows: a launching session opens into the one desktop (no gamescope)
+    }
+}
 
 /// Will `vd.create` on this backend NEST the session's launch command itself (gamescope's bare
 /// spawn runs it inside the new gamescope)? When true the session must NOT also spawn the command
@@ -579,6 +834,27 @@ pub fn launch_into_gamescope_session(cmd: &str) -> Result<std::process::Child> {
     gamescope::launch_into_session(cmd)
 }
 
+/// B2: has a **dedicated** gamescope game session's game exited (its `node_id` doesn't reappear within a
+/// short window after capture loss)? The dedicated-spawn session ends cleanly on `true` instead of the
+/// capture-loss rebuild. Scoped to the session's OWN node so a coexisting gamescope doesn't mask the
+/// exit (review #4/#8). Always `false` off Linux.
+#[cfg(target_os = "linux")]
+pub fn dedicated_game_exited(node_id: u32) -> bool {
+    gamescope::game_session_exited(node_id)
+}
+#[cfg(not(target_os = "linux"))]
+pub fn dedicated_game_exited(_node_id: u32) -> bool {
+    false
+}
+
+/// Cancel any pending TV-session restore because a client (re)connected (review #3). No-op off Linux.
+#[cfg(target_os = "linux")]
+pub fn cancel_pending_tv_restore() {
+    gamescope::cancel_pending_restore();
+}
+#[cfg(not(target_os = "linux"))]
+pub fn cancel_pending_tv_restore() {}
+
 /// Detect the compositor to drive: explicit `PUNKTFUNK_COMPOSITOR` override (legacy / CI / forcing
 /// a backend for a test), else the **live session** ([`detect_active_session`] — so a Bazzite box
 /// follows Gaming↔Desktop switches), else a last-resort `XDG_CURRENT_DESKTOP` read.
@@ -713,6 +989,16 @@ pub fn start_restore_worker() -> std::sync::Arc<()> {
     std::sync::Arc::new(())
 }
 
+/// Recover a stranded TV takeover from a crashed previous host instance
+/// (`design/gamemode-and-dedicated-sessions.md` A3). Call once at `serve` startup, alongside
+/// [`start_restore_worker`]. No-op when no takeover was persisted (a clean start).
+#[cfg(target_os = "linux")]
+pub fn restore_takeover_on_startup() {
+    gamescope::restore_takeover_on_startup();
+}
+#[cfg(not(target_os = "linux"))]
+pub fn restore_takeover_on_startup() {}
+
 // The user-configurable management policy (keep-alive / topology / conflict / identity / layout),
 // layered above the per-compositor backends — platform-neutral (the mgmt API + both host paths read
 // it), so no cfg gate. See `design/display-management.md`.
@@ -729,6 +1015,11 @@ pub(crate) mod lifecycle;
 #[path = "vdisplay/registry.rs"]
 pub(crate) mod registry;
 
+// The pure display-arrangement engine (auto-row / manual → per-member positions), platform-neutral
+// and unit-tested; the registry (state readout) and the KWin position apply consume it.
+#[path = "vdisplay/layout.rs"]
+pub(crate) mod layout;
+
 /// Resolve a [`policy::Topology`] to a concrete value (never [`policy::Topology::Auto`]). `Auto`
 /// reproduces today's default: **extend** under an explicit `PUNKTFUNK_COMPOSITOR` pin (the CI/test
 /// posture, where the host isn't the sole desktop), else **exclusive** (Windows + the auto-detected
@@ -836,21 +1127,33 @@ mod tests {
     fn gamescope_mode_ladder() {
         use GamescopeMode::*;
         let pick = pick_gamescope_mode;
-        // (force_managed, attach_env, node_env, session_env, managed_infra, foreign_gamescope)
+        // (dedicated_launch, force_managed, attach_env, node_env, session_env, managed_infra, foreign_gamescope)
         // Plain distro, nothing running: bare spawn — the path that nests the launch command.
-        assert_eq!(pick(false, false, false, false, false, false), Spawn);
+        assert_eq!(pick(false, false, false, false, false, false, false), Spawn);
         // Bazzite/SteamOS (session infra present): managed, as validated live.
-        assert_eq!(pick(false, false, false, false, true, false), Managed);
-        assert_eq!(pick(false, false, false, false, true, true), Managed);
+        assert_eq!(
+            pick(false, false, false, false, false, true, false),
+            Managed
+        );
+        assert_eq!(pick(false, false, false, false, false, true, true), Managed);
         // Foreign gamescope on an infra-less box: attach and mirror it.
-        assert_eq!(pick(false, false, false, false, false, true), Attach);
+        assert_eq!(pick(false, false, false, false, false, false, true), Attach);
         // Operator-set PUNKTFUNK_GAMESCOPE_SESSION keeps managed even without detected infra.
-        assert_eq!(pick(false, false, false, true, false, false), Managed);
+        assert_eq!(
+            pick(false, false, false, false, true, false, false),
+            Managed
+        );
         // Explicit attach/node wins over infra…
-        assert_eq!(pick(false, true, false, false, true, false), Attach);
-        assert_eq!(pick(false, false, true, true, true, false), Attach);
+        assert_eq!(pick(false, false, true, false, false, true, false), Attach);
+        assert_eq!(pick(false, false, false, true, true, true, false), Attach);
         // …and force-managed wins over everything.
-        assert_eq!(pick(true, true, true, false, false, false), Managed);
+        assert_eq!(pick(false, true, true, true, false, false, false), Managed);
+        // A dedicated launch forces Spawn, outranking managed-infra + foreign-attach…
+        assert_eq!(pick(true, false, false, false, false, true, true), Spawn);
+        // …but the explicit operator overrides still win over dedicated.
+        assert_eq!(pick(true, true, false, false, false, true, false), Managed);
+        assert_eq!(pick(true, false, true, false, false, false, false), Attach);
+        assert_eq!(pick(true, false, false, true, false, false, false), Attach);
     }
 
     #[test]

crates/punktfunk-host/src/vdisplay/admission.rs

@@ -115,6 +115,31 @@ pub fn admit(req_identity: Option<[u8; 32]>) -> Admission {
     decide(effective_conflict(), req_identity, &table().lock().unwrap())
 }
 
+/// Pure core of [`preempt_same_identity`]: the stop flags of live sessions owned by the SAME client
+/// as `req_identity` (its own zombies). Testable over a slice (the public fn locks the global table).
+fn same_identity_stops(
+    req_identity: Option<[u8; 32]>,
+    live: &[LiveSession],
+) -> Vec<Arc<AtomicBool>> {
+    live.iter()
+        .filter(|s| same_client(s.identity, req_identity))
+        .map(|s| Arc::clone(&s.stop))
+        .collect()
+}
+
+/// Preempt this reconnecting client's OWN still-live session(s). A client has at most one live
+/// session, so a new connection from an already-registered identity is a **reconnect** — the old
+/// session is a zombie whose QUIC idle timer hasn't fired yet (an unwanted disconnect is only
+/// declared dead after `max_idle_timeout`, ~seconds later). Return its stop flag(s) so the caller
+/// signals them and waits the release grace: the zombie tears its display down, which (keep-alive on)
+/// lingers, and THIS reconnect **reuses** that kept display instead of landing on a fresh SECOND one
+/// (the "thrown onto a second display while the old one keeps streaming" bug). Anonymous (`None`)
+/// never matches — same limitation as `steal`/`reject`. Call this BEFORE [`admit`] and before this
+/// session registers itself, so it only ever signals a *prior* session's flag, never its own.
+pub fn preempt_same_identity(req_identity: Option<[u8; 32]>) -> Vec<Arc<AtomicBool>> {
+    same_identity_stops(req_identity, &table().lock().unwrap())
+}
+
 /// Register a now-admitted, live session; the returned guard removes it on drop (session end). Call
 /// AFTER [`admit`] (so a session never conflicts with itself) and once the mode + stop flag are known.
 pub fn register(
@@ -225,6 +250,20 @@ mod tests {
         ));
     }
 
+    #[test]
+    fn same_identity_stops_targets_own_zombie_only() {
+        let live = [
+            sess(Some(1), (2560, 1440, 60)), // this client's prior (zombie) session
+            sess(Some(2), (1920, 1080, 60)), // a different client
+        ];
+        // Reconnecting as client 1 → its own zombie's stop is returned (to preempt), not client 2's.
+        assert_eq!(same_identity_stops(fp(1), &live).len(), 1);
+        // A client with no prior session (fp 3) has nothing of its own to preempt.
+        assert_eq!(same_identity_stops(fp(3), &live).len(), 0);
+        // Anonymous never matches — we can't prove it's the same client.
+        assert_eq!(same_identity_stops(None, &live).len(), 0);
+    }
+
     #[test]
     fn join_targets_the_oldest_other_session() {
         let live = [

crates/punktfunk-host/src/vdisplay/layout.rs

@@ -0,0 +1,142 @@
+//! Pure display-**arrangement** engine (design: `design/display-management.md` §6.2). Given a
+//! group's members (in acquire order) and the `layout` policy, compute each member's top-left
+//! origin in the desktop coordinate space. No I/O, no OS types — the registry (for the
+//! `/display/state` readout) and the per-backend position apply both consume it, so the auto-row /
+//! manual math is defined and tested in exactly one place (the `pick_gamescope_mode` / `wiring_plan`
+//! discipline).
+//!
+//! * **auto-row** — left-to-right in acquire order, top-aligned: member *i* sits at
+//!   `x = Σ widths[0..i]`, `y = 0`. This is what compositors mostly do by default, made
+//!   deterministic.
+//! * **manual** — per-identity-slot offsets from [`Layout::positions`] (console-arranged): a member
+//!   whose stable identity slot has a stored position sits there; a member with no pin (no stored
+//!   position, or a shared/anonymous identity that has no slot) falls back to its auto-row origin, so
+//!   a half-arranged group never collapses everything onto the origin.
+//!
+//! Group membership + acquire order live in the registry ([`super::registry`]); this file only turns
+//! that ordered member list into positions.
+
+use super::policy::{Layout, LayoutMode};
+
+/// One display in a group, as the arranger sees it (given in acquire order).
+#[derive(Clone, Copy, Debug)]
+pub struct Member {
+    /// Stable per-client identity slot — the manual-layout key. `None` for a shared/anonymous
+    /// identity (no per-client slot), which can't carry a manual pin and therefore always auto-rows.
+    pub identity_slot: Option<u32>,
+    /// Pixel width, for auto-row `x` accumulation. Clamped at 0 (a bogus negative never shifts a
+    /// sibling left).
+    pub width: i32,
+}
+
+/// A member's resolved desktop-space top-left origin.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct Placement {
+    pub x: i32,
+    pub y: i32,
+}
+
+/// The auto-row origin of member `i`: the summed width of every prior member, top-aligned.
+fn auto_row_x(members: &[Member], i: usize) -> i32 {
+    members[..i].iter().map(|m| m.width.max(0)).sum()
+}
+
+/// Arrange `members` (in acquire order) per `layout`, returning one [`Placement`] per member in the
+/// same order. Pure — the single source of truth for auto-row / manual placement, shared by the
+/// state readout and (KWin) the per-backend position apply.
+pub fn arrange(members: &[Member], layout: &Layout) -> Vec<Placement> {
+    members
+        .iter()
+        .enumerate()
+        .map(|(i, m)| {
+            let auto = Placement {
+                x: auto_row_x(members, i),
+                y: 0,
+            };
+            match layout.mode {
+                LayoutMode::AutoRow => auto,
+                // A pinned member sits at its stored offset; an unpinned one falls back to auto-row.
+                LayoutMode::Manual => m
+                    .identity_slot
+                    .and_then(|slot| layout.positions.get(&slot.to_string()))
+                    .map(|p| Placement { x: p.x, y: p.y })
+                    .unwrap_or(auto),
+            }
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::vdisplay::policy::Position;
+    use std::collections::BTreeMap;
+
+    fn m(slot: Option<u32>, width: i32) -> Member {
+        Member {
+            identity_slot: slot,
+            width,
+        }
+    }
+
+    fn manual(pairs: &[(&str, i32, i32)]) -> Layout {
+        let mut positions = BTreeMap::new();
+        for (k, x, y) in pairs {
+            positions.insert(k.to_string(), Position { x: *x, y: *y });
+        }
+        Layout {
+            mode: LayoutMode::Manual,
+            positions,
+        }
+    }
+
+    #[test]
+    fn auto_row_accumulates_widths_top_aligned() {
+        let members = [m(Some(1), 2560), m(Some(2), 1920), m(None, 1280)];
+        let out = arrange(&members, &Layout::default()); // default = AutoRow
+        assert_eq!(
+            out,
+            vec![
+                Placement { x: 0, y: 0 },
+                Placement { x: 2560, y: 0 },
+                Placement { x: 4480, y: 0 },
+            ]
+        );
+    }
+
+    #[test]
+    fn manual_honors_pins_by_identity_slot() {
+        let members = [m(Some(1), 2560), m(Some(7), 1920)];
+        // Client 7 arranged to the LEFT of client 1 (crossing order reversed vs auto-row).
+        let layout = manual(&[("1", 1920, 0), ("7", 0, 0)]);
+        let out = arrange(&members, &layout);
+        assert_eq!(out[0], Placement { x: 1920, y: 0 });
+        assert_eq!(out[1], Placement { x: 0, y: 0 });
+    }
+
+    #[test]
+    fn manual_unpinned_and_slotless_fall_back_to_auto_row() {
+        let members = [m(Some(1), 2560), m(Some(9), 1920), m(None, 1280)];
+        // Only slot 1 is pinned; slot 9 has no stored pin; the third has no slot at all.
+        let layout = manual(&[("1", 100, 50)]);
+        let out = arrange(&members, &layout);
+        assert_eq!(out[0], Placement { x: 100, y: 50 }, "pinned");
+        assert_eq!(out[1], Placement { x: 2560, y: 0 }, "unpinned → auto-row");
+        assert_eq!(out[2], Placement { x: 4480, y: 0 }, "slotless → auto-row");
+    }
+
+    #[test]
+    fn empty_group_is_empty() {
+        assert!(arrange(&[], &Layout::default()).is_empty());
+        assert!(arrange(&[], &manual(&[("1", 0, 0)])).is_empty());
+    }
+
+    #[test]
+    fn negative_width_never_shifts_siblings_left() {
+        let members = [m(Some(1), -100), m(Some(2), 1920)];
+        let out = arrange(&members, &Layout::default());
+        let origin = Placement { x: 0, y: 0 };
+        assert_eq!(out[0], origin);
+        assert_eq!(out[1], origin, "clamped width contributes 0");
+    }
+}

crates/punktfunk-host/src/vdisplay/linux/gamescope.rs

@@ -14,7 +14,7 @@
 //! Input uses gamescope's own libei/EIS socket (`LIBEI_SOCKET`), relayed to the libei backend (see
 //! `inject/libei.rs`) — wired and live-validated.
 
-use super::{Mode, VirtualDisplay, VirtualOutput};
+use super::{DisplayOwnership, Mode, VirtualDisplay, VirtualOutput};
 use anyhow::{anyhow, bail, Context, Result};
 use std::process::{Child, Command, Stdio};
 use std::time::{Duration, Instant};
@@ -62,6 +62,18 @@ static PENDING_RESTORE: std::sync::Mutex<Option<Instant>> = std::sync::Mutex::ne
 /// instead of triggering a stop/relaunch.
 const RESTORE_DEBOUNCE: Duration = Duration::from_secs(5);
 
+/// Per-spawn instance counter (A5): each bare-spawn gets a unique id addressing its own log so two
+/// coexisting gamescopes (a kept lingering spawn + a fresh one) never parse each other's node id.
+static SPAWN_SEQ: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
+
+/// This spawn instance's log path, under `$XDG_RUNTIME_DIR` (per-user, tmpfs; falls back to `/tmp`
+/// only if unset). Replaces the shared `/tmp/punktfunk-gamescope.log` so concurrent spawns don't
+/// clobber each other's `stream available on node ID:` line.
+fn spawn_log_path(inst: u64) -> std::path::PathBuf {
+    let base = std::env::var("XDG_RUNTIME_DIR").unwrap_or_else(|_| "/tmp".to_string());
+    std::path::Path::new(&base).join(format!("punktfunk-gamescope-{inst}.log"))
+}
+
 /// systemd --user transient unit name for the host-managed gamescope-session-plus session.
 const SESSION_UNIT: &str = "punktfunk-gamescope";
 /// The gamescope-session-plus launcher script (Bazzite / SteamOS-like hosts).
@@ -82,6 +94,80 @@ const STEAMOS_SESSION_TARGET: &str = "gamescope-session.target";
 /// restart the physical session.
 static STEAMOS_TOOK_OVER: std::sync::Mutex<bool> = std::sync::Mutex::new(false);
 
+/// Persisted takeover state (`design/gamemode-and-dedicated-sessions.md` A3): the takeover mechanics
+/// ([`STOPPED_AUTOLOGIN`] / [`STEAMOS_TOOK_OVER`]) are process memory, so a host **crash** mid-stream
+/// would strand the box out of gaming mode with no restore. Mirroring the statics to a file lets
+/// [`restore_takeover_on_startup`] put the TV back after a restart.
+#[derive(serde::Serialize, serde::Deserialize, Default)]
+struct TakeoverState {
+    /// Autologin `gamescope-session-plus@*.service` units we stopped (to restart on restore).
+    stopped_autologin: Vec<String>,
+    /// Whether we took over SteamOS's `gamescope-session.target` (restore = remove drop-in + restart).
+    steamos: bool,
+}
+
+/// Path of the persisted [`TakeoverState`], under `$XDG_RUNTIME_DIR` (per-user, 0700, tmpfs — cleared
+/// on reboot, which is correct: a reboot restarts the autologin itself).
+fn takeover_state_path() -> std::path::PathBuf {
+    let base = std::env::var("XDG_RUNTIME_DIR").unwrap_or_else(|_| "/tmp".to_string());
+    std::path::Path::new(&base).join("punktfunk-session-takeover.json")
+}
+
+/// Persist the current takeover mechanics so a host crash doesn't strand the box out of gaming mode.
+/// Best-effort (a write failure just loses crash-restore, not correctness).
+fn persist_takeover() {
+    let state = TakeoverState {
+        stopped_autologin: STOPPED_AUTOLOGIN
+            .lock()
+            .unwrap_or_else(|e| e.into_inner())
+            .clone(),
+        steamos: *STEAMOS_TOOK_OVER.lock().unwrap_or_else(|e| e.into_inner()),
+    };
+    if state.stopped_autologin.is_empty() && !state.steamos {
+        clear_takeover();
+        return;
+    }
+    if let Ok(bytes) = serde_json::to_vec(&state) {
+        let _ = std::fs::write(takeover_state_path(), bytes);
+    }
+}
+
+/// Remove the persisted takeover file (after a completed restore, or when there's nothing to restore).
+fn clear_takeover() {
+    let _ = std::fs::remove_file(takeover_state_path());
+}
+
+/// On host startup, restore the TV's gaming session if a previous host instance took it over and
+/// crashed before restoring (`design/gamemode-and-dedicated-sessions.md` A3). Loads the persisted
+/// [`TakeoverState`] into the statics and schedules a restore after a short reconnect grace (so a
+/// client reconnecting right after the restart keeps the streamed session instead of bouncing the
+/// box back to gaming mode). No-op when no takeover file exists (a clean start). Call once from
+/// `serve` alongside [`start_restore_worker`].
+pub fn restore_takeover_on_startup() {
+    let Ok(bytes) = std::fs::read(takeover_state_path()) else {
+        return; // no takeover file — clean start
+    };
+    let Ok(state) = serde_json::from_slice::<TakeoverState>(&bytes) else {
+        clear_takeover();
+        return;
+    };
+    if state.stopped_autologin.is_empty() && !state.steamos {
+        clear_takeover();
+        return;
+    }
+    tracing::warn!(
+        units = ?state.stopped_autologin,
+        steamos = state.steamos,
+        "gamescope: found a stranded takeover from a previous host instance — scheduling TV restore"
+    );
+    *STOPPED_AUTOLOGIN.lock().unwrap_or_else(|e| e.into_inner()) = state.stopped_autologin;
+    *STEAMOS_TOOK_OVER.lock().unwrap_or_else(|e| e.into_inner()) = state.steamos;
+    // A generous grace so a client reconnecting right after the restart cancels it (create_managed_session
+    // clears PENDING_RESTORE) and keeps the streamed session rather than bouncing to gaming mode.
+    *PENDING_RESTORE.lock().unwrap_or_else(|e| e.into_inner()) =
+        Some(Instant::now() + Duration::from_secs(15));
+}
+
 impl GamescopeDisplay {
     pub fn new() -> Result<Self> {
         Ok(GamescopeDisplay::default())
@@ -97,6 +183,32 @@ impl VirtualDisplay for GamescopeDisplay {
         self.cmd = cmd;
     }
 
+    fn poolable_now(&self) -> bool {
+        // Only a bare SPAWN is registry-poolable (its `create` reports `Owned`); managed
+        // (`PUNKTFUNK_GAMESCOPE_SESSION`) and attach (`PUNKTFUNK_GAMESCOPE_NODE`) report
+        // `SessionManaged`/`External`, so the registry must not reuse a kept spawn for them (same
+        // backend name). Mirrors [`crate::vdisplay::launch_is_nested`]; read under the env lock the
+        // sub-mode ladder writes these keys under.
+        crate::vdisplay::with_env_lock(|| {
+            std::env::var_os("PUNKTFUNK_GAMESCOPE_SESSION").is_none()
+                && std::env::var_os("PUNKTFUNK_GAMESCOPE_NODE").is_none()
+        })
+    }
+
+    fn launch_command(&self) -> Option<String> {
+        // The registry keys keep-alive reuse on (backend, mode, launch): a kept bare-spawn running
+        // game A must never be reused for a session launching game B (A2).
+        self.cmd.clone()
+    }
+
+    fn kept_display_alive(&mut self, node_id: u32) -> bool {
+        // The nested gamescope dies when its game exits (independently of any compositor), leaving a
+        // dead pooled node. Before the registry reuses that node on a reconnect, confirm it still
+        // exists on the daemon; a `false` makes the registry recreate instead of handing back a corpse
+        // (which would then burn a ~10 s first-frame retry before `mark_failed` recovered it).
+        gamescope_node_present(node_id)
+    }
+
     fn create(&mut self, mode: Mode) -> Result<VirtualOutput> {
         // Host-managed gamescope-session-plus at the CLIENT's mode (the Bazzite path): launch the
         // full Steam-Deck-UI session headless at the client's resolution + refresh — so games SEE
@@ -121,26 +233,51 @@ impl VirtualDisplay for GamescopeDisplay {
             };
             point_injector_at_eis();
             tracing::info!(node_id, "gamescope: attaching to existing PipeWire node");
+            // ATTACH = mirror a foreign gamescope we don't own → External (no keep-alive/reuse).
             return Ok(VirtualOutput {
                 node_id,
                 remote_fd: None,
                 preferred_mode: Some((mode.width, mode.height, mode.refresh_hz)),
                 keepalive: Box::new(()),
+                ownership: DisplayOwnership::External,
+                reused_gen: None,
             });
         }
         check_gamescope_version(); // diagnostic only — warns on known-deadlock-prone versions
-        let proc = GamescopeProc(spawn(
+                                   // B1: a dedicated STEAM launch needs Steam's single instance free. If the box autologged into
+                                   // game mode (Bazzite) its Steam holds the instance, and a nested second Steam would see the
+                                   // first and exit (crashing the spawn) — so free the autologin session first. Its restore is the
+                                   // A3 takeover machinery (recorded in STOPPED_AUTOLOGIN + persisted; restarted on session end via
+                                   // schedule_restore_tv_session). Non-Steam launches don't conflict, so they skip this.
+        if self.cmd.as_deref().is_some_and(is_steam_launch) {
+            stop_autologin_sessions();
+        }
+        // A5: a per-spawn instance id addresses this spawn's log + node discovery, so two coexisting
+        // bare-spawns (a kept lingering one + a fresh one) never parse each other's node id from a
+        // shared log. The nested-command's LIBEI relay stays on the global path (per-instance input
+        // isolation is `design/gamescope-multiuser.md` scope, not addressed here).
+        let inst = SPAWN_SEQ.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+        let log = spawn_log_path(inst);
+        let child = spawn(
             mode.width,
             mode.height,
             mode.refresh_hz.max(1),
             self.cmd.as_deref(),
-        )?);
+            &log,
+        )?;
+        let child_pid = child.id();
+        let proc = GamescopeProc {
+            child,
+            log: log.clone(),
+        };
         // gamescope creates its PipeWire node a moment after start; poll for it (the proc is held
-        // alive meanwhile, and killed if we give up).
-        let node_id = wait_for_node(Duration::from_secs(15)).ok_or_else(|| {
+        // alive meanwhile, and killed if we give up). Discovery reads THIS spawn's log, and the
+        // fallback is scoped to this spawn's process tree.
+        let node_id = wait_for_node(Duration::from_secs(15), &log, child_pid).ok_or_else(|| {
             anyhow!(
                 "gamescope PipeWire node did not appear within 15s — gamescope may have failed to \
-                 start or headless capture is unsupported on this GPU/driver (see /tmp/punktfunk-gamescope.log)"
+                 start or headless capture is unsupported on this GPU/driver (see {})",
+                log.display()
             )
         })?;
         tracing::info!(
@@ -150,12 +287,12 @@ impl VirtualDisplay for GamescopeDisplay {
             hz = mode.refresh_hz,
             "gamescope virtual output ready"
         );
-        Ok(VirtualOutput {
+        // Bare SPAWN: we own the nested gamescope process → registry-poolable (keep-alive-able).
+        Ok(VirtualOutput::owned(
             node_id,
-            remote_fd: None,
-            preferred_mode: Some((mode.width, mode.height, mode.refresh_hz)),
-            keepalive: Box::new(proc),
-        })
+            Some((mode.width, mode.height, mode.refresh_hz)),
+            Box::new(proc),
+        ))
     }
 }
 
@@ -192,12 +329,7 @@ fn create_managed_session(client: &str, mode: Mode) -> Result<VirtualOutput> {
                 hz = mode.refresh_hz,
                 "gamescope session: reusing the running session (same mode — no Steam restart)"
             );
-            return Ok(VirtualOutput {
-                node_id,
-                remote_fd: None,
-                preferred_mode: Some((mode.width, mode.height, mode.refresh_hz)),
-                keepalive: Box::new(()),
-            });
+            return Ok(managed_output(node_id, mode));
         }
         tracing::warn!("gamescope session: tracked session has no live node — relaunching");
         *guard = None;
@@ -218,12 +350,23 @@ fn create_managed_session(client: &str, mode: Mode) -> Result<VirtualOutput> {
         hz = mode.refresh_hz,
         "gamescope session: launched gamescope-session-plus at the client's mode"
     );
-    Ok(VirtualOutput {
+    Ok(managed_output(node_id, mode))
+}
+
+/// The [`VirtualOutput`] for a managed / SteamOS-takeover session: a box-level session whose restore
+/// lifecycle is (at Part A1) the gamescope module's own machinery (`schedule_restore_tv_session`), so
+/// it is [`DisplayOwnership::SessionManaged`] — the registry passes it through (no pooling), and the
+/// capturer's unit keepalive tears nothing down on drop. (Part A3 replaces the unit keepalive with a
+/// real `ManagedSessionHandle` and flips this to `Owned`.)
+fn managed_output(node_id: u32, mode: Mode) -> VirtualOutput {
+    VirtualOutput {
         node_id,
         remote_fd: None,
         preferred_mode: Some((mode.width, mode.height, mode.refresh_hz)),
         keepalive: Box::new(()),
-    })
+        ownership: DisplayOwnership::SessionManaged,
+        reused_gen: None,
+    }
 }
 
 /// SteamOS detection: its session launcher is present and Bazzite's session-plus is NOT (so the
@@ -483,12 +626,7 @@ fn create_managed_session_steamos(mode: Mode) -> Result<VirtualOutput> {
                 hz = mode.refresh_hz,
                 "gamescope (SteamOS): reusing the headless session (same mode — no Steam restart)"
             );
-            return Ok(VirtualOutput {
-                node_id,
-                remote_fd: None,
-                preferred_mode: Some((mode.width, mode.height, mode.refresh_hz)),
-                keepalive: Box::new(()),
-            });
+            return Ok(managed_output(node_id, mode));
         }
         *guard = None; // tracked session lost its node — fall through to a clean restart
     }
@@ -497,9 +635,11 @@ fn create_managed_session_steamos(mode: Mode) -> Result<VirtualOutput> {
     systemctl_user(&["daemon-reload"]);
     systemctl_user(&["restart", STEAMOS_SESSION_TARGET]);
     *STEAMOS_TOOK_OVER.lock().unwrap_or_else(|e| e.into_inner()) = true;
-    // gamescope's node appears within a few seconds of the restart; Steam's first FRAME is slower
-    // (Big Picture cold start) and is awaited by the caller's first-frame retry loop.
-    let node_id = wait_for_node(Duration::from_secs(30)).ok_or_else(|| {
+    persist_takeover(); // A3: survive a host crash mid-stream
+                        // gamescope's node appears within a few seconds of the restart; Steam's first FRAME is slower
+                        // (Big Picture cold start) and is awaited by the caller's first-frame retry loop. The managed
+                        // session logs to journald (not a per-spawn file), so poll `find_gamescope_node` directly.
+    let node_id = poll_managed_node(Duration::from_secs(30)).ok_or_else(|| {
         anyhow!(
             "SteamOS headless gamescope node did not appear within 30s after restarting \
              {STEAMOS_SESSION_TARGET} — check `journalctl --user -u gamescope-session.service`"
@@ -518,12 +658,7 @@ fn create_managed_session_steamos(mode: Mode) -> Result<VirtualOutput> {
         hz = mode.refresh_hz,
         "gamescope (SteamOS): took over gamescope-session.target headless at the client's mode"
     );
-    Ok(VirtualOutput {
-        node_id,
-        remote_fd: None,
-        preferred_mode: Some((mode.width, mode.height, mode.refresh_hz)),
-        keepalive: Box::new(()),
-    })
+    Ok(managed_output(node_id, mode))
 }
 
 /// ATTACH at the CLIENT's resolution: ensure the box's own game-mode session is running at `mode`'s
@@ -670,11 +805,31 @@ fn running_autologin_gamescope_unit() -> Option<String> {
         .map(|u| u.to_string())
 }
 
+/// Tear a gamescope `systemd --user` unit down with **SIGKILL** rather than the default SIGTERM stop
+/// (`design/gamemode-and-dedicated-sessions.md` A3 / `session-aware-host-followups.md` #1): the
+/// hypothesis — validated as the fix on the F44 repro box `.181` — is that gamescope's SIGTERM
+/// teardown handler (the one that SIGSEGVs, exit 139) LEAKS the NVIDIA GPU context, after which every
+/// subsequent gamescope fails `vkCreateDevice` with `VK_ERROR_INITIALIZATION_FAILED` (-3) until a
+/// reboot. SIGKILL skips that handler so the driver reclaims the context cleanly via normal process
+/// exit. Follow with `stop` + `reset-failed` to clear the unit's state so a relaunch is clean.
+fn kill_unit(unit: &str) {
+    let _ = Command::new("systemctl")
+        .args(["--user", "kill", "--signal=SIGKILL", unit])
+        .status();
+    let _ = Command::new("systemctl")
+        .args(["--user", "stop", unit])
+        .status();
+    let _ = Command::new("systemctl")
+        .args(["--user", "reset-failed", unit])
+        .status();
+}
+
 /// Stop every running autologin gaming-mode session (`gamescope-session-plus@*.service`) so its
 /// single-instance Steam is free for our own host-managed session. Records the units so
 /// [`schedule_restore_tv_session`] can restart them on disconnect. Our own session is the transient
 /// `punktfunk-gamescope` unit (not a `@`-instance), so it's never matched here. No-op when nothing
-/// is autologged in (e.g. a box that boots headless).
+/// is autologged in (e.g. a box that boots headless). Uses the **SIGKILL** teardown ([`kill_unit`])
+/// to avoid the F44 GPU-context leak that the autologin's SIGTERM stop triggers.
 fn stop_autologin_sessions() {
     let Ok(out) = Command::new("systemctl")
         .args([
@@ -694,12 +849,10 @@ fn stop_autologin_sessions() {
     for line in String::from_utf8_lossy(&out.stdout).lines() {
         if let Some(unit) = line.split_whitespace().next() {
             if unit.starts_with("gamescope-session-plus@") && unit.ends_with(".service") {
-                let _ = Command::new("systemctl")
-                    .args(["--user", "stop", unit])
-                    .status();
+                kill_unit(unit); // SIGKILL teardown — avoid the F44 GPU-context leak
                 tracing::info!(
                     unit,
-                    "freed Steam: stopped the autologin gaming session for this stream"
+                    "freed Steam: SIGKILL-stopped the autologin gaming session for this stream"
                 );
                 stopped.push(unit.to_string());
             }
@@ -707,15 +860,57 @@ fn stop_autologin_sessions() {
     }
     if !stopped.is_empty() {
         *STOPPED_AUTOLOGIN.lock().unwrap_or_else(|e| e.into_inner()) = stopped;
+        persist_takeover(); // A3: survive a host crash mid-stream
     }
 }
 
-/// Client disconnected: **schedule** a debounced restore of the TV's autologin gaming session(s) we
-/// stopped on connect — the actual restore fires [`RESTORE_DEBOUNCE`] later (via [`start_restore_worker`])
-/// unless a client reconnects first, which cancels it and reuses the warm managed session. Debouncing
-/// means at most one gamescope stop/relaunch per quiet period instead of one per disconnect — the
-/// per-connect churn is what leaked GPU context on F44. No-op when nothing was stolen (non-Bazzite /
-/// headless box). Idempotent / safe to call on every session end.
+/// Cancel any pending TV-session restore — a client has (re)connected, so the box must stay in the
+/// streamed session, not bounce back to gaming mode. This covers the **keep-alive reuse** reconnect
+/// path (a kept dedicated / managed gamescope), which never calls `create_managed_session` (where the
+/// managed path already clears `PENDING_RESTORE`) — so without this, a dedicated Steam reconnect within
+/// the linger window would restart the autologin *underneath* the live session (review finding #3).
+/// Called from the connect path (native `resolve_compositor`, GameStream `open_gs_virtual_source`).
+/// No-op when nothing is pending; the stopped-unit list stays armed for a later real disconnect.
+pub fn cancel_pending_restore() {
+    let mut g = PENDING_RESTORE.lock().unwrap_or_else(|e| e.into_inner());
+    if g.is_some() {
+        *g = None;
+        tracing::info!(
+            "gamescope: client (re)connected — cancelled the pending TV-session restore"
+        );
+    }
+}
+
+/// The delay before restoring the TV's autologin session after the last client disconnects — the
+/// display-management **keep-alive policy**, replacing the hardcoded [`RESTORE_DEBOUNCE`]
+/// (`design/gamemode-and-dedicated-sessions.md` A3). The managed gamescope session is a single
+/// box-level singleton (not a registry pool entry — A1), so its keep-alive lives here rather than in
+/// the registry, but reads the same policy the pooled backends do:
+///   * `off` → restore immediately (0 s);
+///   * `duration(s)` → restore after `s`;
+///   * `forever` → **`None`**: never auto-restore — the managed session is HELD until host stop or a
+///     manual return to gaming mode (the `gaming-rig` "the TV model" story, now truthful on gamescope);
+///   * unconfigured → the historical 5 s [`RESTORE_DEBOUNCE`] (bit-for-bit today's behavior).
+fn restore_delay() -> Option<Duration> {
+    use crate::vdisplay::policy::{self, Linger};
+    match policy::prefs()
+        .configured_effective()
+        .map(|e| e.keep_alive.linger())
+    {
+        Some(Linger::Immediate) => Some(Duration::from_secs(0)),
+        Some(Linger::For(d)) => Some(d),
+        Some(Linger::Forever) => None,
+        None => Some(RESTORE_DEBOUNCE),
+    }
+}
+
+/// Client disconnected: **schedule** a policy-timed restore of the TV's autologin gaming session(s) we
+/// stopped on connect ([`restore_delay`], via [`start_restore_worker`]) — unless a client reconnects
+/// first, which cancels it and reuses the warm managed session. Debouncing means at most one gamescope
+/// stop/relaunch per quiet period instead of one per disconnect — the per-connect churn is what leaked
+/// GPU context on F44. Under `keep_alive=forever` ([`restore_delay`] `None`) NO restore is scheduled:
+/// the managed session is pinned (gaming-rig). No-op when nothing was stolen (non-Bazzite / headless
+/// box). Idempotent / safe to call on every session end.
 pub fn schedule_restore_tv_session() {
     let nothing_to_restore = STOPPED_AUTOLOGIN
         .lock()
@@ -725,12 +920,24 @@ pub fn schedule_restore_tv_session() {
     if nothing_to_restore {
         return; // nothing was taken over → nothing to restore (also the non-managed path)
     }
-    *PENDING_RESTORE.lock().unwrap_or_else(|e| e.into_inner()) =
-        Some(Instant::now() + RESTORE_DEBOUNCE);
-    tracing::info!(
-        secs = RESTORE_DEBOUNCE.as_secs(),
-        "gamescope: scheduled debounced TV-session restore (cancelled if a client reconnects)"
-    );
+    match restore_delay() {
+        None => {
+            // keep_alive=forever → pin the managed session; leave PENDING_RESTORE unset.
+            *PENDING_RESTORE.lock().unwrap_or_else(|e| e.into_inner()) = None;
+            tracing::info!(
+                "gamescope: keep-alive=forever — managed session held (no TV-restore scheduled; \
+                 return to gaming mode or restart the host to free it)"
+            );
+        }
+        Some(delay) => {
+            *PENDING_RESTORE.lock().unwrap_or_else(|e| e.into_inner()) =
+                Some(Instant::now() + delay);
+            tracing::info!(
+                secs = delay.as_secs(),
+                "gamescope: scheduled TV-session restore (keep-alive policy; cancelled on reconnect)"
+            );
+        }
+    }
 }
 
 /// Tear down our host-managed session (freeing Steam) and restart the autologin gaming session(s)
@@ -745,6 +952,7 @@ fn do_restore_tv_session() {
         let mut took = STEAMOS_TOOK_OVER.lock().unwrap_or_else(|e| e.into_inner());
         if *took {
             *took = false;
+            clear_takeover(); // A3: takeover undone — drop the persisted crash-restore marker
             *MANAGED_SESSION.lock().unwrap_or_else(|e| e.into_inner()) = None;
             remove_steamos_dropin();
             systemctl_user(&["daemon-reload"]);
@@ -770,6 +978,7 @@ fn do_restore_tv_session() {
     if units.is_empty() {
         return; // nothing was stolen → nothing to restore (also the non-Bazzite path)
     }
+    clear_takeover(); // A3: takeover consumed — drop the persisted crash-restore marker
     stop_session(SESSION_UNIT); // our gamescope/Steam session, so Steam is free for the autologin
     *MANAGED_SESSION.lock().unwrap_or_else(|e| e.into_inner()) = None;
     // Only bring the gaming autologin BACK if the box is still meant to be in gaming mode. If the
@@ -923,12 +1132,10 @@ fn launch_session(client: &str, unit_name: &str, mode: Mode) -> Result<u32> {
     }
 }
 
-/// Stop the host-managed session's transient unit (best-effort) and clear the EIS relay so a dead
-/// session's socket name can't be reconnected.
+/// Stop the host-managed session's transient unit ([`kill_unit`] — SIGKILL teardown to avoid the F44
+/// GPU-context leak) and clear the EIS relay so a dead session's socket name can't be reconnected.
 fn stop_session(unit_name: &str) {
-    let _ = Command::new("systemctl")
-        .args(["--user", "stop", unit_name])
-        .status();
+    kill_unit(unit_name);
     let _ = std::fs::remove_file(ei_socket_file());
 }
 
@@ -949,13 +1156,36 @@ pub fn ei_socket_file() -> std::path::PathBuf {
     }
 }
 
+/// Shape a resolved launch command for a bare-spawn gamescope session. A Steam URI launch
+/// (`steam steam://rungameid/<id>`, produced by `library::command_for`) gets `-silent` inserted so
+/// the game is the gamescope focus with no Steam client window to navigate
+/// (`design/gamemode-and-dedicated-sessions.md` §5.3). Operator-typed custom commands and non-Steam
+/// launches are returned unchanged. Idempotent (never double-inserts `-silent`). Pure + unit-tested.
+/// Does this resolved launch command start Steam (`steam … steam://…`)? Such a launch needs Steam's
+/// single instance free before a dedicated spawn (B1). Pure + unit-tested.
+fn is_steam_launch(cmd: &str) -> bool {
+    let mut it = cmd.split_whitespace();
+    it.next() == Some("steam") && cmd.contains("steam://")
+}
+
+fn shape_dedicated_command(app: &str) -> String {
+    let mut it = app.split_whitespace();
+    if it.next() == Some("steam") {
+        let rest: Vec<&str> = it.collect();
+        if !rest.contains(&"-silent") && rest.iter().any(|t| t.starts_with("steam://")) {
+            return format!("steam -silent {}", rest.join(" "));
+        }
+    }
+    app.to_string()
+}
+
 /// Spawn `gamescope --backend headless -W w -H h -r hz -- <app>`. The app comes from
 /// `PUNKTFUNK_GAMESCOPE_APP` (default a no-op that just keeps gamescope alive — set it to a real
 /// game/GL app for actual content, e.g. `steam -gamepadui` for the SteamOS-like session).
-/// stdout/stderr go to `/tmp/punktfunk-gamescope.log`. The app is launched through a tiny shell
-/// wrapper that relays gamescope's `LIBEI_SOCKET` (set for its children) to [`ei_socket_file`]
+/// stdout/stderr go to `log` (this spawn's per-instance log, A5). The app is launched through a tiny
+/// shell wrapper that relays gamescope's `LIBEI_SOCKET` (set for its children) to [`ei_socket_file`]
 /// so the input injector can connect to gamescope's EIS server from outside.
-fn spawn(w: u32, h: u32, hz: u32, cmd: Option<&str>) -> Result<Child> {
+fn spawn(w: u32, h: u32, hz: u32, cmd: Option<&str>, log: &std::path::Path) -> Result<Child> {
     // A non-empty per-session command (set via `set_launch_command`) wins; else the
     // `PUNKTFUNK_GAMESCOPE_APP` env var (the documented manual fallback); else a no-op that keeps
     // gamescope alive. Each level is taken only if non-empty, so a blank per-session cmd transparently
@@ -970,6 +1200,9 @@ fn spawn(w: u32, h: u32, hz: u32, cmd: Option<&str>) -> Result<Child> {
         })
         .filter(|s| !s.trim().is_empty())
         .unwrap_or_else(|| "sleep infinity".to_string());
+    // Dedicated-launch command shaping (Part B): a Steam URI runs with `-silent` so the game is the
+    // gamescope focus with no Steam client window to navigate.
+    let app = shape_dedicated_command(&app);
     let relay = ei_socket_file();
     let _ = std::fs::remove_file(&relay); // stale socket path from a previous session
     let mut cmd = Command::new("gamescope");
@@ -990,14 +1223,14 @@ fn spawn(w: u32, h: u32, hz: u32, cmd: Option<&str>) -> Result<Child> {
         .args(app.split_whitespace())
         // Prefer the NVIDIA GL vendor for the nested session (harmless on a pure-NVIDIA box).
         .env("__GLX_VENDOR_LIBRARY_NAME", "nvidia");
-    if let Ok(log) = std::fs::File::create("/tmp/punktfunk-gamescope.log") {
-        if let Ok(log2) = log.try_clone() {
-            cmd.stdout(Stdio::from(log)).stderr(Stdio::from(log2));
+    if let Ok(logf) = std::fs::File::create(log) {
+        if let Ok(log2) = logf.try_clone() {
+            cmd.stdout(Stdio::from(logf)).stderr(Stdio::from(log2));
         }
     } else {
         cmd.stdout(Stdio::null()).stderr(Stdio::null());
     }
-    tracing::info!(w, h, hz, %app, "spawning gamescope (headless)");
+    tracing::info!(w, h, hz, %app, log = %log.display(), "spawning gamescope (headless)");
     cmd.spawn()
         .context("spawn gamescope (is it installed? `apt install gamescope`)")
 }
@@ -1006,22 +1239,59 @@ fn spawn(w: u32, h: u32, hz: u32, cmd: Option<&str>) -> Result<Child> {
 /// line `stream available on node ID: N` (its node carries `node.name=gamescope` on TWO objects
 /// — the adapter and the inner stream — and only the advertised id is the correct capture
 /// target). Falls back to `pw-dump` discovery if the log line doesn't show.
-fn wait_for_node(timeout: Duration) -> Option<u32> {
+/// B2 (game-exit detection): confirm a **dedicated** gamescope session's game has exited. gamescope is
+/// a single-app compositor — it exits when its nested app exits — so once capture is lost, THIS
+/// session's `node_id` not reappearing within a short confirmation window means the game quit (vs. a
+/// transient PipeWire hiccup). Scoped to the session's own `node_id` (via [`gamescope_node_present`]),
+/// so a **coexisting** gamescope (a second dedicated session, or the box's game-mode gamescope beside a
+/// non-Steam dedicated launch) doesn't mask the exit (review findings #4/#8). Returns `true` when the
+/// node stays absent across the window.
+pub fn game_session_exited(node_id: u32) -> bool {
+    let deadline = Instant::now() + Duration::from_millis(1500);
+    loop {
+        if gamescope_node_present(node_id) {
+            return false; // OUR node is (still) present → not an exit (transient loss)
+        }
+        if Instant::now() >= deadline {
+            return true; // our node stayed gone across the window → the game exited
+        }
+        std::thread::sleep(Duration::from_millis(250));
+    }
+}
+
+/// Poll [`find_gamescope_node`] (unscoped) up to `timeout` — for the managed / SteamOS session, which
+/// logs to journald (no per-spawn file) and is single-session (no scoping needed).
+fn poll_managed_node(timeout: Duration) -> Option<u32> {
     let deadline = Instant::now() + timeout;
     loop {
-        if let Some(id) = node_from_log() {
+        if let Some(id) = find_gamescope_node() {
             return Some(id);
         }
         if Instant::now() >= deadline {
-            return find_gamescope_node(); // last-resort fallback
+            return None;
         }
         std::thread::sleep(Duration::from_millis(300));
     }
 }
 
-/// Parse `stream available on node ID: N` from the spawned gamescope's log (ANSI-colored).
-fn node_from_log() -> Option<u32> {
-    let log = std::fs::read_to_string("/tmp/punktfunk-gamescope.log").ok()?;
+fn wait_for_node(timeout: Duration, log: &std::path::Path, child_pid: u32) -> Option<u32> {
+    let deadline = Instant::now() + timeout;
+    loop {
+        if let Some(id) = node_from_log(log) {
+            return Some(id);
+        }
+        if Instant::now() >= deadline {
+            // Last-resort fallback scoped to THIS spawn's process tree (A5), so a coexisting gamescope's
+            // node isn't picked by mistake.
+            return find_gamescope_node_scoped(Some(child_pid));
+        }
+        std::thread::sleep(Duration::from_millis(300));
+    }
+}
+
+/// Parse `stream available on node ID: N` from a spawned gamescope's per-instance log (ANSI-colored).
+fn node_from_log(log: &std::path::Path) -> Option<u32> {
+    let log = std::fs::read_to_string(log).ok()?;
     for line in log.lines().rev() {
         if let Some(pos) = line.find("stream available on node ID:") {
             let tail = &line[pos + "stream available on node ID:".len()..];
@@ -1034,6 +1304,27 @@ fn node_from_log() -> Option<u32> {
     None
 }
 
+/// Is a PipeWire node with exactly `node_id` present on the default daemon right now? Used by the
+/// keep-alive reuse liveness probe ([`GamescopeDisplay::kept_display_alive`]): a kept gamescope node
+/// vanishes when its nested game exits, so a missing id means "recreate, don't reuse the corpse".
+fn gamescope_node_present(node_id: u32) -> bool {
+    let Ok(out) = Command::new("pw-dump").arg(node_id.to_string()).output() else {
+        // pw-dump unavailable → don't block reuse (mark_failed is the backstop on a genuinely dead node).
+        return true;
+    };
+    let Ok(dump) = serde_json::from_slice::<serde_json::Value>(&out.stdout) else {
+        return true;
+    };
+    dump.as_array()
+        .map(|objs| {
+            objs.iter().any(|o| {
+                o.get("id").and_then(|i| i.as_u64()) == Some(node_id as u64)
+                    && o.get("type").and_then(|t| t.as_str()) == Some("PipeWire:Interface:Node")
+            })
+        })
+        .unwrap_or(true)
+}
+
 /// Find the `gamescope` `Video/Source` node id in a `pw-dump` snapshot of the default daemon.
 ///
 /// `node.name=gamescope` appears on TWO objects (the adapter *and* the inner stream node); only
@@ -1041,10 +1332,18 @@ fn node_from_log() -> Option<u32> {
 /// other wedges the link. So we require `Video/Source` first and fall back to a bare name match
 /// only if no class-tagged node is present (older gamescope that doesn't set media.class).
 fn find_gamescope_node() -> Option<u32> {
+    find_gamescope_node_scoped(None)
+}
+
+/// Like [`find_gamescope_node`], but when `scope` is `Some(pid)` only a node whose owning process
+/// (`application.process.id`) is `pid` or a descendant of it qualifies (A5 — a spawn's node must
+/// belong to OUR gamescope's process tree, so a coexisting foreign / other-session gamescope node is
+/// never mistaken for ours). `None` = any gamescope node (the managed/attach paths, single-session).
+fn find_gamescope_node_scoped(scope: Option<u32>) -> Option<u32> {
     let out = Command::new("pw-dump").output().ok()?;
     let dump: serde_json::Value = serde_json::from_slice(&out.stdout).ok()?;
     let nodes = dump.as_array()?;
-    let node_props = |obj: &serde_json::Value| -> Option<(u32, String, String)> {
+    let node_props = |obj: &serde_json::Value| -> Option<(u32, String, String, Option<u32>)> {
         if obj.get("type").and_then(|t| t.as_str()) != Some("PipeWire:Interface:Node") {
             return None;
         }
@@ -1060,20 +1359,40 @@ fn find_gamescope_node() -> Option<u32> {
             .and_then(|n| n.as_str())
             .unwrap_or("")
             .to_string();
-        Some((id, name, class))
+        // PipeWire records the owning process id as a string or an int depending on version.
+        let pid = props
+            .and_then(|p| p.get("application.process.id"))
+            .and_then(|v| {
+                v.as_u64()
+                    .or_else(|| v.as_str().and_then(|s| s.parse().ok()))
+                    .map(|n| n as u32)
+            });
+        Some((id, name, class, pid))
     };
-    // Preferred: a Video/Source node named (or containing) "gamescope".
+    // A node is in-scope when no scope is asked, or its owning pid descends from the scope pid. When
+    // the pid prop is absent (older gamescope / PipeWire) we DON'T exclude it — falling back to the
+    // per-instance log is the primary addressing (design §7 risk note).
+    let in_scope = |pid: Option<u32>| -> bool {
+        match scope {
+            None => true,
+            Some(root) => pid.map(|p| descends_from(p, root)).unwrap_or(true),
+        }
+    };
+    // Preferred: a Video/Source node named (or containing) "gamescope", in scope.
     for obj in nodes {
-        if let Some((id, name, class)) = node_props(obj) {
-            if class == "Video/Source" && (name == "gamescope" || name.contains("gamescope")) {
+        if let Some((id, name, class, pid)) = node_props(obj) {
+            if class == "Video/Source"
+                && (name == "gamescope" || name.contains("gamescope"))
+                && in_scope(pid)
+            {
                 return Some(id);
             }
         }
     }
-    // Fallback: a node literally named "gamescope" with no usable class tag.
+    // Fallback: a node literally named "gamescope" with no usable class tag, in scope.
     for obj in nodes {
-        if let Some((id, name, _)) = node_props(obj) {
-            if name == "gamescope" {
+        if let Some((id, name, _, pid)) = node_props(obj) {
+            if name == "gamescope" && in_scope(pid) {
                 tracing::warn!(
                     node_id = id,
                     "gamescope node has no media.class=Video/Source tag — capturing it anyway"
@@ -1168,22 +1487,62 @@ fn parse_version(text: &str) -> Option<(u32, u32, u32)> {
     None
 }
 
-/// Owns the spawned gamescope process; killing it tears the virtual output down.
-struct GamescopeProc(Child);
+/// Owns the spawned gamescope process (and its per-instance log, A5); killing it tears the virtual
+/// output down.
+struct GamescopeProc {
+    child: Child,
+    log: std::path::PathBuf,
+}
 
 impl Drop for GamescopeProc {
     fn drop(&mut self) {
-        let _ = self.0.kill();
-        let _ = self.0.wait();
+        let _ = self.child.kill();
+        let _ = self.child.wait();
         // Clear the relayed EIS socket name so the host-lifetime injector can't reconnect to this
         // now-dead session's socket between sessions (the stale path is the "Connection refused").
         let _ = std::fs::remove_file(ei_socket_file());
+        // Drop this spawn's per-instance log (A5) so `$XDG_RUNTIME_DIR` doesn't accumulate them.
+        let _ = std::fs::remove_file(&self.log);
     }
 }
 
 #[cfg(test)]
 mod tests {
-    use super::{parse_version, MIN_GAMESCOPE};
+    use super::{is_steam_launch, parse_version, shape_dedicated_command, MIN_GAMESCOPE};
+
+    #[test]
+    fn steam_launch_detection() {
+        assert!(is_steam_launch("steam steam://rungameid/570"));
+        assert!(is_steam_launch("steam -silent steam://rungameid/570"));
+        assert!(!is_steam_launch("vkcube"));
+        assert!(!is_steam_launch("lutris lutris:rungameid/42"));
+        assert!(!is_steam_launch("steam -bigpicture")); // no URI = not a game launch
+    }
+
+    #[test]
+    fn dedicated_command_shaping() {
+        // Steam URI → -silent inserted so the game is the gamescope focus.
+        assert_eq!(
+            shape_dedicated_command("steam steam://rungameid/570"),
+            "steam -silent steam://rungameid/570"
+        );
+        // Idempotent: an already-silent command is left alone.
+        assert_eq!(
+            shape_dedicated_command("steam -silent steam://rungameid/570"),
+            "steam -silent steam://rungameid/570"
+        );
+        // Non-Steam launches and operator custom commands are untouched.
+        assert_eq!(shape_dedicated_command("vkcube"), "vkcube");
+        assert_eq!(
+            shape_dedicated_command("lutris lutris:rungameid/42"),
+            "lutris lutris:rungameid/42"
+        );
+        // A bare `steam` with no URI is left alone (not a game launch).
+        assert_eq!(
+            shape_dedicated_command("steam -bigpicture"),
+            "steam -bigpicture"
+        );
+    }
 
     #[test]
     fn parses_version_banner() {

crates/punktfunk-host/src/vdisplay/linux/kwin.rs

@@ -75,6 +75,29 @@ const MAX_VERSION: u32 = 5;
 #[derive(Default)]
 pub struct KwinDisplay {
     client_fp: Option<[u8; 32]>,
+    /// The identity slot the last [`create`](VirtualDisplay::create) resolved (the per-client id, or
+    /// `None` for shared/anonymous) — reported to the registry via [`last_identity_slot`] so it can key
+    /// the group arrangement + `/display/state` slot to the same id this backend named the output with.
+    last_slot: Option<u32>,
+    /// The base output name the last `create` used (`punktfunk` / `punktfunk-<id>`) — so
+    /// [`apply_position`](VirtualDisplay::apply_position) can address the KWin output `Virtual-<name>`.
+    last_name: Option<String>,
+    /// The topology-restore action the last `create` prepared (re-enable the outputs an `exclusive`
+    /// topology disabled), pending pickup by the registry via [`take_topology_restore`] — so the
+    /// physical is re-enabled only when the display GROUP's last member drops (§6.1), not this session's.
+    /// A backstop [`Drop`] runs it if the registry never took it (so a physical is never left dark).
+    pending_restore: Option<Box<dyn FnOnce() + Send>>,
+}
+
+impl Drop for KwinDisplay {
+    fn drop(&mut self) {
+        // Backstop only: the registry takes the restore right after `create` (moving it into the group),
+        // so this is normally `None`. If some path skipped the take, re-enable here so a physical is
+        // never stranded dark.
+        if let Some(restore) = self.pending_restore.take() {
+            restore();
+        }
+    }
 }
 
 impl KwinDisplay {
@@ -92,20 +115,49 @@ impl VirtualDisplay for KwinDisplay {
         self.client_fp = fingerprint;
     }
 
+    fn last_identity_slot(&self) -> Option<u32> {
+        self.last_slot
+    }
+
+    fn take_topology_restore(&mut self) -> Option<Box<dyn FnOnce() + Send>> {
+        self.pending_restore.take()
+    }
+
+    fn apply_position(&mut self, x: i32, y: i32) {
+        let Some(name) = self.last_name.clone() else {
+            return;
+        };
+        let output = format!("Virtual-{name}");
+        // kscreen-doctor position syntax: `output.<name>.position.<x>,<y>`.
+        let ok = std::process::Command::new("kscreen-doctor")
+            .arg(format!("output.{output}.position.{x},{y}"))
+            .status()
+            .map(|s| s.success())
+            .unwrap_or(false);
+        if ok {
+            tracing::info!(output, x, y, "KWin: placed output in the desktop layout");
+        } else {
+            tracing::warn!(output, x, y, "KWin: output position apply failed");
+        }
+    }
+
     fn create(&mut self, mode: Mode) -> Result<VirtualOutput> {
         // Per-slot output name (Stage 3): the `identity` policy resolves the client to a stable id →
         // `punktfunk-<id>` (KWin exposes `Virtual-punktfunk-<id>`, whose per-output config KWin
         // persists by name). Shared / anonymous → the base `punktfunk` (today's single name). Linux
         // defaults to Shared when unconfigured, so this is a no-op change until a policy opts in — AND
         // it fixes the latent clash where two concurrent sessions both used `Virtual-punktfunk`.
-        let name = match crate::vdisplay::identity::resolve_slot(
+        let slot = crate::vdisplay::identity::resolve_slot(
             self.client_fp,
             (mode.width, mode.height),
             crate::vdisplay::policy::Identity::Shared,
-        ) {
+        );
+        self.last_slot = slot; // reported to the registry for the group arrangement + state slot
+        let name = match slot {
             Some(id) => format!("{VOUT_NAME}-{id}"),
             None => VOUT_NAME.to_string(),
         };
+        self.last_name = Some(name.clone()); // for apply_position (registry-driven §6.2 layout)
         let (setup_tx, setup_rx) = std::sync::mpsc::channel::<Result<u32, String>>();
         let stop = Arc::new(AtomicBool::new(false));
         let stop_thread = stop.clone();
@@ -141,7 +193,7 @@ impl VirtualDisplay for KwinDisplay {
         // plasmashell + windows land on the streamed surface, not the headless `kwin --virtual`
         // bootstrap output. Read from the policy (replacing the PUNKTFUNK_KWIN_VIRTUAL_PRIMARY boolean).
         use crate::vdisplay::policy::Topology;
-        let restore = match crate::vdisplay::effective_topology() {
+        let disabled = match crate::vdisplay::effective_topology() {
             Topology::Exclusive => apply_virtual_primary(&name),
             Topology::Primary => {
                 apply_virtual_primary_only(&name);
@@ -149,15 +201,43 @@ impl VirtualDisplay for KwinDisplay {
             }
             Topology::Extend | Topology::Auto => Vec::new(),
         };
-        Ok(VirtualOutput {
+        // Per-group restore (§6.1): DON'T bind the re-enable to this session's keepalive (a per-session
+        // `StopGuard` restore would re-enable the physical the moment the FIRST of several exclusive
+        // sessions drops — under a still-live sibling). Instead stash it as a closure the registry lifts
+        // into the display group and runs once, when the group's LAST member is torn down (ordered before
+        // that display's output is reclaimed, so KWin never sees zero outputs). Empty ⇒ nothing to restore.
+        self.pending_restore = (!disabled.is_empty()).then(|| {
+            let disabled = disabled.clone();
+            Box::new(move || reenable_outputs(&disabled)) as Box<dyn FnOnce() + Send>
+        });
+        // Layout position (§6.2) is applied by the registry via `apply_position` right after create
+        // (it owns the display group, so it computes auto-row / manual placement over the whole group).
+        Ok(VirtualOutput::owned(
             node_id,
-            remote_fd: None,
-            preferred_mode: Some((mode.width, mode.height, achieved_hz)),
-            keepalive: Box::new(StopGuard { stop, restore }),
-        })
+            Some((mode.width, mode.height, achieved_hz)),
+            Box::new(StopGuard { stop }),
+        ))
     }
 }
 
+/// Re-enable the outputs an `exclusive` topology disabled (bootstrap / physical), so KWin re-homes onto
+/// them. Called by the registry when the display group's last member is torn down (design §6.1), BEFORE
+/// that member's output is reclaimed — so KWin is never momentarily left with zero enabled outputs.
+fn reenable_outputs(outputs: &[String]) {
+    if outputs.is_empty() {
+        return;
+    }
+    let args: Vec<String> = outputs
+        .iter()
+        .map(|o| format!("output.{o}.enable"))
+        .collect();
+    let _ = std::process::Command::new("kscreen-doctor")
+        .args(&args)
+        .status();
+    std::thread::sleep(Duration::from_millis(200));
+    tracing::info!(reenabled = ?outputs, "KWin: restored the physical/bootstrap outputs (group empty)");
+}
+
 /// Best-effort: raise the just-created virtual output's refresh above KWin's default 60 Hz by
 /// installing + selecting a custom mode via `kscreen-doctor` (the output is `Virtual-<VOUT_NAME>`,
 /// refresh given in mHz), then **read back the active mode** and return the refresh KWin actually
@@ -283,7 +363,10 @@ fn other_enabled_outputs() -> Vec<String> {
 /// then sets itself primary — the pre-group behavior). Recent kscreen marks the primary with
 /// `"priority": 1`; older builds used a `"primary": true` bool — accept either.
 fn a_managed_output_is_primary() -> bool {
-    let Ok(out) = std::process::Command::new("kscreen-doctor").arg("-j").output() else {
+    let Ok(out) = std::process::Command::new("kscreen-doctor")
+        .arg("-j")
+        .output()
+    else {
         return false;
     };
     let Ok(doc) = serde_json::from_slice::<serde_json::Value>(&out.stdout) else {
@@ -362,28 +445,15 @@ fn apply_virtual_primary_only(name: &str) {
 }
 
 /// Dropping this releases the KWin virtual output: it flips the keepalive thread's `stop`, which
-/// drops the Wayland connection and makes KWin reclaim the output.
+/// drops the Wayland connection and makes KWin reclaim the output. The topology **restore** is no
+/// longer bound here — it moved to the registry's display group (§6.1, [`reenable_outputs`]), which
+/// runs it once when the group's last member drops, BEFORE this keepalive is dropped.
 struct StopGuard {
     stop: Arc<AtomicBool>,
-    /// Bootstrap output(s) `apply_virtual_primary` disabled to make our streamed output the sole
-    /// desktop — re-enabled here FIRST, so KWin is never left with zero enabled outputs as our
-    /// output is reclaimed. Empty unless PUNKTFUNK_KWIN_VIRTUAL_PRIMARY is set.
-    restore: Vec<String>,
 }
 
 impl Drop for StopGuard {
     fn drop(&mut self) {
-        if !self.restore.is_empty() {
-            let args: Vec<String> = self
-                .restore
-                .iter()
-                .map(|o| format!("output.{o}.enable"))
-                .collect();
-            let _ = std::process::Command::new("kscreen-doctor")
-                .args(&args)
-                .status();
-            std::thread::sleep(Duration::from_millis(200));
-        }
         self.stop.store(true, Ordering::Relaxed);
     }
 }

crates/punktfunk-host/src/vdisplay/linux/mutter.rs

@@ -42,11 +42,19 @@ const CURSOR_EMBEDDED: u32 = 1;
 
 /// The Mutter virtual-display driver. Each [`create`](VirtualDisplay::create) spins up a
 /// keepalive thread owning the D-Bus sessions behind the virtual monitor.
-pub struct MutterDisplay;
+pub struct MutterDisplay {
+    /// Whether this display is the FIRST of its group (§6.1) — set by the registry before `create`.
+    /// A later sibling **extends** into the already-exclusive desktop instead of re-applying the
+    /// sole-monitor config (which would disable the first session's virtual). Defaults true (a lone
+    /// session establishes topology as before).
+    first_in_group: bool,
+}
 
 impl MutterDisplay {
     pub fn new() -> Result<Self> {
-        Ok(MutterDisplay)
+        Ok(MutterDisplay {
+            first_in_group: true,
+        })
     }
 }
 
@@ -64,13 +72,18 @@ impl VirtualDisplay for MutterDisplay {
         "mutter"
     }
 
+    fn set_first_in_group(&mut self, first: bool) {
+        self.first_in_group = first;
+    }
+
     fn create(&mut self, mode: Mode) -> Result<VirtualOutput> {
         let (setup_tx, setup_rx) = std::sync::mpsc::channel::<Result<u32, String>>();
         let stop = Arc::new(AtomicBool::new(false));
         let stop_thread = stop.clone();
+        let first_in_group = self.first_in_group;
         thread::Builder::new()
             .name("punktfunk-mutter-vout".into())
-            .spawn(move || session_thread(setup_tx, stop_thread, mode))
+            .spawn(move || session_thread(setup_tx, stop_thread, mode, first_in_group))
             .context("spawn Mutter virtual-output thread")?;
 
         let node_id = match setup_rx.recv_timeout(Duration::from_secs(20)) {
@@ -84,12 +97,11 @@ impl VirtualDisplay for MutterDisplay {
             h = mode.height,
             "Mutter virtual monitor ready"
         );
-        Ok(VirtualOutput {
+        Ok(VirtualOutput::owned(
             node_id,
-            remote_fd: None,
-            preferred_mode: Some((mode.width, mode.height, mode.refresh_hz)),
-            keepalive: Box::new(StopGuard(stop)),
-        })
+            Some((mode.width, mode.height, mode.refresh_hz)),
+            Box::new(StopGuard(stop)),
+        ))
     }
 }
 
@@ -104,8 +116,14 @@ impl Drop for StopGuard {
 }
 
 /// Keepalive thread: run the D-Bus handshake on a private tokio runtime, report the PipeWire
-/// node id, then hold the connection until stopped.
-fn session_thread(setup_tx: Sender<Result<u32, String>>, stop: Arc<AtomicBool>, mode: Mode) {
+/// node id, then hold the connection until stopped. `first_in_group` gates the topology change (a
+/// non-first sibling extends into the group's already-exclusive desktop instead of re-clobbering it).
+fn session_thread(
+    setup_tx: Sender<Result<u32, String>>,
+    stop: Arc<AtomicBool>,
+    mode: Mode,
+    first_in_group: bool,
+) {
     let rt = match tokio::runtime::Builder::new_multi_thread()
         .worker_threads(1)
         .enable_all()
@@ -122,12 +140,23 @@ fn session_thread(setup_tx: Sender<Result<u32, String>>, stop: Arc<AtomicBool>,
         // value. `Extend` leaves the virtual output an extension (no config change); `Primary` makes
         // it the primary monitor but keeps the physicals as secondaries; `Exclusive` makes it the
         // SOLE output (physicals disabled). `Auto` never reaches here — it's resolved upstream.
+        use crate::vdisplay::policy::Topology;
         let topo = crate::vdisplay::effective_topology();
-        let want_config = matches!(
-            topo,
-            crate::vdisplay::policy::Topology::Primary | crate::vdisplay::policy::Topology::Exclusive
-        );
-        let exclusive = matches!(topo, crate::vdisplay::policy::Topology::Exclusive);
+        let topo_policy = matches!(topo, Topology::Primary | Topology::Exclusive);
+        // Group-aware (§6.1): only the FIRST display of the group establishes the topology. A later
+        // sibling extends into the already-exclusive desktop — re-applying the sole-monitor config would
+        // disable the first session's virtual output (Mutter connectors are un-nameable, so we can't
+        // build a config that keeps all group virtuals; skipping is the safe choice). *Concurrent
+        // Mutter exclusive is on-glass-validation-pending; the APPLY_TEMPORARY revert when the FIRST
+        // session leaves under a live sibling is a documented residual (design §7).*
+        let want_config = first_in_group && topo_policy;
+        if topo_policy && !first_in_group {
+            tracing::info!(
+                "mutter: joining an existing display group — extending (the first session owns the \
+                 exclusive/primary topology)"
+            );
+        }
+        let exclusive = matches!(topo, Topology::Exclusive);
         // Snapshot the monitor layout BEFORE the virtual output exists (so we can tell the new
         // connector apart and restore on teardown) whenever we're going to touch the topology.
         let dc_pre = if want_config {
@@ -255,15 +284,16 @@ async fn connect(mode: Mode) -> Result<MutterSession> {
     )
     .await?;
 
-    // 3. The virtual monitor. By DEFAULT we let Mutter derive the refresh from the PipeWire
-    // framerate (it defaults the virtual monitor to 60 Hz) — universally safe.
-    // PUNKTFUNK_MUTTER_VIRTUAL_REFRESH=1 pins the client's exact WxH@Hz via RecordVirtual's "modes"
-    // (explicit size + refresh-rate; Mutter ≥ 47) for true >60 Hz — validated at 5120×1440@240 on
-    // Mutter 50 + NVIDIA. (A high-refresh virtual CRTC used to SIGSEGV gnome-shell on teardown; the
-    // stop-screencast-before-any-monitor-reconfig teardown below avoids that.)
+    // 3. The virtual monitor. For >60 Hz we pin the client's exact WxH@Hz via RecordVirtual's
+    // "modes" (explicit size + refresh-rate; Mutter ≥ 47) — validated at 5120×1440@240 on Mutter 50
+    // + NVIDIA. At ≤60 Hz we let Mutter derive the refresh from the PipeWire framerate (its 60 Hz
+    // default is already correct), so the custom-mode path only runs when it buys something.
+    // (A high-refresh virtual CRTC used to SIGSEGV gnome-shell on teardown, which is why this was
+    // once gated behind PUNKTFUNK_MUTTER_VIRTUAL_REFRESH; the stop-screencast-before-any-monitor-
+    // reconfig teardown below fixed the crash, so pinning the client's refresh is now the default.)
     let mut rec: HashMap<&str, Value> = HashMap::new();
     rec.insert("cursor-mode", Value::from(CURSOR_EMBEDDED));
-    if virtual_refresh_enabled() && mode.refresh_hz > 60 {
+    if mode.refresh_hz > 60 {
         let mut vmode: HashMap<&str, Value> = HashMap::new();
         vmode.insert("size", Value::from((mode.width, mode.height)));
         vmode.insert("refresh-rate", Value::from(mode.refresh_hz as f64));
@@ -352,22 +382,6 @@ type CurrentState = (
 type ApplyMon = (String, String, HashMap<String, Value<'static>>); // connector, mode_id, props
 type ApplyLogical = (i32, i32, f64, u32, bool, Vec<ApplyMon>);
 
-/// Opt-in: pin the virtual output to the client's exact refresh via RecordVirtual "modes" (true
-/// above-60 Hz). Off by default — Mutter-derived 60 Hz is safe on every host; high-refresh virtual
-/// CRTCs are validated on Mutter 50 + NVIDIA but behaviour can vary, so it stays opt-in. (The
-/// teardown SIGSEGV that first motivated this gate is fixed by stopping the screencast before any
-/// monitor-config change.)
-fn virtual_refresh_enabled() -> bool {
-    std::env::var("PUNKTFUNK_MUTTER_VIRTUAL_REFRESH")
-        .map(|v| {
-            matches!(
-                v.trim().to_ascii_lowercase().as_str(),
-                "1" | "true" | "yes" | "on"
-            )
-        })
-        .unwrap_or(false)
-}
-
 /// A DisplayConfig proxy on its own session-bus connection (owned, so it stays alive for the
 /// session — independent of the RemoteDesktop/ScreenCast connection).
 async fn display_config() -> Result<zbus::Proxy<'static>> {

crates/punktfunk-host/src/vdisplay/linux/wlroots.rs

@@ -19,7 +19,7 @@
 //! `systemctl --user`, see `scripts/headless/prepare-session.sh`), with the ScreenCast
 //! interface routed to xdpw (`scripts/headless/portals.conf`).
 
-use super::{Mode, VirtualDisplay, VirtualOutput};
+use super::{DisplayOwnership, Mode, VirtualDisplay, VirtualOutput};
 use anyhow::{anyhow, bail, Context, Result};
 use std::os::fd::OwnedFd;
 use std::process::Command;
@@ -130,6 +130,11 @@ impl VirtualDisplay for WlrootsDisplay {
                 _stop: StopGuard(stop),
                 _output: output,
             }),
+            // Owned (the compositor output is ours to tear down), but not registry-poolable: the
+            // portal fd can't be re-opened per attach, so the registry passes it through on
+            // `remote_fd.is_some()` (keep-alive stays off for wlroots until fresh-portal re-attach).
+            ownership: DisplayOwnership::Owned,
+            reused_gen: None,
         })
     }
 }

crates/punktfunk-host/src/vdisplay/policy.rs

@@ -158,6 +158,22 @@ pub struct Layout {
     pub positions: BTreeMap<String, Position>,
 }
 
+/// How a session that **launches a game** (a library id on the Hello / apps.json / Decky pin) is
+/// served (`design/gamemode-and-dedicated-sessions.md` §5.2). Orthogonal to the preset/lifecycle axes
+/// — a top-level [`DisplayPolicy`] field, NOT part of [`EffectivePolicy`], so a preset never clobbers
+/// it. Linux-only in effect (a launching Windows session opens into the one desktop).
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize, ToSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum GameSession {
+    /// Today's routing: the launch rides whatever session the box is in (managed Steam session on
+    /// Bazzite/SteamOS, bare spawn on plain distros, spawned into the live desktop on KWin/Mutter/wlroots).
+    #[default]
+    Auto,
+    /// A launching session always gets its OWN headless gamescope at the client's mode, nesting just
+    /// the game — no Steam Big Picture, no game mode. Degrades to `auto` when gamescope is unavailable.
+    Dedicated,
+}
+
 /// A named bundle of the fields below. `Custom` (the default) means the explicit fields rule; any
 /// other preset ignores the stored fields and expands to its own ([`DisplayPolicy::effective`]).
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize, ToSchema)]
@@ -202,6 +218,11 @@ pub struct DisplayPolicy {
     /// Upper bound on simultaneously-live virtual displays (clamped to `1..=16` on write).
     #[serde(default = "default_max_displays")]
     pub max_displays: u32,
+    /// How a game-launching session is served (`design/gamemode-and-dedicated-sessions.md` §5.2).
+    /// Orthogonal to `preset`/lifecycle — preserved across preset changes; `#[serde(default)]` = `Auto`
+    /// so existing `display-settings.json` files are untouched.
+    #[serde(default)]
+    pub game_session: GameSession,
 }
 
 fn one() -> u32 {
@@ -224,6 +245,7 @@ impl Default for DisplayPolicy {
             identity: Identity::default(),
             layout: Layout::default(),
             max_displays: 4,
+            game_session: GameSession::default(),
         }
     }
 }
@@ -273,6 +295,35 @@ impl DisplayPolicy {
     }
 }
 
+impl EffectivePolicy {
+    /// Build a persistable `Custom` [`DisplayPolicy`] that keeps THIS effective behavior but replaces
+    /// the arrangement with a **manual** layout at `positions` — the `/display/layout` endpoint's
+    /// transform, factored out pure so arranging displays stays orthogonal to the other axes and is
+    /// unit-tested without touching the global store. (`Custom` so the explicit fields — incl. the new
+    /// layout — rule; a named preset would ignore them.)
+    pub fn with_manual_layout(
+        &self,
+        positions: BTreeMap<String, Position>,
+        game_session: GameSession,
+    ) -> DisplayPolicy {
+        DisplayPolicy {
+            version: 1,
+            preset: Preset::Custom,
+            keep_alive: self.keep_alive,
+            topology: self.topology,
+            mode_conflict: self.mode_conflict,
+            identity: self.identity,
+            layout: Layout {
+                mode: LayoutMode::Manual,
+                positions,
+            },
+            max_displays: self.max_displays,
+            // Preserve the orthogonal game-session axis (EffectivePolicy doesn't carry it).
+            game_session,
+        }
+    }
+}
+
 /// The field bundle a named preset expands to; `None` for [`Preset::Custom`]. The single expansion
 /// table — the docs' preset table mirrors this and the `presets_match_doc` test guards the shape.
 pub fn preset_fields(preset: Preset) -> Option<EffectivePolicy> {
@@ -375,6 +426,13 @@ impl DisplayPolicyStore {
         self.configured().map(|p| p.effective())
     }
 
+    /// The game-session routing axis (`design/gamemode-and-dedicated-sessions.md` §5.2). Orthogonal to
+    /// the preset — read directly off the stored policy (or the default `Auto` when unconfigured), so a
+    /// preset selection never resets it.
+    pub fn game_session(&self) -> GameSession {
+        self.get().game_session
+    }
+
     /// Persist + adopt a new policy (sanitized first). The in-memory value changes only if the disk
     /// write succeeds, so a full disk can't leave memory and file disagreeing.
     pub fn set(&self, policy: DisplayPolicy) -> Result<()> {
@@ -526,6 +584,35 @@ mod tests {
         assert_eq!(p.max_displays, 16);
     }
 
+    #[test]
+    fn with_manual_layout_preserves_behavior_and_sets_positions() {
+        // Start from a preset's effective behavior (workstation: 5-min linger, exclusive, per-client).
+        let eff = DisplayPolicy {
+            preset: Preset::Workstation,
+            ..DisplayPolicy::default()
+        }
+        .effective();
+        let mut positions = BTreeMap::new();
+        positions.insert("1".to_string(), Position { x: 0, y: 0 });
+        positions.insert("7".to_string(), Position { x: 2560, y: 0 });
+        let p = eff.with_manual_layout(positions, GameSession::Dedicated);
+        // The orthogonal game-session axis is preserved through the layout transform.
+        assert_eq!(p.game_session, GameSession::Dedicated);
+        // Preset drops to Custom so the explicit fields (incl. the layout) rule…
+        assert_eq!(p.preset, Preset::Custom);
+        // …every other behavior axis is preserved verbatim…
+        assert_eq!(p.keep_alive, eff.keep_alive);
+        assert_eq!(p.topology, eff.topology);
+        assert_eq!(p.mode_conflict, eff.mode_conflict);
+        assert_eq!(p.identity, eff.identity);
+        assert_eq!(p.max_displays, eff.max_displays);
+        // …and the arrangement is the manual layout we asked for, surviving the effective round-trip.
+        let e2 = p.effective();
+        assert_eq!(e2.layout.mode, LayoutMode::Manual);
+        let want = Position { x: 2560, y: 0 };
+        assert_eq!(e2.layout.positions.get("7"), Some(&want));
+    }
+
     #[test]
     fn partial_json_fills_defaults() {
         // A hand-written file with only a couple of fields loads, the rest defaulting.

crates/punktfunk-host/src/vdisplay/windows/manager.rs

@@ -31,7 +31,7 @@ use windows::Win32::System::Threading::{
     CreateMutexW, OpenProcess, WaitForSingleObject, PROCESS_SYNCHRONIZE,
 };
 
-use super::{Mode, VirtualOutput};
+use super::{DisplayOwnership, Mode, VirtualOutput};
 use crate::win_display::{
     force_extend_topology, isolate_displays_ccd, resolve_gdi_name, restore_displays_ccd,
     set_active_mode, set_virtual_primary_ccd, SavedConfig,
@@ -129,8 +129,22 @@ impl Monitor {
 
 enum MgrState {
     Idle,
-    Active { mon: Monitor, refs: u32 },
-    Lingering { mon: Monitor, until: Instant },
+    Active {
+        mon: Monitor,
+        refs: u32,
+    },
+    Lingering {
+        mon: Monitor,
+        until: Instant,
+    },
+    /// `keep_alive = forever` (gaming-rig): the monitor is kept indefinitely after the last session
+    /// leaves — like `Lingering` but the linger timer never tears it down. A reconnect preempts +
+    /// recreates it (same as `Lingering`, since a reused IddCx swap-chain is dead); only the mgmt
+    /// `/display/release` (or host shutdown) frees it. The physical screens stay off (exclusive) for
+    /// the box's life — the §8 release-now escape hatch (`force_release`) is the way back.
+    Pinned {
+        mon: Monitor,
+    },
 }
 
 /// The manager's control-device cache. Reopenable: a driver upgrade / WUDFHost restart kills the
@@ -386,22 +400,28 @@ impl VirtualDisplayManager {
         let mut state = self.state.lock().unwrap();
         let dev = self.ensure_device()?;
 
-        // IDD-push: a new connection while a monitor is LINGERING is a single-client RECONNECT (the
-        // prior session fully released). A REUSED IddCx swap-chain is DEAD, so reusing it hands a black
-        // screen — PREEMPT: tear the lingering monitor down (its key/topology are restored) and create a
-        // fresh one. The old session's lease is gen-stamped, so its later drop is a no-op.
+        // IDD-push: a new connection while a monitor is kept (LINGERING or PINNED) is a single-client
+        // RECONNECT (the prior session fully released). A REUSED IddCx swap-chain is DEAD, so reusing it
+        // hands a black screen — PREEMPT: tear the kept monitor down (its key/topology are restored) and
+        // create a fresh one. The old session's lease is gen-stamped, so its later drop is a no-op.
         //
-        // ONLY Lingering, NOT Active: an Active monitor still has a lease held — that's the build-retry
-        // path (`build_pipeline_with_retry` holds one lease across all attempts) or a concurrent session,
-        // NOT a reconnect. Preempting Active would tear a live session down AND churn REMOVE→ADD on every
-        // retry — the per-cold-start monitor churn that exhausts the IddCx slot pool and wedges ADD at
-        // 0x80070490. Active falls through to the JOIN path below (refcount++, no ADD).
-        if matches!(*state, MgrState::Lingering { .. }) {
-            if let MgrState::Lingering { mon, .. } = std::mem::replace(&mut *state, MgrState::Idle)
-            {
+        // ONLY the kept states, NOT Active: an Active monitor still has a lease held — that's the
+        // build-retry path (`build_pipeline_with_retry` holds one lease across all attempts) or a
+        // concurrent session, NOT a reconnect. Preempting Active would tear a live session down AND churn
+        // REMOVE→ADD on every retry — the per-cold-start monitor churn that exhausts the IddCx slot pool
+        // and wedges ADD at 0x80070490. Active falls through to the JOIN path below (refcount++, no ADD).
+        if matches!(*state, MgrState::Lingering { .. } | MgrState::Pinned { .. }) {
+            let taken = match std::mem::replace(&mut *state, MgrState::Idle) {
+                MgrState::Lingering { mon, .. } | MgrState::Pinned { mon } => Some(mon),
+                other => {
+                    *state = other;
+                    None
+                }
+            };
+            if let Some(mon) = taken {
                 tracing::info!(
                     old_target = mon.target_id,
-                    "IDD-push reconnect — preempting the lingering monitor, recreating a fresh one"
+                    "IDD-push reconnect — preempting the kept (lingering/pinned) monitor, recreating a fresh one"
                 );
                 // SAFETY: `teardown` requires `dev` to be a valid control handle; `dev` is the value
                 // `ensure_device()` returned above (cached handles are never closed — a dead one is
@@ -457,12 +477,14 @@ impl VirtualDisplayManager {
             return Ok(self.output_for(mon));
         }
 
-        // Idle or Lingering: repurpose a lingering monitor / create a fresh one → Active{refs:1}.
+        // Idle or kept: repurpose a kept monitor / create a fresh one → Active{refs:1}. (In practice a
+        // kept Lingering/Pinned monitor was already preempted → Idle above; this arm is the defensive
+        // reuse path if a race left one here — it must stay exhaustive over `Pinned` regardless.)
         let mon = match std::mem::replace(&mut *state, MgrState::Idle) {
-            MgrState::Lingering { mut mon, .. } => {
+            MgrState::Lingering { mut mon, .. } | MgrState::Pinned { mut mon } => {
                 tracing::info!(
                     backend = self.driver.name(),
-                    "virtual monitor reused (reconnect within the linger window)"
+                    "virtual monitor reused (reconnect to a kept monitor)"
                 );
                 if mon.mode != mode {
                     // SAFETY: `reconfigure` needs an exclusive `&mut Monitor` and only touches the live
@@ -509,6 +531,9 @@ impl VirtualDisplayManager {
                 mgr: self,
                 gen: mon.gen,
             }),
+            // The Windows manager owns the monitor lifecycle (refcount/linger/pin), so the registry
+            // (which delegates to it via `vd.create`) treats it as Owned.
+            ownership: DisplayOwnership::Owned,
         }
     }
 
@@ -641,10 +666,10 @@ impl VirtualDisplayManager {
                 // MODE_CHANGE storm). Opt out (extend) with PUNKTFUNK_NO_ISOLATE=1 / the console policy.
                 use crate::vdisplay::policy::Topology;
                 match topology_action() {
-                    // SAFETY (both arms): the CCD helper is `unsafe` for its topology FFI; it takes a
-                    // `Copy` `u32` by value and returns an owned `SavedConfig` (no borrowed memory crosses),
-                    // and runs under the `state` lock, the sole mutator of the topology.
                     Topology::Exclusive => {
+                        // SAFETY: `isolate_displays_ccd` is `unsafe` for its CCD topology FFI; it takes the
+                        // `Copy` target id by value and returns an owned `SavedConfig` (no borrowed memory
+                        // crosses), under the `state` lock — the sole topology mutator.
                         ccd_saved = unsafe { isolate_displays_ccd(added.target_id) };
                     }
                     Topology::Primary => {
@@ -654,8 +679,12 @@ impl VirtualDisplayManager {
                         // alongside the virtual, THEN reposition to make the virtual primary — so the
                         // physical stays active. (The bring-up above only force-EXTENDs when the
                         // virtual FAILS to auto-resolve; here it resolved, so we do it explicitly.)
+                        // SAFETY: `force_extend_topology` drives the CCD topology FFI (no args, no borrowed
+                        // memory), under the `state` lock — the sole topology mutator.
                         unsafe { force_extend_topology() };
                         thread::sleep(Duration::from_millis(300));
+                        // SAFETY: `set_virtual_primary_ccd` takes the `Copy` target id by value and returns
+                        // an owned `SavedConfig` (no borrowed memory crosses), under the `state` lock.
                         ccd_saved = unsafe { set_virtual_primary_ccd(added.target_id) };
                     }
                     Topology::Extend | Topology::Auto => {
@@ -747,7 +776,9 @@ impl VirtualDisplayManager {
     fn release(&self, gen: u64) {
         let mut state = self.state.lock().unwrap();
         let stale = match &*state {
-            MgrState::Active { mon, .. } | MgrState::Lingering { mon, .. } => mon.gen != gen,
+            MgrState::Active { mon, .. }
+            | MgrState::Lingering { mon, .. }
+            | MgrState::Pinned { mon } => mon.gen != gen,
             MgrState::Idle => true,
         };
         if stale {
@@ -758,6 +789,14 @@ impl VirtualDisplayManager {
                 mon,
                 refs: refs - 1,
             },
+            // Last session left: keep the monitor forever (Pinned) under `keep_alive = forever`,
+            // else linger for the policy window before the timer tears it down.
+            MgrState::Active { mon, .. } if keep_alive_forever() => {
+                tracing::info!(
+                    "virtual-display: last session left — PINNED (keep_alive=forever); free via /display/release"
+                );
+                MgrState::Pinned { mon }
+            }
             MgrState::Active { mon, .. } => {
                 let ms = linger_ms();
                 tracing::info!(
@@ -918,7 +957,7 @@ fn resolve_render_pin() -> Option<LUID> {
 pub(crate) struct ManagedInfo {
     pub backend: &'static str,
     pub mode: (u32, u32, u32),
-    /// `"active"` | `"lingering"`.
+    /// `"active"` | `"lingering"` | `"pinned"`.
     pub state: &'static str,
     /// Milliseconds until a lingering monitor is torn down (`None` when active).
     pub expires_in_ms: Option<u64>,
@@ -939,6 +978,8 @@ impl VirtualDisplayManager {
                 let ms = until.saturating_duration_since(Instant::now()).as_millis() as u64;
                 (mon, "lingering", 0u32, Some(ms))
             }
+            // Pinned (keep_alive=forever): kept indefinitely, no expiry — the console shows "Pinned".
+            MgrState::Pinned { mon } => (mon, "pinned", 0u32, None),
         };
         Some(ManagedInfo {
             backend: self.driver.name(),
@@ -950,20 +991,28 @@ impl VirtualDisplayManager {
         })
     }
 
-    /// Force-tear-down a LINGERING monitor now (the `/display/release` endpoint) — so a
-    /// physical-screen user gets their screen back without waiting out the linger. An Active monitor
-    /// is refused (stopping a live session is session management, not display management). Returns
-    /// `true` if a lingering monitor was released.
+    /// Force-tear-down a kept (LINGERING **or** PINNED) monitor now (the `/display/release` endpoint) —
+    /// so a physical-screen user gets their screen back without waiting out the linger, and it is the §8
+    /// escape hatch that frees a `keep_alive=forever` (Pinned) monitor. An Active monitor is refused
+    /// (stopping a live session is session management, not display management). Returns `true` if a kept
+    /// monitor was released.
     pub(crate) fn force_release(&self) -> bool {
         let Some(dev) = self.device_handle() else {
             return false;
         };
         let mut st = self.state.lock().unwrap();
-        if matches!(&*st, MgrState::Lingering { .. }) {
-            if let MgrState::Lingering { mon, .. } = std::mem::replace(&mut *st, MgrState::Idle) {
+        if matches!(&*st, MgrState::Lingering { .. } | MgrState::Pinned { .. }) {
+            let mon = match std::mem::replace(&mut *st, MgrState::Idle) {
+                MgrState::Lingering { mon, .. } | MgrState::Pinned { mon } => Some(mon),
+                other => {
+                    *st = other;
+                    None
+                }
+            };
+            if let Some(mon) = mon {
                 // SAFETY: `teardown` needs a live control handle; `dev` is from `device_handle()`
                 // (cached handles are never closed — a dead one is retired, kept alive; see
-                // `DeviceSlot`). `mon` was moved out of the `Lingering` state under the `state` lock,
+                // `DeviceSlot`). `mon` was moved out of the kept state under the `state` lock,
                 // so it is exclusively owned here — no aliasing.
                 unsafe { self.teardown(dev, mon) };
                 return true;
@@ -996,16 +1045,10 @@ fn linger_ms() -> u64 {
         return match eff.keep_alive.linger() {
             Linger::Immediate => 0,
             Linger::For(d) => d.as_millis() as u64,
-            // Pinned (keep forever) is built in the display-lifecycle stage; until then fall back to
-            // the default rather than silently keeping the monitor — and thus the physical screens —
-            // dark indefinitely. (The mgmt PUT also rejects `forever` at Stage 0, so this is defensive.)
-            Linger::Forever => {
-                tracing::warn!(
-                    "display policy: keep_alive=forever not yet honored — lingering 10 s \
-                     (Pinned lands in the display-lifecycle stage)"
-                );
-                10_000
-            }
+            // `forever` is handled BEFORE this by `keep_alive_forever()` in `release` (→ `Pinned`), so
+            // this arm is only reached defensively (e.g. a caller that resolves ms without the pin
+            // check) — fall back to the default rather than a huge linger.
+            Linger::Forever => 10_000,
         };
     }
     std::env::var("PUNKTFUNK_MONITOR_LINGER_MS")
@@ -1014,6 +1057,17 @@ fn linger_ms() -> u64 {
         .unwrap_or(10_000)
 }
 
+/// Whether the configured console policy's `keep_alive` resolves to **forever** (`Pinned`) — the
+/// gaming-rig preset. `release` uses this to keep the last-released monitor indefinitely instead of
+/// lingering. Unconfigured hosts are never forever (default is a short linger).
+fn keep_alive_forever() -> bool {
+    use crate::vdisplay::policy::{prefs, Linger};
+    prefs()
+        .configured_effective()
+        .map(|eff| matches!(eff.keep_alive.linger(), Linger::Forever))
+        .unwrap_or(false)
+}
+
 /// The effective display topology for a freshly-created monitor (never `Auto`): the console policy's
 /// [`effective_topology`](crate::vdisplay::effective_topology) when configured, else the legacy
 /// `PUNKTFUNK_NO_ISOLATE` env knob (`Extend`) / `Exclusive` (today's default). `Extend` leaves the IDD

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

@@ -415,7 +415,7 @@ pub(crate) unsafe fn isolate_displays_ccd(keep_target_id: u32) -> Option<SavedCo
     // live topology each attempt and re-apply until ONLY the keep target is active. Secure-desktop
     // correctness depends on this — the lock screen must not land on a stray panel while we stream.
     for attempt in 1..=4u32 {
-        let (mut paths, mut modes) = query_active_config()?;
+        let (mut paths, modes) = query_active_config()?;
         let mut others = 0u32;
         for p in paths.iter_mut() {
             if p.targetInfo.id == keep_target_id {
@@ -492,8 +492,10 @@ pub(crate) unsafe fn set_virtual_primary_ccd(keep_target_id: u32) -> Option<Save
         }
         let idx = p.sourceInfo.Anonymous.modeInfoIdx as usize;
         let m = modes.get(idx)?;
+        // `then_some` (eager): `sourceMode.width` is a POD `u32` union read, discarded when the arm is
+        // false — no lazy guard needed. (`then(|| …)` here trips clippy::unnecessary_lazy_evaluations.)
         (m.infoType == DISPLAYCONFIG_MODE_INFO_TYPE_SOURCE)
-            .then(|| m.Anonymous.sourceMode.width as i32)
+            .then_some(m.Anonymous.sourceMode.width as i32)
     })?;
     let others = paths.len().saturating_sub(1);
 

crates/punktfunk-tray/src/status.rs

@@ -33,6 +33,10 @@ pub struct Summary {
     pub native_paired_clients: u32,
     pub pin_pending: bool,
     pub pending_approvals: u32,
+    /// Virtual displays kept with no live session (lingering/pinned). `#[serde(default)]` so an older
+    /// host that doesn't send it deserializes as 0.
+    #[serde(default)]
+    pub kept_displays: u32,
 }
 
 #[derive(Clone, Copy, Debug, PartialEq, serde::Deserialize)]
@@ -71,6 +75,14 @@ impl TrayStatus {
                     s.version, sess.width, sess.height, sess.fps
                 ),
                 (_, true) => format!("punktfunk host {} — streaming", s.version),
+                // Idle, but surface a kept (lingering/pinned) display: it — and, under an exclusive
+                // topology, your physical monitors — is being held. Release it from the console.
+                _ if s.kept_displays > 0 => format!(
+                    "punktfunk host {} — idle · {} display{} kept",
+                    s.version,
+                    s.kept_displays,
+                    if s.kept_displays == 1 { "" } else { "s" }
+                ),
                 _ => format!("punktfunk host {} — idle", s.version),
             },
         }
@@ -432,6 +444,7 @@ mod tests {
             native_paired_clients: 2,
             pin_pending: false,
             pending_approvals: 0,
+            kept_displays: 0,
         }
     }
 

design/display-management.md

@@ -1,8 +1,27 @@
 # Virtual-display management & lifecycle policy — design
 
-> **Status (2026-07-05):** **Stages 0–4 DONE + on-glass validated; Stage 5 STARTED** (branch
-> `display-mgmt-stage0`, not yet merged). See the **Status — handoff** block under §11 for the
-> per-stage state, the key decisions (notably the Windows `reject` default), and what's left.
+> **Status (2026-07-05):** **Stages 0–5 (§6A) DONE + on-glass validated; keep-alive reconnect
+> hardened** (branch `display-mgmt-stage0`, not yet merged). Stage 5 §6A: display **groups**
+> (`registry::group_key` — one per desktop backend, each gamescope spawn its own), group-aware
+> `exclusive`/`primary` (KWin name-filter + first-slot-wins; Mutter `set_first_in_group`), **per-group
+> topology restore** (KWin restore floats through the group, runs on the last member's teardown), the
+> **layout engine** (`vdisplay/layout.rs`, auto-row + manual) + registry-driven `apply_position`, the
+> `PUT /display/layout` endpoint with group/position/index in `/display/state`, and the **web console
+> arrangement table** — **live-validated on KWin `.116` + Mutter `.21`** (group model, positions,
+> identity keying, group-aware exclusive/extend, 2 concurrent Mutter `RecordVirtual` monitors). The
+> Stage-3 **KDE scaling round-trip is now proven live** (set 150 %/125 % → disconnect → reconnect →
+> reapplied, seen in `kwinoutputconfig.json`). **Keep-alive reconnect hardening (`b53710d`, on-glass
+> validated with the probe):** a same-client reconnect **preempts its own zombie**
+> (`admission::preempt_same_identity` — fixes "reconnect within the idle-detection window lands on a
+> fresh SECOND display while the old one keeps streaming"), a **deliberate quit skips the linger**
+> (client closes with `QUIT_CLOSE_CODE` 0x51 → `registry::release(force_immediate)`; §5.1), and the QUIC
+> control-connection idle timeout (the disconnect-detection latency) is **host-tunable**
+> (`PUNKTFUNK_IDLE_TIMEOUT_MS` / `--idle-timeout-ms`, default 8 s). **Remaining Stage 5 = hardware-gated
+> residuals only**: the per-group physical-restore EFFECT (needs a monitor-attached Linux box — the
+> headless validation boxes report `also_disabled=[]`, so nothing is disabled to restore), wlroots
+> `exclusive` (needs a Sway box), Mutter `APPLY_TEMPORARY` disconnect-revert. See the **Status —
+> handoff** block under §11 for the per-stage state and key decisions (notably the Windows `reject`
+> default).
 > This doc designs a **policy layer on top of the
 > existing per-compositor `VirtualDisplay` backends** — user-configurable lifecycle (keep-alive
 > after disconnect), topology (primary / exclusive), conflict handling (what happens when a second
@@ -14,7 +33,11 @@
 
 Companion docs: `design/implementation-plan.md` §6 (virtual displays), `design/vrr-plan.md`
 (pacing — out of scope here), `design/gamescope-multiuser.md` (per-session isolation — adjacent,
-not required).
+not required), **`design/gamemode-and-dedicated-sessions.md`** (PLANNED — reconciles this layer
+with session-mobile Bazzite/SteamOS hosts: display **ownership classes** so the registry stops
+pooling gamescope managed/attach outputs it doesn't own, validated reuse + invalidation, the
+§5.1 "policy replaces the managed 5 s debounce" promise actually implemented, and the dedicated
+per-launch gamescope game sessions built on it).
 
 ## 1. Goal
 
@@ -258,7 +281,11 @@ plumbing) does not. Concretely per backend, "the display survives" means:
 - **gamescope (managed)**: the policy duration replaces the hardcoded 5 s
   `RESTORE_DEBOUNCE` — the warm Steam session stays up for the window; `forever` means the TV
   session is never auto-restored (release via console/tray).
-- **Windows**: the existing linger, plus `forever` = the new `Pinned` state.
+- **Windows**: the existing linger, plus `forever` = the `Pinned` state — **shipped** (`ccbd7e8`,
+  `MgrState::Pinned`; compile-verified on `.173`, on-glass Windows Pinned pending). Freed via
+  `POST /display/release` (`force_release` handles Pinned) — the §8 escape hatch. `gaming-rig` (the
+  `forever` preset) is no longer mgmt-rejected and is enabled in the console; **on-glass validated on
+  Linux** (`.116` KWin: normal disconnect → `pinned`, no expiry; Release frees it).
 
 **Rules.**
 - Input devices (uinput pads, libei/EIS contexts) stay session-scoped — a disconnect reads to
@@ -267,10 +294,21 @@ plumbing) does not. Concretely per backend, "the display survives" means:
 - The **launch command runs once per display creation, never per attach** — a reconnect to a
   kept gamescope must not double-launch the game. Today launch already happens once per
   `build_pipeline`-successful session; the invariant moves with the create into the registry.
-- An explicit client **quit** (GameStream `cancel`/quit-app; a future punktfunk/1
-  `EndSession{quit}` control message — protocol growth, trailing-byte back-compat as usual)
-  bypasses keep-alive: the user said "stop the game", so tear down now. Plain disconnects and
-  connection losses honor the policy.
+- An explicit client **quit** (a user "stop", not a network drop) bypasses keep-alive: tear down
+  now. **Implemented on punktfunk/1** (`b53710d`, on-glass validated): the client closes the QUIC
+  connection with `QUIT_CLOSE_CODE` (0x51, shared in `core::quic`); the host reads the
+  `ApplicationClosed` reason and does `registry::release(force_immediate)` → `Linger::Immediate` →
+  teardown, skipping the linger. `NativeClient::disconnect_quit()` + `punktfunk-probe --quit` drive
+  it; GameStream `cancel`/quit-app (`h_cancel`) + the five real clients sending the code are
+  follow-ups. A plain disconnect / connection loss honors the policy (lingers for reconnect).
+- A **same-client reconnect resumes** (never a fresh second display). A reconnect while the client's
+  own prior session is still `Active` — its QUIC idle timer hasn't fired, and detection lags a drop by
+  `max_idle_timeout` (default 8 s, host-tunable via `PUNKTFUNK_IDLE_TIMEOUT_MS` / `--idle-timeout-ms`)
+  — is recognised by `admission::preempt_same_identity` (same cert fingerprint): the host signals the
+  zombie's stop + waits the release grace, so it lingers and the reconnect **reuses** the kept display.
+  Without this, a reconnect inside the detection window landed on a fresh second display while the old
+  session kept streaming. **Implemented + on-glass validated** (`b53710d`); implements the "preempts
+  downstream" the admission layer already promised (§5.3).
 - Host shutdown tears everything down (RAII on exit, as today). A host crash leaves whatever
   the OS reclaims — Wayland connections die with the process (compositor reclaims outputs),
   spawned gamescopes die with the process group, the pf-vdisplay watchdog reaps monitors when
@@ -545,7 +583,7 @@ out per-host instead of lying:
 
 | Capability | KWin | gamescope spawn | gamescope managed | gamescope attach | Mutter | wlroots | Windows |
 |---|---|---|---|---|---|---|---|
-| keep-alive (linger/forever) | ✅ hold the vout thread; re-attach PipeWire consumer to the kept node — **validate** | ✅ nested session + game survive; re-discover node | ✅ policy replaces the 5 s debounce | — (never owned it) | ✅ hold the D-Bus session; consumer re-attach — **validate** | ✅ output persists; fresh portal capture per attach (cleanest) | ✅ shipped; add `Pinned` |
+| keep-alive (linger/forever) | ✅ hold the vout thread; re-attach PipeWire consumer to the kept node — **validate** | ✅ nested session + game survive; re-discover node | ✅ policy replaces the 5 s debounce | — (never owned it) | ✅ hold the D-Bus session; consumer re-attach — **validate** | ✅ output persists; fresh portal capture per attach (cleanest) | ✅ shipped incl. `Pinned` (forever) |
 | reconfigure kept display to a new mode | ✅ `set_custom_refresh` + kscreen mode | ✅ SIGKILL+respawn is the honest "reconfigure" (game restarts — docs say so) or decline → recreate | ✅ existing managed-mode set | — | ⚠ node is sized by negotiation; renegotiation unproven — fallback recreate | ✅ `output <n> mode --custom` | ✅ `reconfigure()` shipped |
 | topology: primary | ✅ | n/a | n/a | n/a | ✅ | ❌ → extend | ✅ (new, small) |
 | topology: exclusive | ✅ shipped (filter → group-aware) | n/a | n/a | n/a | ✅ shipped (→ group-aware) | ✅ (new, small) | ✅ shipped (→ group-aware) |
@@ -556,7 +594,12 @@ out per-host instead of lying:
 
 The **attach** gamescope sub-mode never owns the display (it mirrors a foreign gamescope) — the
 registry records it as an unmanaged pass-through slot: no keep-alive, no topology, no identity,
-conflict = join-only. That's just codifying reality.
+conflict = join-only. That's just codifying reality. **Gap (2026-07-05):** the shipped registry
+does NOT implement this row — it pools every `remote_fd == None` output, including the
+managed/attach/SteamOS paths' unit-keepalive outputs, which double-owns the managed session
+against the gamescope module's own restore worker (stale-node reuse wedge on game-mode
+reconnect). The fix — explicit display **ownership classes** + registry-owned managed-session
+restore — is designed in `design/gamemode-and-dedicated-sessions.md` Part A.
 
 ## 8. Management API, web console, tray
 
@@ -667,9 +710,27 @@ GNOME/Mutter, RTX 5070 Ti), **`.116`** (Bazzite KDE/KWin, AMD — build via a `f
   via `effective_topology()`), 3 (platform-neutral `identity.rs` map + `per-client-mode` + KWin per-slot
   output naming → **KWin persists per-output scale by name**, proven via `kwinoutputconfig.json` on `.116`),
   4 (mode-conflict admission — `vdisplay/admission.rs`, loopback-validated for all four policies).
-- **Stage 5: STARTED** — only the critical §6.1 **group-aware exclusive** fix for KWin has landed
-  (`kwin.rs` `MANAGED_PREFIX` + first-slot-wins), unit-tested but NOT yet driven by two concurrent
-  sessions on-glass. Everything else in Stage 5 is TODO.
+- **Stage 5 (§6A): DONE + on-glass validated (KWin `.116` + Mutter `.21`).** All §6A group semantics
+  landed + unit-tested, then live-validated (group model, positions, identity keying, group-aware
+  exclusive/extend, 2 concurrent Mutter `RecordVirtual` monitors; the dev VM itself is GPU-less):
+  **display groups** (`registry::group_key` — one
+  per desktop backend, each gamescope spawn its own group), **group-aware exclusive/primary** (KWin
+  `MANAGED_PREFIX` + first-slot-wins; Mutter `set_first_in_group` → a non-first session extends rather than
+  re-clobbering), **per-group topology restore** (KWin hands its restore to the registry via
+  `take_topology_restore`; `Entry::topology_restore` + `hand_off_restore` float it to a surviving sibling
+  and run it only when the group empties, before the last output drops — all 3 teardown paths), the pure
+  **layout engine** (`vdisplay/layout.rs::arrange`, auto-row + manual) + **registry-driven `apply_position`**
+  (`position_for_new` over the whole group; skips the origin so the single-display path is unchanged), the
+  `PUT /api/v1/display/layout` endpoint (`EffectivePolicy::with_manual_layout`), and `/display/state` now
+  carrying `group`/`display_index`/`position`/`identity_slot`/`topology`. The registry keys the arrangement
+  on per-client identity via `VirtualDisplay::last_identity_slot` (KWin). The **web arrangement table**
+  (`DisplayCard.tsx` `DisplayArrangement`, en+de) is also done, moved to its own **Virtual displays** nav
+  section with a full one-click-preset config surface. **Remaining = hardware-gated residuals only:** the
+  per-group physical-restore EFFECT (needs a monitor-attached box — the headless boxes report
+  `also_disabled=[]`), wlroots `exclusive` (needs a Sway box), Mutter `APPLY_TEMPORARY` disconnect-revert —
+  see the Stage 5 entry below. Plus the **keep-alive reconnect hardening** (`b53710d`, on-glass validated):
+  same-client zombie preempt + deliberate-quit skip-linger + tunable idle timeout (§5.1) — what made
+  "reconnect resumes" actually hold under a fast reconnect.
 
 **Decisions / deltas from this plan as written — read before continuing:**
 - **Windows admission default is `reject`, NOT `join`** (supersedes the Stage-4 line below). Two
@@ -687,11 +748,18 @@ GNOME/Mutter, RTX 5070 Ti), **`.116`** (Bazzite KDE/KWin, AMD — build via a `f
 - **GameStream 503** is implemented (owner-fp on `LaunchSession`, `gamestream_admission()` unit-tested,
   shares `effective_conflict()`) but NOT Moonlight-validated (can't drive `/launch` autonomously).
 
-**Deferred (need a display-attached box / a specific compositor / a real client):** the `primary`
-physical-keep EFFECT on Linux + a Windows primary-only CCD variant; **wlroots `exclusive`**; the KWin
-set-150 %-scaling ROUND-TRIP (SSH can't drive `kscreen-doctor` into the live session — the persist
-mechanism itself is already proven); GameStream 503 on-glass; two-concurrent-session validation of the
-Stage-5 group-aware exclusive.
+**Validated since (2026-07-05):** the KWin **set-scaling ROUND-TRIP** — a client set 150 % then 125 %
+in the streamed KDE session, disconnected, reconnected, and the scale was reapplied to the freshly
+re-created `Virtual-punktfunk-<id>` (proven in `kwinoutputconfig.json`); this closes the Stage-3 gate.
+Also the §6A group model + group-aware exclusive/extend + 2 concurrent Mutter `RecordVirtual` monitors,
+and the keep-alive reconnect hardening.
+
+**Still deferred (need a display-attached box / a specific compositor / a real client):** the `primary`
+physical-keep EFFECT on Linux + a Windows primary-only CCD variant; **wlroots `exclusive`**; GameStream
+503 on-glass; and the **per-group physical-restore EFFECT** — a monitor-attached box is required to see
+`exclusive` disable a physical output and the group restore re-enable it only after the last member drops
+(the headless boxes report `also_disabled=[]`, so the group semantics are proven but the physical
+toggle isn't).
 
 - **Stage 0 — policy + plumbing-lite. [DONE ✓]** `policy.rs` (schema/presets/persist/env-compat, fully
   unit-tested), mgmt GET/PUT `/display/settings`, console card (settings only), docs page
@@ -714,8 +782,11 @@ Stage-5 group-aware exclusive.
 - **Stage 3 — identity. [DONE ✓]** Platform-neutral identity map + migration, per-slot KWin output
   naming (+ the concurrent-session name-clash fix riding along), GameStream identity wiring,
   optional `per-client-mode` keying, per-client `default_scale` on KWin.
-  *Validate on KDE:* connect client A → set 150 % scaling → disconnect → reconnect → scaling
-  reapplied; client B unaffected; `kwinoutputconfig.json` inspected for the named entries.
+  *Validated on KDE (`.116`, 2026-07-05):* a client set 150 % then 125 % in the streamed session,
+  disconnected, reconnected (keep-alive off → full teardown+recreate), and the scale was reapplied to
+  the fresh `Virtual-punktfunk-<id>` — confirmed in `kwinoutputconfig.json` (`scale=1.25` persisted by
+  connector name). This is the round-trip the persist mechanism was designed for. *(client-B-unaffected
+  under two concurrent sessions is folded into the Stage-5 two-session case.)*
 - **Stage 4 — mode-conflict admission. [DONE ✓]** Decision function (`vdisplay/admission.rs`,
   `decide`/`admit`/`effective_conflict`) wired into the punktfunk/1 handshake + GameStream `h_launch`,
   the typed punktfunk/1 `busy` refusal (QUIC close `0x42` + reason), GameStream 503 path, `steal`
@@ -723,18 +794,79 @@ Stage-5 group-aware exclusive.
   `join`/silent-reconfigure originally planned** — see the handoff Decisions above (single-capturer
   IDD-push). Loopback-validated (all four policies) + `.173` reject-default validated; GameStream 503
   unit-tested, Moonlight-pending.
-- **Stage 5 — §6A multi-client monitors. [STARTED]** Display groups, group-aware exclusive/primary/
-  restore (incl. the name-filter fix), layout auto-row + manual, `/display/layout`, console
-  arrangement table. Cheap: rides Stages 1–3 infrastructure, no protocol change.
-  **Done so far:** KWin group-aware `exclusive` (the name-filter fix — recognise the managed group by
-  the `Virtual-punktfunk` prefix instead of one hardcoded name) + first-slot-wins for the group
-  primary, unit-tested. **TODO:** Mutter + wlroots group-aware analogues (Mutter is more involved — its
-  sole-monitor `ApplyMonitorsConfig` must include ALL group virtuals, not just its own); layout
-  auto-row + manual + `/display/layout` + console table; per-group topology restore (restore the
-  physical only when the group's LAST member drops); gamescope groups (single-output → decline extras).
-  *Validate:* two clients (probe + GTK) on the headless KDE box forming a 2-output desktop;
-  drag a window across; disconnect one → its slot lingers per policy, sibling unaffected,
-  restore only after both drop.
+- **Stage 5 — §6A multi-client monitors. [DONE ✓ — on-glass validated (KWin `.116` + Mutter `.21`); hardware-gated residuals deferred]** Display
+  groups, group-aware exclusive/primary/restore (incl. the name-filter fix), layout auto-row + manual,
+  `/display/layout`, console arrangement table. Cheap: rides Stages 1–3 infrastructure, no protocol change.
+  **Done:**
+  - KWin group-aware `exclusive` (the name-filter fix — recognise the managed group by the
+    `Virtual-punktfunk` prefix instead of one hardcoded name) + first-slot-wins for the group primary,
+    unit-tested.
+  - **Layout engine** (`vdisplay/layout.rs::arrange`): pure auto-row (left-to-right in acquire order,
+    top-aligned) + manual (per-identity-slot offsets, auto-row fallback for unpinned members),
+    unit-tested. `manual_position` helper for a single backend-local apply.
+  - **Registry group model** (Linux): group = backend (one desktop per compositor session); the
+    `/display/state` snapshot groups entries, orders by acquire (gen), and computes each member's
+    `position` via the engine. `DisplayInfo` now carries `group` / `display_index` / `position` /
+    `identity_slot` / `topology`. The backend reports its resolved slot via the new
+    `VirtualDisplay::last_identity_slot` (KWin only), so the arrangement + state key on per-client identity.
+  - **`PUT /api/v1/display/layout`**: persists the console's manual arrangement (positions keyed by
+    identity slot) via the pure `EffectivePolicy::with_manual_layout` transform (locks the current
+    effective behavior into explicit `Custom` fields + sets a manual layout — arranging is orthogonal to
+    the other axes). OpenAPI regenerated.
+  - **Registry-driven position apply** (`VirtualDisplay::apply_position(x, y)`, default no-op; KWin
+    implements it via `kscreen-doctor output.<n>.position.<x>,<y>`): the registry owns the group, so
+    right after `create` it computes the new display's position over the whole group via the pure
+    `position_for_new` (existing same-backend members in acquire order + the new one appended last →
+    `layout::arrange` → the new member's placement) and calls `apply_position`. This makes **both**
+    auto-row (deterministic left-to-right, not just the compositor's default) **and** manual placement
+    go through one seam. Guarded: the registry skips the desktop origin `(0, 0)`, so a single-display /
+    first-of-group session (and every non-KWin backend, which no-ops `apply_position`) issues no
+    positioning at all — the historical single-display path is byte-for-byte unchanged. `position_for_new`
+    is unit-tested. *On-glass-validation-pending (kscreen positioning of a live virtual output).*
+  - **Per-group topology restore** (design §6.1 — restore the physical only when the group's LAST member
+    drops): the KWin `exclusive` restore no longer rides the per-session `StopGuard` (which would re-enable
+    the physical the moment the FIRST of several exclusive sessions dropped, under a live sibling). KWin
+    now hands the restore to the registry as a closure (`take_topology_restore`); the registry keeps it in
+    the display **group** (`Entry::topology_restore`) and, on teardown, **floats** it to a surviving
+    same-group sibling (`hand_off_restore`) or, when the group empties, runs it — outside the lock, BEFORE
+    the last output's keepalive drops, so the compositor never sees zero outputs. All three teardown paths
+    (lease drop / linger expiry / mgmt release) honor it. The single-display path is byte-for-byte
+    unchanged (one member → run on its teardown). `hand_off_restore` is unit-tested (float / run-on-last /
+    non-carrier-first / never-cross-backend). *Residual concurrent-connect race + two-session on-glass
+    validation pending.*
+  - **Mutter group-aware** (`set_first_in_group`): the registry tells each backend whether it is the
+    FIRST display of its group; a non-first Mutter session **extends** into the already-exclusive desktop
+    instead of re-applying a sole-monitor `ApplyMonitorsConfig` that would disable the first session's
+    virtual. (Simpler than the originally-planned "include all group virtuals," which Mutter can't do —
+    its connectors are un-nameable — and achieves the same connect-time outcome.) Single-session unchanged
+    (`first == true`). *Residual: Mutter `APPLY_TEMPORARY` reverts the topology when the FIRST session
+    leaves under a live sibling (§7) — a full fix needs a group-owned `DisplayConfig` connection; deferred.
+    Concurrent-Mutter on-glass validation pending (even ≥2 `RecordVirtual` monitors is unproven).*
+  - **gamescope groups** (design §6.1): a gamescope **spawn** is an independent nested session per client
+    (no shared desktop), so `registry::group_key` makes each gamescope display its OWN group — never
+    auto-rowed against, topology-grouped with, or restore-grouped with another gamescope. Unit-tested.
+    (§6B single-output "decline extras" is Stage 6.)
+  - **Console arrangement table (web)** [DONE ✓]: a `DisplayArrangement` x/y editor in the `Virtual
+    displays` card (`web/src/sections/Host/DisplayCard.tsx`) — for a ≥2-display group it renders an x/y
+    table over the live displays that carry an identity slot, seeded from `/display/state`, and Save
+    writes `PUT /display/layout` (switches the host to a manual layout, applied next connect). en+de
+    i18n; the stale `display_pending_note` copy refreshed. tsc + vite build green. (Drag mini-map is a
+    later stretch.)
+  **Remaining Stage 5 — hardware-gated residuals only (no more host/web build work):**
+  - **On-glass validation — mostly DONE (2026-07-05, KWin `.116` + Mutter `.21`):** the group model,
+    per-member positions, identity keying, group-aware `exclusive`/`extend` coexistence (a 2nd session
+    does NOT clobber the 1st's output), and **2 concurrent Mutter `RecordVirtual` monitors** are all
+    confirmed live; the keep-alive reconnect path (reuse, quit-skip-linger, tunable idle) was validated
+    deterministically with the probe. **STILL PENDING: the per-group physical-restore EFFECT** — both
+    boxes are headless so `also_disabled=[]` (nothing to disable → nothing to restore); seeing
+    `exclusive` black out a real monitor and the group restore re-enable it only after the LAST member
+    drops needs a **monitor-attached Linux box**. The group-restore LOGIC (`hand_off_restore`) is
+    unit-tested; only the physical effect is unobserved.
+  - **wlroots group-aware exclusive** stays deferred: wlroots `exclusive` is not implemented at all (needs
+    a Sway box), so there is no topology to make group-aware yet. §6A multi-view on wlroots already works
+    (independent `HEADLESS-N` outputs).
+  - **Mutter `APPLY_TEMPORARY` disconnect-revert** (§7): when the FIRST Mutter session leaves under a live
+    sibling, Mutter reverts the topology — a full fix needs a group-owned `DisplayConfig` connection.
 - **Stage 6 — §6B protocol + Linux host + GTK client.** `VIDEO_CAP_MULTI_DISPLAY`, control-
   stream Add/Remove/DisplayAdded, per-flow nonce-salt derivation, per-display pipelines on
   KWin/wlroots, input display-index routing, C ABI additions, GTK client multi-window

design/gamemode-and-dedicated-sessions.md

@@ -0,0 +1,439 @@
+# Game-mode integration & dedicated game sessions — design
+
+> **Status: IMPLEMENTED (2026-07-05), Linux on-glass validation pending.** Parts A (A1–A5) and B
+> (B0–B2) landed; `cargo build`/`test --workspace`/`clippy -D warnings`/`fmt` green, OpenAPI
+> regenerated. It reconciles the shipped display-management layer (`design/display-management.md`,
+> Stages 0–5 merged `95b3496`) with **session-mobile hosts** — Bazzite/SteamOS boxes that flip
+> between Steam Game Mode (gamescope) and a KDE/GNOME desktop — and adds **dedicated game sessions**:
+> a `game_session=dedicated` policy that serves every library launch from its own host-spawned
+> headless gamescope at the client's exact mode, booting straight into the game with no Steam Big
+> Picture and no game mode.
+>
+> ## Implementation status (as-built — read the deviations)
+>
+> - **A1 (ownership classes) — DONE.** `DisplayOwnership {Owned, External, SessionManaged}` on
+>   `VirtualOutput`; the registry pools only `Owned` outputs on the default daemon. gamescope
+>   spawn = `Owned`, attach = `External`, managed/SteamOS = `SessionManaged`, KWin/Mutter/Windows =
+>   `Owned`, wlroots = `Owned` but gated out by `remote_fd`. Plus `VirtualDisplay::poolable_now()`
+>   so a managed/attach acquire never reuses a kept bare-spawn. **This alone removes the reported
+>   Bazzite game-mode-reconnect stale-node wedge** (managed sessions are no longer pooled).
+> - **A2 (validated reuse) — DONE.** Reuse keys on `(backend, mode, launch, epoch)`;
+>   `VirtualDisplay::kept_display_alive()` (gamescope checks its node is still present) tears a dead
+>   kept display down and recreates; `VirtualOutput::reused_gen` + `registry::mark_failed(gen)` on a
+>   reused-display first-frame failure so the retry loop creates fresh instead of re-wedging.
+> - **A3 (managed restore) — DONE, but DEVIATES from the plan below.** The managed/SteamOS session
+>   is a **single-instance box singleton** (one Steam per uid), so making it a registry-`Owned` pool
+>   entry (as §4-A3 sketches) collides with its single-instance nature on a mode-change relaunch
+>   (two `ManagedSessionHandle` drops fighting over the shared `SESSION_UNIT`/autologin). Since A1
+>   already fixed the wedge, A3 instead **keeps the managed session's own single-instance lifecycle**
+>   (`MANAGED_SESSION`/`STOPPED_AUTOLOGIN`/`STEAMOS_TOOK_OVER` + the restore worker) and makes only
+>   its **restore policy-driven**: `schedule_restore_tv_session` reads `restore_delay()` = the
+>   `keep_alive` policy (`off`→0s, `duration`→N s, **`forever`→never** = gaming-rig held, unconfigured
+>   →5s bit-for-bit). Plus **crash-restore persistence** (`$XDG_RUNTIME_DIR/punktfunk-session-takeover.json`
+>   → `restore_takeover_on_startup`) and the **SIGKILL-teardown** experiment in `stop_session`
+>   (followups.md #1/#7). *Not done:* `/display/release` freeing a `forever`-held managed session
+>   (managed isn't a registry entry) — a forever managed box returns to gaming mode by manual switch
+>   or host restart (documented; acceptable for a dedicated couch appliance).
+> - **A4 (session epoch) — DONE.** `session_epoch()`/`bump_session_epoch()` + `ActiveSession.compositor_pid`;
+>   `observe_session_instance()` (called from the per-connect resolve, the mid-stream watcher, the
+>   capture-loss re-detect, and the GameStream acquire) bumps the epoch + `registry::invalidate_backend`
+>   on a compositor-instance change (kind change OR same-kind restart). `take_expired` also reaps
+>   kept dead-epoch entries.
+> - **A5 (addressed discovery) — PARTIAL.** Per-spawn **log** (`$XDG_RUNTIME_DIR/punktfunk-gamescope-<inst>.log`)
+>   + **scoped node discovery** (`find_gamescope_node_scoped` by `application.process.id` /
+>   `descends_from`) — fixes concurrent bare-spawn VIDEO-node ambiguity (the load-bearing correctness
+>   part). **DEFERRED:** the per-instance **EIS input relay** — the injector-coupling rework the map
+>   warned about ("EIS setup timed out"); input for concurrent gamescopes stays on the global relay,
+>   which is exactly `design/gamescope-multiuser.md` scope. Noted there.
+> - **B0 (dedicated routing) — DONE.** `GameSession {Auto, Dedicated}` — a **top-level** `DisplayPolicy`
+>   field (NOT in `EffectivePolicy`, so presets don't clobber it). `pick_gamescope_mode` gains a leading
+>   `dedicated_launch` that forces `Spawn` (below explicit operator env, above managed-infra/foreign);
+>   `wants_dedicated_game_session()` (launch present ∧ policy dedicated ∧ gamescope available, else
+>   honest `auto` fallback) → `resolve_compositor(pref, dedicated)` forces gamescope; threaded through
+>   `apply_input_env(chosen, dedicated_launch)`. Steam URIs are shaped `steam -silent steam://…`
+>   (`shape_dedicated_command`). GameStream shares the dispatch.
+> - **B1 (Steam single-instance takeover) — FOCUSED.** A dedicated **Steam** spawn frees the box's
+>   autologin/game-mode Steam first (`is_steam_launch` → `stop_autologin_sessions`, restored on session
+>   end via the A3 machinery). *Not done:* force-releasing a *kept dedicated Steam* session for a
+>   *different* Steam game (two concurrent dedicated Steam sessions) — rare; documented degradation.
+> - **B2 (game-exit clean end) — DONE.** A dedicated gamescope session whose node vanishes
+>   (`dedicated_game_exited()` — gamescope is single-app, dies with its game) ends the session with the
+>   new `APP_EXITED_CLOSE_CODE` (0x52) so launcher clients return to their library, instead of the 40 s
+>   capture-loss rebuild timeout.
+> - **B3 (docs/console) — this block + docs-site + CLAUDE.md; the web console toggle is the remaining
+>   surface.** The `game_session` axis is in the API + OpenAPI now.
+>
+> **Adversarial review pass (2026-07-05):** a multi-agent review confirmed 11 findings, all fixed:
+> (1) `registry::acquire` held the pool mutex across the `pw-dump` liveness probe → the probe now runs
+> OUTSIDE the lock (snapshot candidate under lock → probe → re-lock + re-find by gen); (2–5,7,10) the
+> session epoch / `invalidate_backend` wrongly tore down **independent gamescope spawns** on any Gaming
+> pid flap (the CRITICAL "dedicated Steam on a game-mode box self-destructs" — B1 stopping the autologin
+> flipped the winning PID) → `observe_session_instance` now acts ONLY on **desktop** compositor changes,
+> and `epoch_matches` exempts gamescope from the epoch (reuse + reap); (3) a dedicated-Steam reconnect
+> didn't cancel the pending TV restore (reuse skips `create`) → `cancel_pending_tv_restore()` on every
+> connect; (4,8) B2 game-exit used the UNSCOPED node scan → now scoped to the session's own `node_id`
+> (threaded through the pipeline); (9) an unknown launch id → blank gamescope → dedicated now gated on
+> the launch RESOLVING to a command. All green after fixes (`test --workspace` 360).
+>
+> **Remaining before this is "shipped":** Linux on-glass validation (`.116` Bazzite-KWin game-mode
+> reconnect under presets, `.21`/`.116` dedicated launch, gaming-rig-forever held-managed, crash-restore,
+> SIGKILL-teardown F44 check), and the two documented deferrals (A5 per-instance EIS relay →
+> gamescope-multiuser; B1 concurrent-dedicated-Steam release).
+>
+> The **PLAN as originally written follows** — it still reads as "PLANNED"; the status block above is
+> the authority on what actually shipped and where it deviates.
+
+Companion docs: `design/display-management.md` (the policy/registry layer this reconciles — its
+§7 capability matrix and §5.1 gamescope semantics are amended here),
+`design/session-aware-host-followups.md` (open session-switch limitations #1/#7 are resolved by
+Part A3 below), `design/gamescope-multiuser.md` (per-session input/audio isolation — adjacent;
+Part B deliberately stops short of it and cross-references instead).
+
+## 1. The two problems
+
+**(A) The display-management rewrite does not compose with Bazzite game mode / KDE switching.**
+The registry (`vdisplay/registry.rs`) assumes it owns every display it pools: it holds the
+backend keepalive, decides linger/pin/teardown from the policy, and reuses kept displays by
+`(backend, mode)`. On a session-mobile box that assumption is false twice over — the gamescope
+managed/attach paths hand it outputs whose lifecycle is owned by *other* machinery
+(`MANAGED_SESSION` + the debounced TV-restore worker), and the compositor under **every** Linux
+backend can be killed and replaced at any moment by a Game↔Desktop switch. The result is pool
+entries that lie: they linger or pin while the session behind them is torn down, then get reused
+as dead nodes and wedge the whole retry budget.
+
+**(B) Library launches deserve a first-class "just the game" mode.** Today a library launch on a
+Bazzite box rides the managed `gamescope-session-plus` Steam session (Big Picture at the client's
+mode, launch forwarded into the running Steam) — the game appears, but inside game mode's whole
+UX, with Steam BPM boot time and game-mode ownership of the box. The bare-spawn path that nests
+*just* the resolved command in a headless gamescope already exists and works — but the sub-mode
+ladder makes it unreachable exactly where users want it most (any box with session-plus/SteamOS
+infra picks managed). The ask: a host option so a library launch **always** gets a dedicated
+gamescope session at the client's requested mode — game boots directly; non-Steam titles
+instantly, Steam titles without any UI to navigate.
+
+These are one design because both reduce to the same question: **who owns a gamescope session's
+lifecycle, and how does the registry know?** Part A answers it for what exists; Part B builds the
+new launch mode on the answer.
+
+## 2. Failure inventory (code-anchored)
+
+What actually goes wrong today, in dependency order:
+
+1. **The registry pools externally-owned outputs.** `registry::linux::acquire` pools every output
+   with `remote_fd == None`. The gamescope **managed**, **SteamOS-takeover**, and **attach** paths
+   all return `remote_fd: None` with `keepalive: Box::new(())` (`gamescope.rs::create_managed_session`
+   / `create_managed_session_steamos` / the attach arm) — a unit keepalive that keeps *nothing*
+   alive. The pool entry claims ownership of a display it cannot hold or tear down.
+2. **Two lifecycle owners for the managed session → stale-node reuse wedge.** The real managed
+   lifecycle is `MANAGED_SESSION` + `PENDING_RESTORE` + `RESTORE_DEBOUNCE` (hardcoded 5 s) + the
+   restore worker, which stops the session and restarts the TV autologin. With any `keep_alive`
+   policy configured, a disconnect leaves a registry entry Lingering (e.g. 300 s) while the restore
+   worker kills the session at 5 s. A reconnect inside the linger window **reuses the dead
+   `node_id`**; capture fails "no PipeWire frame within 10s"; the capturer drop returns the entry to
+   Lingering; `build_pipeline_with_retry` re-acquires the **same corpse** on every attempt — all 8
+   retries wedge (~90 s). This is the `.41`-class "game-mode reconnect broken" symptom, now
+   *manufacturable on any Bazzite box by clicking a console preset*.
+3. **`gaming-rig` (keep_alive=forever) is a lie on gamescope.** Design §5.1 promised "the policy
+   duration replaces the hardcoded 5 s debounce; forever = the TV session is never auto-restored".
+   Never implemented: the restore worker doesn't read the policy, so `forever` pins an entry whose
+   session the worker restores away regardless.
+4. **A session switch leaves zombie entries.** The mid-stream watcher rebuild and the per-connect
+   re-detect drop the old backend's lease → the old entry lingers/pins **for a compositor that no
+   longer exists** (KWin dies on the switch to game mode; the game-mode gamescope dies on the switch
+   to desktop). `/display/state` lies; expiry drops keepalives into dead compositors; a
+   Desktop→Game→Desktop bounce brings up a *new* KWin whose node-id space has no relation to the
+   kept entry's — reuse hands out a number that now means nothing.
+5. **Discovery is ambient and ambiguous.** One shared spawn log (`/tmp/punktfunk-gamescope.log`),
+   name-based node discovery (`find_gamescope_node` returns *any* `gamescope` `Video/Source`), and
+   one global EIS relay file (`punktfunk-gamescope-ei`). Correct only while at most one gamescope
+   exists per uid. A kept spawn + live game mode, two concurrent spawns, or (Part B) a dedicated
+   session next to game mode can capture the wrong node and inject into the wrong session.
+6. **Stock Bazzite restarts the systemd user manager on every Game↔Desktop switch** (observed on
+   `.41`: user-manager PID churn), killing the host, the compositor, and the pool together. Inherent
+   — keep-alive **cannot** span a switch on a stock setup (the headless-appliance setup —
+   `enable-linger` + `multi-user.target` — keeps the host alive and can). Separately, the takeover
+   bookkeeping (`STOPPED_AUTOLOGIN`, `STEAMOS_TOOK_OVER`, the SteamOS drop-in) is process memory
+   only: a host crash mid-stream strands the box out of game mode with no restore on restart.
+
+## 3. Design principles
+
+- **One owner per display.** Every `VirtualOutput` declares who owns its lifecycle; the registry
+  pools only what it owns. This extends the CLAUDE.md invariant ("display lifecycle is owned by
+  the registry; sessions hold leases") with its honest converse: *what the registry does not own,
+  it must not pretend to keep.*
+- **Keep-alive is an optimization, never a failure mode** (display-management §3, now enforced):
+  reuse validates liveness; a failed reuse invalidates and creates fresh; the retry budget is
+  never spent twice on the same corpse.
+- **The compositor instance, not the host process, is the unit of session truth.** A session
+  epoch invalidates every display created under a previous compositor instance — kind changes
+  *and* same-kind restarts.
+- **Addressed, not ambient, discovery.** Every spawned gamescope gets its own log, its own node
+  resolution, its own EIS relay. Global singletons are what break the moment two sessions coexist.
+- **Launch identity is part of display identity.** A kept display running game A must never be
+  handed to a session asking for game B.
+
+## 4. Part A — ownership & session mobility
+
+### A1. Ownership classes (the structural fix — ship first)
+
+`VirtualOutput` gains an ownership declaration:
+
+```rust
+pub enum DisplayOwnership {
+    /// The registry owns lifecycle: pool, linger, pin, tear down. (KWin, Mutter, gamescope
+    /// SPAWN, Windows manager-delegated.)
+    Owned,
+    /// Someone else's display, mirrored: no keep-alive, no topology, no reuse — codifies the
+    /// display-management §7 "attach = unmanaged pass-through" row the code never implemented.
+    /// (gamescope ATTACH; wlroots stays gated on remote_fd as today.)
+    External,
+    /// A box-level session the gamescope module manages (managed session-plus / SteamOS
+    /// takeover). Pass-through at A1 (capturer owns the lease as pre-Stage-1); A3 converts it
+    /// to Owned by giving the registry the real keepalive + restore duty.
+    SessionManaged,
+}
+```
+
+The registry pools `Owned` only; `External`/`SessionManaged` pass through unchanged (today's
+pre-registry behavior — teardown-on-capturer-drop is a no-op for their unit keepalives, and the
+existing gamescope-module machinery keeps doing what it does). `remote_fd == Some` keeps its gate.
+
+Effect: failures 1–3 stop being reachable from the console — a preset can no longer create lying
+entries for game-mode sessions. Smallest possible diff; everything else layers on it. Until A3
+lands, keep-alive on gamescope managed/attach honestly reports **unsupported** in
+`/display/state` capabilities instead of pretending.
+
+### A2. Validated reuse, invalidation, launch key
+
+- **Launch key.** `Entry` gains `launch: Option<String>` (the resolved launch command the display
+  was created with; `None` = plain desktop). Reuse requires `(backend, mode, launch)` equality.
+  Without this, a kept spawn running game A is reused for a session that asked to launch game B —
+  latent today (unconfigured Linux lingers Immediate), live the moment keep-alive + launches
+  combine, load-bearing for Part B.
+- **Liveness probe at reuse.** New trait method, default honest:
+  `fn kept_display_alive(&mut self, node_id: u32) -> bool { true }` — gamescope-spawn checks the
+  child (`try_wait`) *and* the node; KWin/Mutter check the node still exists on the default
+  daemon (one cheap PipeWire registry roundtrip — no capture attach). A dead entry is torn down
+  (its group restore handed off / run) and the acquire falls through to a fresh create.
+- **Invalidation on reuse failure.** `acquire` marks the returned `VirtualOutput` as reused (a
+  flag on the lease/gen); when `build_pipeline`'s first-frame fails on a **reused** display, it
+  calls `registry::mark_failed(gen)` before returning the error — the entry is torn down, so the
+  retry loop's next `acquire` **creates fresh** instead of re-wedging on the same corpse. This is
+  the direct fix for failure 2's 8×10 s wedge shape, and it holds for every future way a kept
+  display can silently die.
+
+### A3. One owner for the managed session (registry-owned restore)
+
+The managed/SteamOS paths become `Owned` by giving the registry the two things it lacks:
+
+- **A real keepalive.** `create_managed_session*` returns a `ManagedSessionHandle` whose `Drop`
+  performs today's `do_restore_tv_session` duty: stop the transient unit / remove the SteamOS
+  drop-in, then restart the autologin **iff no desktop session is active** (the existing guard
+  moves in verbatim — a user who switched to KDE mid-linger is never yanked back to game mode).
+- **The policy as the debounce.** The registry linger *is* the restore delay: unconfigured
+  default = 5 s (bit-for-bit today's `RESTORE_DEBOUNCE`), a configured duration replaces it,
+  `forever` = never auto-restore — `gaming-rig` finally means on a Bazzite couch box what its
+  story says, released via `/display/release` or the tray. A reconnect inside the linger is a
+  registry **reuse** (the same warm-session fast path `PENDING_RESTORE`-cancel gives today, now
+  with A2 validation); a different requested mode tears down + relaunches through the registry
+  (gamescope's honest "reconfigure = recreate").
+- **Retire the parallel machinery.** `PENDING_RESTORE`, `RESTORE_DEBOUNCE`,
+  `start_restore_worker`, and the `restore_managed_session()` call sites go away — the registry
+  linger timer is the one timer. `MANAGED_SESSION` survives only as the module's mode/unit cache.
+  `STOPPED_AUTOLOGIN`/`STEAMOS_TOOK_OVER` stay as the *mechanics* the handle's Drop consumes.
+- **Persist the takeover.** The stopped-unit list + SteamOS-drop-in marker are written to
+  `$XDG_RUNTIME_DIR/punktfunk-session-takeover.json` at takeover, cleared at restore. On host
+  startup, a leftover file (crash / service restart mid-stream) schedules a restore after a short
+  reconnect grace — with the same active-desktop guard. A crashed host no longer strands the TV.
+- **Teardown signal.** Adopt the parked follow-ups doc #1 experiment here: the handle's stop uses
+  `systemctl --user kill --signal=SIGKILL <unit>` (+ `stop`/`reset-failed` to clear unit state)
+  instead of plain SIGTERM stop, testing the hypothesis that skipping gamescope's crashy SIGTERM
+  teardown avoids the F44 GPU-context leak. A3's validation pass is the natural place to measure
+  it; fall back to SIGTERM if SIGKILL misbehaves. Follow-ups #7 (restore-guard/keep-warm
+  interaction) dissolves: "keep warm" is now just `keep_alive: forever`.
+
+### A4. Session epoch & backend invalidation
+
+- **`vdisplay::session_epoch()`** — a host-global counter bumped whenever session detection
+  observes a different compositor **instance**: an `ActiveKind` change *or* a new compositor PID
+  for the same kind (the Desktop→Game→Desktop bounce). Entries stamp their creation epoch; reuse
+  requires an epoch match; the linger timer reaps entries from dead epochs (their keepalive Drops
+  hit dead sockets and fail fast; the registry already drops outside the lock).
+- **Watcher hook.** A `SessionSwitch` (and a per-connect re-detect that finds the previous
+  backend's compositor gone) additionally calls `registry::invalidate_backend(old)` so
+  `/display/state` is honest immediately rather than at the next expiry poll.
+- **Stock-Bazzite user-manager restarts** stay inherent: the host dies with the switch, the pool
+  dies with the host, and that is documented ("keep-alive spans a Game↔Desktop switch only on the
+  headless-appliance setup"). The persisted takeover file (A3) is what survives.
+
+### A5. Addressed discovery (Part-B prerequisite)
+
+- **Per-spawn log**: `$XDG_RUNTIME_DIR/punktfunk-gamescope-<gen>.log`; the spawned instance's
+  node id is parsed from *its* log only.
+- **Scoped node discovery**: PipeWire node props carry `application.process.id` — a spawn's node
+  must belong to our child's PID tree (`descends_from`, already written); managed/attach
+  discovery conversely **excludes** nodes owned by our spawned children. `find_gamescope_node`
+  grows a scope parameter instead of "first node named gamescope".
+- **Per-instance EIS relay**: `punktfunk-gamescope-ei-<gen>`, path carried on `VirtualOutput`
+  (the gamescope-multiuser doc's item 1), with the injector service resolving the session's own
+  relay for gamescope sessions (a narrow slice of its item 2 — the shared injector stays for the
+  portal backends, where shared input is correct and where per-session churn caused the historic
+  "EIS setup timed out" wedge).
+
+### Part A validation (on-glass, `.116` Bazzite KWin/AMD + Deck `.253`; `.21` for spawn-on-GNOME)
+
+1. Game-mode reconnect: connect → disconnect → reconnect inside game mode, under *every* preset
+   incl. `gaming-rig` (the failure-2/3 repro — must reuse the warm session or cleanly recreate,
+   never wedge the retry budget).
+2. Game↔Desktop switch mid-linger both directions; Desktop→Game→Desktop bounce (epoch test);
+   `/display/state` never lists a display whose compositor is dead.
+3. `gaming-rig` on Bazzite: TV stays off until `/display/release`; a KDE switch mid-linger is not
+   yanked back to game mode.
+4. Kill -9 the host mid-takeover → restart → TV session restored (persisted-takeover test).
+5. Two gamescopes coexisting (kept spawn + game mode): capture and input land in the right one.
+
+## 5. Part B — dedicated game sessions for library launches
+
+### 5.1 What it is
+
+A session that carries a launch id (native `Hello.launch`, the GTK `--browse`/`--launch` flows,
+Decky pins, GameStream apps with a library id) can be served by a **dedicated gamescope
+session**: a host-spawned headless gamescope at exactly the client's WxH@Hz whose nested command
+is the resolved game. No Steam Big Picture, no game mode, no desktop involvement. Session end
+returns the client to its launcher (already shipped behavior); the game survives disconnects per
+`keep_alive` — the Apollo-style detach/reattach the design always wanted, now per-game.
+
+### 5.2 Policy surface
+
+One new axis in `display-settings.json` (same store/PUT/console pattern; serde-defaulted so
+existing files are untouched):
+
+```json5
+// How a session that LAUNCHES a game is served:
+//   "auto"      – today's routing: the launch rides whatever session the box is in (managed
+//                 Steam session on Bazzite/SteamOS, bare spawn on plain distros, spawned into
+//                 the live desktop on KWin/Mutter/wlroots)
+//   "dedicated" – a launching session always gets its own headless gamescope at the client's
+//                 mode, nesting just the game
+"game_session": "auto"
+```
+
+Sessions **without** a launch id are untouched by this axis — desktop streaming routes exactly as
+today. `dedicated` degrades honestly: no gamescope binary → log + fall back to `auto`. Console: a
+toggle on the Virtual displays card (it is a display-lifecycle decision) with one story line.
+Deliberate non-options for v1: per-entry overrides (schema keys allow a later
+`"per_entry": {"<id>": …}` overlay) and a client-requested Hello byte ("launch dedicated") — host
+policy first, protocol growth when a client actually wants to differ per connect.
+
+### 5.3 Routing & command shaping
+
+- **Sub-mode ladder.** `pick_gamescope_mode` (pure, unit-tested) gains a leading
+  `dedicated_launch: bool` input that forces `Spawn`, outranking managed-infra/foreign-attach
+  (explicit operator `MANAGED`/`ATTACH`/`NODE` envs still win — they are debug/CI overrides).
+  `resolve_compositor` computes it: launch id present ∧ policy `dedicated` ∧ gamescope available
+  → chosen = `Gamescope`, spawn sub-mode; `launch_is_nested` then routes the command into the
+  spawn as today.
+- **Non-Steam entries** (custom / lutris / heroic): the resolved command nests directly — truly
+  instant (gamescope up in ~1 s, then the game's own boot).
+- **Steam entries** (`steam steam://rungameid/<id>`): Steam is single-instance per uid, so:
+  1. Command shape becomes `steam -silent steam://rungameid/<id>` in dedicated mode — `-silent`
+     suppresses the Steam main window so the game is the gamescope focus. **Empirical validation
+     item** (behavior of `-silent` under a fresh nested Steam); fallback is the plain URI form
+     (a briefly-visible Steam client, still no BPM navigation).
+  2. If another same-uid Steam is live (game mode autologin, a kept managed session, a kept
+     dedicated Steam session): **take Steam over first** — force-release kept entries whose
+     `launch` is a Steam title, stop the autologin via the A3-owned takeover (persisted state,
+     policy-driven restore). This reuses the exact machinery game mode streaming already needs;
+     `dedicated` adds no new churn class.
+- **Game exit ends the session.** When the nested command exits (user quits the game), the
+  gamescope child dies; today's capture-loss path would rebuild an empty session. Dedicated
+  sessions instead end cleanly: the rebuild path consults the keepalive child (`try_wait`) and a
+  confirmed child exit becomes a typed session end (host closes QUIC with a new
+  `APP_EXITED_CLOSE_CODE`, sibling of `QUIT_CLOSE_CODE` 0x51, so launchers can distinguish "game
+  ended" from an error) with `force_immediate` release. Clients need no change to *work* (they
+  already return to the launcher on session end); the typed code is polish they can adopt.
+- **Mid-stream `Reconfigure`** on a dedicated session = teardown + respawn (gamescope cannot
+  live-resize its output; the game restarts) — the same honest §7 caveat as managed, documented.
+
+### 5.4 Lifecycle composition (where Part A pays off)
+
+- Dedicated outputs are `Owned` (A1) with the child as a real keepalive → they pool naturally.
+- Reuse keys on `(backend, mode, launch)` (A2): reconnect to the same game re-attaches to the
+  still-running session instantly; a different game never falsely reuses. `keep_alive` then reads
+  exactly as the presets promise: `off` = game dies with the disconnect; a duration = the detach
+  window; `forever` = the game runs until released (`gaming-rig`, per-game).
+- Each dedicated session is already its own registry **group** (`group_key` — no topology or
+  restore interaction with the desktop); `max_displays` bounds how many can be kept; Steam
+  titles are additionally bounded to one by the single-instance takeover above.
+- Input rides the per-instance EIS relay (A5); uinput gamepads are per-session already. Audio and
+  mic stay the host-wide shared services — one *active* dedicated session is the designed case;
+  concurrent independent-audio sessions are exactly `design/gamescope-multiuser.md` scope, not
+  re-solved here.
+- Admission (`mode_conflict`) applies unchanged across clients; a second client asking for a
+  different dedicated game under `separate` gets its own spawn (non-Steam) or the single-instance
+  takeover rules (Steam) — the honest per-backend gating pattern.
+
+### 5.5 GameStream
+
+Same dispatch (the launch path was unified in the 2026-07-01 rebuild): an apps.json/library-id
+launch under `dedicated` spawns the same way; serverinfo/RTSP negotiate the client's mode as
+today. Moonlight's quit-app (`h_cancel`) maps to a `force_immediate` release — killing the game
+on explicit quit — which folds into the already-deferred "GameStream quit-code" follow-up from
+display-management §5.1.
+
+### 5.6 Client experience & latency honesty
+
+No client changes are required: GTK `--browse`/`--launch`, Decky pins, and the Apple/Android
+library grids just launch, and session end already returns to the launcher. Boot-time
+expectations, stated plainly in docs: non-Steam titles are gamescope-spawn (~1 s) + game boot;
+Steam titles pay the Steam client's own cold boot inside the fresh session (~10–25 s class)
+before the game process starts — "no UI to navigate", not "zero seconds". A pre-warmed parked
+Steam (`steam -silent` held inside a background headless gamescope at host start) would close
+that gap but fights game mode over the single instance — explicitly out of scope for v1, noted
+as the one candidate v2 if Steam cold boot proves to be the complaint. **Stretch** (needs a small
+mgmt surface, not v1): launchers showing "Resume" for a game the host reports as kept
+(`/display/state` already exposes the entries; adding `launch` to `DisplayInfo` is the only
+schema growth).
+
+## 6. Staging & dependencies
+
+| Stage | Contents | Depends on | Validation |
+|---|---|---|---|
+| **A1** | `DisplayOwnership`, pool `Owned` only, honest capabilities | — | unit + `.116` game-mode reconnect under presets no longer wedges |
+| **A2** | launch key, `kept_display_alive`, `mark_failed` on reused-display capture failure | A1 | probe-driven: kill a kept display's session → reconnect creates fresh on attempt 2 |
+| **A3** | `ManagedSessionHandle`, policy-as-debounce, retire restore worker, persisted takeover, SIGKILL-teardown experiment | A1 | `.116`/Deck: gaming-rig semantics, crash-restore, desktop-guard |
+| **A4** | session epoch, `invalidate_backend` on switch | A1 | `.116`: switch matrix incl. same-kind bounce; `/display/state` honesty |
+| **A5** | per-spawn log, scoped node discovery, per-instance EIS relay | — (parallel) | two-gamescope coexistence test |
+| **B0** | `game_session` policy + ladder input + steam `-silent` shaping | A1 (correctness), A5 (if game mode may be live) | `.21`/plain box: non-Steam + Steam dedicated launch on glass |
+| **B1** | Steam takeover integration (autologin stop / kept-Steam release) | A3 | `.116`/Deck: dedicated launch from game mode, TV restore per policy |
+| **B2** | reuse-by-launch reattach + game-exit-ends-session (`APP_EXITED` close) | A2 | disconnect → game keeps running → reattach; quit game → launcher |
+| **B3** | docs (virtual-displays + steamos-host pages), console toggle polish, "Resume" stretch | B0–B2 | — |
+
+Every stage lands green (`cargo test/clippy/fmt`, OpenAPI drift) and independently shippable,
+per the display-management discipline. A1+A2 alone fix the user-visible breakage; A3 makes the
+presets truthful; B0 is the first user-visible new capability.
+
+## 7. Risks & open questions
+
+- **`steam -silent` inside a fresh nested gamescope** — the load-bearing empirical unknown for
+  B0's Steam polish (the launch itself works either way; only the cosmetic Steam-window flash is
+  at stake). Validate first on `.21`/`.116` desktop mode.
+- **Bare spawn vs session-plus environment** — session-plus wraps Steam in MangoApp/runtime/
+  controller-config scaffolding a bare `gamescope -- steam` lacks. The historic "nested Steam
+  crashes" finding was Steam-vs-Steam single-instance (both dying), *not* a missing-scaffolding
+  failure — with Steam taken over first, a bare spawn should hold, but this is exactly what B1's
+  on-glass pass must prove per box (Bazzite, Deck).
+- **PipeWire `application.process.id` availability** across gamescope versions (A5's scoped
+  discovery) — fall back to log-derived ids (per-spawn logs make those unambiguous already).
+- **Keepalive drops into dead compositors** (A4 reaping): Wayland conns fail fast; Mutter's D-Bus
+  `Stop` can block — the registry already drops outside the lock, keep it that way and bound the
+  damage to one reaper tick.
+- **Epoch granularity**: detecting "new compositor instance, same kind" needs the compositor PID
+  in `ActiveSession` — cheap (the `/proc` scan already visits it), but the watcher must debounce
+  PID flaps during a switch (its existing 3 s debounce covers it).
+- **Injector rework caution** (A5): per-session EIS injectors only for gamescope; the shared
+  service stays for portal backends — re-learning the "EIS setup timed out" lesson is the failure
+  mode to guard in review.
+- **Windows**: entirely untouched — `game_session` is Linux-only for now (`launch_title` on
+  Windows opens via the shell into the one desktop); the policy field documents that honestly
+  rather than pretending.

design/security-posture-audit-2026-07-05.md

@@ -0,0 +1,202 @@
+# punktfunk — security posture audit (2026-07-05)
+
+> **Status:** AUDIT COMPLETE (2026-07-05). Whole-project **posture** audit — not a finding hunt
+> like [`security-review.md`](security-review.md) (2026-06-21) and
+> [`security-review-2026-06-28.md`](security-review-2026-06-28.md) (host follow-up), but an
+> assessment of the overall security architecture, the state of the prior reviews' remediations,
+> the delta landed since 2026-06-28 (display management Stages 0–8, WoL wake-until-up,
+> `--data-port`, web display-config surface), and the process/supply-chain controls around the
+> code. Method: single-reviewer read of the trust-model core (`quic.rs`, `crypto.rs`,
+> `session.rs`, `native_pairing.rs`, `punktfunk1.rs`, `mgmt.rs`, `mgmt_token.rs`, the web BFF
+> auth stack, `gamestream/{pairing,crypto,control}.rs`, `discovery.rs`, `wol.rs`), plus sweeps
+> for TLS-bypass patterns, committed secrets, unsafe density, CI workflow hygiene, and the
+> dependency/advisory pipeline.
+
+## Executive summary
+
+**The posture is strong — unusually so for a project of this size.** The core trust
+architecture is sound and shows defense-in-depth discipline: a modern, mutually-authenticated
+native plane (QUIC + rustls, fingerprint pinning with real `CertificateVerify` verification,
+SPAKE2 pairing with cert-fingerprint identity binding); a management plane with a clean
+authn/authz split (loopback-confined bearer for admin, deny-by-default read-only allowlist for
+paired mTLS certs); a web console that never leaks the admin token to the browser and fails
+closed when misconfigured; legacy GameStream compatibility correctly quarantined behind an
+explicit opt-in; and a supply chain guarded by scheduled `cargo audit`, a tightly-justified
+ignore list, a license allowlist, and an exact-pinned toolchain. The two prior reviews' 18
+findings are remediated or accepted-with-rationale, and the fixes are visible (and in several
+cases regression-tested) in the code today.
+
+**No new high-severity issue was found.** The residual risk concentrates in the **web console's
+password gate** (no brute-force throttling; cookie-sealing key derived from the login password)
+and in **second-tier supply-chain gaps** (no advisory scanning for the Bun/Nitro stack;
+tag-pinned third-party CI actions holding deploy secrets). All are bounded by the documented
+threat model (trusted LAN / VPN, no WAN exposure) but are cheap to close and worth closing.
+
+## Remediation status (2026-07-05)
+
+All findings from this audit were fixed the same day, plus one Windows LPE gap (F-8) surfaced by a
+reviewer during remediation. Verification notes are per-item.
+
+| # | Sev | Status |
+|---|-----|--------|
+| F-1 | Medium | **FIXED** — per-IP exponential-backoff login throttle (`web/server/util/loginThrottle.ts` + `login.post.ts`); 5 free attempts then 1s→5min backoff, global floor, size-capped map. Behaviorally tested (backoff, unlock, IP-independence, success-clear). |
+| F-2 | Medium | **FIXED** — cookie-seal key now derived from the CSPRNG mgmt token (`sessionConfig` in `auth.ts`), not the login password; password-derivation kept only as a no-token dev fallback. A captured cookie is no longer an offline password oracle. |
+| F-3 | Low | **FIXED** — accept-any-cert scoped to the loopback proxy hop via Bun per-request `tls` (`routes/api/[...].ts`, gated on `isLoopbackUrl`); process-wide `NODE_TLS_REJECT_UNAUTHORIZED=0` removed from all 4 deploy files + 3 docs. A non-loopback mgmt URL now verifies normally. |
+| F-4 | Low | **FIXED** — `bun audit` job added to `audit.yml` (weekly + on `web/bun.lock` change), same fail-on-vulnerability stance as `cargo audit`. |
+| F-5 | Low | **FIXED** — the three secret-touching third-party actions SHA-pinned with version comments: `appleboy/scp-action`, `appleboy/ssh-action` (deploy SSH key + registry token, `docker.yml`), `android-actions/setup-android` (signing keystore + Play SA, `android.yml`/`android-screenshots.yml`). GitHub-owned `actions/*` left on major tags (org controls the tag). |
+| F-6 | Info | No change (accepted) — tray loopback accept-any-cert; spoofed-status-only, local-process out of scope. |
+| F-7 | Info | No change (documented) — session-layer input replay; native plane rides replay-protected QUIC, GameStream covered by the trusted-LAN caveat. |
+| **F-8** | **Medium** | **FIXED** — see below. `driver install` executed/trusted files from `--dir` with no check the dir was admin-only → local EoP if the payload is staged somewhere user-writable. Added a DACL/owner check (`ensure_admin_only_source` in `windows/install.rs`) that fails closed. Verified: Win32 FFI typechecks against `windows 0.62.2` for `x86_64-pc-windows-msvc`. |
+
+### F-8 (Medium) — driver install trusts a non-admin-writable source directory
+
+**Reported by the user during remediation; confirmed.** `punktfunk-host driver install --dir <stage>`
+runs **elevated** (the Inno `[Run]` section, or a manual admin invocation) and, from `--dir`,
+**executes** `nefconc.exe`, trusts a `.cer` into the machine `Root`/`TrustedPublisher` stores, and
+`pnputil /add-driver`s the package — with **no check that `--dir` is writable only by
+administrators**. If the staging directory is writable by a non-admin, a local unprivileged user can
+plant a malicious `nefconc.exe` (arbitrary code as the elevated installer → SYSTEM) or swap the
+`.cer` (poisoning the machine trust store) before the elevated step consumes it — a local elevation
+of privilege.
+
+**Not exploitable in the default install** (correctly noted by the reporter): the shipped installer
+stages into `{tmp}` under a `DefaultDirName={autopf}` (Program Files), `PrivilegesRequired=admin`
+Inno setup, which restricts the staging dir to Administrators/SYSTEM. The gap bites only when the
+payload is staged somewhere user-writable — a custom install directory, or a hand-run
+`driver install --dir <user-writable>`. *Fix:* `ensure_admin_only_source` reads the directory's
+owner + DACL (`GetNamedSecurityInfoW`) and refuses to proceed unless every principal with a
+create/write/delete/DACL-rewrite right is SYSTEM/Administrators/TrustedInstaller (or CREATOR-OWNER
+under a privileged owner). Fails **closed** — an unreadable ACL is treated as unsafe — and, like
+every other step in the best-effort installer, a refusal only degrades the host to a physical
+display; it never aborts the install.
+
+## Trust architecture assessment
+
+### Native plane (punktfunk/1) — sound
+
+- **Transport:** QUIC via quinn 0.11.11 / rustls 0.23.41 (ring). Data-plane sessions are
+  created with `encrypt: true` (`punktfunk1.rs:959`) and per-session random key+salt.
+- **Identity & pinning:** hosts serve a persisted self-signed cert; clients pin its SHA-256
+  (TOFU only as the documented bootstrap special case, `endpoint::client_insecure` =
+  `client_pinned(None)`). Crucially, the pin verifier still verifies TLS 1.2/1.3 handshake
+  signatures for real (`quic.rs:2064-2096`) — possession of the pinned cert's key is proven,
+  the classic pin-without-CertificateVerify hole is explicitly avoided. The host-side
+  `AcceptAnyClientCert` likewise verifies the handshake signature, so a client fingerprint is
+  proof of key possession, not just a presented blob.
+- **Pairing (SPAKE2):** the ceremony binds *both* certificate fingerprints as SPAKE2
+  identities, so a MITM presenting different certs to each leg cannot reach a shared key.
+  Key-confirmation MACs are compared constant-time. The PIN is CSPRNG-minted, **single-use and
+  consumed before the client's proof is read** (`punktfunk1.rs`, `pair_ceremony`) — an
+  attacker gets exactly one online guess per operator arming, rate-limited further by the 2s
+  `PAIRING_COOLDOWN`. Arming windows can be **fingerprint-bound** (prior review #9), and the
+  delegated-approval pending queue is flood-resistant (per-source-IP cap, parked-knock
+  eviction protection, TTL — prior review #13, all regression-tested in `native_pairing.rs`).
+- **Session AEAD:** AES-128-GCM with a documented nonce-uniqueness contract (per-direction
+  salt bit, per-session key+salt, zero-key rejected by config validation), sequence bound as
+  AAD. Wire decoders bound every attacker-controllable header field (`packet.rs:323`,
+  `ReassemblerLimits`); pairing/control messages are length-checked with exact-trailing-bytes
+  rejection.
+- **Untrusted-input hygiene:** client-supplied device names are sanitized against control
+  chars, ANSI escapes, and Unicode bidi overrides before storage/log/UI
+  (`native_pairing.rs::sanitize_device_name`) — approval-UI spoofing is handled.
+- **Trust store:** atomic temp+rename writes, owner-only permissions (0600/DACL via
+  `write_secret_file`), in-memory rollback on persist failure.
+
+### Management plane — sound
+
+- HTTPS always; bearer token always required (env > owner-only persisted file > generated;
+  `mgmt_token.rs`). Token comparison hashes both sides before comparing (`mgmt.rs::token_eq`),
+  neutralizing timing.
+- The **bearer (full-admin) path is honored only from loopback peers**, even though the
+  listener binds all interfaces by default; LAN callers must present a **paired** mTLS cert
+  and are confined to a deny-by-default, GET-only allowlist (`cert_may_access`) — a paired
+  streaming client cannot administer the host (unpair others, read/arm PINs, stop sessions,
+  or mutate the library/display config). The new display-management routes stayed off the
+  cert allowlist, with a regression test (`display_settings_surface stays read-only`).
+- `/api/v1/local/summary` (tray status) is unauthenticated but loopback-only and
+  deliberately non-sensitive.
+
+### Web console (Nitro/Bun BFF) — good design, two hardening gaps (F-1, F-2)
+
+- Single shared password gate; **fails closed** (503) when `PUNKTFUNK_UI_PASSWORD` is unset;
+  constant-time compare; sealed (AES-GCM) `httpOnly` `SameSite=lax` session cookie with a
+  7-day TTL; open-redirect guard on the post-login path; `/api/**` always gated; the mgmt
+  bearer token is injected **server-side only** and browser cookies are stripped from the
+  upstream request. Public-path allowlisting is by path, not extension (with the reasoning
+  documented — `openapi.json` exposure via a `*.json` allowlist was anticipated and avoided).
+- Gaps: no login throttling (F-1), cookie-sealing key derived from the password when
+  `PUNKTFUNK_UI_SECRET` is unset (F-2), process-wide `NODE_TLS_REJECT_UNAUTHORIZED=0` for the
+  loopback proxy hop (F-3).
+
+### GameStream/Moonlight compatibility — correctly quarantined
+
+Off by default; enabled only by `--gamestream`/`--moonlight`, and documented (SECURITY.md,
+`--help`) as legacy-crypto, trusted-LAN-only. Within that constraint the implementation is
+defensively built: PIN delivery only via the authenticated management API (never nvhttp —
+prior #1), parked-handshake caps (#12), one RSA signature per ceremony (Marvin-amplifier
+hardening, S7), phase-repeat rejection, RTSP gated on a paired `/launch` bound to the
+launching peer's IP (#4). The AES-128-ECB pairing crypto and mostly-plaintext media streams
+are wire-compatibility constraints of the Moonlight protocol, not implementation choices, and
+the input-replay gap at the raw-UDP session layer is documented in code
+(`session.rs:31-35`) and covered by the trusted-LAN assumption.
+
+### Discovery & Wake-on-LAN — appropriately advisory
+
+mDNS TXT records (`fp`, `mac`, `pair`, `mgmt`) are treated as unauthenticated hints
+everywhere they're consumed: pinning still gates the actual connection, and a spoofed MAC
+only makes a wake fail (magic packets are inert). `wol.rs` detect-and-warn never mutates NIC
+state.
+
+### Supply chain & process — mature
+
+- **Rust:** `cargo audit` weekly + on every `Cargo.lock` change + on demand
+  (`.gitea/workflows/audit.yml`); the `.cargo/audit.toml` ignore list is tight, justified,
+  and *self-correcting* (the RUSTSEC-2023-0071 entry documents that its own earlier rationale
+  was wrong and re-justifies the accept on corrected grounds — exemplary). Key crypto deps
+  are current (rustls 0.23.41, quinn 0.11.11, ring 0.17.14). License allowlist enforced via
+  `cargo-about` (no copyleft in the linked set). Exact toolchain pin (1.96.0).
+- **Secrets hygiene:** no committed key material or real `.env` files (templates only);
+  secret files routed through `write_secret_file` (0600 + Windows SYSTEM/Admins DACL).
+- **Process:** SECURITY.md with private reporting, coordinated disclosure, and safe harbor;
+  two prior deep reviews with per-finding remediation tracking; findings referenced by number
+  in code comments and regression tests.
+- Gaps: no JS-side advisory scanning (F-4); third-party actions tag-pinned, not SHA-pinned
+  (F-5).
+
+## Findings (this audit)
+
+No High findings. Severities assume the documented LAN/VPN threat model.
+
+| # | Sev | Component | Finding |
+|---|-----|-----------|---------|
+| F-1 | **Medium** | web console | **No throttling on `POST /_auth/login`** (`web/server/routes/_auth/login.post.ts`). The constant-time compare stops timing leaks but not volume: a LAN peer can brute-force `PUNKTFUNK_UI_PASSWORD` at network speed against a console that is, by design, LAN-exposed. Every other password/PIN gate in the project is rate-limited (pairing cooldown, single-use PINs) — this is the one unthrottled secret. *Fix:* small in-memory failure counter with exponential backoff (per source IP + global), mirroring `PAIRING_COOLDOWN`'s philosophy. |
+| F-2 | **Medium** | web console | **Cookie-sealing key is derived from the login password** when `PUNKTFUNK_UI_SECRET` is unset (`web/server/util/auth.ts::sessionConfig` — `sha256("punktfunk-session-v1:" + password)`). A captured session cookie (e.g. sniffed over the plain-HTTP dev/LAN mode, where `Secure` is off by default) becomes an **offline dictionary oracle for the password**: an attacker tries candidate passwords by deriving the key and attempting to unseal — no server round-trips, so F-1's fix doesn't help. *Fix:* generate and persist a random 32-byte secret on first start when `PUNKTFUNK_UI_SECRET` is unset (same pattern as `mgmt_token.rs`), instead of deriving from the password. |
+| F-3 | Low | web console | **`NODE_TLS_REJECT_UNAUTHORIZED=0` is process-wide**, not scoped to the loopback mgmt hop it's documented for (`web/.env.example:25`, README). Today the BFF makes no other outbound TLS call, so the practical scope holds — but it's a global switch that silently unverifies any *future* fetch (an update check, an art CDN, a webhook). *Fix:* drop the env var and pass the host's own `cert.pem` as a per-fetch CA (Bun `fetch` `tls.ca` / undici `Agent`), which also removes a scary line from the deployment docs. |
+| F-4 | Low | supply chain | **No advisory scanning for the web stack.** `audit.yml` covers the Rust tree only; the Bun/Nitro BFF — the component that holds the login gate, session sealing, and the mgmt token — has a `bun.lock` but no scheduled vulnerability scan. *Fix:* add a job running `bun audit` (or `osv-scanner --lockfile web/bun.lock`) on the same weekly + lockfile-change triggers. |
+| F-5 | Low | CI | **Third-party actions are tag-pinned, not SHA-pinned.** `appleboy/ssh-action@v1.2.5` / `appleboy/scp-action@v0.1.7` receive deploy SSH credentials, and `actions/checkout@v4` / `cache@v4` run on every job on self-hosted runners; a moved tag = code execution on the runners plus secret exfiltration. Given how rigorous the Rust-side supply chain is, this is the soft spot. *Fix:* pin at least the secret-touching actions to full commit SHAs. |
+| F-6 | Info | tray / local | The tray's status fetch (`punktfunk-tray/src/status.rs`) uses the accept-any-cert verifier against `127.0.0.1:47990`. If the host isn't running, any local unprivileged process can squat the port and feed the tray fake status. Impact is spoofed tray UI only (the tray sends no secrets and the summary is non-sensitive) — consistent with the documented "local processes are out of scope" stance. No action needed; recorded for completeness. |
+| F-7 | Info | core session | Input-event replay at the raw-UDP session layer remains unfiltered — **already documented** in `session.rs:31-35` with the correct future home (a sliding window keyed on the authenticated sequence, in the GameStream host). The native plane is unaffected (client input rides QUIC datagrams, which are inherently replay-protected). Keep the doc note honest until the GameStream path grows the window; it stays covered by the opt-in/trusted-LAN caveat. |
+
+## Prior-review remediations — spot-verified present
+
+- #1 (PIN only via bearer mgmt API): confirmed — `PinGate` doc + no nvhttp PIN route.
+- #2 (mgmt token via `write_secret_file`): confirmed — `mgmt_token.rs:62`.
+- #9 (fingerprint-bound arming windows): confirmed — `arm_for`/`pin_for_attempt` + tests.
+- #12 (parked-waiter cap): confirmed — `MAX_PARKED_WAITERS` + atomic slot reservation.
+- #13 (per-IP pending cap, parked-knock protection): confirmed — constants + tests.
+- S7 (rsa Marvin accept): rationale in `.cargo/audit.toml` matches the corrected version;
+  one-signature-per-ceremony hardening referenced in the ignore justification.
+
+## Priorities
+
+1. **F-1 + F-2 together** (web console password gate): a login backoff plus a
+   generated-not-derived cookie secret close the only realistic LAN-attacker path to admin
+   found in this audit. Both are small, isolated changes.
+2. **F-4 + F-5** (supply chain parity): one CI job and a handful of SHA pins bring the JS
+   stack and the workflows up to the standard the Rust tree already meets.
+3. **F-3** (scoped CA instead of the global TLS switch): low urgency, high
+   docs/appearance value.
+
+Nothing found here changes the documented threat model or contradicts SECURITY.md's stated
+limits. The next full finding-hunt review should focus on the Windows vdisplay/driver
+admission surface (largest post-2026-06-28 delta) and the web console once F-1/F-2 land.