fix(clients/android): the button correction fired on pads that never needed it

Two field reports (2026-08-21), one shape: a GameSir G8+ and an Xbox Elite
Series 2 ("Xbox Wireless Controller" over Bluetooth) with X answering Y, Y
answering LB, and the two shoulders answering menu buttons — everything else
correct. That is not a stray mapping, it is exactly what `GENERIC_XBOX` does to
scancodes `0x133`/`0x134`/`0x136`/`0x137`, so the correction added yesterday was
firing on pads whose buttons were already where `Generic.kl` says they are.

It fired because it asked the wrong question. `hasKeys(BUTTON_C, BUTTON_Z)`
answers for what a device DECLARES, not what it reports: `hid-input` allocates
`BTN_A + n` straight through for every button in the descriptor, so BTN_C
(`0x132`) and BTN_Z (`0x135`) are set on ANY pad declaring six or more —
including a standard-layout pad that never presses either. The signal is
therefore identical on the pad that needs correcting and the pad that does not,
and no amount of tightening it could have separated them. It is the same pad
model in both reports: an Elite Series 2 needed the correction on a Fire TV and
another Elite Series 2 was broken by it here.

What does separate them is the axes. A HID gamepad describes its triggers either
as the Accelerator/Brake usages — which become `ABS_GAS`/`ABS_BRAKE`, names
Android has words for — or as two more generic axes on `ABS_Z`/`ABS_RZ`, which
it does not. A descriptor well-formed enough to name its triggers puts its
buttons at the standard positions too. It is also the firmware line on the pad in
the report: an Xbox Wireless Controller over Bluetooth reports GAS/BRAKE after
its firmware update and Z/Rz before it, and only the older one was ever wrong.

`padButtons` now takes `namedTriggers` and answers NATIVE whenever it is set —
no correction of any kind, on buttons or axes, for a pad Android already reads.
`padMap` computed that fact one line below and only ever spent it on the axes;
it now decides both. `hasKeys` stays for the narrower question it can answer —
WHICH straight-through order, once the axes have established there is one — where
a false positive costs nothing.

Moonlight decides it on the same fact (`ControllerHandler`, `gasRange == null`
beside the `"Xbox Wireless Controller"` name); yesterday's commit cited its
tables and then replaced its discriminator, which is where this came in.

Verified: `:kit:testDebugUnitTest` and `:app:testDebugUnitTest` green (16 cases
in PadButtonsTest, 3 new: the gate holds for every vendor/declaration
combination, the four reported buttons stay themselves, and the report-order
choice past the gate is unchanged), `:app:compileDebugKotlin` clean. The
DualSense report filed alongside these — Triangle dead in the client UI and in
the stream — is NOT explained by this and is not fixed here: a button that
reaches neither is one `buttonBit` maps to nothing, which no branch of the
correction produces for Triangle. The Controllers screen prints the raw scancode
and keycode of every press; that line off the reporter's pad will pin it.

.gitea/workflows/arch.yml

@@ -248,7 +248,9 @@ jobs:
         if: steps.webconsole.outputs.cache-hit != 'true'
         run: |
           cd web
-          bun install --frozen-lockfile --ignore-scripts
+          # Retried: bun's download-and-extract is single-shot, and a truncated tarball reads as
+          # `Fail extracting tarball` (ci.yml's web job has the measurement).
+          bash ../scripts/ci/retry.sh 3 bun install --frozen-lockfile --ignore-scripts
           bun run build
 
       - name: The console must exist (cache hit or fresh build)

.gitea/workflows/ci.yml

@@ -339,8 +339,19 @@ jobs:
         working-directory: /
         run: apt-get update && apt-get install -y --no-install-recommends ca-certificates git nodejs
       - uses: actions/checkout@v4
+      # RETRIED, like every other single-shot network call in CI (scripts/ci/retry.sh's header
+      # has the why: this box runs many jobs in parallel and drops packets under that load).
+      # `bun install` streams download-and-extract, so a tarball truncated mid-stream surfaces
+      # as `error: Fail extracting tarball for "<pkg>"` — which reads like a corrupt package and
+      # is not one. Measured 2026-08-20: run 19630's docs-site died that way on
+      # @rolldown/binding-linux-x64-gnu (8.3 MB) while the web job installed the same registry
+      # in the same run, and run 19632 installed the identical lockfile seven minutes later. The
+      # tarball's sha512 matches the lockfile and both bun 1.3.13 and 1.3.14 extract it from
+      # disk, so there was never anything wrong with the package. 3 attempts (10s+20s backoff),
+      # not retry.sh's usual 5: a genuinely stale lockfile fails deterministically here, and
+      # 30s is enough to ride out a load burst without making that wait a minute and a half.
       - name: Install dependencies
-        run: bun install --frozen-lockfile --ignore-scripts
+        run: bash ../scripts/ci/retry.sh 3 bun install --frozen-lockfile --ignore-scripts
       # Build first: it generates the orval API client + paraglide messages that
       # typechecking imports.
       - name: Build
@@ -368,8 +379,9 @@ jobs:
         working-directory: /
         run: apt-get update && apt-get install -y --no-install-recommends ca-certificates git
       - uses: actions/checkout@v4
+      # Retried — see the web job above; this is the job the flake was measured on.
       - name: Install dependencies
-        run: bun install --frozen-lockfile --ignore-scripts
+        run: bash ../scripts/ci/retry.sh 3 bun install --frozen-lockfile --ignore-scripts
       # Build first: fumadocs-mdx emits the .source typegen the typecheck imports.
       - name: Build
         run: bun run build
@@ -417,7 +429,7 @@ jobs:
       # oven/bun ships neither git nor a real node, and the slim base has no CA bundle —
       # actions/checkout needs all three (see the web job).
       - name: Install git + node + CA certs
-        run: apt-get update && apt-get install -y --no-install-recommends ca-certificates git nodejs
+        run: apt-get update && apt-get install -y --no-install-recommends ca-certificates curl git nodejs
       - uses: actions/checkout@v4
       # OpenAPI snapshot in sync, PUNKTFUNK_* vars in docs still exist, undocumented-var
       # ratchet (baseline: scripts/ci/docs-undocumented-env-baseline.txt), host-cli.md commands

.gitea/workflows/deb.yml

@@ -231,7 +231,9 @@ jobs:
           # scripts, and web's `postinstall` is `bun2nix -o bun.nix` — a Nix codegen step this job
           # neither consumes nor commits, whose only effect here is to make the install depend on
           # bun2nix resolving. `build` re-runs its own `prebuild` codegen regardless.
-          bun install --frozen-lockfile --ignore-scripts
+          # Retried: bun's download-and-extract is single-shot, and a truncated tarball reads as
+          # `Fail extracting tarball` (ci.yml's web job has the measurement).
+          bash ../scripts/ci/retry.sh 3 bun install --frozen-lockfile --ignore-scripts
           bun run build
           if ! grep -q 'Bun\.serve' .output/server/index.mjs; then
             echo "ERROR: web build is not a bun bundle — need the 'bun' preset + custom entry"; exit 1

.gitea/workflows/installer-smoke.yml

@@ -61,3 +61,9 @@ jobs:
           punktfunk-host detect-conflicts
       - name: Re-running is a no-op install
         run: sh scripts/install.sh --yes --no-start | grep -q 'already installed'
+      - name: --uninstall takes the packages and the repo off again
+        run: |
+          sh scripts/install.sh --yes --uninstall
+          ! command -v punktfunk-host
+          ! test -e /etc/apt/sources.list.d/punktfunk.list -o -e /etc/yum.repos.d/punktfunk.repo
+          ! grep -q '^\[punktfunk\]' /etc/pacman.conf 2>/dev/null

.gitea/workflows/linux-client-screenshots.yml

@@ -111,3 +111,20 @@ jobs:
           name: punktfunk-linux-client-screenshots
           path: clients/linux/screenshots
           retention-days: 30
+
+      # The artifact above is browser-only (Gitea's API doesn't serve v3 artifacts), which
+      # blocked reusing these shots for the docs. Publish them to the generic package registry
+      # too — fixed version `ci`, delete-then-PUT so each run overwrites, anonymous GET on a
+      # public repo:
+      #   https://git.unom.io/api/packages/unom/generic/punktfunk-linux-client-screenshots/ci/<scene>.png
+      - name: Publish screenshots to the package registry
+        env:
+          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          BASE="https://git.unom.io/api/packages/unom/generic/punktfunk-linux-client-screenshots/ci"
+          for f in clients/linux/screenshots/*.png; do
+            name=$(basename "$f")
+            curl -fsS -o /dev/null --user "enricobuehler:$TOKEN" -X DELETE "$BASE/$name" || true
+            curl -fsS -o /dev/null --user "enricobuehler:$TOKEN" --upload-file "$f" "$BASE/$name"
+            echo "published $BASE/$name"
+          done

.gitea/workflows/plugin-kit-publish.yml

@@ -37,15 +37,18 @@ jobs:
 
       - uses: actions/checkout@v4
 
+      # Both installs retried: bun's download-and-extract is single-shot, and a truncated tarball
+      # reads as `Fail extracting tarball` (ci.yml's web job has the measurement). A publish job
+      # is the worst place to lose to a dropped packet — the tag is already pushed.
       - name: Build the SDK (file:../sdk dependency source)
         working-directory: sdk
         run: |
-          bun install --frozen-lockfile --ignore-scripts
+          bash ../scripts/ci/retry.sh 3 bun install --frozen-lockfile --ignore-scripts
           bun run build
 
       - name: Install dependencies
         working-directory: plugin-kit
-        run: bun install --frozen-lockfile --ignore-scripts
+        run: bash ../scripts/ci/retry.sh 3 bun install --frozen-lockfile --ignore-scripts
 
       # bun 1.3 installs a `file:` dependency by copying its DIRECTORIES but symlinking each
       # top-level FILE to itself — `node_modules/@punktfunk/host/package.json -> package.json`, a

.gitea/workflows/rpm.yml

@@ -176,7 +176,9 @@ jobs:
         if: steps.webconsole.outputs.cache-hit != 'true'
         run: |
           cd web
-          bun install --frozen-lockfile --ignore-scripts
+          # Retried: bun's download-and-extract is single-shot, and a truncated tarball reads as
+          # `Fail extracting tarball` (ci.yml's web job has the measurement).
+          bash ../scripts/ci/retry.sh 3 bun install --frozen-lockfile --ignore-scripts
           bun run build
 
       # Same mandatory assertion as deb.yml — a missing or wrong-preset bundle must fail here, not

.gitea/workflows/sdk-publish.yml

@@ -39,8 +39,11 @@ jobs:
 
       - uses: actions/checkout@v4
 
+      # Retried: bun's download-and-extract is single-shot, and a truncated tarball reads as
+      # `Fail extracting tarball` (ci.yml's web job has the measurement). A publish job is the
+      # worst place to lose to a dropped packet — the tag is already pushed.
       - name: Install dependencies
-        run: bun install --frozen-lockfile --ignore-scripts
+        run: bash ../scripts/ci/retry.sh 3 bun install --frozen-lockfile --ignore-scripts
 
       - name: Typecheck
         run: bun run typecheck

.gitea/workflows/web-screenshots.yml

@@ -40,8 +40,10 @@ jobs:
       - uses: actions/checkout@v4
       # --ignore-scripts skips the prepare→codegen hook (mirrors ci.yml); run codegen
       # explicitly since build-storybook has no prebuild hook of its own.
+      # Retried: bun's download-and-extract is single-shot, and a truncated tarball reads as
+      # `Fail extracting tarball` (ci.yml's web job has the measurement).
       - name: Install dependencies
-        run: bun install --frozen-lockfile --ignore-scripts
+        run: bash ../scripts/ci/retry.sh 3 bun install --frozen-lockfile --ignore-scripts
       - name: Generate API client + i18n messages
         run: bun run codegen
       # Pulls the matching Chromium build + the apt libs it needs (root in-container).

CHANGELOG.md

@@ -14,16 +14,19 @@ with the version table of the release you are moving to, then read **Breaking ch
 
 ## v0.31.0
 
-90 commits since v0.30.0 (65 non-merge).
+170 commits since v0.30.0 (113 non-merge), counted at the tip this was cut from.
 
-Nothing versioned moves. `WIRE_VERSION` stays **2**, the C ABI stays **24** — `include/punktfunk_core.h`
-is byte-identical to the v0.30.0 tag — the driver protocol, gamepad channel and plugin index schema
-are all unchanged, and no `trust::Settings` field, capability bit or control-message type byte was
-added. Every 0.30.x host, client, driver and plugin keeps interoperating in both directions, with no
-re-pairing.
+One versioned surface moves, additively: the **C ABI goes 24 → 25**, a single new symbol
+(`punktfunk_set_log_callback`) that lets an embedder hear the core's own log lines. Nothing else
+does — `WIRE_VERSION` stays **2**, the driver protocol, gamepad channel and plugin index schema are
+unchanged, and no `trust::Settings` field, capability bit or control-message type byte was added.
+No existing C function changed its signature or behaviour and no `#[repr(C)]` struct grew a field,
+so an embedder that adopts nothing rebuilds against the new header and is done. Every 0.30.x host,
+client, driver and plugin keeps interoperating in both directions, with no re-pairing.
 
-What did move is beneath the versioned surfaces, and three parts of it are worth a packager's or
-embedder's attention: the Linux host package installs **three new system files** (a udev rule, a
+Beneath the versioned surfaces, four things are worth a packager's or embedder's attention: the
+**Windows client's default download changes** to a per-user installer plus a portable zip, with the
+MSIX kept for the Store; the Linux host package installs **three new system files** (a udev rule, a
 WirePlumber policy and an ALSA UCM drop-in) that the DualSense audio path depends on; the Linux
 desktop-audio capture **flipped topology by default** (`PUNKTFUNK_STREAM_SINK` unset now means a
 host-owned `null-audio-sink`, with `=stream` a one-release escape hatch to the 0.30 shape); and the
@@ -35,7 +38,7 @@ three ABIs, which removes the Compose screenshot scenes.
 | | v0.30.0 | v0.31.0 | Notes |
 |---|---|---|---|
 | Wire protocol | 2 | **2** | unchanged |
-| C ABI | 24 | **24** | unchanged — `include/punktfunk_core.h` is byte-identical to the v0.30.0 tag; the only new `pub` items in `punktfunk-core` are three RT-safe DSP helpers (`crossfade_insert`, `pcm::raised_cosine_tail`, `pcm::raised_cosine_head`), Rust-only, no `pub const` for cbindgen to pick up |
+| C ABI | 24 | **25** | one additive step: v25 adds `punktfunk_set_log_callback` and the `PunktfunkLogCb` typedef (below). No existing declaration moved and no struct grew a field. Also new in `punktfunk-core`, Rust-only: three RT-safe DSP helpers (`crossfade_insert`, `pcm::raised_cosine_tail`, `pcm::raised_cosine_head`) |
 | Rust edition | 2024 | **2024** | unchanged |
 | MSRV (`rust-version`) | 1.85 | **1.85** | unchanged |
 | Workspace crate dirs | 27 | **27** | unchanged (39 `[workspace] members`, also unchanged) |
@@ -43,20 +46,39 @@ three ABIs, which removes the Compose screenshot scenes.
 | Windows virtual-gamepad channel | 3 | **3** | unchanged |
 | Plugin index schema | 1 | **1** | unchanged |
 | Host event schema | 1 | **1** | unchanged (`punktfunk-host/src/events.rs`) |
-| `api/openapi.json` | 0.29.0 | **0.29.0** | unchanged — no management-API surface moved this cycle; both copies (`api/` and `docs-site/public/`) are byte-identical to each other and to the tag |
+| `api/openapi.json` | 0.29.0 | **0.31.0** | **the stamp only** — no management-API surface moved this cycle. The file had been left at 0.29.0 while the crate was already 0.31.0; #337's regenerate-and-diff caught it and it was regenerated, which is a one-line change to both copies. `api/` and `docs-site/public/` are byte-identical to each other |
 | gamescope patch level (`+pfhdrN`) | 8 | **8** | unchanged; no new patch files. ⚠ `packaging/gamescope/PKGBUILD` still says `pfhdr7` — pre-existing at v0.30.0, not a regression this cycle, but the Arch package builds a binary the host's `>= 8` probe rejects for the keymap path |
-| `@punktfunk/host` (SDK) | 0.1.4 | **0.1.4** | unchanged in `package.json` — but `sdk/src/config.ts` and `runner-cli.ts` changed (the `mgmt-endpoint` fix below), so a `sdk-v0.1.5` cut is **owed**; plugins resolve the SDK from the registry and cannot pick the fix up until it ships |
+| `@punktfunk/host` (SDK) | 0.1.4 | **0.1.5** | cut — `sdk/src/config.ts` and `runner-cli.ts` carry the `mgmt-endpoint` fix below, and plugins resolve the SDK from the registry, so it could not reach them until it shipped |
 | `@punktfunk/plugin-kit` | 0.4.2 | **0.4.3** | cut, for the two `sync-engine.ts` changes that cannot reach a plugin any other way: `minInterval` (below) and the always-apply sync reasons (`startup`/`manual` publish even when the fingerprint matches, so a host-side art drop is recoverable by restarting rather than by deleting the plugin's cache). Note the registry skips 0.4.2: `plugin-kit-v0.4.2` was tagged but its publish never landed, and the tag is left where it is rather than moved |
 
 ⚠ The SDK and plugin-kit version independently of the app (`sdk-v*` / `plugin-kit-v*` tags,
-`sdk-publish.yml` / `plugin-kit-publish.yml`); this release commit does not bump them. Both have
-unpublished code changes, called out in the table so they are cut deliberately rather than
-discovered.
+`sdk-publish.yml` / `plugin-kit-publish.yml`), so their rows record what the registry holds, not
+what this tag ships. Both were cut during this cycle rather than left owed — a plugin resolves them
+from the registry, so a fix that never ships there never reaches one.
 
 ### ⚠ Breaking changes
 
-**None on any versioned surface.** No wire change, no C ABI change, no driver-protocol change, no
-plugin-contract change. Four things are worth attention anyway; none breaks a build:
+**None that break a build.** No wire change, no driver-protocol change, no plugin-contract change.
+The C ABI moves 24 → 25 by **addition only**:
+
+- **v25 — `punktfunk_set_log_callback(max_level, cb, user)`.** The core logs through `tracing`; an
+  embedder that installs no Rust subscriber hears none of it — transport warnings, connection events,
+  handshake notes — and a client log bundle carries the shell's half alone, which is exactly what an
+  Apple TV field report turned out to be. The call registers a `log::Log` backend behind a C callback
+  (`PunktfunkLogCb`: level, target, message, user), gated by `log::set_max_level` so anything above
+  the ceiling costs no formatting; `NULL` detaches, and it answers `Unsupported` when another log
+  backend already owns the process (`android_logger`). Both strings are borrowed for the call only,
+  and an interior NUL drops the line rather than truncating it. `punktfunk-core` now declares
+  `tracing`'s `log` feature explicitly — it had been on transitively via quinn, which an ABI promise
+  must not rest on. An embedder that never calls it is byte-compatible with v24; see
+  `docs/embedding-the-c-abi.md` §2.6.
+- **One header comment was wrong and is corrected, with no signature change:**
+  `punktfunk_connect_ex10`'s summary still stated the pre-2026-08-16 rule that only a format other
+  than 48000/16 requests the lossless plane. Any non-zero format at all does, 48000/16 included —
+  which is what its own warning already said and what the code always did. Embedders reading the
+  summary were reading the old rule.
+
+Five more things are worth attention; none breaks a build:
 
 - **`refactor(android)!` — the Compose console is deleted.** `pf-console-ui` (the Skia shell the
   desktop session binary draws) is now Android's console on arm64-v8a, x86_64 **and** armeabi-v7a;
@@ -78,6 +100,11 @@ plugin-contract change. Four things are worth attention anyway; none breaks a bu
   monitors disabled for the session now (closes #284).
 - **Three new system files in the Linux host package** — the DualSense audio path does not work
   without them. Downstream repackagers: see the packaging section.
+- **The Windows client's default download is a per-user installer, not the MSIX.** The MSIX stays,
+  for the Store; the installer and a portable zip are what the download page now offers, and the
+  release carries `punktfunk-client-setup_<arch>.exe` and `..._<arch>-portable.zip` alongside it.
+  Anyone scripting against the MSIX asset name is unaffected; anyone scripting against "the Windows
+  client download" gets a different artifact. See the Windows client section.
 
 ### DualSense audio and haptics on Linux: five faults, and the files they needed
 
@@ -295,6 +322,25 @@ gains two direct deps already in the graph.
   `frameRatePowerSavingsBalanced`) raises the render-range floor — so the ineffective pins were
   removed again and `pf.present` gained the cadence loop's late-permille / jitter / cushion /
   re-anchors / qDepth.
+- **Colour tagging, which the SurfaceView path never had to do.** MediaCodec tags its own window
+  buffers; with `AImageReader` → `ASurfaceControl` the transaction is the only carrier, and a
+  dataspace of 0 means `setBufferDataSpace` is never called. Two consequences, both fixed inside the
+  cycle: **HDR** was seeded from a hardcoded `BT2020_ITU_PQ` guess and then overwritten by whatever
+  the codec echoed on the first output-format change — a decoder that omits color-transfer (common)
+  echoes None, clobbering the dataspace to 0 before the first present, so P010 buffers composited as
+  sRGB, and an HLG stream was mis-seeded PQ. The initial dataspace now derives from `client.color`
+  (PQ vs HLG, range) and a format change only *refines* it when the codec actually reports an HDR
+  transfer, never resets it — the SurfaceView path's semantics. And **SDR** was untagged entirely:
+  a limited-range BT.709 buffer read as full range shows black (16) as grey, so SDR now maps to
+  `ADATASPACE_BT709` and every ASC buffer is tagged.
+- **One owner for the system bars.** Console → stream rides an `AnimatedContent` cross-fade, so the
+  outgoing console shell stays composed until the fade ends and its
+  `onDispose { show(systemBars()) }` fired *after* `StreamScreen`'s hide — parking the status and
+  gesture bars over the video for the whole session. Hide/show now lives once in `App.kt`, keyed on
+  the resolved intent (streaming or console fronting = immersive, touch shell = bars back), and both
+  screens' per-screen bar management is deleted.
+- **Idle gates** (from the console-ui sweep): the reachability sweep only probes while the console is
+  attached, and the render thread drops to half rate after 60 s without input.
 
 ### Hyprland / sway: `topology: exclusive` (closes #284)
 
@@ -314,20 +360,92 @@ with non-legacy parsers"). `primary` stays extend and warns distinctly. ⚠ **Th
 exercised on a live sway** — no box in the fleet runs one; both argv shapes are pinned by tests and
 the read-back turns a wrong guess into a warning naming the outputs. Six new unit tests.
 
-### Gaming Mode takeover: the mask was the relogin storm
+### Gaming Mode takeover: it no longer touches the display manager at all
 
-On an SDDM-autologin box the runtime mask the takeover laid sat in SDDM's relogin path, so every
-autologin failed in milliseconds and `Relogin=true` has no backoff: 962 logind sessions in 3.7 min,
-system buttons re-scanned 5,688×, udev `change` at ~20/s, iio-sensor-proxy crash-looping ~16
-starts/s, load 26 on 12 cores — and Wine's bus driver, re-enumerating udev per event, read the pad at
-~1.4 Hz. `dm_plan` loses its `mask` input and `dm_survives_masked_unit`; the mask is laid **only after
-the stop has landed** and every restore path unmasks before restarting; a planned DM stop that does
-not land now **fails the takeover** and the caller degrades to ATTACH. `skip` is `!any_live` on every
-flavor; `any_live` now counts `deactivating` and `reloading`. New `DmHelperError::shape()`;
-`watch_for_relogin_storm()` (two `read_dir`s of `/run/systemd/sessions` 5 s apart, ERROR above 1/s,
-detect-only); `systemctl_system` captures stderr at DEBUG (the "requires interactive authentication"
-line was going to the journal on the *successful* path). `cargo test -p pf-vdisplay --lib gamescope`
-52 passed, 1 ignored.
+This landed in two steps within the cycle, and the second retired the first — read the end state.
+
+**The storm.** On an SDDM-autologin box the runtime mask the takeover laid sat in SDDM's relogin
+path, so every autologin failed in milliseconds and `Relogin=true` has no backoff: 962 logind
+sessions in 3.7 min, system buttons re-scanned 5,688×, udev `change` at ~20/s, iio-sensor-proxy
+crash-looping ~16 starts/s, load 26 on 12 cores — and Wine's bus driver, re-enumerating udev per
+event, read the pad at ~1.4 Hz. Masking without stopping the display manager is not a weaker
+defence; it is the storm's engine.
+
+**Then stopping the DM proved wrong too.** With no display manager there is nothing on the box able
+to start a desktop session, so Steam's own "Switch to Desktop" sat on its modal until a reboot
+(field report 2026-08-18, `.41`). It could not even be detected and worked around: on a
+steamos-manager box every trace of that switch is written by the component we had just stopped —
+the `~/.config/steamos-session-select` sentinel is never written (that is the ChimeraOS/Nobara
+layout), `/var/lib/sddm/state.conf` only advances when sddm actually *starts* a session,
+`get-default-login-mode` stays `game` for a non-persistent switch, and `graphical-session.target`
+going inactive fires at takeover time as well.
+
+**End state: idle the autologin, leave the display manager alone.** The takeover drops a unit
+override over the `gamescope-session-plus@` template replacing `ExecStart` with a process that
+sleeps. The autologin still *succeeds*, so there is no failed unit to relogin against; the session
+runs nothing, so Steam is free; and the DM is alive, so the box can service its own session switch.
+No privilege, no DM-flavour matrix, no detection. Measured on `.41` in both directions: takeover
+leaves `steam` down, `sddm` active, the unit `active (running)` with `NRestarts=0`; the switch that
+used to hang brings Plasma up in ~10 s; the restore puts Steam back within 5 s. The drop-in lives
+under `$XDG_RUNTIME_DIR` (a copy outliving the host would be a box whose Game Mode silently does
+nothing), is swept unconditionally at startup, and its removal sits above every early return in the
+restore — the desktop-active return is exactly the path that would leak it. The restore *restarts*
+rather than starts, because `start` on an active-but-idle unit is a no-op that would log success
+over it.
+
+With nothing stopping a display manager any more, the whole chain built to survive doing so is
+deleted: `try_stop_display_manager`, `ensure_host_survives_dm_stop`, `host_is_under_user_manager`,
+`cgroup_under_user_manager`, `linger_enabled` and `dm_plan`'s mask input — 142 lines out, 17 in.
+**Two shipped facts became false and are corrected:** the takeover no longer has to stop the display
+manager, and it no longer needs the `punktfunk` group (the docs and the shipped Bazzite `host.env`
+both said it did). That group still gates the usbip nodes the virtual Steam Deck pad attaches
+through, which is what the advice now narrows to. Kept from the first step: `any_live` counts
+`deactivating` and `reloading` (a unit mid-teardown used to read as a dead leftover, so a box that
+*is* in gaming mode sampled as idle); `DmHelperError::shape()`; `watch_for_relogin_storm()` (two
+`read_dir`s of `/run/systemd/sessions` 5 s apart, ERROR above 1/s, detect-only, and it states that
+no audio, input or PipeWire measurement taken during a storm is valid); and `systemctl_system`
+capturing stderr at DEBUG, since that verb is *expected* to fail on an unprivileged host and its
+"requires interactive authentication" line was going to the journal on the successful path.
+
+### KWin 6.6 creates our virtual output disabled, and refuses to stream it
+
+On KWin ≥ 6.6 `streamVirtualOutput` creates the output on the backend and then hands
+`workspace()->findOutput(output)` to the stream — null for an output the workspace does not manage
+(`wantsToManage` = `isEnabled() && !isNonDesktop()`). An output KWin creates **disabled** is
+therefore refused with "Could not find output", translated into the session's language and logged
+nowhere, because disabling an output is a perfectly valid configuration that applies successfully.
+6.4/6.5 passed the backend output straight through and streamed it either way. It repeats forever:
+the host asks for a *stable* per-client output name precisely so KWin persists that client's scale
+and mode against it, so a stored configuration naming it `enabled: false` is reapplied to every
+future session for that client — and the user cannot fix it in System Settings, because the output
+only exists for the few milliseconds the request is alive. The host now enables the output and
+retries. Related, from the same investigation: a **translated** KWin refusal used to burn all 8
+retries because the match was against KWin's message rather than our own prefix.
+
+### Windows client: a per-user installer and a portable zip, because Steam must spawn the exe
+
+A user report — launching through Big Picture does not work and the Steam overlay never appears —
+turned out to be nothing to do with the app being UWP (it is full-trust Win32 under MSIX too) and
+everything to do with the MSIX install **shape**: the exe lives under the ACL'd `WindowsApps`
+directory that Steam's non-Steam-game picker cannot browse, and alias / `shell:AppsFolder`
+activation defeats the overlay's injection. Steam has to spawn the exe itself, from a normal path.
+
+- **`punktfunk-client.iss`** — a per-user Inno Setup install (no UAC) to
+  `%LOCALAPPDATA%\Programs\Punktfunk`, re-creating in `HKCU` what the MSIX manifest granted: the
+  `punktfunk://` scheme, the Start entries, and `{app}` on the user PATH for the `punktfunk` CLI. It
+  fetches the Windows App Runtime when missing.
+- **`pack-client-installer.ps1`** consumes `pack-msix.ps1`'s layout (one assembly, three artifacts),
+  signs the four exes individually and emits `setup.exe` plus a portable zip — same signing backends
+  and fail-closed-on-tags rule as its siblings, and no `.cer`, because an exe runs untrusted.
+- **`windows-client.yml`** packs after the MSIX and publishes/attaches the new artifacts;
+  canary/latest aliases are `punktfunk-client-setup_<arch>.exe` and `..._<arch>-portable.zip`.
+- **`deeplink.rs`**: `write_shortcut` targets the app-execution alias only under package identity —
+  an unpackaged install has no alias but does have a stable path, so it targets `current_exe()`.
+  `has_package_identity()` is now shared with `main.rs`'s AppUserModelID probe.
+- Uninstall is `Settings → Apps → Installed apps` (per-user, no admin prompt) or
+  `unins000.exe /VERYSILENT`; a portable unzip registers nothing and is deleted by hand. Documented
+  in install-client (with a "Launching through Steam" section), channels, clients, uninstall, and
+  both copies of `platforms.json`.
 
 ### Windows host: two session-killers
 
@@ -351,6 +469,123 @@ line was going to the journal on the *successful* path). `cargo test -p pf-vdisp
   instead of `launching` forever. Fixture in `a_pid_only_launch_reports_its_exit` widened 4 → 8 s
   (it passed only because of the bug); new ignored test drives the field report.
 
+### `scripts/install.sh`: a guided Linux host install (preview)
+
+Plain POSIX `sh`, dash-clean, `curl -fsSL https://punktfunk.unom.io/install.sh | sh`. Detect the
+distro from os-release (apt / dnf / pacman / rpm-ostree→sysext; NixOS, SteamOS, Windows and unknown
+distros get a one-line pointer and stop; Debian 12 / Ubuntu 24.04 / Mint 22 / Fedora 45 hit the
+documented floors with the right docs link) → install using the `data/platforms.json` lines
+**verbatim** (channel and the Fedora group are edited into the string at run time) → run
+`punktfunk-host detect-conflicts` (exit 1 = an active Sunshine-family host) → offer to keep both by
+moving the management API port (`PUNKTFUNK_MGMT_BIND`, default 47991, which the firewall step then
+opens) → input group (`ujust` on Bazzite) → optional `punktfunk` group, GameStream compat and shared
+clipboard, all defaulting to no → firewalld/ufw profiles → enable host + console (+ the plugin
+runner where it is not) → optional linger → verify (unit active, UDP 9777 bound) and print the
+console URL, the password command and the pairing steps.
+
+`--dry-run` prints every command and changes nothing; `--uninstall` reverses the install and the
+service enable per family (user units off first, then only the punktfunk packages actually
+installed, then the repo — config, groups and firewall stay, as `/docs/uninstall` states). Every
+prompt has a `PUNKTFUNK_INSTALL_*` environment twin so `--yes` (or no terminal) runs unattended, and
+stdin is never read, because under `curl | sh` stdin *is* the script. Re-running is safe. The
+end-of-run check catches the two NVIDIA silent failures on every family — no driver at all, and a
+module the kernel refused to load under Secure Boot — via an `nvidia-smi` probe pointing at the
+troubleshooting anchor.
+
+It is labelled **PREVIEW** on purpose: the per-distro docs pages remain the documented default until
+it has mileage. CI runs it: a new `installer-smoke.yml` exercises install and `--uninstall` per
+package family, and `check-docs-drift.sh` gate 7 runs the 16-file os-release detection matrix
+through the real script under `--dry-run` on every push. One bug fixed by the first smoke run: the
+`/dev/tty` probe used `-r`/`-w`, which answer yes in a container that has the node but no
+controlling terminal, so the redirect failed — it opens the device instead now.
+
+### One home per fact: `data/platforms.json`, and CI gates against drift
+
+Install commands, repo URLs and port numbers had drifted across four surfaces. They now live in
+`data/platforms.json` and nowhere else: the docs-site install pages quote it through an
+`<Install platform="…"/>` MDX component reading a byte-identical snapshot at
+`docs-site/src/data/platforms.json` (the Docker build context is `docs-site/` alone, the same
+arrangement `openapi.json` uses), `<Ports/>` renders the port table from it, the website download
+page vendors it, and `install.sh` runs it. `scripts/ci/check-docs-drift.sh` gates the parse, the
+snapshot sync, undocumented `PUNKTFUNK_*` knobs (against a checked-in baseline) and the detection
+matrix; `check-docs-links.sh` covers dead links.
+
+⚠ **Two consequences for whoever cuts this release.** The website vendors `platforms.json` and only
+refreshes when someone runs `bun run sync-platforms` in punktfunk-website and commits — the release
+flow in `docs/releases/README.md` gained that step, and `platforms.json` **did** change this cycle
+(the Windows client download). And the `.gitea/PULL_REQUEST_TEMPLATE.md` now asks the one question
+CI cannot: did a user-facing fact change, and is the page that owns it updated in the same PR.
+
+### Clients can send their logs to the host, on every platform that has a console
+
+0.30 shipped "Send logs to host" on the Gaming Mode console alone and named the Apple and Android
+legs as follow-ups. Both landed here.
+
+- **Apple** — a `ClientLog` drop-in for `Logger(subsystem: "io.unom.punktfunk", category:)` with the
+  same call shape, writing os_log *and* a process-global ring bounded at 4096 lines / 768 KiB (under
+  the host's 1 MiB cap), stamped wall-clock ISO-8601 so a bundle lines up with the host log;
+  `.debug` stays out of the ring, which is the Steam Deck DPB lesson applied in advance. 13 `Logger`
+  declarations swapped. `MgmtTransport`/`MgmtConnection` POST a length-framed body on the same
+  pooled, pinned mTLS connection; `SendLogs.toHost` requires identity and pinned fingerprint, the
+  same gates as the library. Reachable from the host card's context menu and the gamepad host
+  options. Paired with ABI v25 above, the Swift client finally hears the core's own lines too
+  (`core.<crate>`, info ceiling by default, `PUNKTFUNK_CORE_LOG_LEVEL` raises it).
+- **Android** — `pf-client-core`'s logring RING half (note/render/wallclock, std-only) is
+  Android-enabled, with `send_to_host` still desktop-gated alongside the ureq fetches; `wallclock`
+  moves in from the session's ring layer so every feeder stamps lines identically. `JNI_OnLoad`
+  installs a `RingTee`, so every `log` record goes to logcat **and** into the ring in the desktop
+  ring layer's line shape; `nativeRenderLogs(header)` hands Kotlin the rendered bundle, and the
+  upload rides the client's own mTLS.
+
+### A provider plugin can report which of its titles are **running**
+
+New: `PUT /api/v1/library/provider/{provider}/running`, body
+`{"running":[{"external_id":"…","pid":1234}]}` — the **live** counterpart to the static `detect`
+hints a reconcile carries. `detect` says *how to recognize* a title's process; this says *it is
+running now*, and carries the pid where the provider knows one. Additive: no existing route,
+payload or behaviour changes, and a host with no reporting plugin behaves exactly as before.
+
+It exists because one class of title could never be tracked at all. The host derives liveness by
+scanning (`procscan` + `DetectSpec`), which needs something recognizable on disk — an install
+directory, an executable, a Steam reaper. A Playnite-launched emulated game, a manually added one,
+or a library plugin that records no install directory has none of that, and its launch is a
+`playnite://` hand-off, so the host holds no process either: the lease went `Untracked`, its exit
+was never noticed, `session_on_game_exit` could not fire, and `POST /game/end` had nothing to aim
+at. Playnite knew the whole time — it starts the game, tracks it in the mode the person configured,
+and fires an event on both edges carrying the pid. That was being thrown away.
+
+- **Declarative and idempotent**, like the reconcile beside it: the body is the provider's
+  **complete** running set, so a missed event, a plugin restart or an install mid-game self-correct
+  on the next report instead of drifting. Absent from the set = stopped.
+- **Reports expire** (`crate::runstate::REPORT_TTL`, 90 s; the answer carries `ttl_s`). This is what
+  makes it safe for a live provider to hold a streaming session open for a game the host cannot
+  see: a plugin that dies with a game running stops counting shortly after and the host falls back
+  to scanning. Reporters must restate well inside the window.
+- **New `gamelease::LeaseKind::Reported`** — a lease with no process signal of its own, tracked by
+  what its provider says. `open` reaches it when the spec is empty and a provider speaks for the id;
+  the shim-reclassification paths (every Windows launch is a hand-off by construction) fall back to
+  it too, where they previously fell to `Untracked`. Phase 1 accepts "running" as the game
+  appearing; phase 2 treats "stopped" as the exit, and — unlike `procscan::running_hint`, which may
+  only ever *delay* an exit because Steam's registry flag survives an unclean exit — a fresh
+  provider report is decisive in both directions. A reported pid joins the termination ladders on
+  the same terms as a spawned one (re-resolved and start-time-pinned at the moment of use).
+- **Route authority**: the plugin lane, like the reconcile (`mgmt::auth::plugin_may_access`, and its
+  exhaustive classification table). No new authority — the host maps `external_id` through the
+  catalog, so a provider can only ever speak about entries it published; an unknown id is *counted*,
+  not refused, because a report legitimately races its own reconcile and 400-ing the batch would
+  throw away the liveness of every other running title.
+- **`@punktfunk/plugin-kit`: `ProviderClient.reportRunning(providerId, running)`**, returning
+  `{matched, unknown, ttlS}`; a 404 from an older host means "this host tracks games by scanning".
+  Version bumped to **0.4.4** — **unpublished, `plugin-kit-v0.4.4` owed.**
+
+The Playnite half lives in `punktfunk-plugin-playnite` (**0.4.5**, exporter **0.4.0**): the C#
+exporter hooks Playnite's `OnGameStarted`/`OnGameStopped`/`OnGameStartupCancelled` and writes a
+small `punktfunk-running.json` beside the library export, re-stamped every 30 s and *deleted* when
+Playnite closes; the plugin polls it and restates the set to this route. It calls the route through
+the kit's untyped host seam rather than `reportRunning`, deliberately — depending on the method
+would make that repo unbuildable until the kit publishes, for the same request. Needs a host
+carrying this route; an older one 404s and the plugin carries on without it.
+
 ### Everything else an integrator might notice
 
 - **`mgmt-endpoint` is followed everywhere.** `PUNKTFUNK_MGMT_BIND` moved off 47990 left every plugin,
@@ -402,44 +637,130 @@ line was going to the journal on the *successful* path). `cargo test -p pf-vdisp
   (screenshot harness only).
 - **New environment variables:** `PUNKTFUNK_PAD_SINK_VOLUME` (`=0` skips both pad-sink pins),
   `PUNKTFUNK_DUALSENSE_USBIP_GRACE_MS` (pad-arrival grace), `PUNKTFUNK_USBIP_TRACE` (byte-level
-  USB/IP trace prefix, off by default), and the three Apple screenshot-harness hooks above.
+  USB/IP trace prefix, off by default), `PUNKTFUNK_CORE_LOG_LEVEL` (Apple: raises the ABI v25 log
+  sink's ceiling above its info default), the three Apple screenshot-harness hooks above, and nine
+  `PUNKTFUNK_INSTALL_*` twins for `install.sh`'s prompts (`_YES`, `_CHANNEL`, `_GAMESTREAM`,
+  `_CLIPBOARD`, `_PUNKTFUNK_GROUP`, `_LINGER`, `_MGMT_PORT`, `_DRY_RUN`, `_OS_RELEASE`).
   `PUNKTFUNK_STREAM_SINK` gained the `stream` value and is documented for the first time.
+- **A Steam Deck never learned a host's wake MAC, so Wake-on-LAN was skipped there in silence.**
+  Every wake gate reads `!host.mac.is_empty()`, and the MAC only ever reached the store through
+  `trust::learn_mac`, whose two callers were the GTK and WinUI hosts pages — neither of which runs
+  in Gaming Mode. Rather than add the missing call twice, the three per-field learners (`learn_mac`,
+  `learn_os`, `learn_mgmt_port`) collapse into one `learn_from_advert`, called wherever an advert
+  meets a saved record: both desktop hosts pages, the console home, and the CLI's `discover`.
+  Remembering one call is not something a front-end can half-do; remembering three is what produced
+  this (#322).
+- **`HostRow` gains `clipboard_sync`** (`#[serde(default)]`) and `ConsoleCmd` two variants,
+  `BindProfile` and `SetClipboard` — additive and default-tolerant. From the 2026-08-19 console-ui
+  sweep, which also brought touch deferred-tap and drag-to-scroll to the console (a swipe across the
+  settings list used to cycle whatever value it landed on, because `MenuList` presses focus *and*
+  activate), Controller haptics/speaker rows, and two Android idle gates (the reachability sweep
+  only probes while the console is attached, and the render thread halves its rate after 60 s
+  without input).
+- **Cancelling a connect returns the console immediately.** The takeover could only be dismissed by
+  a session phase coming back from the embedder and nothing guaranteed one would: Android's shell
+  sent no phase at all on the cancelled path, and the desktop shell waited on a pump parked inside
+  the blocking `NativeClient::connect*`, which had no abort — 15 s on a normal dial, **185 s** on a
+  request-access connect the host holds pending approval. The private `connect_*` inner fn takes a
+  trailing `cancel: Option<Arc<AtomicBool>>`; not exported through the C ABI.
+- **A portable Playnite's covers survive the art confinement.** A Playnite unzipped outside the
+  users base keeps its library beside the exe, so every cover it exports sits outside every default
+  art root: the games synced and all **70** covers were dropped, with `PUNKTFUNK_LIBRARY_ART_ROOTS`
+  the only way out. The Playnite install dirs are art roots now, exactly as Steam's install root
+  already was, and `playnite_install_dirs` learned to find a portable copy at all — it registers no
+  uninstall entry and sits under no profile, but it does register the `playnite://` handler, which
+  is the very registration the launch path already follows. So a portable install also gets its
+  Fullscreen launcher tile, which it never had. The confinement is not loosened: roots come from the
+  host's own registry and filesystem probes, never from the plugin lane that supplies the art path.
+  Paired with the plugin-kit fix below, a fixed host no longer needs a cache file deleted.
+- **`plugin-kit`: `startup` and `manual` sync reasons always publish.** The fingerprint says the
+  plugin would compute the same entries again; it does *not* say the host still holds them — and the
+  host may accept a payload and store less of it (an art path outside its roots is stripped and the
+  games kept, deliberately, because a cover must not cost a library). Once that happened the
+  fingerprint was a permanent "no changes", and the only way out was deleting the plugin's cache
+  file, which is exactly the advice a portable-Playnite library with 70 dropped covers was given.
+  The two triggers with a person behind them now always apply.
+- **Nix:** nixpkgs bumped because its gamescope 3.16.24 no longer took our patch 0009 (the publish
+  tier was red on every build); `enableWsi` is a nixpkgs *function argument* defaulting to false, so
+  the plain derivation shipped a compositor with **no WSI layer at all** and nothing under it could
+  obtain an HDR10 swapchain — our own postInstall assertion caught it. Also: the prune makes `$out`
+  writable first (reshade installs read-only), the bun builds are serialised and the OOM is measured
+  against the real 7 GiB cgroup cap rather than guessed at, and a dispatch opt-in compared against
+  the string `"true"` silently skipped when the API delivered a real JSON boolean — the step was
+  skipped and the job still reported success.
 - **New packaging payload (Linux host, rpm/deb/arch; nix where noted):** `scripts/60-punktfunk.rules`
   (+2 sound rules), `scripts/60-punktfunk-dualsense.conf` (WirePlumber, also nix),
   `scripts/alsa-ucm2/…` (UCM drop-in, **not** nix). Bazzite sysext inherits all three from the RPMs.
 - **Docs:** `AGENTS.md` + `docs/agents/` (issue tracker is Gitea via the `gitea` MCP server; the
   five triage labels; single-context domain docs). A host audio-source comment corrected
   (`pw_impl_node_set_driver` marks props changed but leaves the flush to the next info emission).
-- **CI:** Nix publish job records `df` after the build as well as before.
+- **CI:** the Nix publish job records `df` after the build as well as before; the
+  `linux-client-screenshots` run publishes its PNGs to the generic package registry as well as the
+  v3 artifact store (which is browser-only, so nothing could reuse the shots for the docs — that is
+  how the get-started track got its fifth screenshot, a client's host list); and **every Linux
+  `bun install` is now wrapped in `scripts/ci/retry.sh`**. That last one is a real failure, not
+  tidying: `bun install` streams download-and-extract, so a tarball truncated by the runner's
+  packet loss under parallel load surfaces as `error: Fail extracting tarball for "<pkg>"` and
+  names a package that is perfectly intact — measured on run 19630, where docs-site died on
+  `@rolldown/binding-linux-x64-gnu` while the web job installed the same registry in the same run
+  and run 19632 installed the identical lockfile seven minutes later. The tarball's sha512 matches
+  the lockfile and bun 1.3.13 and 1.3.14 both extract it from disk, so neither the package nor the
+  floating `oven/bun:1` bump was ever at fault. `retry.sh`'s header had already diagnosed this
+  class and said to wrap every single-shot network command; `bun install` was the one still
+  unwrapped. Three attempts rather than the usual five, so a genuinely stale lockfile still fails
+  fast under `--frozen-lockfile`.
+- **The web console's Virtual displays page** put the Streamed-screen and session-lifetime cards
+  below the tab shell, so both rendered on both tabs; they are policy surfaces and now sit inside
+  the Configuration tab, leaving the Live tab as the live list plus arrangement.
 
 ### Verification status
 
 Gates run on the release tree (this MacBook, rustc/rustfmt 1.96.0 per `rust-toolchain.toml`):
-`cargo fmt --all --check` clean — **after** a whitespace-only commit on the release branch: two files
-(`pf-console-ui/src/screens/controllers.rs`, `punktfunk-host/src/audio/linux/pad_card_volume.rs`)
-had landed on main formatted differently from rustfmt 1.96.0, so `ci.yml`'s Format step was red on
-the tip this is cut from; `cargo metadata --offline` ok with the `Cargo.lock` diff versions-only
-(36/36 lines); `cargo test -p punktfunk-core` **272 passed** in the unit suite; the android.yml Play
-notes gate run verbatim — 498/500 characters and not byte-identical to any prior release's; both
-openapi copies `cmp` identical and unchanged since the tag; `include/punktfunk_core.h` regenerated
-by the build and `git diff` clean against the tag.
+`cargo fmt --all --check` clean; `cargo metadata --offline` ok with the `Cargo.lock` diff
+versions-only (36/36 lines); `cargo test -p punktfunk-core --lib` **273 passed**; the android.yml
+Play notes gate run verbatim — 456/500 characters and not byte-identical to any prior release's;
+both openapi copies `cmp` identical, both stamped 0.31.0; notes voice scan clean outside the
+For developers section.
 
-⚠ **The C ABI harness (`tests/c_abi.rs`) did not run on this cut**: it links the staticlib with
-`-lopus` and this machine has no libopus (`ld: library 'opus' not found`), which is an environment
-gap, not a code fault. The header it exercises is byte-identical to v0.30.0's, where the harness
-passed (261 + 1 + 8), and nothing in `punktfunk-core`'s C surface changed. The CI runner is its
-first execution for this tag.
+⚠ **This release was cut more than once.** The first cut (`601f040f`, merged as #320) was never
+tagged, and 41 more non-merge commits landed on top of it — the Windows client installer, the
+guided Linux installer, the docs overhaul, ABI v25, the KWin 6.6 repair and the takeover's final
+shape among them; a handful more (the Virtual displays tab fix, the fifth get-started screenshot)
+arrived while the second cut was being written. This section, the version table and the notes are
+all re-measured on the latest tip; where the cuts disagreed, the earlier text was **rewritten
+rather than appended to**, because none of
+the intervening work ever shipped. Specifically: the "C ABI unchanged / header byte-identical"
+claim is gone (it is 25 now), the openapi row moved off 0.29.0, the SDK and plugin-kit rows record
+cuts that have happened rather than cuts that were owed, and the Gaming Mode takeover section
+describes idling the autologin rather than stopping the display manager — a within-cycle correction
+no user could have seen.
 
-⚠ **Verified by reading only** — compiled nowhere available to the cutting host: the Windows runner
-log redirect (`scripting-run.cmd`), the tray's `Option<u16>` port on Windows, and the sway half of
-`topology: exclusive` (no live sway in the fleet, as with #283).
+⚠ **The C ABI harness (`tests/c_abi.rs`) did not run on this cut**, and this time the header *did*
+change: it links the staticlib with `-lopus` and this machine has no libopus (`ld: library 'opus'
+not found`), which is an environment gap, not a code fault. `punktfunk_set_log_callback` is
+therefore compiled by cbindgen and by the Rust unit tests here, but the generated header has not
+been compiled by a C compiler on this cut — the CI runner is its first. Worth naming because ABI 25
+is the one versioned surface that moved.
+
+⚠ **Verified by reading only** — compiled nowhere available to the cutting host: the Windows client
+installer and portable zip (`punktfunk-client.iss`, `pack-client-installer.ps1` — the pack step is a
+Windows runner's), the Windows runner log redirect (`scripting-run.cmd`), the tray's `Option<u16>`
+port on Windows, and the sway half of `topology: exclusive` (no live sway in the fleet, as with
+#283).
 
 ⚠ **Not verified on hardware by this cut**, named rather than left to be discovered: the null-sink
 capture topology's on-glass validation (pw-top showing our sink at the top of its own group, 5 min
 of loud audio at `delivered_pct=100 gaps=0` on a box where a hardware sink also runs) was still owed
-when it landed; the 96 kbps speaker lane was judged on glass by ear only; and the Android
-`ASurfaceControl` path was verified on one device (Nothing Phone 3) — the fallback presenter is
-byte-for-byte the 0.30 one.
+when it landed; the 96 kbps speaker lane was judged on glass by ear only; the Android
+`ASurfaceControl` path was verified on one device (Nothing Phone 3), with the fallback presenter
+byte-for-byte the 0.30 one; the Mac Accessibility intercept (the tap ahead of Spotlight, inside the
+sandbox) needs a granted Accessibility switch the dev machine does not have; and `install.sh` is
+smoke-tested per package family in CI containers but is shipped **preview** precisely because it has
+no real-box mileage, Bazzite above all.
+
+⚠ **Owed outside this repository:** `data/platforms.json` changed this cycle (the Windows client
+download), and the website's download page vendors a copy that only refreshes when someone runs
+`bun run sync-platforms` in punktfunk-website and commits — step 1 of `docs/releases/README.md`.
 
 ---
 

api/openapi.json

@@ -1860,6 +1860,69 @@
         }
       }
     },
+    "/api/v1/library/provider/{provider}/running": {
+      "put": {
+        "tags": [
+          "library"
+        ],
+        "summary": "Report which of a provider's titles are running",
+        "description": "The **live** counterpart to the `detect` hints in a reconcile payload: that one says *how to\nrecognize* a title's process, this one says *it is running now* (design §9,\n[`crate::runstate`]). For a provider that starts games itself and knows when they stop —\nPlaynite tracks every launch and fires an event on both edges — this is a fact the host would\notherwise have to re-derive by scanning, and for a title with nothing to scan for (an emulated\ngame, a manually added one) could not derive at all.\n\nDeclarative and idempotent, like the reconcile: the body is the provider's **complete** running\nset, so a missed event, a plugin restart or an install mid-game all self-correct on the next\nreport rather than drifting.\n\nThe report **expires** after `ttl_s` (90s) unless restated, which is what makes it safe for a\nlive provider to keep a streaming session open for a game the host cannot see: a plugin that\ndies with a game running stops counting shortly after, and the host falls back to process\nscanning exactly as it does without one. Re-report on every change **and** on a timer well\ninside the window.\n\nTitles the provider does not currently publish are ignored (counted in `unknown`), not an error:\na report may legitimately race its own reconcile.",
+        "operationId": "reportProviderRunning",
+        "parameters": [
+          {
+            "name": "provider",
+            "in": "path",
+            "description": "The provider id ([a-z0-9._-], `manual` reserved)",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ProviderRunningInput"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "The report was accepted",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProviderRunningAccepted"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid provider id or payload",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/v1/library/scanners": {
       "get": {
         "tags": [
@@ -7792,6 +7855,46 @@
           }
         }
       },
+      "ProviderRunningAccepted": {
+        "type": "object",
+        "description": "The result of a liveness report.",
+        "required": [
+          "matched",
+          "unknown",
+          "ttl_s"
+        ],
+        "properties": {
+          "matched": {
+            "type": "integer",
+            "description": "How many reported titles matched an entry this provider currently publishes.",
+            "minimum": 0
+          },
+          "ttl_s": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Seconds this report stays authoritative without being restated — re-report inside it while\nanything is running.",
+            "minimum": 0
+          },
+          "unknown": {
+            "type": "integer",
+            "description": "How many were ignored because no such entry exists (a report that raced a reconcile).",
+            "minimum": 0
+          }
+        }
+      },
+      "ProviderRunningInput": {
+        "type": "object",
+        "description": "Request body for `reportProviderRunning`.",
+        "properties": {
+          "running": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RunningTitle"
+            },
+            "description": "Every title of this provider's that is running **right now**. The full set, not a delta:\nanything absent from it is reported as stopped."
+          }
+        }
+      },
       "ReleaseDisplayRequest": {
         "type": "object",
         "description": "Request body for `releaseDisplay`.",
@@ -7846,6 +7949,28 @@
           }
         }
       },
+      "RunningTitle": {
+        "type": "object",
+        "description": "One running title in a provider's liveness report.",
+        "required": [
+          "external_id"
+        ],
+        "properties": {
+          "external_id": {
+            "type": "string",
+            "description": "The provider's own stable id for the title — the same key its reconcile payload uses."
+          },
+          "pid": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int32",
+            "description": "The process id the provider started for it, when it knows one. Optional, and never trusted\nas a bare number: the host re-resolves it and pins it to its start time before it is ever\nsignalled, so a stale or recycled pid simply contributes nothing.",
+            "minimum": 0
+          }
+        }
+      },
       "RuntimeRequest": {
         "type": "object",
         "required": [

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

@@ -96,7 +96,11 @@ internal fun ControllersScreen(
         InputDevice.getDeviceIds()
             .toList()
             .mapNotNull { InputDevice.getDevice(it) }
-            .filter { !it.isVirtual && !Gamepad.isPad(it) }
+            // Everything real that is NOT counted as a controller — including a device that claims
+            // a pad source with no pad hardware behind it, which the Gamepads list above now
+            // rejects. One list or the other, never neither: this screen is where someone looks
+            // when the client's idea of "a pad is attached" disagrees with the room.
+            .filter { !it.isVirtual && !Gamepad.looksLikeController(it) }
     }
     DisposableEffect(Unit) {
         val im = context.getSystemService(InputManager::class.java)
@@ -136,14 +140,19 @@ internal fun ControllersScreen(
             // Read ONCE, up front: the test can end inside this very event, and the release that
             // ended it still has to be swallowed here — see the B branch below.
             val consume = consuming
+            // The CORRECTED keycode, so this screen shows the button the stream will send and not
+            // the one Android guessed for a pad it has no key layout for — the two differ on every
+            // controller [Gamepad.padKeyCode] exists for, and a tester that disagrees with the
+            // stream is worse than no tester. The raw pair is still reported in "Last input".
+            val code = Gamepad.padKeyCode(event)
             when (event.action) {
                 KeyEvent.ACTION_DOWN -> {
-                    held[event.keyCode] = true
-                    if (event.keyCode == KeyEvent.KEYCODE_BUTTON_B) bHeld = true
+                    held[code] = true
+                    if (code == KeyEvent.KEYCODE_BUTTON_B) bHeld = true
                 }
                 KeyEvent.ACTION_UP -> {
-                    held[event.keyCode] = false
-                    if (event.keyCode == KeyEvent.KEYCODE_BUTTON_B) {
+                    held[code] = false
+                    if (code == KeyEvent.KEYCODE_BUTTON_B) {
                         bHeld = false
                         if (consume) {
                             if (event.eventTime - event.downTime >= HOLD_TO_FINISH_MS) {
@@ -167,23 +176,43 @@ internal fun ControllersScreen(
                     }
                 }
             }
-            lastInput = "${event.device?.name}: ${KeyEvent.keyCodeToString(event.keyCode)}"
+            // Raw scancode AND keycode, plus the correction when one fired: this line is what a
+            // field report needs to pin an unmapped pad's report order without the device in hand.
+            val raw = KeyEvent.keyCodeToString(event.keyCode).removePrefix("KEYCODE_")
+            val fixed = KeyEvent.keyCodeToString(code).removePrefix("KEYCODE_")
+            lastInput = "${event.device?.name}: scan 0x%X · %s%s".format(
+                event.scanCode,
+                raw,
+                if (code != event.keyCode) " → $fixed" else "",
+            )
             consume
         }
         val motionProbe: (MotionEvent) -> Boolean = probe@{ event ->
             if (!Gamepad.isPad(event.device)) return@probe false
+            // Through the device's resolved map, exactly as `Gamepad.AxisMapper` reads it while
+            // streaming — on a pad Android has no key layout for, the right stick and the triggers
+            // are not on the axes their names suggest.
+            val map = Gamepad.padMap(event.device)
             axes["LX"] = event.getAxisValue(MotionEvent.AXIS_X)
             axes["LY"] = event.getAxisValue(MotionEvent.AXIS_Y)
-            axes["RX"] = event.getAxisValue(MotionEvent.AXIS_Z)
-            axes["RY"] = event.getAxisValue(MotionEvent.AXIS_RZ)
-            axes["LT"] = maxOf(
-                event.getAxisValue(MotionEvent.AXIS_LTRIGGER),
-                event.getAxisValue(MotionEvent.AXIS_BRAKE),
-            )
-            axes["RT"] = maxOf(
-                event.getAxisValue(MotionEvent.AXIS_RTRIGGER),
-                event.getAxisValue(MotionEvent.AXIS_GAS),
-            )
+            axes["RX"] = event.getAxisValue(map.rightStickX)
+            axes["RY"] = event.getAxisValue(map.rightStickY)
+            axes["LT"] = if (map.leftTrigger == Gamepad.AXIS_NONE) {
+                maxOf(
+                    event.getAxisValue(MotionEvent.AXIS_LTRIGGER),
+                    event.getAxisValue(MotionEvent.AXIS_BRAKE),
+                )
+            } else {
+                map.level(event.getAxisValue(map.leftTrigger))
+            }
+            axes["RT"] = if (map.rightTrigger == Gamepad.AXIS_NONE) {
+                maxOf(
+                    event.getAxisValue(MotionEvent.AXIS_RTRIGGER),
+                    event.getAxisValue(MotionEvent.AXIS_GAS),
+                )
+            } else {
+                map.level(event.getAxisValue(map.rightTrigger))
+            }
             axes["HX"] = event.getAxisValue(MotionEvent.AXIS_HAT_X)
             axes["HY"] = event.getAxisValue(MotionEvent.AXIS_HAT_Y)
             consuming
@@ -689,6 +718,16 @@ private fun PadRow(info: PadInfo, gamepadSetting: Int) {
                 style = MaterialTheme.typography.bodySmall,
                 color = MaterialTheme.colorScheme.onSurfaceVariant,
             )
+            // Only when a correction is actually in force: on a pad Android has a key layout for
+            // there is nothing to say, and a line that says "normal" on every device teaches
+            // nobody anything. Named rather than merely flagged, so a field report can quote it.
+            padButtonsNote(info.buttons)?.let {
+                Text(
+                    it,
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
             if (info.canRumble) {
                 OutlinedButton(onClick = { info.dev?.let(::testRumble) }) { Text("Test rumble") }
             } else {
@@ -784,6 +823,12 @@ internal data class PadInfo(
     val controllerNumber: Int,
     val resolvedPref: Int,
     val canRumble: Boolean,
+    /**
+     * The report order this pad's buttons were resolved to ([Gamepad.padButtons]). Defaults to
+     * the pad Android already knows, which is what a screenshot scene wants and what the note
+     * under the card stays silent about.
+     */
+    val buttons: Gamepad.PadButtons = Gamepad.PadButtons.NATIVE,
     val dev: InputDevice? = null,
 )
 
@@ -793,6 +838,7 @@ internal fun padInfoOf(dev: InputDevice): PadInfo = PadInfo(
     forwarded = isForwarded(dev),
     controllerNumber = dev.controllerNumber,
     resolvedPref = Gamepad.prefFor(dev),
+    buttons = Gamepad.padMap(dev).buttons, // via padMap so the list refresh reuses the cache
     canRumble = deviceHasVibrator(dev),
     dev = dev,
 )
@@ -823,6 +869,20 @@ internal fun testRumble(dev: InputDevice) {
 }
 
 /** Identity line: VID:PID + the source classes Android assigned. */
+/**
+ * What to say about a pad whose buttons had to be resolved from their scancodes because Android
+ * has no key layout for it — null for a pad it does know, which needs no explanation.
+ */
+private fun padButtonsNote(buttons: Gamepad.PadButtons): String? = when (buttons) {
+    Gamepad.PadButtons.NATIVE -> null
+    Gamepad.PadButtons.GENERIC_SONY ->
+        "Android has no button layout for this controller — read as a PlayStation pad"
+    Gamepad.PadButtons.GENERIC_XBOX ->
+        "Android has no button layout for this controller — read as an Xbox pad"
+    Gamepad.PadButtons.SONY_MODERN ->
+        "Android has no button layout for this controller — face buttons corrected"
+}
+
 private fun deviceDetail(dev: InputDevice): String =
     "%04X:%04X · %s".format(dev.vendorId, dev.productId, sourcesLabel(dev.sources))
 

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

@@ -11,6 +11,7 @@ import androidx.compose.runtime.getValue
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.rememberUpdatedState
 import androidx.compose.ui.platform.LocalContext
+import io.unom.punktfunk.kit.Gamepad
 import kotlin.math.abs
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.isActive
@@ -96,7 +97,7 @@ fun GamepadNavEffect(
         val keyProbe: (KeyEvent) -> Boolean = probe@{ ev ->
             val down = ev.action == KeyEvent.ACTION_DOWN
             val edge = down && ev.repeatCount == 0
-            when (ev.keyCode) {
+            when (Gamepad.padKeyCode(ev)) {
                 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.
@@ -202,7 +203,7 @@ fun GamepadNavEffect2D(
         val keyProbe: (KeyEvent) -> Boolean = probe@{ ev ->
             val down = ev.action == KeyEvent.ACTION_DOWN
             val edge = down && ev.repeatCount == 0
-            when (ev.keyCode) {
+            when (Gamepad.padKeyCode(ev)) {
                 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 }

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

@@ -616,7 +616,7 @@ class MainActivity : ComponentActivity() {
             // no BUTTON_SELECT scancode delivers its Select: see [Gamepad.padButtonBit], which is
             // why this asks it rather than `buttonBit`).
             if (event.isFromSource(InputDevice.SOURCE_GAMEPAD)) {
-                val bit = Gamepad.padButtonBit(event.keyCode, event.flags)
+                val bit = Gamepad.padButtonBit(Gamepad.padKeyCode(event), event.flags)
                 if (bit != 0) {
                     // The router forwards the bit on this device's own wire pad index and tracks held
                     // state per pad. The emergency-exit chord (Select + Start + L1 + R1) is handled
@@ -708,8 +708,10 @@ class MainActivity : ComponentActivity() {
             if (event.isFromSource(InputDevice.SOURCE_GAMEPAD)) {
                 // Not streaming: a game controller drives the Compose UI (TV + phone). Map the face
                 // 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) {
+                // already move focus on their own, so they fall through to super untouched. Read
+                // through [Gamepad.padKeyCode] so a pad Android has no key layout for reaches the
+                // menus on the right buttons too, not only the stream.
+                when (Gamepad.padKeyCode(event)) {
                     // 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.

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

@@ -940,6 +940,17 @@ fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> U
                         }
 
                         override fun surfaceChanged(holder: SurfaceHolder, format: Int, width: Int, height: Int) {
+                            // The view's CURRENT pixel size, for the ASurfaceControl layer's
+                            // destination rect. It is reported here and not only at
+                            // surfaceCreated because the view grows a frame or two after the
+                            // stream screen appears — hiding the system bars and switching on
+                            // cutout drawing both resize it, and neither recreates the surface.
+                            // A layer left on the start-up rect paints the picture small, in the
+                            // top-left corner. The view's own size, not the buffer geometry in
+                            // `width`/`height`: the layer composites in the view's space.
+                            NativeBridge.nativeVideoSurfaceSize(
+                                handle, this@apply.width, this@apply.height,
+                            )
                             // Re-assert the frame-rate vote: a buffer-geometry change can reset
                             // the surface's frame-rate setting on some OEM builds, silently
                             // dropping the 120 Hz pin mid-stream. Mirrors the native hint's

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

@@ -325,6 +325,7 @@ internal object ConsoleJson {
         extra.put("android.sc2_capture", s.sc2Capture)
         extra.put("android.ds_capture", s.dsCapture)
         extra.put("android.gamepad_ui_mode", s.gamepadUiMode)
+        extra.put("android.gamepad_ui_enabled", s.gamepadUiEnabled)
         j.put("extra", extra)
         return j
     }
@@ -379,6 +380,7 @@ internal object ConsoleJson {
             dsCapture = extra.optBoolean("android.ds_capture", s.dsCapture),
             gamepadUiMode = extra.optString("android.gamepad_ui_mode", s.gamepadUiMode)
                 .ifEmpty { s.gamepadUiMode },
+            gamepadUiEnabled = extra.optBoolean("android.gamepad_ui_enabled", s.gamepadUiEnabled),
         )
     }
 }

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

@@ -159,6 +159,9 @@ object SkiaConsole {
         val opts = JSONObject()
             .put("device_name", deviceName(app))
             .put("gpu_cache_bytes", gpuCacheBytes(app))
+            // The touch shell exists as a fallback on phones/tablets but not on a TV —
+            // gates the console's own "Controller-optimized UI" off switch.
+            .put("fallback_ui", !io.unom.punktfunk.isTvDevice(app))
             .put("settings", ConsoleJson.settings(initial, base))
             .put("profiles", JSONArray(ConsoleJson.profiles(profiles)))
             .put("known_hosts", JSONObject(ConsoleJson.knownHosts(knownHostStore.all())))

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

@@ -159,7 +159,12 @@ fun SkiaConsoleShell(
             if (ev.action != KeyEvent.ACTION_DOWN && ev.action != KeyEvent.ACTION_UP) return@probe false
             val fromPad = ev.isFromSource(InputDevice.SOURCE_GAMEPAD)
             if (fromPad) {
-                val bit = when (ev.keyCode) {
+                // The CORRECTED keycode: a pad Android has no key layout for delivers its buttons
+                // under other buttons' names, so read raw this console answered ✕ with whatever
+                // sat in BUTTON_A's scancode slot. Same resolution the stream uses — the console
+                // and the game must not disagree about which button a user pressed.
+                val code = Gamepad.padKeyCode(ev)
+                val bit = when (code) {
                     KeyEvent.KEYCODE_BUTTON_A -> 0
                     KeyEvent.KEYCODE_BUTTON_B -> 1
                     KeyEvent.KEYCODE_BUTTON_X -> 2
@@ -179,7 +184,7 @@ fun SkiaConsoleShell(
                     }
                     return@probe true
                 }
-                val dbit = when (ev.keyCode) {
+                val dbit = when (code) {
                     KeyEvent.KEYCODE_DPAD_UP -> 0
                     KeyEvent.KEYCODE_DPAD_DOWN -> 1
                     KeyEvent.KEYCODE_DPAD_LEFT -> 2
@@ -191,7 +196,7 @@ fun SkiaConsoleShell(
                     padState.push(handle)
                     return@probe true
                 }
-                if (ev.keyCode == KeyEvent.KEYCODE_BUTTON_SELECT && down && ev.repeatCount == 0) {
+                if (code == KeyEvent.KEYCODE_BUTTON_SELECT && down && ev.repeatCount == 0) {
                     NativeBridge.nativeConsoleMenu(handle, 0) // ▲ opens the tile's options on Home
                     return@probe true
                 }

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

@@ -3,6 +3,7 @@ package io.unom.punktfunk.kit
 import android.view.InputDevice
 import android.view.KeyEvent
 import android.view.MotionEvent
+import java.util.concurrent.ConcurrentHashMap
 import kotlin.math.roundToInt
 
 /**
@@ -127,8 +128,12 @@ object Gamepad {
 
     // Microsoft Xbox One / Series product ids (wired + the common Bluetooth/dongle revisions). All
     // behave like Xbox 360 on the host minus the glyph identity, so they share one pref byte.
+    // The Bluetooth revisions (0x02E0/0x02FD Xbox One S, 0x0B05/0x0B22 Elite Series 2 and its
+    // Core) are here for the same reason as the wired ones: they are the pads a couch actually
+    // pairs to a TV box, and without them an Elite streams under the Xbox 360 identity.
     private val PID_XBOXONE = setOf(
-        0x02D1, 0x02DD, 0x02E3, 0x02EA, 0x0B00, 0x0B12, 0x0B13, 0x0B20,
+        0x02D1, 0x02DD, 0x02E0, 0x02E3, 0x02EA, 0x02FD,
+        0x0B00, 0x0B05, 0x0B12, 0x0B13, 0x0B20, 0x0B22,
     )
 
     /**
@@ -188,9 +193,53 @@ object Gamepad {
             s and InputDevice.SOURCE_JOYSTICK == InputDevice.SOURCE_JOYSTICK
     }
 
-    /** All connected gamepad/joystick [InputDevice]s, in system enumeration order. */
-    fun pads(): List<InputDevice> =
-        InputDevice.getDeviceIds().toList().mapNotNull { InputDevice.getDevice(it) }.filter { isPad(it) }
+    /**
+     * True when [dev] is a controller someone can actually hold: a pad source ([isPad]) that is a
+     * REAL device carrying real pad hardware — a stick, a HAT, or the A/B face buttons.
+     *
+     * [isPad] alone answers "did this event come from a pad source", which is the right question
+     * for ROUTING an event and the wrong one for "is a controller attached". Devices publish
+     * inputs that claim `SOURCE_GAMEPAD`/`SOURCE_JOYSTICK` while being no such thing — OEM
+     * game-mode overlays and the gaming-phone shoulder triggers among them — and one of those is
+     * enough to pin the console UI on forever: a pad that was never there cannot disconnect, so
+     * "With a controller" has no way back to the touch UI.
+     *
+     * The capability probe is what separates them: a source class is a claim, a stick or a face
+     * button is hardware. It is not a complete defence — an OEM device that declares `BTN_GAMEPAD`
+     * and a pair of axes is indistinguishable from a pad at this layer — so the master switch stays
+     * the guaranteed way out. `isVirtual` only means "device id < 0" (the platform's own synthetic
+     * device), which is worth excluding but catches none of the above.
+     */
+    fun looksLikeController(dev: InputDevice?): Boolean {
+        val d = dev ?: return false
+        return looksLikeController(
+            padSource = isPad(d),
+            virtual = d.isVirtual,
+            hasStick = d.getMotionRange(MotionEvent.AXIS_X, InputDevice.SOURCE_JOYSTICK) != null ||
+                d.getMotionRange(MotionEvent.AXIS_HAT_X, InputDevice.SOURCE_JOYSTICK) != null,
+            // `hasKeys` answers for the DEVICE, so a pad with no sticks at all (an arcade stick,
+            // a d-pad-only pad) still counts.
+            hasFaceButtons = d.hasKeys(KeyEvent.KEYCODE_BUTTON_A, KeyEvent.KEYCODE_BUTTON_B)
+                .any { it },
+        )
+    }
+
+    /** [looksLikeController]'s decision, over plain facts — the seam its truth table is tested at
+     * (an [InputDevice] cannot be built off a device). */
+    fun looksLikeController(
+        padSource: Boolean,
+        virtual: Boolean,
+        hasStick: Boolean,
+        hasFaceButtons: Boolean,
+    ): Boolean = padSource && !virtual && (hasStick || hasFaceButtons)
+
+    /**
+     * All connected controllers, in system enumeration order — the devices that answer "is a pad
+     * attached", so the filter is [looksLikeController] rather than the looser [isPad].
+     */
+    fun pads(): List<InputDevice> = InputDevice.getDeviceIds().toList()
+        .mapNotNull { InputDevice.getDevice(it) }
+        .filter { looksLikeController(it) }
 
     /** First connected gamepad/joystick [InputDevice], or null when none is attached. */
     fun firstPad(): InputDevice? = pads().firstOrNull()
@@ -293,6 +342,334 @@ object Gamepad {
         else -> BTN_BACK
     }
 
+    // ---------------------------------------------------------------------------------------
+    // Controllers Android has no key layout for
+    //
+    // Android turns a pad's raw evdev scancode into a `KeyEvent.keyCode` through a KEY LAYOUT
+    // file matched on USB VID/PID (`Vendor_054c_Product_0ce6.kl` & co.). A pad with no matching
+    // file falls back to AOSP's `Generic.kl`, which assigns keycodes by SCANCODE POSITION —
+    // `0x130`→BUTTON_A, `0x131`→BUTTON_B, `0x132`→BUTTON_C, and so on up. That is only right if
+    // the pad's buttons happen to sit at the positions the file assumes, and a HID gamepad with
+    // no kernel driver behind it numbers its buttons 1..n straight through IN ITS OWN REPORT
+    // ORDER — so every keycode after the first divergence is somebody else's button.
+    //
+    // Reported from a Fire TV Stick 4K Max (2026-08-20): a DualSense and an Xbox Elite Series 2,
+    // both over Bluetooth, both identified correctly but with buttons landing on the wrong
+    // actions ("L1 being L2"). Neither has a layout there — AOSP ships none for the Elite
+    // Series 2 over Bluetooth (`045e:0b05`) on ANY version, and the DualSense's
+    // (`054c:0ce6`) both postdates Fire OS and carries `requires_kernel_config
+    // CONFIG_HID_PLAYSTATION`, which a Fire TV kernel does not have. A DualSense reporting
+    // straight through puts L2 on `0x136`, which `Generic.kl` calls BUTTON_L1: the reported
+    // symptom exactly.
+    //
+    // The fix is to resolve buttons from the SCANCODE, which is the pad's own report position and
+    // is immune to the layout file — the same reason [Keymap.toVk] reads `scanCode` for keyboards.
+    // Two things keep it from breaking a pad that already works:
+    //
+    //  1. Nothing is corrected on a pad that names its triggers ([padButtons]). A descriptor
+    //     well-formed enough to call them Accelerator/Brake puts its buttons at the standard
+    //     positions too, and that is the fact — not the model — that separates the two firmwares
+    //     of the SAME Xbox pad, only the older of which needs any of this.
+    //  2. Past that gate the correction still applies ONLY where the delivered keycode is what
+    //     `Generic.kl` would have said ([genericKeyCode]). A different keycode means a
+    //     device-specific layout IS in force and knows this pad better than we do.
+    //
+    // Moonlight carries the same two tables AND the same gate (`ControllerHandler`'s
+    // `isNonStandardDualShock4` / `isNonStandardXboxBtController`, the latter on `gasRange == null`),
+    // which is why both pads work there on the same box.
+    //
+    // The first cut of this asked `hasKeys(BUTTON_C, BUTTON_Z)` on its own, on the reasoning that a
+    // pad numbering straight through reaches keycodes no controller has a button for. It does — but
+    // so does every pad that merely DECLARES six buttons, because `hid-input` allocates `BTN_A + n`
+    // straight through for the whole descriptor whether or not the pad ever presses them. That fired
+    // the correction on pads Android was already reading correctly (2026-08-21: an Xbox pad
+    // answering X with Y, Y with LB, and both shoulders with a menu button), and it could not have
+    // done otherwise: the signal is identical on the firmware that needs correcting and the one that
+    // does not. Declaration is not report order. Only the axes tell them apart.
+
+    /** [MotionEvent] axis id meaning "this pad has no such axis" — see [PadMap]. */
+    const val AXIS_NONE = -1
+
+    /**
+     * The report order a controller's buttons are numbered in, and with it which scancode carries
+     * which physical button. Resolved once per device by [padButtons] from what the device
+     * declares; [correct] then maps one scancode to the keycode it should have produced.
+     */
+    enum class PadButtons {
+        /**
+         * The keycode Android delivered is already right — a device-specific key layout is in
+         * force, or the generic one happens to agree. [correct] changes nothing.
+         */
+        NATIVE,
+
+        /**
+         * A Sony pad numbering straight through with no kernel driver behind it: □ ✕ ○ △ L1 R1
+         * L2 R2 Create Options L3 R3 PS, i.e. `0x130`..`0x13c` in that order. The analog trigger
+         * value rides `AXIS_RX`/`AXIS_RY` on such a pad, so the digital L2/R2 fold to keycodes
+         * [buttonBit] deliberately drops — the wire carries the axis, never both.
+         */
+        GENERIC_SONY,
+
+        /**
+         * An Xbox-layout pad numbering straight through: A B X Y LB RB View Menu LS RS, i.e.
+         * `0x130`..`0x139`. Also the fallback for an unbranded pad, which near-universally
+         * clones the Xbox layout — the same assumption [styleFor] makes for its glyphs.
+         */
+        GENERIC_XBOX,
+
+        /**
+         * A Sony pad WITH a kernel driver (`hid-playstation` / `hid-sony`) but still no key
+         * layout — the combination an Android 11 box on a 5.10 kernel lands in. Such a driver
+         * emits the modern Linux gamepad codes, where `0x133` is BTN_NORTH (△) and `0x134` is
+         * BTN_WEST (□); `Generic.kl` reads those two as BUTTON_X and BUTTON_Y, so exactly the
+         * face pair comes out swapped and nothing else is wrong.
+         */
+        SONY_MODERN,
+        ;
+
+        /**
+         * The keycode scancode [scan] should have produced, given Android delivered [keyCode].
+         *
+         * Returns [keyCode] untouched unless it is precisely what [genericKeyCode] would have
+         * said for [scan] — anything else is a device-specific layout's answer, which outranks
+         * this table. That guard is what makes the correction idempotent and safe to run on
+         * every pad: it can only ever fire where Android was guessing in the first place.
+         */
+        fun correct(scan: Int, keyCode: Int): Int {
+            if (this == NATIVE) return keyCode
+            if (keyCode != genericKeyCode(scan)) return keyCode
+            val fixed = when (this) {
+                GENERIC_SONY -> when (scan) {
+                    0x130 -> KeyEvent.KEYCODE_BUTTON_X // □
+                    0x131 -> KeyEvent.KEYCODE_BUTTON_A // ✕
+                    0x132 -> KeyEvent.KEYCODE_BUTTON_B // ○
+                    0x133 -> KeyEvent.KEYCODE_BUTTON_Y // △
+                    0x134 -> KeyEvent.KEYCODE_BUTTON_L1
+                    0x135 -> KeyEvent.KEYCODE_BUTTON_R1
+                    0x136 -> KeyEvent.KEYCODE_BUTTON_L2 // analog: AXIS_RX
+                    0x137 -> KeyEvent.KEYCODE_BUTTON_R2 // analog: AXIS_RY
+                    0x138 -> KeyEvent.KEYCODE_BUTTON_SELECT // Create / Share
+                    0x139 -> KeyEvent.KEYCODE_BUTTON_START // Options
+                    0x13a -> KeyEvent.KEYCODE_BUTTON_THUMBL
+                    0x13b -> KeyEvent.KEYCODE_BUTTON_THUMBR
+                    0x13c -> KeyEvent.KEYCODE_BUTTON_MODE // PS
+                    // 0x13d touchpad click / 0x13e mute: no wire button, dropped as before.
+                    else -> KeyEvent.KEYCODE_UNKNOWN
+                }
+                GENERIC_XBOX -> when (scan) {
+                    0x132 -> KeyEvent.KEYCODE_BUTTON_X
+                    0x133 -> KeyEvent.KEYCODE_BUTTON_Y
+                    0x134 -> KeyEvent.KEYCODE_BUTTON_L1
+                    0x135 -> KeyEvent.KEYCODE_BUTTON_R1
+                    0x136 -> KeyEvent.KEYCODE_BUTTON_SELECT // View
+                    0x137 -> KeyEvent.KEYCODE_BUTTON_START // Menu
+                    0x138 -> KeyEvent.KEYCODE_BUTTON_THUMBL
+                    0x139 -> KeyEvent.KEYCODE_BUTTON_THUMBR
+                    else -> keyCode // 0x130 A / 0x131 B already agree
+                }
+                // Only the face pair; every other row of Generic.kl is right for these codes.
+                SONY_MODERN -> when (scan) {
+                    0x133 -> KeyEvent.KEYCODE_BUTTON_Y // BTN_NORTH = △
+                    0x134 -> KeyEvent.KEYCODE_BUTTON_X // BTN_WEST  = □
+                    else -> keyCode
+                }
+                NATIVE -> keyCode
+            }
+            return fixed
+        }
+    }
+
+    /**
+     * AOSP `Generic.kl`'s gamepad rows — the layout Android falls back to when no device-specific
+     * key layout matches the pad's VID/PID. Scancodes outside it answer [KeyEvent.KEYCODE_UNKNOWN],
+     * which never equals a real delivered keycode, so [PadButtons.correct]'s guard leaves those
+     * events alone.
+     */
+    fun genericKeyCode(scan: Int): Int = when (scan) {
+        0x130 -> KeyEvent.KEYCODE_BUTTON_A
+        0x131 -> KeyEvent.KEYCODE_BUTTON_B
+        0x132 -> KeyEvent.KEYCODE_BUTTON_C
+        0x133 -> KeyEvent.KEYCODE_BUTTON_X
+        0x134 -> KeyEvent.KEYCODE_BUTTON_Y
+        0x135 -> KeyEvent.KEYCODE_BUTTON_Z
+        0x136 -> KeyEvent.KEYCODE_BUTTON_L1
+        0x137 -> KeyEvent.KEYCODE_BUTTON_R1
+        0x138 -> KeyEvent.KEYCODE_BUTTON_L2
+        0x139 -> KeyEvent.KEYCODE_BUTTON_R2
+        0x13a -> KeyEvent.KEYCODE_BUTTON_SELECT
+        0x13b -> KeyEvent.KEYCODE_BUTTON_START
+        0x13c -> KeyEvent.KEYCODE_BUTTON_MODE
+        0x13d -> KeyEvent.KEYCODE_BUTTON_THUMBL
+        0x13e -> KeyEvent.KEYCODE_BUTTON_THUMBR
+        else -> KeyEvent.KEYCODE_UNKNOWN
+    }
+
+    /**
+     * How one controller must be read: its button report order plus the axes its right stick and
+     * analog triggers actually arrive on. Resolved once per device by [padMap].
+     */
+    class PadMap(
+        val buttons: PadButtons,
+        val rightStickX: Int = MotionEvent.AXIS_Z,
+        val rightStickY: Int = MotionEvent.AXIS_RZ,
+        /**
+         * The trigger axes, or [AXIS_NONE] for a pad Android already names them on — that case
+         * keeps folding LTRIGGER with BRAKE and RTRIGGER with GAS by max, which is what pads that
+         * report one pair, the other, or both have always needed.
+         */
+        val leftTrigger: Int = AXIS_NONE,
+        val rightTrigger: Int = AXIS_NONE,
+        /** Those trigger axes rest at −1 rather than 0, measured off the device's own range. */
+        val triggersSigned: Boolean = false,
+    ) {
+        /** One resolved trigger axis value, folded to the 0..1 the wire scale expects. */
+        fun level(v: Float): Float = if (triggersSigned) (v + 1f) / 2f else v
+    }
+
+    /** The map every pad with a key layout uses: Android's own names, unchanged. */
+    private val NATIVE_MAP = PadMap(PadButtons.NATIVE)
+
+    /**
+     * Resolved [PadMap]s, keyed by [InputDevice.getDescriptor] — the device's stable identity
+     * hash, so a pad that reconnects is recognised and a model resolves once for the process.
+     * Nothing here depends on a live connection, so entries never need evicting.
+     */
+    private val padMaps = ConcurrentHashMap<String, PadMap>()
+
+    /**
+     * Which report order [dev]'s buttons follow — [namedTriggers] is whether the pad reports its
+     * triggers under a name Android knows (see [padMap]), and [declaresCZ] whether it declares
+     * BUTTON_C and BUTTON_Z.
+     *
+     * `namedTriggers` decides it, and a pad that has them is [PadButtons.NATIVE] whatever else it
+     * says. A HID gamepad describes its triggers either as the Accelerator/Brake usages, which
+     * become `ABS_GAS`/`ABS_BRAKE` and axis names Android has words for, or as two more generic
+     * axes on `ABS_Z`/`ABS_RZ`, which it does not — and a report descriptor well-formed enough to
+     * name its triggers puts its buttons at the standard positions too, the ones `Generic.kl`
+     * already reads correctly. It is the same fact Moonlight decides this on (`gasRange == null`
+     * beside the `"Xbox Wireless Controller"` name), and it is the one that separates the two
+     * firmwares of the SAME pad: an Xbox Wireless Controller over Bluetooth reports GAS/BRAKE
+     * after its firmware update and Z/Rz before it, and only the older one needs correcting.
+     *
+     * `declaresCZ` cannot make that call and must never be asked to. `hasKeys` answers for what a
+     * device DECLARES, not what it reports: `hid-input` allocates `BTN_A + n` straight through for
+     * every button in the descriptor, so BTN_C (`0x132`) and BTN_Z (`0x135`) are set on any pad
+     * declaring six or more — a standard-layout pad that never presses either included. Read alone
+     * it fired the correction on pads whose buttons were already right, which is how an Xbox pad
+     * came to answer X with Y and Y with LB (field reports, 2026-08-21). It stays as the narrower
+     * question it can answer — WHICH straight-through order, once `namedTriggers` has established
+     * there is one — where a false positive costs nothing.
+     */
+    fun padButtons(dev: InputDevice, namedTriggers: Boolean): PadButtons {
+        val has = dev.hasKeys(KeyEvent.KEYCODE_BUTTON_C, KeyEvent.KEYCODE_BUTTON_Z, 0)
+        return padButtons(namedTriggers, dev.vendorId == VID_SONY, declaresCZ = has[0] && has[1])
+    }
+
+    /** [padButtons]'s choice over plain facts — the seam its truth table is tested at (an
+     * [InputDevice] cannot be built off a device). */
+    fun padButtons(namedTriggers: Boolean, sony: Boolean, declaresCZ: Boolean): PadButtons = when {
+        namedTriggers -> PadButtons.NATIVE
+        declaresCZ && sony -> PadButtons.GENERIC_SONY
+        declaresCZ -> PadButtons.GENERIC_XBOX
+        sony -> PadButtons.SONY_MODERN
+        else -> PadButtons.NATIVE
+    }
+
+    /**
+     * The [PadMap] for [dev] — its button report order and the axes its right stick and triggers
+     * arrive on, resolved once per device model and cached.
+     *
+     * Axes get the same treatment as buttons: a pad Android has a layout for names its triggers
+     * LTRIGGER/RTRIGGER (or BRAKE/GAS, or BRAKE/THROTTLE) and is left exactly as it was. A pad
+     * with NONE of those names is one Android never mapped, and its triggers are sitting on two
+     * raw axes under the names the HID report gave them. Which two depends on the same report
+     * order the buttons did:
+     *
+     *  - a Sony pad reporting straight through lays out X, Y, Z, Rz, Rx, Ry = left stick, right
+     *    stick, then the triggers — so the right stick is already right and only the triggers
+     *    (`AXIS_RX`/`AXIS_RY`) are missed;
+     *  - every other such pad puts the right stick on Rx/Ry and the triggers on Z/Rz, which is
+     *    the shape that makes pulling a trigger swing the right stick.
+     *
+     * Whether those axes idle at −1 is MEASURED from the device's own range rather than assumed,
+     * so a pad that reports an honest 0..1 is not rescaled to a permanent half-pull.
+     */
+    fun padMap(dev: InputDevice?): PadMap {
+        if (dev == null) return NATIVE_MAP
+        padMaps[dev.descriptor]?.let { return it }
+        fun has(a: Int) = axis(dev, a) != null
+        val named = (has(MotionEvent.AXIS_LTRIGGER) && has(MotionEvent.AXIS_RTRIGGER)) ||
+            (has(MotionEvent.AXIS_BRAKE) && has(MotionEvent.AXIS_GAS)) ||
+            (has(MotionEvent.AXIS_BRAKE) && has(MotionEvent.AXIS_THROTTLE))
+        val buttons = padButtons(dev, namedTriggers = named)
+        val rx = axis(dev, MotionEvent.AXIS_RX)
+        val hasRxRy = rx != null && has(MotionEvent.AXIS_RY)
+        // Whichever pair the fallback is about to pick, ask THAT one where it rests.
+        val restsNegative = if (buttons == PadButtons.GENERIC_SONY) {
+            (rx?.min ?: 0f) < -0.5f
+        } else {
+            (axis(dev, MotionEvent.AXIS_Z)?.min ?: 0f) < -0.5f
+        }
+        val map = padMap(buttons, namedTriggers = named, hasRxRy = hasRxRy, restsNegative = restsNegative)
+        padMaps[dev.descriptor] = map
+        return map
+    }
+
+    /**
+     * The axis half of [padMap], decided from four facts about the device so it can be pinned
+     * without one — see `PadButtonsTest`. [namedTriggers] is whether the pad calls its triggers
+     * anything Android knows (LTRIGGER/RTRIGGER, BRAKE/GAS, BRAKE/THROTTLE); if it does, nothing
+     * here applies and the pad is read exactly as it always was. [restsNegative] is measured off
+     * whichever axis pair the fallback picks, never assumed.
+     */
+    fun padMap(
+        buttons: PadButtons,
+        namedTriggers: Boolean,
+        hasRxRy: Boolean,
+        restsNegative: Boolean,
+    ): PadMap = when {
+        namedTriggers || !hasRxRy -> PadMap(buttons)
+        // X, Y, Z, Rz, Rx, Ry = left stick, right stick, triggers. The sticks already read right.
+        buttons == PadButtons.GENERIC_SONY -> PadMap(
+            buttons,
+            leftTrigger = MotionEvent.AXIS_RX,
+            rightTrigger = MotionEvent.AXIS_RY,
+            triggersSigned = restsNegative,
+        )
+        // Right stick on Rx/Ry and triggers on Z/Rz — the shape in which reading Z/Rz as the
+        // right stick makes pulling a trigger swing it.
+        else -> PadMap(
+            buttons,
+            rightStickX = MotionEvent.AXIS_RX,
+            rightStickY = MotionEvent.AXIS_RY,
+            leftTrigger = MotionEvent.AXIS_Z,
+            rightTrigger = MotionEvent.AXIS_RZ,
+            triggersSigned = restsNegative,
+        )
+    }
+
+    /** [dev]'s range for one joystick [axis], under either source class a pad reports on. */
+    private fun axis(dev: InputDevice, axis: Int): InputDevice.MotionRange? =
+        dev.getMotionRange(axis, InputDevice.SOURCE_JOYSTICK)
+            ?: dev.getMotionRange(axis, InputDevice.SOURCE_GAMEPAD)
+
+    /**
+     * The keycode [event] should have carried, given the controller it came from — [event]'s own
+     * keycode for every pad Android has a key layout for, and the scancode's true button for one
+     * it does not (see the block comment above [PadButtons]).
+     *
+     * A drop-in for `event.keyCode` at every gamepad reader: the console UI's navigation, the
+     * Controllers screen's tester, and the streaming branch all route through it, so a mis-mapped
+     * pad is fixed in the menus and in the game at once. Events from anything that is not a
+     * controller, and events with no scancode (soft keyboards, synthetic events), pass through
+     * untouched.
+     */
+    fun padKeyCode(event: KeyEvent): Int {
+        val dev = event.device ?: return event.keyCode
+        if (event.scanCode == 0 || !isPad(dev)) return event.keyCode
+        return padMap(dev).buttons.correct(event.scanCode, event.keyCode)
+    }
+
     /**
      * Maps one controller's joystick MotionEvents to axis (+ HAT→dpad) sends on wire pad index [pad],
      * **on change only**. Holds the previous axis/hat state so an unchanged frame emits nothing. One
@@ -306,7 +683,12 @@ object Gamepad {
      * node (DualSense/DS4 motion sensors), which reports every pad axis as 0. [onMotion] therefore
      * folds the event straight in without re-qualifying it.
      */
-    class AxisMapper(private val handle: Long, private val pad: Int) {
+    class AxisMapper(
+        private val handle: Long,
+        private val pad: Int,
+        /** Which axes this controller's right stick and triggers arrive on — see [padMap]. */
+        private val map: PadMap = NATIVE_MAP,
+    ) {
         // Sentinel so the first real value (incl. 0) always sends once after attach (Linux parity).
         private val last = IntArray(6) { Int.MIN_VALUE }
         private var hatX = 0 // -1 / 0 / +1
@@ -317,30 +699,18 @@ object Gamepad {
             // Sticks: Android floats −1..1, +y = down → ±32767, negate Y for the wire's +y = up.
             sendAxis(AXIS_LS_X, stick(event.getAxisValue(MotionEvent.AXIS_X)))
             sendAxis(AXIS_LS_Y, stick(-event.getAxisValue(MotionEvent.AXIS_Y)))
-            sendAxis(AXIS_RS_X, stick(event.getAxisValue(MotionEvent.AXIS_Z)))
-            sendAxis(AXIS_RS_Y, stick(-event.getAxisValue(MotionEvent.AXIS_RZ)))
+            sendAxis(AXIS_RS_X, stick(event.getAxisValue(map.rightStickX)))
+            sendAxis(AXIS_RS_Y, stick(-event.getAxisValue(map.rightStickY)))
 
             // Triggers: pads report LTRIGGER/RTRIGGER or BRAKE/GAS (some mirror both) — merge
             // with max, the same fold as the Controllers screen probe, so a pad that reports
-            // only one pair and a pad that reports both behave identically; 0..1 → 0..255.
-            sendAxis(
-                AXIS_LT,
-                trigger(
-                    maxOf(
-                        event.getAxisValue(MotionEvent.AXIS_LTRIGGER),
-                        event.getAxisValue(MotionEvent.AXIS_BRAKE),
-                    ),
-                ),
-            )
-            sendAxis(
-                AXIS_RT,
-                trigger(
-                    maxOf(
-                        event.getAxisValue(MotionEvent.AXIS_RTRIGGER),
-                        event.getAxisValue(MotionEvent.AXIS_GAS),
-                    ),
-                ),
-            )
+            // only one pair and a pad that reports both behave identically; 0..1 → 0..255. A pad
+            // reporting NONE of those names is one Android has no key layout for, and [map]
+            // carries the raw axes its triggers really landed on instead.
+            val lt = resolved(event, map.leftTrigger, MotionEvent.AXIS_LTRIGGER, MotionEvent.AXIS_BRAKE)
+            val rt = resolved(event, map.rightTrigger, MotionEvent.AXIS_RTRIGGER, MotionEvent.AXIS_GAS)
+            sendAxis(AXIS_LT, trigger(lt))
+            sendAxis(AXIS_RT, trigger(rt))
 
             // HAT → dpad button transitions. Android BATCHES joystick ACTION_MOVEs, so a rapid d-pad
             // tap (press+release inside one batch window) lives only in the historical samples — the
@@ -383,6 +753,17 @@ object Gamepad {
             hatY = 0
         }
 
+        /**
+         * One trigger's 0..1 value: [resolvedAxis] when this pad needed one resolved for it,
+         * else the max of the two names Android gives a trigger it does know.
+         */
+        private fun resolved(event: MotionEvent, resolvedAxis: Int, named: Int, alias: Int): Float =
+            if (resolvedAxis == AXIS_NONE) {
+                maxOf(event.getAxisValue(named), event.getAxisValue(alias))
+            } else {
+                map.level(event.getAxisValue(resolvedAxis))
+            }
+
         private fun sendAxis(id: Int, v: Int) {
             if (last[id] == v) return
             last[id] = v

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

@@ -605,7 +605,7 @@ class GamepadRouter(
         // for the slot's life; the sensor path reads it on every sample.
         val slot = Slot(
             index,
-            Gamepad.AxisMapper(handle, index),
+            Gamepad.AxisMapper(handle, index, Gamepad.padMap(dev)),
             NativeBridge.nativePadMotionReaches(handle, pref),
         )
         slots[dev.id] = slot

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

@@ -298,6 +298,18 @@ object NativeBridge {
         surfaceH: Int,
     )
 
+    /**
+     * Re-report the video SurfaceView's on-screen pixel size — call it from every `surfaceChanged`.
+     *
+     * The ASurfaceControl present backend composites the picture into exactly this rectangle, and
+     * the view grows AFTER [nativeStartVideo] has run: the stream screen hides the system bars and
+     * switches the window to draw into the display cutout a frame or two later, and neither
+     * recreates the surface. Without this the layer keeps painting at its start-up size in the
+     * corner of a now-bigger surface. Non-positive values are ignored. No-op on a `0` handle;
+     * cheap (one atomic store), UI-safe.
+     */
+    external fun nativeVideoSurfaceSize(handle: Long, width: Int, height: Int)
+
     /** Stop + join the decode thread without closing the session. No-op on `0`. */
     external fun nativeStopVideo(handle: Long)
 

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

@@ -0,0 +1,254 @@
+package io.unom.punktfunk.kit
+
+import android.view.KeyEvent
+import android.view.MotionEvent
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+/**
+ * Pure JVM test of [Gamepad.PadButtons.correct] — the scancode resolution for controllers Android
+ * has no key layout for. Only `KeyEvent`'s compile-time-inlined keycode constants are involved, so
+ * no Android runtime is needed. Run: `./gradlew :kit:testDebugUnitTest`.
+ *
+ * The regression it pins is a field report from a Fire TV Stick 4K Max (2026-08-20): a DualSense
+ * and an Xbox Elite Series 2, both over Bluetooth, both identified correctly but with buttons
+ * landing on the wrong actions — "L1 being L2". Neither pad has a key layout on that box (AOSP
+ * ships none for `045e:0b05` at all, and the DualSense's requires `CONFIG_HID_PLAYSTATION`), so
+ * both fall back to `Generic.kl`, which names keycodes by scancode POSITION. A pad with no kernel
+ * driver numbers its HID buttons 1..n straight through in its own report order, so every keycode
+ * after the first divergence belongs to a different button.
+ *
+ * The table below is the pad's physical button on the left and where `Generic.kl` put it on the
+ * right; the assertions read it back the other way.
+ */
+class PadButtonsTest {
+
+    private fun sony(scan: Int) =
+        Gamepad.PadButtons.GENERIC_SONY.correct(scan, Gamepad.genericKeyCode(scan))
+
+    private fun xbox(scan: Int) =
+        Gamepad.PadButtons.GENERIC_XBOX.correct(scan, Gamepad.genericKeyCode(scan))
+
+    /**
+     * The exact report: a DualSense's L2 sits at scancode `0x136`, which `Generic.kl` calls
+     * BUTTON_L1 — so pulling L2 read as a shoulder press, and L1 (at `0x134`, read as BUTTON_Y)
+     * read as a face button.
+     */
+    @Test
+    fun `a DualSense's shoulders stop being each other's buttons`() {
+        assertEquals(KeyEvent.KEYCODE_BUTTON_L1, sony(0x134)) // L1, delivered as BUTTON_Y
+        assertEquals(KeyEvent.KEYCODE_BUTTON_R1, sony(0x135)) // R1, delivered as BUTTON_Z
+        assertEquals(KeyEvent.KEYCODE_BUTTON_L2, sony(0x136)) // L2, delivered as BUTTON_L1
+        assertEquals(KeyEvent.KEYCODE_BUTTON_R2, sony(0x137)) // R2, delivered as BUTTON_R1
+    }
+
+    /** ✕ is the bottom button — the one A means everywhere else — and □ is the left one. */
+    @Test
+    fun `a DualSense's face buttons land on their Xbox positions`() {
+        assertEquals(KeyEvent.KEYCODE_BUTTON_X, sony(0x130)) // □
+        assertEquals(KeyEvent.KEYCODE_BUTTON_A, sony(0x131)) // ✕
+        assertEquals(KeyEvent.KEYCODE_BUTTON_B, sony(0x132)) // ○
+        assertEquals(KeyEvent.KEYCODE_BUTTON_Y, sony(0x133)) // △
+    }
+
+    /**
+     * Create/Options/L3/R3/PS. Select in particular: without this it arrived as BUTTON_THUMBL,
+     * which took the exit, mic and stats chords with it — every one of them is built on Select.
+     */
+    @Test
+    fun `a DualSense's menu buttons and stick clicks are themselves`() {
+        assertEquals(KeyEvent.KEYCODE_BUTTON_SELECT, sony(0x138)) // Create
+        assertEquals(KeyEvent.KEYCODE_BUTTON_START, sony(0x139)) // Options
+        assertEquals(KeyEvent.KEYCODE_BUTTON_THUMBL, sony(0x13a)) // L3
+        assertEquals(KeyEvent.KEYCODE_BUTTON_THUMBR, sony(0x13b)) // R3
+        assertEquals(KeyEvent.KEYCODE_BUTTON_MODE, sony(0x13c)) // PS
+    }
+
+    /** The touchpad click and mute have no wire button; they must resolve to nothing, not to R3. */
+    @Test
+    fun `a DualSense's touchpad and mute are dropped rather than mistaken`() {
+        assertEquals(KeyEvent.KEYCODE_UNKNOWN, sony(0x13d))
+        assertEquals(KeyEvent.KEYCODE_UNKNOWN, sony(0x13e))
+        assertEquals(0, Gamepad.buttonBit(sony(0x13d)))
+    }
+
+    /** An Xbox-layout pad numbering straight through: A B X Y LB RB View Menu LS RS. */
+    @Test
+    fun `an Xbox pad numbering straight through keeps its own layout`() {
+        assertEquals(KeyEvent.KEYCODE_BUTTON_A, xbox(0x130))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_B, xbox(0x131))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_X, xbox(0x132))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_Y, xbox(0x133))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_L1, xbox(0x134))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_R1, xbox(0x135))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_SELECT, xbox(0x136)) // View
+        assertEquals(KeyEvent.KEYCODE_BUTTON_START, xbox(0x137)) // Menu
+        assertEquals(KeyEvent.KEYCODE_BUTTON_THUMBL, xbox(0x138))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_THUMBR, xbox(0x139))
+    }
+
+    /** `hid-playstation` emits the modern Linux codes, where only the face pair reads swapped. */
+    @Test
+    fun `a driver-backed Sony pad has only its face pair corrected`() {
+        val m = Gamepad.PadButtons.SONY_MODERN
+        assertEquals(KeyEvent.KEYCODE_BUTTON_Y, m.correct(0x133, KeyEvent.KEYCODE_BUTTON_X)) // △
+        assertEquals(KeyEvent.KEYCODE_BUTTON_X, m.correct(0x134, KeyEvent.KEYCODE_BUTTON_Y)) // □
+        for (scan in listOf(0x130, 0x131, 0x136, 0x137, 0x13a, 0x13b, 0x13c)) {
+            assertEquals(Gamepad.genericKeyCode(scan), m.correct(scan, Gamepad.genericKeyCode(scan)))
+        }
+    }
+
+    /**
+     * The guard that makes all of this safe to run on every pad: a keycode that is NOT what
+     * `Generic.kl` would have said came from a device-specific key layout, which knows this
+     * controller better than any table here. Correcting it would break a pad that works.
+     */
+    @Test
+    fun `a keycode a device layout already resolved is never second-guessed`() {
+        // AOSP's DualSense layout puts △ on BUTTON_Y itself. Every profile must leave it be.
+        for (p in Gamepad.PadButtons.entries) {
+            assertEquals(KeyEvent.KEYCODE_BUTTON_Y, p.correct(0x133, KeyEvent.KEYCODE_BUTTON_Y))
+        }
+        // Same for a scancode outside the generic gamepad block entirely — a pad's Back key.
+        assertEquals(
+            KeyEvent.KEYCODE_BACK,
+            Gamepad.PadButtons.GENERIC_SONY.correct(158, KeyEvent.KEYCODE_BACK),
+        )
+    }
+
+    /** Correcting twice is correcting once — the output is never itself a generic-layout answer. */
+    @Test
+    fun `correction is idempotent`() {
+        for (p in Gamepad.PadButtons.entries) {
+            for (scan in 0x130..0x13e) {
+                val once = p.correct(scan, Gamepad.genericKeyCode(scan))
+                assertEquals(once, p.correct(scan, once))
+            }
+        }
+    }
+
+    /**
+     * The axis half. A pad that names its triggers something Android knows is read exactly as it
+     * always was — this is the branch that must NOT fire on the pads that already work.
+     */
+    @Test
+    fun `a pad that names its triggers is read unchanged`() {
+        for (p in Gamepad.PadButtons.entries) {
+            val map = Gamepad.padMap(p, namedTriggers = true, hasRxRy = true, restsNegative = true)
+            assertEquals(MotionEvent.AXIS_Z, map.rightStickX)
+            assertEquals(MotionEvent.AXIS_RZ, map.rightStickY)
+            assertEquals(Gamepad.AXIS_NONE, map.leftTrigger)
+            assertEquals(Gamepad.AXIS_NONE, map.rightTrigger)
+        }
+        // Same when there is no Rx/Ry to fall back to in the first place.
+        val none = Gamepad.padMap(Gamepad.PadButtons.GENERIC_SONY, false, hasRxRy = false, restsNegative = false)
+        assertEquals(Gamepad.AXIS_NONE, none.leftTrigger)
+    }
+
+    /**
+     * A Sony pad reporting straight through lays out X, Y, Z, Rz, Rx, Ry — left stick, right
+     * stick, then the triggers. Only the triggers were being missed; the sticks already read
+     * right and must be left alone.
+     */
+    @Test
+    fun `an unmapped Sony pad keeps its sticks and gains its triggers`() {
+        val map = Gamepad.padMap(Gamepad.PadButtons.GENERIC_SONY, false, hasRxRy = true, restsNegative = false)
+        assertEquals(MotionEvent.AXIS_Z, map.rightStickX)
+        assertEquals(MotionEvent.AXIS_RZ, map.rightStickY)
+        assertEquals(MotionEvent.AXIS_RX, map.leftTrigger)
+        assertEquals(MotionEvent.AXIS_RY, map.rightTrigger)
+    }
+
+    /**
+     * Every other unmapped pad is the opposite way round: right stick on Rx/Ry, triggers on Z/Rz.
+     * Reading Z/Rz as the right stick there is what makes pulling a trigger swing it — so the two
+     * pairs must never be mixed up, which is the whole point of pinning them.
+     */
+    @Test
+    fun `an unmapped Xbox-layout pad has its stick and triggers the other way round`() {
+        for (p in listOf(Gamepad.PadButtons.GENERIC_XBOX, Gamepad.PadButtons.SONY_MODERN)) {
+            val map = Gamepad.padMap(p, namedTriggers = false, hasRxRy = true, restsNegative = false)
+            assertEquals(MotionEvent.AXIS_RX, map.rightStickX)
+            assertEquals(MotionEvent.AXIS_RY, map.rightStickY)
+            assertEquals(MotionEvent.AXIS_Z, map.leftTrigger)
+            assertEquals(MotionEvent.AXIS_RZ, map.rightTrigger)
+        }
+    }
+
+    /**
+     * A trigger axis that idles at −1 is rescaled; one that idles at 0 must NOT be, or it would
+     * read as a permanent half-pull. Which it is gets measured off the device, never assumed —
+     * both the DualSense's raw RX/RY and the Xbox pad's Z/Rz report an honest 0..1.
+     */
+    @Test
+    fun `only a trigger that idles negative is rescaled`() {
+        val signed = Gamepad.padMap(Gamepad.PadButtons.GENERIC_SONY, false, hasRxRy = true, restsNegative = true)
+        assertEquals(0f, signed.level(-1f), 1e-6f)
+        assertEquals(0.5f, signed.level(0f), 1e-6f)
+        assertEquals(1f, signed.level(1f), 1e-6f)
+
+        val unsigned = Gamepad.padMap(Gamepad.PadButtons.GENERIC_SONY, false, hasRxRy = true, restsNegative = false)
+        assertEquals(0f, unsigned.level(0f), 1e-6f)
+        assertEquals(1f, unsigned.level(1f), 1e-6f)
+    }
+
+    /** A pad Android does know is untouched, which is most of them. */
+    @Test
+    fun `a pad with a key layout is left alone`() {
+        for (scan in 0x130..0x13e) {
+            val generic = Gamepad.genericKeyCode(scan)
+            assertEquals(generic, Gamepad.PadButtons.NATIVE.correct(scan, generic))
+        }
+    }
+
+    /**
+     * The regression that made this gate necessary (field reports, 2026-08-21): an Xbox Wireless
+     * Controller and a GameSir G8+, both with their buttons at the standard positions and both
+     * corrected anyway, because `hasKeys` says BUTTON_C and BUTTON_Z for any pad that DECLARES six
+     * buttons — `hid-input` allocates the whole descriptor `BTN_A + n` straight through whether the
+     * pad ever presses them or not. Naming the triggers is what tells the two apart.
+     */
+    @Test
+    fun `a pad that names its triggers is never corrected, whatever it declares`() {
+        for (sony in listOf(false, true)) {
+            for (declaresCZ in listOf(false, true)) {
+                assertEquals(
+                    Gamepad.PadButtons.NATIVE,
+                    Gamepad.padButtons(namedTriggers = true, sony = sony, declaresCZ = declaresCZ),
+                )
+            }
+        }
+    }
+
+    /**
+     * The four buttons the field reports named, on a pad whose report order is already standard:
+     * X answering Y, Y answering LB, and both shoulders answering a menu button. NATIVE is what
+     * keeps them themselves — the correction tables are right for the pads they are for, and this
+     * is about not reaching one of them.
+     */
+    @Test
+    fun `an Xbox pad at the standard positions keeps X, Y and its shoulders`() {
+        val native = Gamepad.PadButtons.NATIVE
+        assertEquals(KeyEvent.KEYCODE_BUTTON_X, native.correct(0x133, KeyEvent.KEYCODE_BUTTON_X))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_Y, native.correct(0x134, KeyEvent.KEYCODE_BUTTON_Y))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_L1, native.correct(0x136, KeyEvent.KEYCODE_BUTTON_L1))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_R1, native.correct(0x137, KeyEvent.KEYCODE_BUTTON_R1))
+        // What the old heuristic did to each of them, kept here so the difference stays visible.
+        val wrong = Gamepad.PadButtons.GENERIC_XBOX
+        assertEquals(KeyEvent.KEYCODE_BUTTON_Y, wrong.correct(0x133, KeyEvent.KEYCODE_BUTTON_X))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_L1, wrong.correct(0x134, KeyEvent.KEYCODE_BUTTON_Y))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_SELECT, wrong.correct(0x136, KeyEvent.KEYCODE_BUTTON_L1))
+        assertEquals(KeyEvent.KEYCODE_BUTTON_START, wrong.correct(0x137, KeyEvent.KEYCODE_BUTTON_R1))
+    }
+
+    /** Past the gate, which straight-through order to read is still the question it always was. */
+    @Test
+    fun `an unnamed-trigger pad still resolves its report order`() {
+        fun order(sony: Boolean, declaresCZ: Boolean) =
+            Gamepad.padButtons(namedTriggers = false, sony = sony, declaresCZ = declaresCZ)
+        assertEquals(Gamepad.PadButtons.GENERIC_SONY, order(sony = true, declaresCZ = true))
+        assertEquals(Gamepad.PadButtons.GENERIC_XBOX, order(sony = false, declaresCZ = true))
+        assertEquals(Gamepad.PadButtons.SONY_MODERN, order(sony = true, declaresCZ = false))
+        assertEquals(Gamepad.PadButtons.NATIVE, order(sony = false, declaresCZ = false))
+    }
+}

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

@@ -0,0 +1,67 @@
+package io.unom.punktfunk.kit
+
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * The truth table behind "is a controller attached" — the question the console UI's
+ * "With a controller" mode is answered by. A false positive here is not cosmetic: it pins the
+ * console UI on with no pad in the room, and no setting short of turning the whole thing off can
+ * dismiss it, because the phantom pad never disconnects.
+ */
+class PadPresenceTest {
+
+    /** A real pad: the source class plus hardware behind it, in either of the two shapes. */
+    @Test
+    fun realPadsCount() {
+        assertTrue(
+            Gamepad.looksLikeController(
+                padSource = true, virtual = false, hasStick = true, hasFaceButtons = true,
+            ),
+        )
+        // An arcade stick / d-pad-only pad — buttons, no analog stick.
+        assertTrue(
+            Gamepad.looksLikeController(
+                padSource = true, virtual = false, hasStick = false, hasFaceButtons = true,
+            ),
+        )
+        // A wheel or flight stick — axes, no A/B.
+        assertTrue(
+            Gamepad.looksLikeController(
+                padSource = true, virtual = false, hasStick = true, hasFaceButtons = false,
+            ),
+        )
+    }
+
+    /** The gaming-phone shoulder triggers and OEM game-mode overlays: a virtual device wearing the
+     * gamepad source class. This is the field report — the console UI that could not be dismissed. */
+    @Test
+    fun virtualDevicesAreNotControllers() {
+        assertFalse(
+            Gamepad.looksLikeController(
+                padSource = true, virtual = true, hasStick = true, hasFaceButtons = true,
+            ),
+        )
+    }
+
+    /** A device that claims a pad source with nothing behind it is not a pad either. */
+    @Test
+    fun aSourceClaimWithoutHardwareIsNotAController() {
+        assertFalse(
+            Gamepad.looksLikeController(
+                padSource = true, virtual = false, hasStick = false, hasFaceButtons = false,
+            ),
+        )
+    }
+
+    /** And a keyboard/mouse with sticks it never reports on the joystick source stays out. */
+    @Test
+    fun nonPadSourcesNeverCount() {
+        assertFalse(
+            Gamepad.looksLikeController(
+                padSource = false, virtual = false, hasStick = true, hasFaceButtons = true,
+            ),
+        )
+    }
+}

clients/android/native/src/console/mod.rs

@@ -45,6 +45,10 @@ struct CreateOptions {
     device_name: String,
     /// Skia's resource budget, bytes (Kotlin sizes it from `ActivityManager.memoryClass`).
     gpu_cache_bytes: usize,
+    /// Whether the touch shell exists as a fallback (phones/tablets; false on a TV) —
+    /// gates the console-off settings row. Default false: absent means don't offer it.
+    #[serde(default)]
+    fallback_ui: bool,
     /// The settings snapshot the shell starts from (`pf_client_core::trust::Settings` JSON).
     settings: pf_client_core::trust::Settings,
     /// The profile catalog as `[[id, name], …]`.
@@ -150,6 +154,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConsoleCrea
         let console_opts = ConsoleOptions {
             device_name: opts.device_name,
             deck: false,
+            fallback_ui: opts.fallback_ui,
             store: Some(store.clone()),
             platform: Platform::Android,
             gpu_cache_bytes: opts.gpu_cache_bytes.max(16 << 20),

clients/android/native/src/decode/asc_presenter.rs

@@ -142,21 +142,21 @@ pub(super) struct AscBackend {
 impl AscBackend {
     /// Create the reader + compositor layer, or `None` on API < 29 / init failure (the caller then
     /// runs the SurfaceView presenter). `window` is the SurfaceView's `ANativeWindow`; `src_w/h` the
-    /// negotiated decode size; `panel_hz` the mode-table panel rate (seeds the learner);
+    /// negotiated decode size; `surface_size` the LIVE view size the layer composites into;
+    /// `panel_hz` the mode-table panel rate (seeds the learner);
     /// `dataspace` the `ADataSpace` from the negotiated colour; `source_hz` the negotiated stream rate.
     #[allow(clippy::too_many_arguments)]
     pub(super) fn create(
         window: &NativeWindow,
         src_w: i32,
         src_h: i32,
-        surface_w: i32,
-        surface_h: i32,
+        surface_size: std::sync::Arc<std::sync::atomic::AtomicU64>,
         panel_hz: i32,
         dataspace: i32,
         source_hz: u32,
         priority: PresentPriority,
     ) -> Option<AscBackend> {
-        let layer = Layer::create(window, surface_w, surface_h)?;
+        let layer = Layer::create(window, surface_size)?;
         let usage = ndk::hardware_buffer::HardwareBufferUsage::GPU_SAMPLED_IMAGE
             | ndk::hardware_buffer::HardwareBufferUsage::COMPOSER_OVERLAY;
         let reader = match ImageReader::new_with_usage(

clients/android/native/src/decode/async_loop.rs

@@ -96,8 +96,7 @@ pub(super) fn run_async(
         present_priority,
         smooth_buffer,
         panel_hz,
-        surface_w,
-        surface_h,
+        surface_size,
     } = opts;
     boost_thread_priority();
     let mode = client.mode();
@@ -199,8 +198,7 @@ pub(super) fn run_async(
             &window,
             mode.width as i32,
             mode.height as i32,
-            surface_w,
-            surface_h,
+            surface_size,
             panel_hz,
             initial_ds,
             mode.refresh_hz,

clients/android/native/src/decode/mod.rs

@@ -91,7 +91,14 @@ const NO_VIDEO_PATIENCE: std::time::Duration = std::time::Duration::from_millis(
 
 /// Re-ask cadence once [`NO_VIDEO_PATIENCE`] has elapsed with still nothing received. Slow, because
 /// this state is either self-healing on the first ask or not ours to heal — and each pass logs.
-const NO_VIDEO_RETRY: std::time::Duration = std::time::Duration::from_millis(2000);
+///
+/// ⚠ Taken from core, NOT a local number. `FLUSH_COOLDOWN` (the jump-to-live rate limit) is 2000 ms,
+/// and the host classifies a keyframe-recovery cadence by matching a cooldown's period ±10 % to
+/// decide WHICH client failure it is looking at. The two are opposites — "I have received nothing"
+/// versus "I am drowning in frames I cannot drain" — so while this was also 2000 ms the host
+/// confidently reported the wrong one, and a black-screen field case was diagnosed as a slow decoder
+/// for days (2026-08-20). Keeping the value in core is what stops the two drifting back together.
+const NO_VIDEO_RETRY: std::time::Duration = punktfunk_core::client::NO_VIDEO_RETRY;
 
 /// Whether low-latency mode uses the event-driven async decode loop (default) or the synchronous
 /// poll loop. Flip to `false` to A/B the two on the HUD (`design/…`); the async loop presents a
@@ -133,12 +140,12 @@ pub(crate) struct DecodeOptions {
     /// named here is not necessarily the one the panel ends up in. The measured timeline spacing
     /// corrects it in both directions ([`punktfunk_core::phase::PanelGrid`]).
     pub panel_hz: i32,
-    /// The video `SurfaceView`'s on-screen pixel size (the aspect-fitted display footprint), from
-    /// Kotlin at `surfaceCreated`. The ASurfaceControl backend composites its layer in this
-    /// coordinate space — NOT the window's buffer geometry, which is rotated/scaled. `0` = Kotlin
-    /// couldn't read it yet, and the backend falls back to the window buffer size.
-    pub surface_w: i32,
-    pub surface_h: i32,
+    /// The video `SurfaceView`'s LIVE on-screen pixel size (the aspect-fitted display footprint),
+    /// packed by [`crate::session::pack_surface_size`] and re-reported by Kotlin on every
+    /// `surfaceChanged`. The ASurfaceControl backend composites its layer in this coordinate space
+    /// — NOT the window's buffer geometry, which is rotated/scaled. `0` = Kotlin couldn't read it
+    /// yet, and the backend falls back to the window buffer size.
+    pub surface_size: std::sync::Arc<std::sync::atomic::AtomicU64>,
 }
 
 /// The decode entry point on the `pf-decode` thread: dispatches to the async or synchronous loop.

clients/android/native/src/decode/surface_control.rs

@@ -24,6 +24,7 @@ use ndk::hardware_buffer::HardwareBuffer;
 use ndk::native_window::NativeWindow;
 use std::ffi::c_void;
 use std::os::fd::{FromRawFd, OwnedFd, RawFd};
+use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::{mpsc, Arc};
 
 use super::async_loop::DecodeEvent;
@@ -276,9 +277,14 @@ unsafe extern "C" fn on_complete(context: *mut c_void, stats: *mut ASurfaceTrans
 pub(super) struct Layer {
     api: Api,
     sc: Arc<ScHandle>,
-    /// Destination rectangle (the SurfaceView's pixel size) — the buffer is scaled to fill it.
-    dest_w: i32,
-    dest_h: i32,
+    /// The SurfaceView's LIVE pixel size, packed by `pack_surface_size` and re-read before every
+    /// present — the destination rectangle the buffer is scaled to fill. Live rather than captured
+    /// because the view resizes under a surface that is never recreated (see `dest`).
+    surface_size: Arc<AtomicU64>,
+    /// Fallback destination for as long as `surface_size` is still `0` (Kotlin hadn't measured the
+    /// view when video started): the window's own buffer geometry, the best remaining guess.
+    fallback_w: i32,
+    fallback_h: i32,
     /// `true` once the first transaction has made the layer visible + set its z-order + frame rate.
     configured: bool,
 }
@@ -287,13 +293,16 @@ impl Layer {
     /// Create the compositor layer over `window` (the SurfaceView's `ANativeWindow`), or `None` on
     /// API < 29 / a null layer — the caller then uses the SurfaceView presenter.
     ///
-    /// `dest_w/h` are the SurfaceView's **on-screen pixel size** — the coordinate space the child
-    /// layer is composited into, which is the display footprint of the (aspect-fitted) video view,
-    /// NOT the window's buffer size. `ANativeWindow_getWidth/Height` return the buffer geometry in a
-    /// rotated/scaled space (observed 1260×567 for a 2800×1260 full-bleed stream) — using it shrank
-    /// the picture to the top-left corner. A non-positive `dest_w/h` (Kotlin couldn't read the view
-    /// yet) falls back to that buffer size as the best remaining guess.
-    pub(super) fn create(window: &NativeWindow, dest_w: i32, dest_h: i32) -> Option<Layer> {
+    /// `surface_size` carries the SurfaceView's **on-screen pixel size** — the coordinate space the
+    /// child layer is composited into, which is the display footprint of the (aspect-fitted) video
+    /// view, NOT the window's buffer size. `ANativeWindow_getWidth/Height` return the buffer
+    /// geometry in a rotated/scaled space (observed 1260×567 for a 2800×1260 full-bleed stream) —
+    /// using it shrank the picture to the top-left corner. It is read fresh on every present
+    /// because that view RESIZES mid-stream under a surface that is never recreated: the stream
+    /// screen hides the system bars and switches on cutout drawing a frame or two after
+    /// `surfaceCreated`, and each one grows it. An empty `surface_size` (Kotlin hadn't measured the
+    /// view yet) falls back to the buffer size as the best remaining guess.
+    pub(super) fn create(window: &NativeWindow, surface_size: Arc<AtomicU64>) -> Option<Layer> {
         let api = Api::resolve()?;
         // SAFETY: `window.ptr()` is the live `ANativeWindow` the decode thread owns; the name is a
         // static NUL-terminated string; the call returns null on failure (checked).
@@ -303,20 +312,11 @@ impl Layer {
             log::warn!("asc: createFromWindow returned null — falling back to SurfaceView");
             return None;
         }
-        let dest_w = if dest_w > 0 {
-            dest_w
-        } else {
-            window.width().max(1)
-        };
-        let dest_h = if dest_h > 0 {
-            dest_h
-        } else {
-            window.height().max(1)
-        };
+        let fallback_w = window.width().max(1);
+        let fallback_h = window.height().max(1);
         log::info!(
-            "asc: layer created, dest {dest_w}x{dest_h} (window buffer {}x{})",
-            window.width(),
-            window.height(),
+            "asc: layer created, dest {:?} (window buffer {fallback_w}x{fallback_h})",
+            crate::session::unpack_surface_size(surface_size.load(Ordering::Relaxed)),
         );
         Some(Layer {
             sc: Arc::new(ScHandle {
@@ -324,12 +324,20 @@ impl Layer {
                 release: api.ac_release,
             }),
             api,
-            dest_w,
-            dest_h,
+            surface_size,
+            fallback_w,
+            fallback_h,
             configured: false,
         })
     }
 
+    /// The destination rectangle for this present: the live view size, or the window's buffer
+    /// geometry while Kotlin has reported nothing.
+    fn dest(&self) -> (i32, i32) {
+        crate::session::unpack_surface_size(self.surface_size.load(Ordering::Relaxed))
+            .unwrap_or((self.fallback_w, self.fallback_h))
+    }
+
     /// Present one decoded buffer at `desired_present_ns` (`CLOCK_MONOTONIC`; `0` = ASAP). Consumes
     /// `acquire_fence` (ownership passes to SurfaceFlinger via `setBuffer`). Registers a one-shot
     /// completion that reports the real latch + the previous buffer's release fence on `ev_tx`,
@@ -370,11 +378,12 @@ impl Layer {
                 right: src_w.max(1),
                 bottom: src_h.max(1),
             };
+            let (dest_w, dest_h) = self.dest();
             let dst = ARect {
                 left: 0,
                 top: 0,
-                right: self.dest_w,
-                bottom: self.dest_h,
+                right: dest_w,
+                bottom: dest_h,
             };
             (self.api.txn_set_geometry)(txn, sc, &src, &dst, TRANSFORM_IDENTITY);
             if dataspace != 0 {

clients/android/native/src/decode/sync_loop.rs

@@ -50,8 +50,7 @@ pub(super) fn run_sync(
         panel_hz: _,
         // The ASurfaceControl backend is async-loop only; the sync loop renders straight to the
         // SurfaceView, so it never needs the view's on-screen size.
-        surface_w: _,
-        surface_h: _,
+        surface_size: _,
     } = opts;
     boost_thread_priority();
     let mode = client.mode();

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

@@ -470,6 +470,8 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
                 // A fresh session is never muted (mute is per-session UI state, not a setting).
                 mic_muted: Arc::new(std::sync::atomic::AtomicBool::new(false)),
                 access_seq: std::sync::atomic::AtomicU32::new(0),
+                // Reported by Kotlin at `surfaceCreated` and on every resize after it.
+                surface_size: Arc::new(std::sync::atomic::AtomicU64::new(0)),
             };
             Box::into_raw(Box::new(handle)) as jlong
         }

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

@@ -26,7 +26,7 @@ mod probe;
 
 use punktfunk_core::client::NativeClient;
 use std::panic::AssertUnwindSafe;
-use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, Ordering};
 use std::sync::{Arc, Mutex};
 use std::thread::JoinHandle;
 
@@ -87,6 +87,37 @@ pub(crate) struct SessionHandle {
     /// `nativeAccessState` poll ([`access`]) — how the Kotlin poller tells a fresh update
     /// (the host's expiry warnings) arrived without holding a blocking event thread.
     pub(crate) access_seq: AtomicU32,
+    /// The video `SurfaceView`'s LIVE on-screen pixel size ([`pack_surface_size`]), written by
+    /// `nativeStartVideo` and by every `nativeVideoSurfaceSize` the `surfaceChanged` callback
+    /// sends, read by the ASurfaceControl presenter before each present.
+    ///
+    /// Shared and live rather than a start-time parameter because the view RESIZES under a surface
+    /// that is never recreated: hiding the system bars and switching the window to
+    /// `LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS` both happen a frame or two AFTER `surfaceCreated`,
+    /// and each one grows the video view. A destination rect captured once at creation then keeps
+    /// compositing the picture at its old, smaller size anchored at the layer's origin — the
+    /// "stream in the top-left corner" field report. `0` = nothing reported yet, and the layer
+    /// falls back to the window's buffer geometry.
+    pub surface_size: Arc<AtomicU64>,
+}
+
+/// Pack a surface's pixel size into one `u64` — so the presenter reads width and height as a
+/// single atomic load and can never see a torn pair (a new width against an old height).
+/// Non-positive values pack as `0`, the "not reported yet" sentinel.
+pub(crate) fn pack_surface_size(w: i32, h: i32) -> u64 {
+    if w <= 0 || h <= 0 {
+        return 0;
+    }
+    ((w as u64) << 32) | (h as u64 & 0xffff_ffff)
+}
+
+/// The inverse of [`pack_surface_size`]: `None` for the `0` sentinel.
+#[cfg_attr(not(target_os = "android"), allow(dead_code))]
+pub(crate) fn unpack_surface_size(packed: u64) -> Option<(i32, i32)> {
+    if packed == 0 {
+        return None;
+    }
+    Some((((packed >> 32) as u32) as i32, (packed as u32) as i32))
 }
 
 struct VideoThread {
@@ -160,3 +191,29 @@ fn parse_hex32(s: &str) -> Option<[u8; 32]> {
     }
     Some(out)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{pack_surface_size, unpack_surface_size};
+
+    /// The pair the presenter reads as one atomic load must survive the round trip — including a
+    /// size wider than a signed 16-bit value, which every panel this runs on now is.
+    #[test]
+    fn surface_size_round_trips() {
+        assert_eq!(
+            unpack_surface_size(pack_surface_size(2800, 1260)),
+            Some((2800, 1260))
+        );
+        assert_eq!(unpack_surface_size(pack_surface_size(1, 1)), Some((1, 1)));
+    }
+
+    /// "Not reported yet" — and anything nonsensical — is the one sentinel, so the layer falls back
+    /// to the window's buffer geometry rather than composing into an empty rectangle.
+    #[test]
+    fn non_positive_sizes_are_the_sentinel() {
+        assert_eq!(pack_surface_size(0, 0), 0);
+        assert_eq!(pack_surface_size(1920, 0), 0);
+        assert_eq!(pack_surface_size(-1, 1080), 0);
+        assert_eq!(unpack_surface_size(0), None);
+    }
+}

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

@@ -72,6 +72,13 @@ 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)
+
+        // Seed the live view size with what the view measures right now; `surfaceChanged` keeps it
+        // current from here on (the bars hide and the cutout mode changes AFTER this call).
+        h.surface_size.store(
+            super::pack_surface_size(surface_w, surface_h),
+            std::sync::atomic::Ordering::Relaxed,
+        );
         let opts = crate::decode::DecodeOptions {
             decoder_name: decoder,
             ll_feature,
@@ -80,8 +87,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
             present_priority,
             smooth_buffer,
             panel_hz: panel_fps,
-            surface_w,
-            surface_h,
+            surface_size: h.surface_size.clone(),
         };
         let join = std::thread::Builder::new()
             .name("pf-decode".into())
@@ -93,6 +99,37 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
     .resolve::<LogErrorAndDefault>()
 }
 
+/// `NativeBridge.nativeVideoSurfaceSize(handle, width, height)` — the video `SurfaceView`'s
+/// on-screen pixel size, re-reported on every `surfaceChanged`.
+///
+/// The ASurfaceControl presenter composites its child layer into exactly this rectangle, and the
+/// view resizes UNDER a surface that is never recreated: the stream screen hides the system bars
+/// and asks to draw into the display cutout a frame or two after `surfaceCreated`, both of which
+/// grow it. Without this the layer would keep painting the picture at its start-up size, in the
+/// corner of a bigger surface. Non-positive values are ignored (they'd blank the picture).
+/// No-op on a `0` handle. Stored whether or not video is running — the next `nativeStartVideo`
+/// then starts from a measured view rather than the window's guess. Not android-gated: pure `jni`
+/// + an atomic store, so it links on the host build too.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoSurfaceSize(
+    _env: EnvUnowned,
+    _this: JObject,
+    handle: jlong,
+    width: jni::sys::jint,
+    height: jni::sys::jint,
+) {
+    jni_guard((), || {
+        let packed = super::pack_surface_size(width, height);
+        if handle == 0 || packed == 0 {
+            return;
+        }
+        // SAFETY: live handle per the nativeConnect/nativeClose contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        h.surface_size
+            .store(packed, std::sync::atomic::Ordering::Relaxed);
+    })
+}
+
 /// `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`].

clients/cli/src/main.rs

@@ -370,15 +370,26 @@ from the config directory for a true factory reset."
             .unwrap_or(DISCOVER_DEFAULT_SECS)
             .min(DISCOVER_MAX_SECS);
         let found = pf_client_core::discovery::discover_for(Duration::from_secs_f64(secs));
-        // `read`, not `load`: this verb only LOOKS at the records to annotate what it found, and
-        // never hands their ids back. `load` would mint ids for a pre-mint store and save them —
-        // a write from a read-only verb, and one that races the `hosts list` a caller is very
-        // likely running at the same moment (the Decky panel issues both together).
+        // `read`, not `load`: this verb never hands a record's id back, so it has no business
+        // MINTING one. `load` would mint ids for a pre-mint store and save them, racing the
+        // `hosts list` a caller is very likely running at the same moment (the Decky panel issues
+        // both together) — after which the ids one of them already handed out no longer resolve.
         let known = KnownHosts::read();
         let rows: Vec<(
             &pf_client_core::discovery::DiscoveredHost,
             Option<&KnownHost>,
         )> = found.iter().map(|d| (d, match_saved(&known, d))).collect();
+        // The one write this verb does make, and why it doesn't contradict the above: an advert
+        // is the only place a host's wake MAC is ever published, and this verb is the only one
+        // the Decky panel runs that ever sees one. Without it a Deck in Gaming Mode never learns
+        // a MAC at all and Wake-on-LAN cannot fire, with nothing to show for it (#322).
+        // `learn_from_advert` mints nothing either, and writes only when an advert genuinely
+        // taught the record something new — so a steady-state panel refresh touches no disk.
+        for (d, saved) in &rows {
+            if let Some(k) = saved {
+                trust::learn_from_advert(&k.fp_hex, &k.addr, k.port, &d.mac, &d.os, d.mgmt_port);
+            }
+        }
         if has(args, "--json") {
             let hosts: Vec<serde_json::Value> = rows
                 .iter()
@@ -733,7 +744,9 @@ from the config directory for a true factory reset."
         };
         let host = &known.hosts[i];
         if host.mac.is_empty() {
-            eprintln!("no Wake-on-LAN address known for {} — connect to it once while it's awake so the client can learn it", host.name);
+            // A MAC is learned from the host's mDNS advert, never from a connect — say so, since
+            // "connect to it once" sent at least one Deck owner looking in the wrong place (#322).
+            eprintln!("no Wake-on-LAN address known for {} — run `punktfunk discover` while it's awake (the Deck panel does this every time it opens) so the client learns it from the host's advert", host.name);
             return UNRESOLVED;
         }
         if !has(args, "--wait") {

clients/linux/src/ui_hosts.rs

@@ -1087,33 +1087,20 @@ impl HostsPage {
                 // Online = advertising on mDNS OR proven reachable by the last probe sweep.
                 let online = self.adverts.values().any(|a| matches(k, a))
                     || self.probed.get(&saved_key(k)).copied().unwrap_or(false);
-                // Learn this host's wake MAC(s) from its live advert while it's online.
-                if let Some(a) = self
-                    .adverts
-                    .values()
-                    .find(|a| matches(k, a) && !a.mac.is_empty())
-                {
-                    crate::trust::learn_mac(&k.fp_hex, &k.addr, k.port, &a.mac);
-                }
-                // Same for its OS chain — the icon then survives the host going offline.
-                if let Some(a) = self
-                    .adverts
-                    .values()
-                    .find(|a| matches(k, a) && !a.os.is_empty())
-                {
-                    crate::trust::learn_os(&k.fp_hex, &k.addr, k.port, &a.os);
-                }
-                // Same for its management port — and this one is not cosmetic: without it a host
-                // that moved off 47990 loses its library the moment mDNS is unavailable, because
-                // the advert was the only place the real port ever lived.
-                if let Some(a) = self
-                    .adverts
-                    .values()
-                    .find(|a| matches(k, a) && a.mgmt_port.is_some())
-                {
-                    if let Some(p) = a.mgmt_port {
-                        crate::trust::learn_mgmt_port(&k.fp_hex, &k.addr, k.port, p);
-                    }
+                // Learn what this host's live advert teaches while it's online: its wake MAC(s),
+                // its OS chain (so the icon survives it going offline), and its management port
+                // — the last one not cosmetic, since a host that moved off 47990 loses its
+                // library the moment mDNS is unavailable and the advert is the only place the
+                // real port ever lived.
+                if let Some(a) = self.adverts.values().find(|a| matches(k, a)) {
+                    crate::trust::learn_from_advert(
+                        &k.fp_hex,
+                        &k.addr,
+                        k.port,
+                        &a.mac,
+                        &a.os,
+                        a.mgmt_port,
+                    );
                 }
                 saved.push_back(HostCard {
                     connecting: self.connecting.as_deref() == Some(k.fp_hex.as_str()),

clients/probe/src/main.rs

@@ -53,9 +53,9 @@ use punktfunk_core::config::Role;
 use punktfunk_core::input::{InputEvent, InputKind};
 use punktfunk_core::packet::FLAG_PROBE;
 use punktfunk_core::quic::{
-    endpoint, io, window_loss_ppm, BitrateChanged, CursorRenderMode, Hello, LossReport,
-    ProbeRequest, ProbeResult, Reconfigure, Reconfigured, RequestKeyframe, SetBitrate, Start,
-    Welcome,
+    endpoint, io, window_loss_ppm, BitrateChanged, CursorRenderMode, DeliveryReport, Hello,
+    LossReport, ProbeRequest, ProbeResult, Reconfigure, Reconfigured, RequestKeyframe, SetBitrate,
+    Start, Welcome,
 };
 use punktfunk_core::transport::UdpTransport;
 use punktfunk_core::{CompositorPref, Mode, PunktfunkError, Session};
@@ -987,10 +987,18 @@ async fn session(args: Args) -> Result<()> {
         let mut ls = send;
         let lp = loss_ppm.clone();
         let df = dropped_frames.clone();
+        // Delivery truth for the host's dead-data-plane check: report what actually landed on the
+        // wire, so the probe reproduces a real client's answer rather than the "cannot answer"
+        // sentinel — which is exactly what makes it usable for testing that path.
+        let rxp = rx_wire_packets.clone();
         tokio::spawn(async move {
             use std::sync::atomic::Ordering::Relaxed;
             let mut last_report = std::time::Instant::now();
             let mut last_dropped = 0u64;
+            // Mirrors the real clients' rule (see `pump/data.rs`): report the delivery count every
+            // window while it is zero, once when the first packets land, then stop — so a host that
+            // predates the message is not flooded with "unknown control message" on a good session.
+            let mut delivery_confirmed = false;
             loop {
                 tokio::time::sleep(std::time::Duration::from_millis(100)).await;
                 let d = df.load(Relaxed);
@@ -1007,6 +1015,25 @@ async fn session(args: Args) -> Result<()> {
                 if last_report.elapsed() >= std::time::Duration::from_millis(750) {
                     last_report = std::time::Instant::now();
                     let v = lp.swap(u32::MAX, Relaxed);
+                    // Independent of whether there is a fresh loss sample: "no fresh sample" is
+                    // exactly the shape a dead data plane has, so gating it on one would silence
+                    // it in the state it exists to report.
+                    let received = rxp.load(Relaxed);
+                    if received == 0 || !delivery_confirmed {
+                        delivery_confirmed = received > 0;
+                        if io::write_msg(
+                            &mut ls,
+                            &DeliveryReport {
+                                packets_received: received,
+                            }
+                            .encode(),
+                        )
+                        .await
+                        .is_err()
+                        {
+                            break; // control stream gone
+                        }
+                    }
                     if v != u32::MAX
                         && io::write_msg(&mut ls, &LossReport { loss_ppm: v }.encode())
                             .await

clients/session/src/console.rs

@@ -800,11 +800,21 @@ impl ServiceState {
                         || (d.addr == h.addr && d.port == h.port)
                 });
                 let online = advert.is_some() || probed.get(&key).copied().unwrap_or(false);
-                // Write the advertised mgmt port down while the host is visible, so this console
-                // keeps working against a moved port once it is not. No-op (and no disk write)
+                // Write down everything the advert teaches while the host is visible: the mgmt
+                // port (so this console keeps working against a moved one once it is not), the
+                // OS chain, and the wake MAC — which matters most here, because this console and
+                // the Decky panel are the only surfaces a Deck in Gaming Mode ever runs, and a
+                // record that never learned a MAC can never be woken. No-op (and no disk write)
                 // when unchanged, so this is safe on every refresh tick.
-                if let Some(p) = advert.and_then(|d| d.mgmt_port) {
-                    pf_client_core::trust::learn_mgmt_port(&h.fp_hex, &h.addr, h.port, p);
+                if let Some(a) = advert {
+                    pf_client_core::trust::learn_from_advert(
+                        &h.fp_hex,
+                        &h.addr,
+                        h.port,
+                        &a.mac,
+                        &a.os,
+                        a.mgmt_port,
+                    );
                 }
                 let row = HostRow {
                     key: key.clone(),

clients/windows/src/app/hosts.rs

@@ -700,31 +700,23 @@ pub(crate) fn hosts_page(props: &HostsProps, cx: &mut RenderCx) -> Element {
                 .iter()
                 .any(|h| h.fp_hex == k.fp_hex || (h.addr == k.addr && h.port == k.port))
                 || props.probed.get(&k.fp_hex).copied().unwrap_or(false);
-            // Learn this host's wake MAC(s) from its live advert while it's online, so we can wake
-            // it once it sleeps (no-op / no disk write when unchanged).
-            if let Some(a) = hosts.iter().find(|h| {
-                (h.fp_hex == k.fp_hex || (h.addr == k.addr && h.port == k.port))
-                    && !h.mac.is_empty()
-            }) {
-                crate::trust::learn_mac(&k.fp_hex, &k.addr, k.port, &a.mac);
-            }
-            // Same for its OS chain — the tile's mark then survives the host going offline.
-            if let Some(a) = hosts.iter().find(|h| {
-                (h.fp_hex == k.fp_hex || (h.addr == k.addr && h.port == k.port)) && !h.os.is_empty()
-            }) {
-                crate::trust::learn_os(&k.fp_hex, &k.addr, k.port, &a.os);
-            }
-            // Same for its management port — load-bearing, unlike the two above: a host moved off
-            // 47990 loses its library entirely once mDNS is gone unless we write the port down.
-            if let Some(p) = hosts
+            // Learn what this host's live advert teaches while it's online: its wake MAC(s) (so we
+            // can wake it once it sleeps), its OS chain (so the tile's mark survives it going
+            // offline), and its management port — the last load-bearing rather than cosmetic, as
+            // a host moved off 47990 loses its library entirely once mDNS is gone unless we write
+            // the port down. No-op, and no disk write, when unchanged.
+            if let Some(a) = hosts
                 .iter()
-                .find(|h| {
-                    (h.fp_hex == k.fp_hex || (h.addr == k.addr && h.port == k.port))
-                        && h.mgmt_port.is_some()
-                })
-                .and_then(|h| h.mgmt_port)
+                .find(|h| h.fp_hex == k.fp_hex || (h.addr == k.addr && h.port == k.port))
             {
-                crate::trust::learn_mgmt_port(&k.fp_hex, &k.addr, k.port, p);
+                crate::trust::learn_from_advert(
+                    &k.fp_hex,
+                    &k.addr,
+                    k.port,
+                    &a.mac,
+                    &a.os,
+                    a.mgmt_port,
+                );
             }
             let can_wake = !online && !k.mac.is_empty();
             let menu = {

clients/windows/src/discovery.rs

@@ -29,7 +29,7 @@ pub struct DiscoveredHost {
     /// persisted like `mac`. Empty if absent (older host).
     pub os: String,
     /// The management API's port from the mDNS `mgmt` TXT — where the game library is served.
-    /// Persisted like `mac` (`trust::learn_mgmt_port`), and load-bearing rather than cosmetic:
+    /// Persisted like `mac` (`trust::learn_from_advert`), and load-bearing rather than cosmetic:
     /// a host moved off 47990 loses its library once mDNS is gone unless we write this down.
     /// `None` if absent (older host) — resolve via `library::DEFAULT_MGMT_PORT`.
     pub mgmt_port: Option<u16>,

clients/windows/src/trust.rs

@@ -8,6 +8,6 @@
 //! still load via a serde alias in core.
 
 pub use pf_client_core::trust::{
-    hex, learn_mac, learn_mgmt_port, learn_os, load_or_create_identity, pair_error_message,
-    parse_hex32, KnownHost, KnownHosts, Settings,
+    hex, learn_from_advert, load_or_create_identity, pair_error_message, parse_hex32, KnownHost,
+    KnownHosts, Settings,
 };

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

@@ -675,10 +675,10 @@ pub fn forget_placeholder(addr: &str, port: u16) {
     }
 }
 
-/// The record [`learn_mac`]/[`learn_os`] should write what an advert taught them onto:
-/// the fingerprint match if there is one, else whatever the address resolves to. Fingerprint
-/// FIRST — a single pass that took "either" would hand a stale record at the same address the
-/// data the live host advertised, purely because it came earlier in the file.
+/// The record an advert's lesson should land on: the fingerprint match if there is one, else
+/// whatever the address resolves to. Fingerprint FIRST — a single pass that took "either" would
+/// hand a stale record at the same address the data the live host advertised, purely because it
+/// came earlier in the file.
 fn learn_target<'a>(
     known: &'a mut KnownHosts,
     fp_hex: &str,
@@ -692,61 +692,62 @@ fn learn_target<'a>(
     known.hosts.get_mut(i)
 }
 
-/// Learn/refresh a saved host's Wake-on-LAN MAC(s) from its live advert (called while the host
-/// is online, matched by fingerprint or address). No-op — and no disk write — when unchanged, so
-/// the hosts page can call it on every discovery tick without churning the store.
-pub fn learn_mac(fp_hex: &str, addr: &str, port: u16, mac: &[String]) {
-    if mac.is_empty() {
-        return;
-    }
-    let mut known = KnownHosts::load();
-    let Some(h) = learn_target(&mut known, fp_hex, addr, port) else {
-        return;
-    };
-    if h.mac == mac {
-        return;
-    }
-    h.mac = mac.to_vec();
-    let _ = known.save();
-}
-
-/// Learn/refresh a saved host's OS-identity chain from its live advert (mDNS `os` TXT), matched
-/// like [`learn_mac`]: by fingerprint or address. No-op — and no disk write — when unchanged, so
-/// the hosts page can call it on every discovery tick without churning the store.
-pub fn learn_os(fp_hex: &str, addr: &str, port: u16, os: &str) {
-    if os.is_empty() {
-        return;
-    }
-    let mut known = KnownHosts::load();
-    let Some(h) = learn_target(&mut known, fp_hex, addr, port) else {
-        return;
-    };
-    if h.os == os {
-        return;
-    }
-    h.os = os.to_string();
-    let _ = known.save();
-}
-
-/// Learn/refresh a saved host's management-API port from its live advert (mDNS `mgmt` TXT),
-/// matched like [`learn_mac`]: by fingerprint or address. No-op — and no disk write — when
-/// unchanged, so the hosts page can call it on every discovery tick without churning the store.
+/// Copy everything an advert can teach onto a saved record — wake MAC(s), OS-identity chain,
+/// management port — and report whether anything actually moved, so the caller writes only when
+/// there is something to write. Pure (no disk, no clock), which is what makes it testable.
 ///
-/// This is what makes a moved mgmt port outlive mDNS. Until it existed the port was read straight
-/// off the live advert and thrown away, so the library worked on the LAN and went blank over a VPN.
-pub fn learn_mgmt_port(fp_hex: &str, addr: &str, port: u16, mgmt_port: u16) {
-    if mgmt_port == 0 {
-        return;
+/// A field the advert does not carry is left alone, never cleared: an older host simply omits the
+/// TXT, and forgetting a MAC already learned would cost the user their wake.
+fn apply_advert(h: &mut KnownHost, mac: &[String], os: &str, mgmt_port: Option<u16>) -> bool {
+    let mut changed = false;
+    if !mac.is_empty() && h.mac != mac {
+        h.mac = mac.to_vec();
+        changed = true;
     }
-    let mut known = KnownHosts::load();
+    if !os.is_empty() && h.os != os {
+        h.os = os.to_string();
+        changed = true;
+    }
+    // 0 is how "not advertised" reaches us from a caller whose own type has no `Option`.
+    if mgmt_port.is_some_and(|p| p != 0 && h.mgmt_port != Some(p)) {
+        h.mgmt_port = mgmt_port;
+        changed = true;
+    }
+    changed
+}
+
+/// Write down everything a live advert teaches the saved record it matched — wake MAC(s), OS
+/// chain, management port — matched by fingerprint or address. No-op, and no disk write, when
+/// the record already says all three, so a surface can call this on every discovery tick.
+///
+/// ONE call rather than three. Each field used to be learned by its own function, which meant
+/// every front-end had to remember all three, and only the two desktop hosts pages ever did:
+/// the console home and the headless CLI learned the management port alone. On a Steam Deck,
+/// whose Gaming Mode runs nothing but those two, that left every saved host with no MAC forever
+/// — and every wake gate in the codebase reads `!mac.is_empty()` against this record, so
+/// Wake-on-LAN there could not fire at all, with no error to show for it (#322).
+///
+/// [`KnownHosts::read`], not [`KnownHosts::load`]: `punktfunk discover` calls this, and that verb
+/// is deliberately not an id-minter (see [`KnownHosts::read`] for the race that avoids). Learning
+/// a MAC is no reason to become one.
+///
+/// Takes the three learned fields rather than a `DiscoveredHost` because there are two of those
+/// — core's and the WinUI shell's verbatim port — and this has to serve both.
+pub fn learn_from_advert(
+    fp_hex: &str,
+    addr: &str,
+    port: u16,
+    mac: &[String],
+    os: &str,
+    mgmt_port: Option<u16>,
+) {
+    let mut known = KnownHosts::read();
     let Some(h) = learn_target(&mut known, fp_hex, addr, port) else {
         return;
     };
-    if h.mgmt_port == Some(mgmt_port) {
-        return;
+    if apply_advert(h, mac, os, mgmt_port) {
+        let _ = known.save();
     }
-    h.mgmt_port = Some(mgmt_port);
-    let _ = known.save();
 }
 
 /// Re-key a saved host's address/port after it rediscovered on a new DHCP lease (matched by
@@ -785,7 +786,7 @@ pub fn touch_last_used(fp_hex: &str) {
 /// Save a host's management-API port learned from the **session's own `Welcome`**, keyed by
 /// fingerprint alone — the identity a just-connected client is certain of.
 ///
-/// This is the mDNS-free path, and the one that matters most: [`learn_mgmt_port`] can only fire
+/// This is the mDNS-free path, and the one that matters most: [`learn_from_advert`] can only fire
 /// where an advert is visible, whereas this fires on any successful connect, including a host
 /// added by IP on a network where discovery has never worked. No-op — and no disk write — when
 /// the fingerprint isn't stored or the value is unchanged, so it is safe on every connect.
@@ -2293,6 +2294,33 @@ mod tests {
         assert!(learn_target(&mut k, &fp('e'), "10.0.0.9", 9777).is_none());
     }
 
+    /// What an advert carries lands on the record; what it omits is left alone; and a repeat of
+    /// the same advert reports no change — which is what lets every surface call this on every
+    /// discovery tick without churning the store.
+    #[test]
+    fn apply_advert_learns_what_it_carries_and_keeps_what_it_omits() {
+        let mut h = KnownHost::default();
+        let mac = vec!["aa:bb:cc:dd:ee:ff".to_string()];
+        assert!(apply_advert(&mut h, &mac, "linux/arch", Some(47991)));
+        assert_eq!(h.mac, mac);
+        assert_eq!(h.os, "linux/arch");
+        assert_eq!(h.mgmt_port, Some(47991));
+        // The same advert a tick later: nothing moved, so there is nothing to persist.
+        assert!(!apply_advert(&mut h, &mac, "linux/arch", Some(47991)));
+        // An older host advertises none of the three. Clearing a learned MAC here is exactly what
+        // would cost the user their wake, so an absent field must never overwrite a known one.
+        assert!(!apply_advert(&mut h, &[], "", None));
+        assert_eq!(h.mac, mac);
+        assert_eq!(h.os, "linux/arch");
+        assert_eq!(h.mgmt_port, Some(47991));
+        // 0 is how "not advertised" reaches us from a consumer that has no Option — not a port.
+        assert!(!apply_advert(&mut h, &[], "", Some(0)));
+        assert_eq!(h.mgmt_port, Some(47991));
+        // A host that genuinely moved: the new value wins.
+        assert!(apply_advert(&mut h, &[], "", Some(47992)));
+        assert_eq!(h.mgmt_port, Some(47992));
+    }
+
     /// Pins render in card order, deduplicated, with deleted profiles simply gone — a pin is
     /// presentation state, so a dangling one is never an error surface.
     #[test]

crates/pf-console-ui/src/glyphs.rs

@@ -148,6 +148,10 @@ pub(crate) enum HintKey {
     /// there isn't (the library grid spends up on rows) the same menu hangs off
     /// [`HintKey::Tertiary`] instead; the button differs, the word "Options" does not.
     Up,
+    /// ▼ — the home carousel's other spare direction, which opens Settings. Advertised in
+    /// place of [`HintKey::Tertiary`] where no pad is attached, because that is exactly the
+    /// device that has no X to press: a TV remote is a D-pad, OK and Back.
+    Down,
     Key(&'static str),
 }
 
@@ -272,7 +276,7 @@ fn glyph_width(fonts: &Fonts, key: HintKey, style: GlyphStyle, k: f64) -> f64 {
     match resolved(key, style) {
         Resolved::Badge(_) | Resolved::Adjust => BADGE_D * k,
         Resolved::Shoulders => 2.0 * shoulder_w(fonts, k) + 3.0 * k,
-        Resolved::Up => BADGE_D * k,
+        Resolved::Up | Resolved::Down => BADGE_D * k,
         Resolved::Key(text) => keycap_w(fonts, text, k),
     }
 }
@@ -294,6 +298,9 @@ enum Resolved {
     /// The d-pad's up — drawn the same in every style, because it is a direction rather
     /// than a button whose label changes with the pad.
     Up,
+    /// The d-pad's down — the same triangle stood on its head, and style-free for the
+    /// same reason [`Resolved::Up`] is.
+    Down,
     Key(&'static str),
 }
 
@@ -317,6 +324,7 @@ fn resolved(key: HintKey, style: GlyphStyle) -> Resolved {
             HintKey::Shoulders => Resolved::Key("Tab"),
             HintKey::Adjust => Resolved::Adjust,
             HintKey::Up => Resolved::Up,
+            HintKey::Down => Resolved::Down,
             HintKey::Key(t) => Resolved::Key(t),
         };
     }
@@ -327,6 +335,7 @@ fn resolved(key: HintKey, style: GlyphStyle) -> Resolved {
         HintKey::Secondary => Resolved::Badge(Face::Y),
         HintKey::Shoulders => Resolved::Shoulders,
         HintKey::Adjust => Resolved::Adjust,
+        HintKey::Down => Resolved::Down,
         HintKey::Up => Resolved::Up,
         HintKey::Key(t) => Resolved::Key(t),
     }
@@ -394,17 +403,23 @@ fn draw_glyph(
                 pen += w + 3.0 * k;
             }
         }
-        Resolved::Up => {
-            // ▲ — one solid triangle in a badge-sized slot.
+        g @ (Resolved::Up | Resolved::Down) => {
+            // ▲ / ▼ — one solid triangle in a badge-sized slot, the same triangle either
+            // way up: apex toward the direction it names, base at the other end.
             let r = BADGE_D * k / 2.0;
             let (cx, cyf) = ((x + r) as f32, cy as f32);
             let (tw, th) = ((5.5 * k) as f32, (4.5 * k) as f32);
-            let mut up = PathBuilder::new();
-            up.move_to((cx, cyf - th));
-            up.line_to((cx - tw, cyf + th));
-            up.line_to((cx + tw, cyf + th));
-            up.close();
-            canvas.draw_path(&up.detach(), &fill(fg(0.85)));
+            let (apex, base) = if matches!(g, Resolved::Down) {
+                (cyf + th, cyf - th)
+            } else {
+                (cyf - th, cyf + th)
+            };
+            let mut tri = PathBuilder::new();
+            tri.move_to((cx, apex));
+            tri.line_to((cx - tw, base));
+            tri.line_to((cx + tw, base));
+            tri.close();
+            canvas.draw_path(&tri.detach(), &fill(fg(0.85)));
         }
         Resolved::Adjust => {
             // ◀ ▶ — two small solid triangles.

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

@@ -63,6 +63,10 @@ pub(crate) struct Ctx<'a> {
     pub pads: &'a [PadInfo],
     /// Steam Deck: never draw our keyboard — Steam's types via SDL text input.
     pub deck: bool,
+    /// The host app has another interface to fall back to when the console is switched
+    /// off (an Android phone/tablet's touch shell) — see
+    /// [`crate::shell::ConsoleOptions::fallback_ui`]. Gates the console-off settings row.
+    pub fallback_ui: bool,
     /// The name the HOST stores this client under when pairing (the machine's
     /// hostname, resolved by the binary).
     pub device_name: &'a str,

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

@@ -396,6 +396,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads,
             deck,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         }

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

@@ -255,6 +255,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -301,6 +302,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -323,6 +325,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };

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

@@ -941,6 +941,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &[],
             deck: false,
+            fallback_ui: false,
             device_name: "test",
             t: 0.0,
         };

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

@@ -378,6 +378,7 @@ mod tests {
             platform,
             pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -429,6 +430,7 @@ mod tests {
                 platform,
                 pads,
                 deck: false,
+                fallback_ui: false,
                 device_name: "t",
                 t: 0.0,
             }

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

@@ -206,7 +206,17 @@ impl HomeScreen {
                 }
                 _ => Some(MenuPulse::Boundary),
             },
-            MenuEvent::Move(_) => None,
+            // Down is Settings — the same screen X opens. The carousel is horizontal, so
+            // down is the other free direction, and it is the only route to Settings on a
+            // device whose input has no face buttons: an Android TV remote is a D-pad, OK
+            // and Back, and X never arrives. (Apple hit this on the Siri Remote too, and
+            // answered it by moving rows out to the ordinary Settings app.)
+            MenuEvent::Move(MenuDir::Down) => {
+                fx.push(Screen::Settings(super::settings::SettingsScreen::new(
+                    ctx.store,
+                )));
+                Some(MenuPulse::Confirm)
+            }
         }
     }
 
@@ -279,7 +289,15 @@ impl HomeScreen {
         {
             hints.push(Hint::new(HintKey::Up, "Options"));
         }
-        hints.push(Hint::new(HintKey::Tertiary, "Settings"));
+        // Name the route this device actually has. With no pad attached the legend is
+        // already speaking keyboard, and the one input that reaches here with neither a
+        // pad NOR letter keys is a TV remote — for which X is not a button that exists.
+        // Down opens Settings for everyone; only the advertisement changes.
+        hints.push(if ctx.pads.is_empty() {
+            Hint::new(HintKey::Down, "Settings")
+        } else {
+            Hint::new(HintKey::Tertiary, "Settings")
+        });
         hints.push(Hint::new(HintKey::Back, "Quit"));
         hints
     }
@@ -859,6 +877,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "test",
             t: 0.0,
         };
@@ -885,6 +904,67 @@ mod tests {
         ));
     }
 
+    /// Everything this screen offers must be reachable from a D-pad, OK and Back alone —
+    /// an Android TV remote has no face buttons, so Settings (X) and the options menu
+    /// would otherwise be unreachable there. Up is the menu, down is Settings, and the
+    /// legend names the direction rather than X when nothing is plugged in.
+    #[test]
+    fn a_remote_reaches_settings_and_options_without_face_buttons() {
+        let mut settings = ctx_settings();
+        let hosts = [host("paired", true, true, false)];
+        let pads: Vec<pf_client_core::menu_nav::PadInfo> = Vec::new();
+        let library = crate::library::LibraryShared::default();
+        let mut ctx = Ctx {
+            hosts: &hosts,
+            library: &library,
+            settings: &mut settings,
+            store: crate::store::file_store(),
+            platform: crate::platform::Platform::Android,
+            pads: &pads,
+            deck: false,
+            fallback_ui: true,
+            device_name: "test",
+            t: 0.0,
+        };
+        let mut s = HomeScreen::new();
+
+        // Down opens the same screen X opens.
+        let mut fx = Outbox::default();
+        s.menu(MenuEvent::Move(MenuDir::Down), &mut ctx, &mut fx);
+        assert!(
+            matches!(fx.nav, Some(crate::screens::Nav::Push(ref sc)) if matches!(**sc, Screen::Settings(_))),
+            "down must open Settings"
+        );
+        // Up still opens the host's own menu — the library hangs off that menu now.
+        let mut fx = Outbox::default();
+        s.menu(MenuEvent::Move(MenuDir::Up), &mut ctx, &mut fx);
+        assert!(
+            matches!(fx.nav, Some(crate::screens::Nav::Push(ref sc)) if matches!(**sc, Screen::HostOptions(_))),
+            "up must open the host options menu"
+        );
+        // With no pad the legend advertises the direction, not a button that isn't there.
+        assert!(
+            s.hints(&ctx).iter().any(|h| h.key == HintKey::Down),
+            "a padless device is told about down"
+        );
+        // With a pad it goes back to naming X, which is faster to press.
+        let pads = vec![pf_client_core::menu_nav::PadInfo {
+            name: "Pad".into(),
+            key: "045e:028e:Pad".into(),
+            pref: punktfunk_core::config::GamepadPref::Xbox360,
+            steam_virtual: false,
+            battery: None,
+            detail: "045E:028E · gamepad".into(),
+            forwarded: true,
+            rumble: false,
+        }];
+        ctx.pads = &pads;
+        assert!(
+            s.hints(&ctx).iter().any(|h| h.key == HintKey::Tertiary),
+            "a pad is told about X"
+        );
+    }
+
     /// A pinned card's A-press is a connect WITH its profile (one-off), titled so the
     /// connecting takeover says which settings are coming (§5.2a).
     #[test]
@@ -908,6 +988,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "test",
             t: 0.0,
         };
@@ -932,6 +1013,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "test",
             t: 0.0,
         };

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

@@ -2218,6 +2218,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &[],
             deck: false,
+            fallback_ui: false,
             device_name: "test",
             t: 0.0,
         }

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

@@ -34,6 +34,10 @@ use skia_safe::{Canvas, Rect};
 enum Action {
     Wake,
     SendLogs,
+    /// Open this host's game library — the same shelf the home carousel's Y opens, offered
+    /// here because Y is a face button and a TV remote has none. Saved-and-paired only,
+    /// exactly like that Y (an unpaired host has no shelf to fetch).
+    Library,
     CopyLink,
     Edit,
     /// Choose the profile the host's primary tile connects with (opens the
@@ -154,6 +158,12 @@ impl OptionsScreen {
         if host.paired && host.online {
             a.push(Action::SendLogs);
         }
+        // The shelf, on the same terms the carousel's Y offers it. Ahead of Copy link
+        // because it is the one row here that goes somewhere rather than acting on the
+        // host — and on a remote-only device it is the ONLY way to the library.
+        if host.paired && host.saved {
+            a.push(Action::Library);
+        }
         a.extend([
             Action::CopyLink,
             Action::Edit,
@@ -171,6 +181,7 @@ impl OptionsScreen {
         match a {
             Action::Wake => "Wake host".into(),
             Action::SendLogs => "Send logs to host".into(),
+            Action::Library => "Library".into(),
             Action::CopyLink => "Copy link".into(),
             Action::Edit => "Edit\u{2026}".into(),
             Action::BindProfile => "Default profile\u{2026}".into(),
@@ -234,7 +245,7 @@ impl OptionsScreen {
             ListMsg::Adjust(_) => Some(MenuPulse::Boundary),
             ListMsg::None => pulse,
             ListMsg::Activate => {
-                self.run(action, ctx.store, fx);
+                self.run(action, ctx, fx);
                 pulse
             }
         }
@@ -257,7 +268,8 @@ impl OptionsScreen {
         }
     }
 
-    fn run(&mut self, action: Action, store: &dyn crate::store::SettingsStore, fx: &mut Outbox) {
+    fn run(&mut self, action: Action, ctx: &Ctx, fx: &mut Outbox) {
+        let store = ctx.store;
         let key = self.host_key().to_string();
         match action {
             Action::Wake => {
@@ -289,6 +301,24 @@ impl OptionsScreen {
                 }
                 fx.pop();
             }
+            // Same two steps the home carousel's Y takes: ask for the shelf, then open it
+            // on the epoch read BEFORE the command drains, so the screen can tell its own
+            // fetch's titles from the ones already in the model. `replace`, not push — the
+            // menu has said its piece, and Back from the shelf belongs on the carousel
+            // rather than on a menu about the host you just left.
+            Action::Library => {
+                let host = self.host();
+                fx.cmds.push(ConsoleCmd::FetchLibrary {
+                    addr: host.addr.clone(),
+                    mgmt: host.mgmt_port,
+                    fp_hex: host.fp_hex.clone(),
+                });
+                let epoch = ctx.library.fetch_epoch();
+                fx.replace(Screen::Library(super::library::LibraryScreen::new(
+                    self.host(),
+                    epoch,
+                )));
+            }
             Action::Edit => fx.replace(Screen::AddHost(super::add_host::AddHostScreen::edit(
                 self.host(),
             ))),
@@ -407,6 +437,27 @@ mod tests {
     use crate::model::ProfileChip;
     use crate::screens::Nav;
 
+    /// Activate one row. `run` reads the store, and — for Library — the shared library's
+    /// fetch epoch; nothing else in this menu touches the context, so one throwaway is
+    /// enough for every action test here.
+    fn run_action(s: &mut OptionsScreen, action: Action, fx: &mut Outbox) {
+        let mut settings = pf_client_core::trust::Settings::default();
+        let library = crate::library::LibraryShared::default();
+        let ctx = Ctx {
+            hosts: &[],
+            library: &library,
+            settings: &mut settings,
+            store: crate::store::file_store(),
+            platform: crate::platform::Platform::Desktop,
+            pads: &[],
+            deck: false,
+            fallback_ui: false,
+            device_name: "test",
+            t: 0.0,
+        };
+        s.run(action, &ctx, fx);
+    }
+
     fn host() -> HostRow {
         HostRow {
             key: "aa".into(),
@@ -510,6 +561,38 @@ mod tests {
         assert_eq!(s.host_key(), "aa");
     }
 
+    /// The shelf is on this menu, which is the only route to it that survives a device with
+    /// no face buttons: home's Y opens it too, but an Android TV remote has no Y. Offered on
+    /// the same terms that Y is (saved AND paired), and it REPLACES the menu, so Back from
+    /// the shelf lands on the carousel rather than on a menu about the host just left.
+    #[test]
+    fn the_library_hangs_off_the_menu_for_a_padless_device() {
+        let mut s = OptionsScreen::for_host(&host());
+        assert!(s
+            .actions(crate::platform::Platform::Android)
+            .contains(&Action::Library));
+
+        let mut fx = Outbox::default();
+        run_action(&mut s, Action::Library, &mut fx);
+        assert!(
+            matches!(fx.cmds.first(), Some(ConsoleCmd::FetchLibrary { .. })),
+            "opening the shelf asks for it first"
+        );
+        match fx.nav {
+            Some(Nav::Replace(screen)) => assert!(matches!(*screen, Screen::Library(_))),
+            _ => panic!("expected the shelf to replace the menu"),
+        }
+
+        // An unpaired host has no shelf to fetch — the row is absent, not inert.
+        let unpaired = OptionsScreen::for_host(&HostRow {
+            paired: false,
+            ..host()
+        });
+        assert!(!unpaired
+            .actions(crate::platform::Platform::Android)
+            .contains(&Action::Library));
+    }
+
     /// "Default profile…" swaps the menu for the chooser — a Replace like Edit's, and for
     /// the same reason — addressed to the HOST's plain key even from rows that carry a
     /// composite one.
@@ -520,7 +603,7 @@ mod tests {
             .actions(crate::platform::Platform::Desktop)
             .contains(&Action::BindProfile));
         let mut fx = Outbox::default();
-        s.run(Action::BindProfile, crate::store::file_store(), &mut fx);
+        run_action(&mut s, Action::BindProfile, &mut fx);
         match fx.nav {
             Some(crate::screens::Nav::Replace(screen)) => match *screen {
                 Screen::BindProfile(b) => assert_eq!(b.host_name(), "Desk"),
@@ -537,7 +620,7 @@ mod tests {
         let mut s = OptionsScreen::for_host(&host());
         assert!(s.label(Action::Clipboard).ends_with("Off"));
         let mut fx = Outbox::default();
-        s.run(Action::Clipboard, crate::store::file_store(), &mut fx);
+        run_action(&mut s, Action::Clipboard, &mut fx);
         assert_eq!(
             fx.cmds,
             vec![ConsoleCmd::SetClipboard {
@@ -551,7 +634,7 @@ mod tests {
         });
         assert!(s.label(Action::Clipboard).ends_with("On"));
         let mut fx = Outbox::default();
-        s.run(Action::Clipboard, crate::store::file_store(), &mut fx);
+        run_action(&mut s, Action::Clipboard, &mut fx);
         assert_eq!(
             fx.cmds,
             vec![ConsoleCmd::SetClipboard {
@@ -569,12 +652,12 @@ mod tests {
         s.list.cursor = i;
         let mut fx = Outbox::default();
 
-        s.run(Action::Forget, crate::store::file_store(), &mut fx);
+        run_action(&mut s, Action::Forget, &mut fx);
         assert!(fx.cmds.is_empty(), "the first press only arms");
         assert!(s.armed);
         assert!(s.label(Action::Forget).contains("press again"));
 
-        s.run(Action::Forget, crate::store::file_store(), &mut fx);
+        run_action(&mut s, Action::Forget, &mut fx);
         assert_eq!(
             fx.cmds,
             vec![ConsoleCmd::ForgetHost { key: "aa".into() }],
@@ -597,6 +680,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &[],
             deck: false,
+            fallback_ui: false,
             device_name: "test",
             t: 0.0,
         };
@@ -659,7 +743,7 @@ mod tests {
             OptionsScreen::for_game(&host(), &game()),
         ] {
             let mut fx = Outbox::default();
-            s.run(Action::CopyLink, crate::store::file_store(), &mut fx);
+            run_action(&mut s, Action::CopyLink, &mut fx);
             assert!(matches!(fx.nav, Some(Nav::Pop)));
             assert!(fx.toast.is_some());
         }

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

@@ -497,6 +497,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "living-room-deck",
             t: 0.0,
         };
@@ -537,6 +538,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "deck",
             t: 0.0,
         };

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

@@ -233,6 +233,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -274,6 +275,7 @@ mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };

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

@@ -104,6 +104,12 @@ enum RowId {
     Sc2Passthrough,
     /// DualSense raw-USB capture (touchpad, motion, adaptive triggers).
     DsCapture,
+    /// Whether the console UI fronts the app at all — the touch settings' switch
+    /// (`Settings.gamepadUiEnabled`), reachable from inside the console it turns off.
+    /// Only offered where there is another interface to fall back to
+    /// ([`Ctx::fallback_ui`]): on a TV or the desktop session this console is the only
+    /// UI, and an off switch would strand the user in nothing.
+    GamepadUi,
     /// When the console UI fronts the app: with a controller attached, or always.
     GamepadUiMode,
     /// The platform's connected-controllers view (an action row — opens a native screen).
@@ -121,6 +127,7 @@ mod android_keys {
     pub const SC2: &str = "android.sc2_capture";
     pub const DS_CAPTURE: &str = "android.ds_capture";
     pub const GAMEPAD_UI_MODE: &str = "android.gamepad_ui_mode";
+    pub const GAMEPAD_UI: &str = "android.gamepad_ui_enabled";
 }
 
 /// The Android console-UI mode's stored values (`GamepadUi.kt`).
@@ -245,6 +252,7 @@ const TABS: [(&str, &[RowId]); 7] = [
             RowId::Stats,
             RowId::Fullscreen,
             RowId::AutoWake,
+            RowId::GamepadUi,
             RowId::GamepadUiMode,
             RowId::Licenses,
         ],
@@ -384,7 +392,7 @@ impl SettingsScreen {
                 .1
                 .iter()
                 .copied()
-                .filter(|id| row_on(*id, ctx.platform) && row_applies(*id, ctx.settings))
+                .filter(|id| row_on(*id, ctx.platform) && row_applies(*id, ctx))
                 .collect();
         }
         if self.profiles.is_empty() {
@@ -675,6 +683,7 @@ fn row_on(id: RowId, platform: crate::platform::Platform) -> bool {
             | RowId::PhoneGyro
             | RowId::Sc2Passthrough
             | RowId::DsCapture
+            | RowId::GamepadUi
             | RowId::GamepadUiMode
             | RowId::Controllers
             | RowId::Licenses
@@ -694,9 +703,22 @@ fn row_on(id: RowId, platform: crate::platform::Platform) -> bool {
     }
 }
 
-fn row_applies(id: RowId, s: &pf_client_core::trust::Settings) -> bool {
+fn row_applies(id: RowId, ctx: &Ctx) -> bool {
     match id {
-        RowId::SmoothBuffer => s.present_priority == "smooth",
+        RowId::SmoothBuffer => ctx.settings.present_priority == "smooth",
+        // The console-off switch needs somewhere for "off" to land: only clients with a
+        // fallback interface (an Android phone/tablet's touch shell) get the row — on a TV
+        // this console is the only UI, and off would strand the user (the touch settings'
+        // subtitle even promises "A TV always uses it").
+        RowId::GamepadUi => ctx.fallback_ui,
+        // The same two conditions the mode decides anything under: a TV is in console mode
+        // whatever the mode says (`GamepadUi.kt`: the tv term alone satisfies the OR), and
+        // while the switch above is off nothing fronts the console at all. Hidden rather
+        // than dimmed, like the touch screen's picker, and it sits directly below the row
+        // that drops it so the cursor is never under anything that moves.
+        RowId::GamepadUiMode => {
+            ctx.fallback_ui && extra_bool(ctx.settings, android_keys::GAMEPAD_UI, true)
+        }
         _ => true,
     }
 }
@@ -962,9 +984,17 @@ fn row_spec(id: RowId, ctx: &Ctx, profiles: &[(String, String)]) -> RowSpec {
             "DualSense over USB",
             on_off(extra_bool(s, android_keys::DS_CAPTURE, true)).into(),
         ),
+        RowId::GamepadUi => (
+            None,
+            "Controller-optimized UI",
+            on_off(extra_bool(s, android_keys::GAMEPAD_UI, true)).into(),
+        ),
         RowId::GamepadUiMode => (
             None,
-            "Controller UI",
+            // The touch screen's word for the same picker, which now sits under the same
+            // switch it does there — "Controller UI" beside "Controller-optimized UI"
+            // would be two rows a reader has to tell apart by their tails.
+            "Show it",
             label_for(
                 &GAMEPAD_UI_MODES,
                 extra_str(s, android_keys::GAMEPAD_UI_MODE, "connected"),
@@ -1145,9 +1175,14 @@ fn detail(id: RowId, platform: crate::platform::Platform) -> &'static str {
             "Capture a wired DualSense directly (touchpad, motion, adaptive triggers). \
              Needs the USB grant when the pad is plugged in."
         }
+        RowId::GamepadUi => {
+            "Front the app with this console instead of the touch interface. Off returns \
+             to the touch home immediately — switch it back on there."
+        }
         RowId::GamepadUiMode => {
             "When this console fronts the app: whenever a controller is attached, or \
-             always. The touch settings' \"Controller-optimized UI\" switch turns it off."
+             always — for a device that lives docked to a TV. The switch above turns it \
+             off altogether."
         }
         RowId::Controllers => "Connected controllers, their grants and a rumble/haptics test.",
         RowId::Licenses => "The open-source licences this app ships under.",
@@ -1375,6 +1410,7 @@ fn adjust(id: RowId, delta: i32, wrap: bool, ctx: &mut Ctx) -> bool {
         RowId::PhoneGyro => toggle_extra(s, android_keys::PHONE_GYRO, false, delta, wrap),
         RowId::Sc2Passthrough => toggle_extra(s, android_keys::SC2, true, delta, wrap),
         RowId::DsCapture => toggle_extra(s, android_keys::DS_CAPTURE, true, delta, wrap),
+        RowId::GamepadUi => toggle_extra(s, android_keys::GAMEPAD_UI, true, delta, wrap),
         RowId::GamepadUiMode => {
             let mut v = extra_str(s, android_keys::GAMEPAD_UI_MODE, "connected").to_string();
             step_str(&GAMEPAD_UI_MODES, &mut v, delta, wrap).map(|()| {
@@ -1504,6 +1540,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1538,6 +1575,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1603,6 +1641,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1652,6 +1691,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1686,6 +1726,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1727,6 +1768,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1757,6 +1799,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1793,6 +1836,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1867,6 +1911,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1900,6 +1945,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1931,6 +1977,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -1960,6 +2007,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -2009,6 +2057,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -2060,6 +2109,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -2105,6 +2155,7 @@ pub(super) mod tests {
                 RowId::Sc2Passthrough,
                 RowId::DsCapture,
                 RowId::Controllers,
+                RowId::GamepadUi,
                 RowId::GamepadUiMode,
                 RowId::Licenses,
             ]
@@ -2147,6 +2198,9 @@ pub(super) mod tests {
                 extra_str(ctx.settings, android_keys::GAMEPAD_UI_MODE, "connected"),
                 "always"
             );
+            assert!(extra_bool(ctx.settings, android_keys::GAMEPAD_UI, true));
+            assert!(adjust(RowId::GamepadUi, 1, true, ctx));
+            assert!(!extra_bool(ctx.settings, android_keys::GAMEPAD_UI, true));
             // Only `extra` moved.
             let mut after = ctx.settings.clone();
             after.extra = before.extra.clone();
@@ -2154,6 +2208,34 @@ pub(super) mod tests {
         });
     }
 
+    /// The console-off switch exists only where there is a fallback interface for "off"
+    /// to land in, and the mode row under it only where the mode decides anything: not on
+    /// a TV (always console, whatever the mode says) and not while the switch is off.
+    #[test]
+    fn console_off_switch_needs_a_fallback_ui() {
+        with_ctx(|ctx| {
+            ctx.platform = crate::platform::Platform::Android;
+            // A TV: no off switch (it would strand the user), and no mode row either —
+            // `gamepadUiActive`'s tv term satisfies the OR on its own.
+            assert!(
+                !row_applies(RowId::GamepadUi, ctx),
+                "a TV offers no off switch"
+            );
+            assert!(!row_applies(RowId::GamepadUiMode, ctx));
+            // A phone or tablet with the console on: both rows.
+            ctx.fallback_ui = true;
+            assert!(row_applies(RowId::GamepadUi, ctx));
+            assert!(row_applies(RowId::GamepadUiMode, ctx));
+            // Switched off: the switch stays (it is the way back), the mode row goes.
+            set_extra_bool(ctx.settings, android_keys::GAMEPAD_UI, false);
+            assert!(row_applies(RowId::GamepadUi, ctx));
+            assert!(
+                !row_applies(RowId::GamepadUiMode, ctx),
+                "the mode row decides nothing while the switch above it is off"
+            );
+        });
+    }
+
     #[test]
     fn every_row_has_exactly_one_tab() {
         let mut seen: Vec<RowId> = Vec::new();
@@ -2168,9 +2250,9 @@ pub(super) mod tests {
         // 2026-08 sweep found them bridged but unreachable) later passes added, minus the
         // game-library toggle: this screen never read it, and the library is offered on any
         // paired host now.
-        // 35 desktop rows + the eight Android-only ones (design android-skia-console-port.md
-        // D3): six `extra`-backed settings and two platform-screen action rows.
-        assert_eq!(seen.len(), 43, "{seen:?}");
+        // 35 desktop rows + the nine Android-only ones (design android-skia-console-port.md
+        // D3): seven `extra`-backed settings and two platform-screen action rows.
+        assert_eq!(seen.len(), 44, "{seen:?}");
         assert!(seen.contains(&RowId::Palette));
         assert!(seen.contains(&RowId::ReduceMotion));
         assert!(seen.contains(&RowId::AudioFormat));
@@ -2209,6 +2291,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -2250,6 +2333,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -2295,6 +2379,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };
@@ -2373,6 +2458,7 @@ pub(super) mod tests {
             platform: crate::platform::Platform::Desktop,
             pads: &pads,
             deck: false,
+            fallback_ui: false,
             device_name: "t",
             t: 0.0,
         };

crates/pf-console-ui/src/shell.rs

@@ -183,6 +183,11 @@ pub struct ConsoleOptions {
     pub device_name: String,
     /// Steam Deck: Steam's keyboard types (SDL text input); ours never draws.
     pub deck: bool,
+    /// Whether the host app has another interface to fall back to when the console is
+    /// switched off — an Android phone/tablet's touch shell. Shows the console-off switch
+    /// on the settings screen; false where this console is the only UI there is (the
+    /// desktop session, an Android TV), where offering "off" would strand the user.
+    pub fallback_ui: bool,
     /// Where settings persist and the profile catalog comes from. `None` = the desktop
     /// file store (`pf_client_core::trust`), which is what the Vulkan session wants and the
     /// only store there is on Linux/Windows; every other host must supply one.
@@ -203,6 +208,7 @@ impl ConsoleOptions {
         ConsoleOptions {
             device_name,
             deck,
+            fallback_ui: false,
             store: None,
             platform: Platform::Desktop,
             gpu_cache_bytes: DEFAULT_GPU_CACHE_BYTES,
@@ -247,6 +253,8 @@ pub(crate) struct Shell {
     hosts_gen: u64,
     device_name: String,
     deck: bool,
+    /// See [`ConsoleOptions::fallback_ui`].
+    fallback_ui: bool,
     pub(crate) in_stream: bool,
     connecting: Option<Connecting>,
     /// The last host title a connect was raised for, kept past the connect itself so
@@ -352,6 +360,7 @@ impl Shell {
             hosts_gen: u64::MAX,
             device_name: opts.device_name,
             deck: opts.deck,
+            fallback_ui: opts.fallback_ui,
             in_stream: false,
             connecting: None,
             last_connect_title: None,
@@ -888,6 +897,7 @@ impl Shell {
                 platform: self.platform,
                 pads: &self.pads,
                 deck: self.deck,
+                fallback_ui: self.fallback_ui,
                 device_name: &self.device_name,
                 t: self.t0.elapsed().as_secs_f64(),
             };
@@ -951,6 +961,10 @@ impl Shell {
                     // navigation but "open this tile's menu". Without this the context menu —
                     // and with it the only way to copy a host's link — is pad-only.
                     crate::glyphs::HintKey::Up => Some(MenuEvent::Move(MenuDir::Up)),
+                    // ▼ is the same kind of hint: a direction that steers nothing, because
+                    // the only screen publishing it is the home carousel, where down means
+                    // "open Settings". A finger must be able to press what it advertises.
+                    crate::glyphs::HintKey::Down => Some(MenuEvent::Move(MenuDir::Down)),
                     _ => None,
                 };
                 if let Some(ev) = ev {
@@ -970,6 +984,7 @@ impl Shell {
                 platform: self.platform,
                 pads: &self.pads,
                 deck: self.deck,
+                fallback_ui: self.fallback_ui,
                 device_name: &self.device_name,
                 t: self.t0.elapsed().as_secs_f64(),
             };

crates/pf-console-ui/src/shell/render.rs

@@ -172,6 +172,7 @@ impl Shell {
             platform: self.platform,
             pads: &self.pads,
             deck: self.deck,
+            fallback_ui: self.fallback_ui,
             device_name: &self.device_name,
             t,
             glyphs: self.glyphs,
@@ -331,6 +332,8 @@ struct LayerEnv<'a> {
     platform: crate::platform::Platform,
     pads: &'a [PadInfo],
     deck: bool,
+    /// See [`crate::shell::ConsoleOptions::fallback_ui`] — a screen's row set can ask.
+    fallback_ui: bool,
     device_name: &'a str,
     t: f64,
     glyphs: GlyphStyle,
@@ -365,6 +368,7 @@ impl LayerEnv<'_> {
             platform: self.platform,
             pads: self.pads,
             deck: self.deck,
+            fallback_ui: self.fallback_ui,
             device_name: self.device_name,
             t: self.t,
         };

crates/pf-console-ui/src/shell/tests.rs

@@ -402,10 +402,11 @@ fn a_replace_carries_the_screen_it_replaced() {
     assert!(matches!(s.stack.last(), Some(Screen::HostOptions(_))));
     finish_motion(&mut s);
 
-    // Walk to "Edit…" and take it. The first fixture host is paired and online and cannot
-    // wake, so its menu is [Send logs, Copy link, Edit…, Forget, Cancel] — Edit is two down.
-    // Pressed exactly rather than searched, so that reordering the menu fails HERE instead of
-    // quietly landing this test's Confirm on "Forget".
+    // Walk to "Edit…" and take it. The first fixture host is paired, saved and online and
+    // cannot wake, so its menu is [Send logs, Library, Copy link, Edit…, …] — Edit is three
+    // down. Pressed exactly rather than searched, so that reordering the menu fails HERE
+    // instead of quietly landing this test's Confirm on something destructive.
+    s.handle_menu(MenuEvent::Move(MenuDir::Down));
     s.handle_menu(MenuEvent::Move(MenuDir::Down));
     s.handle_menu(MenuEvent::Move(MenuDir::Down));
     s.handle_menu(MenuEvent::Confirm);

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

@@ -116,11 +116,16 @@ static MANAGED_LAUNCH: std::sync::Mutex<()> = std::sync::Mutex::new(());
 /// (single-instance), so [`schedule_restore_tv_session`] can restart them when the client disconnects.
 static STOPPED_AUTOLOGIN: std::sync::Mutex<Vec<String>> = std::sync::Mutex::new(Vec::new());
 
-/// The display-manager unit we stopped for the takeover (any DM that drove a LIVE gaming session
-/// is stopped for the stream — see [`dm_plan`]), so the restore brings the box back via
+/// A display-manager unit stopped for a takeover, so the restore brings the box back via
 /// `reset-failed` + `restart` of the DM instead of a `--user start` of the gamescope unit (which
 /// cannot work on a mask-fragile flavor: without a DM login session there is no seat, so gamescope
 /// never gets DRM master — live-proven on the Nobara repro VM 2026-07-24).
+///
+/// ⚠ **Adoption-only since 0.31.0**: the takeover idles the box's autologin session
+/// ([`install_idle_dropin`]) and leaves the DM up, so nothing in this process ever writes this any
+/// more — only [`restore_takeover_on_startup`], for a takeover stranded by a host old enough to
+/// have stopped one. It is therefore NOT the marker of a live takeover; [`takeover_idled`] is.
+/// Reading it as that marker is what silently unreachable-d the in-stream switch gate in 0.31.0.
 static STOPPED_DM: std::sync::Mutex<Option<String>> = std::sync::Mutex::new(None);
 
 /// Whether this takeover runtime-masked the [`STOPPED_AUTOLOGIN`] units ([`mask_unit`]) — i.e.
@@ -136,12 +141,16 @@ static STOPPED_DM: std::sync::Mutex<Option<String>> = std::sync::Mutex::new(None
 static AUTOLOGIN_MASKED: std::sync::Mutex<bool> = std::sync::Mutex::new(false);
 
 /// mtime of the `steamos-session-select` sentinel as of the takeover — the baseline the in-stream
-/// "Switch to Desktop" detector compares against. Steam's session-select script writes
-/// `~/.config/steamos-session-select` unconditionally in its USER pass, before any of its
-/// display-manager checks — so it advances even under a DM-stop takeover, where the script's
-/// config-rewrite tail is a silent no-op (every write branch is gated on the DM *running*;
-/// diagnosed live on the Nobara repro VM 2026-07-24). An advanced mtime after a capture loss is
-/// therefore the one durable trace of the user's switch request.
+/// "Switch to Desktop" detector compares against. The ChimeraOS-layout `os-session-select`
+/// (Nobara, ChimeraOS) writes `~/.config/steamos-session-select` unconditionally in its USER pass,
+/// before any of its display-manager checks, so an advanced mtime after a capture loss is the one
+/// durable trace of the user's switch request — the switch itself leaves nothing else behind that
+/// this host can see.
+///
+/// ⚠ Bazzite/SteamOS write NO sentinel: their `os-session-select` is a thin wrapper over
+/// `steamosctl` D-Bus calls. The detector is therefore inert there by construction, which is
+/// exactly right — those platforms default the mid-stream session watcher ON
+/// ([`is_steam_htpc_platform`]) and follow the switch with it instead.
 ///
 /// Two levels of `Option`, because "no baseline" and "no sentinel" mean opposite things:
 /// * **outer `None`** — never baselined (no takeover this host lifetime). Nothing can read as an
@@ -674,21 +683,28 @@ fn create_managed_session(client: &str, mode: Mode, hdr: bool) -> Result<Virtual
     if steamos_session_present() {
         return create_managed_session_steamos(mode, hdr);
     }
-    // In-stream "Switch to Desktop" under a DM-stop takeover: the user's session-select inside
-    // the streamed game mode advanced the sentinel, but its config rewrite was a silent no-op
-    // (every write branch needs the DM running, and the takeover stopped it) — so without this,
-    // the capture loss it caused would just relaunch game mode ("thrown back in", field-tested
-    // 2026-07-24). Honor the request instead: restore the DM and replay the switch.
-    let dm_takeover = STOPPED_DM.lock().unwrap_or_else(|e| e.into_inner()).clone();
-    if let Some(dm) = dm_takeover {
-        if session_select_requested() {
-            *STOPPED_DM.lock().unwrap_or_else(|e| e.into_inner()) = None;
-            honor_session_select_switch(dm);
-            return Err(anyhow!(
-                "the user switched the box to the desktop session — display manager restored; \
-                 re-detection follows the desktop compositor as it comes up"
-            ));
-        }
+    // In-stream "Switch to Desktop": the user's session-select inside the streamed game mode
+    // advanced the sentinel, so the box is on its way to a desktop session. Without this, the
+    // capture loss that switch causes just relaunches game mode over the booting desktop — the
+    // "thrown back in" field report of 2026-07-24, and again on Nobara 2026-08-20.
+    //
+    // ⚠ Gated on the IDLED takeover, not on [`STOPPED_DM`]. Until 0.31.0 the takeover stopped the
+    // display manager, and setting that static was what armed this gate; the idled takeover
+    // replaced both the stop and the static ([`install_idle_dropin`]) and nothing re-armed the
+    // gate, so this branch became unreachable on every box. Bazzite did not notice — its
+    // `os-session-select` is a `steamosctl` D-Bus call that writes no sentinel, and its session
+    // watcher is on by default ([`is_steam_htpc_platform`]) so the stream follows the switch
+    // anyway. The ChimeraOS-layout distros are the ones that lost their handling: their
+    // `os-session-select` DOES write the sentinel, and `ID=nobara` matches no HTPC default.
+    if takeover_idled() && session_select_requested() {
+        // `take`, so an adopted DM stop is consumed exactly once — see
+        // [`honor_session_select_switch`] for why a 0.31.0 takeover has none to consume.
+        let adopted_dm = std::mem::take(&mut *STOPPED_DM.lock().unwrap_or_else(|e| e.into_inner()));
+        honor_session_select_switch(adopted_dm);
+        return Err(anyhow!(
+            "the user switched the box to the desktop session — the box's own game mode is handed \
+             back; re-detection follows the desktop compositor as it comes up"
+        ));
     }
     // Post-honor grace: while the selected desktop boots, a managed relaunch would win the race
     // (gamescope+Steam start faster than KWin) and a delivering pipeline ends the rebuild's
@@ -1349,19 +1365,34 @@ fn install_idle_dropin() -> Result<()> {
         .parent()
         .context("the idle drop-in path has no parent directory")?;
     std::fs::create_dir_all(dir).with_context(|| format!("create {}", dir.display()))?;
-    std::fs::write(
-        &path,
-        format!(
-            "[Service]\nExecStart=\nExecStart={} infinity\n",
-            sleep_binary()
-        ),
-    )
-    .with_context(|| format!("write {}", path.display()))?;
+    std::fs::write(&path, idle_dropin_body(sleep_binary()))
+        .with_context(|| format!("write {}", path.display()))?;
     systemctl_user(&["daemon-reload"]);
     *IDLE_DROPIN_ARMED.lock().unwrap_or_else(|e| e.into_inner()) = true;
     Ok(())
 }
 
+/// The idle drop-in's body (the unit-testable core of [`install_idle_dropin`]).
+///
+/// The **empty `ExecStart=` comes first and is load-bearing**: `ExecStart` is a list-valued
+/// directive, so a drop-in that only adds a line APPENDS to the box's own — which would run the
+/// real gamescope session *and* the sleep, i.e. exactly the Steam-fighting session the takeover
+/// exists to get out of the way, with no symptom pointing here. The reset is what replaces it.
+fn idle_dropin_body(sleep_bin: &str) -> String {
+    format!("[Service]\nExecStart=\nExecStart={sleep_bin} infinity\n")
+}
+
+/// Does THIS host hold the box's game mode idled right now? The successor to "did we stop the
+/// display manager" as the marker of a live managed takeover, and so what arms the in-stream
+/// switch gate in [`create_managed_session`].
+///
+/// Reads [`IDLE_DROPIN_ARMED`] — this process's own memory — deliberately, unlike
+/// [`remove_idle_dropin`]: a drop-in on disk that we did not write belongs to a dead host, and
+/// honoring a "switch" against someone else's takeover would hand back a box we never took.
+fn takeover_idled() -> bool {
+    *IDLE_DROPIN_ARMED.lock().unwrap_or_else(|e| e.into_inner())
+}
+
 /// Remove the idle drop-in so the box's own Game Mode runs for real again; reports whether one was
 /// there. Deliberately NOT gated on [`IDLE_DROPIN_ARMED`] — the flag is this process's memory, and
 /// the drop-in outliving a host that died is exactly the case that has to be swept.
@@ -2282,10 +2313,36 @@ fn switch_ends_mask_window(kind: super::ActiveKind) -> bool {
 }
 
 /// The host's mid-stream session watcher calls this on every switch it confirms; see
-/// [`switch_ends_mask_window`] for which ones actually lift the mask.
+/// [`switch_ends_mask_window`] for which ones end the takeover's hold on the box's own game mode.
+///
+/// This is the SECOND of the two ways a box can leave our takeover mid-stream — the sentinel
+/// detector in [`create_managed_session`] is the other — and both owe the box the same hand-back.
+/// The watcher is the one that covers Bazzite/SteamOS, where it is on by default
+/// ([`is_steam_htpc_platform`]) and no sentinel is ever written; the detector covers the
+/// ChimeraOS-layout distros, which are the reverse. Fixing only one leaves the other's boxes
+/// holding an idled game mode.
 pub fn release_autologin_mask(switched_to: super::ActiveKind) {
-    if switch_ends_mask_window(switched_to) {
-        lift_autologin_mask();
+    if !switch_ends_mask_window(switched_to) {
+        return;
+    }
+    lift_autologin_mask();
+    // The idle drop-in is the mask's successor and inherits its whole hazard: it replaces the
+    // box's game-mode `ExecStart` with a sleep, and a switch to a desktop is exactly where that
+    // stops being ours to hold. Left on, the user's "Return to Gaming Mode" starts a unit that
+    // only sleeps — the same barred way back this function's mask lift exists to prevent, and
+    // measured in that state on Bazzite `.41` 2026-08-20 (`ExecStart=/usr/bin/sleep infinity`
+    // still on the unit after a completed switch to KDE).
+    //
+    // Deliberately NOT a full [`clear_takeover`]: the takeover outlives this window, exactly as
+    // the mask lift's own note says. The box may come back to game mode, and the disconnect
+    // restore still owes [`STOPPED_AUTOLOGIN`] a start. All this says is "the box's own game mode
+    // runs for real again".
+    if remove_idle_dropin() {
+        tracing::info!(
+            switched_to = ?switched_to,
+            "gamescope: the box left our game session for a desktop — removed the takeover's idle \
+             drop-in so its own Game Mode runs for real again"
+        );
     }
 }
 
@@ -2754,11 +2811,12 @@ fn session_select_mtime() -> Option<std::time::SystemTime> {
 
 /// Record the sentinel baseline, so a LATER write (the user's in-stream "Switch to Desktop") is
 /// distinguishable from the switch that led into this session. Taken at **takeover** (the moment
-/// [`STOPPED_DM`] is set, which is what arms the honor gate) and again at a successful launch: the
-/// switch INTO game mode writes the sentinel on its way in, and that write must never read as a
-/// request to go back out. Baselining only at launch left the window in between — a takeover whose
-/// launch failed, then a client retry inside the restore debounce — reading a months-old sentinel
-/// as a live request and pushing the box to the desktop the user never asked for.
+/// the idle drop-in goes in, which is what arms the honor gate — see [`takeover_idled`]) and again
+/// at a successful launch: the switch INTO game mode writes the sentinel on its way in, and that
+/// write must never read as a request to go back out. Baselining only at launch left the window in
+/// between — a takeover whose launch failed, then a client retry inside the restore debounce —
+/// reading a months-old sentinel as a live request and pushing the box to the desktop the user
+/// never asked for.
 fn record_session_select_baseline() {
     *SESSION_SELECT_BASELINE
         .lock()
@@ -2801,11 +2859,11 @@ fn sentinel_advanced(
 ///
 /// The caller then refuses managed relaunches for [`SWITCH_HONOR_GRACE`] so the capture-loss
 /// re-detection follows the desktop compositor once it's up instead of racing it.
-fn honor_session_select_switch(dm: String) {
+fn honor_session_select_switch(adopted_dm: Option<String>) {
     tracing::info!(
-        %dm,
-        "gamescope: in-stream session-select detected — restoring the display manager and \
-         switching the box to the desktop session"
+        adopted_dm = ?adopted_dm,
+        "gamescope: in-stream session-select detected — handing the box's own game mode back and \
+         following the desktop session the user selected"
     );
     // Consume the takeover state up front: from here on the box is the DM's again. The mask goes
     // FIRST and while the unit list still exists — this path discards that list, and it is the only
@@ -2818,7 +2876,43 @@ fn honor_session_select_switch(dm: String) {
     clear_takeover();
     *MANAGED_SESSION.lock().unwrap_or_else(|e| e.into_inner()) = None;
     stop_session(SESSION_UNIT); // dead already (the switch shut its Steam down) — clear the unit
-    if let Err(e) = restore_display_manager(&dm) {
+                                // Give the box its own Game Mode back before anything else can ask for it. The takeover
+                                // replaced that session's `ExecStart` with a sleep ([`install_idle_dropin`]), and a switch is
+                                // the one exit that used to leave it behind: the disconnect restore sweeps it, but a switch is
+                                // not a disconnect. Without this the user's next "Return to Gaming Mode" starts a unit that
+                                // does nothing at all — measured on the Nobara VM 2026-08-20, and on glass it is
+                                // indistinguishable from broken hardware.
+    if remove_idle_dropin() {
+        tracing::info!(
+            "gamescope: removed the takeover's idle drop-in — the box's own Game Mode runs for \
+             real again"
+        );
+    }
+    // Only an ADOPTED takeover still owes a display-manager restore. 0.31.0 leaves the DM up for
+    // exactly this reason, so by the time we get here the OS's own switch has already done the
+    // whole job — config rewrite and relogin (measured end to end on the Nobara VM). A takeover
+    // inherited from a host old enough to have STOPPED the DM has not: for it the switch really
+    // was the silent no-op that every write branch of `os-session-select` becomes without a
+    // running DM, so that one still has to be replayed.
+    if let Some(dm) = adopted_dm {
+        replay_switch_under_restored_dm(&dm);
+    }
+    record_session_select_baseline();
+    *SWITCH_HONORED_AT.lock().unwrap_or_else(|e| e.into_inner()) = Some(Instant::now());
+}
+
+/// Restore a display manager an ADOPTED takeover stopped, then replay the user's switch under it —
+/// every verb live-validated on the Nobara repro VM:
+/// 1. start the DM (its autologin heads back into game mode briefly — the config still names it);
+/// 2. run the distro's own `os-session-select desktop` as the user (its internal pkexec is
+///    `allow_any`-authorized), which rewrites the DM autologin config to the desktop session;
+/// 3. stop the autologin gamescope unit — the login session exits, and `Relogin=true` relogs
+///    into the now-selected desktop.
+///
+/// Reachable only from [`honor_session_select_switch`], and only for a takeover inherited from a
+/// pre-0.31.0 host: nothing stops a display manager any more.
+fn replay_switch_under_restored_dm(dm: &str) {
+    if let Err(e) = restore_display_manager(dm) {
         tracing::warn!(
             %dm,
             reason = %e,
@@ -2831,7 +2925,7 @@ fn honor_session_select_switch(dm: String) {
         // Budgeted: this is a 10 s loop, and a single unbounded `is-active` against a system
         // manager that is itself mid-restart would consume the whole window in one tick.
         let active = crate::proc::output_within(
-            Command::new("systemctl").args(["is-active", &dm]),
+            Command::new("systemctl").args(["is-active", dm]),
             UNIT_STATE_BUDGET,
         )
         .map(|o| String::from_utf8_lossy(&o.stdout).trim() == "active")
@@ -2888,8 +2982,6 @@ fn honor_session_select_switch(dm: String) {
              session instead of switching to the desktop"
         );
     }
-    record_session_select_baseline();
-    *SWITCH_HONORED_AT.lock().unwrap_or_else(|e| e.into_inner()) = Some(Instant::now());
 }
 
 /// Stop every autologin gaming-mode session (`gamescope-session-plus@*.service`) so its
@@ -2979,6 +3071,13 @@ fn stop_autologin_sessions() -> Result<()> {
     // switch.
     if plan.dm_relogins {
         install_idle_dropin().context("idling the box's autologin game session for the stream")?;
+        // Baseline the switch sentinel HERE, not only at a successful launch: arming the idle
+        // drop-in is what arms the honor gate in [`create_managed_session`], so from this instant
+        // an unbaselined sentinel would read as an in-stream "Switch to Desktop" — including the
+        // write left by the switch that just brought the box INTO game mode. A successful launch
+        // re-baselines (tighter still). This moved here from the display-manager stop that 0.31.0
+        // retired; losing it with that stop is what left the gate unarmed.
+        record_session_select_baseline();
     }
     let units: Vec<String> = listed.into_iter().map(|(u, _)| u).collect();
     let mut stopped = Vec::new();
@@ -5233,9 +5332,10 @@ mod tests {
     use super::{
         any_output_size_is, cancel_pending_restore, cgroup_is_punktfunk_owned,
         classify_output_size, connected_connector_under, display_manager_unit_under, dm_plan,
-        game_hz, gamescope_output_size, hdr_args, is_steam_launch, mask_unit, missing_flags,
-        mode_mismatch, nested_wrapper_script, our_wsi_layer_dir, plan_bind, release_autologin_mask,
-        script_hardcodes_gamescope, sentinel_advanced, shape_dedicated_command,
+        game_hz, gamescope_output_size, hdr_args, idle_dropin_body, idle_dropin_path,
+        install_idle_dropin, is_steam_launch, mask_unit, missing_flags, mode_mismatch,
+        nested_wrapper_script, our_wsi_layer_dir, plan_bind, release_autologin_mask,
+        remove_idle_dropin, script_hardcodes_gamescope, sentinel_advanced, shape_dedicated_command,
         switch_ends_mask_window, takeover_state_is_live, unmask_unit, xwayland_refusal_marker,
         BindOff, BindPlan, BoxOutputSize, DmHelperError, SessionBind, TakeoverState, WsiPlan,
         AUTOLOGIN_MASKED, DISTRO_GAMESCOPE_PATH, PENDING_RESTORE, RESTORE_FLIGHT,
@@ -5434,6 +5534,25 @@ mod tests {
         assert!(!sentinel_advanced(Some(Some(t0)), None));
     }
 
+    /// `ExecStart` is list-valued, so the reset line is the whole mechanism: without it the
+    /// drop-in APPENDS the sleep to the box's own session command and both run — the takeover
+    /// would then be fighting the very Steam it set out to free, and nothing on the box would say
+    /// why. Pins the reset, its order, and that the resolved `sleep` is the one that gets run.
+    #[test]
+    fn idle_dropin_replaces_exec_start_rather_than_appending() {
+        let body = idle_dropin_body("/usr/bin/sleep");
+        assert_eq!(
+            body, "[Service]\nExecStart=\nExecStart=/usr/bin/sleep infinity\n",
+            "{body}"
+        );
+        let lines: Vec<&str> = body.lines().collect();
+        assert_eq!(lines[1], "ExecStart=", "the reset must come first: {body}");
+        // The path is resolved per box ([`sleep_binary`]) and must reach the unit verbatim — a
+        // bare `sleep` would depend on the unit's PATH, and an ExecStart that fails to EXECUTE is
+        // the failing unit the display manager relogin-loops against.
+        assert!(idle_dropin_body("/bin/sleep").contains("ExecStart=/bin/sleep infinity"));
+    }
+
     #[test]
     fn nested_wrapper_script_shapes() {
         let relay = std::path::Path::new("/run/user/1000/pf-ei");
@@ -5661,10 +5780,32 @@ mod tests {
         release_autologin_mask(crate::ActiveKind::None);
         assert_eq!(is_enabled(), "masked-runtime");
 
+        // The idle drop-in is the mask's successor and shares this exact window, so it has to come
+        // off with it. A takeover that leaves it on has replaced the box's game-mode `ExecStart`
+        // with a sleep — a "Return to Gaming Mode" that starts and does nothing, which is the same
+        // barred way back, measured on Bazzite `.41` 2026-08-20.
+        install_idle_dropin().expect("arm the takeover's idle drop-in");
+        assert!(idle_dropin_path().exists());
+
+        // Mid-stream, with the box still ours: the mask is doing its job and must stay. `Gaming` is
+        // what our own managed session reads as, and `None` is one momentarily down between
+        // relaunches — lifting on either would void the mask for the whole stream.
+        release_autologin_mask(crate::ActiveKind::Gaming);
+        release_autologin_mask(crate::ActiveKind::None);
+        assert_eq!(is_enabled(), "masked-runtime");
+        assert!(
+            idle_dropin_path().exists(),
+            "the idle drop-in must survive a switch that is not to a desktop"
+        );
+
         // The user switched the box to its own desktop mid-stream: the window is over, and the way
         // back into game mode has to be clear before they ask for it.
         release_autologin_mask(crate::ActiveKind::DesktopKde);
         assert_ne!(is_enabled(), "masked-runtime");
+        assert!(
+            !idle_dropin_path().exists(),
+            "the idle drop-in outlived the switch — the box's Game Mode is a sleep now"
+        );
         // The restart list SURVIVES the lift: the mask's lifetime is shorter than the takeover's,
         // and the disconnect restore still owes these units a `start`.
         assert_eq!(STOPPED_AUTOLOGIN.lock().unwrap().as_slice(), [PROBE]);
@@ -5673,6 +5814,7 @@ mod tests {
         assert_ne!(is_enabled(), "masked-runtime");
 
         unmask_unit(PROBE);
+        remove_idle_dropin();
         STOPPED_AUTOLOGIN.lock().unwrap().clear();
         *AUTOLOGIN_MASKED.lock().unwrap() = false;
     }

crates/punktfunk-core/cbindgen.toml

@@ -215,6 +215,7 @@ include = ["PunktfunkEndReason"]
 "MSG_CLOCK_PROBE" = "PUNKTFUNK_MSG_CLOCK_PROBE"
 "MSG_CURSOR_RENDER" = "PUNKTFUNK_MSG_CURSOR_RENDER"
 "MSG_CURSOR_SHAPE" = "PUNKTFUNK_MSG_CURSOR_SHAPE"
+"MSG_DELIVERY_REPORT" = "PUNKTFUNK_MSG_DELIVERY_REPORT"
 "MSG_LOSS_REPORT" = "PUNKTFUNK_MSG_LOSS_REPORT"
 "MSG_PAIR_CHALLENGE" = "PUNKTFUNK_MSG_PAIR_CHALLENGE"
 "MSG_PAIR_PROOF" = "PUNKTFUNK_MSG_PAIR_PROOF"

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

@@ -1,7 +1,9 @@
 //! `CtrlRequest` (the embedder's control-stream requests) and `Negotiated` (the handshake result).
 
 use crate::config::{CompositorPref, GamepadPref, Mode};
-use crate::quic::{ClipControl, ClipOffer, ColorInfo, LossReport, ProbeRequest, RfiRequest};
+use crate::quic::{
+    ClipControl, ClipOffer, ColorInfo, DeliveryReport, LossReport, ProbeRequest, RfiRequest,
+};
 
 /// A control-stream request the embedder makes on the open handshake stream: a mode switch or a
 /// speed test. One outbound channel carries both so the worker's `select!` has a single writer
@@ -15,6 +17,10 @@ pub(crate) enum CtrlRequest {
     /// forcing a full IDR. See [`RfiRequest`].
     Rfi(RfiRequest),
     Loss(LossReport),
+    /// How many data-plane packets have reached us all session — sent straight after every
+    /// [`CtrlRequest::Loss`], because `loss_ppm` is ambiguous at zero (no loss and no packets look
+    /// identical) and only this separates them. See [`DeliveryReport`].
+    Delivery(DeliveryReport),
     /// Adaptive bitrate: ask the host to re-target its encoder (kbps). Sent by the pump's
     /// [`BitrateController`] when the user's bitrate setting is Automatic.
     SetBitrate(u32),

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

@@ -57,6 +57,21 @@ pub(crate) const FLUSH_AFTER: Duration = Duration::from_millis(250);
 /// the number, so the two can never drift apart.
 pub const FLUSH_COOLDOWN: Duration = Duration::from_secs(2);
 
+/// Spacing of a client's keyframe re-asks while it has received **no video at all** — the other
+/// reason a client asks on a perfectly fixed cadence, and the OPPOSITE fault to [`FLUSH_COOLDOWN`]'s
+/// (nothing arriving, versus more arriving than it can drain).
+///
+/// **Public, and deliberately a different value, for the same reason [`FLUSH_COOLDOWN`] is public.**
+/// While both were 2000 ms the host's recovery-cadence detector could not tell which failure it was
+/// looking at, and reported the confident wrong one: a 2026-08-20 field case where not one byte of
+/// video ever reached the client was diagnosed for days as a client too slow to keep up. Embedders
+/// own the no-video timer (it lives in each decode loop), so this is the value they must use — a
+/// local copy is exactly the drift that made the two indistinguishable in the first place.
+///
+/// The delivery count on [`crate::quic::LossReport`] settles it outright for clients new enough to
+/// send one; this keeps the period itself informative for those that are not.
+pub const NO_VIDEO_RETRY: Duration = Duration::from_millis(2600);
+
 /// A clock-triggered jump-to-live that discarded fewer datagrams than this (and no queued AUs)
 /// found NO local backlog: the frames read as late, but nothing here was actually behind. Two
 /// causes, and flushing helps neither: a **wall-clock step** (NTP mid-session on either end)

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

@@ -42,7 +42,7 @@ mod recovery;
 mod rumble;
 mod worker;
 
-pub use self::frame_channel::FLUSH_COOLDOWN;
+pub use self::frame_channel::{FLUSH_COOLDOWN, NO_VIDEO_RETRY};
 pub use self::planes::AudioPacket;
 pub use self::probe::ProbeOutcome;
 pub use self::rumble::{ActuatorQuirks, RumbleCommand};

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

@@ -11,9 +11,9 @@ use crate::abr::BitrateController;
 use crate::config::Role;
 use crate::packet::FLAG_PROBE;
 use crate::quic::{
-    io, wall_clock_ns, window_loss_ppm, BitrateChanged, ClipState, ClockEcho, ClockResync, Hello,
-    LossReport, ProbeResult, Reconfigure, Reconfigured, RequestKeyframe, ResyncAdmit, ResyncGuard,
-    ResyncStep, SetBitrate, Start, Welcome,
+    io, wall_clock_ns, window_loss_ppm, BitrateChanged, ClipState, ClockEcho, ClockResync,
+    DeliveryReport, Hello, LossReport, ProbeResult, Reconfigure, Reconfigured, RequestKeyframe,
+    ResyncAdmit, ResyncGuard, ResyncStep, SetBitrate, Start, Welcome,
 };
 use crate::session::Session;
 use crate::transport::UdpTransport;

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

@@ -107,6 +107,7 @@ impl ControlTask {
                         }
                         CtrlRequest::Rfi(r) => r.encode(),
                         CtrlRequest::Loss(r) => r.encode(),
+                        CtrlRequest::Delivery(r) => r.encode(),
                         CtrlRequest::SetBitrate(k) => SetBitrate { bitrate_kbps: k }.encode(),
                         CtrlRequest::ClockResync => {
                             if clock_rtt_ns.is_none() {

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

@@ -77,6 +77,12 @@ impl DataPump {
                                           // size FEC to the link. Suppressed during a speed test (its FLAG_PROBE filler would skew it).
         const ADAPT_REPORT_INTERVAL: Duration = Duration::from_millis(750);
         let mut last_report = Instant::now();
+        // Has the host been told, once, that data-plane packets are reaching us? See the send site:
+        // the delivery count is reported every window while it is ZERO (the state the host acts on)
+        // and once more when the first packets land, then never again. A host that predates the
+        // message logs "unknown control message" for each one, so a healthy session must not stream
+        // them — one line per session is a fair price on an old host, eighty a minute is not.
+        let mut delivery_confirmed = false;
         let (
             mut last_recovered,
             mut last_late,
@@ -415,6 +421,27 @@ impl DataPump {
                     );
                 } else {
                     let _ = ctrl_tx.try_send(CtrlRequest::Loss(LossReport { loss_ppm }));
+                    // Rides with the loss report — it is what makes `loss_ppm = 0` readable at the
+                    // host, which cannot otherwise tell a flawless link from one delivering
+                    // nothing. The session TOTAL, not this window's, so one message stands on its
+                    // own. Deliberately inside the same arm: a discarded window is discarded
+                    // because the host was rebuilding or a probe distorted it, and staying silent
+                    // there keeps that contract exact. Nothing is lost — the state this reports
+                    // (no packets at all) produces no discards, so its windows always send.
+                    //
+                    // Sent every window while the count is ZERO, then ONCE when the first packets
+                    // land (so the host stops guessing and can name the other failure confidently),
+                    // then never again: a healthy session must not stream a message that older
+                    // hosts log as unknown on every arrival.
+                    // ponytail: only start-of-session death is covered. A path that dies MID-stream
+                    // leaves the count frozen above zero and silent, which the host still reads as
+                    // healthy — detecting that needs a stalled-counter check with its own timing,
+                    // worth adding if a mid-session case is ever reported.
+                    if should_report_delivery(st.packets_received, &mut delivery_confirmed) {
+                        let _ = ctrl_tx.try_send(CtrlRequest::Delivery(DeliveryReport {
+                            packets_received: st.packets_received,
+                        }));
+                    }
                 }
                 // Standing-latency bleed: close the detector's window with this report's loss
                 // verdict and run its escalation ladder — re-sync first (free; a stale offset
@@ -757,10 +784,58 @@ fn take_pipeline_gap(slot: &AtomicU32) -> Option<u32> {
     }
 }
 
+/// Does this report window owe the host a [`DeliveryReport`], and record that it has been told?
+///
+/// Every window while `packets_received` is ZERO — that is the state the host escalates on, and it
+/// must keep hearing it — then exactly ONCE more when the first packets land, so the host learns
+/// delivery works and can stop hedging its stall diagnosis. Silent after that: a host that predates
+/// the message logs every unknown control message, and a healthy hours-long session must not fill
+/// its log with them.
+fn should_report_delivery(packets_received: u64, confirmed: &mut bool) -> bool {
+    let owed = packets_received == 0 || !*confirmed;
+    *confirmed = packets_received > 0;
+    owed
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    /// The host must keep hearing "zero" for as long as it is true (that is the black-screen
+    /// signal), get exactly one confirmation when video starts, and then silence — the noise budget
+    /// on an older host, which warns per unknown message, is what pays for the first two.
+    #[test]
+    fn the_delivery_count_is_reported_while_zero_then_once_more_and_never_again() {
+        let mut confirmed = false;
+        // Nothing arriving: reported every window, for as long as it stays true.
+        for _ in 0..5 {
+            assert!(
+                should_report_delivery(0, &mut confirmed),
+                "a dead data plane must be re-reported every window"
+            );
+        }
+        // First packets land: one confirmation, so the host can name the other failure confidently.
+        assert!(should_report_delivery(500, &mut confirmed));
+        // Healthy from here: silent.
+        for n in [900, 1_200, 90_000] {
+            assert!(
+                !should_report_delivery(n, &mut confirmed),
+                "a healthy session must not stream delivery reports"
+            );
+        }
+    }
+
+    /// A session that never receives anything must never look confirmed, no matter how long it runs
+    /// — the whole point is that the host keeps being told.
+    #[test]
+    fn a_session_that_receives_nothing_never_reports_itself_healthy() {
+        let mut confirmed = false;
+        for _ in 0..100 {
+            assert!(should_report_delivery(0, &mut confirmed));
+            assert!(!confirmed);
+        }
+    }
+
     #[test]
     fn a_pipeline_gap_is_taken_exactly_once() {
         let slot = AtomicU32::new(0);
@@ -935,8 +1010,8 @@ mod tests {
             .expect("the window after the gap reports on schedule");
         assert!(
             matches!(reported, Some(CtrlRequest::Loss(_))),
-            "the window after the gap must produce a loss report — an idle session's only \
-             outbound request"
+            "the window after the gap must produce a loss report — the first of the two requests \
+             an idle session makes (the delivery count follows it)"
         );
         assert!(
             started.elapsed() >= Duration::from_millis(1_400),

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

@@ -97,6 +97,33 @@ pub struct LossReport {
     pub loss_ppm: u32,
 }
 
+/// `client → host`, sent immediately after each [`LossReport`]: data-plane packets this client has
+/// received all session, cumulative.
+///
+/// ⚠ Exists because `loss_ppm` alone is **ambiguous at zero**: a client receiving a flawless stream
+/// and a client receiving *nothing at all* both report `loss_ppm = 0` — loss is a ratio over a
+/// window whose denominator is the packets that arrived, so no-packets is indistinguishable from
+/// no-loss. That ambiguity let a host decay adaptive FEC to its floor while the client sat behind a
+/// black screen having received zero bytes, and the host's own stall diagnosis blamed the client for
+/// "not sustaining the stream" it had never been sent (field 2026-08-20: a Windows host whose
+/// per-session data port was closed inbound, so the client's hole-punch never opened the return
+/// path). `0` while the host has sent frames is the one unambiguous statement of "the video data
+/// plane is not reaching me" — the control plane carrying this report is, by construction, healthy.
+///
+/// ⚠ A SEPARATE MESSAGE rather than a field appended to [`LossReport`], and that is load-bearing:
+/// `LossReport::decode` length-checks EXACTLY, so a longer report is rejected outright by every host
+/// already shipped — a new client would silently lose adaptive FEC against them. Mixed versions are
+/// normal here (the field case that motivated this ran a current host against a months-old client),
+/// so the compatible shape is a new type byte an older host simply ignores, exactly as it already
+/// ignores every other control message it predates.
+///
+/// Cumulative, not per-window, so a single message is self-contained; `u64` to match the counter it
+/// mirrors, with no saturation to reason about.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct DeliveryReport {
+    pub packets_received: u64,
+}
+
 /// `client → host`, any time after [`Start`]: reconfigure the encoder to a new target bitrate
 /// without reconnecting — the mid-stream lever of adaptive bitrate. The host clamps the request
 /// exactly like [`Hello::bitrate_kbps`] (its `[MIN, MAX]` band; `0` → host default), answers with
@@ -270,6 +297,8 @@ pub const MSG_SHARD_PAYLOAD_ACK: u8 = 0x09;
 /// and [`BitrateChanged`] already feed. Deliberately NOT in the 0x30 clock block — it carries a
 /// duration precisely so that no clock domain is involved.
 pub const MSG_PIPELINE_GAP: u8 = 0x0A;
+/// Type byte of [`DeliveryReport`].
+pub const MSG_DELIVERY_REPORT: u8 = 0x0B;
 /// Type byte of [`ProbeRequest`].
 pub const MSG_PROBE_REQUEST: u8 = 0x20;
 /// Type byte of [`ProbeResult`].
@@ -436,6 +465,26 @@ impl LossReport {
     }
 }
 
+impl DeliveryReport {
+    pub fn encode(&self) -> Vec<u8> {
+        // magic[0..4] type[4] packets_received[5..13]
+        let mut b = Vec::with_capacity(13);
+        b.extend_from_slice(CTL_MAGIC);
+        b.push(MSG_DELIVERY_REPORT);
+        b.extend_from_slice(&self.packets_received.to_le_bytes());
+        b
+    }
+
+    pub fn decode(b: &[u8]) -> Result<DeliveryReport> {
+        if b.len() != 13 || &b[0..4] != CTL_MAGIC || b[4] != MSG_DELIVERY_REPORT {
+            return Err(PunktfunkError::InvalidArg("bad DeliveryReport"));
+        }
+        Ok(DeliveryReport {
+            packets_received: u64::from_le_bytes(b[5..13].try_into().unwrap()),
+        })
+    }
+}
+
 impl SetBitrate {
     pub fn encode(&self) -> Vec<u8> {
         // magic[0..4] type[4] bitrate_kbps[5..9]
@@ -1291,6 +1340,41 @@ mod tests {
         .is_err());
     }
 
+    #[test]
+    fn delivery_report_roundtrip() {
+        for packets_received in [0u64, 1, 9_999, u32::MAX as u64 + 1, u64::MAX] {
+            let r = DeliveryReport { packets_received };
+            assert_eq!(DeliveryReport::decode(&r.encode()).unwrap(), r);
+        }
+        assert!(DeliveryReport::decode(&RequestKeyframe.encode()).is_err());
+        assert!(DeliveryReport::decode(&LossReport { loss_ppm: 0 }.encode()).is_err());
+    }
+
+    /// The delivery count MUST NOT ride on [`LossReport`]: that message is length-checked EXACTLY,
+    /// so lengthening it would make every already-shipped host reject the loss reports its adaptive
+    /// FEC runs on — a silent regression for a new client against an old host, which is the normal
+    /// mixed-version case here (the field report that motivated this ran a current host against a
+    /// months-old client). Its own type byte keeps `LossReport` byte-identical while an older host
+    /// simply ignores the message it does not know.
+    #[test]
+    fn the_delivery_count_does_not_disturb_the_loss_report_wire_form() {
+        let loss = LossReport { loss_ppm: 42 }.encode();
+        assert_eq!(loss.len(), 9, "LossReport must stay the 9-byte wire form");
+        assert_eq!(loss[4], MSG_LOSS_REPORT);
+
+        let delivery = DeliveryReport {
+            packets_received: 0,
+        }
+        .encode();
+        assert_ne!(
+            delivery[4], MSG_LOSS_REPORT,
+            "a distinct type byte is what makes an old host ignore it instead of failing"
+        );
+        // Neither can be silently mis-parsed as the other.
+        assert!(LossReport::decode(&delivery).is_err());
+        assert!(DeliveryReport::decode(&loss).is_err());
+    }
+
     #[test]
     fn window_loss_ppm_estimates_and_caps() {
         // No traffic → 0. A clean window (nothing recovered) → 0.

crates/punktfunk-host/src/gamelease.rs

@@ -114,9 +114,18 @@ pub enum LeaseKind {
     Child,
     /// A launcher owns the game; it is recognized by its [`DetectSpec`].
     Matched,
-    /// Nothing identifies this title's process — no detect signals and no child we own. Both
-    /// lifetime behaviors stay inert for it, and the host says so once in the log rather than
-    /// guessing.
+    /// A launcher owns the game and **tells us** when it starts and stops
+    /// ([`crate::runstate`]) — no process signal of our own.
+    ///
+    /// The one lease kind whose liveness the host does not determine for itself, and the answer to
+    /// a title that has nothing to scan for: Playnite launches an emulated or manually-added game
+    /// through its own tracking and reports the edges, where the host could see only a
+    /// `playnite://` forwarder exiting. Before this such a title was [`Untracked`](Self::Untracked)
+    /// — the honest answer at the time, and a dead end.
+    Reported,
+    /// Nothing identifies this title's process — no detect signals, no child we own, and no
+    /// provider reporting on it. Both lifetime behaviors stay inert for it, and the host says so
+    /// once in the log rather than guessing.
     Untracked,
 }
 
@@ -126,6 +135,7 @@ impl LeaseKind {
             Self::Nested => "nested",
             Self::Child => "child",
             Self::Matched => "matched",
+            Self::Reported => "reported",
             Self::Untracked => "untracked",
         }
     }
@@ -387,6 +397,12 @@ pub fn open(req: LeaseRequest, on_exit: OnExit) -> GameLease {
         LeaseKind::Child
     } else if !spec.is_empty() {
         LeaseKind::Matched
+    } else if crate::runstate::speaks_for(game.id.as_deref()) {
+        // Nothing to scan for, but the provider that published this title is reporting liveness for
+        // it — so it is tracked after all. Asked once, here, rather than every poll: a lease's kind
+        // is what decides whether it is watched at all, and a title that flipped kind mid-flight
+        // would make both lifetime behaviors depend on a plugin's uptime.
+        LeaseKind::Reported
     } else {
         LeaseKind::Untracked
     };
@@ -551,6 +567,27 @@ fn watch(
         s.is_some_and(|p| !scanner.alive(&[p]).is_empty())
     };
 
+    // What this title's provider says about it, when one reports at all ([`crate::runstate`]) —
+    // `None` on every host with no reporting plugin, which is what keeps all of this inert until
+    // someone opts in. Re-read each poll rather than captured: the whole value of it is that it
+    // changes while the lease is alive.
+    let reported = || shared.game.id.as_deref().and_then(crate::runstate::opinion);
+
+    // What a `Child` lease falls back to once its child turns out to be a shim: the store's own
+    // signals, else the provider's reporting, else nothing. The same ladder [`open`] walks, minus
+    // the child that has just gone away — and the reason a hint-less Playnite title is tracked at
+    // all on Windows, where the launch is `explorer.exe "playnite://…"` and therefore ALWAYS a
+    // hand-off, so every such lease arrives here.
+    let fallback_kind = || {
+        if !shared.spec.is_empty() {
+            LeaseKind::Matched
+        } else if crate::runstate::speaks_for(shared.game.id.as_deref()) {
+            LeaseKind::Reported
+        } else {
+            LeaseKind::Untracked
+        }
+    };
+
     // ---- Phase 1: wait for the game to show up. ----
     let start_deadline = spawned_at + START_GRACE;
     loop {
@@ -567,8 +604,10 @@ fn watch(
             && !spawned_up(&spawned)
         {
             spawned = None;
-            if spawned_at.elapsed() < SHIM_WINDOW {
-                if shared.spec.is_empty() {
+            let quick = spawned_at.elapsed() < SHIM_WINDOW;
+            kind = fallback_kind();
+            if quick {
+                if matches!(kind, LeaseKind::Untracked) {
                     tracing::info!(
                         title = %shared.game.title,
                         "the launch command exited immediately (a launcher handing off) and this \
@@ -582,11 +621,10 @@ fn watch(
                 }
                 tracing::debug!(
                     title = %shared.game.title,
-                    "the launch command handed off and exited — recognizing the game by its store \
-                     signals instead"
+                    kind = kind.as_str(),
+                    "the launch command handed off and exited — recognizing the game another way"
                 );
-                kind = LeaseKind::Matched;
-            } else if shared.spec.is_empty() {
+            } else if matches!(kind, LeaseKind::Untracked) {
                 // It ran long enough to have BEEN the game, and nothing else identifies it.
                 shared.was_running.store(true, Ordering::Relaxed);
                 finish(&shared, &on_exit, "the launched process exited");
@@ -604,31 +642,30 @@ fn watch(
                     shared.forget_child();
                     if quick && status.success() {
                         // A launcher that handed the game off and exited. Fall back to recognizing
-                        // the game by its store's signals; with none, stop tracking entirely rather
-                        // than pretend the shim's exit was the game's.
-                        kind = if shared.spec.is_empty() {
+                        // the game by its store's signals (or its provider's reporting); with
+                        // neither, stop tracking entirely rather than pretend the shim's exit was
+                        // the game's.
+                        kind = fallback_kind();
+                        if matches!(kind, LeaseKind::Untracked) {
                             tracing::info!(
                                 title = %shared.game.title,
                                 "the launch command exited immediately (a launcher handing off) and \
                                  this title has no detect signals — stopping game tracking for it"
                             );
-                            LeaseKind::Untracked
-                        } else {
-                            tracing::debug!(
-                                title = %shared.game.title,
-                                "the launch command handed off and exited — recognizing the game by \
-                                 its store signals instead"
-                            );
-                            LeaseKind::Matched
-                        };
-                        if matches!(kind, LeaseKind::Untracked) {
                             shared.set_state(GameState::Untracked);
                             return;
                         }
+                        tracing::debug!(
+                            title = %shared.game.title,
+                            kind = kind.as_str(),
+                            "the launch command handed off and exited — recognizing the game \
+                             another way"
+                        );
                     } else {
                         // It ran long enough to have BEEN the game (or failed outright). Either way
                         // the game is gone; only a success after a real run counts as "played".
-                        if shared.spec.is_empty() {
+                        kind = fallback_kind();
+                        if matches!(kind, LeaseKind::Untracked) {
                             if spawned_at.elapsed() >= SHIM_WINDOW {
                                 shared.was_running.store(true, Ordering::Relaxed);
                                 finish(&shared, &on_exit, "the launched process exited");
@@ -642,11 +679,7 @@ fn watch(
                 Some(Err(e)) => {
                     tracing::debug!(error = %e, "could not poll the launched child — falling back to scanning");
                     child = None;
-                    kind = if shared.spec.is_empty() {
-                        LeaseKind::Untracked
-                    } else {
-                        LeaseKind::Matched
-                    };
+                    kind = fallback_kind();
                     if matches!(kind, LeaseKind::Untracked) {
                         shared.set_state(GameState::Untracked);
                         return;
@@ -680,7 +713,12 @@ fn watch(
             && (child.is_some() || spawned.is_some())
             && spawned_at.elapsed() >= SHIM_WINDOW;
         let live = scanner.find(&shared.spec, shared.launch_stamp);
-        if !live.is_empty() || child_alive {
+        // A provider saying so is as good as seeing it — better, for a title there is nothing to
+        // see: it is the launcher that started the game telling us it did. This is the only way a
+        // [`LeaseKind::Reported`] lease ever leaves this phase, and for a `Matched` one it just
+        // gets there sooner than the scan would.
+        let said_running = reported().is_some_and(|l| l.running);
+        if !live.is_empty() || child_alive || said_running {
             known = live.clone();
             publish(&live);
             shared.was_running.store(true, Ordering::Relaxed);
@@ -754,6 +792,27 @@ fn watch(
             gone_since = None;
             vetoed = false;
             shared.last_seen_ms.store(now_ms(), Ordering::Relaxed);
+        } else if let Some(said) = reported() {
+            // Nothing of the game is visible to us, but its provider is still reporting on it — and
+            // that report is decisive in BOTH directions, where `running_hint` below may only ever
+            // delay an exit.
+            //
+            // The difference is what backs each claim. Steam's registry flag is a leftover that
+            // survives an unclean exit, so believing it indefinitely produces a session that never
+            // ends; a provider report is an event from the launcher that started the game, restated
+            // continuously, and it stops counting the moment it goes stale
+            // ([`crate::runstate::REPORT_TTL`]) — after which this branch simply stops being taken
+            // and the scan-only path below resumes. So a *live* provider is allowed to hold the
+            // session open for a game the host cannot see at all, which is the entire point for a
+            // title with no detect signals, and a dead one costs at most one TTL.
+            if said.running {
+                gone_since = None;
+                vetoed = false;
+                shared.last_seen_ms.store(now_ms(), Ordering::Relaxed);
+            } else {
+                finish(&shared, &on_exit, "its provider reported the game stopped");
+                return;
+            }
         } else {
             // How long the game's processes have been CONTINUOUSLY absent. Deliberately not reset by
             // the veto below — letting it run on is exactly what bounds the veto.
@@ -909,7 +968,7 @@ fn terminate_blocking(shared: &LeaseShared) {
                 "released the nested session's kept display to end its game"
             );
         }
-        LeaseKind::Child | LeaseKind::Matched => {
+        LeaseKind::Child | LeaseKind::Matched | LeaseKind::Reported => {
             #[cfg(target_os = "linux")]
             unix_term_ladder(shared);
             #[cfg(windows)]
@@ -919,6 +978,26 @@ fn terminate_blocking(shared: &LeaseShared) {
     }
 }
 
+/// The process this lease's provider reports for its game, re-resolved and pinned to its start
+/// time, or `None`.
+///
+/// The reason the wire carries a pid at all: for a [`LeaseKind::Reported`] title the matcher finds
+/// nothing by construction, so without this "End" would have no target and would silently do
+/// nothing — the exact failure a spawned pid was folded into the Windows ladder to fix. Resolved at
+/// the moment of use rather than stored on the lease, so a report that has since gone stale, or a
+/// pid the kernel has since recycled, contributes nothing.
+#[cfg(any(target_os = "linux", windows))]
+fn reported_proc(shared: &LeaseShared) -> Option<crate::procscan::ProcRef> {
+    let pid = shared
+        .game
+        .id
+        .as_deref()
+        .and_then(crate::runstate::opinion)
+        .filter(|l| l.running)?
+        .pid?;
+    crate::procscan::resolve(pid)
+}
+
 /// SIGTERM everything that belongs to the game, wait, then SIGKILL whatever ignored it.
 ///
 /// Every pid is re-verified against its recorded start time immediately before each signal, so a pid
@@ -942,11 +1021,22 @@ fn unix_term_ladder(shared: &LeaseShared) {
         // `OwnedChild::group_leader`) — never for a child sharing the host's own group.
         unsafe { libc::kill(target, sig) == 0 }
     };
+    // Everything the matcher can find, plus the pid the provider reported (see `reported_proc`) —
+    // which for a `Reported` lease is the only member of this set.
+    let targets = || {
+        let mut procs = scanner.find(&shared.spec, shared.launch_stamp);
+        if let Some(p) = reported_proc(shared) {
+            if !procs.iter().any(|q| q.pid == p.pid) {
+                procs.push(p);
+            }
+        }
+        procs
+    };
     let signal_matched = |sig: i32| -> usize {
         // Re-scan and re-verify immediately before signalling, so a pid recycled since the last
         // sweep is never hit.
         scanner
-            .alive(&scanner.find(&shared.spec, shared.launch_stamp))
+            .alive(&targets())
             .into_iter()
             // SAFETY: as above, for a single pid just re-verified to be the process we adopted.
             .filter(|p| unsafe { libc::kill(p.pid as i32, sig) == 0 })
@@ -965,9 +1055,7 @@ fn unix_term_ladder(shared: &LeaseShared) {
     let deadline = Instant::now() + TERM_GRACE;
     while Instant::now() < deadline {
         std::thread::sleep(POLL);
-        let still = scanner
-            .alive(&scanner.find(&shared.spec, shared.launch_stamp))
-            .len();
+        let still = scanner.alive(&targets()).len();
         // Signal 0 only probes for existence — the child (or its group) is gone once it fails.
         let child_gone = !signal_child(0);
         if still == 0 && child_gone {
@@ -1000,11 +1088,19 @@ fn windows_term_ladder(shared: &LeaseShared) {
     let live = || {
         let mut procs = scanner.alive(&scanner.find(&shared.spec, shared.launch_stamp));
         // Re-verified like everything else, so a dead or recycled pid contributes nothing, and
-        // de-duplicated: the matcher may well have found this same process by its image.
-        if let Some(p) = shared.spawned {
+        // de-duplicated: the matcher may well have found this same process by its image. The
+        // provider's reported pid joins on the same terms, and for a `Reported` lease it is the
+        // only thing here (see `reported_proc`).
+        let mut fold = |p: crate::procscan::ProcRef| {
             if !scanner.alive(&[p]).is_empty() && !procs.iter().any(|q| q.pid == p.pid) {
                 procs.push(p);
             }
+        };
+        if let Some(p) = shared.spawned {
+            fold(p);
+        }
+        if let Some(p) = reported_proc(shared) {
+            fold(p);
         }
         procs
     };
@@ -1570,6 +1666,54 @@ mod tests {
         assert!(!l.shared().is_trackable());
     }
 
+    /// A title with nothing to scan for is tracked after all when its provider reports on it.
+    ///
+    /// This is the Playnite case the static `detect` hints could never reach: an emulated game, a
+    /// manually added one, a library plugin that records no install directory. The launch is a
+    /// `playnite://` hand-off, so the host holds nothing; the spec is empty, so the matcher finds
+    /// nothing; and the honest verdict used to be [`LeaseKind::Untracked`] — no exit detection, and
+    /// `POST /game/end` with nothing to aim at. Playnite knew the whole time.
+    #[test]
+    fn a_reported_title_is_tracked_where_it_used_to_be_untracked() {
+        // The same request with no provider reporting: unchanged, and the control for what follows.
+        let l = open(
+            req("playnite:lease-test", DetectSpec::default(), false),
+            Box::new(|| {}),
+        );
+        assert!(matches!(l.shared().kind(), LeaseKind::Untracked));
+        assert!(!l.shared().is_trackable());
+        drop(l);
+
+        // A provider that speaks for the title — while reporting it NOT running, which is exactly
+        // what a report looks like at the moment a game is launched. Trackability follows from the
+        // provider *reporting*, not from what it currently says; a lease whose kind flipped with
+        // the answer would make both lifetime behaviours depend on a plugin's timing.
+        crate::runstate::report(
+            "playnite-lease-test",
+            ["playnite:lease-test".to_string()].into_iter().collect(),
+            std::collections::HashMap::new(),
+        );
+        let l = open(
+            req("playnite:lease-test", DetectSpec::default(), false),
+            Box::new(|| {}),
+        );
+        assert!(matches!(l.shared().kind(), LeaseKind::Reported));
+        assert!(
+            l.shared().is_trackable(),
+            "so its exit is noticed and `POST /game/end` has a target"
+        );
+        drop(l);
+        crate::runstate::forget("playnite-lease-test");
+
+        // …and once the provider is gone, so is the tracking. Pinned because a report that outlived
+        // its plugin is the one way this could hold a session open forever.
+        let l = open(
+            req("playnite:lease-test", DetectSpec::default(), false),
+            Box::new(|| {}),
+        );
+        assert!(matches!(l.shared().kind(), LeaseKind::Untracked));
+    }
+
     #[test]
     fn an_untracked_lease_is_never_terminated() {
         let l = open(

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

@@ -30,7 +30,7 @@
 use super::{AppState, CONTROL_PORT};
 use crate::inject::gamepad::GamepadManager;
 use anyhow::{anyhow, Context, Result};
-use punktfunk_core::input::InputEvent;
+use punktfunk_core::input::{GamepadEvent, InputEvent};
 use punktfunk_core::quic::{classify, GrantClass, HdrMeta, GRANT_ALL};
 use rusty_enet::{Event, Host, HostSettings, Packet, PeerID};
 use std::net::UdpSocket;
@@ -229,6 +229,65 @@ fn permitted(mask: u32, class: GrantClass, drops: &mut GrantDrops) -> bool {
     false
 }
 
+/// The virtual Xbox pad a Moonlight session presents, and the one place this plane decides which
+/// backend builds it.
+///
+/// On Windows there are two, and they are not interchangeable to a game: the XUSB companion
+/// registers only `GUID_DEVINTERFACE_XUSB` and exposes no HID collection, so Steam's hidapi
+/// enumeration, SDL, RawInput, DirectInput, `joy.cpl` and WGI/GameInput cannot see it at all —
+/// only classic `XInputGetState` can. The native plane made the HID pad its default on
+/// 2026-08-09 for exactly that reason; this plane kept constructing
+/// [`GamepadManager`](crate::inject::gamepad::GamepadManager) directly and so kept handing
+/// Moonlight clients a pad most games cannot enumerate. Both planes now read the same knob —
+/// `native::gamepad::windows_xbox_hid` (not an intra-doc link: it is `cfg(windows)`, so the link
+/// would not resolve on any other target) — so `PUNKTFUNK_XBOX_BACKEND=xusb` reverts both
+/// together and neither can drift again.
+///
+/// Everywhere else the choice does not exist: Linux has one uinput X-Box pad, and the stub
+/// backend on other platforms drops events.
+enum SessionPads {
+    /// Linux uinput / the Windows XUSB companion — `crate::inject::gamepad`.
+    Xusb(GamepadManager),
+    /// The Windows UMDF HID Xbox pad, what the native plane builds by default.
+    #[cfg(target_os = "windows")]
+    Hid(crate::inject::xbox_windows::XboxWindowsManager),
+}
+
+impl SessionPads {
+    /// Build this session's pad manager, honoring the shared Windows backend knob.
+    fn new() -> SessionPads {
+        #[cfg(target_os = "windows")]
+        if crate::native::gamepad::windows_xbox_hid() {
+            return SessionPads::Hid(crate::inject::xbox_windows::XboxWindowsManager::new());
+        }
+        SessionPads::Xusb(GamepadManager::new())
+    }
+
+    /// Apply one decoded controller event (create/destroy by mask, then state).
+    fn handle(&mut self, ev: &GamepadEvent) {
+        match self {
+            SessionPads::Xusb(m) => m.handle(ev),
+            #[cfg(target_os = "windows")]
+            SessionPads::Hid(m) => m.handle(ev),
+        }
+    }
+
+    /// Service the pads' feedback protocol and relay changed rumble levels. Games block inside the
+    /// kernel/driver handshake until answered, so call this every tick.
+    ///
+    /// The HID pad's rich-feedback plane is discarded rather than plumbed: an Xbox pad has no
+    /// lightbar or adaptive triggers to report, and GameStream has no vocabulary for one either —
+    /// its rumble message (`0x010B`, [`super::gamepad::rumble_plaintext`]) carries the two handle
+    /// motors and nothing else, which is also why the trigger levels are dropped at the call site.
+    fn pump_rumble(&mut self, rumble: impl FnMut(u16, u16, u16, u16, u16)) {
+        match self {
+            SessionPads::Xusb(m) => m.pump_rumble(rumble),
+            #[cfg(target_os = "windows")]
+            SessionPads::Hid(m) => m.pump(rumble, |_| {}),
+        }
+    }
+}
+
 /// Reconcile the control port to the paired-client list: bound while at least one pairing
 /// exists, closed when none remain. Idempotent and race-free (see [`Gate::running`]); call it
 /// wherever the paired list changes — startup, pairing phase 4, unpair.
@@ -362,7 +421,7 @@ fn spawn(state: Arc<AppState>) -> Result<Running> {
             // by every outbound message (rumble + the HDR-mode signal): the GCM nonce is derived
             // from `seq`, so a per-message-type counter would reuse (key, nonce) pairs across
             // message types in the host direction.
-            let mut pads = GamepadManager::new();
+            let mut pads = SessionPads::new();
             // Pen/touch translator (SS_PEN/SS_TOUCH → virtual tablet / wire touch). Sent only
             // by clients that saw our SS_FF_PEN_TOUCH_EVENTS feature flag (rtsp.rs).
             let mut pointer = super::pen::GsPointer::new();
@@ -480,7 +539,7 @@ fn spawn(state: Arc<AppState>) -> Result<Running> {
                                 hdr_sent = false;
                                 // Unplug the session's virtual pads + tablet (destroying the
                                 // uinput pen releases any held tool/tip kernel-side).
-                                pads = GamepadManager::new();
+                                pads = SessionPads::new();
                                 pointer = super::pen::GsPointer::new();
                                 // Surface the session's enforcement-drop totals (WP13).
                                 drops.end_of_session();
@@ -583,7 +642,7 @@ fn spawn(state: Arc<AppState>) -> Result<Running> {
                         detected = None;
                         decrypt_fails = 0;
                         hdr_sent = false;
-                        pads = GamepadManager::new();
+                        pads = SessionPads::new();
                         pointer = super::pen::GsPointer::new();
                         drops.end_of_session();
                     }
@@ -689,7 +748,7 @@ fn on_receive(
     detected: &mut Option<Scheme>,
     decrypt_fails: &mut u64,
     inj_tx: &Sender<InputEvent>,
-    pads: &mut GamepadManager,
+    pads: &mut SessionPads,
     pointer: &mut super::pen::GsPointer,
     grants: u32,
     drops: &mut GrantDrops,

crates/punktfunk-host/src/main.rs

@@ -105,6 +105,9 @@ mod plugins;
 // session⇄game lifetime binding (design/session-game-lifetime.md §4). Per-OS matchers inside; on a
 // platform with neither (macOS, which has no launch path either) the module is an empty shell.
 mod procscan;
+// The live half of the same binding: what a provider PLUGIN reports about its titles' liveness,
+// where `procscan` can only look at the process table.
+mod runstate;
 mod send_pacing;
 #[cfg(target_os = "windows")]
 #[path = "windows/service.rs"]

crates/punktfunk-host/src/mgmt.rs

@@ -372,6 +372,7 @@ fn api_router_parts() -> (Router<Arc<MgmtState>>, utoipa::openapi::OpenApi) {
             library::reconcile_provider_entries,
             library::delete_provider_entries
         ))
+        .routes(routes!(library::report_provider_running))
         .routes(routes!(library::get_library_art))
         .routes(routes!(stats::stats_capture_start))
         .routes(routes!(stats::stats_capture_stop))

crates/punktfunk-host/src/mgmt/auth.rs

@@ -250,6 +250,10 @@ pub(crate) fn plugin_may_access(method: &Method, path: &str) -> bool {
         (&Method::DELETE, "/api/v1/library/custom/{}"),
         (&Method::PUT, "/api/v1/library/provider/{}"),
         (&Method::DELETE, "/api/v1/library/provider/{}"),
+        // Liveness reporting for a provider's OWN titles. No new authority: the host maps the
+        // report through the catalog, so a plugin can only ever speak about entries it published,
+        // and the worst a defective one can do to someone else's session is nothing at all.
+        (&Method::PUT, "/api/v1/library/provider/{}/running"),
         // Stats / telemetry.
         (&Method::POST, "/api/v1/stats/capture/start"),
         (&Method::POST, "/api/v1/stats/capture/stop"),

crates/punktfunk-host/src/mgmt/library.rs

@@ -607,12 +607,130 @@ pub(crate) async fn delete_provider_entries(Path(provider): Path<String>) -> Res
             if removed > 0 {
                 tracing::info!(provider, removed, "library provider entries removed");
             }
+            // Its entries are gone, so its opinions about them are meaningless — and a lease must
+            // never be held open by a provider that no longer exists.
+            crate::runstate::forget(&provider);
             Json(ProviderRemoved { removed }).into_response()
         }
         Err(e) => api_error(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string()),
     }
 }
 
+/// One running title in a provider's liveness report.
+#[derive(Deserialize, ToSchema)]
+pub(crate) struct RunningTitle {
+    /// The provider's own stable id for the title — the same key its reconcile payload uses.
+    pub external_id: String,
+    /// The process id the provider started for it, when it knows one. Optional, and never trusted
+    /// as a bare number: the host re-resolves it and pins it to its start time before it is ever
+    /// signalled, so a stale or recycled pid simply contributes nothing.
+    #[serde(default)]
+    pub pid: Option<u32>,
+}
+
+/// Request body for `reportProviderRunning`.
+#[derive(Deserialize, ToSchema)]
+pub(crate) struct ProviderRunningInput {
+    /// Every title of this provider's that is running **right now**. The full set, not a delta:
+    /// anything absent from it is reported as stopped.
+    #[serde(default)]
+    pub running: Vec<RunningTitle>,
+}
+
+/// The result of a liveness report.
+#[derive(Serialize, ToSchema)]
+pub(crate) struct ProviderRunningAccepted {
+    /// How many reported titles matched an entry this provider currently publishes.
+    matched: usize,
+    /// How many were ignored because no such entry exists (a report that raced a reconcile).
+    unknown: usize,
+    /// Seconds this report stays authoritative without being restated — re-report inside it while
+    /// anything is running.
+    ttl_s: u64,
+}
+
+/// Report which of a provider's titles are running
+///
+/// The **live** counterpart to the `detect` hints in a reconcile payload: that one says *how to
+/// recognize* a title's process, this one says *it is running now* (design §9,
+/// [`crate::runstate`]). For a provider that starts games itself and knows when they stop —
+/// Playnite tracks every launch and fires an event on both edges — this is a fact the host would
+/// otherwise have to re-derive by scanning, and for a title with nothing to scan for (an emulated
+/// game, a manually added one) could not derive at all.
+///
+/// Declarative and idempotent, like the reconcile: the body is the provider's **complete** running
+/// set, so a missed event, a plugin restart or an install mid-game all self-correct on the next
+/// report rather than drifting.
+///
+/// The report **expires** after `ttl_s` (90s) unless restated, which is what makes it safe for a
+/// live provider to keep a streaming session open for a game the host cannot see: a plugin that
+/// dies with a game running stops counting shortly after, and the host falls back to process
+/// scanning exactly as it does without one. Re-report on every change **and** on a timer well
+/// inside the window.
+///
+/// Titles the provider does not currently publish are ignored (counted in `unknown`), not an error:
+/// a report may legitimately race its own reconcile.
+#[utoipa::path(
+    put,
+    path = "/library/provider/{provider}/running",
+    tag = "library",
+    operation_id = "reportProviderRunning",
+    params(("provider" = String, Path, description = "The provider id ([a-z0-9._-], `manual` reserved)")),
+    request_body = ProviderRunningInput,
+    responses(
+        (status = OK, description = "The report was accepted", body = ProviderRunningAccepted),
+        (status = BAD_REQUEST, description = "Invalid provider id or payload", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn report_provider_running(
+    Path(provider): Path<String>,
+    ApiJson(input): ApiJson<ProviderRunningInput>,
+) -> Response {
+    if let Err(e) = crate::library::validate_provider_name(&provider) {
+        return api_error(StatusCode::BAD_REQUEST, &e);
+    }
+    // Resolve the provider's own keys to the ids the rest of the host uses. A plugin knows its
+    // titles by `external_id`; a lease knows them by the library id the catalog assigned
+    // (`playnite:<guid>`), and only the catalog can map between the two — which is also what makes
+    // this authorization-safe, since a provider can only ever speak about entries it published.
+    let mine: Vec<(String, String)> = crate::library::load_custom()
+        .into_iter()
+        .filter(|e| e.provider.as_deref() == Some(provider.as_str()))
+        .filter_map(|e| {
+            let external = e.external_id.clone()?;
+            Some((external, crate::library::library_id_for(&e)))
+        })
+        .collect();
+    let owned: std::collections::HashSet<String> = mine.iter().map(|(_, id)| id.clone()).collect();
+
+    let mut running = std::collections::HashMap::new();
+    let mut unknown = 0usize;
+    for t in &input.running {
+        match mine.iter().find(|(external, _)| *external == t.external_id) {
+            Some((_, id)) => {
+                running.insert(id.clone(), t.pid);
+            }
+            None => unknown += 1,
+        }
+    }
+    let matched = running.len();
+    tracing::debug!(
+        provider,
+        owned = owned.len(),
+        matched,
+        unknown,
+        "provider liveness report"
+    );
+    crate::runstate::report(&provider, owned, running);
+    Json(ProviderRunningAccepted {
+        matched,
+        unknown,
+        ttl_s: crate::runstate::REPORT_TTL.as_secs(),
+    })
+    .into_response()
+}
+
 /// Fetch one cover-art image for a library entry
 ///
 /// Resolves `kind` (`portrait` | `hero` | `logo` | `header`) for the given library id and streams

crates/punktfunk-host/src/mgmt/tests.rs

@@ -1440,6 +1440,16 @@ fn every_route_is_classified_for_the_plugin_and_cert_lanes() {
         ("DELETE", "/api/v1/library/custom/{id}", true, false),
         ("PUT", "/api/v1/library/provider/{provider}", true, false),
         ("DELETE", "/api/v1/library/provider/{provider}", true, false),
+        // Liveness for a provider's own titles: the plugin lane's, like the reconcile beside it,
+        // and for the same reason — the host maps the report through the catalog, so a provider can
+        // only ever speak about entries it published. Never the cert lane: a streaming client has
+        // no titles of its own to report on.
+        (
+            "PUT",
+            "/api/v1/library/provider/{provider}/running",
+            true,
+            false,
+        ),
         // ---- stats.
         ("POST", "/api/v1/stats/capture/start", true, false),
         ("POST", "/api/v1/stats/capture/stop", true, false),
@@ -2935,3 +2945,54 @@ async fn provider_reconcile_validation() {
     let (s, _) = send(&app, del).await;
     assert_eq!(s, StatusCode::BAD_REQUEST);
 }
+
+/// Liveness reporting: the provider id is validated like every other provider write, and a title
+/// the provider does not publish is *counted*, not refused.
+///
+/// That tolerance is the point. A report races its own reconcile by construction — a game can start
+/// before the entry that describes it has landed — and 400-ing the whole report over one unknown id
+/// would throw away the liveness of every other running title, which is precisely the failure the
+/// launcher-tile 400 taught us to avoid (`sanitize_launcher_entries`). The developer's real catalog
+/// is not touched here, so every id in this test is `unknown` by construction — which is exactly
+/// the case being pinned.
+#[tokio::test]
+async fn provider_running_report_validation() {
+    let app = test_app(test_state(), None);
+    let put = |provider: &str, body: serde_json::Value| {
+        axum::http::Request::put(format!("/api/v1/library/provider/{provider}/running"))
+            .header(axum::http::header::CONTENT_TYPE, "application/json")
+            .body(Body::from(body.to_string()))
+            .unwrap()
+    };
+
+    let (s, json) = send(&app, put("manual", serde_json::json!({"running": []}))).await;
+    assert_eq!(s, StatusCode::BAD_REQUEST);
+    assert!(json["error"].as_str().unwrap().contains("reserved"));
+    let (s, _) = send(&app, put("Bad%2FName", serde_json::json!({"running": []}))).await;
+    assert_eq!(s, StatusCode::BAD_REQUEST);
+
+    // An unreported provider is a legitimate report of "nothing is running".
+    let (s, json) = send(&app, put("playnite", serde_json::json!({"running": []}))).await;
+    assert_eq!(s, StatusCode::OK);
+    assert_eq!(json["matched"], 0);
+    assert_eq!(json["unknown"], 0);
+    assert!(json["ttl_s"].as_u64().unwrap() > 0);
+
+    // An id this provider does not publish is ignored, not an error.
+    let (s, json) = send(
+        &app,
+        put(
+            "playnite",
+            serde_json::json!({"running": [{"external_id": "no-such-title", "pid": 4242}]}),
+        ),
+    )
+    .await;
+    assert_eq!(s, StatusCode::OK);
+    assert_eq!(json["matched"], 0);
+    assert_eq!(json["unknown"], 1);
+
+    // A report leaves no opinion behind about a title nobody published, so nothing this test did
+    // can hold a real lease open.
+    assert!(!crate::runstate::speaks_for(Some("playnite:no-such-title")));
+    crate::runstate::forget("playnite");
+}

crates/punktfunk-host/src/native.rs

@@ -48,8 +48,10 @@ mod compositor;
 use compositor::resolve_compositor;
 
 /// Virtual-gamepad backend resolution (plan §W1); `serve_session` + the `Pads` state machine reach
-/// `resolve_gamepad`/`resolve_pad_kind`/`route_decision` here.
-mod gamepad;
+/// `resolve_gamepad`/`resolve_pad_kind`/`route_decision` here. Crate-visible because the choice of
+/// Windows Xbox backend (`windows_xbox_hid`) is not the native plane's alone — the GameStream plane
+/// presents the same virtual pad and has to make the same choice, from one definition.
+pub(crate) mod gamepad;
 use gamepad::{resolve_gamepad, resolve_pad_kind, route_decision};
 
 /// The SPAKE2 pairing ceremony (plan §W1); `serve_session` dispatches a PairRequest connection here.
@@ -1402,6 +1404,12 @@ async fn serve_session(
     // evidence (a refusal without the score left a 23-minute floor-pinned field session with no
     // trace of why).
     let cadence_behind_score = Arc::new(AtomicU32::new(0));
+    // Delivery truth, control task → data plane: the packet count the client reports having
+    // received all session (`u32::MAX` until a client new enough to answer sends one). The data
+    // plane needs it to tell a clean link from a dead one — `loss_ppm = 0` means both — before it
+    // blames the client for a stream that never reached it.
+    let client_packets_received = Arc::new(AtomicU32::new(u32::MAX));
+    let client_packets_received_ctl = client_packets_received.clone();
     let (probe_tx, probe_rx) = std::sync::mpsc::channel::<ProbeRequest>();
     let (probe_result_tx, probe_result_rx) = tokio::sync::mpsc::unbounded_channel::<ProbeResult>();
     // Mode-switch outcome, data plane → control task (same pattern as `probe_result_tx`): the accept
@@ -1533,6 +1541,7 @@ async fn serve_session(
         encoder_ceiling_kbps.clone(),
         cadence_degraded.clone(),
         cadence_behind_score.clone(),
+        client_packets_received_ctl,
         fec_target_ctl,
         phase_ctl_control,
         reconfig_tx,
@@ -2091,6 +2100,26 @@ async fn serve_session(
                  address with no hole-punch; else punched=true → the client's observed source, \
                  false → no punch seen, the reported address)"
             );
+            // A punch that never arrives is not a routine fallback — it is the fingerprint of a
+            // data port the client cannot reach INBOUND, and every client punches (5/s for the
+            // first three seconds, then every two). Video then goes to an address the client only
+            // CLAIMED, unverified, and if anything on the path needed the flow opened client-first
+            // it silently goes nowhere: black picture, healthy control plane, no error anywhere.
+            // On Windows the usual cause is a firewall rule that opens fixed ports only, while
+            // this port is ephemeral and different every session (fixed by the program-scoped rule
+            // `service install` now adds — an install predating it still has the old rules).
+            // `direct` skips the punch by operator choice, so it is not a failure there.
+            if !direct && !punched {
+                tracing::warn!(
+                    %client_udp,
+                    udp_port,
+                    "no hole-punch reached this host's data port — inbound UDP to it looks \
+                     BLOCKED, so video is being sent to the address the client reported without \
+                     any confirmed return path. If the picture stays black while the session is \
+                     otherwise healthy, this line is the reason: allow inbound UDP for the host \
+                     executable (any port), or pin --data-port and open that one"
+                );
+            }
             let mut session = Session::new(cfg, Box::new(transport))
                 .map_err(|e| anyhow!("host session: {e:?}"))?;
             match source {
@@ -2125,6 +2154,7 @@ async fn serve_session(
                         encoder_ceiling_kbps,
                         cadence_degraded,
                         cadence_behind_score,
+                        client_packets_received,
                         bitrate_auto,
                         bit_depth,
                         chroma,

crates/punktfunk-host/src/native/control.rs

@@ -30,6 +30,10 @@ pub(super) async fn run(
     encoder_ceiling_kbps: Arc<AtomicU32>,
     cadence_degraded: Arc<AtomicBool>,
     cadence_behind_score: Arc<AtomicU32>,
+    // Delivery truth, published from every `DeliveryReport` for the data plane's stall diagnosis:
+    // the packets the client says it has received all session (`u32::MAX` = a client too old to
+    // send one, the pre-seeded value).
+    client_packets_received: Arc<AtomicU32>,
     fec_target_ctl: Arc<AtomicU8>,
     // Phase-locked capture bridge: client PhaseReports land here latest-wins; the encode loop's
     // controller drains at its own ~1 Hz cadence (design/phase-locked-capture.md).
@@ -162,6 +166,16 @@ pub(super) async fn run(
                     if rfi_tx.send((req.first_frame, req.last_frame)).is_err() {
                         break; // data plane gone
                     }
+                } else if let Ok(rep) = punktfunk_core::quic::DeliveryReport::decode(&msg) {
+                    // What the client has actually RECEIVED — published unconditionally, because it
+                    // is what lets the data plane read `loss_ppm = 0` correctly and must survive
+                    // both the `adaptive_fec` opt-out and a pinned FEC percentage (a host with
+                    // PUNKTFUNK_FEC_PCT set is exactly as blind to a dead data plane otherwise).
+                    // Saturated into the u32 bridge; the value only ever matters near zero.
+                    client_packets_received.store(
+                        rep.packets_received.min(u32::MAX as u64 - 1) as u32,
+                        Ordering::Relaxed,
+                    );
                 } else if let Ok(rep) = LossReport::decode(&msg) {
                     // Adaptive FEC: size recovery to the loss the client is seeing. The data-plane
                     // send loop reads `fec_target_ctl` and applies it per frame. Ignored when FEC

crates/punktfunk-host/src/native/gamepad.rs

@@ -363,8 +363,13 @@ fn degrade_xbox_identity(chosen: GamepadPref) -> GamepadPref {
 ///
 /// The two backends are mutually exclusive per pad by construction (one match arm or the other) —
 /// presenting both would hand a game two controllers for one pair of hands.
+///
+/// Read by BOTH input planes. The native plane branches on it in `Pads::handle`; the GameStream
+/// plane in `gamestream::control::SessionPads`. It was `pub(super)` while only the native plane
+/// consulted it, and that is exactly how Moonlight sessions spent two releases on the XUSB pad
+/// after this default flipped — the knob was unreachable from the module that needed it.
 #[cfg(target_os = "windows")]
-pub(super) fn windows_xbox_hid() -> bool {
+pub(crate) fn windows_xbox_hid() -> bool {
     match std::env::var("PUNKTFUNK_XBOX_BACKEND") {
         Ok(v) if v.trim().eq_ignore_ascii_case("xusb") => false,
         // Anything else — unset, empty, "hid", or a typo — takes the default. A misspelled opt-out

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

@@ -1319,6 +1319,14 @@ pub(super) struct SessionContext {
     /// of what held it there — the score is the missing discriminator between "the detector's
     /// budget is wrong" and "this encoder genuinely can't hold cadence").
     pub(super) cadence_behind_score: Arc<AtomicU32>,
+    /// Data-plane packets the CLIENT says it has received all session, from the latest
+    /// [`punktfunk_core::quic::DeliveryReport`] ([`u32::MAX`] = a client too old to send one).
+    ///
+    /// The one signal that distinguishes "the link is clean" from "nothing is arriving": both look
+    /// like `loss_ppm = 0`, because loss is a ratio over the packets that DID arrive. Read by the
+    /// keyframe-cadence diagnosis below, which without it accuses the client of being too slow for
+    /// a stream it has never received a byte of.
+    pub(super) client_packets_received: Arc<AtomicU32>,
     /// The client asked for "Automatic" (`Hello::bitrate_kbps == 0`), so `bitrate_kbps` came from
     /// the host's codec-aware default. For PyroWave that default is the ~1.6 bpp operating point of
     /// the NEGOTIATED MODE (`resolve_bitrate_kbps_for`) — a mid-stream mode switch re-resolves it
@@ -1598,6 +1606,7 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
         encoder_ceiling_kbps,
         cadence_degraded,
         cadence_behind_score,
+        client_packets_received,
         bitrate_auto,
         bit_depth,
         // The resolved chroma is already captured in `plan` (above); ignore the duplicate here.
@@ -3006,16 +3015,65 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
                     // subsystems while the real chain was: client refused the codec → demoted to
                     // a slower decode rung → could not sustain the rate → standing queue.
                     // Perfect periodicity argues FOR a software cooldown, not against it.
-                    if matches_client_flush_cadence(period) {
-                        tracing::warn!(
+                    let client_rx = client_packets_received.load(Ordering::Relaxed);
+                    // The client has TOLD us it has received nothing all session (a v1 client
+                    // leaves the `u32::MAX` seed, so this only fires on an explicit zero). That
+                    // outranks both cadence verdicts below, which are about a client drowning in
+                    // frames — the opposite failure, and indistinguishable by period alone because
+                    // a client that got no picture re-asks on its own no-video timer at very
+                    // nearly the same spacing. Diagnosing this as "too slow" cost a 2026-08-20
+                    // field investigation days: the host was blameless-looking (`sent` climbing,
+                    // `loss_ppm = 0`, FEC decayed to the floor) while not one byte of video ever
+                    // reached the client.
+                    if client_rx == 0 {
+                        tracing::error!(
                             period_s = format!("{:.1}", period.as_secs_f64()),
-                            "client keyframe recoveries match the client's jump-to-live cooldown \
-                             — the CLIENT cannot sustain the stream and is shedding a standing \
-                             receive queue (check its log for 'receive backlog stopped draining' \
-                             with queue_depth, and for a decode rung that demoted); a slower \
-                             decode path or a link below the bitrate does this, and it is NOT a \
-                             host display disturbance"
+                            frames_sent = sent,
+                            "THE VIDEO DATA PLANE IS NOT REACHING THE CLIENT — it reports 0 \
+                             packets received all session while this host has sent the frames \
+                             counted here, so the picture is black and every keyframe we force is \
+                             wasted. The control plane is healthy (this report arrived on it), so \
+                             the session looks alive: audio, input and the library keep working. \
+                             This is a PATH problem, not decode — check that inbound UDP to this \
+                             host's per-session data port is allowed (the 'data plane bound' line \
+                             above shows `punched=false` when the client's hole-punch never \
+                             arrived, which is the fingerprint), and that no other host or \
+                             firewall is intercepting it"
                         );
+                    } else if matches_client_recovery_cooldown(period) {
+                        if client_rx == u32::MAX {
+                            // This client predates the delivery count, so the period alone has to
+                            // carry the verdict — and it CANNOT: both client cooldowns live in this
+                            // band and they mean opposite things. Say so instead of picking one.
+                            // The old confident wording sent a field investigation after the
+                            // decoder for days while the real fault was that nothing arrived.
+                            tracing::warn!(
+                                period_s = format!("{:.1}", period.as_secs_f64()),
+                                frames_sent = sent,
+                                "client keyframe recoveries land on a client software cooldown, \
+                                 but this client is too old to report whether any video reached \
+                                 it — so this is EITHER a client that cannot sustain the stream \
+                                 and is shedding a standing receive queue, OR a client that has \
+                                 received nothing at all and is re-asking on its no-video timer. \
+                                 They are opposite faults; the host cannot tell them apart from \
+                                 the period. Its log does: 'receive backlog stopped draining' \
+                                 (with queue_depth) means the first, 'no video received … into \
+                                 the session' means the second. Upgrading the client makes this \
+                                 line decide on its own"
+                            );
+                        } else {
+                            tracing::warn!(
+                                period_s = format!("{:.1}", period.as_secs_f64()),
+                                client_packets_received = client_rx,
+                                "client keyframe recoveries match the client's jump-to-live \
+                                 cooldown, and it confirms video IS arriving — the CLIENT cannot \
+                                 sustain the stream and is shedding a standing receive queue \
+                                 (check its log for 'receive backlog stopped draining' with \
+                                 queue_depth, and for a decode rung that demoted); a slower \
+                                 decode path or a link below the bitrate does this, and it is NOT \
+                                 a host display disturbance"
+                            );
+                        }
                     } else {
                         tracing::warn!(
                             period_s = format!("{:.1}", period.as_secs_f64()),
@@ -4191,6 +4249,26 @@ fn matches_client_flush_cadence(period: std::time::Duration) -> bool {
     period.abs_diff(flush) < flush / 10
 }
 
+/// The client's OTHER re-ask cooldown: it has received no video whatsoever and is asking for a
+/// keyframe on its no-video timer. Kept separate from [`matches_client_flush_cadence`] because the
+/// two describe opposite faults — drowning in frames versus receiving none — and only the client's
+/// reported delivery count can say which. Both are host-side-irrelevant either way: a fixed
+/// software cooldown is never the periodic *disturbance* the metronomic branch reports.
+///
+/// Compared against the SHARED constant, never a copy of the number — the same discipline
+/// [`matches_client_flush_cadence`] follows, and the one that was missing when the two cooldowns
+/// were both 2000 ms and the host could not even tell that it was guessing.
+fn matches_client_no_video_cadence(period: std::time::Duration) -> bool {
+    let no_video = punktfunk_core::client::NO_VIDEO_RETRY;
+    period.abs_diff(no_video) < no_video / 10
+}
+
+/// Either client cooldown — the band in which a period tells us about the CLIENT's software, not
+/// about anything physical on this host.
+fn matches_client_recovery_cooldown(period: std::time::Duration) -> bool {
+    matches_client_flush_cadence(period) || matches_client_no_video_cadence(period)
+}
+
 /// One mode's capture/encode pipeline: (capturer, encoder, first frame, frame interval).
 /// Dropping the capturer tears down the PipeWire stream and the virtual output with it.
 type Pipeline = (
@@ -5068,6 +5146,29 @@ mod tests {
         assert!(!matches_client_flush_cadence(std::time::Duration::ZERO));
     }
 
+    /// The two client cooldowns must stay TELLABLE APART by period, and both must stay out of the
+    /// display-disturbance branch. While they were both 2000 ms a black-screen field case (nothing
+    /// ever reached the client) was reported as "the client cannot sustain the stream" — the exact
+    /// opposite fault — because the periods were identical and the host guessed.
+    #[test]
+    fn the_two_client_cooldowns_are_distinguishable_and_both_excluded_from_display_blame() {
+        let flush = punktfunk_core::client::FLUSH_COOLDOWN;
+        let no_video = punktfunk_core::client::NO_VIDEO_RETRY;
+        assert_ne!(
+            flush, no_video,
+            "identical cooldowns make the host's verdict a coin flip"
+        );
+        // Neither may fall inside the other's ±10% band, or the period stops discriminating.
+        assert!(!matches_client_flush_cadence(no_video));
+        assert!(!matches_client_no_video_cadence(flush));
+        // Both are client software cooldowns: never the metronomic display-disturbance branch.
+        assert!(matches_client_recovery_cooldown(flush));
+        assert!(matches_client_recovery_cooldown(no_video));
+        // A real periodic disturbance still reaches that branch.
+        assert!(!matches_client_recovery_cooldown(flush * 3));
+        assert!(!matches_client_recovery_cooldown(std::time::Duration::ZERO));
+    }
+
     #[test]
     fn an_escalated_but_caught_up_encoder_stops_refusing_climbs() {
         const DEGRADE: u32 = 10;

crates/punktfunk-host/src/runstate.rs

@@ -0,0 +1,217 @@
+//! What a provider plugin **says** is running — the one liveness signal the host cannot work out
+//! for itself.
+//!
+//! [`crate::procscan`] answers "is this game running" by looking at the process table, and
+//! [`crate::gamelease`] turns that into a session lifetime. That works because most stores leave
+//! something recognizable behind: an install directory, an executable, a Steam reaper. Some do not,
+//! and one store in particular *already knows the answer*: Playnite starts the game itself, tracks
+//! it with the mode the person configured (process, directory, original-process), and fires an
+//! event on both edges — carrying the pid it started. Every bit of that was being thrown away, and
+//! the host was left re-deriving a worse version of it by scanning.
+//!
+//! So this is the inbound half of [`crate::library::DetectHint`]. That one is *static* ("here is
+//! how to recognize my title's process"); this one is *live* ("that title is running right now, and
+//! here is its pid"). A provider PUTs its full running set; the host keeps it here; the lease
+//! watcher consults it.
+//!
+//! ### Why the whole set, and why a TTL
+//!
+//! The wire is declarative — the same shape as the library reconcile, for the same reason. A
+//! provider that missed an event, restarted, or was installed mid-game converges on its next PUT
+//! instead of drifting forever; there is no per-event delta to lose.
+//!
+//! And a report **expires**. A plugin that dies with a game running would otherwise leave a claim
+//! that is true today and a lie tomorrow — and unlike Steam's registry flag (which
+//! [`crate::procscan::running_hint`] must treat as merely a bounded veto because Steam leaves it
+//! set on any unclean exit) this claim is allowed to *keep a session alive on its own*. That is
+//! only safe while something is actively restating it, so a report older than [`REPORT_TTL`] stops
+//! counting and the host falls back to scanning, exactly as it does today. The provider's side of
+//! that bargain is to re-PUT well inside the window while anything is running.
+
+use std::collections::{HashMap, HashSet};
+use std::sync::{Mutex, MutexGuard, OnceLock};
+use std::time::{Duration, Instant};
+
+/// How long a provider's report stays authoritative without being restated.
+///
+/// Generous enough that a plugin refreshing every 30s survives a slow reconcile or a paused runner,
+/// short enough that a *dead* plugin stops vetoing a session end within a couple of minutes. The
+/// cost of expiring too early is the pre-existing behaviour (scan-only); the cost of never expiring
+/// is a session that can never end on its own, which is the bug this whole area exists to kill.
+pub const REPORT_TTL: Duration = Duration::from_secs(90);
+
+/// What a provider says about one of its titles.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct Liveness {
+    /// Whether the provider lists this title as running right now.
+    pub running: bool,
+    /// The pid the provider started for it, when it knows one. Never trusted as a bare number —
+    /// every use re-verifies it through [`crate::procscan`], which pins it to its start time.
+    pub pid: Option<u32>,
+}
+
+/// One provider's most recent report.
+struct Report {
+    /// When it landed — the TTL clock.
+    at: Instant,
+    /// Every library id this provider speaks for. What makes "not in `running`" mean *not running*
+    /// rather than *no opinion*: without it an omitted title is indistinguishable from a title
+    /// belonging to some other provider entirely.
+    owned: HashSet<String>,
+    /// The subset that is running, each with the pid the provider started (when it has one).
+    running: HashMap<String, Option<u32>>,
+}
+
+impl Report {
+    fn fresh(&self) -> bool {
+        self.at.elapsed() < REPORT_TTL
+    }
+}
+
+fn table() -> MutexGuard<'static, HashMap<String, Report>> {
+    static TABLE: OnceLock<Mutex<HashMap<String, Report>>> = OnceLock::new();
+    TABLE
+        .get_or_init(|| Mutex::new(HashMap::new()))
+        .lock()
+        .unwrap_or_else(|e| e.into_inner())
+}
+
+/// Record a provider's report, replacing whatever it said before.
+///
+/// `owned` is every library id the provider currently publishes; `running` is the subset that is
+/// running, keyed the same way, valued by pid where one is known.
+pub fn report(provider: &str, owned: HashSet<String>, running: HashMap<String, Option<u32>>) {
+    table().insert(
+        provider.to_string(),
+        Report {
+            at: Instant::now(),
+            owned,
+            running,
+        },
+    );
+}
+
+/// Forget everything a provider said — its entries are gone, so its opinions are meaningless.
+pub fn forget(provider: &str) {
+    table().remove(provider);
+}
+
+/// What a *fresh* provider says about this library id, or `None` when none speaks for it.
+///
+/// `None` is the answer for every title on a host with no reporting plugin, which is what keeps
+/// this entirely inert until someone opts in.
+pub fn opinion(app_id: &str) -> Option<Liveness> {
+    let table = table();
+    table
+        .values()
+        .filter(|r| r.fresh())
+        .find(|r| r.owned.contains(app_id))
+        .map(|r| match r.running.get(app_id) {
+            Some(pid) => Liveness {
+                running: true,
+                pid: *pid,
+            },
+            None => Liveness {
+                running: false,
+                pid: None,
+            },
+        })
+}
+
+/// Whether any fresh provider reports liveness for this title at all — regardless of what it
+/// currently says.
+///
+/// Asked once, when a lease opens: a title whose provider will tell us when it stops is trackable
+/// even with no detect signals whatsoever, which is the whole point (see
+/// [`crate::gamelease::LeaseKind::Reported`]).
+pub fn speaks_for(app_id: Option<&str>) -> bool {
+    app_id.is_some_and(|id| opinion(id).is_some())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn owned(ids: &[&str]) -> HashSet<String> {
+        ids.iter().map(|s| (*s).to_string()).collect()
+    }
+
+    fn running(ids: &[(&str, Option<u32>)]) -> HashMap<String, Option<u32>> {
+        ids.iter().map(|(s, p)| ((*s).to_string(), *p)).collect()
+    }
+
+    // The table is process-global and these tests run in parallel, so each takes a provider id and
+    // app ids only it uses, and cleans up only its own row. An earlier draft shared the id
+    // `playnite` and cleared the whole table between cases, which made the three of them flip each
+    // other's answers depending on scheduling — the same shape as `mgmt`'s `local_summary` race.
+
+    /// The three answers, and the distinction the whole module turns on: a title its provider omits
+    /// is *not running*, while a title nobody speaks for has *no opinion*. Conflating them would
+    /// make every unreported game on the box look like it had just quit.
+    #[test]
+    fn omitted_is_not_running_but_unknown_is_no_opinion() {
+        report(
+            "answers-test",
+            owned(&["answers:a", "answers:b"]),
+            running(&[("answers:a", Some(4242))]),
+        );
+        assert_eq!(
+            opinion("answers:a"),
+            Some(Liveness {
+                running: true,
+                pid: Some(4242)
+            })
+        );
+        assert_eq!(
+            opinion("answers:b"),
+            Some(Liveness {
+                running: false,
+                pid: None
+            })
+        );
+        assert_eq!(opinion("answers:never-published"), None);
+        assert!(speaks_for(Some("answers:b")));
+        assert!(!speaks_for(Some("answers:never-published")));
+        assert!(!speaks_for(None));
+        forget("answers-test");
+    }
+
+    /// A report replaces its predecessor wholesale. The set is the message: a title that dropped out
+    /// of it has stopped, and carrying the old entry forward would be exactly the stuck-running
+    /// state this exists to prevent.
+    #[test]
+    fn a_report_replaces_the_previous_one() {
+        report(
+            "replace-test",
+            owned(&["replace:a"]),
+            running(&[("replace:a", None)]),
+        );
+        report("replace-test", owned(&["replace:a"]), running(&[]));
+        assert_eq!(
+            opinion("replace:a"),
+            Some(Liveness {
+                running: false,
+                pid: None
+            })
+        );
+        forget("replace-test");
+        assert_eq!(opinion("replace:a"), None);
+    }
+
+    /// A stale report stops counting — the bound that makes it safe to let a plugin's claim hold a
+    /// session open. Seeded with an aged timestamp rather than by sleeping for 90 seconds.
+    #[test]
+    fn a_stale_report_has_no_opinion() {
+        table().insert(
+            "stale-test".to_string(),
+            Report {
+                at: Instant::now() - REPORT_TTL - Duration::from_secs(1),
+                owned: owned(&["stale:a"]),
+                running: running(&[("stale:a", Some(7))]),
+            },
+        );
+        assert_eq!(opinion("stale:a"), None);
+        assert!(!speaks_for(Some("stale:a")));
+        forget("stale-test");
+    }
+}

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

@@ -1587,6 +1587,7 @@ fn add_firewall_rules(allow_public: bool) {
             eprintln!("warning: could not add firewall rule '{name}' (add it manually if needed)");
         }
     }
+    add_data_plane_firewall_rule(profile);
     if !allow_public {
         println!(
             "Note: streaming ports are open on Private/Domain networks only. On a network Windows \
@@ -1596,7 +1597,75 @@ fn add_firewall_rules(allow_public: bool) {
     }
 }
 
+/// Rule name for the program-scoped data-plane rule (see [`add_data_plane_firewall_rule`]).
+const FW_DATA_PLANE_RULE: &str = "Punktfunk UDP (data plane)";
+
+/// Inbound UDP for the host executable itself, at **any** local port.
+///
+/// The media data plane binds an EPHEMERAL port per session (`0.0.0.0:0`, reported to the client in
+/// the Welcome), so no `localport=` rule can cover it — the port-scoped rules above open the fixed
+/// control/GameStream/mDNS ports and nothing else. Without this, Windows Firewall drops the client's
+/// hole-punch (`PUNCH_MAGIC` → the host's data port) on EVERY session: that is what `punched=false`
+/// on the host's "data plane bound" line means. The punch then never opens the return path, video
+/// falls back to blind-sending at the address the client merely *reported*, and the moment anything
+/// on the path needs the flow opened client-first the stream goes black while the control plane
+/// stays healthy — no reconnect, no error, just a session that never shows a picture.
+///
+/// Program-scoped rather than a pinned port: it covers whatever port the session picks, needs no
+/// second rule when the range moves, and cannot collide with another host (a pinned data port in
+/// 47998-48010 would land on Sunshine/Apollo's GameStream range). The port rules above are kept as
+/// they are — an install whose recorded exe path later moves still has its fixed ports open.
+fn add_data_plane_firewall_rule(profile: &str) {
+    let exe = match std::env::current_exe() {
+        Ok(p) => p,
+        Err(e) => {
+            eprintln!(
+                "warning: could not resolve the host executable path ({e}) — skipping the \
+                 data-plane firewall rule; streams may show a black picture behind a healthy \
+                 connection on networks that need the client's hole-punch to open the path"
+            );
+            return;
+        }
+    };
+    let ok = run_quiet(
+        "netsh",
+        &[
+            "advfirewall",
+            "firewall",
+            "add",
+            "rule",
+            &format!("name={FW_DATA_PLANE_RULE}"),
+            "dir=in",
+            "action=allow",
+            "protocol=UDP",
+            &format!("program={}", exe.to_string_lossy()),
+            profile,
+        ],
+    );
+    if ok {
+        println!(
+            "Firewall rule added: {FW_DATA_PLANE_RULE} (any UDP port for {}) [{profile}]",
+            exe.display()
+        );
+    } else {
+        eprintln!(
+            "warning: could not add firewall rule '{FW_DATA_PLANE_RULE}' — the per-session video \
+             data port stays closed to inbound, so the client's hole-punch cannot reach it"
+        );
+    }
+}
+
 fn remove_firewall_rules() {
+    let _ = run_quiet(
+        "netsh",
+        &[
+            "advfirewall",
+            "firewall",
+            "delete",
+            "rule",
+            &format!("name={FW_DATA_PLANE_RULE}"),
+        ],
+    );
     for suffix in ["TCP", "UDP"] {
         // Capital P is the brand; netsh matches a rule name case-INSENSITIVELY, so this still
         // reaps the lowercase rules every release up to 0.22.1 created — no orphans on upgrade.

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

@@ -4,346 +4,277 @@ description: Every setting a Punktfunk client stores — what it does, what it d
 ---
 
 The host has [its own settings reference](/docs/configuration). This page is the other half: the
-settings each **client** keeps, which together decide what a session looks like.
-
-Most of them are a *request*. The client asks, the host answers in the handshake — so a setting the
-host can't honor is usually a quiet downgrade rather than an error.
+settings each **client** keeps. Most are a *request* — the client asks, the host answers in the
+handshake, and a setting the host can't honor is a quiet downgrade rather than an error.
 
 ## Where the settings live
 
 The Linux, Windows, Mac, iPhone/iPad and Android apps group settings the same way — **General**,
 **Display**, **Input**, **Audio**, **Controllers** — under *Preferences* on Linux and *Settings*
-elsewhere. The Apple TV app shows one scrolling list instead, as does any client's settings screen
-reached with a controller. A controller-driven launch (Steam Deck Gaming Mode) opens the client's
-**console home**, whose settings screen is one steppable list of sections — **Stream**, **Video**,
-**Presentation**, **Audio**, **Controller**, **Touchscreen**, **Interface**, **Profiles**. On a
-Steam Deck that list *is* the settings surface: the [Decky plugin](/docs/steam-deck) is a launcher
-and keeps no settings of its own, and its **Open Punktfunk** button puts the console home one tap
-from the Quick Access Menu. The console home is part of the client — it is not the host's
-[web console](/docs/web-console).
+elsewhere. The Apple TV app and any settings screen reached with a controller show one steppable
+list instead — **Stream**, **Video**, **Presentation**, **Audio**, **Controller**, **Touchscreen**,
+**Interface**, **Profiles** — the client's **console home** (not the host's
+[web console](/docs/web-console)). On a Steam Deck that list *is* the settings surface: the
+[Decky plugin](/docs/steam-deck) is a launcher with no settings of its own, and its **Open
+Punktfunk** button opens the console home from the Quick Access Menu.
 
-Linux stores them in `~/.config/punktfunk/client-gtk-settings.json`, the same file the console home
-writes, so a change in either shows up in the other. Windows uses
-`%APPDATA%\punktfunk\client-windows-settings.json`; the Apple and Android apps use their own stores.
+Linux stores them in `~/.config/punktfunk/client-gtk-settings.json` (shared with the console home);
+Windows in `%APPDATA%\punktfunk\client-windows-settings.json`; the Apple and Android apps use their
+own stores.
 
-Changes apply to the **next** session — a running stream keeps what it started with. (*Match window*
-is the exception in effect, not in reading: it too is read at connect, but once a session is running
-with it on, every window resize renegotiates the mode.)
-
-Not every client offers every setting; the names below are the Linux app's, and differences that
-matter are noted per setting.
+Changes apply to the **next** session. (*Match window* is also read at connect, but once on, every
+window resize renegotiates the mode.) Names below are the Linux app's; differences that matter are
+noted per setting.
 
 ## Video
 
-**Resolution** — *default: Native display.* The host builds a virtual display at exactly this size
-and streams it; nothing is scaled. Native resolves at connect to the mode of the display your window
-is on. The Apple app instead stores an explicit size (1920 × 1080 out of the box): on iPhone, iPad
-and Mac a **Use this display's mode** button fills in what you're looking at, and the Apple TV app
-picks a combined **Stream mode** preset instead ("This TV (native)", 720p, 1080p or 4K at 60 Hz). If
-the host has been pinned to stream a *real* monitor rather than make one, your request is declined
-and your client scales what it gets — see
-[Virtual displays](/docs/virtual-displays#stream-a-real-monitor-instead).
+**Resolution** — *default: Native display.* The host builds a virtual display at exactly this size;
+nothing is scaled. Native resolves at connect to the mode of the display your window is on. The
+Apple app stores an explicit size (1920 × 1080 out of the box) with a **Use this display's mode**
+button on iPhone/iPad/Mac; Apple TV picks a combined **Stream mode** preset ("This TV (native)",
+720p, 1080p or 4K at 60 Hz). A host pinned to stream a *real* monitor declines the request and your
+client scales — see [Virtual displays](/docs/virtual-displays#stream-a-real-monitor-instead).
 
-**Match window** — *default: off.* The stream mode follows your window instead, and each resize
-renegotiates the host's display and encoder, so a windowed session stays pixel-exact. Fullscreen
-degenerates to the display's native mode. Offered by the Linux, Windows, Mac, iPhone/iPad and
-console-home screens (in the console home it is an option inside the Resolution picker, and a
-Gaming-Mode stream is always fullscreen, so there it lands on native); not by Android.
+**Match window** — *default: off.* The stream mode follows your window; each resize renegotiates
+the host's display and encoder. Fullscreen degenerates to the display's native mode. Linux,
+Windows, Mac, iPhone/iPad and the console home (inside the Resolution picker; a Gaming-Mode stream
+is always fullscreen, so there it lands on native); not Android.
 
 **Refresh rate** — *default: Native*, the refresh of the display your window is on. The Apple app
-stores an explicit rate (60 Hz by default): iPhone and iPad offer the rates the device can display,
-on a Mac you type one in, and on Apple TV the rate rides along with the Stream mode preset above.
+stores an explicit rate (60 Hz default): iPhone and iPad offer the device's displayable rates, on a
+Mac you type one in, and Apple TV's rate rides with the Stream mode preset.
 
-**Bitrate** — *default: Automatic.* For H.264, HEVC and AV1, Automatic means the host's own default,
-**20 Mbps**, and it turns on two things an explicit rate switches off: adaptive bitrate, and a short
-link-capacity probe about two seconds in that measures what your link really carries and lets the
-rate climb past 20 Mbps. An explicit rate is fixed for the session, and clamped by the host to
-**500 kbps – 8 Gbps**. A host card's menu has a **Test network speed…** entry that measures your link
-and suggests a value.
+**Bitrate** — *default: Automatic.* For H.264, HEVC and AV1, Automatic means the host's default,
+**20 Mbps**, plus two things an explicit rate switches off: adaptive bitrate, and a link-capacity
+probe about two seconds in that lets the rate climb past 20 Mbps. An explicit rate is fixed for the
+session, clamped to **500 kbps – 8 Gbps**. A host card's menu has **Test network speed…** to suggest
+a value.
 
-PyroWave is the exception: it has no useful low-rate regime, so its Automatic rate is a fixed
-per-pixel budget for the negotiated mode (hundreds of Mbps), and both adaptive bitrate and the
-capacity probe stay off for the whole session.
+PyroWave has no useful low-rate regime: its Automatic is a fixed per-pixel budget for the negotiated
+mode (hundreds of Mbps), with adaptive bitrate and the probe off for the whole session.
 
-**Render scale** — *default: Native (1×).* The host renders and encodes at your chosen mode
-multiplied by this, and your device resamples the result to its window. Above 1× supersamples for
-sharpness, at more bandwidth *and* more decode work; below 1× is lighter on both the host and the
-link. The stops run 0.5× to 4×. The result is floored to an even size and capped per axis at
+**Render scale** — *default: Native (1×).* The host renders and encodes at your mode times this;
+your device resamples to its window. Above 1× supersamples at more bandwidth and decode work; below
+1× is lighter on both. Stops 0.5×–4×; the result is floored to an even size and capped per axis at
 4096 px for H.264, 8192 px otherwise. Offered everywhere.
 
-**Video codec** — *default: Automatic.* A soft preference: the host emits your choice when it can
-also produce it, otherwise the best codec you both speak, in the order HEVC → AV1 → H.264.
-**PyroWave** is never auto-picked — pick it explicitly on Linux, Windows, the console home, or an
-Apple device whose decode probe passes; anywhere else it isn't offered, and asking for it lands on
-that same order. See [PyroWave](/docs/pyrowave). The Android and Apple apps hide AV1 unless the
-device has a hardware AV1 decoder; Android never offers PyroWave.
+**Video codec** — *default: Automatic.* A soft preference: your choice when the host can produce
+it, else the best codec you both speak, in the order HEVC → AV1 → H.264. **PyroWave** is never
+auto-picked — pick it explicitly on Linux, Windows, the console home, or an Apple device whose
+decode probe passes; elsewhere asking for it lands on that same order. See
+[PyroWave](/docs/pyrowave). Android and Apple hide AV1 without a hardware AV1 decoder; Android never
+offers PyroWave.
 
-**10-bit HDR** — *default: on.* Off means "never send me 10-bit", and the host then never upgrades.
-On, the stream goes 10-bit BT.2020 PQ only when the host has HDR content *and* the encoder can do
-10-bit. Android disables the toggle, and never advertises HDR, on a panel that can't present HDR10.
-Full detail: [HDR](/docs/hdr).
+**10-bit HDR** — *default: on.* Off means "never send me 10-bit". On, the stream goes 10-bit
+BT.2020 PQ only when the host has HDR content *and* the encoder can do 10-bit. Android disables the
+toggle, and never advertises HDR, on a panel that can't present HDR10. Full detail: [HDR](/docs/hdr).
 
-**Full chroma (4:4:4)** — *default: off.* Crisp small text and thin lines, at more bandwidth. It
-needs HEVC or PyroWave, the host's own 4:4:4 policy left on, a capture path that delivers full
-chroma, and a GPU that can encode it; if any gate fails the host says 4:2:0 before your decoder is
-built. The Apple, Linux and Windows apps all advertise it (Apple additionally requires its hardware
-decode probe to pass). The console home offers the toggle; Android doesn't.
+**Full chroma (4:4:4)** — *default: off.* Crisp small text and thin lines, at more bandwidth. Needs
+HEVC or PyroWave, the host's 4:4:4 policy on, a capture path that delivers full chroma, and a GPU
+that can encode it; if any gate fails the host says 4:2:0 before your decoder is built. Apple
+(hardware decode probe required), Linux, Windows and the console home; not Android.
 
-**Prioritize** — *default: Lowest latency.* What the client optimizes for when a decoded frame is
-ready. **Lowest latency** shows every frame the moment the display can take it, so a network hiccup
-becomes an occasional repeated or skipped frame. **Smoothness** holds a small buffer that evens those
-hiccups out, at that buffer's worth of added delay. Linux and Windows apps and the console home; the
-Apple and Android apps have it too, stored under the same name, so a
+**Prioritize** — *default: Lowest latency.* **Lowest latency** shows every frame the moment the
+display can take it — a network hiccup becomes an occasional repeated or skipped frame.
+**Smoothness** holds a small buffer that evens hiccups out, at that buffer's worth of added delay.
+Linux, Windows, the console home, Apple and Android — stored under the same name everywhere, so a
 [profile](/docs/profiles-and-links) means the same thing on every device.
 
-**Smoothness buffer** — *default: Automatic (two frames).* How many frames are held back before
-showing. Each frame absorbs roughly one screen refresh of network hiccup and costs one refresh of
-delay — so on a 120 Hz screen, two frames is about 17 ms of extra delay bought against 17 ms of
-jitter. If you never see stutter, you don't need this. The row appears wherever **Prioritize** is
-offered, and only once you have picked **Smoothness**.
+**Smoothness buffer** — *default: Automatic (two frames).* Frames held back before showing. Each
+absorbs roughly one screen refresh of jitter and costs one refresh of delay — on a 120 Hz screen,
+two frames ≈ 17 ms both ways. Appears wherever **Prioritize** is offered, once **Smoothness** is
+picked.
 
-**V-Sync** — *default: on.* Tear-free presentation. Off asks the GPU to show each frame the instant
-it's ready instead of waiting for the screen's next refresh: the lowest delay a display can give
-you, at the cost of visible tearing on fast motion. It is **best-effort** — not every driver or
-compositor offers a tearing mode, and where none is available the stream stays tear-free. The
-Detailed [stats overlay](/docs/stats) names the mode actually in use, so you can tell "off" from
-"off but unavailable". Linux and Windows apps and the console home.
+**V-Sync** — *default: on.* Tear-free presentation. Off shows each frame the instant it's ready:
+the lowest delay a display can give, with visible tearing on fast motion. Best-effort — where the
+driver or compositor has no tearing mode the stream stays tear-free, and the Detailed
+[stats overlay](/docs/stats) names the mode actually in use. Linux, Windows, console home.
 
-**Follow variable refresh rate** — *default: on.* On a VRR / FreeSync / G-Sync screen, let the panel
-refresh in step with the stream rather than on a fixed cadence — which removes the wait between a
-frame being ready and the screen being willing to show it. Applies to **fullscreen** sessions (a
-windowed one is at the compositor's mercy) and is harmless on a fixed-refresh screen. It needs a
-graphics driver that offers the modern queue-free display mode; on an older driver it does nothing
-unless you also set `PUNKTFUNK_VRR_FIFO=1` (see [configuration](/docs/configuration)), because the
-older way of following a panel costs noticeable latency on a fixed-refresh screen. The stats overlay
-reports `vrr yes` once it has *measured* that the panel really is following. Linux and Windows apps
-and the console home.
+**Follow variable refresh rate** — *default: on.* On a VRR / FreeSync / G-Sync screen, the panel
+refreshes in step with the stream. Applies to **fullscreen** sessions; harmless on a fixed-refresh
+screen. Needs a driver with the modern queue-free display mode; on an older driver it does nothing
+unless `PUNKTFUNK_VRR_FIFO=1` is set (see [configuration](/docs/configuration)). The stats overlay
+reports `vrr yes` once it has *measured* the panel following. Linux, Windows, console home.
 
-**Host compositor** — *default: Automatic.* Which backend a **Linux** host uses to drive the virtual
-output. Advisory: a host without that backend quietly auto-detects instead.
+**Host compositor** — *default: Automatic.* Which backend a **Linux** host uses to drive the
+virtual output. Advisory: a host without that backend auto-detects instead.
 
 ## Audio
 
-**Audio channels** — *default: Stereo.* You can ask for **5.1** or **7.1**; anything else is read as
-stereo. The count the host will really send comes back in the handshake, and your client builds its
-decoder from *that*, never from the request. What surround means differs by host: a **Linux** host
-claims a sink advertising exactly that many channels, so applications produce real surround, while a
-**Windows** host loopback-captures your current output endpoint and lets Windows convert it — so 5.1
-from a stereo endpoint is an upmix, not new channels. Offered everywhere.
+**Audio channels** — *default: Stereo.* **5.1** or **7.1** on request; anything else reads as
+stereo. The count the host will really send comes back in the handshake and your decoder is built
+from *that*. A **Linux** host claims a sink with exactly that many channels (real surround); a
+**Windows** host loopback-captures the current output endpoint and lets Windows convert — 5.1 from
+a stereo endpoint is an upmix. Offered everywhere.
 
 **Microphone** — *default: off on Linux, Windows, Android and the console home; on in the Apple
-app.* Sends this device's microphone to the host's virtual mic. On Linux and Windows the row is
-spelled *Stream microphone*, and **Ctrl+Alt+Shift+V** mutes it mid-stream without ending anything —
-see [Muting your microphone](/docs/input#muting-your-microphone).
+app.* Sends this device's microphone to the host's virtual mic. Spelled *Stream microphone* on
+Linux and Windows; **Ctrl+Alt+Shift+V** mutes it mid-stream — see
+[Muting your microphone](/docs/input#muting-your-microphone).
 
-**Echo cancellation** — *default: on.* Stops the host's audio, playing out of this device's speakers,
-from being picked up by the microphone and sent straight back. It hands the microphone to the
-system's own canceller rather than doing the work itself: on **Linux** that means capturing from an
-echo-cancelled PipeWire source when your desktop provides one, on **Windows** asking WASAPI for the
-Communications stream category so the endpoint's processing engages, and on **Apple** and
-**Android** the platform's voice-processing mode. Turn it off if your microphone already runs its
-own processing, or if the canceller makes your voice sound thin. The row sits under the microphone
-toggle and greys out while the microphone is off. Offered by the Linux, Windows, Apple, Android and
-console-home clients. What it can and can't fix is in [Why do I hear myself](/docs/echo).
+**Echo cancellation** — *default: on.* Stops the host's audio, playing from this device's speakers,
+from re-entering the microphone. It uses the system's own canceller: an echo-cancelled PipeWire
+source on **Linux**, the WASAPI Communications stream category on **Windows**, the platform
+voice-processing mode on **Apple** and **Android**. Turn it off if your microphone runs its own
+processing or the canceller thins your voice. Sits under the microphone toggle, greyed out while
+the mic is off. Linux, Windows, Apple, Android, console home. See
+[Why do I hear myself](/docs/echo).
 
-**Speaker** and **Microphone** device pickers — *default: System default.* Which endpoint stream
-audio plays out of, and which input feeds the uplink. Only the Linux app (PipeWire nodes) and the
-**Mac** app (which also has a microphone *channel* picker) have these — iPhone, iPad, Apple TV,
-Android and the console home have none, and the Windows app has none and ignores a stored speaker
-choice. On Linux, a device that has since disappeared keeps a "(not detected)" entry rather than
-silently snapping back to the default; the Mac shows it as "Unavailable device". A Steam Deck in
-Gaming Mode therefore has no endpoint picker at all: the session uses whatever the Desktop-Mode app
-last stored, and the system default otherwise.
+**Speaker** and **Microphone** device pickers — *default: System default.* Which endpoint plays the
+stream, and which input feeds the uplink. Only the Linux app (PipeWire nodes) and the **Mac** app
+(plus a microphone *channel* picker) have these; the Windows app ignores a stored speaker choice. A
+vanished device keeps a "(not detected)" entry on Linux, "Unavailable device" on the Mac. A Steam
+Deck in Gaming Mode has no endpoint picker: the session uses what the Desktop-Mode app last stored.
 
 ## Input
 
 Touch modes, mouse modes and the in-stream chords have their own page: [Input](/docs/input). Five
 more settings are worth naming here.
 
-**Forward controllers** — *default: on*, on every client. Off, the controllers connected to *this*
-device are not sent to the host at all. That is what you want when your controller already reaches
-the host by some other route —
-[USB passthrough](/docs/automation#recipe-full-controller-passthrough-virtualhere) such as
-VirtualHere, or a pad plugged into the host itself. Leaving forwarding on there hands the host two
-controllers for one pair of hands, and games read both: a stick drifts because the second pad is
-centred, or a menu takes every input twice.
+**Forward controllers** — *default: on*, everywhere. Off, controllers connected to *this* device
+are not sent to the host — what you want when the controller already reaches the host another way
+([USB passthrough](/docs/automation#recipe-full-controller-passthrough-virtualhere) such as
+VirtualHere, or a pad plugged into the host), where forwarding would hand games two controllers for
+one pair of hands.
 
-On Linux and Windows, opening a controller is what *claims* it — the client's SDL takes the device
-node — and a passthrough tool cannot bind a claimed device; with this off the session never opens
-the controller at all, leaving it free for VirtualHere to hand over. The consequence: the
-[controller escape chord](/docs/input#leaving-with-a-controller) is read off forwarded pads, so it is
-unavailable on those two while this is off — leave a stream with the keyboard chord or the client's
-own UI. The Apple and Android apps claim nothing, so their chords keep working either way; the
-Android app does stop its DualSense and Steam Controller 2 USB captures, which *do* claim the device.
-
-The rows below it — which pad, and what type — have nothing to act on while this is off, and every
-client greys them out to say so.
+On Linux and Windows, opening a controller *claims* it (SDL takes the device node), and a
+passthrough tool can't bind a claimed device; off, the session never opens the pad. Consequence:
+the [controller escape chord](/docs/input#leaving-with-a-controller) is read off forwarded pads, so
+on those two it is unavailable while this is off — leave with the keyboard chord or the client's
+UI. The Apple and Android apps claim nothing, so their chords keep working; Android does stop its
+DualSense and Steam Controller 2 USB captures, which do claim the device. The rows below grey out
+while this is off.
 
 **Gamepad type** (*Controller type* on Apple, Android and the console home) — *default: Automatic*,
-which matches each physical controller. The pickers offer Xbox 360, Xbox One, DualSense and
-DualShock 4 everywhere, plus Steam Deck on Linux, Android and the console home. Your client declares
-a type per pad as it connects — Automatic declares what that controller really is, an explicit
-choice declares your choice — and the host builds each virtual pad from that. A type the host has no
-backend for degrades to an Xbox 360 pad rather than failing: Xbox One on a Windows host, for
-instance, or any Sony pad on a Linux host that can't open `/dev/uhid`.
+which matches each physical controller. Pickers offer Xbox 360, Xbox One, DualSense and DualShock 4
+everywhere, plus Steam Deck on Linux, Android and the console home. The host builds each virtual
+pad from the declared type; a type the host has no backend for degrades to an Xbox 360 pad (Xbox
+One on a Windows host, any Sony pad on a Linux host that can't open `/dev/uhid`).
 
-That degrade matters for **motion**. An Xbox-class virtual pad has no gyroscope in its HID
-contract, so a session that ends up on one throws every motion sample away — your controller's gyro
-does nothing. Automatic lands there for any controller punktfunk doesn't recognise as Sony or Valve (an 8BitDo
-with a gyro, say), and so does a Switch Pro streaming to a Windows host, which has no Nintendo
-backend to build. **If you want motion, pick a DualSense-class type** — DualSense, DualSense Edge,
-DualShock 4, Switch Pro or Steam Deck all carry a motion plane. The clients detect this case and say
-so on-screen for a few seconds when it happens; the setting applies from the next session, not the
-one you are in.
-
-On a **Steam Deck as the client**, motion also needs Steam Input switched off for punktfunk — with
-it on, Steam hands the app its own virtual Xbox pad, which has no gyro to forward no matter which
-type you pick.
+That degrade matters for **motion**: an Xbox-class virtual pad has no gyroscope, so a session on
+one throws every motion sample away. Automatic lands there for any pad not recognised as Sony or
+Valve (an 8BitDo with a gyro, say), and for a Switch Pro streaming to a Windows host. **If you want
+motion, pick a DualSense-class type** — DualSense, DualSense Edge, DualShock 4, Switch Pro or Steam
+Deck all carry a motion plane. Clients say so on-screen when it happens; the setting applies from
+the next session. On a **Steam Deck as the client**, motion also needs Steam Input off for
+punktfunk — with it on, Steam hands the app its own virtual Xbox pad.
 
 **Forwarded controller** (*Use controller* on Apple and the console home) — *default: Automatic*,
-which forwards *every* connected controller, each as its own player, on Linux, Windows, Apple and the
-console home. Pinning one restricts the session to that controller alone — single-player. The Android
-app has no such picker.
+which forwards *every* connected controller, each as its own player. Pinning one restricts the
+session to that controller alone. Linux, Windows, Apple, console home; not Android.
 
-**Steam / guide button** (*Guide button* on Apple and Android) — *default: Automatic*, on every
-client. Where the guide (Xbox/PS/Steam) and quick-access presses go while streaming: **Send to
-host** forwards them raw, **This device** keeps them local. Automatic forwards everywhere except
-Gaming Mode, where SteamOS opens its own menus for those buttons no matter what — forwarding raw
-there opens *both* menus at once, the local one covering the stream. The full story, including how
-to reach the host's menus when the raw press stays local, is on the
-[Input page](/docs/input#the-guide-button-xbox--ps--steam-and-quick-access).
+**Steam / guide button** (*Guide button* on Apple and Android) — *default: Automatic*, everywhere.
+Where guide (Xbox/PS/Steam) and quick-access presses go while streaming: **Send to host** forwards
+them raw, **This device** keeps them local. Automatic forwards everywhere except Gaming Mode, where
+SteamOS opens its own menus for those buttons regardless — forwarding raw there opens both menus at
+once. Full story:
+[the guide button](/docs/input#the-guide-button-xbox--ps--steam-and-quick-access).
 
-**Hold Select for guide** — *default: Automatic*, on every client. The gesture that presses the
-host's guide button from any controller: hold Select (Back/View) on its own for about a third of a
-second, and keep holding for the host's long-press (a Gaming-Mode host's Quick Access Menu, on a
-regular pad). Automatic arms it only where the raw guide press can't reach the host cleanly —
-Gaming Mode, iPhone/iPad, Apple TV — because the gesture has a cost: a Select *tap* arrives a beat
-late, and a game that expects a *held* Select would trigger it. Set **On** or **Off** to overrule.
+**Hold Select for guide** — *default: Automatic*, everywhere. The gesture that presses the host's
+guide button from any controller: hold Select (Back/View) alone ~⅓ s; keep holding for the host's
+long-press. Automatic arms it only where the raw press can't reach the host cleanly — Gaming Mode,
+iPhone/iPad, Apple TV — because the gesture costs: a Select *tap* arrives a beat late, and a game
+expecting a *held* Select would trigger it. **On**/**Off** overrule.
 
-**Controller haptics** — *default: on*, and **Controller speaker** — *default: on* on the Linux and
-Windows apps, *off* on Android. The two halves of [controller audio](/docs/controller-audio): a
-DualSense's voice-coil haptics, and the little speaker in the middle of the pad. Both need a
-**wired** DualSense or DualSense Edge — over Bluetooth a controller exposes no audio device at all,
-and both settings quietly do nothing. Neither costs anything without a host that sends them: the
-plane is negotiated, and silence is never encoded or transmitted. Turn **Controller speaker** off if
-you would rather all game audio came out of your speakers or headset.
+**Controller haptics** — *default: on*, and **Controller speaker** — *default: on* on Linux and
+Windows, *off* on Android. The two halves of [controller audio](/docs/controller-audio): a
+DualSense's voice-coil haptics and the pad's speaker. Both need a **wired** DualSense or DualSense
+Edge — Bluetooth exposes no audio device, and both settings quietly do nothing. The plane is
+negotiated, so neither costs anything without a host that sends them. Linux, Windows and Android.
+On Linux the client also switches the pad's sound card to Pro Audio while it needs the voice coils
+and puts it back afterwards — see
+[the controller-audio page](/docs/controller-audio#on-a-linux-client-the-pads-own-profile-matters-too).
 
-Offered by the Linux, Windows and Android apps. On Linux, the client also switches the controller's
-sound card to Pro Audio while it needs the voice coils, and puts it back afterwards — see
-[the controller-audio page](/docs/controller-audio#on-a-linux-client-the-pads-own-profile-matters-too)
-for why that is necessary and how to turn it off.
+**Capture system shortcuts** — *default: on.* Linux, Windows (spelled *Capture system shortcuts
+(Alt+Tab, Win, …)*), macOS and the console home; on a Deck it matters only for an attached keyboard
+(gamescope holds nothing back). On, Alt+Tab and the Windows/Super key reach the host while input is
+captured; off, they act locally. Either way the chords return when you release capture with
+**Ctrl+Alt+Shift+Q**, the window loses focus, or the stream ends —
+[Desktop mouse mode](/docs/input#mouse-modes) never takes them at all. Leaving it on means
+**Ctrl+Alt+Shift+Q is your way out**, since Alt+Tab no longer is.
 
-**Capture system shortcuts** — *default: on.* Offered by the Linux, Windows and macOS apps and the
-console home; Windows spells the row out as *Capture system shortcuts (Alt+Tab, Win, …)*. On a Deck it
-matters only for a keyboard you attached yourself: Gaming Mode is gamescope, which has nothing to
-hold back. On, Alt+Tab and the Windows key (Super on Linux)
-reach the host while the stream has input captured. Off, they act on this machine instead — what you
-want when the stream shares a screen with local work. Either way the chords come back the moment you
-release capture with **Ctrl+Alt+Shift+Q**, the window loses focus, or the stream ends, and
-[Desktop mouse mode](/docs/input#mouse-modes) never takes them at all. Leaving this on does mean
-**Ctrl+Alt+Shift+Q is your way out** of a captured stream, since Alt+Tab no longer is.
+On macOS the chords in question are the **⌘** ones — on, ⌘Q, ⌘W, ⌘H and the rest go to the host
+while input is captured (⌘Q arrives as Super+Q); off, they act on the Mac, which means ⌘Q quits
+Punktfunk mid-stream. **⌘⎋ always stays local** — it releases capture, as does ⌃⌥⇧Q, and ⌃⌘F keeps
+working on the window. ⌘Tab, ⌘Space and the Mission Control keys never reach the host either way —
+macOS claims them first.
 
-On macOS the chords in question are the **⌘** ones — ⌘Q above all, which reaches the host as Super+Q,
-one of the most-bound chords on a Linux desktop. On, ⌘Q, ⌘W, ⌘H and the rest go to the host instead
-of this app's menu bar while input is captured. Off, they act on the Mac as usual, which means ⌘Q
-quits Punktfunk mid-stream. **⌘⎋ always stays local whichever way the toggle is set** — it is what
-releases capture, as is ⌃⌥⇧Q, and ⌃⌘F keeps working on the window. A few chords never reach the host
-either way, because macOS claims them before any app can see them: ⌘Tab, ⌘Space, and the Mission
-Control keys.
-
-On Linux this needs a compositor that supports keyboard-shortcuts-inhibit — KDE Plasma, GNOME and
-the wlroots compositors all do, and X11 sessions grab the keyboard directly. Under
-[gamescope](/docs/gamescope) there is nothing to inhibit: it hands the session everything already.
+On Linux this needs a compositor with keyboard-shortcuts-inhibit — KDE Plasma, GNOME and wlroots
+compositors have it, X11 sessions grab the keyboard directly. Under [gamescope](/docs/gamescope)
+there is nothing to inhibit.
 
 **Invert scroll direction** — *default: off*, i.e. the host scrolls the way this machine does.
 
 ## Behavior
 
 **Auto-wake on connect** — *default: on.* Connecting to a saved host that looks offline sends
-Wake-on-LAN and waits for it to boot — only for a host whose MAC address this client has already
-learned. Turn it off for hosts you reach over a VPN, where "offline" usually means "not reachable by
-broadcast" and the wake only adds a delay. The Linux, Windows, Apple and Android apps have this
-toggle, as does the console home — and on a Steam Deck it governs the
-[Decky plugin's](/docs/steam-deck) launches too, because the plugin starts every stream through the
-client. The console home also offers wake as an
-explicit action on an offline host, whatever the toggle says. See
-[Wake-on-LAN](/docs/wake-on-lan).
+Wake-on-LAN and waits — only for a host whose MAC this client has learned. Turn it off for hosts
+reached over a VPN, where the wake only adds delay. Linux, Windows, Apple, Android and the console
+home; on a Steam Deck it also governs the [Decky plugin's](/docs/steam-deck) launches. The console
+home additionally offers wake as an explicit action on an offline host, whatever the toggle says.
+See [Wake-on-LAN](/docs/wake-on-lan).
 
 **Show game library** — *Apple and Android only, default: on.* Browse a paired host's games and
-launch one directly. The Linux and Windows apps have nothing to switch on — **Browse library…** sits
-on every paired host's card — and neither does the console home, whose **Library** button was always
-offered on any paired host. See [Game library](/docs/game-library).
+launch one directly. Linux and Windows have **Browse library…** on every paired host's card, and
+the console home a **Library** button — nothing to switch. See [Game library](/docs/game-library).
 
 **Start streams in fullscreen** — *default: on.* On Linux and Windows, F11 or Alt+Enter leaves
-fullscreen live. On a Mac the setting is **Fullscreen while streaming**, and the window comes back
-when you return to the host list. The console home carries the row for the desktop client that
-shares the store — a Gaming-Mode launch is fullscreen whatever it says. iPhone, iPad, Apple TV and
-Android have no equivalent.
+fullscreen live. On a Mac the setting is **Fullscreen while streaming**, and the window returns
+with the host list. The console home carries the row for the desktop client that shares the store —
+a Gaming-Mode launch is fullscreen regardless. Not on iPhone, iPad, Apple TV or Android.
 
 ## Interface
 
-These change how the client itself looks and behaves. None touches a stream, so none can live in a
-[profile](/docs/profiles-and-links) — they are decisions about the device in front of you.
+How the client itself looks. None touches a stream, so none can live in a
+[profile](/docs/profiles-and-links).
 
-**Gamepad-optimized browsing** — *default: on.* Swaps the touch or desktop home for the
-controller-optimized one: the host carousel, larger focus targets, a swipeable cover browser, and
-settings you can step with a thumbstick. The Apple and Android apps have this switch. Turn it off to
-stay in the touch interface even with a pad in your hands. On Linux, Windows and the Steam Deck the
-controller-optimized home is a separate entry point rather than a switch, so there is nothing to
-turn off. An Android TV is always in this mode — its remote is the only input it has.
+**Gamepad-optimized browsing** — *default: on.* Swaps the touch/desktop home for the
+controller-optimized one: host carousel, larger focus targets, a swipeable cover browser, steppable
+settings. Apple and Android have the switch — on Android in both places, ordinary Settings and the
+controller-optimized settings themselves, so that home can be left from inside it; on Linux, Windows
+and the Steam Deck the controller-optimized home is a separate entry point. An Android TV is always
+in this mode, so the switch is not offered there.
 
-**Show it** — *default: With a controller.* Only shown while the switch above is on, and it decides
-*when* that switch takes effect. **With a controller**: the controller-optimized home appears as a
-pad connects and the touch interface returns when the last one disconnects. **Always** keeps the
-controller-optimized home either way — for a phone or tablet docked to a TV, where the pad isn't
-always awake. Apple and Android. (An Android TV is in that mode regardless, so the choice changes nothing
-there.)
+**Show it** — *default: With a controller.* Shown while the switch above is on. **With a
+controller**: the controller-optimized home appears as a pad connects, the touch interface returns
+when the last one disconnects. **Always** keeps it either way — for a phone or tablet docked to a
+TV. Apple and Android (an Android TV is in that mode regardless, so the row is not offered there).
 
-**Background** — *default: Violet.* The colour family the controller-optimized home's living backdrop
-drifts through. Thirteen of them: seven dark fields — **Violet**, **OLED**, **Nebula**, **Abyss**,
-**Ember**, **Moss**, **Graphite** — then six pale ones, **Holo**, **Sunset**, **Bloom**, **Dawn**,
-**Mint** and **Opal**, which flip the whole interface to dark text on a light field. The backdrop
-recolours as you step the row, so pick by looking. **OLED** is the one with a practical point: it is
-true black — most of the frame is pixels switched off, which on an OLED or AMOLED panel means no
-glow and no power drawn, with only a faint violet ember left in one corner. Stored under the same
-name on every client, so a phone, a Deck and a desktop set to Mint all look alike.
-
-The row lives in the controller-optimized settings themselves — the screen you reach with **X** from
-the controller-optimized home — on every platform that has one, which includes the Steam Deck and the
-Linux and Windows console home. The Apple TV is the exception: it carries **Background** in its
-ordinary Settings instead, next to **Show it**, because its controller-optimized home needs a real
-controller to open and the palettes would otherwise be unreachable from the Siri Remote.
+**Background** — *default: Violet.* The colour family of the controller-optimized home's backdrop.
+Thirteen: seven dark — **Violet**, **OLED**, **Nebula**, **Abyss**, **Ember**, **Moss**,
+**Graphite** — and six pale — **Holo**, **Sunset**, **Bloom**, **Dawn**, **Mint**, **Opal** — which
+flip the interface to dark text on a light field. The backdrop recolours as you step the row.
+**OLED** is true black: most of the frame is pixels switched off — no glow, no power on an
+OLED/AMOLED panel. Stored under the same name on every client. The row lives in the
+controller-optimized settings (**X**, or **down** on the host carousel, from the controller-optimized
+home) everywhere that has one, including the Steam Deck and the Linux/Windows console home — down is
+the route where there are no face buttons to press, such as an Android TV remote, and the hint bar
+names whichever your device has; the Apple TV carries it in ordinary Settings next to **Show it**
+instead, so it's reachable from the Siri Remote.
 
 ## Overlay
 
 **Statistics overlay** — *default: Normal.* Four tiers — Off, Compact, Normal, Detailed — each a
-superset of the one before. This setting only picks the tier a session *starts* at — you can cycle
-them live in-stream, with a shortcut that differs by platform. The Apple app additionally lets you
-choose which corner the overlay sits in (Top Left, Top Right, Bottom Left, Bottom Right). The
-console home has the tier picker too, as **Statistics overlay** under **Interface**. The shortcuts,
-and every number in the overlay, are in [Understanding the stats overlay](/docs/stats).
+superset of the last. This picks the tier a session *starts* at; cycle live in-stream with a
+per-platform shortcut. The Apple app also picks the corner (Top/Bottom × Left/Right). The console
+home has the tier picker under **Interface**. Shortcuts and every number:
+[Understanding the stats overlay](/docs/stats).
 
 ## Settings that are facts about your device
 
-A few of these describe the machine you're sitting at rather than how you want a host streamed. They
-stay global and **cannot be put in a settings profile**:
+These describe the machine you're sitting at, stay global, and **cannot be put in a settings
+profile**:
 
 - **Video decoder** and **GPU** — the decode path and adapter this device uses. Automatic is
-  vendor-ordered and falls back on its own; change it only when debugging, and note that
-  `PUNKTFUNK_DECODER` overrides it
-  ([Configuration](/docs/configuration#client-side-native-clients)). The decoder picker is on Linux,
-  Windows and in the console home; the GPU picker on Windows, and on Linux only when the machine has
-  more than one adapter — the console home has none, and a Deck has a single adapter anyway. The
-  Apple and Android apps have neither.
+  vendor-ordered and falls back on its own; change only when debugging; `PUNKTFUNK_DECODER`
+  overrides it ([Configuration](/docs/configuration#client-side-native-clients)). Decoder picker:
+  Linux, Windows, console home. GPU picker: Windows, and Linux with more than one adapter. Apple
+  and Android have neither.
 - **Speaker** and **Microphone** device pickers — this device's audio endpoints.
-- **Forwarded controller** — which physical pad is in your hands. The *type* the host creates is a
-  preference and can live in a profile; which pad you hold cannot. **Forward controllers** is a
-  preference too, and does live in a profile — a work profile can decline to forward what a game
-  profile forwards.
-- **Auto-wake on connect**, and **Show game library** where it still exists (the Apple and Android
-  apps) — decisions about this device and this network, not about how a given host is streamed.
-- Everything under **Interface** — **Gamepad-optimized browsing**, **Show it** and **Background**.
-  How this client looks has nothing to do with how a host streams to it.
+- **Forwarded controller** — which physical pad is in your hands. (The *type* the host creates is a
+  preference and can live in a profile, as can **Forward controllers**.)
+- **Auto-wake on connect**, and **Show game library** where it exists (Apple, Android).
+- Everything under **Interface**.
 
 One switch you might expect here isn't in Settings at all: **Share clipboard** lives in a saved
 host's own edit sheet, because handing a machine your clipboard is a decision about that one host —

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

@@ -137,8 +137,9 @@ runs what it already knows about the title, so a client can never hand the host
   keep a **Show game library** switch, on by default, for turning it off. See
   [Client settings](/docs/client-settings).
 - **Android** — the library lives only in the controller-optimized home, which a TV always uses and a
-  phone or tablet switches to when a controller is connected. Press **Y** on a saved host, or open its
-  options and choose **Library**.
+  phone or tablet switches to when a controller is connected. Press **Y** on a saved host, or press
+  **up** for its options and choose **Library** — the route a TV remote takes, having no **Y** to
+  press.
 - **Steam Deck (Decky)** — the panel is a launcher and browses nothing itself: tap **Open
   Punktfunk**, which opens the client's console home, where a paired host's **Library** button is —
   full-screen covers, gamepad-navigable, and a press starts the stream with the title launching. See

docs-site/content/docs/input.md

@@ -42,13 +42,11 @@ uplink keeps running underneath, so unmuting is instant.
 While muted, a **Microphone muted** badge sits in the top-right corner of the stream — separate
 from the [stats overlay](/docs/stats), so it shows even with stats off.
 
-The mute lasts for that stream only — the next session starts unmuted, and nothing is written to
-your settings. If the stream isn't sending a microphone at all (**Stream microphone** off in
-[client settings](/docs/client-settings#audio)) the shortcut does nothing and no badge appears.
-
-**Linux and Windows** clients only — a Steam Deck stream is the Linux client, so an attached
-keyboard gets the chord. The Apple and Android clients have no mute shortcut yet; turn **Stream
-microphone** off in their settings instead.
+The mute lasts for that stream only — the next session starts unmuted; nothing is written to your
+settings. With **Stream microphone** off in [client settings](/docs/client-settings#audio) the
+shortcut does nothing and no badge appears. **Linux and Windows** clients only (a Steam Deck stream
+is the Linux client, so an attached keyboard gets the chord); on Apple and Android turn **Stream
+microphone** off in settings instead.
 
 Alt-Tabbing away releases input on its own and takes it back when you return. A release you asked
 for with the chord stays released until you opt back in. Either way, keys and buttons you were
@@ -104,10 +102,9 @@ watching for the chord either way.
 ### Statistics with a controller
 
 The **Apple** apps reserve a second chord: **Select + X**, which cycles the
-[stats overlay](/docs/stats) one level each time you complete it. For when you have a pad but no
-keyboard for **⌃⌥⇧S** and no free screen for the three-finger tap; on **Apple TV** it is the only
-way there with a pad. X is deliberately none of the four leave-chord buttons, so reaching for one
-chord never trips the other. Both buttons still reach the game; only the overlay changes locally.
+[stats overlay](/docs/stats) one level each time you complete it — for a pad with no keyboard and
+no free screen for the three-finger tap; on **Apple TV** it is the only way there with a pad. Both
+buttons still reach the game; only the overlay changes locally.
 
 On the **Siri Remote**, **hold Play/Pause** for about half a second instead. A quick tap is still a
 right click, sent when you let go.
@@ -115,26 +112,23 @@ right click, sent when you let go.
 ### The guide button (Xbox / PS / Steam) and Quick Access
 
 A controller's **guide button** — the Xbox logo, the PS button, the Deck's **Steam** button — is
-meant to open menus **on the host**: the Steam overlay, or a Gaming-Mode host's Steam menu. Some
-devices want that button for themselves, so every client also carries a gesture that works
-everywhere:
-
-**Hold Select (Back / View) on its own for about a third of a second.** The host sees its guide
-button held down for as long as you hold — a long press, which is how SteamOS opens the **Quick
-Access Menu** for a regular pad. A quick tap of Select still reaches the game, delivered when you
-let go (a beat late). Select pressed as part of a combo — including the leave chord above — passes
-through untouched.
+meant to open menus **on the host**. Some devices want that button for themselves, so every client
+also carries a gesture that works everywhere: **hold Select (Back / View) on its own for about a
+third of a second**. The host sees its guide button held for as long as you hold — a long press,
+which is how SteamOS opens the **Quick Access Menu** for a regular pad. A quick tap of Select still
+reaches the game, delivered when you let go (a beat late); Select in a combo — including the leave
+chord above — passes through untouched.
 
 What the raw button does, per client:
 
 - **Linux & Windows desktop, macOS, Android** — the guide press is forwarded to the host. If Steam
   Big Picture or the Xbox Game Bar is also watching for it *on the device in your hands*, both may
   react — that's a local setting on that device, not something the stream can suppress.
-- **Steam Deck / Gaming Mode** — the **Steam** and **`…`** buttons stay with the Deck by default:
-  SteamOS always opens its own menus for them, so forwarding the raw press as well opened BOTH menus
-  at once, the Deck's on top of the stream. Reach the host's menus with **hold-Select**, or with the
-  Punktfunk panel's **Host menus** buttons ([Steam Deck page](/docs/steam-deck)). The old behavior
-  is one setting away: **Steam / guide button → Send to host**.
+- **Steam Deck / Gaming Mode** — the **Steam** and **`…`** buttons stay with the Deck by default
+  (SteamOS always opens its own menus for them; forwarding the raw press too opens both menus at
+  once). Reach the host's menus with **hold-Select**, or the Punktfunk panel's **Host menus**
+  buttons ([Steam Deck page](/docs/steam-deck)); **Steam / guide button → Send to host** restores
+  the old behavior.
 - **iPhone / iPad** — iOS reserves the Home press for its own Game Overlay, so hold-Select is the
   reliable route to the host's overlay. On iOS 27 or later you can also hand the button to the app
   yourself, in the system's per-controller Home-button setting.
@@ -200,11 +194,9 @@ Touch passthrough depends on the host being able to inject touch, and that varie
 | Sway, Hyprland and other wlroots compositors | Not injected — contacts are dropped |
 | gamescope Gaming Mode | Degraded to a single absolute pointer — see [gamescope](/docs/gamescope) |
 
-The gamescope row is a rule, not an exception: wherever the compositor offers no touchscreen device
-to drive, only the first finger is used, as an absolute pointer. Tapping still clicks; pinches and
-other multi-finger gestures do not survive.
-
-The trackpad and pointer models are unaffected by all of this: they send ordinary mouse events.
+Wherever the compositor offers no touchscreen device to drive, only the first finger is used, as
+an absolute pointer — tapping still clicks; pinches and multi-finger gestures don't survive. The
+trackpad and pointer models are unaffected: they send ordinary mouse events.
 
 ## Pen and stylus
 
@@ -237,10 +229,9 @@ The Linux, Windows, macOS and Apple TV clients do not send stylus input.
 the virtual gamepads need, step 3 of your [install guide](/docs/install). Without it the host never
 offers pen at all.
 
-**If the host is too old, or pen is switched off**, nothing breaks: the client keeps folding the
-stylus into its ordinary touch or pointer path. You can still draw — just without pressure and tilt.
-Whether pen splits out is decided by the host, not by your touch mode: you can be in Trackpad mode
-and still draw with full fidelity.
+**If the host is too old, or pen is switched off**, the client folds the stylus into its ordinary
+touch or pointer path — you can still draw, without pressure and tilt. Whether pen splits out is
+decided by the host, not your touch mode.
 
 **Operators** can turn the whole feature off by setting `PUNKTFUNK_PEN=0` in the host's `host.env`
 (see [Configuration](/docs/configuration)). The host then stops advertising pen to Punktfunk and

docs-site/content/docs/install.mdx

@@ -30,13 +30,13 @@ console, and tells you how to pair:
 
 <Installer />
 
-Prefer to read what runs first (it's plain `sh`, ~350 lines):
+Prefer to read what runs first (it's plain `sh`, ~450 lines):
 
 <Installer inspect />
 
 It asks before anything optional (Moonlight compat, the shared clipboard, the `punktfunk` group,
 starting at boot) and every answer has a default, so `sh install.sh --yes` — or piping it with no
-terminal — runs unattended; `--channel canary`, `--mgmt-port`, `--no-start` and the environment
+terminal — runs unattended; `--channel canary`, `--mgmt-port`, `--no-start`, `--uninstall` and the environment
 twins (`PUNKTFUNK_INSTALL_YES`, `PUNKTFUNK_INSTALL_CHANNEL`, `PUNKTFUNK_INSTALL_GAMESTREAM`,
 `PUNKTFUNK_INSTALL_CLIPBOARD`, `PUNKTFUNK_INSTALL_PUNKTFUNK_GROUP`, `PUNKTFUNK_INSTALL_LINGER`,
 `PUNKTFUNK_INSTALL_MGMT_PORT`) are listed by `--help`. It covers Ubuntu/Debian, Fedora, Arch-family

docs-site/content/docs/pairing.md

@@ -36,15 +36,15 @@ stream on a host this device already trusts.
 
 ## Choosing access when you admit a device
 
-Approving and deciding what the device may do are one dialog. Alongside the name:
+Approving and deciding what the device may do are one dialog:
 
-- **Access level** — **Full control**, **Controller only**, or **View only** (an **Advanced**
-  expander has the individual toggles — [Access levels](/docs/access-levels)).
-- **Expires** — **Forever**, or 1 h / 4 h / 8 h / custom.
+![Approve this device: name, access level, expiry, and the one-click Approve as guest](/img/console-approve-device.png)
 
-Defaults are *Full control · Forever* — right for your own new laptop. For a friend's device there
-is a one-click **Approve as guest**: Controller only, for 4 hours, then it expires on its own. The
-same two controls sit on the **Pair a device** card, and apply to whichever device completes the PIN.
+The levels are **Full control**, **Controller only** and **View only** (**Advanced** opens the
+individual toggles — [Access levels](/docs/access-levels)); expiry is **Never** or 1 h / 4 h / 8 h /
+custom. The defaults are right for your own new laptop; **Approve as guest** is for a friend's
+device — Controller only, for 4 hours, then it expires on its own. The same two controls sit on the
+**Pair a device** card, and apply to whichever device completes the PIN.
 
 ## Managing paired devices
 

docs-site/content/docs/plugins.mdx

@@ -5,7 +5,8 @@ description: First-party plugins — bring each of your game launchers into the
 
 Plugins extend the host through the **scripting runner** (see [Events & hooks](/docs/automation)). A
 plugin runs alongside the host, reconciles titles into your [game library](/docs/game-library) as a
-provider — so they appear in the grid on every client — and can add its own page to the [web console](/docs/web-console).
+provider — so they appear in the grid on every client — and can add its own page to the
+[web console](/docs/web-console).
 
 **Your game library is built from plugins.** From v0.28.0 the host scans no launcher on its own;
 install the one for each launcher you use.
@@ -29,8 +30,7 @@ off succeeds and starts nothing, so check it first:
 1. Open the [web console](/docs/web-console) → **Plugins** → **Installed** and look at the **Plugin
    runner** card. *Not installed*: install the runner package first (see
    [Troubleshooting](#troubleshooting)). *Disabled*: press **Enable runner** — once per host.
-   *Running* means you're set; *Stopped* means the runner is enabled but not up right now, and its
-   log says why (see [Troubleshooting](#troubleshooting)).
+   *Stopped*: the runner is enabled but not up, and its log says why.
 2. Go to **Browse**, pick a plugin from the catalog and confirm. The host installs it and restarts
    the runner, and the plugin's own page appears in the console's nav.
 
@@ -39,14 +39,13 @@ off succeeds and starts nothing, so check it first:
 ### What "Verified" means
 
 Every catalogued plugin pins **one exact version** and its package hash. **Verified** means somebody
-at unom reviewed *that exact package* — not the project in general, not whatever it publishes next;
-when a plugin releases a new version, the store keeps offering the reviewed one until the new release
-is reviewed too. Before anything is downloaded, the host re-checks the pinned hash against the
-registry, so a package quietly republished under the same version number is refused.
+at unom reviewed *that exact package* — not the project in general; a new release keeps offering the
+reviewed version until the new one is reviewed too. Before anything is downloaded, the host
+re-checks the pinned hash against the registry, so a package quietly republished under the same
+version number is refused.
 
-A catalog can also **revoke** a version. When an advisory covers an entry, the console shows the
-reason and won't install that version — on **Browse** as a red-ringed panel with the install button
-disabled, on **Installed** as a warning against the plugin you already have. It never removes
+A catalog can also **revoke** a version: the console shows the advisory and won't install it — a
+red-ringed panel on **Browse**, a warning on **Installed** if you already have it. It never removes
 running code for you.
 
 The three badges:
@@ -54,18 +53,15 @@ The three badges:
 | Badge | Where it came from |
 |---|---|
 | **Verified** | The built-in catalog. unom reviewed this exact package. |
-| **External source**, *from <source>* | A catalog **you** added. Still pinned and hash-checked, but curated by somebody else — unom has not looked at the code. This badge is amber, not the red **Unverified** below. |
-| **Unverified** | Installed by hand from a package spec. Nobody reviewed it and nothing pins it; the console asks you to type the name to confirm, and the plugin stays marked this way for as long as it is installed. |
+| **External source**, *from <source>* | A catalog **you** added. Still pinned and hash-checked, but curated by somebody else — unom has not looked at the code. Amber, not the red **Unverified** below. |
+| **Unverified** | Installed by hand from a package spec. Nobody reviewed it and nothing pins it; the console asks you to type the name to confirm, and the mark stays for as long as it is installed. |
 
 ### Adding another catalog
 
 **Sources** → *Add a catalog source*: a name and the URL of its index. Optionally paste the source's
 `ed25519:…` public key — with a key set, the host refuses any index from that source that isn't
-correctly signed, rather than falling back to an unsigned one.
-
-Adding a source is a trust decision you make once: its plugins become installable on this host,
-always attributed to it and never carrying the Verified badge, which belongs to the built-in
-catalog alone.
+correctly signed. Adding a source is a one-time trust decision: its plugins become installable,
+always attributed to it, never carrying **Verified**.
 
 To publish a plugin to the built-in catalog, open a pull request against
 [`punktfunk-plugin-index`](https://git.unom.io/unom/punktfunk-plugin-index) — its README covers the
@@ -73,9 +69,6 @@ format and what review looks for.
 
 ## Installing from the CLI
 
-Two commands: install the plugin, then turn the runner on. The host CLI handles the rest — creating
-the plugins directory, pointing it at the package registry, and starting the supervisor.
-
 <Tabs items={['Linux', 'Windows']}>
 <Tab value="Linux">
 
@@ -85,43 +78,43 @@ punktfunk-host plugins enable           # turn the runner on (once)
 ```
 
 On **SteamOS** the [host installer](/docs/steamos-host) ships the runner automatically (user-scoped
-under `~/.local` — the read-only `/usr` can't take the package). If the console reports the runner
-isn't installed on an older setup, re-run `scripts/steamdeck/update.sh` once.
+under `~/.local`). If the console reports the runner isn't installed on an older setup, re-run
+`scripts/steamdeck/update.sh` once.
 
 </Tab>
 <Tab value="Windows">
 
-Run these from an **elevated** PowerShell — right-click **PowerShell** → **Run as administrator**.
-The plugins directory lives under `%ProgramData%\punktfunk`, which is admin-owned. The runner task
-itself runs as the low-privilege `NT AUTHORITY\LocalService` account — `plugins enable` sets that
-up (including read access to the runner's scoped API token).
+Run these from an **elevated** PowerShell — the plugins directory lives under
+`%ProgramData%\punktfunk`, which is admin-owned. The runner task itself runs as the low-privilege
+`NT AUTHORITY\LocalService` account; `plugins enable` sets that up (including read access to the
+runner's scoped API token).
 
 ```powershell
 punktfunk-host plugins add playnite     # or: rom-manager
 punktfunk-host plugins enable           # turn the runner on (once)
 ```
 
-If `punktfunk-host` isn't found, open a **new** terminal (the installer adds it to `PATH`), or use
-the full path: `& "$env:ProgramFiles\punktfunk\punktfunk-host.exe" plugins add playnite`.
+If `punktfunk-host` isn't found, open a **new** terminal, or use the full path:
+`& "$env:ProgramFiles\punktfunk\punktfunk-host.exe" plugins add playnite`.
 
 </Tab>
 </Tabs>
 
 The plugin's page then appears in the [web console](/docs/web-console)'s nav automatically.
 
-The runner is **on by default** on a new install — your game sources are plugins, so a host without
-it would show an empty library. (A host that predates this stays however you left it; turn it on
-with `punktfunk-host plugins enable`, once.) The runner discovers plugins when it starts, so one
-installed later needs a restart (`systemctl --user restart punktfunk-scripting`, or `Restart` the
-`PunktfunkScripting` task) — the console does that restart for you as part of installing.
+The runner is **on by default** on a new install (a host that predates this stays however you left
+it — `punktfunk-host plugins enable`, once). The runner discovers plugins when it starts, so one
+installed later needs a runner restart — `systemctl --user restart punktfunk-scripting` on Linux,
+`Restart` the `PunktfunkScripting` task on Windows; the console does that restart for you as part
+of installing.
 
-Don't want it? It is a normal service you can switch off: `systemctl --user mask punktfunk-scripting`
-on Linux, or disable the `PunktfunkScripting` scheduled task on Windows. Your host keeps streaming;
-you just lose plugin-provided game sources and any automation.
+Don't want it? `systemctl --user mask punktfunk-scripting` on Linux, or disable the
+`PunktfunkScripting` scheduled task on Windows. The host keeps streaming; you lose plugin-provided
+game sources and automation.
 
-A plugin installed from the CLI shows up in the console as **Installed via CLI**: the console knows
-what is installed, but not who vouched for it. Install the same plugin from the store's Browse tab
-and it carries its catalog badge instead.
+A plugin installed from the CLI shows in the console as **Installed via CLI** — the console knows
+what is installed, not who vouched for it. Install the same plugin from **Browse** and it carries
+its catalog badge instead.
 
 ### The rest of the commands
 
@@ -144,33 +137,31 @@ always from Punktfunk's own package registry. Any other name (`punktfunk-plugin-
 
 ## Updating and removing a plugin
 
-**Update.** The console's **Installed** tab grows an **Update to &lt;version&gt;** button whenever the
-catalog pins a newer version than the one you have; it installs through the same confirmation as a
-fresh install, and the console restarts the runner for you. There is no `plugins update` command —
-from a terminal, re-run `punktfunk-host plugins add <name>`. That installs the newest version the
-package registry has rather than the version the catalog pins, and does **not** restart the runner:
-restart it yourself (`systemctl --user restart punktfunk-scripting`, or `Restart` the
-`PunktfunkScripting` task) so the new code is picked up.
+**Update.** The **Installed** tab grows an **Update to &lt;version&gt;** button whenever the catalog
+pins a newer version; it installs through the same confirmation and restarts the runner for you.
+There is no `plugins update` command — from a terminal, re-run `punktfunk-host plugins add <name>`,
+which installs the newest version the *registry* has (not the catalog pin) and does **not** restart
+the runner: restart it yourself so the new code is picked up.
 
-**Remove.** The **Uninstall** (bin) button on the **Installed** tab removes the package *and*
-restarts the runner, so the plugin stops straight away. `punktfunk-host plugins remove <name>`
-removes the package only — restart the runner yourself, as above, to stop a plugin still running.
+**Remove.** The **Uninstall** (bin) button removes the package *and* restarts the runner.
+`punktfunk-host plugins remove <name>` removes the package only — restart the runner yourself to
+stop a plugin still running.
 
-Uninstalling removes the package only; a plugin's own config and cache stay where it wrote them —
+Uninstalling removes the package only; a plugin's own config and cache stay —
 `~/.config/punktfunk/plugin-state/<plugin>/` on Linux,
 `%ProgramData%\punktfunk\plugin-state\<plugin>\` on Windows — so re-installing later picks your
-settings back up. Delete that directory yourself if you want it gone.
+settings back up.
 
-To stop *every* plugin without uninstalling anything, turn the runner off: **Disable runner** on the
-Installed tab, or `punktfunk-host plugins disable`.
+To stop *every* plugin without uninstalling anything: **Disable runner** on the Installed tab, or
+`punktfunk-host plugins disable`.
 
 ## ROM Manager
 
 `@punktfunk/plugin-rom-manager` — point it at your ROM directories and it scans them, matches each
-platform to an installed emulator, fetches box art (SteamGridDB, or the keyless libretro thumbnails),
-and reconciles the result into your library as the `rom-manager` provider. ~25 built-in platforms
-(NES through Switch, PS1/2/PSP, Dreamcast, and more), per-game overrides, and a console page to
-configure it all.
+platform to an installed emulator, fetches box art (SteamGridDB, or the keyless libretro
+thumbnails), and reconciles the result into your library as the `rom-manager` provider. ~25
+built-in platforms (NES through Switch, PS1/2/PSP, Dreamcast, and more), per-game overrides, and a
+console page to configure it all.
 
 ```sh
 punktfunk-host plugins add rom-manager
@@ -212,21 +203,20 @@ Then add a root or two — from the console's **ROM Manager** page, or in the co
 </Tabs>
 
 `plugin-state` is where a plugin reads and writes its own files — on Windows it is the one
-directory `plugins enable` grants the low-privilege runner write access to. A config file placed
+directory `plugins enable` grants the low-privilege runner write access to; a config file placed
 anywhere else under `%ProgramData%\punktfunk` is not read.
 
-Full options and the platform/emulator list are in
+Full options and the platform/emulator list:
 [the plugin's repo](https://git.unom.io/unom/punktfunk-plugin-rom-manager).
 
 ## Playnite
 
-`@punktfunk/plugin-playnite` — mirrors your **[Playnite](https://playnite.link)** library (Steam,
-GOG, Epic, Xbox, itch, emulators, manually-added games — everything Playnite manages) into your
-library. Launching a title hands it back to Playnite, which performs the real launch, so there are no
-per-store launch commands to maintain. Covers are served by the host, so it scales to large libraries.
+`@punktfunk/plugin-playnite` — mirrors your **[Playnite](https://playnite.link)** library (every
+store and emulator Playnite manages) into your library. Launching a title hands it back to
+Playnite, so there are no per-store launch commands to maintain; covers are served by the host.
 
-Playnite is Windows-only, so both halves live on the **Windows host**. Because Playnite keeps its
-library locked while running, there are **two parts**:
+Playnite keeps its library locked while running, so there are **two parts**, both on the **Windows
+host**:
 
 1. **The plugin** — from an elevated PowerShell:
 
@@ -236,20 +226,19 @@ library locked while running, there are **two parts**:
    ```
 
 2. **The Punktfunk Sync extension** (in Playnite) — download `punktfunk-sync.pext` from the
-   [plugin's builds](https://git.unom.io/unom/punktfunk-plugin-playnite/actions) and **double-click
-   it** to install it in Playnite like any add-on, then restart Playnite once.
+   [plugin's builds](https://git.unom.io/unom/punktfunk-plugin-playnite/actions), **double-click**
+   to install it like any add-on, restart Playnite once.
 
-Open the console's **Playnite** page — it shows "Exporter connected", and your games sync within
-seconds of any library change. Filters (installed-only, per-store, hidden) live on that page or in
-`%ProgramData%\punktfunk\plugin-state\playnite\config.json`. Details are in
+The console's **Playnite** page shows "Exporter connected", and your games sync within seconds of
+any library change. Filters (installed-only, per-store, hidden) live on that page or in
+`%ProgramData%\punktfunk\plugin-state\playnite\config.json`. Details:
 [the plugin's repo](https://git.unom.io/unom/punktfunk-plugin-playnite).
 
 ## VirtualHere (USB passthrough)
 
 `@punktfunk/plugin-virtualhere` — hands a **physical USB device** on your couch machine to the
 host while you play, and gives it back afterwards. The game sees the real device — the answer for a
-racing wheel, a HOTAS, pedals, an arcade stick, or any controller whose value is that it is not
-emulated.
+racing wheel, HOTAS, pedals or arcade stick.
 
 <Callout type="warn">
 This plugin drives [VirtualHere](https://www.virtualhere.com/), a commercial USB-over-IP product
@@ -258,31 +247,28 @@ Punktfunk — you install and license it yourself. The plugin is not affiliated
 VirtualHere.
 </Callout>
 
-You need both halves of VirtualHere running before the plugin is any use:
+You need both halves of VirtualHere running first:
 
 - **The USB Server on the couch**, sharing the device. Free for one device; beyond that, and to run
   the client as a service, VirtualHere requires a purchased licence.
 - **The USB Client on the host**, ideally installed as a service so it survives logging out.
 
 Servers exist for Windows, Linux, macOS and Android couches. **There is no VirtualHere server for
-iOS or tvOS**, so iPhones, iPads and Apple TVs cannot pass devices through.
+iOS or tvOS.**
 
 ```sh
 punktfunk-host plugins add virtualhere
 punktfunk-host plugins enable
 ```
 
-Then open the console's **VirtualHere** page. The **Devices** tab lists whatever the couch is
-sharing; pick one and it writes a rule matching the device *by name*, which keeps working after the
-couch reboots or the device moves to another port. By default the device is handed over when video
-starts and returned when it stops, so the couch keeps its own controller the rest of the time —
-you can widen that to the whole session, or to the entire time a client is connected.
+The console's **VirtualHere** page → **Devices** lists whatever the couch is sharing; pick one and
+it writes a rule matching the device *by name*, which survives reboots and port changes. By default
+the device is handed over when video starts and returned when it stops; you can widen that to the
+whole session, or to the entire time a client is connected.
 
-If nothing happens, the **Diagnostics** tab walks the whole two-sided setup and tells you which
-part to fix. The same checks run as `punktfunk-plugin-virtualhere doctor` — the useful thing to
-paste into a support thread.
-
-Full configuration is in
+If nothing happens, the **Diagnostics** tab walks the two-sided setup and names the part to fix —
+the same checks as `punktfunk-plugin-virtualhere doctor`, the useful thing to paste into a support
+thread. Full configuration:
 [the plugin's repo](https://git.unom.io/unom/punktfunk-plugin-virtualhere).
 
 ## Troubleshooting
@@ -291,38 +277,31 @@ Full configuration is in
 installer's `PATH` change, or call the exe by full path. On Linux the host package installs it to
 `/usr/bin/punktfunk-host`.
 
-**"the plugin runner isn't installed"** — the runner ships as its own package. On Ubuntu:
-`sudo apt install punktfunk-scripting`. On Fedora: `sudo dnf install punktfunk-scripting` from the
-[same RPM repo you installed the host from](/docs/fedora). On Arch:
-`sudo pacman -Syu punktfunk-scripting` (a full `-Syu`, like every other install from that repo).
-On SteamOS, re-run `scripts/steamdeck/install.sh` (or
-`scripts/steamdeck/update.sh`). On NixOS it comes with `services.punktfunk.scripting.enable` (on by
-default whenever the host is). On Windows, re-run the installer and keep the scripting component.
+**"the plugin runner isn't installed"** — the runner ships as its own package. Ubuntu:
+`sudo apt install punktfunk-scripting`. Fedora: `sudo dnf install punktfunk-scripting` from the
+[same RPM repo as the host](/docs/fedora). Arch: `sudo pacman -Syu punktfunk-scripting` (a full
+`-Syu`). SteamOS: re-run `scripts/steamdeck/install.sh` (or `update.sh`). NixOS: comes with
+`services.punktfunk.scripting.enable` (on by default whenever the host is). Windows: re-run the
+installer and keep the scripting component.
 
 If the runner *is* installed and the host still says it isn't, the host could not find the
-`punktfunk-scripting` executable. It looks beside its own binary, then on `PATH`, then in the
-packaged `/usr` and `~/.local` layouts — so a runner installed somewhere else needs
-`PUNKTFUNK_SCRIPTING` pointed at it (see [Configuration](/docs/configuration)). The console installs
-plugins from inside the host *service*, whose `PATH` is usually much shorter than your shell's: a
-runner that `punktfunk-host plugins add` finds and the console does not is that difference, and the
-env var is the fix.
+`punktfunk-scripting` executable — it looks beside its own binary, then on `PATH`, then in the
+packaged `/usr` and `~/.local` layouts. Point `PUNKTFUNK_SCRIPTING` at it (see
+[Configuration](/docs/configuration)). The console installs plugins from inside the host *service*,
+whose `PATH` is much shorter than your shell's — a runner that `plugins add` finds and the console
+doesn't is that difference, and the env var is the fix.
 
 **Where a plugin's log output goes** — the console's **Logs** page, under the **Plugins** filter.
-The runner ships everything your plugins print to the host, so a plugin's own lines sit next to the
-host's, on one timeline, with the same search and download. Each is tagged `plugin:<name>` — the
-plugin's own name for lines it logged itself, `plugin:runner` for the supervisor's (starting a
-plugin, restarting a crashed one, refusing an unsafe file).
-
-An empty Plugins view almost always means the runner isn't running — it is a separate service. Check
-with `punktfunk-host plugins status`.
+Plugin lines sit next to the host's, on one timeline, tagged `plugin:<name>` (`plugin:runner` for
+the supervisor). An empty Plugins view almost always means the runner isn't running — check with
+`punktfunk-host plugins status`.
 
 <Callout>
 Nothing is lost if the host is down: the runner keeps buffering and sends the backlog when the host
 comes back, and says so in the log if the buffer overflowed.
 </Callout>
 
-**Reading the runner's log directly** — rarely needed, but the ground truth if the runner can't
-reach the host at all:
+**Reading the runner's log directly** — the ground truth if the runner can't reach the host at all:
 
 <Tabs items={['Linux', 'Windows']}>
 <Tab value="Linux">
@@ -334,19 +313,17 @@ journalctl --user -u punktfunk-scripting -f
 </Tab>
 <Tab value="Windows">
 
-The runner task writes its output to `%ProgramData%\punktfunk\plugin-state\runner.log` (the
-previous run is kept as `runner.log.1`). Read — or send — this file when the console's Plugins view
-stays empty although the runner is running: everything the runner and its plugins printed lands
-here even when they can't reach the host.
+The runner task writes to `%ProgramData%\punktfunk\plugin-state\runner.log` (previous run:
+`runner.log.1`) — everything the runner and its plugins printed lands here even when they can't
+reach the host.
 
 ```powershell
 Get-Content "$env:ProgramData\punktfunk\plugin-state\runner.log" -Tail 100
 ```
 
 If the file doesn't exist, the task started before `punktfunk-host plugins enable` ever ran (which
-is what makes `plugin-state` writable for the runner's `LocalService` account) — run it from an
-elevated prompt, then read the file. To watch a start live instead, run the runner in the
-foreground (stop it with <kbd>Ctrl</kbd>+<kbd>C</kbd>):
+is what makes `plugin-state` writable for `LocalService`) — run it from an elevated prompt. To
+watch a start live, run the runner in the foreground (<kbd>Ctrl</kbd>+<kbd>C</kbd> stops it):
 
 ```powershell
 & "$env:ProgramFiles\punktfunk\bun\bun.exe" "$env:ProgramFiles\punktfunk\scripting\runner-cli.js"
@@ -357,9 +334,9 @@ foreground (stop it with <kbd>Ctrl</kbd>+<kbd>C</kbd>):
 
 **A plugin can't reach a service running on the same box (Linux)** — plugins that drive a local
 daemon usually talk to it over a socket or FIFO in `/tmp`. The runner's unit shipped with
-`PrivateTmp=yes` in earlier releases, hiding the real `/tmp`: the plugin would launch the vendor's
-binary and then time out reaching the daemon, while the same command worked in your own shell. On an
-older host, or with a drop-in that reinstates it, put the real `/tmp` back:
+`PrivateTmp=yes` in earlier releases, hiding the real `/tmp`: the plugin launches the vendor's
+binary and times out reaching the daemon, while the same command works in your shell. On an older
+host, or with a drop-in that reinstates it:
 
 ```sh
 systemctl --user edit punktfunk-scripting
@@ -377,5 +354,4 @@ by the runner. The kit owns lifecycle, config and state, the library sync engine
 plugin's console page; `@punktfunk/host` (`definePlugin`) is the lower-level host client underneath
 it. Start from the
 [plugin-kit README](https://git.unom.io/unom/punktfunk/src/branch/main/plugin-kit) and
-[ROM Manager](https://git.unom.io/unom/punktfunk-plugin-rom-manager), which is the reference
-implementation — or any of the three plugins above.
+[ROM Manager](https://git.unom.io/unom/punktfunk-plugin-rom-manager), the reference implementation.

docs-site/content/docs/quickstart.md

@@ -45,6 +45,8 @@ certificate is the host's own, so your browser warns once — continue) and log
   (SteamOS: the install script printed it; it's in `~/.config/punktfunk/web.env`).
 - **Windows:** the installer showed it on its last page.
 
+![The console sign-in card: one password field](/img/console-login.png)
+
 Lost it? [Forgot your password](/docs/forgot-password). Everything else about the console:
 [The Web Console](/docs/web-console).
 
@@ -54,11 +56,16 @@ On the device you want to stream *to*, install the app — [Install a Client](/d
 has the link for every device (Mac, iPhone/iPad/Apple TV, Linux, Windows, Android, Steam Deck), and
 any Moonlight client works too once you [turn GameStream on](/docs/moonlight).
 
-Open the app: your host is already in the list. Select it and **connect**. Back in the console, the
-device appears under **Pairing → Waiting for approval** — click **Approve** and it's in, no PIN to
-type. (Prefer a PIN? Click **Pair a device** in the console and type the 4-digit code into the
-client.) Pairing happens once; the device reconnects on its own from then on.
-Details: [Pairing & Trust](/docs/pairing).
+Open the app: your host is already in the list.
+
+![The client's host list: saved hosts with their pairing state, and unpaired hosts found on this network](/img/client-hosts.png)
+
+Select it and **connect**, then click **Approve**
+next to the device in the console's **Pairing** page — no PIN to type. (Prefer a PIN? **Pair a device**
+shows a 4-digit code to type into the client.) Pairing happens once; the device reconnects on its
+own from then on. Details: [Pairing & Trust](/docs/pairing).
+
+![The console's Pairing page: two devices waiting for approval, and an armed 4-digit PIN](/img/console-pairing.png)
 
 ## 5. Stream
 

docs-site/content/docs/uninstall.md

@@ -23,6 +23,10 @@ Jump to what you installed:
 
 ## Linux hosts
 
+If you installed with the guided script, `sh install.sh --uninstall` runs this section and the
+package removal for your family in one go (fetch it again with `curl -fsSLO https://punktfunk.unom.io/install.sh`);
+what it leaves behind is the same list below.
+
 ### Stop the services first
 
 The Linux packages ship systemd **user** units, and `systemctl --user enable` writes symlinks into

docs-site/content/docs/virtual-displays.md

@@ -11,8 +11,7 @@ settings like scaling.
 
 Set it in the **web console** (the **Virtual displays** page), or edit
 `~/.config/punktfunk/display-settings.json` (`%ProgramData%\punktfunk\display-settings.json` on
-Windows). A change applies to the **next** connection — a running session keeps the display it
-opened on.
+Windows). A change applies to the **next** connection.
 
 > **You rarely need to touch this.** The default matches how Punktfunk has always worked; reach for
 > a preset when you want a specific experience.
@@ -23,43 +22,33 @@ opened on.
 To stream a monitor the host **already has** instead, see
 [Stream a real monitor instead](#stream-a-real-monitor-instead) — it turns most of this page off.
 
-> **What's live today:** **keep-alive** (linger, or **forever**), **topology** (extend / primary /
-> exclusive), **conflict handling**, **per-client identity + persistent scaling** (Windows, KDE/KWin
-> *and* GNOME/Mutter) and **multi-monitor layout** (several clients as monitors of one desktop) are
-> all enforced. A reconnect — even a fast one — always resumes the kept display instead of spawning
-> a second. Gaps, noted inline: the Linux `primary` physical-keep *effect*, and multi-display for a
-> *single* client (the next stage).
-
 ## Stream a real monitor instead
 
-> **Linux only.** A Windows host enumerates its monitors but has no backend that can capture one, so
-> the Streamed screen card is read-only there and every Windows session gets a virtual display.
+> **Linux only.** A Windows host enumerates its monitors but has no backend that can capture one —
+> the Streamed screen card is read-only there.
 
-For a wall-mounted shop-floor PC, a lab bench machine or a media box's TV output, you want *that*
-screen, not a new one. Set **Virtual displays → Streamed screen** in the console to a listed
-monitor and Punktfunk streams that physical monitor instead of creating a virtual display; every
-client sees it at *its* resolution.
+Set **Virtual displays → Streamed screen** in the console to a listed monitor and Punktfunk streams
+that physical monitor instead of creating a virtual display; every client sees it at *its*
+resolution.
 
 - The monitor is **never touched** — not resized, moved, disabled or restored. Keep-alive, topology
-  and multi-monitor layout don't apply: there's no display of ours to apply them to.
+  and multi-monitor layout don't apply.
 - **The resolution is the monitor's**, not yours. A client asking for a different one is told no and
-  scales its own picture; the mid-stream resize machinery is switched off.
+  scales its own picture; mid-stream resize is off.
 - **Every client sees the same screen** — two clients are two viewers of one monitor.
-- Naming a monitor this host **doesn't have, while it has others**, is a **hard error**, not a
-  fallback: the session fails with `no monitor named "DP-9" — this host has: HDMI-1`. The one
-  exception is a session with **no physical heads at all** — a nested or headless compositor: the
-  pin is set aside with a warning in the log, you get an ordinary virtual display, and the pin
-  applies again the next time a session with real heads runs.
+- Naming a monitor this host **doesn't have, while it has others**, is a **hard error**: the session
+  fails with `no monitor named "DP-9" — this host has: HDMI-1`. The exception is a session with
+  **no physical heads at all** (nested or headless compositor): the pin is set aside with a log
+  warning, you get an ordinary virtual display, and the pin applies again on the next session with
+  real heads.
 - **Virtual screen (default)** in the same card puts you back on the normal path.
 
 Supported on **KDE/KWin**, **GNOME/Mutter**, **Sway/wlroots**, **Hyprland** and **gamescope Game
-Mode** (a Steam Deck / Bazzite couch box, where gamescope drives the screen) — each through the
-compositor's own screen-recording API, so there is **no chooser dialog**. That matters for a host
-running unattended as a [service](/docs/running-as-a-service): a background `systemd --user` daemon
-has nobody to answer a permission prompt. On gamescope only the head the session is driving is
-listed — mirroring attaches to the session's own composited stream, so that screen keeps showing
-what the person in front of it sees and nothing is relaunched. A *nested* or headless gamescope (the
-per-client sessions the host spawns itself) has no head, so the picker is empty there.
+Mode** — each through the compositor's own screen-recording API, so there is **no chooser dialog**
+(a background [service](/docs/running-as-a-service) has nobody to answer one). On gamescope only the
+head the session is driving is listed — mirroring attaches to the session's own composited stream,
+so the screen keeps showing what the person in front of it sees. A *nested* or headless gamescope
+has no head, so the picker is empty there.
 
 ### Naming the monitor from the host
 
@@ -83,8 +72,8 @@ To pin it **from the host's configuration** instead — the appliance route —
 PUNKTFUNK_CAPTURE_MONITOR=HDMI-A-1
 ```
 
-The environment variable **wins over the console setting**, so an operator's declaration can't be
-re-aimed by a click; the console shows the Streamed screen card as locked while it's set.
+The environment variable **wins over the console setting**; the console shows the card as locked
+while it's set.
 
 Check the whole path — mirror, capture, frames — without a client:
 
@@ -98,10 +87,9 @@ the mouse on the host while it runs or a working mirror reads as a stall.
 ### Absolute input follows the pin
 
 Pinning a monitor also re-aims **absolute** mouse and pen input to that head's origin, so a click
-lands where you point on *that* screen. Heads are matched by position, not size — two monitors can
-be the same size, and getting that wrong puts the pointer silently on the wrong screen. The host
-resolves the pin at startup and whenever the console writes it, so no restart is needed; the log
-line is `capture monitor: …`.
+lands where you point on *that* screen. Heads are matched by position, not size. The host resolves
+the pin at startup and whenever the console writes it — no restart; the log line is
+`capture monitor: …`.
 
 To check it with no client involved:
 
@@ -110,12 +98,10 @@ punktfunk-host anchor-test --monitor HDMI-A-1
 ```
 
 It lists this host's heads, says whether the box has the same-size pair the matching exists for,
-walks the pointer through the centre and corners so you can watch which screen it moves on, and
-prints the region it mapped into. `--none` runs the same walk unanchored, as an A/B.
-
-The anchor rides the **libei** injector — the backend a GNOME/Mutter host uses. On KWin, Sway and
-Hyprland the host injects through a different protocol, and `anchor-test` stops and says so rather
-than reporting a green run that proves nothing.
+walks the pointer through the centre and corners, and prints the region it mapped into. `--none`
+runs the same walk unanchored, as an A/B. The anchor rides the **libei** injector — the
+GNOME/Mutter backend. On KWin, Sway and Hyprland the host injects through a different protocol, and
+`anchor-test` stops and says so rather than reporting a green run that proves nothing.
 
 ## Pick a preset
 
@@ -132,20 +118,16 @@ further down.
 
 ## Save your own preset
 
-Once you've dialed in a setup — by tweaking a preset or setting every option under **Custom** —
-**save it as your own named preset** and switch back to it in one click.
-
 - **Save as preset** — names the settings currently in force (all the options below **plus**
   *Dedicated game sessions*) and adds it to the picker alongside the built-ins.
 - **Apply** — writes exactly those settings, like picking a built-in.
-- **Edit / delete** — rename it, update it to your current settings, or remove it. Deleting never
-  changes what's running — it only takes the card out of the picker.
+- **Edit / delete** — rename, update to your current settings, or remove. Deleting never changes
+  what's running.
 
-The built-in presets deliberately leave *Dedicated game sessions* alone, so switching presets never
-changes your game-launch routing; a **custom preset captures your full setup**, including that axis
-— it's *your* saved configuration, not a curated behavior bundle. Custom presets live on the host in
-`display-presets.json` (next to `display-settings.json`); the catalog and the active policy are
-independent, so editing a preset never disturbs a running session.
+The built-in presets leave *Dedicated game sessions* alone, so switching presets never changes your
+game-launch routing; a **custom preset captures your full setup**, including that axis. Custom
+presets live on the host in `display-presets.json` (next to `display-settings.json`); editing a
+preset never disturbs a running session.
 
 ## Options reference
 
@@ -154,28 +136,25 @@ Choose **Custom** in the console to set these directly.
 ### Keep alive
 
 How long the virtual display survives after your last session disconnects. On a gamescope game host
-this also keeps the **game itself running**, so you can reconnect straight back into it.
+this also keeps the **game itself running**.
 
 - **Off** — tear the display down at session end.
-- **A duration** (seconds) — keep it that long; a reconnect inside the window drops you straight
-  back in, with no re-negotiation and no desktop reshuffle.
+- **A duration** (seconds) — a reconnect inside the window drops you straight back in, with no
+  re-negotiation and no desktop reshuffle.
 - **Forever** — keep it until you stop the host or **release it** from the console (**Virtual
   displays** → *Release*). The headless-box model.
 
-Default: **10 seconds**. Windows has always lingered 10 s; the Linux backends previously tore down
-immediately — a short linger makes reconnects smoother on both.
+Default: **10 seconds**.
 
-**A reconnect always resumes the kept display** — the host recognises your device and hands back the
-same display, even a second or two after dropping (before it has noticed you left). **Deliberately
-quitting** (closing the client, not a network drop) tears the display down at once, skipping the
-linger. How quickly a *dropped* client is noticed is the QUIC idle
-timeout — 8 s by default, tunable with `PUNKTFUNK_IDLE_TIMEOUT_MS` (see
-[Legacy environment knobs](#legacy-environment-knobs)) to free kept displays sooner.
+**A reconnect always resumes the kept display** — even a second or two after dropping.
+**Deliberately quitting** (closing the client, not a network drop) tears the display down at once,
+skipping the linger. How quickly a *dropped* client is noticed is the QUIC idle timeout — 8 s by
+default, tunable with `PUNKTFUNK_IDLE_TIMEOUT_MS` (see
+[Legacy environment knobs](#legacy-environment-knobs)).
 
 > **Keep-alive + Exclusive keeps your physical monitors dark after you disconnect**, until the
-> linger expires or you release the display. Intentional for a dedicated gaming box — but don't set
-> a long/forever keep-alive with Exclusive on a machine whose monitors you also use in person; use
-> **Shared desktop** there.
+> linger expires or you release the display. Intentional for a dedicated gaming box — on a machine
+> whose monitors you also use in person, use **Shared desktop**.
 
 ### Topology
 
@@ -184,11 +163,9 @@ What Punktfunk does with your monitor layout while it streams.
 - **Extend** — add the virtual display alongside your real monitors; touch nothing else.
 - **Primary** — make the virtual display your primary output; physical monitors stay on.
 - **Exclusive** — the virtual display becomes your **only** enabled output (physical monitors are
-  disabled, then restored when streaming ends). This makes the streamed surface *be* the desktop,
-  so panels and windows land on it.
+  disabled, then restored when streaming ends), so panels and windows land on it.
 - **Automatic** *(default)* — Exclusive on Windows and on an auto-detected KDE/GNOME desktop;
-  Extend when you've pinned a
-  specific compositor with `PUNKTFUNK_COMPOSITOR` (a test/CI posture).
+  Extend when you've pinned a specific compositor with `PUNKTFUNK_COMPOSITOR`.
 
 Per-backend support:
 
@@ -198,62 +175,51 @@ Per-backend support:
 | Primary | ✅ | ✅ | ⚠️ treated as Extend | ✅ |
 | Exclusive | ✅ | ✅ | ✅ | ✅ |
 
-**Primary** has no equivalent on **Sway/wlroots and Hyprland** — a Wayland fact, not a missing
-feature: there is no primary-output concept. They have a *focused* output, and the host points that
-at the streamed display — at session start, and again immediately before it launches anything from
-your library. Both open new windows on the focused monitor, which is what puts the game on the
-display you're streaming. Primary therefore behaves as Extend, and the host says so in the log.
+**Sway/wlroots and Hyprland have no primary-output concept**; they have a *focused* output, and the
+host points that at the streamed display — at session start, and again immediately before it
+launches anything from your library, which is what puts the game on the streamed display. Primary
+therefore behaves as Extend (the host says so in the log), and a window that opens *later* follows
+whatever has focus then — clicking a physical monitor mid-launch can still pull a window over.
 
-Because it's focus rather than promotion, a window that opens *later* (a launcher spawning a second
-window, a game re-parenting itself) follows whatever has focus then — so if you're also sitting at
-the machine, clicking a physical monitor mid-launch can still pull a window over to it.
+**Exclusive** on both compositor families:
 
-**Exclusive** does disable your physical monitors on both, and switches them back on when the last
-streaming display is torn down. Two compositor-specific details:
-
-- Punktfunk only disables monitors it did not create, so a second client streaming at the same time
-  never goes dark.
-- On Hyprland the restore is a `hyprctl reload`, because nothing else re-enables a monitor that a
-  rule disabled — a re-applied monitor rule is accepted and ignored. The reload re-reads your
-  Hyprland config, which puts your monitors back; the side effect is that settings changed at
-  runtime with `hyprctl keyword` are dropped too, and a non-Lua config re-runs its `exec =` lines
-  (`exec-once` is not re-run). This only happens if a session actually disabled something.
+- Punktfunk only disables monitors it did not create, so a second concurrent client never goes dark.
+- On Hyprland the restore is a `hyprctl reload` — nothing else re-enables a monitor a rule disabled.
+  The reload re-reads your Hyprland config; settings changed at runtime with `hyprctl keyword` are
+  dropped and a non-Lua config re-runs its `exec =` lines (`exec-once` is not). Only happens if a
+  session actually disabled something.
 
 ### Conflict handling · identity · layout
 
-- **Conflict handling** — what happens when a *different* client connects while one is already
-  streaming and asks for a different resolution: give it its own display (**separate**), take the
-  box over (**steal**), share the existing display at its current mode (**join**), or refuse it
-  (**reject**). On Linux, `separate` gives each client its own display on the shared desktop. On
-  **Windows** a second client is **rejected** (a clean "host busy") even under `separate` — two
-  clients can't yet share one virtual display's capture there (a later stage), so the live session
-  is protected instead. A same-client *reconnect* never conflicts — it resumes.
+- **Conflict handling** — a *different* client connects mid-stream asking for a different
+  resolution: give it its own display (**separate**), take the box over (**steal**), share the
+  existing display at its current mode (**join**), or refuse it (**reject**). On **Windows** a
+  second client is **rejected** ("host busy") even under `separate` — two clients can't yet share
+  one virtual display's capture there. A same-client *reconnect* never conflicts — it resumes.
 - **Identity** — whether each client gets a **stable display identity** so your desktop environment
   remembers its settings (see [Persistent scaling](#persistent-scaling)): one shared identity, one
   **per client**, or one **per client + resolution**.
-- **Layout / max displays** — when several clients each become a monitor of one desktop, this places
-  them side by side (**auto**) or exactly where you arrange them in the console (**manual**, keyed to
-  each client), up to **max displays**. Arrange them on the **Virtual displays** page once two or more
-  are streaming.
+- **Layout / max displays** — several clients as monitors of one desktop: side by side (**auto**) or
+  exactly where you arrange them in the console (**manual**, keyed to each client), up to **max
+  displays**. Arrange them on the **Virtual displays** page once two or more are streaming.
 
 ### Dedicated game sessions
 
-**Dedicated game sessions** control how a session that *launches a game from
-[your library](/docs/game-library)* is served (Linux hosts):
+How a session that *launches a game from [your library](/docs/game-library)* is served (Linux
+hosts):
 
-- **Auto** (default) — the launch rides whatever session the box is in: the managed Steam session on a
-  Steam Deck / Bazzite couch box, a bare gamescope on a plain distro, or spawned into your live KDE /
-  GNOME / Sway desktop.
-- **Dedicated** — every library launch gets its **own headless gamescope at your exact resolution and
-  refresh**, with just the game inside — no Steam Big Picture to navigate, no game-mode desktop.
-  Steam titles launch with the client hidden (`steam -silent`); non-Steam titles start almost
-  instantly (gamescope up in ~1 s, then the game's own boot). Combined with **keep alive**, the game
-  keeps running when you disconnect and you re-attach straight back into it.
+- **Auto** (default) — the launch rides whatever session the box is in: the managed Steam session
+  on a Steam Deck / Bazzite couch box, a bare gamescope on a plain distro, or your live KDE / GNOME
+  / Sway desktop.
+- **Dedicated** — every library launch gets its **own headless gamescope at your exact resolution
+  and refresh**, with just the game inside. Steam titles launch with the client hidden
+  (`steam -silent`); non-Steam titles start almost instantly (gamescope up in ~1 s). Combined with
+  **keep alive**, the game keeps running when you disconnect.
 
-Dedicated needs `gamescope` installed on the host; without it a launch falls back to **Auto**
-routing. This axis is independent of the preset — pick it on the **Virtual displays** page. On a box
-already in Steam game mode, a dedicated Steam launch frees game mode's Steam first and restores it
-when the session ends. (GameStream / Moonlight launches follow the same routing.)
+Dedicated needs `gamescope` installed; without it a launch falls back to **Auto**. This axis is
+independent of the preset. On a box already in Steam game mode, a dedicated Steam launch frees game
+mode's Steam first and restores it when the session ends. (GameStream / Moonlight launches follow
+the same routing.)
 
 ## When a game ends, and when a session does
 
@@ -263,48 +229,44 @@ only to a game **this host launched for the session**: a game you started yourse
 
 ### When the game exits
 
-**End the session** (default). Quit the game and your client goes back to its own library. A
-dedicated game session has always done this; it now works on every path — your live KDE/GNOME/Sway
-desktop, an attached gamescope, and Moonlight.
-
-**Keep streaming** if you stream the desktop and treat the game as incidental.
+**End the session** (default) — quit the game and your client goes back to its own library, on
+every path (live desktop, attached gamescope, Moonlight). **Keep streaming** if you stream the
+desktop and treat the game as incidental.
 
 ### When the session ends
 
 Whether stopping — or losing — a session also closes the game.
 
-- **Leave it running** (default). Nothing is ever closed. Disconnect, and the game plays on for when
-  you come back.
-- **Close it on Stop** — closing the client, or pressing *Stop* in the console, closes the game.
-  A network drop does not: you get your game back when you reconnect.
-- **Always close it** — a drop closes it too, but only after a **reconnect window** (5 minutes by
-  default). Reconnect inside the window and nothing happens; the console shows the countdown, with
-  an **End now** button if you'd rather not wait.
+- **Leave it running** (default). Nothing is ever closed.
+- **Close it on Stop** — closing the client, or *Stop* in the console, closes the game. A network
+  drop does not.
+- **Always close it** — a drop closes it too, after a **reconnect window** (5 minutes by default).
+  Reconnect inside the window and nothing happens; the console shows the countdown, with an **End
+  now** button.
 
-Closing a game costs whatever it hadn't saved, which is why nothing closes by default. The host asks
-first — a polite close, the same as clicking the window's X, so the game runs its own shutdown — and
-only forces the issue after ten seconds of being ignored.
+Closing a game costs whatever it hadn't saved, which is why nothing closes by default. The host
+asks first — a polite close, the same as clicking the window's X — and only forces the issue after
+ten seconds of being ignored.
 
 > **Keep alive and this setting are different clocks.** Keep-alive decides how long the *display*
-> outlives a disconnect (10 s by default); the reconnect window decides how long the *game* does
-> (5 minutes). A display set to **Forever** stays up regardless of what happens to the game — a
-> pinned display is a deliberate "this box is a game host" choice, and closing a game doesn't undo it.
+> outlives a disconnect (10 s default); the reconnect window decides how long the *game* does
+> (5 min). A display set to **Forever** stays up regardless of what happens to the game.
 
 ### On a gamescope session, the display has the final say
 
-When a launch gets its **own gamescope** — a dedicated game session, the usual setup on a Steam Deck
-or a Bazzite couch box — the game runs *inside* the streamed display, so it lives exactly as long as
-that display does, and **Keep alive decides that, not the setting above**:
+When a launch gets its **own gamescope** — a dedicated game session, the usual setup on a Steam
+Deck or Bazzite couch box — the game runs *inside* the streamed display and lives exactly as long
+as it does, so **Keep alive decides, not the setting above**:
 
 | you disconnect by | what happens to the game |
 |---|---|
-| pressing **Stop** (or the console's stop) | the display tears down at once — keep-alive is deliberately skipped for a real stop — and the game goes with it, even on *Leave it running* |
+| pressing **Stop** (or the console's stop) | the display tears down at once — keep-alive is skipped for a real stop — and the game goes with it, even on *Leave it running* |
 | dropping out (network, sleep) | the display lingers for your keep-alive window, then tears down; the game ends with it |
 | dropping out, keep-alive **Forever** | the display is pinned, so the game genuinely survives — and *Always close it* still ends it when the reconnect window closes |
 
-So on a gamescope box, "leave the game running after I disconnect" means **keep-alive Forever** (or a
-window long enough to come back in), not just this setting. On a desktop session — KWin, GNOME, Sway —
-the game is an ordinary process next to your desktop and the setting above is the whole story.
+On a gamescope box, "leave the game running after I disconnect" means **keep-alive Forever** (or a
+window long enough to come back in). On a desktop session — KWin, GNOME, Sway — the game is an
+ordinary process and the setting above is the whole story.
 
 ### Automation
 
@@ -320,8 +282,8 @@ display identity*, so your desktop environment keys its per-monitor settings to
 | Host | Supported | How |
 |---|---|---|
 | **Windows** | ✅ today | Set scaling in Settings while streaming — Windows remembers it per client. |
-| **KDE / KWin** | ✅ today | Set scaling in System Settings while streaming; KWin keys it to a stable per-client output name and reapplies it on reconnect. Validated live (150 %/125 % survive a full disconnect + reconnect). |
-| **GNOME / Mutter** | ✅ today | GNOME's virtual-monitor API exposes no stable identity to key config on, so the **host persists the scale itself**: set scaling in Settings while streaming — the host captures the change, remembers it per client, and reapplies it on reconnect. |
+| **KDE / KWin** | ✅ today | Set scaling in System Settings while streaming; KWin keys it to a stable per-client output name and reapplies it on reconnect. |
+| **GNOME / Mutter** | ✅ today | GNOME's virtual-monitor API exposes no stable identity, so the **host persists the scale itself**: set scaling in Settings while streaming — the host captures it per client and reapplies on reconnect. |
 | **Sway / wlroots** | ❌ | Headless outputs can't carry a stable identity; pin scale in your sway config instead. |
 
 ## Legacy environment knobs
@@ -335,51 +297,48 @@ them — when a settings file exists, it wins.
 | `PUNKTFUNK_NO_ISOLATE` | **Topology** → Extend *(Windows)* |
 | `PUNKTFUNK_KWIN_VIRTUAL_PRIMARY` / `PUNKTFUNK_MUTTER_VIRTUAL_PRIMARY` | **Topology** → Exclusive (when set) / Extend (when `0`) |
 
-One knob has no console equivalent — it's transport tuning, not display policy:
+One knob has no console equivalent — transport tuning, not display policy:
 
-- **`PUNKTFUNK_IDLE_TIMEOUT_MS`** (host, default `8000`) — how long the host waits before declaring a
-  *dropped* client gone, which is when a kept display starts its linger (or is freed). Lower it (e.g.
-  `3000`) to reclaim kept displays sooner after an ungraceful drop; it's clamped to ≥1 s and its
-  keep-alive ping scales with it, so a live session never false-disconnects. A deliberate quit is
-  instant regardless. Also `--idle-timeout-ms` on `punktfunk1-host`.
+- **`PUNKTFUNK_IDLE_TIMEOUT_MS`** (host, default `8000`) — how long before a *dropped* client is
+  declared gone, which is when a kept display starts its linger (or is freed). Lower it (e.g.
+  `3000`) to reclaim kept displays sooner; it's clamped to ≥1 s and its keep-alive ping scales with
+  it, so a live session never false-disconnects. A deliberate quit is instant regardless. Also
+  `--idle-timeout-ms` on `punktfunk1-host`.
 
 ## Troubleshooting
 
 **My physical monitors stayed off after I disconnected.** Keep-alive is set together with Exclusive
-topology — the display (and your isolated desktop) is kept for the linger window. Release it from
-the console (**Virtual displays**), or switch to the **Shared desktop** preset so streaming never
-disables your real monitors.
+topology — the display is kept for the linger window. Release it from the console (**Virtual
+displays**), or switch to the **Shared desktop** preset.
 
 **The virtual output shows only my wallpaper.** Your topology is Extend, so the streamed display is
 an empty extension. Use **Primary** or **Exclusive** so your desktop lands on it.
 
 **KWin can't create the virtual output.** On a normal Plasma session KWin runs its **DRM backend**,
-which creates virtual outputs at any version. The 6.5.6 floor applies only to the **virtual backend**
-(`kwin_wayland --virtual`, used for headless and test sessions) — below that the request fails with
-"Could not find output". On **KWin 6.6+** that same message also covers an output KWin *did* create
-and then left disabled; [KDE Plasma](/docs/kde#troubleshooting) walks that one. See
+which creates virtual outputs at any version. The 6.5.6 floor applies only to the **virtual
+backend** (`kwin_wayland --virtual`, headless and test sessions) — below that the request fails
+with "Could not find output". On **KWin 6.6+** that same message also covers an output KWin *did*
+create and then left disabled; [KDE Plasma](/docs/kde#troubleshooting) walks that one. See
 [requirements](/docs/requirements).
 
-**Reconnecting into game mode reconnects cleanly now.** On a Steam Deck / Bazzite box, disconnecting
-and reconnecting within game mode reuses the still-warm session (or cleanly recreates it) instead of
-landing on a dead stream — and switching between game mode and the KDE / GNOME desktop mid-stream
-follows the switch. If a launched game **exits**, a dedicated session ends and returns you to your
-library; a game mode / desktop session keeps streaming.
+**Reconnecting into game mode reconnects cleanly now.** On a Steam Deck / Bazzite box,
+disconnect/reconnect within game mode reuses the still-warm session (or cleanly recreates it), and
+switching between game mode and the desktop mid-stream follows the switch. If a launched game
+**exits**, a dedicated session ends and returns you to your library; a game mode / desktop session
+keeps streaming.
 
 **My keep-alive / topology / layout settings do nothing.** Check whether **Streamed screen** is set
-to a real monitor — those options are about a display Punktfunk created, and when it's mirroring one
-of yours there is nothing to keep alive or rearrange. Switch the card back to *Virtual screen
-(default)*.
+to a real monitor — those options are about a display Punktfunk created. Switch the card back to
+*Virtual screen (default)*.
 
 **The console won't let me change Streamed screen.** `PUNKTFUNK_CAPTURE_MONITOR` is set in this
-host's [`host.env`](/docs/configuration) and outranks the console. Unset it (and restart the host)
-to choose from the console instead.
+host's [`host.env`](/docs/configuration) and outranks the console. Unset it (and restart the host).
 
 **My session fails with "no monitor named …".** The pinned connector isn't among this host's
-monitors — renamed, unplugged, or the host is now in a different session. Run
-`punktfunk-host list-monitors` on the host to see the real names. Punktfunk will not quietly stream
-a different screen.
+monitors — renamed, unplugged, or the host is in a different session. Run
+`punktfunk-host list-monitors` to see the real names. Punktfunk will not quietly stream a different
+screen.
 
-**My couch box's TV stayed on the streamed session after I disconnected.** With the **Headless box**
-preset (keep alive = *forever*), a managed Steam session is held indefinitely so a reconnect resumes
-instantly — return to game mode on the box (or restart the host) to hand the TV back.
+**My couch box's TV stayed on the streamed session after I disconnected.** With the **Headless
+box** preset (keep alive = *forever*), a managed Steam session is held indefinitely — return to
+game mode on the box (or restart the host) to hand the TV back.

docs-site/content/docs/wake-on-lan.md

@@ -14,15 +14,12 @@ are here for.
 
 ## How it works
 
-While running, the host advertises itself over mDNS, including `mac` — the address of the card
-carrying the IP clients reach it on first, then any other non-loopback cards as fallbacks, at most
-four.
-
-Each app stores those addresses on its **saved host** record. Linux, Windows and Android refresh
-them whenever they see the host advertise; the Apple app when you save the host and on every
-connect. A sleeping host stops advertising, but the client still has the addresses on disk.
-
-That ordering is the whole prerequisite:
+While running, the host advertises itself over mDNS, including `mac` — the card carrying the IP
+clients reach it on first, then any other non-loopback cards as fallbacks, at most four. Each app
+stores those addresses on its **saved host** record: Linux, Windows and Android refresh them
+whenever they see the host advertise, the Apple app when you save the host and on every connect. A
+sleeping host stops advertising, but the client still has the addresses on disk. That ordering is
+the whole prerequisite:
 
 > **The client must have seen the host awake at least once**, on a network where the host's mDNS
 > advert reached it. Until then no address is known and there is nothing to wake with — the client
@@ -31,10 +28,9 @@ That ordering is the whole prerequisite:
 
 The packet goes **out of every one of the client's network interfaces** — from a socket bound to
 that interface's own address, aimed at both its subnet broadcast address and `255.255.255.255` — on
-UDP ports 9 and 7, repeated three times, plus a unicast to the host's last known address. The spread
-is deliberate: a sleeping machine has no ARP entry, so a plain unicast cannot find it, and a
-broadcast sent without binding an interface leaves by the default route only — on a machine running
-a VPN or a mesh network, not the LAN the host sleeps on.
+UDP ports 9 and 7, repeated three times, plus a unicast to the host's last known address. (A
+sleeping machine has no ARP entry, and an unbound broadcast leaves by the default route only — on a
+VPN or mesh machine, not the LAN the host sleeps on.)
 
 Neither the advert nor a magic packet is authenticated. A wrong address only makes the wake fail;
 the host's certificate fingerprint still gates the connection. See [Security](/docs/security).
@@ -59,11 +55,9 @@ Two things can still stop it, neither visible from Punktfunk:
 ## Waking from a client
 
 **Auto-wake on connect** is a client setting, **on by default**, in Settings under **Session**
-([Client settings](/docs/client-settings#behavior) covers what sits beside it); the TV and
-controller layouts list it among the other general settings. It is a property of the device and
-the network, so it is *not* part of a
-[settings profile](/docs/profiles-and-links#what-a-profile-cant-change) — "Game" and "Work" cannot
-disagree about it.
+([Client settings](/docs/client-settings#behavior)); the TV and controller layouts list it among
+the general settings. A property of the device and the network, so *not* part of a
+[settings profile](/docs/profiles-and-links#what-a-profile-cant-change).
 
 With auto-wake on, opening a saved host that is not advertising:
 
@@ -108,12 +102,9 @@ shows an explanation with a link to system settings if you decline.
 ### On the Steam Deck
 
 The [Decky plugin](/docs/steam-deck) has no wake button or wake setting of its own. It starts every
-stream through the client, so the wake is the client's, on exactly the terms above — packet, 6-second
-re-send, once-a-second watch, dial only when the host is really back. It follows **Wake hosts
-automatically** in the client's own settings (**Open Punktfunk → Settings** from the same panel)
-and is a no-op until the client has learned that host's MAC address. (The plugin used to fire a
-packet itself and stretch the connect budget to 75 seconds to cover the resume; a wait that watches
-for the host beats a fixed budget, so that is gone.)
+stream through the client, so the wake is the client's, on exactly the terms above. It follows
+**Wake hosts automatically** in the client's own settings (**Open Punktfunk → Settings** from the
+same panel) and is a no-op until the client has learned that host's MAC address.
 
 ### From the command line
 
@@ -173,10 +164,9 @@ Wake-on-WLAN is NOT armed on this host's Wi-Fi NIC — clients cannot wake it fr
 ```
 
 The warning line names the interface and the exact command to fix it. The host only reports; it
-never changes the card's settings. It stays silent when it cannot tell — `iw` or `ethtool` missing,
-a driver that doesn't answer, or not enough privilege — rather than guessing, and says nothing at
-all when mDNS adverts are off (`PUNKTFUNK_MDNS=0` or `--no-mdns`), because then no address is
-published either.
+never changes the card's settings, stays silent when it cannot tell (`iw`/`ethtool` missing, a
+driver that doesn't answer, not enough privilege), and says nothing when mDNS adverts are off
+(`PUNKTFUNK_MDNS=0` or `--no-mdns`) — then no address is published either.
 
 Read the line on the web console's **Logs** page, or with
 `journalctl --user -u punktfunk-host`. See [Troubleshooting](/docs/troubleshooting#still-stuck).

docs-site/content/docs/web-console.md

@@ -112,9 +112,10 @@ appears under **Waiting for approval** instead; approving it pairs it immediatel
 
 Nine destinations in the sidebar (a **More** tab on a phone holds the last five):
 
-- **Dashboard** — live status: whether video and audio are streaming, the active sessions with
-  their codec, resolution, frame rate and bitrate, which games are running, and how many clients
-  are paired. Buttons stop a session or ask the encoder for a fresh keyframe.
+![Live status during a stream: video and audio streaming, the running game, the session's codec, resolution, frame rate and bitrate](/img/console-live-status.png)
+
+- **Dashboard** — the live status above: what's streaming, which games run, how many clients are
+  paired. Buttons stop a session or ask the encoder for a fresh keyframe.
 - **Host** — this host's identity (hostname, OS, local IP, version, unique id), the codecs it
   advertises, its ports, the **Updates** card (see [Updating the Host](/docs/updating)), the
   **GPUs** card — Automatic, or prefer one GPU for capture and encode, applied to the next session

docs-site/public/openapi.json

@@ -1860,6 +1860,69 @@
         }
       }
     },
+    "/api/v1/library/provider/{provider}/running": {
+      "put": {
+        "tags": [
+          "library"
+        ],
+        "summary": "Report which of a provider's titles are running",
+        "description": "The **live** counterpart to the `detect` hints in a reconcile payload: that one says *how to\nrecognize* a title's process, this one says *it is running now* (design §9,\n[`crate::runstate`]). For a provider that starts games itself and knows when they stop —\nPlaynite tracks every launch and fires an event on both edges — this is a fact the host would\notherwise have to re-derive by scanning, and for a title with nothing to scan for (an emulated\ngame, a manually added one) could not derive at all.\n\nDeclarative and idempotent, like the reconcile: the body is the provider's **complete** running\nset, so a missed event, a plugin restart or an install mid-game all self-correct on the next\nreport rather than drifting.\n\nThe report **expires** after `ttl_s` (90s) unless restated, which is what makes it safe for a\nlive provider to keep a streaming session open for a game the host cannot see: a plugin that\ndies with a game running stops counting shortly after, and the host falls back to process\nscanning exactly as it does without one. Re-report on every change **and** on a timer well\ninside the window.\n\nTitles the provider does not currently publish are ignored (counted in `unknown`), not an error:\na report may legitimately race its own reconcile.",
+        "operationId": "reportProviderRunning",
+        "parameters": [
+          {
+            "name": "provider",
+            "in": "path",
+            "description": "The provider id ([a-z0-9._-], `manual` reserved)",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ProviderRunningInput"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "The report was accepted",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProviderRunningAccepted"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid provider id or payload",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/v1/library/scanners": {
       "get": {
         "tags": [
@@ -7792,6 +7855,46 @@
           }
         }
       },
+      "ProviderRunningAccepted": {
+        "type": "object",
+        "description": "The result of a liveness report.",
+        "required": [
+          "matched",
+          "unknown",
+          "ttl_s"
+        ],
+        "properties": {
+          "matched": {
+            "type": "integer",
+            "description": "How many reported titles matched an entry this provider currently publishes.",
+            "minimum": 0
+          },
+          "ttl_s": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Seconds this report stays authoritative without being restated — re-report inside it while\nanything is running.",
+            "minimum": 0
+          },
+          "unknown": {
+            "type": "integer",
+            "description": "How many were ignored because no such entry exists (a report that raced a reconcile).",
+            "minimum": 0
+          }
+        }
+      },
+      "ProviderRunningInput": {
+        "type": "object",
+        "description": "Request body for `reportProviderRunning`.",
+        "properties": {
+          "running": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RunningTitle"
+            },
+            "description": "Every title of this provider's that is running **right now**. The full set, not a delta:\nanything absent from it is reported as stopped."
+          }
+        }
+      },
       "ReleaseDisplayRequest": {
         "type": "object",
         "description": "Request body for `releaseDisplay`.",
@@ -7846,6 +7949,28 @@
           }
         }
       },
+      "RunningTitle": {
+        "type": "object",
+        "description": "One running title in a provider's liveness report.",
+        "required": [
+          "external_id"
+        ],
+        "properties": {
+          "external_id": {
+            "type": "string",
+            "description": "The provider's own stable id for the title — the same key its reconcile payload uses."
+          },
+          "pid": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int32",
+            "description": "The process id the provider started for it, when it knows one. Optional, and never trusted\nas a bare number: the host re-resolves it and pins it to its start time before it is ever\nsignalled, so a stale or recycled pid simply contributes nothing.",
+            "minimum": 0
+          }
+        }
+      },
       "RuntimeRequest": {
         "type": "object",
         "required": [

docs/releases/README.md

@@ -19,7 +19,8 @@ release is born complete and the announcement always has something to say.
    catches renamed knobs and dead links, not a stale sentence). If an install command, repo URL or
    port changed, `data/platforms.json` changed with it — then run `bun run sync-platforms` in
    punktfunk-website and commit, because its download page vendors that file and only refreshes
-   when someone does.
+   when someone does. Same pass for the website itself: does the landing page still describe what
+   this release ships (features, platforms, the blog post the CMS expects per release)?
 2. **Tag & push.** `git tag -a vX.Y.Z … && git push origin vX.Y.Z` fans out to the build
    workflows. Whichever one wins the create race seeds the release body from this file
    (`scripts/ci/gitea-release.sh` → `ensure_release`, and its PowerShell twin). The release page

docs/releases/v0.31.0.md

@@ -2,25 +2,38 @@ Wire-compatible with 0.30.x — everything you have already paired keeps working
 
 Most of this release is things that were wrong in ways nothing announced. A DualSense's rumble and speaker never actually worked in a game streamed from a Linux host, for five separate reasons stacked on top of each other, and every one of them is fixed. On Windows, ending a session was silently killing the whole host, and launching a game from the library on 0.30 could drop your stream a second later. Android phones and TVs now show the same controller console the desktop does — one interface on three platforms — and the picture on a phone arrives markedly earlier with no dropped frames. On Linux hosts, another device on the box can no longer make your desktop audio stutter, and a Gaming Mode takeover on some machines was starving your controller with a login storm of our own making.
 
+Two things also change how you get Punktfunk in the first place. The Windows client is now an ordinary installer rather than a Store-style package, which is what finally lets Steam launch it — overlay, controller configs, Big Picture. And a Linux host can be set up with a single command, if you would rather not follow a page of them.
+
 ## TL;DR
 
+- **Windows: the client is a normal installer now, and Steam can launch it.** Add it as a non-Steam game and the Steam overlay, your controller configuration and Big Picture all work — which the Store-style package could never do. Read *Before you update* if you already have it installed.
+- **One command sets up a Linux host.** `curl -fsSL https://punktfunk.unom.io/install.sh | sh` takes a machine from nothing to a host you can pair with, including living alongside an existing Sunshine or Apollo. It is a preview; the per-system pages remain the documented way.
 - **DualSense rumble and speaker work in-game from a Linux host.** The controller was dying 400 ms after it appeared, every message the game sent it was reported as failed, its sound card was invisible to the sound system, and what got through arrived 48 dB too quiet. All fixed; the details are below.
 - **Windows: ending a session no longer kills the host, and launching a game no longer drops your stream.** The first looked like a mystery reconnect; the second arrived with 0.30.
 - **Android has the desktop's console, and a much faster picture.** One controller interface across Windows, Linux and Android — including 32-bit TV boxes — and on the reference phone end-to-end latency went from 30 ms to about 18 ms with dropped frames going from 40–50 a second to none.
 - **Desktop audio on a Linux host no longer stutters because of somebody else's device.** In one 15-minute session, 15 % of what the listener heard was silence the host had papered over gaps with — because a controller's sound card, attached over the network and connected to nothing, was setting the pace for the whole box.
-- **A Gaming Mode takeover on a machine that logs itself in was choking its own controller input** — the pad enumerated fine and then reported at about 1.4 times a second instead of 250. The cause was ours, and it is gone.
+- **KDE Plasma 6.6 could refuse to start a session, in your own language, forever.** No number of retries helped and there was nothing to fix in System Settings. The host repairs it now.
+- **Every client can send its logs to the host.** Mac, iPhone, iPad, Apple TV and Android join the Gaming Mode console — and the Apple app finally keeps a log worth sending.
 - **Hyprland and Sway users: the default display mode now really turns your desk monitors off during a session.** It said it did before and did nothing. Read *Before you update*.
 
 ## Before you update
 
+- **Windows client: the download you want has changed, and switching to it costs one re-pair.** The default is now `punktfunk-client-setup_x64.exe` — an ordinary per-user installer, no administrator prompt, which upgrades in place and keeps your saved hosts and pairing. A portable zip and the old Store-style package are still offered as alternates. **If you already have the Store-style package and you want the Steam integration, remove it first** — `Get-AppxPackage unom.Punktfunk | Remove-AppxPackage` — and then run the installer: that package keeps its settings, saved hosts and pairing identity inside itself, so you will pair with your hosts once more. If you had added Punktfunk to Steam, add the new one; it lives at `%LOCALAPPDATA%\Programs\Punktfunk\punktfunk-client.exe`. Nothing on the host side is affected, and if you do not care about Steam, staying on what you have is fine.
+- **Steam Deck and Bazzite hosts: two things we told you are no longer true.** Taking over Gaming Mode no longer stops your login manager, so Steam's own "Switch to Desktop" works during and after a session instead of hanging until you reboot — and for that reason the takeover no longer needs the `punktfunk` group. Keep that group only if you use the virtual Steam Deck controller, which still needs it. The comments in the Bazzite `host.env` we ship changed to match.
+- **NixOS hosts: two things, and the first one is that builds were failing outright.** The version of our patched compositor that came with the pinned packages had drifted far enough that it no longer accepted our changes, and since HDR is on by default that failure sat on every `services.punktfunk.host.enable = true` build; the fix moves your `nixpkgs` input, so expect a rebuild. Second, there is now a binary cache, so that rebuild — and every future one — need not compile the workspace and the compositor from source, which took about an hour. Add the cache and its public key to your configuration; the install guide has the snippet, and the cache serves its own public key. Both of these come undone if your flake overrides Punktfunk's `nixpkgs` input: every store path changes, so nothing in the cache matches and everything rebuilds. Separately, one of the controller-audio fixes below is a sound-configuration file the other Linux packages install into a system location NixOS does not have; it needs a package override there.
+- **Plugin authors: update your dependency.** `@punktfunk/host` 0.1.5 and `@punktfunk/plugin-kit` 0.4.3 are published, and plugins take them from the registry — so the fix that makes a plugin follow a moved management port, the cap on re-scanning, and the republish-on-restart behaviour below only reach your plugin once it depends on those versions.
 - **Hyprland and Sway hosts:** the "exclusive" display setting — which is what the default resolves to on these desktops — now genuinely disables your own monitors for the length of a session and brings them back afterwards, exactly as it always has on KDE. Until now it was accepted, reported back as active, and quietly behaved as "extend", so your monitors stayed on. If you would rather keep them on, set the display topology to *extend*. Two things to know: on Hyprland, bringing the monitors back reloads your Hyprland configuration, which also drops any other runtime tweaks you have applied since login and re-runs its startup commands; and the Sway half is written to the same contract but has not been exercised on a live Sway machine, so if it misbehaves, please say so.
-- **NixOS hosts:** there is now a binary cache, so a host no longer takes an hour to build. Add the cache and its public key to your configuration — the install guide has the snippet, and the cache serves its own public key. If your flake overrides Punktfunk's `nixpkgs` input, the cache cannot help you: every package changes and rebuilds. Separately, one of the controller-audio fixes below is a sound-configuration file the other Linux packages install into a system location NixOS does not have; it needs a package override there.
 - **Other Linux hosts:** several controller-audio fixes arrive as system files inside the host package rather than as code — a device rule, a sound-system policy and a sound-card configuration. They take effect after the package is installed and the controller is reattached (or the machine rebooted).
 - **Linux hosts, if you look in your sound settings mid-session:** you will now see a virtual output *and* a recording stream both named after Punktfunk. That is the host's own audio output, and it is not a leak — the troubleshooting guide has a new section on it and on what to do when it tells you another device is clocking your audio.
 - **If you moved the host's management port and hand-edited the tray's start-up command to match, you can undo that.** The tray, every plugin and the plugin runner now follow the port the host actually bound, so nothing needs telling.
 
 ## New
 
+- **The Windows client installs like an ordinary program, and Steam can launch it.** The download is now a signed per-user installer — no administrator prompt — that puts Punktfunk in your own account and registers what you would expect: the Start-menu entries for Punktfunk and Punktfunk Console, `punktfunk://` links, and the `punktfunk` command on your path. It fetches the Windows runtime it needs if the machine does not have it. **The reason this matters beyond tidiness:** someone reported that launching through Big Picture did nothing and the Steam overlay never appeared. That was never about the app — it was the shape of the old Store-style package, whose program file lives in a protected folder Steam's "add a non-Steam game" browser cannot open, and which Windows starts in a way that stops the overlay attaching. Steam has to start the program itself, from an ordinary path. Now it can: add it as a non-Steam game and the overlay, your per-game controller configuration and Big Picture launching all work. There is also a portable zip that registers nothing at all — unzip it anywhere, delete the folder to remove it — and the Store-style package remains for the Microsoft Store.
+- **One command sets up a Linux host, as a preview.** `curl -fsSL https://punktfunk.unom.io/install.sh | sh` works out which system you are on, installs exactly the packages the documentation would have told you to, and then handles the parts people get stuck on: it notices an existing Sunshine, Apollo or Vibeshine and offers to keep both by moving Punktfunk's management port, puts you in the right group, writes a firewall rule, starts the host and web console, checks they are actually running, and prints your console address, the command for its password and the pairing steps. Everything optional defaults to no. `--dry-run` shows every command without running any, `--uninstall` reverses it, and answers can be given up front so it can run unattended. It also catches the two graphics-driver failures that otherwise produce a host that streams badly with no explanation — no driver at all, and a driver the machine refused to load because of Secure Boot. It is labelled **preview** deliberately: the per-system pages stay the documented route until it has more mileage, and NixOS, SteamOS and Windows are pointed at their own instructions rather than half-handled.
+- **Every client can send its logs to the host.** In 0.30 this existed only on the Gaming Mode console. Mac, iPhone, iPad and Apple TV get it in the host card's menu and on the controller-driven host options, and Android phones and TVs get it from the console — where the button previously said it was unavailable. On Apple it is new twice over: the app had never kept a log of its own to send, so a report from an Apple TV arrived carrying only the host's half of the story. It now keeps a rolling log — bounded, so it cannot grow without limit — and for the first time that log includes what the streaming engine itself has to say about connections and network problems, which was previously invisible on those devices.
+- **The console learns three things from the desktop.** Controller haptics and Controller speaker are now switches in the console's Controller tab rather than settings you could only reach elsewhere; each saved machine gets its own Shared clipboard toggle; and you can set a machine's default profile from its menu.
+- **The documentation was rewritten, for two audiences.** There is a get-started track — one task per page, a couple of minutes each, with real screenshots of the console instead of prose describing it — and a Switching from Sunshine page covering what maps to what and how to run both at once. Every install command on those pages is now quoted from one file that the build checks, so the commands you are given cannot drift from the ones that are tested. Several things the pages had told you were simply wrong and are now corrected — among them that GameStream compatibility is opt-in on every route, a missing step in the Ubuntu and Debian instructions, a missing firewall step on Bazzite, and NixOS getting a page of its own.
 - **NixOS users get prebuilt binaries.** Every other install channel shipped binaries; Nix compiled the whole workspace and our patched compositor from source — roughly an hour, on the critical path of enabling the host at all. A signed binary cache is now published on every change to the main branch, so a build that once took an hour takes the time it takes to download.
 - **Hyprland and Sway hosts can run a session on the virtual display alone.** With the display topology on *exclusive*, your own monitors are switched off while the session runs and switched back on when its display goes away — never all at once, so the desktop is never left with nothing to show, and never a monitor belonging to a second session or a second host on the same machine. *Primary* is still treated as *extend* on these desktops, and now says so on its own rather than sharing a warning with *exclusive*: Wayland has no notion of a primary output, only a focused one, and the streamed display already holds that.
 - **The Android app's controller interface is the desktop's.** Plug in or pair a controller and the phone or TV shows the same console Windows and Linux do — same screens, same navigation, same motion — instead of an Android-only recreation of it that had to be fixed three times over. It runs on every Android device, including the 32-bit TV boxes that were previously left out. On a phone the console now takes the whole panel, tucking the system bars away for the duration and bringing them back on a swipe, and the library gives the sort bar's height back to the covers unless you have actually pulled it down. Connected controllers is a page of the console itself now, with the permission prompts, the rumble test and the controller-audio self-test where they were before.
@@ -32,6 +45,10 @@ Most of this release is things that were wrong in ways nothing announced. A Dual
 
 ## Improved
 
+- **Touching the console does what touching things should.** On a touchscreen, swiping across the settings list used to change whichever setting your finger happened to land on — a press was both "focus this" and "choose this". A tap is now a tap, delivered where you put your finger down, and a drag scrolls the list. Using a mouse is unchanged.
+- **The Android console is easier on the battery.** It only looks for machines on the network while the console is actually in front of you, and it halves its drawing rate after a minute without input.
+- **A portable Playnite gets its covers — and a tile of its own.** If your Playnite is unzipped somewhere of your choosing rather than installed, its whole library lives beside the program, which put every cover outside the folders the host is allowed to read art from: one reported library synced its games and dropped all 70 covers, with no way round it but setting an environment variable. Those folders are now included, exactly as Steam's are, and finding a portable Playnite at all also gives it the launcher tile it never had. If you set that environment variable as a workaround, you can drop it.
+- **Fixing something on the host side no longer needs a cache file deleted.** A plugin remembers what it last sent so it does not resend it endlessly — but the host can accept a submission and keep less of it than was sent, which is deliberate, since a cover it cannot serve must not cost you the whole library. Once that happened, the plugin's memory said "nothing to do" forever: you would fix the host and nothing would republish. Restarting, or pressing Sync now, always republishes again.
 - **Windows: the plugin runner writes a log file you can read.** A field report on a 0.30 host had plugins installed, the runner running, an empty library and "no logs at all" — and that was by design, since the runner's only way to speak was through the host it could not reach. It now writes a plain log file next to its plugin state, and the console's empty-library hint tells you where it is.
 - **Apple gamepad screens move like the desktop's.** Screen transitions in the Mac, iPhone, iPad and Apple TV controller shell use the same spring the desktop console uses, and they can be interrupted — press B mid-flight and the same spring carries you back. Reduce Motion crossfades instead of snapping.
 - **The Apple library fits a phone.** The grid fills the width instead of leaving a fifth of it empty on a phone; in a landscape phone's height it holds two rows instead of one; the shoulder-button hint hides on any phone and the sort bar has become a tray you pull down with ▲ and dismiss with ▼, A or B, so the field keeps every point of height it has. Navigating the grid no longer scrolls twice for one move, and a diagonal flick of the stick is one move, not two.
@@ -43,6 +60,12 @@ Most of this release is things that were wrong in ways nothing announced. A Dual
 
 ## Fixed
 
+- **On KDE Plasma 6.6, a session could refuse to start — in your own language — and stay broken.** Plasma 6.6 changed the rules: it will not stream a display it created switched off, and the refusal it sends is a translated sentence with nothing written to any log, because switching a display off is a perfectly ordinary thing to have configured. It also repeated forever, because we deliberately ask for a display named consistently so Plasma remembers your resolution and scale against it — which meant it also remembered "off" and reapplied it to every future session. You could not even fix it in System Settings, since the display exists only for the fraction of a second the request is alive. The host now switches it on and tries again. Separately, that translated refusal used to be mistaken for a temporary problem on any non-English desktop and burned through eight retries over eleven seconds before giving up; it now fails immediately and says what it means.
+- **Gaming Mode: "Switch to Desktop" hung until you rebooted.** Taking over Gaming Mode used to work by stopping the piece of the system that logs you in, which also happens to be the only thing on the machine able to start a desktop session — so Steam's own switch sat on its dialog forever. The takeover now leaves it running and simply parks the automatic gaming login for the duration. Measured on the machine that reported it: the switch that used to hang brings the desktop up in about ten seconds, and Steam is back within five when the session ends.
+- **Wake-on-LAN never worked from a Steam Deck.** Waking a sleeping machine needs its network address, and the only two places that ever recorded one were the Windows and Linux desktop windows — neither of which exists in Gaming Mode. So a Deck's saved machines never had one, every wake was skipped in silence, and nothing said so: no packet, no error. All the places that see a machine announce itself now remember it. Two things fall out of the same fix: a Deck's saved machine keeps its icon instead of losing it the moment the network goes quiet, and the advice in `punktfunk wake` — "connect to it once while it's awake" — is corrected, because connecting never taught it anything.
+- **The web console's Virtual displays page showed the same two cards on both tabs.** The Streamed-screen and session-lifetime cards sat below the tab strip rather than inside it, so whichever tab you were on you saw them — which read as the Configuration tab's contents leaking into the Live displays tab. They are settings, so they now live in Configuration, and the Live tab is just the live list and its arrangement.
+- **Cancelling a connection left you looking at "Cancelling…".** The console waited for the machine you were dialling to confirm, which it had no obligation to do — on Android it never did, so the screen stayed until the app was killed, and on the desktop it waited out the dial: fifteen seconds normally, and just over three minutes when the host was holding your request for someone to approve. Pressing B is your decision and now takes effect at once, and the dial is actually abandoned.
+- **NixOS hosts could not be built at all.** Our patched compositor no longer applied to the version of it that came with the pinned packages, and because HDR is on by default that failure was on the path of every host build. Two more faults were hiding behind it and are fixed in the same breath: the packages we build from turn off the piece that lets a game reach HDR unless explicitly asked, so the compositor would have installed under our name and quietly denied HDR to everything under it; and the cleanup step could not remove files that install into read-only folders.
 - **Ending a session killed the entire host on Windows.** The service restarted it about six seconds later, so it read as a mystery reconnect rather than a crash — four times on one machine, every one of them a session teardown. The cause was a single log line written at a moment when the logging machinery could already be gone, and the crash handler then hid the evidence by trying to log the same way and failing the same way. Neither happens now, and if anything of that shape ever recurs, the message naming it will actually be written down.
 - **Launching a game from a Windows host on 0.30 could drop your stream a second later**, with the console reporting nothing running. Almost every Windows launch is a hand-off to Steam, Playnite or the shell — a process that quits a second after the launcher takes over. 0.30 learned to track the process it started, and for a title without any way to recognise its window it took that hand-off's exit as the game's and closed the connection. It would also, in one shape, have asked your whole Steam client to close when the game ended. Both fixed; a title the host cannot track shows as untracked instead of "launching" forever.
 - **DualSense rumble and speaker in a game streamed from a Linux host — five faults, in order:**
@@ -56,7 +79,7 @@ Most of this release is things that were wrong in ways nothing announced. A Dual
 - **A Gaming Mode takeover on a machine that logs itself in flooded the box with logins.** On a host set to log its user in automatically, the way the takeover held the desktop's login manager back sat squarely in that manager's retry path — so every automatic login failed in milliseconds and it tried again, with no back-off: 962 logins in under four minutes, the system's buttons re-scanned 5,688 times, a load of 26 on 12 cores, and every program that listens for new devices drowning in the noise. To you it looked like "my DualSense is not detected, or only with an insane delay": the pad enumerated perfectly and then delivered input at about 1.4 Hz. That method of holding back is gone; the takeover now stops the login manager first and only then steps in. If it cannot stop it, it no longer tries anyway — it falls back to streaming the desktop's own session, which is a working stream, rather than fighting a login loop that costs you your controller.
 - **Audio hiccups on the client that nothing counted.** On the Linux desktop client and the Steam Deck the audio callback was running on the wrong thread at ordinary priority, and when that thread was late the sound system played silence for us and moved on — an underrun no counter ever saw. On the host, the audio pacer measured its schedule against the wall clock while the audio it carried did not, so every small hole left it a little further behind until a bigger hole repaid the debt as a burst of silence frames — one field log showed 33–72 % of departures late and the worst nearly 100 ms behind. Both fixed, and holes no longer open and close with a click.
 - **A Steam Deck's support bundle covered three seconds instead of the whole session.** The video decoder writes a dozen bookkeeping lines per frame, and at 120 fps that flushed the entire log ring — 2,037,456 lines evicted from a 27-minute session, including the one audio line three rounds of investigation had been waiting for. The chatter is filtered before it reaches the ring.
-- **Android: the picture arrived late and dropped frames on a phone that could easily keep up.** The reference phone decodes a frame in 4–5 ms and was still showing 30 ms end to end with 40–50 skipped frames a second, because it was pacing against a display clock that Android quietly slows down for game processes. Frames are now composited straight onto the display on the panel's real timing, and each one reports back exactly when it landed. On glass: end-to-end 30 ms → about 18 ms, skipped frames 40–50 a second → 0. Whether the panel *holds* 120 Hz turns out to be the phone maker's power policy, not the app's — nothing an app can ask lifts it — so if you want 120 on such a phone, set your phone's minimum refresh rate.
+- **Android: the picture arrived late and dropped frames on a phone that could easily keep up.** The reference phone decodes a frame in 4–5 ms and was still showing 30 ms end to end with 40–50 skipped frames a second, because it was pacing against a display clock that Android quietly slows down for game processes. Frames are now composited straight onto the display on the panel's real timing, and each one reports back exactly when it landed. On glass: end-to-end 30 ms → about 18 ms, skipped frames 40–50 a second → 0. That new path carries the stream's colour properly too — high dynamic range is described by what the two ends agreed on rather than guessed at from the decoder, and ordinary content is labelled so the phone stops washing blacks out to grey — and the status and gesture bars no longer park themselves over the video for the whole session. Whether the panel *holds* 120 Hz turns out to be the phone maker's power policy, not the app's — nothing an app can ask lifts it — so if you want 120 on such a phone, set your phone's minimum refresh rate.
 - **Android: the controller went dead after opening the Controllers or Licences page from the console** — every press was dropped until you force-stopped the app. Also, plugging in a controller could leave you on a grey screen for the rest of the session if the console could not draw; it now hands you back to the touch interface instead.
 - **Mac, iPad and Apple TV: clicking a host connects to it again.** A change earlier in this cycle had made the host card open the game library instead, with "connect" pushed into the menu — the opposite of every other client. Reverted: tap to connect, "Browse Library…" back in the menu, everything else the library work landed kept.
 - **The Apple grid's first day on real hardware.** A single stick flick was read as up-then-right on the way out of the dead zone; the grid drew over the pinned title; rows vanished while still in view; one step down scrolled the row above half away; and "Copy link" was a face button on a gamepad interface. All addressed — X now opens a small options menu for the title.
@@ -64,10 +87,12 @@ Most of this release is things that were wrong in ways nothing announced. A Dual
 
 ## Thanks
 
-Several of these were found because someone sent a log detailed enough to disprove the obvious. The Steam Deck bundle that turned out to hold three seconds of decoder chatter is what made the log-ring bug visible; the audio-clock investigation went through four field logs and a purpose-built probe before a single column in a diagnostic tool named a controller's sound card; and the report of a Windows host with plugins installed, a runner running and nothing to show for it described exactly the failure the runner could not report on its own. Thank you.
+Several of these were found because someone sent a log detailed enough to disprove the obvious. The Steam Deck bundle that turned out to hold three seconds of decoder chatter is what made the log-ring bug visible; the audio-clock investigation went through four field logs and a purpose-built probe before a single column in a diagnostic tool named a controller's sound card; and the report of a Windows host with plugins installed, a runner running and nothing to show for it described exactly the failure the runner could not report on its own.
+
+Several more came from reports that were specific about the thing that did not happen, which is what made each of them findable: Big Picture not launching and the Steam overlay never appearing — a report about a program's install shape, not about streaming at all; ⌘Space doing nothing on a Mac with the setting switched on; a Playnite library that synced its games and dropped exactly 70 covers; a Portuguese-language KDE desktop where the same failure looked like a flaky one; a Steam Deck that would not wake a machine and produced no error to look at; and an Apple TV whose log bundle arrived carrying only the host's half — which is the report that got the client a log of its own. Thank you.
 
 ## For developers
 
 Protocol, ABI, driver and embedder detail — including the version table and the notes on what moved — is in [CHANGELOG.md](https://git.unom.io/unom/punktfunk/src/tag/v0.31.0/CHANGELOG.md).
 
-The short version: nothing versioned moves — no wire, ABI, driver-protocol or plugin-contract change — and the C header is byte-identical to 0.30.0's. Three things are worth reading before you package or embed this release: the Linux host package now installs three new system files (a device rule, a sound-system policy and a sound-card configuration) that the controller-audio fixes depend on; the Linux desktop-audio capture changed topology by default, with a one-release escape hatch back to the 0.30 shape; and the Android app's Compose console is deleted outright, which removes its screenshot scenes.
+The short version: the streaming protocol does not move, and neither does the driver protocol or the plugin contract, so nothing needs re-pairing in any direction. The embedding interface moves one step by pure addition — a single new call that hands an embedder the engine's own log lines, which is what gave the Apple client something worth sending in the first place; adopt it or ignore it, nothing else changed shape. Four things are worth reading before you package or embed this release: the Windows client's default download is now a per-user installer plus a portable zip, with the Store package kept as an alternate; the Linux host package installs three new system files (a device rule, a sound-system policy and a sound-card configuration) that the controller-audio fixes depend on; the Linux desktop-audio capture changed topology by default, with a one-release escape hatch back to the 0.30 shape; and the Android app's Compose console is deleted outright, which removes its screenshot scenes.

docs/releases/whatsnew/v0.31.0.txt

@@ -1,3 +1,4 @@
-• The controller interface is now the same console the desktop app shows — on every phone and TV, 32-bit boxes included — with a Controllers page of its own.
-• A much faster picture: frames land on the panel's real timing, so on the reference phone latency fell from 30 to about 18 ms and dropped frames from 40–50 a second to none.
-• Fixed: the gamepad going dead after opening Controllers or Licences, a grey screen when the console could not draw, and audio gaps when the buffer needed to grow.
+• The controller interface is now the same console the desktop shows — on every phone and TV, 32-bit boxes included — with its own Controllers page.
+• A much faster picture: frames land on the panel's real timing, so latency on the reference phone fell from 30 to about 18 ms and dropped frames to none.
+• New: send logs to the host, wake a sleeping PC, controller haptics and speaker switches.
+• Fixed: swiping the settings list no longer changes values.

include/punktfunk_core.h

@@ -1224,6 +1224,11 @@
 #define PUNKTFUNK_MSG_PIPELINE_GAP 10
 #endif
 
+#if defined(PUNKTFUNK_FEATURE_QUIC)
+// Type byte of [`DeliveryReport`].
+#define PUNKTFUNK_MSG_DELIVERY_REPORT 11
+#endif
+
 #if defined(PUNKTFUNK_FEATURE_QUIC)
 // Type byte of [`ProbeRequest`].
 #define PUNKTFUNK_MSG_PROBE_REQUEST 32

packaging/nix/gamescope.nix

@@ -31,11 +31,39 @@
 {
   lib,
   gamescope,
+  fetchFromGitHub,
   python3,
   patchDir,
   manifestRewriter,
 }:
 let
+  # PIN THE COMPOSITOR SOURCE, rather than patching whatever gamescope nixpkgs happens to carry.
+  # Every other channel already ships this exact commit — packaging/gamescope/README.md,
+  # punktfunk-gamescope.spec, the PKGBUILD and build-punktfunk-gamescope.sh — and nix was the
+  # only one tracking nixpkgs' version and hoping ten patches still applied.
+  #
+  # They did not, and the failures were not academic (MEASURED 2026-08-19/20):
+  #   * nixpkgs shipped 3.16.24 and patch 0009's context did not exist there at all, so the
+  #     build died at patchPhase — every `services.punktfunk.host.enable = true` with it.
+  #   * bumping the lock to 3.16.25 fixed that, then `--version` printed NOTHING: upstream's
+  #     `gamescope::PrintVersion()` landed AFTER the 3.16.25 tag. The host reads that banner to
+  #     decide a session's bit depth and cursor compositing BEFORE the virtual display exists,
+  #     so a silent banner means a silent fall back to SDR — the exact failure every guard in
+  #     this file is written to prevent.
+  # Both are the same bug: nixpkgs' gamescope is older than the tree these patches target.
+  # Pinning makes the nix package agree with every other channel byte for byte.
+  #
+  # Bumping this: move the rev, then `nix-prefetch-git --url https://github.com/ValveSoftware/gamescope
+  # --rev <new> --fetch-submodules` for the hash, and keep packaging/gamescope/README.md in step.
+  pfRev = "5fb8dce4a09d0a68d097b9faf9513782106bc843";
+  pfVersion = "3.16.25-11-g5fb8dce";
+  pfSrc = fetchFromGitHub {
+    owner = "ValveSoftware";
+    repo = "gamescope";
+    rev = pfRev;
+    fetchSubmodules = true;
+    hash = "sha256-pGBiO+7LSdIc0k9K+SQnv/Og2DYD/cjvOImxIl91L2A=";
+  };
   # As of nixos-unstable (checked 2026-07-28) `gamescope` IS the buildable derivation — pname
   # "gamescope", version 3.16.25, carrying `src`/`patches`/`mesonFlags`. Revisions that wrap it
   # (to wire the WSI layer + capabilities) expose the build as `.unwrapped`, so prefer that where
@@ -76,6 +104,8 @@ let
 in
 unwrapped.overrideAttrs (old: {
   pname = "punktfunk-gamescope";
+  version = pfVersion;
+  src = pfSrc;
 
   # Read the patch DIRECTORY rather than naming files: `builtins.attrNames` sorts
   # lexicographically, which for `000N-` prefixes is exactly the apply order, and a patch added or
@@ -96,7 +126,19 @@ unwrapped.overrideAttrs (old: {
     substituteInPlace src/meson.build \
       --replace-fail \
         "vcs_tag = run_command(vcs_tag_cmd, check: false).stdout().strip()" \
-        "vcs_tag = '${old.version}'"
+        "vcs_tag = '${pfVersion}'"
+
+    # Source-level gate, the same one packaging/gamescope/build-punktfunk-gamescope.sh applies.
+    # Splits a missing marker into its two possible stages: fire HERE and patch 0005 or the
+    # substitution above lost it; pass here and fail the ELF check later, and it was lost in
+    # meson configuration or compilation instead. Without this the two are indistinguishable,
+    # at a full compositor build per guess.
+    grep -q '+pfhdr' src/meson.build || {
+      echo "punktfunk-gamescope: +pfhdr is not in src/meson.build after patching" >&2
+      echo "  --- version block as patched: ---" >&2
+      sed -n '/^vcs_tag_cmd/,/^gamescope_version_conf/p' src/meson.build | sed 's/^/    | /' >&2
+      exit 1
+    }
   '';
 
   # Ship the compositor, renamed, AND the WSI layer built beside it. Everything else nixpkgs
@@ -134,7 +176,17 @@ unwrapped.overrideAttrs (old: {
     chmod -R u+w $out
 
     find $out -mindepth 1 -maxdepth 1 ! -name bin -exec rm -rf {} +
-    find $out/bin -mindepth 1 ! -name gamescope -delete
+    # KEEP `.gamescope-wrapped`. nixpkgs wraps this package: makeWrapper leaves the real
+    # compositor ELF at bin/.gamescope-wrapped and installs a small launcher at bin/gamescope
+    # that sets PATH (xwininfo) before exec'ing it. A prune that keeps only `gamescope` deletes
+    # the compositor and ships the launcher alone — MEASURED 2026-08-20 (run 19622): $out/bin
+    # held a single 16 KB file, `--version` printed nothing because the launcher exec'd a path
+    # that no longer existed, and no +pfhdr marker was present because a wrapper carries no
+    # version string. Every symptom chased for three builds came from this one line.
+    #
+    # The launcher references its target by ABSOLUTE path, so renaming the launcher is safe
+    # while the target keeps its name.
+    find $out/bin -mindepth 1 ! -name gamescope ! -name '.gamescope-wrapped' -delete
     mv $out/bin/gamescope $out/bin/punktfunk-gamescope
 
     install -Dm0755 "$TMPDIR/pf-layer.so" \
@@ -147,8 +199,38 @@ unwrapped.overrideAttrs (old: {
   doInstallCheck = true;
   installCheckPhase = ''
     runHook preInstallCheck
-    $out/bin/punktfunk-gamescope --version 2>&1 | grep -q '+pfhdr' \
-      || { echo "punktfunk-gamescope: the +pfhdr marker is missing — the patches did not take"; exit 1; }
+    # Assert the marker is compiled INTO the shipped binary, rather than running it.
+    #
+    # Running it does not work here and never did: `--version` produced EMPTY output under the
+    # build sandbox on BOTH nixpkgs' 3.16.25 and the pinned 5fb8dce4 (MEASURED 2026-08-19/20,
+    # runs 19551 / 19573 / 19594). That is a property of the sandbox, not a defect in the binary:
+    # gamescope calls PrintVersion() before the getopt loop (src/main.cpp:721 at the pinned rev),
+    # so `gamescope --version` DOES print the banner on a real system — which is what the host's
+    # capability probe reads.
+    #
+    # packaging/gamescope/build-punktfunk-gamescope.sh makes the same call, asserting on
+    # src/meson.build. Grepping the installed ELF is strictly stronger: the version string reaches
+    # .rodata through GamescopeVersion.h's k_szGamescopeVersion, so this proves the marker survived
+    # patching, meson configuration AND compilation into the artifact we actually ship, and it
+    # cannot be defeated by the binary being unable to start.
+    # Grep the WRAPPED ELF: bin/punktfunk-gamescope is nixpkgs' launcher and carries no version
+    # string at all, so asserting on it would pass only by accident. Fall back to the launcher
+    # for a future nixpkgs that stops wrapping.
+    gsElf=$out/bin/.gamescope-wrapped
+    [ -f "$gsElf" ] || gsElf=$out/bin/punktfunk-gamescope
+    grep -aq '+pfhdr' "$gsElf" || {
+      echo "punktfunk-gamescope: the +pfhdr marker is not in the installed binary." >&2
+      echo "  src/meson.build carried it (asserted in postPatch), so it was lost between" >&2
+      echo "  meson configuration and the linked artifact. Evidence:" >&2
+      echo "  --- $out/bin ---" >&2
+      ls -l $out/bin 2>&1 | sed 's/^/    | /' >&2
+      echo "  --- anything under $out mentioning pfhdr ---" >&2
+      grep -ral 'pfhdr' $out 2>/dev/null | sed 's/^/    | /' >&2 || echo "    | (nothing)" >&2
+      echo "  --- version-ish strings in the binary ---" >&2
+      grep -aoE '[0-9]+\.[0-9]+\.[0-9]+[^ ]*' "$gsElf" 2>/dev/null \
+        | sort -u | head -5 | sed 's/^/    | /' >&2 || true
+      exit 1
+    }
     # The manifest must name a library this derivation actually installed. A manifest pointing at a
     # path that does not exist is the worst shape of this bug: the loader reads it, finds nothing,
     # and carries on silently, so the box looks healthy and every game renders SDR.

plugin-kit/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@punktfunk/plugin-kit",
-	"version": "0.4.3",
+	"version": "0.4.4",
 	"description": "Effect-based framework for punktfunk plugins: lifecycle runtime, config/state, sync engine, UI serving, CLI scaffold, and browser helpers.",
 	"type": "module",
 	"license": "MIT OR Apache-2.0",