fix(rpm): drop the moved design/implementation-plan.md from %doc

The RPM %files %doc referenced design/implementation-plan.md, but the design/ docs live in the separate planning repo now — the file isn't in the public tree, so rpmbuild failed at %files ("File not found: .../implementation-plan.md") once the build got that far. Ship the two docs that actually exist (README.md + packaging/README.md). Pre-existing spec rot, surfaced by the 0.8.3 release run. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
fix(packaging): vulkan-headers build dep + ship punktfunk-session across desktop packages
2026-07-08 00:44:28 +02:00 · 2026-07-07 23:41:10 +02:00 · 2026-07-07 23:33:40 +02:00 · 2026-07-07 23:18:12 +02:00 · 2026-07-07 23:14:08 +02:00 · 2026-07-07 23:14:08 +02:00
221 changed files with 22793 additions and 6519 deletions
@@ -25,7 +25,8 @@ jobs:
          java-version: "21"
      - name: Android SDK
-        uses: android-actions/setup-android@v3
+        # SHA-pinned for parity with android.yml (third-party action). v3 = 9fc6c4e.
        uses: android-actions/setup-android@9fc6c4e9069bf8d3d10b2204b1fb8f6ef7065407 # v3
      # No NDK/CMake — the screenshot unit tests are pure JVM. compileSdk 37 auto-downloads via AGP
      # if the platform channel lacks it (same note as android.yml).
@@ -43,7 +43,9 @@ jobs:
          "$RUSTUP" target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android
      - name: Android SDK
-        uses: android-actions/setup-android@v3
+        # SHA-pinned: this workflow's release job carries the signing keystore + Play service-account
        # secrets, so a moved tag on a third-party action could exfiltrate them. v3 = 9fc6c4e.
        uses: android-actions/setup-android@9fc6c4e9069bf8d3d10b2204b1fb8f6ef7065407 # v3
      - name: NDK r30 + platform 36 + build-tools + CMake (libopus cross-build)
        # cmake;3.22.1 installs cmake + ninja under $ANDROID_SDK/cmake/3.22.1/bin — the exact path
@@ -101,6 +103,23 @@ jobs:
          # AAB for Play; a universal APK (all ABIs) for direct sideload/testing — same upload key.
          ./gradlew :app:bundleRelease :app:assembleRelease --stacktrace
      # Attach the built APK to the workflow run so it's a one-click sideload download straight from the
      # run page (no need to know the generic-registry URL) — on EVERY trigger, incl. a PR or a
      # workflow_dispatch. The debug APK is built on every run; the signed universal release APK exists
      # only on a main/tag push (its build step above is push-gated), so grab whichever were produced.
      - name: Attach APK(s) to the workflow run
        if: always()
        # v3, not v4: Gitea's artifact backend identifies as GHES, which upload-artifact@v4 refuses
        # (same reason as apple.yml / *-screenshots.yml). Download is a zip of the matched APK(s).
        uses: actions/upload-artifact@v3
        with:
          name: punktfunk-android-apk
          path: |
            clients/android/app/build/outputs/apk/release/*.apk
            clients/android/app/build/outputs/apk/debug/*.apk
          if-no-files-found: warn
          retention-days: 30
      # Publish BEFORE the Play upload so artifacts land even while the Play step is still failing.
      # Generic registry is public for reads — matches windows-msix.yml / deb.yml (REGISTRY_TOKEN, user enricobuehler).
      # main = canary store + `canary/` sideload alias; a `vX.Y.Z` tag = `latest/` alias + attached
@@ -42,7 +42,7 @@ jobs:
      - name: Install build + runtime-dev deps
        run: |
          pacman -Syu --noconfirm --needed \
-            git nodejs rust clang cmake nasm pkgconf python \
+            git nodejs rust clang cmake nasm pkgconf python vulkan-headers \
            gtk4 libadwaita sdl3 ffmpeg pipewire wayland libxkbcommon opus libei \
            mesa libglvnd unzip libarchive
          # bun builds the punktfunk-web console AND is vendored as its runtime (PF_WITH_WEB=1);
@@ -1,7 +1,10 @@
-# Supply-chain advisory scan for the (network-facing, crypto-heavy) Rust dependency tree.
+# Supply-chain advisory scan for BOTH dependency trees the project ships to users:
-# Runs `cargo audit` against the RustSec advisory DB: weekly (catch newly-disclosed CVEs in
+#   * cargo-audit → the (network-facing, crypto-heavy) Rust tree, against the RustSec advisory DB.
-# pinned deps), on every Cargo.lock change (catch a bad dep the moment it lands), and on demand.
+#   * bun audit   → the web management console (Nitro/Bun BFF) — the component that holds the login
-# To silence a known-unfixable advisory, add it to `.cargo/audit.toml` ([advisories] ignore = [...]).
+#                   gate, session sealing, and the mgmt bearer token, so its deps matter too.
 # Triggers: weekly (catch newly-disclosed CVEs in pinned deps), on every lockfile change (catch a bad
 # dep the moment it lands), and on demand.
 # To silence a known-unfixable Rust advisory, add it to `.cargo/audit.toml` ([advisories] ignore=[…]).
 name: audit
 on:
@@ -9,7 +12,7 @@ on:
    - cron: '0 6 * * 1'   # Mondays 06:00 UTC
  push:
    branches: [main]
-    paths: ['Cargo.lock', '.gitea/workflows/audit.yml']
+    paths: ['Cargo.lock', 'web/bun.lock', '.gitea/workflows/audit.yml']
  workflow_dispatch:
 jobs:
@@ -31,3 +34,25 @@ jobs:
          git config --global --add safe.directory "$PWD"
          command -v cargo-audit >/dev/null 2>&1 || cargo install --locked cargo-audit
          cargo audit
  bun-audit:
    runs-on: ubuntu-24.04
    container:
      image: oven/bun:1
    timeout-minutes: 15
    defaults:
      run:
        working-directory: web
    steps:
      # oven/bun's slim base lacks a CA bundle + git — actions/checkout's HTTPS fetch needs them
      # (same preamble as web-screenshots.yml / ci.yml's web job).
      - name: Install git + CA certs
        working-directory: /
        run: apt-get update && apt-get install -y --no-install-recommends ca-certificates git
      - uses: actions/checkout@v4
      # `bun audit` queries the registry advisory DB for the versions pinned in web/bun.lock. No
      # install/build needed — it reads the manifest + lockfile. Fails the job on any advisory, the
      # same fail-on-vulnerability stance as cargo-audit above; triage a finding by bumping the dep
      # (or, if genuinely unfixable + inapplicable, pinning a resolution and noting why here).
      - name: bun audit
        run: bun audit
@@ -60,8 +60,10 @@ jobs:
        run: |
          apt-get update
          # python3 is used by scripts/ci/gitea-release.sh for the stable-tag release attach.
          # libvulkan-dev: /usr/include/vulkan/vulkan.h for the client's pf-ffvk bindgen
          # (FFmpeg's hwcontext_vulkan.h includes it).
          apt-get install -y --no-install-recommends dpkg-dev python3 \
-            libgtk-4-dev libadwaita-1-dev libsdl3-dev
+            libgtk-4-dev libadwaita-1-dev libsdl3-dev libvulkan-dev
      # Share ci.yml's cache keys so the release build reuses its registry + target artifacts.
      - name: Cache keys
@@ -86,7 +88,10 @@ jobs:
          PUNKTFUNK_BUILD_VERSION: ${{ env.VERSION }}   # stamped into the binary (build.rs)
        run: |
          git config --global --add safe.directory "$PWD"
-          cargo build --release -p punktfunk-host -p punktfunk-client-linux --locked
+          # punktfunk-client-session is the Vulkan/Skia streamer the shell execs for a connect —
          # both client binaries must ship (build-client-deb.sh installs both).
          cargo build --release --locked \
            -p punktfunk-host -p punktfunk-client-linux -p punktfunk-client-session
      - name: Build + smoke-boot web console (bun preset)
        # Gate the .deb on a real bun boot: the punktfunk-web .deb runs the Nitro `bun` preset
@@ -86,7 +86,10 @@ jobs:
      - uses: actions/checkout@v4
      - name: Sync compose file
-        uses: appleboy/scp-action@v0.1.7
+        # SHA-pinned (not tag-pinned): this action receives DEPLOY_SSH_KEY + host/user/port, so a
        # moved tag would mean credential exfiltration. v0.1.7 = 917f8b8. Bump both the SHA and the
        # trailing version together when upgrading.
        uses: appleboy/scp-action@917f8b81dfc1ccd331fef9e2d61bdc6c8be94634 # v0.1.7
        with:
          host: ${{ secrets.DEPLOY_HOST }}
          username: ${{ secrets.DEPLOY_USER }}
@@ -97,7 +100,8 @@ jobs:
          overwrite: true
      - name: Pull and start docs
-        uses: appleboy/ssh-action@v1.2.5
+        # SHA-pinned: receives DEPLOY_SSH_KEY + REGISTRY_TOKEN (see the scp step above). v1.2.5 = 0ff4204.
        uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5
        env:
          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
        with:
@@ -25,9 +25,15 @@ on:
    branches: [main]
    # The flatpak is the CLIENT — only rebuild when the client/core/manifest change, not on every
    # design/host push (this is a heavy flatpak-builder run). Tags (v*, the client release) build too.
    # The bundle ships BOTH client binaries (shell + Vulkan session), so every crate in either
    # binary's dependency closure must be listed here.
    paths:
      - 'clients/linux/**'
      - 'clients/linux-session/**'
      - 'crates/punktfunk-core/**'
      - 'crates/pf-client-core/**'
      - 'crates/pf-presenter/**'
      - 'crates/pf-console-ui/**'
      - 'packaging/flatpak/**'
      - 'Cargo.lock'
      - '.gitea/workflows/flatpak.yml'
@@ -30,7 +30,7 @@ jobs:
        run: |
          apt-get update
          apt-get install -y --no-install-recommends \
-            libgtk-4-dev libadwaita-1-dev libsdl3-dev \
+            libgtk-4-dev libadwaita-1-dev libsdl3-dev libvulkan-dev \
            xvfb x11-utils imagemagick scrot \
            libgl1-mesa-dri mesa-vulkan-drivers \
            adwaita-icon-theme fonts-cantarell fonts-dejavu-core
@@ -54,7 +54,9 @@ jobs:
      - name: Prep
        run: |
          git config --global --add safe.directory "$PWD"
-          dnf -y install gtk4-devel libadwaita-devel SDL3-devel
+          # vulkan-headers: the client's pf-ffvk crate runs bindgen over FFmpeg's
          # libavutil/hwcontext_vulkan.h (#include <vulkan/vulkan.h>).
          dnf -y install gtk4-devel libadwaita-devel SDL3-devel vulkan-headers
          # sysext build (packaging/bazzite/build-sysext.sh): squashfs + SELinux labeling.
          dnf -y install squashfs-tools cpio libselinux-utils selinux-policy-targeted
          # bun builds the punktfunk-web console (--with web). Baked into the image; install it
@@ -472,6 +472,8 @@ dependencies = [
 "cexpr",
 "clang-sys",
 "itertools 0.13.0",
 "log",
 "prettyplease",
 "proc-macro2",
 "quote",
 "regex",
@@ -889,9 +891,9 @@ dependencies = [
 [[package]]
 name = "crossbeam-epoch"
-version = "0.9.18"
+version = "0.9.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5b82ac4a3c2ca9c3460964f020e1402edd5753411d7737aa39c3714ad1b5420e"
+checksum = "2d6914041f254d6e9176c01941b21115dcfb7089e55135a35411081bd106ef3f"
 dependencies = [
 "crossbeam-utils",
 ]
@@ -1144,6 +1146,9 @@ name = "fastrand"
 version = "2.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
 dependencies = [
 "getrandom 0.3.4",
 ]
 [[package]]
 name = "fec-rs"
@@ -1193,6 +1198,16 @@ dependencies = [
 "rustc_version",
 ]
 [[package]]
 name = "filetime"
 version = "0.2.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5c287a33c7f0a620c38e641e7f60827713987b3c0f26e8ddc9462cc69cf75759"
 dependencies = [
 "cfg-if",
 "libc",
 ]
 [[package]]
 name = "find-msvc-tools"
 version = "0.1.9"
@@ -1221,6 +1236,7 @@ version = "0.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5e139bc46ca777eb5efaf62df0ab8cc5fd400866427e56c68b22e414e53bd3be"
 dependencies = [
 "fastrand",
 "futures-core",
 "futures-sink",
 "spin",
@@ -1247,6 +1263,15 @@ dependencies = [
 "percent-encoding",
 ]
 [[package]]
 name = "fragile"
 version = "2.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8878864ba14bb86e818a412bfd6f18f9eabd4ec0f008a28e8f7eb61db532fcf9"
 dependencies = [
 "futures-core",
 ]
 [[package]]
 name = "fs-err"
 version = "3.3.0"
@@ -2129,7 +2154,7 @@ dependencies = [
 [[package]]
 name = "latency-probe"
-version = "0.8.0"
+version = "0.8.3"
 [[package]]
 name = "lazy_static"
@@ -2261,7 +2286,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
 [[package]]
 name = "loss-harness"
-version = "0.8.0"
+version = "0.8.3"
 dependencies = [
 "punktfunk-core",
 ]
@@ -2740,6 +2765,39 @@ version = "2.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
 [[package]]
 name = "pf-client-core"
 version = "0.8.3"
 dependencies = [
 "anyhow",
 "async-channel",
 "ffmpeg-next",
 "mdns-sd",
 "opus",
 "pf-ffvk",
 "pipewire",
 "punktfunk-core",
 "rustls",
 "sdl3",
 "serde",
 "serde_json",
 "tracing",
 "ureq",
 ]
 [[package]]
 name = "pf-console-ui"
 version = "0.8.3"
 dependencies = [
 "anyhow",
 "ash",
 "pf-client-core",
 "pf-presenter",
 "sdl3",
 "skia-safe",
 "tracing",
 ]
 [[package]]
 name = "pf-driver-proto"
 version = "0.0.1"
@@ -2747,6 +2805,29 @@ dependencies = [
 "bytemuck",
 ]
 [[package]]
 name = "pf-ffvk"
 version = "0.8.3"
 dependencies = [
 "ash",
 "bindgen",
 "pkg-config",
 ]
 [[package]]
 name = "pf-presenter"
 version = "0.8.3"
 dependencies = [
 "anyhow",
 "ash",
 "async-channel",
 "pf-client-core",
 "pf-ffvk",
 "punktfunk-core",
 "sdl3",
 "tracing",
 ]
 [[package]]
 name = "pin-project-lite"
 version = "0.2.17"
@@ -2869,13 +2950,23 @@ dependencies = [
 "zerocopy",
 ]
 [[package]]
 name = "prettyplease"
 version = "0.2.37"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b"
 dependencies = [
 "proc-macro2",
 "syn",
 ]
 [[package]]
 name = "proc-macro-crate"
 version = "3.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e67ba7e9b2b56446f1d419b1d807906278ffa1a658a8a5d8a39dcb1f5a78614f"
 dependencies = [
- "toml_edit",
+ "toml_edit 0.25.12+spec-1.1.0",
 ]
 [[package]]
@@ -2908,7 +2999,7 @@ dependencies = [
 [[package]]
 name = "punktfunk-client-android"
-version = "0.8.0"
+version = "0.8.3"
 dependencies = [
 "android_logger",
 "jni",
@@ -2918,34 +3009,42 @@ dependencies = [
 "ndk",
 "opus",
 "punktfunk-core",
 "tracing",
 ]
 [[package]]
 name = "punktfunk-client-linux"
-version = "0.8.0"
+version = "0.8.3"
 dependencies = [
 "anyhow",
 "async-channel",
 "ffmpeg-next",
 "gtk4",
 "khronos-egl",
 "libadwaita",
- "mdns-sd",
+ "pf-client-core",
- "opus",
+ "punktfunk-core",
- "pipewire",
+ "relm4",
 "serde_json",
 "tracing",
 "tracing-subscriber",
 ]
 [[package]]
 name = "punktfunk-client-session"
 version = "0.8.3"
 dependencies = [
 "anyhow",
 "pf-client-core",
 "pf-console-ui",
 "pf-presenter",
 "punktfunk-core",
 "rustls",
 "sdl3",
 "serde",
 "serde_json",
 "tracing",
 "tracing-subscriber",
 "ureq",
 ]
 [[package]]
 name = "punktfunk-client-windows"
-version = "0.8.0"
+version = "0.8.3"
 dependencies = [
 "anyhow",
 "async-channel",
@@ -2968,7 +3067,7 @@ dependencies = [
 [[package]]
 name = "punktfunk-core"
-version = "0.8.0"
+version = "0.8.3"
 dependencies = [
 "aes-gcm",
 "bytes",
@@ -2999,7 +3098,7 @@ dependencies = [
 [[package]]
 name = "punktfunk-host"
-version = "0.8.0"
+version = "0.8.3"
 dependencies = [
 "aes",
 "aes-gcm",
@@ -3071,7 +3170,7 @@ dependencies = [
 [[package]]
 name = "punktfunk-probe"
-version = "0.8.0"
+version = "0.8.3"
 dependencies = [
 "anyhow",
 "mdns-sd",
@@ -3085,7 +3184,7 @@ dependencies = [
 [[package]]
 name = "punktfunk-tray"
-version = "0.8.0"
+version = "0.8.3"
 dependencies = [
 "anyhow",
 "ksni",
@@ -3370,6 +3469,41 @@ dependencies = [
 "tokio",
 ]
 [[package]]
 name = "relm4"
 version = "0.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6420f090f0545e9ec9656469d139a4e1b66ff9c30b808fe2247892724f71a198"
 dependencies = [
 "flume",
 "fragile",
 "futures",
 "gtk4",
 "libadwaita",
 "once_cell",
 "relm4-css",
 "relm4-macros",
 "tokio",
 "tracing",
 ]
 [[package]]
 name = "relm4-css"
 version = "0.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f3b81d263f784b103c815afa29124486b59741eca069ce7a5999efb14f13c368"
 [[package]]
 name = "relm4-macros"
 version = "0.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "36c9dbf50a60c82375e66b61d522c936b187a11b25c0a42e91c516326ad24a4f"
 dependencies = [
 "proc-macro2",
 "quote",
 "syn",
 ]
 [[package]]
 name = "ring"
 version = "0.17.14"
@@ -3690,6 +3824,7 @@ version = "0.6.6+SDL-3.4.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "04e7f134def04ed72e6f55187c6c29c72f7dab5d359c4be0dd49c9b97fef59c7"
 dependencies = [
 "ash",
 "cc",
 "cmake",
 "pkg-config",
@@ -3812,6 +3947,15 @@ dependencies = [
 "syn",
 ]
 [[package]]
 name = "serde_spanned"
 version = "0.6.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bf41e0cfaf7226dca15e8197172c295a782857fcb97fad1808a166870dee75a3"
 dependencies = [
 "serde",
 ]
 [[package]]
 name = "serde_spanned"
 version = "1.1.1"
@@ -3897,6 +4041,35 @@ version = "1.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8ee5873ec9cce0195efcb7a4e9507a04cd49aec9c83d0389df45b1ef7ba2e649"
 [[package]]
 name = "skia-bindings"
 version = "0.87.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "704242769235d2ffe66a2a0a3002661262fc4af08d32807c362d7b0160ee703c"
 dependencies = [
 "bindgen",
 "cc",
 "flate2",
 "heck",
 "lazy_static",
 "pkg-config",
 "regex",
 "serde_json",
 "tar",
 "toml 0.8.23",
 ]
 [[package]]
 name = "skia-safe"
 version = "0.87.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0f7d94f3e7537c71ad4cf132eb26e3be8c8a886ed3649c4525c089041fc312b2"
 dependencies = [
 "bitflags",
 "lazy_static",
 "skia-bindings",
 ]
 [[package]]
 name = "slab"
 version = "0.4.12"
@@ -4032,6 +4205,17 @@ dependencies = [
 "version-compare",
 ]
 [[package]]
 name = "tar"
 version = "0.4.46"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3f6221d9a6003c78398e3b239969f352578258df48c8eb051caadae0015bc840"
 dependencies = [
 "filetime",
 "libc",
 "xattr",
 ]
 [[package]]
 name = "target-lexicon"
 version = "0.13.5"
@@ -4217,6 +4401,18 @@ dependencies = [
 "tokio",
 ]
 [[package]]
 name = "toml"
 version = "0.8.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dc1beb996b9d83529a9e75c17a1686767d148d70663143c7854d8b4a09ced362"
 dependencies = [
 "serde",
 "serde_spanned 0.6.9",
 "toml_datetime 0.6.11",
 "toml_edit 0.22.27",
 ]
 [[package]]
 name = "toml"
 version = "0.9.12+spec-1.1.0"
@@ -4225,7 +4421,7 @@ checksum = "cf92845e79fc2e2def6a5d828f0801e29a2f8acc037becc5ab08595c7d5e9863"
 dependencies = [
 "indexmap",
 "serde_core",
- "serde_spanned",
+ "serde_spanned 1.1.1",
 "toml_datetime 0.7.5+spec-1.1.0",
 "toml_parser",
 "toml_writer",
@@ -4240,13 +4436,22 @@ checksum = "81f3d15e84cbcd896376e6730314d59fb5a87f31e4b038454184435cd57defee"
 dependencies = [
 "indexmap",
 "serde_core",
- "serde_spanned",
+ "serde_spanned 1.1.1",
 "toml_datetime 1.1.1+spec-1.1.0",
 "toml_parser",
 "toml_writer",
 "winnow 1.0.3",
 ]
 [[package]]
 name = "toml_datetime"
 version = "0.6.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "22cddaf88f4fbc13c51aebbf5f8eceb5c7c5a9da2ac40a13519eb5b0a0e8f11c"
 dependencies = [
 "serde",
 ]
 [[package]]
 name = "toml_datetime"
 version = "0.7.5+spec-1.1.0"
@@ -4265,6 +4470,20 @@ dependencies = [
 "serde_core",
 ]
 [[package]]
 name = "toml_edit"
 version = "0.22.27"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "41fe8c660ae4257887cf66394862d21dbca4a6ddd26f04a3560410406a2f819a"
 dependencies = [
 "indexmap",
 "serde",
 "serde_spanned 0.6.9",
 "toml_datetime 0.6.11",
 "toml_write",
 "winnow 0.7.15",
 ]
 [[package]]
 name = "toml_edit"
 version = "0.25.12+spec-1.1.0"
@@ -4286,6 +4505,12 @@ dependencies = [
 "winnow 1.0.3",
 ]
 [[package]]
 name = "toml_write"
 version = "0.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801"
 [[package]]
 name = "toml_writer"
 version = "1.1.1+spec-1.1.0"
@@ -5329,6 +5554,9 @@ name = "winnow"
 version = "0.7.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
 dependencies = [
 "memchr",
 ]
 [[package]]
 name = "winnow"
@@ -5388,6 +5616,16 @@ dependencies = [
 "time",
 ]
 [[package]]
 name = "xattr"
 version = "1.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32e45ad4206f6d2479085147f02bc2ef834ac85886624a23575ae137c8aa8156"
 dependencies = [
 "libc",
 "rustix",
 ]
 [[package]]
 name = "xkbcommon"
 version = "0.8.0"
@@ -5,9 +5,14 @@ members = [
    "crates/punktfunk-host",
    "crates/punktfunk-host/vendor/usbip-sim",
    "crates/punktfunk-tray",
    "crates/pf-client-core",
    "crates/pf-presenter",
    "crates/pf-console-ui",
    "crates/pf-ffvk",
    "crates/pf-driver-proto",
    "clients/probe",
    "clients/linux",
    "clients/linux-session",
    "clients/windows",
    "clients/android/native",
    "tools/latency-probe",
@@ -17,7 +22,7 @@ members = [
 exclude = ["packaging/linux/steam-deck-gadget/usbip-poc"]
 [workspace.package]
-version = "0.8.0"
+version = "0.8.3"
 edition = "2021"
 rust-version = "1.82"
 license = "MIT OR Apache-2.0"
@@ -57,7 +57,7 @@ protocol, FEC, and crypto, linked into the host and every client over a stable C
 | **Core** — `punktfunk-core` + C ABI (protocol · FEC · crypto · QUIC) | ✅ Complete & hardened |
 | **GameStream host** → stock Moonlight | ✅ Live end-to-end: pairing, RTSP, audio, per-client virtual output at native resolution, GPU zero-copy NVENC, gamepads |
 | **Native protocol** — `punktfunk/1` | ✅ Validated live: QUIC control + GF(2¹⁶) FEC/AES-GCM data plane, PIN pairing, mDNS discovery, mid-stream mode renegotiation |
-| **Windows host** (Windows 11 22H2+, x64) | 🟡 Implemented & shipping as a signed installer: DXGI/WGC capture · its own all-Rust IddCx **virtual display** (secure-desktop capable) · GPU encode (NVENC on NVIDIA, AMF/QSV on AMD/Intel, software H.264 without a GPU) · WASAPI audio · bundled virtual-gamepad drivers (no ViGEmBus) · HDR incl. Vulkan-game HDR. NVIDIA live-validated; AMD/Intel CI-green |
+| **Windows host** (Windows 11 22H2+, x64) | 🟡 Implemented & shipping as a signed installer: its own all-Rust IddCx **virtual display** (secure-desktop capable) with a **sealed IDD-push** capture path — finished frames pushed straight into its own driver, not screen-scraped (no DDA/WGC) · GPU encode (NVENC on NVIDIA, AMF/QSV on AMD/Intel, software H.264 without a GPU) · WASAPI audio · bundled virtual-gamepad drivers (no ViGEmBus) · HDR incl. Vulkan-game HDR. NVIDIA live-validated; AMD/Intel CI-green |
 | **macOS / iOS / tvOS client** (`clients/apple`) | ✅ Streaming live: VideoToolbox decode, controllers incl. DualSense, discovery, pairing, speed test |
 | **Linux client** (`clients/linux`, GTK4) | ✅ Streaming live: FFmpeg + VAAPI zero-copy decode, PipeWire audio, SDL3 controllers; ships as Flatpak/apt/rpm/Arch |
 | **Android client** (`clients/android`, phone + TV) | ✅ Streaming live: AMediaCodec decode + HDR10, AAudio audio, controllers, discovery, pairing |
@@ -10,7 +10,7 @@
      "name": "MIT OR Apache-2.0",
      "identifier": "MIT OR Apache-2.0"
    },
-    "version": "0.7.4"
+    "version": "0.8.3"
  },
  "paths": {
    "/api/v1/clients": {
@@ -190,6 +190,237 @@
        }
      }
    },
    "/api/v1/display/presets": {
      "get": {
        "tags": [
          "display"
        ],
        "summary": "List the saved custom presets",
        "description": "The operator's named field-bundles (`display-presets.json`). These also ride the\n`GET /display/settings` response (`custom_presets`), so the console rarely needs this directly.",
        "operationId": "listCustomPresets",
        "responses": {
          "200": {
            "description": "The saved custom presets",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/CustomPreset"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "display"
        ],
        "summary": "Save a custom preset",
        "description": "Stores a named bundle of the display-behavior axes (+ the game-session axis) the operator can\napply later. The host assigns a stable id, returned in the body. Applying a preset is a\n`PUT /display/settings` with a `Custom` policy carrying its `fields` — no separate apply route.",
        "operationId": "createCustomPreset",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomPresetInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Preset created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomPreset"
                }
              }
            }
          },
          "400": {
            "description": "Empty name",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Could not persist the catalog",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/display/presets/{id}": {
      "put": {
        "tags": [
          "display"
        ],
        "summary": "Update a custom preset",
        "operationId": "updateCustomPreset",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The custom preset id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomPresetInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Preset updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomPreset"
                }
              }
            }
          },
          "400": {
            "description": "Empty name",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "No custom preset with that id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Could not persist the catalog",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "display"
        ],
        "summary": "Delete a custom preset",
        "description": "Removes it from the catalog. The active policy is untouched — if this preset was the one applied,\nthe running behavior stays exactly as it was (the catalog and `display-settings.json` are decoupled).",
        "operationId": "deleteCustomPreset",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The custom preset id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Preset deleted"
          },
          "401": {
            "description": "Missing or invalid bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "No custom preset with that id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Could not persist the catalog",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/display/release": {
      "post": {
        "tags": [
@@ -2220,6 +2451,52 @@
          }
        }
      },
      "CustomPreset": {
        "type": "object",
        "description": "A user-defined named preset: a saved bundle of the six display-behavior axes (exactly what a\nbuilt-in [`Preset`] expands to) plus the orthogonal game-session axis, that the operator names\nand applies from the console.\n\nUnlike the built-in [`Preset`]s (a closed enum), custom presets are **data** — a catalog stored in\n`<config>/display-presets.json`. Applying one writes a `Custom` [`DisplayPolicy`] carrying these\nfields (the console reuses `PUT /display/settings`), so [`DisplayPolicy::effective`] stays pure and\nthe built-in set is never touched. The catalog is decoupled from the active `display-settings.json`:\nediting or deleting a preset never mutates the running policy (re-apply to adopt a change).",
        "required": [
          "id",
          "name",
          "fields"
        ],
        "properties": {
          "fields": {
            "$ref": "#/components/schemas/EffectivePolicy",
            "description": "The six display-behavior axes this preset applies (the same shape a built-in preset expands to)."
          },
          "game_session": {
            "$ref": "#/components/schemas/GameSession",
            "description": "The game-session routing this preset applies (orthogonal to the six axes; see [`GameSession`]).\nA custom preset captures the operator's *full* setup, so — unlike a built-in preset — applying\none does set this axis."
          },
          "id": {
            "type": "string",
            "description": "Host-assigned, stable for the life of the entry (the `{id}` in the CRUD path)."
          },
          "name": {
            "type": "string",
            "description": "User-facing name shown on the preset card; editable."
          }
        }
      },
      "CustomPresetInput": {
        "type": "object",
        "description": "Request body to create or replace a custom preset (no `id` — the host owns it).",
        "required": [
          "name",
          "fields"
        ],
        "properties": {
          "fields": {
            "$ref": "#/components/schemas/EffectivePolicy"
          },
          "game_session": {
            "$ref": "#/components/schemas/GameSession"
          },
          "name": {
            "type": "string"
          }
        }
      },
      "DisplayLayoutRequest": {
        "type": "object",
        "description": "Request body for `setDisplayLayout`: per-identity-slot desktop offsets, keyed by the identity-slot\nid as a string (the same id `/display/state` reports as `identity_slot`).",
@@ -2240,6 +2517,10 @@
        "type": "object",
        "description": "The user-facing display-management policy — what `display-settings.json` holds and what the mgmt\nAPI GETs/PUTs. When [`preset`](Self::preset) is not [`Preset::Custom`] the explicit fields are\nignored (the console writes one or the other); [`effective`](Self::effective) resolves both to a\nsingle [`EffectivePolicy`].",
        "properties": {
          "game_session": {
            "$ref": "#/components/schemas/GameSession",
            "description": "How a game-launching session is served (`design/gamemode-and-dedicated-sessions.md` §5.2).\nOrthogonal to `preset`/lifecycle — preserved across preset changes; `#[serde(default)]` = `Auto`\nso existing `display-settings.json` files are untouched."
          },
          "identity": {
            "$ref": "#/components/schemas/Identity"
          },
@@ -2280,6 +2561,7 @@
          "configured",
          "effective",
          "presets",
          "custom_presets",
          "enforced"
        ],
        "properties": {
@@ -2287,6 +2569,13 @@
            "type": "boolean",
            "description": "True once a `display-settings.json` exists (the console has configured this host)."
          },
          "custom_presets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomPreset"
            },
            "description": "The operator's saved custom presets (`display-presets.json`) — named field-bundles rendered\nalongside the built-ins. Managed via `POST/PUT/DELETE /display/presets`; applied by writing a\n`Custom` policy carrying the preset's fields."
          },
          "effective": {
            "$ref": "#/components/schemas/EffectivePolicy",
            "description": "The effective (preset-expanded) policy currently in force."
@@ -2399,6 +2688,14 @@
          }
        }
      },
      "GameSession": {
        "type": "string",
        "description": "How a session that **launches a game** (a library id on the Hello / apps.json / Decky pin) is\nserved (`design/gamemode-and-dedicated-sessions.md` §5.2). Orthogonal to the preset/lifecycle axes\n— a top-level [`DisplayPolicy`] field, NOT part of [`EffectivePolicy`], so a preset never clobbers\nit. Linux-only in effect (a launching Windows session opens into the one desktop).",
        "enum": [
          "auto",
          "dedicated"
        ]
      },
      "GpuState": {
        "type": "object",
        "description": "Full GPU-selection state for the console: inventory, the persisted preference, what the next\nsession will use, and what is in use right now.",
@@ -27,6 +27,8 @@ RUN dnf -y install \
      mesa-libGL-devel mesa-libgbm-devel \
      # punktfunk-client link deps (GTK4 shell + SDL3 gamepads)
      gtk4-devel libadwaita-devel SDL3-devel \
      # pf-ffvk bindgen over libavutil/hwcontext_vulkan.h needs <vulkan/vulkan.h>
      vulkan-headers \
  && dnf clean all
 # bun — both the BUILD tool and the RUNTIME for the punktfunk-web console (`bun run build` -> the
@@ -22,6 +22,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
    libgl-dev libegl-dev libgbm-dev \
    # punktfunk-client-linux (GTK4/libadwaita shell, SDL3 gamepads)
    libgtk-4-dev libadwaita-1-dev libsdl3-dev \
    # pf-ffvk (bindgen over libavutil/hwcontext_vulkan.h needs <vulkan/vulkan.h>)
    libvulkan-dev \
    && rm -rf /var/lib/apt/lists/*
 # bun — builds the punktfunk-web console in deb.yml (which runs the web build in THIS image).
@@ -13,6 +13,12 @@
         reception needs it (also an OEM Wi-Fi power-save hedge). -->
    <uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <!-- WifiLock.acquire() ENFORCES this (a normal permission, granted at install). Without it the
         stream's Wi-Fi locks throw SecurityException and power save stays on: downlink delivery
         clumps at beacon intervals — hundreds of ms of latency mush + periodic whole-frame loss.
         Its absence went unnoticed for weeks because the acquire was wrapped in a silent
         runCatching (now logged). -->
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <!-- Enforced from Android 17 (SDK 37) for ALL local-network traffic incl. the QUIC socket.
         Harmless to declare on earlier releases. -->
    <uses-permission android:name="android.permission.ACCESS_LOCAL_NETWORK" />
@@ -43,6 +49,14 @@
        android:supportsRtl="true"
        android:theme="@style/Theme.PunktfunkAndroid">
        <!-- Game Mode config (Android 13+): declare we support Performance mode and opt OUT of the
             OEM interventions that would fight the negotiated stream — resolution downscaling and
             FPS overrides. A game-streaming client renders exactly the host's mode; a platform
             downscale/FPS-cap corrupts that. Ignored below API 33. -->
        <meta-data
            android:name="android.game_mode_config"
            android:resource="@xml/game_mode_config" />
        <activity
            android:name=".MainActivity"
            android:exported="true"
@@ -208,6 +208,8 @@ fun GamepadShell(
            GamepadScreen.Library -> libraryHost?.let { host ->
                LibraryScreen(
                    host = host,
                    settings = settings,
                    onLaunched = onConnected,
                    onBack = { screen = GamepadScreen.Home; libraryHost = null },
                    navActive = s == screen,
                )
@@ -63,9 +63,6 @@ import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
 /** Handshake budget for a normal connect (the prior hardcoded value, now passed explicitly). */
 private const val CONNECT_TIMEOUT_MS = 10_000
 /**
 * Handshake budget for the no-PIN "request access" connect. Must exceed the host's approval-park
 * window (~180 s) so a slow operator approval still lands on this same parked connection rather than
@@ -181,25 +178,10 @@ fun ConnectScreen(
    // it survives a DHCP address change; else by address:port). Mirrors the Apple client.
    val discoveredUnsaved = discovered.filter { dh -> savedHosts.none { it.matches(dh) } }
-    // The one place the full nativeConnect is issued (shared by the normal connect and the
+    // Issue the native connect (shared by the normal connect and the request-access path). A plain
-    // request-access path), including the HDR/gamepad derivation both need.
+    // desktop connect (no library launch) — the library launcher calls [connectToHost] with an id.
-    suspend fun connectNative(id: ClientIdentity, targetHost: String, targetPort: Int, pinHex: String, timeoutMs: Int): Long {
+    suspend fun connectNative(id: ClientIdentity, targetHost: String, targetPort: Int, pinHex: String, timeoutMs: Int): Long =
-        // Advertise HDR only when the user enabled it AND this device's display can present it
+        connectToHost(context, settings, id, targetHost, targetPort, pinHex, launch = null, timeoutMs = timeoutMs)
        // (else the host sends a proper SDR stream rather than PQ the panel would mis-tone-map).
        val hdrEnabled = settings.hdrEnabled && displaySupportsHdr(context)
        // "Automatic" resolves to a concrete pad type from the connected controller's VID/PID
        // (Android exposes no controller-type enum) — parity with the Linux/Apple clients. An
        // explicit choice is passed through unchanged.
        val gamepadPref = Gamepad.resolvePref(settings.gamepad)
        return withContext(Dispatchers.IO) {
            NativeBridge.nativeConnect(
                targetHost, targetPort, w, h, hz,
                id.certPem, id.privateKeyPem, pinHex,
                settings.bitrateKbps, settings.compositor, gamepadPref,
                hdrEnabled, settings.audioChannels, settings.preferredCodec(), timeoutMs,
            )
        }
    }
    // The actual dial (identity already ready). On a TOFU connect (pinHex null), pin the fingerprint
    // the host presented (as an unpaired known host) so the next connect goes straight through and it
@@ -230,11 +212,12 @@ fun ConnectScreen(
        }
    }
-    // Wake-aware connect. If the target is a saved host with a learned MAC that ISN'T currently
+    // Wake-aware connect. If auto-wake is on (Settings.autoWakeEnabled) and the target is a saved
-    // advertising (asleep/off), wake it and WAIT for it to reappear on mDNS (WakeController shows the
+    // host with a learned MAC that ISN'T currently advertising (asleep/off, or just missing from
-    // "Waking…" overlay) before dialing — discovery stays running meanwhile so we can see it come
+    // mDNS), wake it and WAIT for it to reappear on mDNS (WakeController shows the "Waking…" overlay)
-    // back. A fire-and-forget packet + the connect timeout wasn't enough for a cold boot. Otherwise
+    // before dialing — discovery stays running meanwhile so we can see it come back. A fire-and-forget
-    // dial straight through.
+    // packet + the connect timeout wasn't enough for a cold boot. Otherwise (auto-wake off, no MAC, or
    // already seen live) dial straight through.
    fun doConnect(targetHost: String, targetPort: Int, name: String, pinHex: String?) {
        if (identity == null) {
            status = "Identity not ready yet — try again in a moment"
@@ -248,7 +231,7 @@ fun ConnectScreen(
        fun liveAdvert(): DiscoveredHost? =
            if (kh != null) discovered.firstOrNull { kh.matches(it) }
            else discovered.firstOrNull { it.host == targetHost && it.port == targetPort }
-        if (macs.isNotEmpty() && liveAdvert() == null) {
+        if (settings.autoWakeEnabled && macs.isNotEmpty() && liveAdvert() == null) {
            waker.start(
                hostName = name,
                connectsAfter = true,
@@ -2,7 +2,8 @@ package io.unom.punktfunk
 import android.content.res.Configuration
 import androidx.activity.compose.BackHandler
-import androidx.compose.animation.core.animateFloatAsState
+import androidx.compose.animation.animateColorAsState
 import androidx.compose.animation.core.tween
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
 import androidx.compose.foundation.clickable
@@ -361,15 +362,15 @@ private fun rowCols(row: Int): Int = if (row < KB_ACTIONS_ROW) KB_CHAR_ROWS[row]
@Composable
 private fun FieldRow(f: Field, focused: Boolean, editing: Boolean, onClick: () -> Unit) {
-    val scale by animateFloatAsState(if (focused || editing) 1f else 0.98f, label = "fieldScale")
+    val visuals = animateConsoleFocus(active = focused || editing, editing = editing)
    val shape = RoundedCornerShape(14.dp)
    Row(
        modifier = Modifier
            .fillMaxWidth()
-            .graphicsLayer { scaleX = scale; scaleY = scale }
+            .graphicsLayer { scaleX = visuals.scale; scaleY = visuals.scale }
            .clip(shape)
-            .background(if (focused || editing) Color(0x336656F2) else Color(0x14FFFFFF))
+            .background(visuals.background)
-            .border(1.dp, if (editing) Color(0xB38678F5) else Color.White.copy(alpha = if (focused) 0.28f else 0.06f), shape)
+            .border(1.dp, visuals.border, shape)
            .clickable(interactionSource = remember { MutableInteractionSource() }, indication = null, onClick = onClick)
            .padding(horizontal = 16.dp, vertical = 14.dp),
        verticalAlignment = Alignment.CenterVertically,
@@ -389,15 +390,20 @@ private fun FieldRow(f: Field, focused: Boolean, editing: Boolean, onClick: () -
@Composable
 private fun AddActionRow(label: String, enabled: Boolean, focused: Boolean, onClick: () -> Unit) {
-    val scale by animateFloatAsState(if (focused) 1f else 0.98f, label = "addScale")
+    val visuals = animateConsoleFocus(active = focused)
    val shape = RoundedCornerShape(14.dp)
    val labelColor by animateColorAsState(
        if (enabled) Color(0xFF8678F5) else Color.White.copy(alpha = 0.35f),
        tween(160),
        label = "addLabel",
    )
    Box(
        modifier = Modifier
            .fillMaxWidth()
-            .graphicsLayer { scaleX = scale; scaleY = scale }
+            .graphicsLayer { scaleX = visuals.scale; scaleY = visuals.scale }
            .clip(shape)
-            .background(if (focused) Color(0x336656F2) else Color(0x14FFFFFF))
+            .background(visuals.background)
-            .border(1.dp, Color.White.copy(alpha = if (focused) 0.28f else 0.06f), shape)
+            .border(1.dp, visuals.border, shape)
            .clickable(interactionSource = remember { MutableInteractionSource() }, indication = null, onClick = onClick)
            .padding(vertical = 14.dp),
        contentAlignment = Alignment.Center,
@@ -406,7 +412,7 @@ private fun AddActionRow(label: String, enabled: Boolean, focused: Boolean, onCl
            label,
            style = MaterialTheme.typography.bodyLarge,
            fontWeight = FontWeight.Bold,
-            color = if (enabled) Color(0xFF8678F5) else Color.White.copy(alpha = 0.35f),
+            color = labelColor,
        )
    }
 }
@@ -448,11 +454,19 @@ private fun KeyboardGrid(
@Composable
 private fun Keycap(label: String, focused: Boolean, compact: Boolean, modifier: Modifier = Modifier, onClick: () -> Unit) {
    // Fast tweens: the keyboard cursor hops many keys per second under hold-to-repeat, so the
    // trailing key must have faded before the cursor is two keys away — quick, but no longer a snap.
    val bg by animateColorAsState(
        if (focused) Color(0xFF8678F5) else Color(0x14FFFFFF),
        tween(90),
        label = "keyBg",
    )
    val fg by animateColorAsState(if (focused) Color.Black else Color.White, tween(90), label = "keyFg")
    Box(
        modifier = modifier
            .height(if (compact) 34.dp else 44.dp)
            .clip(RoundedCornerShape(9.dp))
-            .background(if (focused) Color(0xFF8678F5) else Color(0x14FFFFFF))
+            .background(bg)
            .clickable(interactionSource = remember { MutableInteractionSource() }, indication = null, onClick = onClick),
        contentAlignment = Alignment.Center,
    ) {
@@ -460,7 +474,7 @@ private fun Keycap(label: String, focused: Boolean, compact: Boolean, modifier:
            label,
            style = MaterialTheme.typography.bodyLarge,
            fontWeight = FontWeight.Medium,
-            color = if (focused) Color.Black else Color.White,
+            color = fg,
            textAlign = TextAlign.Center,
        )
    }
@@ -1,10 +1,14 @@
 package io.unom.punktfunk
 import androidx.compose.animation.animateColorAsState
 import androidx.compose.animation.core.LinearEasing
 import androidx.compose.animation.core.RepeatMode
 import androidx.compose.animation.core.Spring
 import androidx.compose.animation.core.animateFloat
 import androidx.compose.animation.core.animateFloatAsState
 import androidx.compose.animation.core.infiniteRepeatable
 import androidx.compose.animation.core.rememberInfiniteTransition
 import androidx.compose.animation.core.spring
 import androidx.compose.animation.core.tween
 import androidx.compose.foundation.Canvas
 import androidx.compose.foundation.background
@@ -15,6 +19,7 @@ import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.PaddingValues
 import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.Spacer
 import androidx.compose.foundation.layout.offset
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
 import androidx.compose.foundation.layout.width
@@ -31,20 +36,28 @@ import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.clip
 import androidx.compose.ui.geometry.Offset
 import androidx.compose.ui.geometry.Size
 import androidx.compose.ui.graphics.BlendMode
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.graphics.Brush
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.graphics.Path
 import androidx.compose.ui.graphics.StrokeCap
 import androidx.compose.ui.graphics.StrokeJoin
 import androidx.compose.ui.graphics.drawscope.Stroke
 import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.text.style.TextAlign
 import androidx.compose.ui.text.style.TextOverflow
 import androidx.compose.ui.unit.IntOffset
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.unit.sp
 import dev.chrisbanes.haze.HazeState
 import dev.chrisbanes.haze.hazeEffect
 import io.unom.punktfunk.kit.Gamepad
 import kotlin.math.PI
 import kotlin.math.cos
 import kotlin.math.max
 import kotlin.math.roundToInt
 import kotlin.math.sin
 // The console chrome shared by the gamepad-driven screens — the Android mirror of the Apple client's
@@ -189,9 +202,12 @@ fun ConsoleHeader(title: String, modifier: Modifier = Modifier, horizontalInset:
 }
 /**
- * One glyph + label cell of a hint bar. [glyph] is the face letter; [color] its Xbox-convention hue.
+ * One glyph + label cell of a hint bar. [glyph] is the SEMANTIC face letter (the Android
- * [onClick], when set, makes the cell tappable — a TOUCH escape hatch so a user without a working
+ * `KEYCODE_BUTTON_*` name — 'A' = confirm/south); [color] its Xbox-convention hue. How the pair is
- * controller can still drive the console UI (and reach Settings to switch it off).
+ * actually DRAWN is the hint bar's decision, per the driving controller's [Gamepad.PadStyle] — a
 * DualSense renders 'A' as the ✕ shape, a Switch pad as a monochrome letter. [onClick], when set,
 * makes the cell tappable — a TOUCH escape hatch so a user without a working controller can still
 * drive the console UI (and reach Settings to switch it off).
 */
 class GamepadHint(
    val glyph: Char,
@@ -201,11 +217,16 @@ class GamepadHint(
    // Render as the D-pad-centre "select" button (a ring) instead of a lettered face-button disc —
    // for a TV remote, which has no A/B/X/Y.
    val select: Boolean = false,
-    // Render as the gamepad Select/View button (a small capsule).
+    // Render as the pad's physical Select/View/Create/− button (per PadStyle) — the button that
    // delivers KEYCODE_BUTTON_SELECT.
    val viewButton: Boolean = false,
 )
-/** Xbox-convention face-button colours, so the glyphs read at a glance across the room. */
+/**
 * Xbox-convention face-button colours, so the glyphs read at a glance across the room. These are
 * the DEFAULT (Xbox/generic) rendering; the hint bar swaps in PlayStation shapes or Nintendo
 * monochrome per the driving pad's [Gamepad.PadStyle] at draw time.
 */
 object PadGlyph {
    val A = Color(0xFF6BBE45)
    val B = Color(0xFFD14B4B)
@@ -216,6 +237,87 @@ object PadGlyph {
    )
 }
 /** The dark button-face fill shared by the PlayStation / Nintendo / select-button badges. */
 internal val PadButtonFace = Color(0xFF2A2740)
 /** The animated focus visuals of one console row/field/button — see [animateConsoleFocus]. */
 class ConsoleFocusVisuals(val scale: Float, val background: Color, val border: Color)
 /**
 * The focus visuals every console form element shares (settings rows, add-host fields, action
 * rows), ANIMATED: the background/border cross-fade instead of snapping between the focused and
 * resting looks, and the scale pops on a soft spring. [editing] draws the brighter violet border
 * of a field actively receiving keyboard input.
 */
@Composable
 fun animateConsoleFocus(active: Boolean, editing: Boolean = false): ConsoleFocusVisuals {
    val scale by animateFloatAsState(
        targetValue = if (active) 1f else 0.98f,
        animationSpec = spring(dampingRatio = 0.7f, stiffness = Spring.StiffnessMediumLow),
        label = "consoleScale",
    )
    val background by animateColorAsState(
        if (active) Color(0x336656F2) else Color(0x14FFFFFF),
        tween(160),
        label = "consoleBg",
    )
    val border by animateColorAsState(
        when {
            editing -> Color(0xB38678F5)
            active -> Color.White.copy(alpha = 0.28f)
            else -> Color.White.copy(alpha = 0.06f)
        },
        tween(160),
        label = "consoleBorder",
    )
    return ConsoleFocusVisuals(scale, background, border)
 }
 /**
 * The console-styled switch a toggle row renders in place of an "On"/"Off" value: a brand-violet
 * track that tints as it engages while the knob slides across on a spring — the state change reads
 * from across the room, and the motion confirms the press.
 */
@Composable
 fun ConsoleSwitch(on: Boolean, focused: Boolean, modifier: Modifier = Modifier) {
    val travel by animateFloatAsState(
        targetValue = if (on) 1f else 0f,
        animationSpec = spring(dampingRatio = 0.8f, stiffness = 600f),
        label = "switchKnob",
    )
    val track by animateColorAsState(
        if (on) Color(0xFF6656F2) else Color(0x26FFFFFF),
        tween(200),
        label = "switchTrack",
    )
    val outline by animateColorAsState(
        Color.White.copy(alpha = if (focused) 0.45f else 0.15f),
        tween(160),
        label = "switchOutline",
    )
    val trackW = 44.dp
    val trackH = 24.dp
    val pad = 3.dp
    val knob = trackH - pad * 2
    Box(
        modifier
            .size(trackW, trackH)
            .clip(RoundedCornerShape(50))
            .background(track)
            .border(1.dp, outline, RoundedCornerShape(50)),
        contentAlignment = Alignment.CenterStart,
    ) {
        Box(
            Modifier
                .padding(horizontal = pad)
                .offset { IntOffset(((trackW - knob - pad * 2).toPx() * travel).roundToInt(), 0) }
                .size(knob)
                .clip(CircleShape)
                .background(Color.White),
        )
    }
 }
 /** A round face-button badge: a coloured disc with the button letter, like a controller's face. */
@Composable
 fun GamepadButtonGlyph(glyph: Char, color: Color, size: androidx.compose.ui.unit.Dp = 26.dp) {
@@ -253,16 +355,94 @@ private fun BackGlyph(size: androidx.compose.ui.unit.Dp = 26.dp) {
    GamepadButtonGlyph('↩', PadGlyph.B, size)
 }
-/** The gamepad "Select / View" button — a small capsule outline, matching its physical shape. */
+/**
 * A PlayStation face button: the dark button face with the coloured shape outline Sony prints on it.
 * Keyed by the SEMANTIC letter (Android keycode name): A = ✕ cross, B = ○ circle, X = □ square,
 * Y = △ triangle — exactly how a Sony pad's buttons map to `KEYCODE_BUTTON_*`, in the classic
 * DualShock colours.
 */
@Composable
-private fun ViewButtonGlyph(size: androidx.compose.ui.unit.Dp = 26.dp) {
+internal fun PsFaceGlyph(glyph: Char, size: androidx.compose.ui.unit.Dp = 26.dp) {
-    Box(Modifier.size(size), contentAlignment = Alignment.Center) {
+    val color = when (glyph) {
        'A' -> Color(0xFF7C9CE8) // cross — light blue
        'B' -> Color(0xFFE0736F) // circle — red
        'X' -> Color(0xFFD48FC7) // square — pink
        else -> Color(0xFF5FBFA5) // triangle — green
    }
    Box(
-            Modifier
+        Modifier.size(size).clip(CircleShape).background(PadButtonFace),
-                .size(width = size * 0.74f, height = size * 0.46f)
+        contentAlignment = Alignment.Center,
-                .clip(RoundedCornerShape(50))
+    ) {
-                .border(1.6.dp, Color.White.copy(alpha = 0.85f), RoundedCornerShape(50)),
+        Canvas(Modifier.size(size * 0.46f)) {
            val w = this.size.minDimension
            val stroke = Stroke(width = w * 0.17f, cap = StrokeCap.Round, join = StrokeJoin.Round)
            when (glyph) {
                'A' -> { // ✕ — the two diagonals
                    drawLine(color, Offset(0f, 0f), Offset(w, w), stroke.width, StrokeCap.Round)
                    drawLine(color, Offset(w, 0f), Offset(0f, w), stroke.width, StrokeCap.Round)
                }
                'B' -> drawCircle(color, radius = (w - stroke.width) / 2f, style = stroke)
                'X' -> drawRect(
                    color,
                    topLeft = Offset(stroke.width / 2f, stroke.width / 2f),
                    size = Size(w - stroke.width, w - stroke.width),
                    style = stroke,
                )
                else -> { // △
                    val p = Path().apply {
                        moveTo(w / 2f, stroke.width / 2f)
                        lineTo(w - stroke.width / 2f, w - stroke.width / 2f)
                        lineTo(stroke.width / 2f, w - stroke.width / 2f)
                        close()
                    }
                    drawPath(p, color, style = stroke)
                }
            }
        }
    }
 }
 /**
 * The pad's physical Select-family button — the one that delivers `KEYCODE_BUTTON_SELECT` and opens
 * Options — drawn per [Gamepad.PadStyle] as a badge with the button's real face: Xbox View (two
 * overlapping windows), PlayStation Create/Share (a slim capsule), Nintendo − (minus). The generic
 * fallback wears the capsule too (the near-universal select shape).
 */
@Composable
 internal fun SelectButtonGlyph(style: Gamepad.PadStyle, size: androidx.compose.ui.unit.Dp = 26.dp) {
    Box(
        Modifier.size(size).clip(CircleShape).background(PadButtonFace),
        contentAlignment = Alignment.Center,
    ) {
        when (style) {
            Gamepad.PadStyle.XBOX -> Box(Modifier.size(size * 0.50f)) {
                // The View icon: two overlapping outlined windows; the front one is filled with the
                // button face so it visibly occludes the back one.
                val corner = RoundedCornerShape(2.dp)
                Box(
                    Modifier.size(size * 0.32f).align(Alignment.TopEnd)
                        .border(1.4.dp, Color.White.copy(alpha = 0.9f), corner),
                )
                Box(
                    Modifier.size(size * 0.32f).align(Alignment.BottomStart)
                        .clip(corner).background(PadButtonFace)
                        .border(1.4.dp, Color.White.copy(alpha = 0.9f), corner),
                )
            }
            Gamepad.PadStyle.NINTENDO -> Text(
                "−",
                color = Color.White,
                fontWeight = FontWeight.Bold,
                fontSize = (size.value * 0.62f).sp,
                textAlign = TextAlign.Center,
            )
            else -> Box(
                Modifier
                    .size(width = size * 0.58f, height = size * 0.30f)
                    .clip(RoundedCornerShape(50))
                    .border(1.6.dp, Color.White.copy(alpha = 0.9f), RoundedCornerShape(50)),
            )
        }
    }
 }
@@ -274,8 +454,12 @@ private fun ViewButtonGlyph(size: androidx.compose.ui.unit.Dp = 26.dp) {
 fun GamepadHintBar(hints: List<GamepadHint>, modifier: Modifier = Modifier, hazeState: HazeState? = null) {
    // On a TV D-pad remote (no A/B/X/Y), auto-swap the two universal pad glyphs every screen uses:
    // A (confirm) → the select ring, B (back/cancel) → a back glyph. Screen-specific glyphs like the
-    // home's Up/Down handle themselves. Defaults to the gamepad look off an Activity (preview/tests).
+    // home's Up/Down handle themselves. A real pad instead picks its glyph FAMILY (Xbox letters /
-    val padIsGamepad = (LocalContext.current as? MainActivity)?.lastPadIsGamepad ?: true
+    // PlayStation shapes / Nintendo monochrome) from the controller that last drove the UI.
    // Defaults to the generic gamepad look off an Activity (preview/tests).
    val activity = LocalContext.current as? MainActivity
    val padIsGamepad = activity?.lastPadIsGamepad ?: true
    val padStyle = activity?.lastPadStyle ?: Gamepad.PadStyle.GENERIC
    val shape = RoundedCornerShape(50)
    // With a haze source, blur the content behind the pill (real backdrop blur, API 31+; a translucent
    // scrim below) + a light tint; otherwise fall back to a solid frosted fill.
@@ -300,9 +484,13 @@ fun GamepadHintBar(hints: List<GamepadHint>, modifier: Modifier = Modifier, haze
            }
            Row(modifier = cell, verticalAlignment = Alignment.CenterVertically) {
                when {
-                    h.viewButton -> ViewButtonGlyph()
+                    h.viewButton -> SelectButtonGlyph(padStyle)
                    h.select || (!padIsGamepad && h.glyph == 'A') -> SelectGlyph()
                    !padIsGamepad && h.glyph == 'B' -> BackGlyph()
                    padStyle == Gamepad.PadStyle.PLAYSTATION && h.glyph in "ABXY" ->
                        PsFaceGlyph(h.glyph)
                    padStyle == Gamepad.PadStyle.NINTENDO && h.glyph in "ABXY" ->
                        GamepadButtonGlyph(h.glyph, PadButtonFace)
                    else -> GamepadButtonGlyph(h.glyph, h.color)
                }
                Spacer(Modifier.width(6.dp))
@@ -2,7 +2,12 @@ package io.unom.punktfunk
 import android.os.Build
 import androidx.activity.compose.BackHandler
 import androidx.compose.animation.animateColorAsState
 import androidx.compose.animation.core.Spring
 import androidx.compose.animation.core.animateFloatAsState
 import androidx.compose.animation.core.spring
 import androidx.compose.animation.core.tween
 import androidx.compose.foundation.ExperimentalFoundationApi
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
 import androidx.compose.foundation.clickable
@@ -19,6 +24,8 @@ import androidx.compose.foundation.layout.heightIn
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
 import androidx.compose.foundation.layout.widthIn
 import androidx.compose.foundation.relocation.BringIntoViewRequester
 import androidx.compose.foundation.relocation.bringIntoViewRequester
 import androidx.compose.foundation.rememberScrollState
 import androidx.compose.foundation.shape.RoundedCornerShape
 import androidx.compose.foundation.verticalScroll
@@ -26,6 +33,7 @@ import androidx.compose.material3.CircularProgressIndicator
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableIntStateOf
 import androidx.compose.runtime.mutableStateListOf
@@ -90,8 +98,11 @@ fun GamepadDialog(
        },
        onActivate = { actions.getOrNull(focus)?.takeIf { it.enabled }?.onClick?.invoke() },
    )
-    // Cap the card to most of the screen and let the BODY scroll — in a short landscape window the
+    // Cap the card to most of the screen and let body + BUTTONS scroll together — in a short
-    // title + body + buttons would otherwise overflow and compress/clip the bottom button.
+    // landscape window a 5-action stack (host options) exceeds the card even with an empty body, and
    // a pinned actions column can only compress/clip its last button. Only the title stays pinned;
    // the focused button pulls itself into view (see DialogButton), so D-pad navigation always shows
    // the current action even when the stack scrolls.
    val maxCardHeight = (LocalConfiguration.current.screenHeightDp * 0.92f).dp
    Box(
        Modifier.fillMaxSize().background(Color.Black.copy(alpha = 0.62f)),
@@ -109,43 +120,66 @@ fun GamepadDialog(
            verticalArrangement = Arrangement.spacedBy(14.dp),
        ) {
            Text(title, style = MaterialTheme.typography.headlineSmall, fontWeight = FontWeight.Bold, color = Color.White)
            // The body scrolls; the title above and the buttons below stay pinned + always visible.
            Column(
                Modifier.weight(1f, fill = false).verticalScroll(rememberScrollState()),
                verticalArrangement = Arrangement.spacedBy(10.dp),
            ) {
                body()
            }
                Spacer(Modifier.size(4.dp))
                actions.forEachIndexed { i, a ->
                    DialogButton(a.label, focused = i == focus, primary = a.primary, enabled = a.enabled, onClick = a.onClick)
                }
            }
        }
    }
 }
@OptIn(ExperimentalFoundationApi::class)
@Composable
 private fun DialogButton(label: String, focused: Boolean, primary: Boolean, enabled: Boolean, onClick: () -> Unit) {
-    val scale by animateFloatAsState(if (focused) 1.02f else 1f, label = "btnScale")
+    val scale by animateFloatAsState(
        if (focused) 1.02f else 1f,
        spring(dampingRatio = 0.7f, stiffness = Spring.StiffnessMediumLow),
        label = "btnScale",
    )
    // The action stack lives inside the dialog's scroll region: when D-pad focus moves to a button
    // that's scrolled out of a short window, pull it into view (no-op when already visible).
    val intoView = remember { BringIntoViewRequester() }
    LaunchedEffect(focused) { if (focused) intoView.bringIntoView() }
    val shape = RoundedCornerShape(14.dp)
-    val bg = when {
+    // Focus sweeps up/down the stack — cross-fade the fills so it glides instead of snapping.
    val bg by animateColorAsState(
        when {
            focused -> Color(0xFF6656F2)
            primary -> Color(0x336656F2)
            else -> Color(0x14FFFFFF)
-    }
+        },
-    val fg = when {
+        tween(160),
        label = "btnBg",
    )
    val fg by animateColorAsState(
        when {
            !enabled -> Color.White.copy(alpha = 0.35f)
            focused -> Color.White
            primary -> Color(0xFF8678F5)
            else -> Color.White.copy(alpha = 0.85f)
-    }
+        },
        tween(160),
        label = "btnFg",
    )
    val borderColor by animateColorAsState(
        Color.White.copy(alpha = if (focused) 0.3f else 0.08f),
        tween(160),
        label = "btnBorder",
    )
    Box(
        modifier = Modifier
            .fillMaxWidth()
            .bringIntoViewRequester(intoView)
            .graphicsLayer { scaleX = scale; scaleY = scale }
            .clip(shape)
            .background(bg)
-            .border(1.dp, Color.White.copy(alpha = if (focused) 0.3f else 0.08f), shape)
+            .border(1.dp, borderColor, shape)
            .clickable(
                enabled = enabled,
                interactionSource = remember { MutableInteractionSource() },
@@ -2,7 +2,19 @@ package io.unom.punktfunk
 import android.content.res.Configuration
 import androidx.activity.compose.BackHandler
 import androidx.compose.animation.AnimatedContent
 import androidx.compose.animation.AnimatedVisibility
 import androidx.compose.animation.SizeTransform
 import androidx.compose.animation.animateColorAsState
 import androidx.compose.animation.core.animateFloatAsState
 import androidx.compose.animation.core.tween
 import androidx.compose.animation.expandVertically
 import androidx.compose.animation.fadeIn
 import androidx.compose.animation.fadeOut
 import androidx.compose.animation.shrinkVertically
 import androidx.compose.animation.slideInHorizontally
 import androidx.compose.animation.slideOutHorizontally
 import androidx.compose.animation.togetherWith
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
 import androidx.compose.foundation.clickable
@@ -57,6 +69,7 @@ private class GpRow(
    val detail: String,
    val adjust: (Int) -> Boolean, // left/right; returns whether the value actually changed
    val activate: () -> Unit,     // A → cycle forward (wrapping) / flip
    val toggled: Boolean? = null, // non-null = a toggle row, drawn as a ConsoleSwitch (not text)
 )
@Composable
@@ -72,6 +85,9 @@ fun GamepadSettingsScreen(
    val rows = buildSettingsRows(s, ::update)
    var focus by remember { mutableIntStateOf(0) }
    if (focus > rows.lastIndex) focus = rows.lastIndex
    // The direction the focused value last stepped (+1 forward / -1 back) — drives which way the
    // value text slides in its AnimatedContent, so the motion matches the button press.
    var adjustDir by remember { mutableIntStateOf(1) }
    val listState = rememberLazyListState()
    val landscape = LocalConfiguration.current.orientation == Configuration.ORIENTATION_LANDSCAPE
@@ -83,11 +99,11 @@ fun GamepadSettingsScreen(
            when (dir) {
                NavDir.UP -> if (focus > 0) focus--
                NavDir.DOWN -> if (focus < rows.lastIndex) focus++
-                NavDir.LEFT -> rows.getOrNull(focus)?.adjust(-1)
+                NavDir.LEFT -> { adjustDir = -1; rows.getOrNull(focus)?.adjust(-1) }
-                NavDir.RIGHT -> rows.getOrNull(focus)?.adjust(1)
+                NavDir.RIGHT -> { adjustDir = 1; rows.getOrNull(focus)?.adjust(1) }
            }
        },
-        onActivate = { rows.getOrNull(focus)?.activate() },
+        onActivate = { adjustDir = 1; rows.getOrNull(focus)?.activate() },
    )
    // Keep the focused row on screen, but only SCROLL when it's actually off-screen — so entering the
    // screen (focus on the first row) leaves the "Settings" heading visible instead of jumping past it.
@@ -121,8 +137,8 @@ fun GamepadSettingsScreen(
                ConsoleHeader("Settings", horizontalInset = false)
            }
            itemsIndexed(rows, key = { _, r -> r.id }) { index, row ->
-                SettingRowView(row, focused = index == focus, onClick = {
+                SettingRowView(row, focused = index == focus, adjustDir = adjustDir, onClick = {
-                    if (focus == index) row.activate() else focus = index
+                    if (focus == index) { adjustDir = 1; row.activate() } else focus = index
                })
            }
            }
@@ -150,9 +166,17 @@ fun GamepadSettingsScreen(
 }
@Composable
-private fun SettingRowView(row: GpRow, focused: Boolean, onClick: () -> Unit) {
+private fun SettingRowView(row: GpRow, focused: Boolean, adjustDir: Int, onClick: () -> Unit) {
-    val scale by animateFloatAsState(if (focused) 1f else 0.98f, label = "rowScale")
+    val visuals = animateConsoleFocus(active = focused)
    val shape = RoundedCornerShape(14.dp)
    // The chevrons keep their layout slot and only fade, so the value never jumps sideways when
    // focus arrives; the value colour cross-fades with them.
    val chevronAlpha by animateFloatAsState(if (focused) 0.6f else 0f, tween(160), label = "chevrons")
    val valueColor by animateColorAsState(
        Color.White.copy(alpha = if (focused) 1f else 0.6f),
        tween(160),
        label = "valueColor",
    )
    Column {
        if (row.header != null) {
            Text(
@@ -166,10 +190,10 @@ private fun SettingRowView(row: GpRow, focused: Boolean, onClick: () -> Unit) {
        Column(
            modifier = Modifier
                .fillMaxWidth()
-                .graphicsLayer { scaleX = scale; scaleY = scale }
+                .graphicsLayer { scaleX = visuals.scale; scaleY = visuals.scale }
                .clip(shape)
-                .background(if (focused) Color(0x336656F2) else Color(0x14FFFFFF))
+                .background(visuals.background)
-                .border(1.dp, Color.White.copy(alpha = if (focused) 0.28f else 0.06f), shape)
+                .border(1.dp, visuals.border, shape)
                .clickable(
                    interactionSource = remember { MutableInteractionSource() },
                    indication = null,
@@ -186,19 +210,41 @@ private fun SettingRowView(row: GpRow, focused: Boolean, onClick: () -> Unit) {
                    maxLines = 1,
                )
                Spacer(Modifier.weight(1f))
-                if (focused) Text("‹ ", color = Color.White.copy(alpha = 0.6f))
+                if (row.toggled != null) {
                    // A toggle is a switch, not text — the sliding knob + tinting track IS the value.
                    ConsoleSwitch(on = row.toggled, focused = focused)
                } else {
                    Text("‹ ", color = Color.White, modifier = Modifier.graphicsLayer { alpha = chevronAlpha })
                    // The value slides in the direction it was stepped and its width animates, so
                    // cycling a choice reads as motion through a list rather than a text swap.
                    AnimatedContent(
                        targetState = row.value,
                        transitionSpec = {
                            val dir = adjustDir
                            (slideInHorizontally(tween(180)) { w -> w / 2 * dir } + fadeIn(tween(180))) togetherWith
                                (slideOutHorizontally(tween(140)) { w -> -w / 2 * dir } + fadeOut(tween(100))) using
                                SizeTransform(clip = false)
                        },
                        label = "value",
                    ) { value ->
                        Text(
-                    row.value,
+                            value,
                            style = MaterialTheme.typography.bodyMedium,
-                    color = if (focused) Color.White else Color.White.copy(alpha = 0.6f),
+                            color = valueColor,
                            maxLines = 1,
                            overflow = TextOverflow.Ellipsis,
                        )
-                if (focused) Text(" ›", color = Color.White.copy(alpha = 0.6f))
+                    }
                    Text(" ›", color = Color.White, modifier = Modifier.graphicsLayer { alpha = chevronAlpha })
                }
            }
            // The focused row carries its own one-line description — no dedicated (space-eating)
-            // detail strip. It appears right where you're looking, and the row grows to fit.
+            // detail strip. It unfolds right where you're looking, and the row grows to fit.
-            if (focused && row.detail.isNotBlank()) {
+            AnimatedVisibility(
                visible = focused && row.detail.isNotBlank(),
                enter = fadeIn(tween(180, delayMillis = 60)) + expandVertically(tween(180)),
                exit = fadeOut(tween(90)) + shrinkVertically(tween(150)),
            ) {
                Text(
                    row.detail,
                    style = MaterialTheme.typography.bodySmall,
@@ -245,6 +291,7 @@ private fun buildSettingsRows(s: Settings, update: (Settings) -> Unit): List<GpR
        detail = detail,
        adjust = { delta -> val target = delta > 0; if (value != target) { write(target); true } else false },
        activate = { write(!value) },
        toggled = value,
    )
    return listOf(
@@ -278,6 +325,11 @@ private fun buildSettingsRows(s: Settings, update: (Settings) -> Unit): List<GpR
            "HDR10 — engages when the host sends HDR content and this display supports it.",
            s.hdrEnabled,
        ) { update(s.copy(hdrEnabled = it)) },
        toggle(
            "lowLatency", null, "Low-latency mode",
            "The fast pipeline (async decode + system tuning). On by default — turn off to fall back if the stream stutters or glitches.",
            s.lowLatencyMode,
        ) { update(s.copy(lowLatencyMode = it)) },
        choice(
            "audio", "Audio", "Audio channels", "The speaker layout requested from the host.",
@@ -304,6 +356,11 @@ private fun buildSettingsRows(s: Settings, update: (Settings) -> Unit): List<GpR
            "Browse a paired host's games with Y (experimental).",
            s.libraryEnabled,
        ) { update(s.copy(libraryEnabled = it)) },
        toggle(
            "autoWake", null, "Auto-wake on connect",
            "Wake a saved host with Wake-on-LAN when it isn't seen on the network, then connect.",
            s.autoWakeEnabled,
        ) { update(s.copy(autoWakeEnabled = it)) },
        toggle(
            "gamepadUI", null, "Controller-optimized UI",
            "Turn off to use the touch interface even with a controller connected.",
@@ -0,0 +1,48 @@
 package io.unom.punktfunk
 import android.content.Context
 import io.unom.punktfunk.kit.Gamepad
 import io.unom.punktfunk.kit.NativeBridge
 import io.unom.punktfunk.kit.security.ClientIdentity
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
 /** Handshake budget for a normal / library-launch connect (not the long request-access park). */
 const val CONNECT_TIMEOUT_MS = 10_000
 /**
 * The one place [NativeBridge.nativeConnect] is assembled — shared by [ConnectScreen] and the library
 * launcher ([LibraryScreen]). Derives the mode / HDR / gamepad settings the host needs from
 * [settings]. [pinHex] is the pinned fingerprint (empty ⇒ TOFU). [launch] is a store-qualified library
 * id (`steam:<appid>` / `custom:<id>`) to boot straight into a game, or `null` for the desktop.
 * Returns the session handle, or `0` on failure. Call off the main thread.
 */
 suspend fun connectToHost(
    context: Context,
    settings: Settings,
    identity: ClientIdentity,
    host: String,
    port: Int,
    pinHex: String,
    launch: String?,
    timeoutMs: Int = CONNECT_TIMEOUT_MS,
 ): Long {
    // Advertise HDR only when the user enabled it AND this device's display can present it (else the
    // host sends a proper SDR stream rather than PQ the panel would mis-tone-map).
    val (w, h, hz) = settings.effectiveMode(context)
    val hdrEnabled = settings.hdrEnabled && displaySupportsHdr(context)
    // "Automatic" resolves to a concrete pad type from the connected controller's VID/PID.
    val gamepadPref = Gamepad.resolvePref(settings.gamepad)
    return withContext(Dispatchers.IO) {
        // Transport-level half of "Low-latency mode (experimental)" (DSCP marking on the media
        // sockets) — must be applied before connect, since sockets are tagged at creation.
        NativeBridge.nativeSetLowLatencyMode(settings.lowLatencyMode)
        NativeBridge.nativeConnect(
            host, port, w, h, hz,
            identity.certPem, identity.privateKeyPem, pinHex,
            settings.bitrateKbps, settings.compositor, gamepadPref,
            hdrEnabled, settings.audioChannels, settings.preferredCodec(), timeoutMs,
            launch,
        )
    }
 }
@@ -1,8 +1,10 @@
 package io.unom.punktfunk
 import android.widget.Toast
 import androidx.activity.compose.BackHandler
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
 import androidx.compose.foundation.clickable
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.BoxWithConstraints
@@ -57,6 +59,7 @@ import io.unom.punktfunk.kit.library.GameEntry
 import io.unom.punktfunk.kit.library.LibraryClient
 import io.unom.punktfunk.kit.library.LibraryResult
 import io.unom.punktfunk.kit.library.mtlsHttpClient
 import io.unom.punktfunk.kit.security.ClientIdentity
 import io.unom.punktfunk.kit.security.IdentityStore
 import io.unom.punktfunk.kit.security.KnownHost
 import io.unom.punktfunk.kit.security.obtainIdentity
@@ -73,17 +76,27 @@ import kotlinx.coroutines.withContext
 private sealed class LibState {
    object Loading : LibState()
-    data class Ready(val games: List<GameEntry>, val loader: ImageLoader) : LibState()
+    // Carries the client identity so a launch can dial the host over the same pinned mTLS trust.
    data class Ready(val games: List<GameEntry>, val loader: ImageLoader, val identity: ClientIdentity) : LibState()
    data class Message(val text: String) : LibState() // unauthorized / empty / error
 }
@Composable
-fun LibraryScreen(host: KnownHost, onBack: () -> Unit, navActive: Boolean = true) {
+fun LibraryScreen(
    host: KnownHost,
    settings: Settings,
    onLaunched: (Long) -> Unit,
    onBack: () -> Unit,
    navActive: Boolean = true,
 ) {
    BackHandler(onBack = onBack)
    val context = LocalContext.current
    val scope = rememberCoroutineScope()
    val hazeState = remember { HazeState() }
    val landscape = LocalConfiguration.current.orientation == Configuration.ORIENTATION_LANDSCAPE
    var state by remember { mutableStateOf<LibState>(LibState.Loading) }
    // A launch (connect) in flight: shows an overlay + gates the pad so a second press can't dial twice.
    var launching by remember { mutableStateOf(false) }
    LaunchedEffect(host.address, host.port, host.fpHex) {
        state = LibState.Loading
@@ -101,7 +114,7 @@ fun LibraryScreen(host: KnownHost, onBack: () -> Unit, navActive: Boolean = true
                    LibState.Message("No games found on this host.")
                } else {
                    val client = mtlsHttpClient(id.certPem, id.privateKeyPem, host.address, host.fpHex)
-                    LibState.Ready(res.games, ImageLoader.Builder(context).okHttpClient(client).build())
+                    LibState.Ready(res.games, ImageLoader.Builder(context).okHttpClient(client).build(), id)
                }
                is LibraryResult.Unauthorized -> LibState.Message(res.message)
                is LibraryResult.Error -> LibState.Message(res.message)
@@ -118,11 +131,45 @@ fun LibraryScreen(host: KnownHost, onBack: () -> Unit, navActive: Boolean = true
                    when (val s = state) {
                        is LibState.Loading -> LoadingState()
                        is LibState.Message -> MessageState(s.text)
-                        is LibState.Ready -> Coverflow(s.games, s.loader, navActive)
+                        is LibState.Ready -> Coverflow(s.games, s.loader, navActive && !launching) { game ->
                            if (!launching) {
                                launching = true
                                scope.launch {
                                    // Dial the host over the same pinned mTLS trust, booting straight
                                    // into this title (the host resolves `launch` = its library id).
                                    val handle = connectToHost(
                                        context, settings, s.identity,
                                        host.address, host.port, host.fpHex, launch = game.id,
                                    )
                                    launching = false
                                    if (handle != 0L) onLaunched(handle)
                                    else Toast.makeText(
                                        context,
                                        "Launch failed — check the host and try again.",
                                        Toast.LENGTH_LONG,
                                    ).show()
                                }
                            }
                        }
                    }
                }
            }
        }
        // Launching overlay — the connect + host-side game boot takes a moment; block the pad while it runs.
        if (launching) {
            Box(
                Modifier.fillMaxSize().background(Color.Black.copy(alpha = 0.6f)),
                contentAlignment = Alignment.Center,
            ) {
                Column(
                    horizontalAlignment = Alignment.CenterHorizontally,
                    verticalArrangement = Arrangement.spacedBy(14.dp),
                ) {
                    CircularProgressIndicator(color = Color.White)
                    Text("Launching…", color = Color.White, style = MaterialTheme.typography.bodyLarge)
                }
            }
        }
        // Floating legend at the shared spot — same landscape-aware inset as every other console
        // screen (ignore the safe area in landscape, where the bottom edge isn't a tap target).
        Box(
@@ -130,7 +177,13 @@ fun LibraryScreen(host: KnownHost, onBack: () -> Unit, navActive: Boolean = true
                .then(if (landscape) Modifier else Modifier.systemBarsPadding())
                .padding(ConsoleLegendInset),
        ) {
-            GamepadHintBar(listOf(PadGlyph.hint('B', "Close", onClick = onBack)), hazeState = hazeState)
+            GamepadHintBar(
                buildList {
                    if (state is LibState.Ready) add(PadGlyph.hint('A', "Launch"))
                    add(PadGlyph.hint('B', "Close", onClick = onBack))
                },
                hazeState = hazeState,
            )
        }
    }
 }
@@ -155,7 +208,12 @@ private fun MessageState(text: String) {
 }
@Composable
-private fun Coverflow(games: List<GameEntry>, loader: ImageLoader, navActive: Boolean) {
+private fun Coverflow(
    games: List<GameEntry>,
    loader: ImageLoader,
    navActive: Boolean,
    onLaunch: (GameEntry) -> Unit,
 ) {
    BoxWithConstraints(Modifier.fillMaxSize()) {
        // Fit a 2:3 poster into the height the detail line leaves; clamp so it never dwarfs the screen.
        val coverHeight = (maxHeight * 0.72f).coerceAtMost(360.dp)
@@ -167,16 +225,15 @@ private fun Coverflow(games: List<GameEntry>, loader: ImageLoader, navActive: Bo
        LaunchedEffect(pagerState.settledPage) { navTarget = pagerState.settledPage }
        val current = games.getOrNull(navTarget)
-        // Controller nav: the pad drives the coverflow (it wasn't captured before). Left/right steps a
+        // Controller nav: the pad drives the coverflow. Left/right steps a coalesced target the pager
-        // coalesced target the pager chases; A is reserved for launch (browse-only for now); B closes
+        // chases; A launches the centred title; B closes via the screen's BackHandler.
        // via the screen's BackHandler.
        GamepadNavEffect(
            active = navActive && games.isNotEmpty(),
            onMove = { dir ->
                val t = (navTarget + dir).coerceIn(0, games.lastIndex)
                if (t != navTarget) { navTarget = t; scope.launch { pagerState.animateScrollToPage(t) } }
            },
-            onActivate = { /* launch a title — browse-only for now */ },
+            onActivate = { games.getOrNull(navTarget)?.let(onLaunch) },
        )
        Column(Modifier.fillMaxSize(), verticalArrangement = Arrangement.Center) {
@@ -198,6 +255,11 @@ private fun Coverflow(games: List<GameEntry>, loader: ImageLoader, navActive: Bo
                        .zIndex(-d) // centred cover on top, neighbours stacked behind
                        .width(coverWidth)
                        .height(coverHeight)
                        // Touch: tap the centred cover to launch it; tap a neighbour to bring it centre.
                        .clickable {
                            if (page == pagerState.currentPage) onLaunch(games[page])
                            else scope.launch { pagerState.animateScrollToPage(page) }
                        }
                        .graphicsLayer {
                            // Centre at full size; EVERY neighbour settles to one size, so an even pitch
                            // yields even VISUAL gaps. (A progressive shrink made the outer gaps grow —
@@ -51,8 +51,21 @@ class MainActivity : ComponentActivity() {
     * Whether the last console input came from a real gamepad (face buttons / stick) vs. a TV D-pad
     * remote (which has no A/B/X/Y). The console UI reads this to show glyphs the user recognises — pad
     * face buttons, or a select glyph + arrows for a remote. Compose observes it (a snapshot state).
     * Defaults to the remote glyphs on a TV (its D-pad remote is the typical first input, and often the
     * only one) and to gamepad glyphs everywhere else (the console UI on a phone/tablet only activates
     * via a real controller, so a TV-remote glyph would be a wrong first impression there) — set from
     * [onCreate] once a [Context] is available, then kept live by real input.
     */
-    var lastPadIsGamepad by mutableStateOf(false)
+    var lastPadIsGamepad by mutableStateOf(true)
        private set
    /**
     * The glyph family of the controller driving the console UI (Xbox letters / PlayStation shapes /
     * Nintendo monochrome) — seeded from the first connected pad, then kept live by real input the
     * same way [lastPadIsGamepad] is. Compose observes it (a snapshot state); the hint bar picks its
     * button glyphs from it so a DualSense user isn't shown Xbox lettering.
     */
    var lastPadStyle by mutableStateOf(Gamepad.PadStyle.GENERIC)
        private set
    /** The panel's highest-refresh display mode (0 = unknown/unsupported), resolved once at startup. */
@@ -60,6 +73,8 @@ class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        lastPadIsGamepad = !isTvDevice(this)
        lastPadStyle = Gamepad.styleFor(Gamepad.firstPad())
        resolveHighRefreshMode()
        setConsoleHighRefreshRate(true) // the console UI wants max refresh; streaming manages its own
        // Dark, transparent system bars regardless of the system theme — our UI is always dark, so
@@ -154,9 +169,11 @@ class MainActivity : ComponentActivity() {
            }
        } else {
            // Note which input the console UI is being driven by, so its glyphs match (a TV remote's
-            // D-pad is not from SOURCE_GAMEPAD; a pad's face buttons / D-pad are).
+            // D-pad is not from SOURCE_GAMEPAD; a pad's face buttons / D-pad are) — and, for a real
            // pad, WHICH pad family, so the glyphs wear its lettering/shapes.
            if (event.action == KeyEvent.ACTION_DOWN && isConsoleNavKey(event.keyCode)) {
                lastPadIsGamepad = event.isFromSource(InputDevice.SOURCE_GAMEPAD)
                if (lastPadIsGamepad) lastPadStyle = Gamepad.styleFor(event.device)
            }
            // The Controllers debug screen sees pad events before the navigation remap below.
            padKeyProbe?.let { if (it(event)) return true }
@@ -212,6 +229,7 @@ class MainActivity : ComponentActivity() {
                lastNavDir = dir
                if (dir != 0) {
                    lastPadIsGamepad = true // a stick/HAT push can only come from a real gamepad
                    lastPadStyle = Gamepad.styleFor(event.device)
                    super.dispatchKeyEvent(KeyEvent(KeyEvent.ACTION_DOWN, dir))
                    super.dispatchKeyEvent(KeyEvent(KeyEvent.ACTION_UP, dir))
                    return true
@@ -54,6 +54,28 @@ data class Settings(
     * client's `libraryEnabled`.
     */
    val libraryEnabled: Boolean = true,
    /**
     * "Low-latency mode" — the master switch over the latency pipeline: the async decode loop
     * (native; burst-feed + present-newest-per-vsync, the Apple client's discipline), decoder ranking
     * + per-SoC vendor keys, pipeline thread boosts + ADPF max-performance, game-tagged AAudio, DSCP
     * marking on the media sockets, HDMI ALLM, and the forced TV mode switch. (The Wi-Fi locks are NOT
     * part of this — both are always held while streaming; see StreamScreen.) On (default): the fast
     * pipeline. Off restores the original synchronous decode loop byte-for-byte, kept as a per-device
     * escape hatch. Promoted to default once the receive-side latency ratchet the overhaul interacted
     * badly with was fixed in the shared core — the pump now jumps to live on a standing backlog
     * instead of accumulating it (see `punktfunk-core` `FrameChannel`), so the async loop no longer
     * feeds a queue that only grows.
     */
    val lowLatencyMode: Boolean = true,
    /**
     * Wake-on-LAN a saved host before connecting when it isn't currently seen on mDNS. On (default):
     * a connect to a host with a learned MAC that isn't advertising sends a magic packet and waits
     * for it to reappear (see [WakeController]) before dialing. Off: always dial straight through,
     * skipping the mDNS-presence check entirely — for a host that's actually up but not visible on
     * mDNS (a flaky discovery path, a VLAN/subnet that blocks multicast, etc.), where auto-wake would
     * otherwise misfire and wait out its timeout despite the host already being reachable.
     */
    val autoWakeEnabled: Boolean = true,
 )
 /** [Settings.touchMode] values; persisted by name. */
@@ -82,6 +104,8 @@ class SettingsStore(context: Context) {
            ?: if (prefs.getBoolean(K_TRACKPAD, true)) TouchMode.TRACKPAD else TouchMode.POINTER,
        gamepadUiEnabled = prefs.getBoolean(K_GAMEPAD_UI, true),
        libraryEnabled = prefs.getBoolean(K_LIBRARY, true),
        lowLatencyMode = prefs.getBoolean(K_LOW_LATENCY, true),
        autoWakeEnabled = prefs.getBoolean(K_AUTO_WAKE, true),
    )
    fun save(s: Settings) {
@@ -100,6 +124,8 @@ class SettingsStore(context: Context) {
            .putString(K_TOUCH_MODE, s.touchMode.name)
            .putBoolean(K_GAMEPAD_UI, s.gamepadUiEnabled)
            .putBoolean(K_LIBRARY, s.libraryEnabled)
            .putBoolean(K_LOW_LATENCY, s.lowLatencyMode)
            .putBoolean(K_AUTO_WAKE, s.autoWakeEnabled)
            .apply()
    }
@@ -119,6 +145,19 @@ class SettingsStore(context: Context) {
        const val K_GAMEPAD_UI = "gamepad_ui_enabled"
        const val K_LIBRARY = "library_enabled"
        /**
         * Bumped AGAIN to restart every install at the new default (ON). History: the original
         * `"low_latency_mode"` shipped default-ON; `"low_latency_mode_experimental"` restarted
         * everyone at OFF after the overhaul regressed on some phones. That regression was the
         * receive-side latency ratchet the async loop fed (a standing queue that only grew) — now
         * fixed in the shared core (`punktfunk-core` `FrameChannel`: the pump jumps to live on a
         * standing backlog instead of accumulating it), so the fast pipeline is the default again. A
         * fresh key re-defaults every install — including ones persisted OFF under the old key — to
         * on; both stale keys are abandoned unread. The toggle stays as a per-device escape hatch.
         */
        const val K_LOW_LATENCY = "low_latency_mode_v2"
        const val K_AUTO_WAKE = "auto_wake_enabled"
        /** Legacy Boolean the enum replaced — read once as the migration default, never written. */
        const val K_TRACKPAD = "trackpad_mode"
    }
@@ -215,6 +254,10 @@ val BITRATE_OPTIONS = listOf(
    20_000 to "20 Mbps",
    50_000 to "50 Mbps",
    100_000 to "100 Mbps",
    150_000 to "150 Mbps",
    200_000 to "200 Mbps",
    300_000 to "300 Mbps",
    500_000 to "500 Mbps",
 )
 /** index = CompositorPref wire byte. */
@@ -324,6 +324,15 @@ private fun DisplaySettings(s: Settings, update: (Settings) -> Unit, context: an
            options = COMPOSITOR_OPTIONS.mapIndexed { i, lbl -> i to lbl },
            selected = s.compositor,
        ) { c -> update(s.copy(compositor = c)) }
        ToggleRow(
            title = "Low-latency mode",
            subtitle = "The fast pipeline (async decode, per-device decoder selection, HDMI game " +
                "mode). On by default — turn off to fall back to the plain decode path if the stream " +
                "stutters or glitches on this device.",
            checked = s.lowLatencyMode,
            onCheckedChange = { on -> update(s.copy(lowLatencyMode = on)) },
        )
    }
 }
@@ -386,6 +395,14 @@ private fun InterfaceSettings(s: Settings, update: (Settings) -> Unit) {
            checked = s.libraryEnabled,
            onCheckedChange = { on -> update(s.copy(libraryEnabled = on)) },
        )
        ToggleRow(
            title = "Auto-wake on connect",
            subtitle = "Send Wake-on-LAN and wait for a saved host to reappear on mDNS before " +
                "connecting. Turn off if a host that's already on isn't seen on mDNS, so connects " +
                "go straight through instead of waiting out the wake timeout.",
            checked = s.autoWakeEnabled,
            onCheckedChange = { on -> update(s.copy(autoWakeEnabled = on)) },
        )
        ToggleRow(
            title = "Stats overlay",
            subtitle = "Show FPS, throughput and latency while streaming (3-finger tap toggles it live)",
@@ -27,7 +27,7 @@ import kotlin.math.roundToInt
 * older layouts just omit those lines.
 */
@Composable
-internal fun StatsOverlay(s: DoubleArray, modifier: Modifier = Modifier) {
+internal fun StatsOverlay(s: DoubleArray, decoderLabel: String = "", modifier: Modifier = Modifier) {
    if (s.size < 10) return
    val w = s[6].toInt()
    val h = s[7].toInt()
@@ -46,6 +46,14 @@ internal fun StatsOverlay(s: DoubleArray, modifier: Modifier = Modifier) {
            fontFamily = FontFamily.Monospace,
            fontSize = 12.sp,
        )
        if (decoderLabel.isNotEmpty()) {
            Text(
                decoderLabel,
                color = Color(0xFFB0D0FF),
                fontFamily = FontFamily.Monospace,
                fontSize = 12.sp,
            )
        }
        videoFeedLine(s)?.let { feed ->
            Text(
                feed,
@@ -1,11 +1,16 @@
 package io.unom.punktfunk
 import android.Manifest
 import android.content.Context
 import android.content.pm.ActivityInfo
 import android.content.pm.PackageManager
 import android.net.wifi.WifiManager
 import android.os.Build
 import android.util.Log
 import android.view.SurfaceHolder
 import android.view.SurfaceView
 import android.view.WindowManager
 import android.widget.Toast
 import androidx.activity.compose.BackHandler
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.fillMaxSize
@@ -30,6 +35,7 @@ import androidx.core.view.WindowInsetsControllerCompat
 import io.unom.punktfunk.kit.Gamepad
 import io.unom.punktfunk.kit.GamepadFeedback
 import io.unom.punktfunk.kit.NativeBridge
 import io.unom.punktfunk.kit.VideoDecoders
 import java.util.concurrent.atomic.AtomicBoolean
 import kotlinx.coroutines.delay
@@ -55,29 +61,103 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
    // comes from Settings.
    val initialSettings = remember { SettingsStore(context).load() }
    var stats by remember { mutableStateOf<DoubleArray?>(null) }
    var decoderLabel by remember { mutableStateOf("") }
    var showStats by remember { mutableStateOf(initialSettings.statsHudEnabled) }
    // Touch model is fixed per session (re-keys the gesture handler below if it ever changes).
    val touchMode = initialSettings.touchMode
    // "Low-latency mode" master toggle, resolved once for the session. On (the default) enables the
    // fast pipeline — decoder ranking + vendor keys + async loop (native side), HDMI ALLM below,
    // game-tagged audio, and DSCP marking (applied earlier, at connect); off falls back to the
    // original synchronous decode pipeline as a per-device escape hatch.
    val lowLatencyMode = initialSettings.lowLatencyMode
    // TV form factor (leanback): the decoder actively switches the HDMI output mode to the stream
    // refresh; a phone/tablet gets the softer seamless frame-rate hint instead.
    val isTv = remember { context.packageManager.hasSystemFeature(PackageManager.FEATURE_LEANBACK) }
    LaunchedEffect(handle, showStats) {
        NativeBridge.nativeSetVideoStatsEnabled(handle, showStats)
        if (showStats) {
            while (true) {
                delay(1000)
                stats = NativeBridge.nativeVideoStats(handle)
                // The decoder is fixed for the session; fetch its label once it's resolved.
                if (decoderLabel.isEmpty()) decoderLabel = NativeBridge.nativeVideoDecoderLabel(handle)
            }
        } else {
            stats = null // drop the last snapshot so a re-show never flashes stale numbers
        }
    }
    // Host-gone watchdog. When the host suspends/sleeps (or crashes, or drops off the network) it
    // stops answering the QUIC keep-alive and the connection idle-times out (~8 s) — no more frames
    // arrive and the decoder would otherwise sit frozen on its last decoded frame until the user
    // manually backed out. Poll the native session-liveness flag (one atomic load, independent of the
    // stats HUD) and, the moment the session is dead, drop back to the menu so the user can
    // Wake-on-LAN the host instead of being stranded on a frozen picture. Mirrors the Apple client's
    // onSessionEnd → sessionEnded() → disconnect(). The 1 s cadence + the ~8 s idle timeout is a
    // deliberately generous window: the keep-alive holds a merely-quiet connection (a static desktop)
    // open, so this fires only on a genuinely dead peer, never a false positive. Keyed on `handle`, so
    // it stops the moment we navigate away (the handle is only freed later, in onDispose).
    LaunchedEffect(handle) {
        while (true) {
            delay(1000)
            if (NativeBridge.nativeSessionEnded(handle)) {
                Toast.makeText(
                    context,
                    "Connection lost — the host may be asleep. Wake it to reconnect.",
                    Toast.LENGTH_LONG,
                ).show()
                onDisconnect()
                return@LaunchedEffect
            }
        }
    }
    // One-shot teardown guard. Both the SurfaceView callback and DisposableEffect tear down on the
    // way out, but `nativeClose` frees the handle — so once it's closed, NO path may touch the handle
    // again (use-after-free → SIGSEGV: the consistent back-while-streaming crash). Both run on the
    // main thread, so a plain flag is race-free; AtomicBoolean just makes the intent explicit.
    val closed = remember { AtomicBoolean(false) }
    // Wi-Fi locks held for the stream's duration — BOTH of them, unconditionally (Moonlight does
    // the same). Without an effective lock, Wi-Fi power save batches downlink delivery into
    // beacon-interval clumps: hundreds of ms of latency mush, sawtoothing bitrate, and periodic
    // whole-frame loss when the AP's power-save buffer overflows (all observed live on a phone).
    //  - FULL_LOW_LATENCY (API 29+) is the only lock that actually disables power save on modern
    //    Android; it needs the app foreground + screen on, which a stream always is.
    //  - FULL_HIGH_PERF covers older releases — it is deprecated AND a documented no-op on recent
    //    Android, which is exactly why it can't be the only lock (a lesson learned: holding just
    //    HIGH_PERF left power save fully active on Android 13+).
    // acquire() ENFORCES the WAKE_LOCK permission (manifest) — and a failed acquire MUST be loud:
    // a silent runCatching hid the missing permission for weeks (dumpsys wifi showed
    // low_latency_active_time_ms=0 across every "locked" stream). Non-reference-counted: one
    // explicit acquire/release each.
    val wifiLocks = remember(handle) {
        val wm = context.applicationContext.getSystemService(Context.WIFI_SERVICE) as? WifiManager
            ?: return@remember emptyList<WifiManager.WifiLock>()
        buildList {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
                wm.createWifiLock(WifiManager.WIFI_MODE_FULL_LOW_LATENCY, "punktfunk:stream-ll")
                    ?.let(::add)
            }
            @Suppress("DEPRECATION")
            wm.createWifiLock(WifiManager.WIFI_MODE_FULL_HIGH_PERF, "punktfunk:stream-hp")
                ?.let(::add)
        }.onEach { it.setReferenceCounted(false) }
    }
    DisposableEffect(handle) {
        window?.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
        wifiLocks.forEach { lock ->
            runCatching { lock.acquire() }.onFailure { e ->
                Log.w("punktfunk", "WifiLock acquire failed — power save stays ON: $lock", e)
            }
        }
        // HDMI Auto Low-Latency Mode: ask the display to drop its post-processing (game mode) —
        // the biggest panel-side latency win on the TV boxes. No-op where ALLM isn't supported. API
        // 30+. Part of the experimental low-latency stack.
        if (lowLatencyMode && Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
            window?.setPreferMinimalPostProcessing(true)
        }
        controller?.let {
            it.systemBarsBehavior = WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE
            it.hide(WindowInsetsCompat.Type.systemBars())
@@ -91,7 +171,9 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
        activity?.requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE
        activity?.streamHandle = handle // route hardware keys to this session
        activity?.axisMapper = Gamepad.AxisMapper(handle) // route joystick axes
-        activity?.requestStreamExit = onDisconnect // Select+Start+L1+R1 chord leaves the stream
+        // Select+Start+L1+R1 chord leaves the stream — a deliberate quit (signal it so the host skips
        // the keep-alive linger), unlike a host-ended / backgrounded drop.
        activity?.requestStreamExit = { NativeBridge.nativeDisconnectQuit(handle); onDisconnect() }
        activity?.setConsoleHighRefreshRate(false) // let the decoder's setFrameRate pick the panel rate
        // Host→client feedback (rumble + DualSense lightbar/LEDs); poll threads stopped before close.
        val feedback = GamepadFeedback(handle).also { it.start() }
@@ -105,6 +187,10 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
            activity?.setConsoleHighRefreshRate(true) // back to the console UI's max refresh
            controller?.show(WindowInsetsCompat.Type.systemBars())
            window?.clearFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
            if (lowLatencyMode && Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
                window?.setPreferMinimalPostProcessing(false)
            }
            wifiLocks.forEach { runCatching { if (it.isHeld) it.release() } }
            // Release the landscape lock so the rest of the app follows the device/system again.
            activity?.requestedOrientation =
                priorOrientation ?: ActivityInfo.SCREEN_ORIENTATION_UNSPECIFIED
@@ -116,7 +202,8 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
        }
    }
-    BackHandler { onDisconnect() }
+    // Back gesture = a deliberate exit → signal the quit so the host tears down now (no linger).
    BackHandler { NativeBridge.nativeDisconnectQuit(handle); onDisconnect() }
    Box(modifier = Modifier.fillMaxSize()) {
        AndroidView(
@@ -125,8 +212,22 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
                SurfaceView(ctx).apply {
                    holder.addCallback(object : SurfaceHolder.Callback {
                        override fun surfaceCreated(holder: SurfaceHolder) {
-                            NativeBridge.nativeStartVideo(handle, holder.surface)
+                            // Low-latency mode: rank MediaCodecList decoders for the negotiated
-                            NativeBridge.nativeStartAudio(handle)
+                            // MIME (framework-only API) and hand the chosen one to Rust, which
                            // creates it by name and applies the per-SoC vendor low-latency keys.
                            // Off ⇒ no ranking: the platform resolves its default decoder for the
                            // MIME, exactly as before the overhaul.
                            val mime = NativeBridge.nativeVideoMime(handle)
                            val choice = if (lowLatencyMode) VideoDecoders.pickDecoder(mime) else null
                            NativeBridge.nativeStartVideo(
                                handle,
                                holder.surface,
                                choice?.name ?: "",
                                lowLatencyMode,
                                choice?.lowLatencyFeature ?: false,
                                isTv,
                            )
                            NativeBridge.nativeStartAudio(handle, lowLatencyMode)
                            if (micWanted) NativeBridge.nativeStartMic(handle)
                        }
@@ -150,7 +251,7 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
        // Live stats HUD (FPS / throughput / capture→client latency), drawn over the video but
        // BEFORE the transparent gesture layer below, so it shows through and never eats touches.
        if (showStats) {
-            stats?.let { StatsOverlay(it, Modifier.align(Alignment.TopStart).padding(12.dp)) }
+            stats?.let { StatsOverlay(it, decoderLabel, Modifier.align(Alignment.TopStart).padding(12.dp)) }
        }
        // Touch input per the Settings model: trackpad/direct-pointer mouse (the shared gesture
        // vocabulary) or real multi-touch passthrough — see TouchInput.kt.
@@ -0,0 +1,14 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!--
  Game Mode config (Android 13 / API 33+). We support the Performance game mode; and we opt OUT of
  the two OEM interventions that would corrupt a game-streaming session:
    - allowGameDownscaling=false: the client renders exactly the host's negotiated resolution; a
      platform downscale would blur the stream.
    - allowGameFpsOverride=false: the stream is paced to the host's frame rate; a platform FPS cap
      would drop frames / add judder.
  Ignored on releases below API 33.
 -->
 <game-mode-config xmlns:android="http://schemas.android.com/apk/res/android"
    android:supportsPerformanceGameMode="true"
    android:allowGameDownscaling="false"
    android:allowGameFpsOverride="false" />
@@ -187,12 +187,19 @@ internal fun StreamScene() {
                Brush.linearGradient(listOf(Color(0xFF2A1E5C), Color(0xFF0E1B3D), Color(0xFF06122B))),
            ),
    ) {
-        // [fps, mbps, latP50, latP95, latValid, skew, w, h, hz, dropped,
+        // The full 18-double unified layout (design/stats-unification.md): [fps, mbps, e2eP50,
-        //  bitDepth, colorPrimaries, colorTransfer, chromaFormatIdc] — the last four = a 10-bit
+        // e2eP95, latValid, skew, w, h, hz, lost, bitDepth, colorPrimaries, colorTransfer,
-        //  BT.2020 PQ (HDR) 4:2:0 feed, so the HUD renders its video-feed line.
+        // chromaFormatIdc, hostNetP50, decodeP50, hostP50, netP50]. 10/9/16/1 = a 10-bit BT.2020
        // PQ (HDR) 4:2:0 feed so the HUD renders its video-feed line; the Phase-2 stage terms
        // (host 0.6 + network 0.3 + decode 0.4) tile the 1.3 ms headline so it renders the full
        // split equation, and the decoder label line shows the ranked low-latency decoder.
        StatsOverlay(
-            doubleArrayOf(238.0, 921.4, 1.3, 2.1, 1.0, 1.0, 5120.0, 1440.0, 240.0, 0.0, 10.0, 9.0, 16.0, 1.0),
+            doubleArrayOf(
-            Modifier.align(Alignment.TopStart).padding(12.dp),
+                238.0, 921.4, 1.3, 2.1, 1.0, 1.0, 5120.0, 1440.0, 240.0, 0.0,
                10.0, 9.0, 16.0, 1.0, 0.9, 0.4, 0.6, 0.3,
            ),
            decoderLabel = "c2.qti.hevc.decoder · low-latency",
            modifier = Modifier.align(Alignment.TopStart).padding(12.dp),
        )
    }
 }
@@ -110,8 +110,18 @@ afterEvaluate {
    // screenshot unit tests render Compose on the JVM and never load libpunktfunk_android.so), so
    // CI/local screenshot runs don't need the Rust toolchain or NDK. The native build stays wired
    // for every normal APK/AAR build.
    //
    // DEBUG APKs SHIP RELEASE RUST. Cargo's debug profile is not "a bit slower" for this library —
    // it is unusable: the AES-GCM data-plane decrypt runs through generic-array iterator closures
    // with per-byte UB checks instead of ARMv8 hardware AES. Profiled live on a phone (simpleperf):
    // ~800 µs of user CPU per 1.4 KB packet, the receive pump pinned over a full core yet unable to
    // drain a 20 Mbps stream — every debug-APK on-device test was silently benchmarking unoptimized
    // crypto, not the streaming pipeline. Kotlin debuggability is untouched (the APK is still a
    // debug build); only the cargo profile changes. `-PrustDebug` restores a debug-profile native
    // build for the rare session that actually steps through Rust.
    if (!project.hasProperty("skipRustBuild")) {
-        tasks.named("preDebugBuild").configure { dependsOn(cargoNdkDebug) }
+        val debugRust = if (project.hasProperty("rustDebug")) cargoNdkDebug else cargoNdkRelease
        tasks.named("preDebugBuild").configure { dependsOn(debugRust) }
        tasks.named("preReleaseBuild").configure { dependsOn(cargoNdkRelease) }
    }
 }
@@ -57,6 +57,7 @@ object Gamepad {
    private const val VID_SONY = 0x054C
    private const val VID_MICROSOFT = 0x045E
    private const val VID_VALVE = 0x28DE
    private const val VID_NINTENDO = 0x057E
    // Sony product ids. DualSense (PS5) and DualShock 4 (PS4) map to distinct host pad types.
    private val PID_DUALSENSE = setOf(0x0CE6, 0x0DF2)
@@ -98,6 +99,28 @@ object Gamepad {
        }
    }
    /**
     * The glyph family a controller's physical buttons belong to, for the console UI's hint bar —
     * so a DualSense user sees ✕/○/□/△ shapes and a Switch pad its monochrome lettering instead of
     * Xbox's coloured letters. PURELY visual: the wire mapping ([buttonBit]) is unaffected.
     */
    enum class PadStyle { GENERIC, XBOX, PLAYSTATION, NINTENDO }
    /**
     * Resolve the [PadStyle] for a connected controller by USB vendor id. Vendor alone is enough —
     * every pad a vendor ships wears its family's glyphs (any Sony pad has the shapes, any Nintendo
     * pad the −/+ system buttons), so unlike [prefFor] no PID table is needed. Valve renders as
     * [PadStyle.XBOX]: Steam pads carry A/B/X/Y in Xbox positions. Unknown vendors (8BitDo & co.,
     * which near-universally clone the Xbox layout) fall back to [PadStyle.GENERIC], drawn with the
     * Xbox convention.
     */
    fun styleFor(dev: InputDevice?): PadStyle = when (dev?.vendorId) {
        VID_SONY -> PadStyle.PLAYSTATION
        VID_MICROSOFT, VID_VALVE -> PadStyle.XBOX
        VID_NINTENDO -> PadStyle.NINTENDO
        else -> PadStyle.GENERIC
    }
    /** True when [dev]'s source classes include gamepad or joystick. */
    fun isPad(dev: InputDevice?): Boolean {
        val s = dev?.sources ?: return false
@@ -51,11 +51,23 @@ object NativeBridge {
        /** Preferred video codec as a `quic::CODEC_*` bit (`0` = auto). Soft — the host falls back. */
        preferredCodec: Int,
        timeoutMs: Int,
        /** Store-qualified library id (`steam:<appid>` / `custom:<id>`) to boot straight into a game,
         *  or `null`/empty for a plain desktop connect. Rides the Hello as `launch`. */
        launch: String?,
    ): Long
    /** 64-hex SHA-256 of the cert the host presented on [handle]; valid after a successful connect. */
    external fun nativeHostFingerprint(handle: Long): String
    /**
     * Has the underlying QUIC session ended? `true` once the connection closed — a host suspend /
     * crash / network drop idle-timed it out (~8 s), or the host closed it — from then on no frame
     * ever arrives and the video sits frozen on its last one. The stream watchdog polls this (~1 Hz)
     * to leave a dead stream and return to the menu, where the user can Wake-on-LAN the host, instead
     * of stranding them on a frozen frame. `false` on a `0` handle. Cheap (one atomic load); UI-safe.
     */
    external fun nativeSessionEnded(handle: Long): Boolean
    /**
     * Run the SPAKE2 PIN ceremony, presenting [certPem]/[keyPem]. Returns the host's verified
     * fingerprint (64-hex) to persist + pin, or `""` on failure (wrong PIN / MITM / unreachable).
@@ -70,6 +82,14 @@ object NativeBridge {
        name: String,
    ): String
    /**
     * Signal a **deliberate** user disconnect on [handle] before [nativeClose]: the session closes
     * with `QUIT_CLOSE_CODE` so the host tears it down immediately instead of holding the keep-alive
     * linger for a reconnect. Call from an explicit disconnect gesture only — NOT from a
     * host-ended/network-drop end or an app-background (those keep the linger). No-op on `0`.
     */
    external fun nativeDisconnectQuit(handle: Long)
    /** Tear down a session handle returned by [nativeConnect]. No-op on `0`. */
    external fun nativeClose(handle: Long)
@@ -104,14 +124,51 @@ object NativeBridge {
    external fun nativeWakeOnLan(macsCsv: String, lastIp: String): Boolean
    /**
-     * Start the HEVC decode thread rendering onto [surface] (a SurfaceView's surface). Decode runs
+     * Apply the user's "Low-latency mode (experimental)" toggle to the process-wide transport
-     * entirely in Rust (NDK AMediaCodec → ANativeWindow) — no per-frame JNI. No-op if already started.
+     * defaults — today just DSCP/QoS marking on the media sockets. Must be called BEFORE
     * [nativeConnect] (the tag is applied at socket creation); `HostConnect.connectToHost` does.
     * The rest of the toggle rides explicit per-session parameters ([nativeStartVideo] /
     * [nativeStartAudio]). Cheap (one atomic store); UI-safe.
     */
-    external fun nativeStartVideo(handle: Long, surface: android.view.Surface)
+    external fun nativeSetLowLatencyMode(enabled: Boolean)
    /**
     * The MediaCodec MIME the host resolved for this session (`"video/hevc"` / `"video/avc"` /
     * `"video/av01"`), or `""` on a `0` handle. Kotlin ranks `MediaCodecList` decoders for this
     * MIME (see [io.unom.punktfunk.kit.VideoDecoders]) before [nativeStartVideo]. Cheap; UI-safe.
     */
    external fun nativeVideoMime(handle: Long): String
    /**
     * Start the decode thread rendering onto [surface] (a SurfaceView's surface). Decode runs
     * entirely in Rust (NDK AMediaCodec → ANativeWindow) — no per-frame JNI. [decoderName] is the
     * decoder Kotlin ranked from `MediaCodecList` (`""` = let the platform resolve the default for
     * the MIME — what the pre-overhaul client always did); [lowLatencyMode] is the user's
     * "Low-latency mode (experimental)" toggle (off, the default, runs the original decode
     * pipeline; on, the aggressive per-SoC tuning + async loop); [lowLatencyFeature] is whether
     * [decoderName] advertised `FEATURE_LowLatency` (HUD label only). [isTv] drives an active HDMI
     * mode switch to the stream refresh on TV boxes when the toggle is on (vs. the softer seamless
     * hint otherwise). No-op if already started.
     */
    external fun nativeStartVideo(
        handle: Long,
        surface: android.view.Surface,
        decoderName: String,
        lowLatencyMode: Boolean,
        lowLatencyFeature: Boolean,
        isTv: Boolean,
    )
    /** Stop + join the decode thread without closing the session. No-op on `0`. */
    external fun nativeStopVideo(handle: Long)
    /**
     * The resolved decoder identity for the HUD, e.g. `c2.qti.avc.decoder · low-latency`, or `""`
     * before the decode thread has resolved one. One-shot (fixed for the session); poll once after
     * the HUD appears.
     */
    external fun nativeVideoDecoderLabel(handle: Long): String
    /**
     * Drain ~1 s of live decode stats for the on-stream HUD, or `null` when no decode thread runs.
     * Returns 18 doubles (unified stats spec, `design/stats-unification.md`):
@@ -137,10 +194,12 @@ object NativeBridge {
    external fun nativeSetVideoStatsEnabled(handle: Long, enabled: Boolean)
    /**
-     * Start host→client audio: Opus decode → jitter ring → AAudio (LowLatency), all in Rust. No-op
+     * Start host→client audio: Opus decode → jitter ring → AAudio (LowLatency), all in Rust.
-     * if already started. Best-effort — a failure leaves video streaming.
+     * [lowLatencyMode] (the experimental toggle) additionally tags the stream usage=Game for the
     * HAL's game-audio routing. No-op if already started. Best-effort — a failure leaves video
     * streaming.
     */
-    external fun nativeStartAudio(handle: Long)
+    external fun nativeStartAudio(handle: Long, lowLatencyMode: Boolean)
    /** Stop + join the audio thread and close AAudio, without closing the session. No-op on `0`. */
    external fun nativeStopAudio(handle: Long)
@@ -0,0 +1,95 @@
 package io.unom.punktfunk.kit
 import android.media.MediaCodecInfo.CodecCapabilities
 import android.media.MediaCodecList
 import android.os.Build
 /** The decoder Kotlin ranked for a MIME, handed to [NativeBridge.nativeStartVideo]. */
 data class DecoderChoice(val name: String, val lowLatencyFeature: Boolean)
 /**
 * Rank the platform's `MediaCodecList` decoders for a video MIME and pick the best one for
 * low-latency streaming, the way Moonlight-Android does. There is no NDK `MediaCodecList`, so this
 * enumeration must live on the Kotlin (framework) side; Rust then creates the chosen decoder by
 * name (`AMediaCodec_createCodecByName`) and derives the per-SoC vendor low-latency keys from it.
 *
 * Ranking (best first): hardware over software; a real SoC-vendor decoder (Qualcomm/Amlogic/…) over
 * the generic AOSP software fallback; a decoder advertising `FEATURE_LowLatency` over one that
 * doesn't. Known-bad software decoders (`omx.google.*`, `c2.android.*`, Qualcomm/Samsung SW HEVC)
 * are dropped outright — matching Moonlight's blacklist.
 */
 object VideoDecoders {
    /** Decoder-name prefixes/names we never want, mirroring Moonlight's blacklist. */
    private val BLOCKED_PREFIXES = listOf("omx.google.", "c2.android.", "avcdecoder", "omx.ffmpeg.")
    private val BLOCKED_EXACT = listOf("omx.qcom.video.decoder.hevcswvdec", "omx.sec.hevc.sw.dec")
    /**
     * Real SoC-vendor decoder prefixes we prefer over the generic AOSP fallback, covering the common
     * targets: Qualcomm Snapdragon and MediaTek (most phones + many TV boxes), Samsung Exynos (+
     * Google Tensor, whose decoder is `c2.exynos.*`), NVIDIA Tegra (Shield TV), Amlogic / Rockchip /
     * Realtek (TV boxes & smart TVs), and HiSilicon Kirin (older Huawei).
     */
    private val VENDOR_PREFIXES = listOf(
        "omx.qcom", "c2.qti",
        "omx.mtk", "c2.mtk",
        "omx.exynos", "c2.exynos",
        "omx.nvidia", "c2.nvidia",
        "omx.amlogic", "c2.amlogic",
        "omx.rk", "c2.rk",
        "omx.realtek", "c2.realtek",
        "omx.hisi", "c2.hisi",
    )
    /**
     * Pick the best decoder for [mime] (`"video/hevc"` / `"video/avc"` / `"video/av01"`), or `null`
     * to let the platform resolve its default. Enumerates once — call at stream start.
     */
    fun pickDecoder(mime: String): DecoderChoice? {
        if (mime.isEmpty()) return null
        val infos = runCatching { MediaCodecList(MediaCodecList.REGULAR_CODECS).codecInfos }
            .getOrNull() ?: return null
        var bestName: String? = null
        var bestLowLatency = false
        var bestScore = Int.MIN_VALUE
        for (info in infos) {
            if (info.isEncoder) continue
            val name = info.name
            val lower = name.lowercase()
            if (BLOCKED_PREFIXES.any { lower.startsWith(it) } || lower in BLOCKED_EXACT) continue
            // Never a secure decoder: `.secure` names are the DRM-pipeline twins of the real
            // decoder and require a secure surface — configuring one for a clear stream fails (or
            // renders black). The plain twin is also in the list, so drop rather than rank
            // (a `.secure` twin can otherwise OUT-score its plain sibling when only it advertises
            // FEATURE_LowLatency). Moonlight filters the same way.
            if (lower.endsWith(".secure")) continue
            val caps = runCatching { info.getCapabilitiesForType(mime) }.getOrNull() ?: continue
            val secureRequired = runCatching {
                caps.isFeatureRequired(CodecCapabilities.FEATURE_SecurePlayback)
            }.getOrDefault(false)
            if (secureRequired) continue
            val hardware = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
                info.isHardwareAccelerated
            } else {
                // Pre-Q heuristic: the software decoders are the ones we can name (already blocked
                // above), so anything surviving the blacklist is treated as hardware.
                true
            }
            val lowLatency = Build.VERSION.SDK_INT >= Build.VERSION_CODES.R &&
                runCatching { caps.isFeatureSupported(CodecCapabilities.FEATURE_LowLatency) }
                    .getOrDefault(false)
            val vendor = VENDOR_PREFIXES.any { lower.startsWith(it) }
            val score = (if (hardware) 100 else 0) +
                (if (vendor) 40 else 0) +
                (if (lowLatency) 20 else 0)
            if (score > bestScore) {
                bestScore = score
                bestName = name
                bestLowLatency = lowLatency
            }
        }
        return bestName?.let { DecoderChoice(it, bestLowLatency) }
    }
 }
@@ -20,7 +20,7 @@ punktfunk-core = { path = "../../../crates/punktfunk-core", features = ["quic"]
 jni = "0.21"
 log = "0.4"
 # LAN host discovery: browse the host's `_punktfunk._udp` mDNS advert — the SAME crate + service the
-# Linux/Windows clients use (`clients/linux/src/discovery.rs`), replacing Android's per-OEM
+# Linux/Windows clients use (`crates/pf-client-core/src/discovery.rs`), replacing Android's per-OEM
 # `NsdManager` system daemon with one tested browse path. Pure Rust (socket2/if-addrs/mio), so it
 # cross-compiles to the Android targets AND builds on the host (the JNI seam links into
 # `cargo build --workspace`). Kotlin keeps only the Wi-Fi `MulticastLock` + permission UX.
@@ -31,6 +31,14 @@ mdns-sd = "0.20"
 # via `ndk`, the Opus codec) is only pulled in for the real `*-linux-android` targets.
 [target.'cfg(target_os = "android")'.dependencies]
 android_logger = "0.14"
 # Feature bridge, no code here: punktfunk-core logs through `tracing`, but this client only
 # installs `android_logger` (a `log` backend). Core transport warnings (e.g. "UDP socket buffer
 # capped well below target") reach logcat only via tracing's "log" feature, which forwards events
 # as `log` records when no tracing subscriber is set (always, here). Today that feature happens to
 # be enabled transitively — quinn's default `log` feature unifies `tracing/log` onto the whole
 # graph — but nothing about this client's logging should hinge on a QUIC crate's default feature
 # set, so declare it explicitly.
 tracing = { version = "0.1", default-features = false, features = ["std", "log"] }
 # NDK bindings. "media" = AMediaCodec/ANativeWindow (video); "audio" = AAudio (audio playback).
 # Pure-Rust FFI to libmediandk/libnativewindow/libaaudio — no C++/libc++_shared to bundle. Decode +
 # audio run entirely in Rust on native threads (the "no async on the hot path" invariant).
@@ -28,6 +28,7 @@ type CreateSessionFn = unsafe extern "C" fn(*mut c_void, *const i32, usize, i64)
 type ReportFn = unsafe extern "C" fn(*mut c_void, i64) -> c_int;
 type UpdateTargetFn = unsafe extern "C" fn(*mut c_void, i64) -> c_int;
 type CloseFn = unsafe extern "C" fn(*mut c_void);
 type SetPreferPowerEfficiencyFn = unsafe extern "C" fn(*mut c_void, bool) -> c_int;
 /// The entry points we use, resolved once from `libandroid.so`, plus the process-wide manager.
 struct Api {
@@ -35,6 +36,9 @@ struct Api {
    report: ReportFn,
    update_target: UpdateTargetFn,
    close: CloseFn,
    /// `APerformanceHint_setPreferPowerEfficiency` — NDK **API 35**, so `Option`al even when the
    /// rest of ADPF resolved (a 33/34 device has the session API but not this one).
    set_prefer_power_efficiency: Option<SetPreferPowerEfficiencyFn>,
    manager: *mut c_void,
 }
@@ -70,11 +74,20 @@ fn resolve_api() -> Option<Api> {
        if manager.is_null() {
            return None;
        }
        // Optional (API 35): resolve if present, else `None` — the session still works without it.
        let set_prefer_power_efficiency =
            libc::dlsym(lib, c"APerformanceHint_setPreferPowerEfficiency".as_ptr());
        let set_prefer_power_efficiency = (!set_prefer_power_efficiency.is_null()).then(|| {
            std::mem::transmute::<*mut c_void, SetPreferPowerEfficiencyFn>(
                set_prefer_power_efficiency,
            )
        });
        Some(Api {
            create_session: std::mem::transmute::<*mut c_void, CreateSessionFn>(create_session),
            report: std::mem::transmute::<*mut c_void, ReportFn>(report),
            update_target: std::mem::transmute::<*mut c_void, UpdateTargetFn>(update_target),
            close: std::mem::transmute::<*mut c_void, CloseFn>(close),
            set_prefer_power_efficiency,
            manager,
        })
    }
@@ -90,8 +103,10 @@ pub struct HintSession {
 impl HintSession {
    /// Open a session hinting `tids` with an initial per-frame target of `target_ns` nanoseconds.
    /// `None` when ADPF is unavailable (device API < 33) or the platform declines — the caller then
-    /// runs unhinted (a no-op, not an error).
+    /// runs unhinted (a no-op, not an error). `prefer_performance` (the experimental low-latency
-    pub fn create(target_ns: i64, tids: &[i32]) -> Option<Self> {
+    /// mode) additionally biases the governor away from power efficiency (API 35+); off, the
    /// session runs with the platform default, as it did before the overhaul.
    pub fn create(target_ns: i64, tids: &[i32], prefer_performance: bool) -> Option<Self> {
        if target_ns <= 0 || tids.is_empty() {
            return None;
        }
@@ -103,6 +118,15 @@ impl HintSession {
        if session.is_null() {
            return None;
        }
        // Tell the governor NOT to bias this session toward power efficiency (API 35+): our loop is
        // latency-critical, so we want it kept on fast cores at high clocks over battery savings.
        // Best-effort; absent below API 35.
        if prefer_performance {
            if let Some(f) = api.set_prefer_power_efficiency {
                // SAFETY: `session` is the live session just created; the fn takes it + a bool.
                unsafe { f(session, false) };
            }
        }
        Some(Self { api, session })
    }
@@ -18,8 +18,8 @@
 //! grown on XRuns (Google's anti-glitch technique).
 use ndk::audio::{
-    AudioCallbackResult, AudioDirection, AudioFormat, AudioPerformanceMode, AudioSharingMode,
+    AudioCallbackResult, AudioContentType, AudioDirection, AudioFormat, AudioPerformanceMode,
-    AudioStream, AudioStreamBuilder,
+    AudioSharingMode, AudioStream, AudioStreamBuilder, AudioUsage,
 };
 use punktfunk_core::client::NativeClient;
 use punktfunk_core::error::PunktfunkError;
@@ -116,8 +116,10 @@ pub struct AudioPlayback {
 impl AudioPlayback {
    /// Open AAudio (LowLatency, 48 kHz/f32, the host-resolved channel layout) with a realtime
    /// callback draining a jitter ring, then spawn the Opus decode thread. `None` on failure (the
-    /// caller leaves video streaming).
+    /// caller leaves video streaming). `game_audio` (the experimental low-latency mode) tags the
-    pub fn start(client: Arc<NativeClient>) -> Option<AudioPlayback> {
+    /// stream usage=Game for the HAL's game-audio routing; off, the stream is untagged as it was
    /// before the overhaul.
    pub fn start(client: Arc<NativeClient>, game_audio: bool) -> Option<AudioPlayback> {
        // Build playback from the host-RESOLVED channel count (never the request): 2 = stereo /
        // 6 = 5.1 / 8 = 7.1, canonical wire order FL FR FC LFE RL RR SL SR.
        let channels = punktfunk_core::audio::normalize_channels(client.audio_channels) as usize;
@@ -226,7 +228,7 @@ impl AudioPlayback {
                AudioCallbackResult::Continue
            };
-            let stream = AudioStreamBuilder::new()?
+            let builder = AudioStreamBuilder::new()?
                .direction(AudioDirection::Output)
                .sample_rate(SAMPLE_RATE)
                // The wire order (FL FR FC LFE RL RR SL SR) is the standard AAudio/Android channel
@@ -234,7 +236,19 @@ impl AudioPlayback {
                // from `channel_count` (the ndk crate's builder exposes no setChannelMask); the host
                // captures + Opus-encodes in exactly this order.
                .channel_count(channels as i32)
-                .format(AudioFormat::PCM_Float)
+                .format(AudioFormat::PCM_Float);
            // Tag the stream as game audio (usage=Game / content=Movie): the audio HAL applies
            // its low-latency game-audio routing/policy and it's grouped correctly with the
            // game-mode profile. Advisory — ignored where the device has no such policy. Part of
            // the experimental low-latency stack; off, the stream stays untagged.
            let builder = if game_audio {
                builder
                    .usage(AudioUsage::Game)
                    .content_type(AudioContentType::Movie)
            } else {
                builder
            };
            let stream = builder
                .performance_mode(AudioPerformanceMode::LowLatency)
                .sharing_mode(sharing)
                .data_callback(Box::new(callback))
@@ -8,8 +8,8 @@
 use ndk::data_space::DataSpace;
 use ndk::media::media_codec::{
-    DequeuedInputBufferResult, DequeuedOutputBufferInfoResult, MediaCodec, MediaCodecDirection,
+    AsyncNotifyCallback, DequeuedInputBufferResult, DequeuedOutputBufferInfoResult, MediaCodec,
-    OutputBuffer,
+    MediaCodecDirection, OutputBuffer,
 };
 use ndk::media::media_format::MediaFormat;
 use ndk::native_window::NativeWindow;
@@ -19,9 +19,14 @@ use punktfunk_core::session::Frame;
 use std::collections::VecDeque;
 use std::ffi::c_void;
 use std::sync::atomic::{AtomicBool, Ordering};
-use std::sync::Arc;
+use std::sync::{mpsc, Arc, Mutex};
 use std::time::{Duration, Instant};
 /// Cap on AUs parked in the async loop awaiting a free codec input slot. Matches the connector's
 /// own frame-channel depth; on sustained overflow the oldest is dropped and a keyframe requested
 /// (same recovery as a reassembler drop). In steady state this stays near-empty.
 const FRAME_PARK_CAP: usize = 16;
 /// Cap on the pts→received-timestamp map below: MediaCodec holds only a handful of frames in
 /// flight, so anything beyond this is stale (codec flushed / HUD toggled) and gets evicted.
 const IN_FLIGHT_CAP: usize = 64;
@@ -31,29 +36,83 @@ const IN_FLIGHT_CAP: usize = 64;
 /// this deep is a lost datagram (or an old host that never sends any) and gets evicted.
 const PENDING_SPLIT_CAP: usize = 256;
-/// The decode loop. Runs on the `pf-decode` thread until `shutdown` is set or the session closes.
+/// Whether low-latency mode uses the event-driven async decode loop (default) or the synchronous
 /// poll loop. Flip to `false` to A/B the two on the HUD (`design/…`); the async loop presents a
 /// decoded frame the instant it's ready instead of waiting out a poll interval. Only consulted when
 /// the user's "Low-latency mode" toggle is ON (now the default) — off, the sync loop always runs (the
 /// original pipeline, kept as the per-device escape hatch).
 const USE_ASYNC_DECODE: bool = true;
 /// Per-session decode configuration, resolved by the JNI layer (`nativeStartVideo`) and passed to
 /// the decode loop. Bundled so the loop entry points don't sprout a wide argument list.
 pub(crate) struct DecodeOptions {
    /// The decoder Kotlin ranked from `MediaCodecList` (`VideoDecoders.pickDecoder`). `None`/empty ⇒
    /// let the platform resolve the default decoder for the MIME.
    pub decoder_name: Option<String>,
    /// Whether Kotlin found the chosen decoder advertises `FEATURE_LowLatency` (queryable only via
    /// the Java `CodecCapabilities` API) — surfaced on the HUD next to the decoder name.
    pub ll_feature: bool,
    /// The user's "Low-latency mode" master toggle. On (default) ⇒ the full fast pipeline: async
    /// decode loop, per-SoC vendor keys, pipeline thread boosts, ADPF max-performance, forced TV
    /// mode switch. Off ⇒ the original synchronous pre-overhaul pipeline, kept as the per-device
    /// escape hatch.
    pub low_latency_mode: bool,
    /// TV form factor (Kotlin's `UiModeManager`): actively drive the HDMI output into the stream's
    /// refresh mode, vs. the softer seamless hint on a phone/tablet.
    pub is_tv: bool,
 }
 /// The decode entry point on the `pf-decode` thread: dispatches to the async or synchronous loop.
 /// Both run until `shutdown` is set or the session closes.
 pub fn run(
    client: Arc<NativeClient>,
    window: NativeWindow,
    shutdown: Arc<AtomicBool>,
    stats: Arc<crate::stats::VideoStats>,
    opts: DecodeOptions,
 ) {
    if opts.low_latency_mode && USE_ASYNC_DECODE {
        run_async(client, window, shutdown, stats, opts);
    } else {
        run_sync(client, window, shutdown, stats, opts);
    }
 }
 /// The synchronous poll loop — the original decode path: the only one when low-latency mode is off,
 /// and the [`USE_ASYNC_DECODE`] A/B fallback when it's on. Feeds and drains on this one thread; the
 /// only blocking wait is a short output dequeue while input is backed up.
 fn run_sync(
    client: Arc<NativeClient>,
    window: NativeWindow,
    shutdown: Arc<AtomicBool>,
    stats: Arc<crate::stats::VideoStats>,
    opts: DecodeOptions,
 ) {
    let DecodeOptions {
        decoder_name,
        ll_feature,
        low_latency_mode,
        is_tv,
    } = opts;
    boost_thread_priority();
    let mode = client.mode();
-    // The MediaCodec MIME for the codec the host resolved (`Welcome.codec`): HEVC or H.264. AMediaCodec
+    // The MediaCodec MIME for the codec the host resolved (`Welcome.codec`). AMediaCodec needs no
-    // needs no out-of-band extradata — the in-band VPS/SPS/PPS on every IDR configure it either way.
+    // out-of-band extradata — the in-band VPS/SPS/PPS on every IDR configure it either way.
-    let mime = match client.codec {
+    let mime = codec_mime(client.codec);
-        punktfunk_core::quic::CODEC_H264 => "video/avc",
+    let codec = match create_codec(mime, decoder_name.as_deref()) {
        _ => "video/hevc",
    };
    let codec = match MediaCodec::from_decoder_type(mime) {
        Some(c) => c,
        None => {
            log::error!("decode: no {mime} decoder on this device");
            return;
        }
    };
-    log::info!("decode: codec mime = {mime}");
+    // The decoder's *actual* resolved name (Kotlin's pick, or the platform default when it fell
    // back) drives both the HUD label and which vendor low-latency keys apply below.
    let codec_name = codec.name().unwrap_or_default();
    stats.set_decoder(&codec_name, ll_feature);
    log::info!(
        "decode: codec mime = {mime}, decoder = {codec_name} (low-latency feature: {ll_feature})"
    );
    let mut format = MediaFormat::new();
    format.set_str("mime", mime);
@@ -64,23 +123,9 @@ pub fn run(
        "max-input-size",
        (mode.width * mode.height).max(2_000_000) as i32,
    );
-    // Ask for the low-latency decode path where the decoder supports it (no reordering buffer).
+    // Standard + per-SoC vendor low-latency keys and the clock hints, gated on the resolved decoder
-    format.set_i32("low-latency", 1);
+    // name and the master toggle (see `configure_low_latency`).
-    // Best-effort vendor twin of the standard key: older Qualcomm decoders only honor their own
+    configure_low_latency(&mut format, &codec_name, low_latency_mode);
    // extension. Unknown keys are ignored by other vendors' codecs, so this is safe to set blind.
    format.set_i32("vendor.qti-ext-dec-low-latency.enable", 1);
    // Advisory low-latency hints (KEY_PRIORITY / KEY_OPERATING_RATE), ignored where unsupported:
    // realtime priority + the target frame rate, so vendor decoders (e.g. Qualcomm) run at full
    // clocks instead of a power-saving cadence that adds dequeue latency.
    format.set_i32("priority", 0); // 0 = realtime
                                   // Operating rate = the codec's clock hint. Setting it to the display rate merely asks the
                                   // decoder to *sustain* that cadence — a Qualcomm decoder can meet 60/120 fps at a power-saving
                                   // clock that adds a millisecond-plus of decode latency per frame. Setting it to the AOSP
                                   // "unbounded" sentinel (Short.MAX) instead asks the decoder to run each frame at max clocks and
                                   // finish ASAP, minimising per-frame decode latency — the right trade for a real-time stream
                                   // (costs power/heat; the dial to lower if a device thermally throttles over a long session).
                                   // Ignored where unsupported.
    format.set_i32("operating-rate", i16::MAX as i32); // 32767 = "as fast as possible"
    // HDR static metadata (ST.2086 mastering + content light level): when an HDR session was
    // negotiated, set KEY_HDR_STATIC_INFO so the display tone-maps from the source's real grade.
@@ -118,7 +163,11 @@ pub fn run(
    // above our API-28 floor, so we resolve it at runtime (see `try_set_frame_rate`) rather than link
    // it — a hard import would stop `libpunktfunk_android.so` loading at all on API 28/29. Absent
    // there ⇒ we simply skip the hint (non-fatal; the stream renders fine without it).
-    if mode.refresh_hz > 0 && !try_set_frame_rate(&window, mode.refresh_hz as f32) {
+    // The forced TV mode switch (`is_tv` ⇒ ALWAYS strategy) is part of the experimental stack;
    // off, every form factor gets the original soft seamless hint.
    if mode.refresh_hz > 0
        && !try_set_frame_rate(&window, mode.refresh_hz as f32, is_tv && low_latency_mode)
    {
        log::debug!(
            "decode: set_frame_rate({} Hz) unavailable/declined (non-fatal)",
            mode.refresh_hz
@@ -277,7 +326,12 @@ pub fn run(
                // or where the platform declines → `None`, and the loop runs unhinted).
                hint_tried = true;
                let tids = client.hot_thread_ids();
-                hint = crate::adpf::HintSession::create(frame_period_ns, &tids);
+                // The pump/audio priority boost is part of the experimental low-latency stack; the
                // ADPF session itself predates it and always runs (max-performance bias gated inside).
                if low_latency_mode {
                    boost_hot_threads(&tids);
                }
                hint = crate::adpf::HintSession::create(frame_period_ns, &tids, low_latency_mode);
                log::info!(
                    "decode: ADPF hint session {} — {} hot thread(s), target {frame_period_ns} ns",
                    if hint.is_some() {
@@ -326,6 +380,626 @@ fn now_realtime_ns() -> i128 {
        .unwrap_or(0)
 }
 /// The MediaCodec MIME for the codec the host resolved (`Welcome.codec`). Shared by the decode
 /// thread and `nativeVideoMime` (which tells Kotlin what to rank decoders for). AV1 uses the
 /// AOSP `video/av01` type; anything not H.264/AV1 is treated as HEVC (every pre-negotiation host
 /// emitted HEVC).
 pub(crate) fn codec_mime(codec: u8) -> &'static str {
    match codec {
        punktfunk_core::quic::CODEC_H264 => "video/avc",
        punktfunk_core::quic::CODEC_AV1 => "video/av01",
        _ => "video/hevc",
    }
 }
 /// Create the decoder: prefer the specific codec Kotlin ranked from `MediaCodecList`
 /// (`from_codec_name`), falling back to the platform's default decoder for the MIME
 /// (`from_decoder_type`) if that name can't be created (codec busy / renamed across an OS update).
 fn create_codec(mime: &str, preferred: Option<&str>) -> Option<MediaCodec> {
    if let Some(name) = preferred.filter(|n| !n.is_empty()) {
        if let Some(c) = MediaCodec::from_codec_name(name) {
            return Some(c);
        }
        log::warn!(
            "decode: from_codec_name({name}) failed — falling back to default {mime} decoder"
        );
    }
    MediaCodec::from_decoder_type(mime)
 }
 /// Apply the low-latency MediaFormat keys for `codec_name`.
 ///
 /// `aggressive` = the "Low-latency mode" master toggle. **Off** ⇒ the pre-overhaul key set,
 /// byte-for-byte — the standard `low-latency` key, the blind Qualcomm vendor twin, `priority = 0` AND
 /// `operating-rate = MAX` set together — kept as the per-device escape hatch (the profile every device
 /// streamed with before the overhaul). **On** (default) ⇒ the Moonlight-parity
 /// profile: MediaTek's `vdec-lowlatency` (unconditionally — ignored off MediaTek), the per-SoC
 /// vendor extension keys (gated on the decoder-name prefix the way Moonlight-Android does, since a
 /// key one vendor honours is meaningless on another), and one *mutually exclusive* clock hint.
 ///
 /// Vendor keys mirror Moonlight's `MediaCodecHelper` (verified against current source): Qualcomm
 /// picture-order + low-latency, Exynos (also Google Tensor), Amlogic, HiSilicon, MediaTek. NVIDIA
 /// Tegra / Rockchip / Realtek expose no such key (nor does Moonlight) — they're covered by the
 /// standard key + clock hint + being ranked first in `VideoDecoders`.
 fn configure_low_latency(format: &mut MediaFormat, codec_name: &str, aggressive: bool) {
    // Standard key: request the no-reorder low-latency path where the platform decoder supports it.
    format.set_i32("low-latency", 1);
    if !aggressive {
        // The original profile: the Qualcomm vendor twin set blind (unknown keys are ignored by
        // other vendors' codecs), realtime priority, and the AOSP "unbounded" operating-rate
        // sentinel — decode each frame at max clocks rather than pacing to the frame rate.
        format.set_i32("vendor.qti-ext-dec-low-latency.enable", 1);
        format.set_i32("priority", 0); // 0 = realtime
        format.set_i32("operating-rate", i16::MAX as i32); // 32767 = "as fast as possible"
        return;
    }
    // MediaTek's low-latency key — very common (mid/budget phones + many Google TV / Fire TV boxes).
    // Set unconditionally like the standard key: MediaTek decoders honour it, others ignore it, so it
    // covers MediaTek whatever the exact decoder name (omx.mtk / c2.mtk / an OEM rename). Moonlight
    // does the same, and also relies on it for Amazon's Amlogic fork.
    format.set_i32("vdec-lowlatency", 1);
    let name = codec_name.to_ascii_lowercase();
    let is = |prefix: &str| name.starts_with(prefix);
    // Qualcomm Snapdragon (the most common phone SoC): picture-order forces decode-order output
    // (kills the reorder buffer on decoders that predate the standard key); low-latency is the older
    // vendor twin.
    if is("omx.qcom") || is("c2.qti") {
        format.set_i32("vendor.qti-ext-dec-picture-order.enable", 1);
        format.set_i32("vendor.qti-ext-dec-low-latency.enable", 1);
    }
    // Samsung Exynos — also covers Google Tensor (Pixel 6+), whose hardware decoder is `c2.exynos.*`.
    if is("omx.exynos") || is("c2.exynos") {
        format.set_i32("vendor.rtc-ext-dec-low-latency.enable", 1);
    }
    // Amlogic — the Android TV boxes (onn 4K, Chromecast w/ Google TV, Homatics).
    if is("omx.amlogic") || is("c2.amlogic") {
        format.set_i32("vendor.low-latency.enable", 1);
    }
    // HiSilicon / Kirin (older Huawei; paired req/rdy keys).
    if is("omx.hisi") || is("c2.hisi") {
        format.set_i32(
            "vendor.hisi-ext-low-latency-video-dec.video-scene-for-low-latency-req",
            1,
        );
        format.set_i32(
            "vendor.hisi-ext-low-latency-video-dec.video-scene-for-low-latency-rdy",
            -1,
        );
    }
    // NVIDIA Tegra (Shield TV) and Rockchip/Realtek (budget TV boxes / smart TVs) expose no
    // low-latency vendor key (Moonlight has none either) — their decoders are already low-latency
    // oriented, so the standard `low-latency` key + the clock hint below + being ranked first
    // (see `VideoDecoders`) is their treatment.
    //
    // Clock hint, mutually exclusive (matching Moonlight): the AOSP "unbounded" operating-rate
    // sentinel (Short.MAX) tells the decoder to run each frame at max clocks and finish ASAP rather
    // than pace to the frame rate — shaving per-frame decode latency at a power/heat cost. Only
    // Qualcomm is known to handle the sentinel; every other vendor mis-paces on it, so they get the
    // plain realtime `priority` hint instead.
    if decoder_supports_max_operating_rate(&name) {
        format.set_i32("operating-rate", i16::MAX as i32); // 32767 = "as fast as possible"
    } else {
        format.set_i32("priority", 0); // 0 = realtime
    }
 }
 /// Whether a decoder tolerates `operating-rate = Short.MAX` rather than regressing on it. Follows
 /// Moonlight's allowlist: Qualcomm decoders honour the sentinel (the Adreno 620 generation is the
 /// known exception Moonlight excludes by GPU model — undetectable from native code here, so it
 /// rides the master toggle as its escape hatch). Other vendors fall back to the plain `priority`
 /// hint above.
 fn decoder_supports_max_operating_rate(name_lower: &str) -> bool {
    name_lower.starts_with("omx.qcom") || name_lower.starts_with("c2.qti")
 }
 /// One decoded output buffer ready to release: its codec buffer index + the pts the codec echoed
 /// (from the output callback's `BufferInfo`), used to pair the `decode` HUD stat.
 struct OutputReady {
    index: usize,
    pts_us: u64,
 }
 /// Events the async decode loop reacts to. The codec's async-notify callbacks (which run on its
 /// internal looper thread) push the codec ones; the feeder thread pushes `Au`. Each carries only
 /// owned/`Copy` data so the callback closures satisfy the `Send` bound and never touch the codec.
 enum DecodeEvent {
    /// A received access unit from the feeder, ready to queue into the decoder.
    Au(Frame),
    /// An input buffer slot freed (index) — we can queue an AU into it.
    InputAvailable(usize),
    /// A decoded frame is ready (buffer index + echoed pts).
    OutputAvailable { index: usize, pts_us: u64 },
    /// The output format changed — re-check the stream's colour signalling (HDR DataSpace).
    FormatChanged,
    /// The codec reported an error; `fatal` when neither recoverable nor transient.
    Error { fatal: bool },
 }
 /// The event-driven async decode loop (default; see [`run`]/[`USE_ASYNC_DECODE`]). The codec drives
 /// us: an async-notify callback fires the instant an input buffer frees or a frame finishes
 /// decoding, so a decoded frame is presented immediately instead of waiting out a poll interval (the
 /// latency the sync loop left on the table). The callbacks run on the codec's internal looper thread
 /// and only *push events* — every `AMediaCodec` buffer op stays on this thread, which owns the codec,
 /// sidestepping the self-reference that would arise from a callback calling back into the codec it's
 /// stored in. A small `pf-decode-feed` thread blocks on the network so this loop never does.
 fn run_async(
    client: Arc<NativeClient>,
    window: NativeWindow,
    shutdown: Arc<AtomicBool>,
    stats: Arc<crate::stats::VideoStats>,
    opts: DecodeOptions,
 ) {
    let DecodeOptions {
        decoder_name,
        ll_feature,
        low_latency_mode,
        is_tv,
    } = opts;
    boost_thread_priority();
    let mode = client.mode();
    let mime = codec_mime(client.codec);
    let mut codec = match create_codec(mime, decoder_name.as_deref()) {
        Some(c) => c,
        None => {
            log::error!("decode: no {mime} decoder on this device");
            return;
        }
    };
    let codec_name = codec.name().unwrap_or_default();
    stats.set_decoder(&codec_name, ll_feature);
    log::info!(
        "decode: codec mime = {mime}, decoder = {codec_name} (async, low-latency feature: {ll_feature})"
    );
    // The event channel: the callbacks + feeder push, this loop pulls. `Sender` is `Send`, so the
    // callback closures (each capturing a clone) satisfy the async-notify `Send` bound.
    let (ev_tx, ev_rx) = mpsc::channel::<DecodeEvent>();
    // Install the callbacks BEFORE configure()/start() so we're in async mode from the first buffer.
    // Each just forwards an index/flag — no codec access here (the codec owns these closures).
    {
        let out_tx = ev_tx.clone();
        let in_tx = ev_tx.clone();
        let fmt_tx = ev_tx.clone();
        let err_tx = ev_tx.clone();
        let cb = AsyncNotifyCallback {
            on_input_available: Some(Box::new(move |idx| {
                let _ = in_tx.send(DecodeEvent::InputAvailable(idx));
            })),
            on_output_available: Some(Box::new(move |idx, info| {
                let _ = out_tx.send(DecodeEvent::OutputAvailable {
                    index: idx,
                    pts_us: info.presentation_time_us().max(0) as u64,
                });
            })),
            on_format_changed: Some(Box::new(move |_fmt| {
                let _ = fmt_tx.send(DecodeEvent::FormatChanged);
            })),
            on_error: Some(Box::new(move |e, code, _detail| {
                let fatal = !code.is_recoverable() && !code.is_transient();
                log::warn!("decode: codec error {e:?} (fatal={fatal})");
                let _ = err_tx.send(DecodeEvent::Error { fatal });
            })),
        };
        if let Err(e) = codec.set_async_notify_callback(Some(cb)) {
            log::error!("decode: set_async_notify_callback failed: {e}");
            return;
        }
    }
    // Build the low-latency format (identical keys to the sync path).
    let mut format = MediaFormat::new();
    format.set_str("mime", mime);
    format.set_i32("width", mode.width as i32);
    format.set_i32("height", mode.height as i32);
    format.set_i32(
        "max-input-size",
        (mode.width * mode.height).max(2_000_000) as i32,
    );
    configure_low_latency(&mut format, &codec_name, low_latency_mode);
    if client.color.is_hdr() {
        match client.next_hdr_meta(Duration::from_millis(250)) {
            Ok(meta) => {
                format.set_buffer("hdr-static-info", &android_hdr_static_info(&meta));
                log::info!("decode: HDR static metadata applied (KEY_HDR_STATIC_INFO)");
            }
            Err(_) => {
                log::info!("decode: HDR session but no mastering metadata yet — DataSpace only")
            }
        }
    }
    if let Err(e) = codec.configure(&format, Some(&window), MediaCodecDirection::Decoder) {
        log::error!("decode: configure failed: {e}");
        return;
    }
    if let Err(e) = codec.start() {
        log::error!("decode: start failed: {e}");
        return;
    }
    log::info!(
        "decode: decoder started (async) at {}x{}",
        mode.width,
        mode.height
    );
    // The forced TV mode switch (`is_tv` ⇒ ALWAYS strategy) is part of the experimental stack;
    // off, every form factor gets the original soft seamless hint.
    if mode.refresh_hz > 0
        && !try_set_frame_rate(&window, mode.refresh_hz as f32, is_tv && low_latency_mode)
    {
        log::debug!(
            "decode: set_frame_rate({} Hz) unavailable/declined (non-fatal)",
            mode.refresh_hz
        );
    }
    // Skew-corrected latency stats (spec: design/stats-unification.md). Receipt stamps (keyed by the
    // pts we queue) live in a shared map: the feeder writes them at receipt, this loop pairs decoded
    // output back to them. Behind a `Mutex` since two threads touch it — only ever locked while the
    // HUD is visible.
    let clock_offset = client.clock_offset_ns;
    let in_flight = Arc::new(Mutex::new(VecDeque::<(u64, i128)>::new()));
    // Feeder thread: block on the network so this loop doesn't (an AU's arrival becomes an event that
    // wakes us immediately, with no input-side poll latency). It also records the `received` HUD stat.
    let feeder = {
        let client = client.clone();
        let stats = stats.clone();
        let in_flight = in_flight.clone();
        let shutdown = shutdown.clone();
        let ev_tx = ev_tx.clone();
        std::thread::Builder::new()
            .name("pf-decode-feed".into())
            .spawn(move || {
                feeder_loop(
                    client,
                    stats,
                    in_flight,
                    clock_offset as i128,
                    shutdown,
                    ev_tx,
                );
            })
            .ok()
    };
    drop(ev_tx); // only the feeder + callbacks keep the channel alive now
    // ADPF: same as the sync path — register this thread now, create the session lazily on the first
    // presented frame (by when the pump + audio + feeder threads have registered their tids too).
    let frame_period_ns = if mode.refresh_hz > 0 {
        1_000_000_000i64 / mode.refresh_hz as i64
    } else {
        0
    };
    client.register_hot_thread();
    let mut hint: Option<crate::adpf::HintSession> = None;
    let mut hint_tried = false;
    let mut free_inputs: VecDeque<usize> = VecDeque::new();
    let mut pending_aus: VecDeque<Frame> = VecDeque::new();
    let mut ready: Vec<OutputReady> = Vec::new();
    let mut applied_ds: Option<DataSpace> = None;
    let mut fed: u64 = 0;
    let mut rendered: u64 = 0;
    let mut discarded: u64 = 0;
    let mut last_dropped = client.frames_dropped();
    let mut last_kf_req: Option<Instant> = None;
    // Productive (dispatch+feed+present) time between displayed frames; reported to ADPF once one is
    // presented. The blocking event wait is excluded (idle, not work) — same accounting as the sync loop.
    let mut work_accum_ns: i64 = 0;
    let mut fatal = false;
    while !shutdown.load(Ordering::Relaxed) && !fatal {
        // Block for the next event (idle wait — excluded from the work tally). The short timeout
        // drives loss-recovery housekeeping when the pipeline is momentarily quiet.
        let ev0 = match ev_rx.recv_timeout(Duration::from_millis(5)) {
            Ok(ev) => Some(ev),
            Err(mpsc::RecvTimeoutError::Timeout) => None,
            Err(mpsc::RecvTimeoutError::Disconnected) => break,
        };
        let work_t0 = Instant::now();
        let mut fmt_dirty = false;
        let mut au_dropped = false;
        if let Some(ev) = ev0 {
            au_dropped |= dispatch_event(
                ev,
                &mut pending_aus,
                &mut free_inputs,
                &mut ready,
                &mut fmt_dirty,
                &mut fatal,
            );
        }
        // Coalesce every other event already queued into this one work pass — correct newest-only
        // presentation across a decode burst, and batched feeding.
        while let Ok(ev) = ev_rx.try_recv() {
            au_dropped |= dispatch_event(
                ev,
                &mut pending_aus,
                &mut free_inputs,
                &mut ready,
                &mut fmt_dirty,
                &mut fatal,
            );
        }
        if fmt_dirty {
            apply_hdr_dataspace(&codec, &window, &mut applied_ds);
        }
        feed_ready(&codec, &mut pending_aus, &mut free_inputs, &mut fed);
        let had_output = !ready.is_empty();
        present_ready(
            &codec,
            &mut ready,
            &stats,
            &in_flight,
            clock_offset,
            &mut rendered,
            &mut discarded,
        );
        work_accum_ns += work_t0.elapsed().as_nanos() as i64;
        if had_output {
            if !hint_tried {
                hint_tried = true;
                let tids = client.hot_thread_ids();
                // The pump/audio priority boost is part of the experimental low-latency stack; the
                // ADPF session itself predates it and always runs (max-performance bias gated inside).
                if low_latency_mode {
                    boost_hot_threads(&tids);
                }
                hint = crate::adpf::HintSession::create(frame_period_ns, &tids, low_latency_mode);
                log::info!(
                    "decode: ADPF hint session {} — {} hot thread(s), target {frame_period_ns} ns",
                    if hint.is_some() {
                        "active"
                    } else {
                        "unavailable"
                    },
                    tids.len(),
                );
            }
            if let Some(h) = &hint {
                h.report_actual(work_accum_ns);
            }
            work_accum_ns = 0;
            if rendered > 0 && rendered % 300 == 0 {
                log::info!("decode: fed={fed} rendered={rendered} discarded={discarded}");
            }
        }
        // Loss recovery: request an IDR when the reassembler's unrecoverable-drop count climbs (or we
        // dropped a parked AU on overflow), throttled so a multi-frame recovery gap doesn't flood the
        // control stream.
        let dropped = client.frames_dropped();
        if dropped > last_dropped || au_dropped {
            last_dropped = dropped;
            let now = Instant::now();
            if last_kf_req.is_none_or(|t| now.duration_since(t) >= Duration::from_millis(100)) {
                last_kf_req = Some(now);
                let _ = client.request_keyframe();
            }
        }
    }
    let _ = codec.stop();
    shutdown.store(true, Ordering::SeqCst); // ensure the feeder wakes and exits, then join it
    if let Some(j) = feeder {
        let _ = j.join();
    }
    log::info!("decode: stopped (async, fed={fed} rendered={rendered} discarded={discarded})");
 }
 /// The `pf-decode-feed` thread: block on the connector for the next access unit so the async loop
 /// never has to. Records the `received` HUD stat (receipt point) — including the Phase-2 host/network
 /// split from any matching 0xCF host timings — then hands the AU to the loop via the event channel.
 /// Exits when `shutdown` is set, the session closes, or the loop's receiver is gone.
 fn feeder_loop(
    client: Arc<NativeClient>,
    stats: Arc<crate::stats::VideoStats>,
    in_flight: Arc<Mutex<VecDeque<(u64, i128)>>>,
    clock_offset: i128,
    shutdown: Arc<AtomicBool>,
    ev_tx: mpsc::Sender<DecodeEvent>,
 ) {
    // Received AUs awaiting their 0xCF host timing (Phase-2 split), as (pts_ns, capture→received µs).
    let mut pending_split: VecDeque<(u64, u64)> = VecDeque::new();
    while !shutdown.load(Ordering::Relaxed) {
        match client.next_frame(Duration::from_millis(5)) {
            Ok(frame) => {
                if stats.enabled() {
                    let received_ns = now_realtime_ns();
                    let lat_ns = received_ns + clock_offset - frame.pts_ns as i128;
                    let lat_us =
                        (lat_ns > 0 && lat_ns < 10_000_000_000).then_some((lat_ns / 1000) as u64);
                    stats.note_received(frame.data.len(), lat_us, clock_offset != 0);
                    {
                        let mut g = in_flight
                            .lock()
                            .unwrap_or_else(std::sync::PoisonError::into_inner);
                        g.push_back((frame.pts_ns / 1000, received_ns));
                        if g.len() > IN_FLIGHT_CAP {
                            g.pop_front(); // stale — codec never echoed it back
                        }
                    }
                    if let Some(hostnet_us) = lat_us {
                        pending_split.push_back((frame.pts_ns, hostnet_us));
                        if pending_split.len() > PENDING_SPLIT_CAP {
                            pending_split.pop_front();
                        }
                    }
                    while let Ok(t) = client.next_host_timing(Duration::ZERO) {
                        if let Some(i) = pending_split.iter().position(|&(p, _)| p == t.pts_ns) {
                            let (_, hostnet_us) = pending_split.remove(i).unwrap();
                            stats.note_host_split(
                                t.host_us as u64,
                                hostnet_us.saturating_sub(t.host_us as u64),
                            );
                        }
                    }
                }
                if ev_tx.send(DecodeEvent::Au(frame)).is_err() {
                    break; // the decode loop is gone
                }
            }
            Err(PunktfunkError::NoFrame) => {} // timeout — re-check shutdown and poll again
            Err(_) => break,                   // session closed
        }
    }
 }
 /// Route one [`DecodeEvent`] into the loop's working sets. Returns `true` only when a parked AU was
 /// dropped on overflow (the caller then requests a keyframe).
 fn dispatch_event(
    ev: DecodeEvent,
    pending_aus: &mut VecDeque<Frame>,
    free_inputs: &mut VecDeque<usize>,
    ready: &mut Vec<OutputReady>,
    fmt_dirty: &mut bool,
    fatal: &mut bool,
 ) -> bool {
    match ev {
        DecodeEvent::Au(f) => {
            pending_aus.push_back(f);
            if pending_aus.len() > FRAME_PARK_CAP {
                pending_aus.pop_front(); // sustained overflow — drop oldest, signal a keyframe request
                return true;
            }
        }
        DecodeEvent::InputAvailable(i) => free_inputs.push_back(i),
        DecodeEvent::OutputAvailable { index, pts_us } => ready.push(OutputReady { index, pts_us }),
        DecodeEvent::FormatChanged => *fmt_dirty = true,
        DecodeEvent::Error { fatal: f } => {
            if f {
                *fatal = true;
            }
        }
    }
    false
 }
 /// Queue as many parked AUs as there are free input buffer slots (async mode: the indices come from
 /// `InputAvailable` callbacks, not a dequeue). Each AU is copied into its codec input buffer and
 /// submitted; a too-large AU is truncated (logged) rather than dropped.
 fn feed_ready(
    codec: &MediaCodec,
    pending_aus: &mut VecDeque<Frame>,
    free_inputs: &mut VecDeque<usize>,
    fed: &mut u64,
 ) {
    while !pending_aus.is_empty() && !free_inputs.is_empty() {
        let idx = free_inputs.pop_front().unwrap();
        let frame = pending_aus.pop_front().unwrap();
        let pts_us = frame.pts_ns / 1000;
        let Some(dst) = codec.input_buffer(idx) else {
            log::warn!("decode: input_buffer({idx}) returned None — dropping AU");
            continue;
        };
        let au = &frame.data;
        let n = au.len().min(dst.len());
        if n < au.len() {
            log::warn!(
                "decode: AU {} > input buffer {}, truncated",
                au.len(),
                dst.len()
            );
        }
        // SAFETY: `au` (wire AU) and `dst` (codec input buffer) are distinct allocations, both valid
        // for `n` bytes; `MaybeUninit<u8>` is layout-identical to `u8`, so this initializes dst[..n].
        unsafe {
            std::ptr::copy_nonoverlapping(au.as_ptr(), dst.as_mut_ptr().cast::<u8>(), n);
        }
        if let Err(e) = codec.queue_input_buffer_by_index(idx, 0, n, pts_us, 0) {
            log::warn!("decode: queue_input_buffer_by_index: {e}");
        } else {
            *fed += 1;
        }
    }
 }
 /// Present only the NEWEST ready output (render = true) and release the rest without rendering — a
 /// burst of stale frames on glass is worse than skipping to the freshest (the sync loop's newest-ready
 /// policy, callback-driven). Every dequeued buffer, rendered or not, is the HUD's `decoded`
 /// measurement point (it finished decoding either way); samples are recorded in pts order so the
 /// receipt-map eviction stays monotonic. `ready` is drained.
 fn present_ready(
    codec: &MediaCodec,
    ready: &mut Vec<OutputReady>,
    stats: &crate::stats::VideoStats,
    in_flight: &Mutex<VecDeque<(u64, i128)>>,
    clock_offset: i64,
    rendered: &mut u64,
    discarded: &mut u64,
 ) {
    if ready.is_empty() {
        return;
    }
    if stats.enabled() {
        let mut g = in_flight
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        for o in ready.iter() {
            note_decoded_pts(stats, &mut g, clock_offset, o.pts_us);
        }
    }
    let last = ready.len() - 1;
    for (i, o) in ready.drain(..).enumerate() {
        let render = i == last;
        match codec.release_output_buffer_by_index(o.index, render) {
            Ok(()) if render => *rendered += 1,
            Ok(()) => *discarded += 1,
            Err(e) => {
                log::warn!(
                    "decode: release_output_buffer_by_index({}, {render}): {e}",
                    o.index
                )
            }
        }
    }
 }
 /// React to an output-format change by signalling the stream's HDR dataspace on the Surface (SDR
 /// streams leave the default alone). The AMediaCodec analogue of the sync loop's `OutputFormatChanged`
 /// handling; safe to call repeatedly (`applied_ds` dedups).
 fn apply_hdr_dataspace(
    codec: &MediaCodec,
    window: &NativeWindow,
    applied_ds: &mut Option<DataSpace>,
 ) {
    if let Some(ds) = hdr_dataspace(codec) {
        if *applied_ds != Some(ds) {
            match window.set_buffers_data_space(ds) {
                Ok(()) => {
                    *applied_ds = Some(ds);
                    log::info!("decode: HDR stream → Surface dataspace {ds}");
                }
                Err(e) => {
                    log::warn!("decode: set_buffers_data_space({ds}) failed (non-fatal): {e}")
                }
            }
        }
    }
 }
 /// Raise the pipeline's OTHER hot threads — the core's data-plane pump (UDP receive + FEC
 /// reassembly) and the audio decode thread — toward the display band, matching this decode thread's
 /// own boost. `setpriority(PRIO_PROCESS, tid)` targets any task in the process, so we do it from
 /// here once their tids are known (the same set ADPF hints), without a per-platform priority hook
 /// in the shared core. Slightly below the decode thread's -10 so the display path still wins.
 /// Best-effort; skips this thread (already boosted) and is non-fatal if the platform refuses.
 fn boost_hot_threads(tids: &[i32]) {
    // SAFETY: `gettid` is an always-safe syscall on the calling thread.
    let self_tid = unsafe { libc::gettid() };
    for &tid in tids {
        if tid == self_tid {
            continue;
        }
        // SAFETY: `setpriority` with PRIO_PROCESS + a live tid in our own process is an always-safe
        // syscall; a refusal is reported via the return value, not UB.
        unsafe {
            if libc::setpriority(libc::PRIO_PROCESS, tid as libc::id_t, -8) != 0 {
                log::debug!("decode: setpriority(-8) on hot tid {tid} failed (non-fatal)");
            }
        }
    }
 }
 /// Best-effort: raise the decode thread toward Android's URGENT_DISPLAY band so background work
 /// can't preempt it under load (which shows up as late/dropped frames). Non-fatal if the platform
 /// refuses (foreground apps may set their own threads; the exact floor is policy-dependent).
@@ -343,23 +1017,48 @@ fn boost_thread_priority() {
    }
 }
-/// `ANativeWindow_setFrameRate` (NDK **API 30**) resolved from `libandroid.so` at runtime, so the lib
+/// Set the surface's frame-rate hint to the stream's refresh so SurfaceFlinger picks a matching
-/// still loads on our API-28 floor — a hard import of a >floor symbol makes `dlopen`/`System.load`
+/// display mode and aligns vsync (no 60-in-120 judder). Both NDK entry points sit above our API-28
-/// fail on every API-28/29 device, even where this path is never hit. Mirrors the dlsym approach in
+/// floor, so both are dlsym-resolved at runtime (a hard import of a >floor symbol makes
-/// [`crate::adpf`]. Returns `true` when the platform accepted the hint; `false` on API < 30 (symbol
+/// `dlopen`/`System.load` fail on every API-28/29 device, even where this path is never hit —
-/// absent) or when the platform declined. `compatibility` is fixed to the DEFAULT (0) policy.
+/// mirrors [`crate::adpf`]):
-fn try_set_frame_rate(window: &NativeWindow, frame_rate: f32) -> bool {
+///   - On a **TV** (`is_tv`): `ANativeWindow_setFrameRateWithChangeStrategy` (**API 31**) with
 ///     `changeFrameRateStrategy = ALWAYS`, which actively drives the HDMI output into the matching
 ///     mode (e.g. 60↔120) instead of leaving the panel at its default and judder-matching. The
 ///     forced switch may blank the panel briefly — acceptable once at stream start, not wanted on a
 ///     phone. Falls through to the 2-arg hint on API 30.
 ///   - Otherwise: `ANativeWindow_setFrameRate` (**API 30**) with `compatibility = DEFAULT` — the
 ///     softer, seamless-preferred hint for phones/tablets and the universal fallback.
 ///
 /// Returns `true` when the platform accepted a hint; `false` on API < 30 (symbols absent) or a
 /// decline.
 fn try_set_frame_rate(window: &NativeWindow, frame_rate: f32, is_tv: bool) -> bool {
    // int32_t ANativeWindow_setFrameRate(ANativeWindow*, float frameRate, int8_t compatibility)
    type SetFrameRateFn = unsafe extern "C" fn(*mut c_void, f32, i8) -> i32;
    // int32_t ANativeWindow_setFrameRateWithChangeStrategy(
    //     ANativeWindow*, float frameRate, int8_t compatibility, int8_t changeFrameRateStrategy)
    type SetFrameRateStrategyFn = unsafe extern "C" fn(*mut c_void, f32, i8, i8) -> i32;
    // SAFETY: `dlopen` of the always-mapped `libandroid.so` (only bumps its refcount; never closed —
-    // process-lifetime handle). `dlsym` returns null when the symbol is absent (device API < 30),
+    // process-lifetime handle). Each `dlsym` returns null when the symbol is absent (device below the
-    // checked before transmuting the non-null pointer to its fn-pointer type. `window.ptr()` is the
+    // symbol's API level), checked before transmuting the non-null pointer to its fn-pointer type.
-    // live `ANativeWindow` this `NativeWindow` owns for the call's duration.
+    // `window.ptr()` is the live `ANativeWindow` this `NativeWindow` owns for the call's duration.
    unsafe {
        let lib = libc::dlopen(c"libandroid.so".as_ptr(), libc::RTLD_NOW);
        if lib.is_null() {
            return false;
        }
        // TV: prefer the API-31 change-strategy form to force the mode switch (strategy 1 = ALWAYS,
        // compatibility 0 = DEFAULT). Absent on API 30 ⇒ fall through to the 2-arg hint below.
        if is_tv {
            let sym = libc::dlsym(
                lib,
                c"ANativeWindow_setFrameRateWithChangeStrategy".as_ptr(),
            );
            if !sym.is_null() {
                let set = std::mem::transmute::<*mut c_void, SetFrameRateStrategyFn>(sym);
                return set(window.ptr().as_ptr().cast(), frame_rate, 0, 1) == 0;
            }
        }
        let sym = libc::dlsym(lib, c"ANativeWindow_setFrameRate".as_ptr());
        if sym.is_null() {
            return false; // device API < 30 — no per-surface frame-rate hint
@@ -499,7 +1198,22 @@ fn note_decoded(
    clock_offset: i64,
    buf: &OutputBuffer<'_>,
 ) {
-    let pts_us = buf.info().presentation_time_us().max(0) as u64;
+    note_decoded_pts(
        stats,
        in_flight,
        clock_offset,
        buf.info().presentation_time_us().max(0) as u64,
    );
 }
 /// The [`note_decoded`] body keyed by the echoed `presentationTimeUs` directly — the async loop has
 /// the pts (from the output callback's `BufferInfo`) but no borrowed `OutputBuffer`, so it calls this.
 fn note_decoded_pts(
    stats: &crate::stats::VideoStats,
    in_flight: &mut VecDeque<(u64, i128)>,
    clock_offset: i64,
    pts_us: u64,
 ) {
    let decoded_ns = now_realtime_ns();
    // Pair the echoed pts back to its receipt stamp, evicting stale (older) entries as we go.
    let mut received_ns = None;
@@ -1,5 +1,5 @@
 //! LAN host discovery over mDNS, in Rust via `mdns-sd` — the same crate + service type the
-//! Linux/Windows clients use (`clients/linux/src/discovery.rs`), exposed to Kotlin over JNI.
+//! Linux/Windows clients use (`crates/pf-client-core/src/discovery.rs`), exposed to Kotlin over JNI.
 //!
 //! Why not `NsdManager`: that API delegates to a per-OEM system mDNS daemon whose reliability
 //! varies wildly (the Android client's discovery was "mostly broken"). Browsing in our own Rust
@@ -44,7 +44,10 @@ mod stats;
 mod wol;
 /// Initialize `android_logger` once when the JVM loads the library. Logs land in logcat under the
-/// `punktfunk` tag. Android-only — there is no JVM (and no logcat) on the host build.
+/// `punktfunk` tag. Core `tracing` events (transport warnings: socket-buffer clamp, QoS failures)
 /// arrive here too: tracing's "log" feature — declared explicitly in Cargo.toml rather than relied
 /// on via quinn's defaults — forwards them as `log` records since no tracing subscriber is ever
 /// installed. Android-only — there is no JVM (and no logcat) on the host build.
 #[cfg(target_os = "android")]
 #[no_mangle]
 pub extern "system" fn JNI_OnLoad(
@@ -32,8 +32,23 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeGenerateIde
    }
 }
 /// `NativeBridge.nativeSetLowLatencyMode(enabled)` — apply the user's "Low-latency mode
 /// (experimental)" toggle to the process-wide transport defaults, today just DSCP/QoS marking on
 /// the media sockets. Must be called BEFORE `nativeConnect` (the tag is applied at socket
 /// creation); Kotlin's one connect choke point (`HostConnect.connectToHost`) does. The rest of the
 /// toggle rides explicit per-session parameters (`nativeStartVideo` / `nativeStartAudio`).
 #[no_mangle]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSetLowLatencyMode(
    _env: JNIEnv,
    _this: JObject,
    enabled: jboolean,
 ) {
    punktfunk_core::transport::set_dscp_default(enabled != 0);
 }
 /// `NativeBridge.nativeConnect(host, port, w, h, hz, certPem, keyPem, pinHex, bitrateKbps,
-/// compositorPref, gamepadPref, hdrEnabled, audioChannels, preferredCodec, timeoutMs): Long`.
+/// compositorPref, gamepadPref, hdrEnabled, audioChannels, preferredCodec, timeoutMs, launch): Long`.
 /// `launch` (empty ⇒ none) is a store-qualified library id to boot straight into a game.
 /// `certPem`/`keyPem` empty = anonymous, else presented as the persistent identity. `pinHex` empty
 /// = TOFU (read `nativeHostFingerprint` after), else 64-hex SHA-256 to pin the host (mismatch → 0).
 /// `bitrateKbps` 0 = host default. `compositorPref`/`gamepadPref` are `CompositorPref`/`GamepadPref`
@@ -63,6 +78,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
    audio_channels: jint,
    preferred_codec: jint,
    timeout_ms: jint,
    launch: JString<'local>,
 ) -> jlong {
    let host: String = match env.get_string(&host) {
        Ok(s) => s.into(),
@@ -74,6 +90,13 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
        .unwrap_or_default();
    let key: String = env.get_string(&key_pem).map(Into::into).unwrap_or_default();
    let pin_hex: String = env.get_string(&pin_hex).map(Into::into).unwrap_or_default();
    // A store-qualified library id (`steam:<appid>` / `custom:<id>`) to boot straight into a game;
    // null / empty ⇒ None (a plain desktop connect). Rides the Hello as `launch`.
    let launch: Option<String> = env
        .get_string(&launch)
        .map(Into::into)
        .ok()
        .filter(|s: &String| !s.is_empty());
    let identity: Option<(String, String)> = if cert.is_empty() || key.is_empty() {
        None
@@ -124,7 +147,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
        // + the soft `preferred_codec` and echoes it in `connector.codec`, which drives the mime below.
        punktfunk_core::quic::CODEC_H264 | punktfunk_core::quic::CODEC_HEVC,
        preferred_codec.clamp(0, u8::MAX as jint) as u8,
-        None,     // launch: default app
+        launch,   // a store-qualified library id to boot into a game, or None for the desktop
        pin,      // Some → Crypto on host-fp mismatch
        identity, // owned (cert, key) PEM, or None (anonymous)
        // Handshake budget from Kotlin: ~10 s for a normal connect, ~185 s for "request access"
@@ -170,6 +193,30 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClose(
    })
 }
 /// `NativeBridge.nativeDisconnectQuit(handle)` — signal a DELIBERATE user quit before `nativeClose`,
 /// so the session closes with `QUIT_CLOSE_CODE` and the host tears it down immediately instead of
 /// holding the keep-alive linger for a reconnect. Call from an explicit disconnect action only (a
 /// plain drop / app-background keeps the linger). The handle is only BORROWED (not freed). No-op on `0`.
 ///
 /// # Safety contract
 /// `handle` must be `0` or a live handle from [`Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect`],
 /// not freed / closed concurrently with this call (Kotlin still owns it and closes it via `nativeClose`).
 #[no_mangle]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDisconnectQuit(
    _env: JNIEnv,
    _this: JObject,
    handle: jlong,
 ) {
    jni_guard((), || {
        if handle != 0 {
            // SAFETY: per the contract, `handle` is a live `Box<SessionHandle>` — we only borrow it
            // (no drop), so it stays owned by Kotlin for the later `nativeClose`.
            let sh = unsafe { &*(handle as *const SessionHandle) };
            sh.client.disconnect_quit();
        }
    })
 }
 /// `NativeBridge.nativeHostFingerprint(handle): String` — the SHA-256 (64-hex) of the cert the host
 /// presented on this connection. Valid after a successful `nativeConnect`; Kotlin pins it on a TOFU
 /// connect. `""` on a `0` handle.
@@ -192,6 +239,28 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeHostFingerp
    }
 }
 /// `NativeBridge.nativeSessionEnded(handle): Boolean` — has the underlying QUIC session ended?
 /// `true` once the connection closed (a host suspend / crash / network drop idle-timed it out, or the
 /// host closed it) — from then on no more frames arrive and the video sits frozen on its last one.
 /// Kotlin's stream watchdog polls this (~1 Hz) to leave a dead stream and return to the menu (where
 /// the user can Wake-on-LAN the host) instead of stranding them on a frozen frame. `false` on a `0`
 /// handle. Cheap (one atomic load); safe on the UI thread.
 #[no_mangle]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSessionEnded(
    _env: JNIEnv,
    _this: JObject,
    handle: jlong,
 ) -> jboolean {
    jni_guard(0, || {
        if handle == 0 {
            return 0;
        }
        // SAFETY: live handle per the nativeConnect/nativeClose contract.
        let h = unsafe { &*(handle as *const SessionHandle) };
        jboolean::from(h.client.is_session_ended())
    })
 }
 /// `NativeBridge.nativePair(host, port, certPem, keyPem, pin, name): String` — run the SPAKE2 PIN
 /// ceremony, presenting our persistent identity. On success returns the host's verified fingerprint
 /// (64-hex) to persist + pin; on any failure (wrong PIN / MITM / host reject / unreachable) returns
@@ -2,20 +2,31 @@
 //! ~1 Hz decode-stats drain for the HUD.
 use jni::objects::JObject;
-use jni::sys::{jboolean, jdoubleArray, jlong, jsize};
+// Used only by the android-gated `nativeStartVideo`; on the host build that fn is cfg'd out.
 #[cfg(target_os = "android")]
 use jni::objects::JString;
 use jni::sys::{jboolean, jdoubleArray, jlong, jsize, jstring};
 use jni::JNIEnv;
 use super::{jni_guard, SessionHandle};
-/// `NativeBridge.nativeStartVideo(handle, surface)` — wrap the SurfaceView's `Surface` as an
+/// `NativeBridge.nativeStartVideo(handle, surface, decoderName, lowLatencyMode, lowLatencyFeature)`
-/// `ANativeWindow` and start the HEVC decode thread rendering onto it. No-op if already started.
+/// — wrap the SurfaceView's `Surface` as an `ANativeWindow` and start the decode thread rendering
 /// onto it. `decoderName` is the codec Kotlin ranked from `MediaCodecList` (`""` = let the platform
 /// resolve the default for the MIME); `lowLatencyMode` is the user's master toggle;
 /// `lowLatencyFeature` is whether that decoder advertised `FEATURE_LowLatency` (HUD label only).
 /// No-op if already started.
 #[cfg(target_os = "android")]
 #[no_mangle]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
-    env: JNIEnv,
+    mut env: JNIEnv,
    _this: JObject,
    handle: jlong,
    surface: JObject,
    decoder_name: JString,
    low_latency_mode: jboolean,
    ll_feature: jboolean,
    is_tv: jboolean,
 ) {
    use super::VideoThread;
    use std::sync::atomic::AtomicBool;
@@ -24,6 +35,12 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
    if handle == 0 {
        return;
    }
    // The decoder name Kotlin picked (empty string / read failure ⇒ None ⇒ default resolver).
    let decoder = env
        .get_string(&decoder_name)
        .ok()
        .map(String::from)
        .filter(|s| !s.is_empty());
    // SAFETY: live handle per the nativeConnect/nativeClose contract.
    let h = unsafe { &*(handle as *const SessionHandle) };
    let mut guard = h.video.lock().unwrap();
@@ -48,13 +65,67 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
    let client = h.client.clone();
    let sd = shutdown.clone();
    let st = h.stats.clone(); // session-lifetime stats (gate survives surface recreate)
    let opts = crate::decode::DecodeOptions {
        decoder_name: decoder,
        ll_feature: ll_feature != 0,
        low_latency_mode: low_latency_mode != 0,
        is_tv: is_tv != 0,
    };
    let join = std::thread::Builder::new()
        .name("pf-decode".into())
-        .spawn(move || crate::decode::run(client, window, sd, st))
+        .spawn(move || crate::decode::run(client, window, sd, st, opts))
        .ok();
    *guard = Some(VideoThread { shutdown, join });
 }
 /// `NativeBridge.nativeVideoMime(handle): String` — the MediaCodec MIME for the codec the host
 /// resolved (`"video/hevc"` / `"video/avc"` / `"video/av01"`), so Kotlin can rank `MediaCodecList`
 /// decoders for it before calling [`Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo`].
 /// Empty string on a `0` handle. Cheap; safe on the UI thread.
 #[cfg(target_os = "android")]
 #[no_mangle]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoMime<'local>(
    env: JNIEnv<'local>,
    _this: JObject<'local>,
    handle: jlong,
 ) -> jstring {
    jni_guard(std::ptr::null_mut(), || {
        if handle == 0 {
            return std::ptr::null_mut();
        }
        // SAFETY: live handle per the nativeConnect/nativeClose contract.
        let h = unsafe { &*(handle as *const SessionHandle) };
        match env.new_string(crate::decode::codec_mime(h.client.codec)) {
            Ok(s) => s.into_raw(),
            Err(_) => std::ptr::null_mut(),
        }
    })
 }
 /// `NativeBridge.nativeVideoDecoderLabel(handle): String` — the resolved decoder identity for the
 /// HUD, e.g. `c2.qti.avc.decoder · low-latency`, or `""` before the decode thread has resolved one.
 /// One-shot (the decoder is fixed for the session); poll once after the HUD appears. Not
 /// android-gated — pure `jni` + a lock, so it links on the host build too (Kotlin only calls it on
 /// device).
 #[no_mangle]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoDecoderLabel<'local>(
    env: JNIEnv<'local>,
    _this: JObject<'local>,
    handle: jlong,
 ) -> jstring {
    jni_guard(std::ptr::null_mut(), || {
        if handle == 0 {
            return std::ptr::null_mut();
        }
        // SAFETY: live handle per the nativeConnect/nativeClose contract.
        let h = unsafe { &*(handle as *const SessionHandle) };
        match env.new_string(h.stats.decoder_label()) {
            Ok(s) => s.into_raw(),
            Err(_) => std::ptr::null_mut(),
        }
    })
 }
 /// `NativeBridge.nativeStopVideo(handle)` — stop + join the decode thread (without closing the
 /// session). No-op on `0`.
 #[no_mangle]
@@ -162,14 +233,17 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSetVideoSta
    })
 }
-/// `NativeBridge.nativeStartAudio(handle)` — start the Opus→AAudio playback thread. No-op if already
+/// `NativeBridge.nativeStartAudio(handle, lowLatencyMode)` — start the Opus→AAudio playback thread.
-/// started or on a `0` handle. Best-effort: a failure leaves video streaming.
+/// `lowLatencyMode` (the experimental toggle) tags the stream usage=Game for the HAL's game-audio
 /// routing. No-op if already started or on a `0` handle. Best-effort: a failure leaves video
 /// streaming.
 #[cfg(target_os = "android")]
 #[no_mangle]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartAudio(
    _env: JNIEnv,
    _this: JObject,
    handle: jlong,
    low_latency_mode: jboolean,
 ) {
    if handle == 0 {
        return;
@@ -180,7 +254,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartAudio(
    if guard.is_some() {
        return; // already playing
    }
-    match crate::audio::AudioPlayback::start(h.client.clone()) {
+    match crate::audio::AudioPlayback::start(h.client.clone(), low_latency_mode != 0) {
        Some(p) => *guard = Some(p),
        None => log::error!("nativeStartAudio: playback init failed (video unaffected)"),
    }
@@ -22,9 +22,21 @@ pub struct VideoStats {
    /// they (and the caller's latency computation — see `enabled`) early-out on this flag alone.
    /// Off until Kotlin shows the HUD.
    enabled: AtomicBool,
    /// The resolved decoder identity for the HUD: the codec's actual `AMediaCodec` name (e.g.
    /// `c2.qti.avc.decoder`) and whether it advertised `FEATURE_LowLatency`. Set once when the
    /// decode thread creates the codec (`set_decoder`), read one-shot by `nativeVideoDecoderLabel`.
    /// Separate from `inner` (never touched per-frame) so naming it costs nothing on the hot path.
    decoder: Mutex<Option<DecoderInfo>>,
    inner: Mutex<Inner>,
 }
 /// The chosen decoder's identity, surfaced on the stats HUD so before/after latency comparisons
 /// name the codec that produced them.
 struct DecoderInfo {
    name: String,
    low_latency: bool,
 }
 struct Inner {
    window_start: Instant,
    frames: u64,
@@ -79,6 +91,7 @@ impl VideoStats {
    pub fn new() -> VideoStats {
        VideoStats {
            enabled: AtomicBool::new(false),
            decoder: Mutex::new(None),
            inner: Mutex::new(Inner {
                window_start: Instant::now(),
                frames: 0,
@@ -121,6 +134,36 @@ impl VideoStats {
        }
    }
    /// Record the resolved decoder identity for the HUD — the codec's real `AMediaCodec` name and
    /// whether it reported `FEATURE_LowLatency`. Called once from the decode thread right after the
    /// codec is created (before `configure`), overwriting any prior value on a surface recreate.
    // Set only by the android-only decode thread; unreferenced on the host build — expected.
    #[cfg_attr(not(target_os = "android"), allow(dead_code))]
    pub fn set_decoder(&self, name: &str, low_latency: bool) {
        let mut g = self
            .decoder
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        *g = Some(DecoderInfo {
            name: name.to_owned(),
            low_latency,
        });
    }
    /// The decoder label for the HUD, e.g. `c2.qti.avc.decoder · low-latency`, or `""` before the
    /// decode thread has resolved one. Cheap (a lock + a string build); safe on the UI thread.
    pub fn decoder_label(&self) -> String {
        let g = self
            .decoder
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        match &*g {
            Some(d) if d.low_latency => format!("{} · low-latency", d.name),
            Some(d) => d.name.clone(),
            None => String::new(),
        }
    }
    /// Record one received access unit: its wire size and (if in range) its capture→received
    /// `host+network` stage sample. Receipt is the fps/goodput counting point per the spec.
    // Driven only by the android-only decode thread; unreferenced on the host build — expected.
@@ -432,6 +432,7 @@
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_FILE = Config/Info.plist;
 				INFOPLIST_KEY_CFBundleDisplayName = Punktfunk;
 				INFOPLIST_KEY_GCSupportsControllerUserInteraction = YES;
 				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.utilities";
 				INFOPLIST_KEY_NSLocalNetworkUsageDescription = "Punktfunk connects directly to your punktfunk host on the local network to stream video, audio, and input.";
 				INFOPLIST_KEY_NSMicrophoneUsageDescription = "Your microphone is streamed to the connected punktfunk host, where it appears as a virtual microphone.";
@@ -471,6 +472,7 @@
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_FILE = Config/Info.plist;
 				INFOPLIST_KEY_CFBundleDisplayName = Punktfunk;
 				INFOPLIST_KEY_GCSupportsControllerUserInteraction = YES;
 				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.utilities";
 				INFOPLIST_KEY_NSLocalNetworkUsageDescription = "Punktfunk connects directly to your punktfunk host on the local network to stream video, audio, and input.";
 				INFOPLIST_KEY_NSMicrophoneUsageDescription = "Your microphone is streamed to the connected punktfunk host, where it appears as a virtual microphone.";
@@ -276,7 +276,10 @@ final class SessionModel: ObservableObject {
        disconnect()
    }
-    func disconnect() {
+    /// Tear the session down. `deliberate` (the default) means a user-initiated quit — signal
    /// `disconnectQuit()` so the host skips the keep-alive linger; `sessionEnded()` (a host-ended /
    /// dropped session) passes `false` to leave the linger intact.
    func disconnect(deliberate: Bool = true) {
        statsTimer?.invalidate()
        statsTimer = nil
        let audio = self.audio
@@ -294,6 +297,8 @@ final class SessionModel: ObservableObject {
            Task.detached {
                audio?.stop()
                feedback?.stop()
                // Deliberate user quit → tell the host to skip the keep-alive linger (must precede close).
                if deliberate { conn.disconnectQuit() }
                conn.close()
            }
        } else {
@@ -321,7 +326,7 @@ final class SessionModel: ObservableObject {
    func sessionEnded() {
        guard connection != nil else { return }
        let name = activeHost?.displayName ?? "host"
-        disconnect()
+        disconnect(deliberate: false) // host/network ended it — keep the linger for a reconnect
        errorMessage = "Session ended by \(name)."
    }
@@ -759,6 +759,17 @@ public final class PunktfunkConnection {
        _ = punktfunk_connection_send_input(h, &ev)
    }
    /// Signal a **deliberate** user-initiated quit before ``close()``: the connection closes with
    /// `QUIT_CLOSE_CODE` (81) so the host tears the session down immediately instead of holding the
    /// keep-alive linger for a reconnect. Call only from an explicit "Disconnect" action — NOT from a
    /// network drop / host-ended / app-background (those keep the linger). Idempotent, safe pre-close.
    public func disconnectQuit() {
        abiLock.lock()
        defer { abiLock.unlock() }
        guard let h = handle, !closeRequested else { return }
        punktfunk_connection_disconnect_quit(h)
    }
    /// Close the connection and free the handle. Safe from any thread, idempotent; waits
    /// for in-flight pulls (≤ their timeouts) before tearing down.
    public func close() {
@@ -84,15 +84,6 @@ public final class InputCapture {
    /// its Esc suppression need it in both states).
    private var cmdKeysDown: Set<UInt32> = []
    #if os(macOS)
    /// Previous raw `NSEvent.modifierFlags.rawValue` (LOW 16 bits intact — those carry the
    /// device-dependent L/R bits). Modifier keys never fire keyDown/keyUp on macOS; they
    /// arrive as flagsChanged, which doesn't carry down-vs-up — we recover that by diffing
    /// this snapshot. Resynced (not diffed) while forwarding is off so a modifier held
    /// across a capture toggle can't produce a phantom transition on re-engage.
    private var prevModFlags: UInt = 0
    #endif
    /// While true, mouse/keyboard flow to the host and key NSEvents are swallowed
    /// locally; while false the user is interacting with the local UI (dragging the
    /// window, clicking the HUD) and nothing is forwarded. Main-queue only.
@@ -279,12 +270,6 @@ public final class InputCapture {
        residualY = 0
        residualScrollX = 0
        residualScrollY = 0
        #if os(macOS)
        // Drop the modifier snapshot too: a flagsChanged transition can be missed if focus
        // leaves mid-chord, and the next handleFlagsChanged resyncs from a clean slate (it
        // resyncs while released anyway, but this keeps stuck state from outliving a blur).
        prevModFlags = 0
        #endif
    }
    /// Release any held MOUSE buttons host-side, leaving keyboard state untouched. Used when
@@ -359,39 +344,52 @@ public final class InputCapture {
    }
    /// NSEvent modifier path (macOS): modifier keys never fire keyDown/keyUp — they arrive
-    /// as flagsChanged, which carries no down-vs-up. We diff the raw flags against the prior
+    /// as flagsChanged, which carries no down-vs-up. `keyCode` names the key that changed
-    /// snapshot to recover each transition, and the changed key's L/R identity from the
+    /// (kVK_Control & co., already L/R-specific); `resolveModifier` recovers the direction
-    /// device-dependent bits in the LOW 16 bits (the .deviceIndependentFlagsMask the ⌘⎋
+    /// from the flags. Fed `event.keyCode` + `UInt(event.modifierFlags.rawValue)` — LOW 16
-    /// monitor uses deliberately strips exactly these — do NOT pre-mask here). Each side maps
+    /// bits intact, they carry the device-dependent L/R bits (the .deviceIndependentFlagsMask
-    /// to the same L/R modifier VK `hidToVK` already emits, so the host needs no change.
+    /// the ⌘⎋ monitor uses deliberately strips exactly these — do NOT pre-mask here).
-    /// Fed `UInt(event.modifierFlags.rawValue)`.
+    public func handleFlagsChanged(keyCode: UInt16, rawFlags: UInt) {
-    public func handleFlagsChanged(_ rawFlags: UInt) {
+        if inputDebug {
-        // While released we only resync the snapshot, so a modifier held across a capture
+            inputLog.debug(
-        // toggle doesn't show up as a spurious transition the moment forwarding re-engages.
+                "flagsChanged keyCode \(keyCode, privacy: .public) flags 0x\(String(rawFlags, radix: 16), privacy: .public) forwarding \(self.forwarding, privacy: .public)")
        guard forwarding else {
            prevModFlags = rawFlags
            return
        }
-        // (device-dependent mask, VK). LOW-16-bit masks from IOLLEvent.h (NX_DEVICE*MASK):
+        guard forwarding else { return }
-        // Lshift 0x2 Rshift 0x4 | Lctrl 0x1 Rctrl 0x2000 | Lalt 0x20 Ralt 0x40 | Lcmd 0x8 Rcmd 0x10.
+        guard let (vk, down) = Self.resolveModifier(
-        let table: [(UInt, UInt32)] = [
+            keyCode: keyCode, rawFlags: rawFlags, isDown: { pressedVKs.contains($0) })
-            (0x2, 0xA0), (0x4, 0xA1), // VK_LSHIFT / VK_RSHIFT
+        else { return } // Fn / Caps Lock / unknown — nothing the host consumes on this path
            (0x1, 0xA2), (0x2000, 0xA3), // VK_LCONTROL / VK_RCONTROL
            (0x20, 0xA4), (0x40, 0xA5), // VK_LMENU / VK_RMENU (left/right alt-option)
            (0x8, 0x5B), (0x10, 0x5C), // VK_LWIN / VK_RWIN (left/right command)
        ]
        for (mask, vk) in table {
            let now = (rawFlags & mask) != 0
            let was = (prevModFlags & mask) != 0
            guard now != was else { continue }
        // Keep cmdKeysDown in step (the ⌘⎋ toggle + Esc suppression read it); sendKey
        // adds the VK to pressedVKs so releaseAll/blur flushes a held modifier cleanly.
        if vk == 0x5B || vk == 0x5C {
-                if now { cmdKeysDown.insert(vk) } else { cmdKeysDown.remove(vk) }
+            if down { cmdKeysDown.insert(vk) } else { cmdKeysDown.remove(vk) }
        }
-            sendKey(vk, down: now)
+        sendKey(vk, down: down)
    }
-        prevModFlags = rawFlags
+
    /// Resolve one flagsChanged transition to (Windows VK, down). The changed key is
    /// `keyCode`; the direction comes from the flags. The device-dependent L/R bits (LOW
    /// 16 bits, NX_DEVICE*KEYMASK) disambiguate the two same-class keys, but some
    /// keyboards ship flagsChanged WITHOUT them — only the device-independent class
    /// bit (NX_CONTROLMASK & co.) is set. A pure diff of the device bits silently drops
    /// those keys (seen live: Control never forwarded), so this is keyCode-driven with the
    /// flags as evidence: class bit clear → the key went up; device bits present → they
    /// say which side is held now; class bit set with NO device bits → flip the held state
    /// we track (`isDown`, from pressedVKs — SDL ships the same fallback). Each keyCode
    /// maps to the L/R modifier VK `hidToVK` already emits, so the host needs no change.
    /// Returns nil for modifiers the host doesn't consume on this path (Fn, Caps Lock).
    static func resolveModifier(
        keyCode: UInt16, rawFlags: UInt, isDown: (UInt32) -> Bool
    ) -> (vk: UInt32, down: Bool)? {
        guard let mod = modifierBits[keyCode] else { return nil }
        let down: Bool
        if rawFlags & mod.classMask == 0 {
            down = false
        } else if rawFlags & (mod.deviceBit | mod.siblingBit) != 0 {
            down = rawFlags & mod.deviceBit != 0
        } else {
            down = !isDown(mod.vk)
        }
        return (mod.vk, down)
    }
    #endif
@@ -98,5 +98,23 @@ extension InputCapture {
        m[0x47] = 0x90 // KP clear sits where NumLock is → VK_NUMLOCK. (KP equals 0x51 dropped.)
        return m
    }()
    /// NSEvent.keyCode of each modifier key (kVK_Shift & co. — modifiers arrive only as
    /// flagsChanged) → its Windows VK plus the `NSEvent.modifierFlags` bits that describe
    /// it: `classMask` is the device-INDEPENDENT NX_*MASK for the modifier class,
    /// `deviceBit`/`siblingBit` the device-dependent bits (LOW 16 bits, NX_DEVICE*KEYMASK
    /// in IOLLEvent.h) for this key and its opposite-side twin. Consumed by
    /// `resolveModifier`, which explains why both kinds of bit are needed.
    static let modifierBits:
        [UInt16: (vk: UInt32, classMask: UInt, deviceBit: UInt, siblingBit: UInt)] = [
            56: (0xA0, 0x2_0000, 0x2, 0x4), // left shift → VK_LSHIFT
            60: (0xA1, 0x2_0000, 0x4, 0x2), // right shift → VK_RSHIFT
            59: (0xA2, 0x4_0000, 0x1, 0x2000), // left control → VK_LCONTROL
            62: (0xA3, 0x4_0000, 0x2000, 0x1), // right control → VK_RCONTROL
            58: (0xA4, 0x8_0000, 0x20, 0x40), // left option → VK_LMENU
            61: (0xA5, 0x8_0000, 0x40, 0x20), // right option → VK_RMENU
            55: (0x5B, 0x10_0000, 0x8, 0x10), // left command → VK_LWIN
            54: (0x5C, 0x10_0000, 0x10, 0x8), // right command → VK_RWIN
        ]
    #endif
 }
@@ -346,10 +346,13 @@ public final class StreamLayerView: NSView {
        super.keyUp(with: event)
    }
    /// Modifier keys (shift/control/option/command) arrive ONLY as flagsChanged on macOS,
-    /// never keyDown/keyUp — InputCapture diffs the raw flags to recover each L/R down/up.
+    /// never keyDown/keyUp — the changed key is `event.keyCode`; InputCapture resolves the
    /// down-vs-up direction from the flags (diffing the device-dependent flag bits alone
    /// proved unreliable — some keyboards omit them, which silently dropped Control).
    public override func flagsChanged(with event: NSEvent) {
        if captured, let inputCapture {
-            inputCapture.handleFlagsChanged(UInt(event.modifierFlags.rawValue))
+            inputCapture.handleFlagsChanged(
                keyCode: event.keyCode, rawFlags: UInt(event.modifierFlags.rawValue))
            return
        }
        super.flagsChanged(with: event)
@@ -0,0 +1,87 @@
 #if os(macOS)
 import XCTest
@testable import PunktfunkKit
 /// Pins the macOS flagsChanged → modifier-VK resolution (InputCapture.resolveModifier).
 /// Modifier keys arrive only as flagsChanged, which carries no down-vs-up: the changed key
 /// is the event's keyCode, and the direction is recovered from the flag bits — with a
 /// held-state fallback for keyboards that omit the device-dependent L/R bits (the gap that
 /// used to silently drop Control when the transition was diffed from those bits alone).
 final class ModifierResolveTests: XCTestCase {
    /// Resolve with a fixed already-held answer for the fallback path.
    private func resolve(
        keyCode: UInt16, rawFlags: UInt, held: Bool = false
    ) -> (vk: UInt32, down: Bool)? {
        InputCapture.resolveModifier(keyCode: keyCode, rawFlags: rawFlags) { _ in held }
    }
    // MARK: Keyboards that report the device-dependent L/R bits (the common case)
    func testControlPressAndReleaseWithDeviceBits() {
        // Real left-Control down: NX_CONTROLMASK | NX_DEVICELCTLKEYMASK (+ misc low bits).
        let down = resolve(keyCode: 59, rawFlags: 0x4_0101)
        XCTAssertEqual(down?.vk, 0xA2) // VK_LCONTROL
        XCTAssertEqual(down?.down, true)
        // Release: the class mask is gone entirely.
        let up = resolve(keyCode: 59, rawFlags: 0x100)
        XCTAssertEqual(up?.vk, 0xA2)
        XCTAssertEqual(up?.down, false)
    }
    func testRightControlUsesItsOwnDeviceBit() {
        let down = resolve(keyCode: 62, rawFlags: 0x4_2000)
        XCTAssertEqual(down?.vk, 0xA3) // VK_RCONTROL
        XCTAssertEqual(down?.down, true)
    }
    func testReleasingOneOfTwoHeldControls() {
        // Left goes up while right stays held: class mask still set, right device bit
        // still set, LEFT device bit cleared — the left key must resolve as UP.
        let leftUp = resolve(keyCode: 59, rawFlags: 0x4_2000, held: true)
        XCTAssertEqual(leftUp?.vk, 0xA2)
        XCTAssertEqual(leftUp?.down, false)
    }
    func testEverySideMapsToItsOwnVK() {
        XCTAssertEqual(resolve(keyCode: 56, rawFlags: 0x2_0002)?.vk, 0xA0) // VK_LSHIFT
        XCTAssertEqual(resolve(keyCode: 60, rawFlags: 0x2_0004)?.vk, 0xA1) // VK_RSHIFT
        XCTAssertEqual(resolve(keyCode: 58, rawFlags: 0x8_0020)?.vk, 0xA4) // VK_LMENU
        XCTAssertEqual(resolve(keyCode: 61, rawFlags: 0x8_0040)?.vk, 0xA5) // VK_RMENU
        XCTAssertEqual(resolve(keyCode: 55, rawFlags: 0x10_0008)?.vk, 0x5B) // VK_LWIN
        XCTAssertEqual(resolve(keyCode: 54, rawFlags: 0x10_0010)?.vk, 0x5C) // VK_RWIN
        for (_, down) in [56, 60, 58, 61, 55, 54].compactMap({
            self.resolve(keyCode: UInt16($0), rawFlags: 0xFF_FFFF)
        }) {
            XCTAssertTrue(down)
        }
    }
    // MARK: Keyboards that DON'T report the device bits (the bug this resolver fixes)
    func testControlPressWithoutDeviceBitsFallsBackToHeldState() {
        // Only NX_CONTROLMASK, no low bits at all: a flag diff of the device bits sees no
        // transition and drops the key — the fallback must infer DOWN from "not held yet".
        let down = resolve(keyCode: 59, rawFlags: 0x4_0000, held: false)
        XCTAssertEqual(down?.vk, 0xA2)
        XCTAssertEqual(down?.down, true)
        // And the mirror release (class cleared) still resolves as UP.
        let up = resolve(keyCode: 59, rawFlags: 0, held: true)
        XCTAssertEqual(up?.down, false)
    }
    func testClassBitStillSetButKeyAlreadyHeldResolvesUp() {
        // Device-bit-less keyboard, second same-class key still holding the class bit:
        // the best available answer for the key that changed is to flip its held state.
        let up = resolve(keyCode: 59, rawFlags: 0x4_0000, held: true)
        XCTAssertEqual(up?.down, false)
    }
    // MARK: Modifiers the host doesn't consume on this path
    func testFnAndCapsLockResolveToNothing() {
        XCTAssertNil(resolve(keyCode: 63, rawFlags: 0x80_0000)) // Fn / Globe
        XCTAssertNil(resolve(keyCode: 57, rawFlags: 0x1_0000)) // Caps Lock
    }
 }
 #endif
@@ -43,10 +43,12 @@ read-only, so the flatpak (which bundles libadwaita/SDL3) is the canonical clien
 **Install Plugin from URL**, paste:
 ```
-https://git.unom.io/api/packages/unom/generic/punktfunk-decky/latest/punktfunk.zip
+https://unom.io/pf-decky
 ```
-(or a pinned `.../punktfunk-decky/<version>/punktfunk.zip`). The plugin then **self-updates** without
+(short link for `https://git.unom.io/api/packages/unom/generic/punktfunk-decky/latest/punktfunk.zip`;
 for a pinned version use `https://git.unom.io/api/packages/unom/generic/punktfunk-decky/<version>/punktfunk.zip`
 directly). The plugin then **self-updates** without
 the Decky store — when a newer build exists, an **Update** button appears and drives Decky
 Loader's own (SHA-256-verified) install. Installs and updates can take a couple of minutes on some
 networks: Decky's installer also contacts its plugin store first, which may be slow or blackholed
@@ -104,7 +104,7 @@ def _parse_library_tsv(stdout: str) -> list[dict]:
 def _classify_library_error(stderr: str) -> str:
    """Map the client's ``library: <LibraryError Display>`` stderr line to a stable error
    code for the UI. Substring-matched against the Display strings in
-    ``clients/linux/src/library.rs`` — a wording change degrades to ``client-error``
+    ``crates/pf-client-core/src/library.rs`` — a wording change degrades to ``client-error``
    (generic copy), never a crash."""
    s = stderr.lower()
    if "didn't recognize this device" in s:
@@ -0,0 +1,32 @@
 [package]
 name = "punktfunk-client-session"
 description = "punktfunk/1 Vulkan session binary — SDL3 window, ash presenter, terminal stats; the power-user / gamescope stream client"
 version.workspace = true
 edition.workspace = true
 rust-version.workspace = true
 license.workspace = true
 authors.workspace = true
 repository.workspace = true
 [[bin]]
 name = "punktfunk-session"
 path = "src/main.rs"
 [features]
 default = ["ui"]
 # The Skia console UI (stats OSD, capture HUD, later the gamepad library). Dropping it
 # (`--no-default-features`) is the ~15 MB-smaller power-user build: same streaming,
 # stats on stdout only.
 ui = ["dep:pf-console-ui", "dep:serde_json"]
 # Same Linux gating as the rest of the client stack; elsewhere this is a stub binary.
 [target.'cfg(target_os = "linux")'.dependencies]
 pf-presenter = { path = "../../crates/pf-presenter" }
 pf-console-ui = { path = "../../crates/pf-console-ui", optional = true }
 pf-client-core = { path = "../../crates/pf-client-core" }
 punktfunk-core = { path = "../../crates/punktfunk-core", features = ["quic"] }
 # The fake-library dev hook (`PUNKTFUNK_FAKE_LIBRARY`, browse mode) parses GameEntry JSON.
 serde_json = { version = "1", optional = true }
 anyhow = "1"
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
@@ -0,0 +1,51 @@
 # punktfunk-session
 The Vulkan session binary: one stream per invocation in an SDL3 window — no UI toolkit,
 no widgets, terminal stats. The power-user / gamescope stream client, and the stage-2
 presenter of the Linux client re-architecture (punktfunk-planning:
 `linux-client-rearchitecture.md`).
 ```
 punktfunk-session --connect host[:port] [--fp HEX] [--launch id] [--fullscreen] [--stats]
 punktfunk-session --browse host[:port] [--mgmt PORT] [--fullscreen]
 ```
 `--browse` opens the console game library (the Skia coverflow over the animated aurora)
 instead of connecting: A launches the focused title as a stream in the same window,
 session end returns to the library, B quits (Gaming Mode returns). Paired hosts only —
 pairing is the desktop client / Decky plugin's job. `PUNKTFUNK_FAKE_LIBRARY=<file.json>`
 feeds canned entries with no host (portrait paths starting with `/` load from disk).
 Reads the same identity / known-hosts / settings stores as the desktop client
 (`punktfunk-client`) — pair there (or via its headless `--pair`) first; this binary never
 connects to a host it has no pinned fingerprint for (`--fp HEX` overrides the store).
 Stdout is the machine interface: `{"ready":true}` after the first presented frame,
 `stats: …` once per second (Ctrl+Alt+Shift+S toggles, `--stats` forces on), one
 `{"error"|"ended": …}` JSON line on the way out. Logs go to stderr. Exit codes: `0`
 clean end, `2` connect failed, `3` trust rejected / pairing required, `4` presenter
 init failed.
 In-stream keys match the desktop client: click captures input (Ctrl+Alt+Shift+Q
 releases), Ctrl+Alt+Shift+D disconnects, F11 toggles fullscreen; the controller escape
 chord (L1+R1+Start+Select, hold to disconnect) works the same.
 The default build carries the Skia console UI (`ui` feature): the stats OSD and capture
 hint render in-window (Ctrl+Alt+Shift+S toggles both the OSD and the stdout mirror).
 `--no-default-features` is the ~5 MB power-user build — same streaming, stats on stdout
 only, no Skia anywhere in the dependency tree.
 Decode follows the Settings preference (auto: Vulkan Video → VAAPI → software):
 FFmpeg's Vulkan Video decoder runs on the presenter's own device where the stack
 supports it (every vendor, zero copy); VAAPI dmabufs import per-plane elsewhere;
 software is the universal fallback. 10-bit Main10 and HDR10 are advertised
 (`VIDEO_CAP_10BIT|HDR`): P010 decodes through all three paths, and PQ streams present
 on an HDR10/ST.2084 swapchain when the desktop offers one (KDE HDR, gamescope) or
 tone-map in-shader to SDR when it doesn't (`PUNKTFUNK_TONEMAP_PEAK` tunes the rolloff,
 default ≈1000 nits). The host still gates the upgrade behind its `PUNKTFUNK_10BIT`
 policy.
 Debug/bisect knobs: `PUNKTFUNK_DECODER=vulkan|vaapi|software`, `PUNKTFUNK_PRESENT_MODE=
 mailbox|immediate` (default FIFO), `PUNKTFUNK_VK_DEVICE=<index>` (multi-GPU), and
 `PUNKTFUNK_HW_FAULT=import` (fault every VAAPI dmabuf import — proves the three-strike
 demotion to software on healthy hardware).
@@ -0,0 +1,186 @@
 //! `--browse host[:port]` — the console game library (phase 4b of the plan): the Skia
 //! coverflow idles in the session window, A launches the focused title as a stream in
 //! the SAME window (no gamescope window handoff — the whole point of one process), the
 //! session's end returns to the library, B quits to Gaming Mode.
 //!
 //! The host must already be paired (the stored pin fetches the library and connects
 //! silently; no ceremony can run under gamescope) — an unpaired target renders the
 //! pair-first scene. `PUNKTFUNK_FAKE_LIBRARY=<file.json>` feeds canned entries with no
 //! host (portrait paths starting with `/` load from disk), the GPU-only dev path.
 use crate::session_main::{arg_flag, arg_value, fullscreen_mode, parse_host_port, session_params};
 use pf_client_core::{library, trust};
 use pf_console_ui::{LibraryGame, LibraryPhase, LibraryShared, SkiaOverlay};
 use pf_presenter::overlay::OverlayAction;
 use pf_presenter::ActionOutcome;
 use std::collections::VecDeque;
 pub fn run(target: &str) -> u8 {
    let (addr, port) = parse_host_port(target);
    let known = trust::KnownHosts::load();
    let k = known
        .hosts
        .iter()
        .find(|h| h.addr == addr && h.port == port);
    let host_label = k.map_or_else(|| addr.clone(), |h| h.name.clone());
    let paired = k.is_some_and(|h| h.paired);
    let pin = k.and_then(|h| trust::parse_hex32(&h.fp_hex));
    let mgmt = arg_value("--mgmt")
        .and_then(|p| p.parse().ok())
        .unwrap_or(library::DEFAULT_MGMT_PORT);
    let identity = match trust::load_or_create_identity() {
        Ok(i) => i,
        Err(e) => {
            eprintln!("client identity: {e:#}");
            return crate::session_main::EXIT_CONNECT_FAILED;
        }
    };
    let settings = trust::Settings::load();
    let (overlay, shared) = match SkiaOverlay::with_library(host_label.clone()) {
        Ok(v) => v,
        Err(e) => {
            eprintln!("console UI: {e:#}");
            return crate::session_main::EXIT_PRESENTER_FAILED;
        }
    };
    // The library fetch — paired hosts only (the fake-library hook exists precisely for
    // host-less/pairing-less UI work).
    let fake = std::env::var_os("PUNKTFUNK_FAKE_LIBRARY").is_some();
    if paired || fake {
        spawn_fetch(shared.clone(), addr.clone(), mgmt, identity.clone(), pin);
    } else {
        shared.set_phase(LibraryPhase::PairFirst);
    }
    let opts = pf_presenter::SessionOpts {
        window_title: format!("Punktfunk · {host_label}"),
        fullscreen: fullscreen_mode(),
        print_stats: settings.show_stats || arg_flag("--stats"),
        json_status: false, // browse has no shell parent reading stdout
        on_connected: Some(Box::new(|fingerprint: [u8; 32]| {
            trust::touch_last_used(&trust::hex(&fingerprint));
        })),
        overlay: Some(Box::new(overlay)),
    };
    let result =
        pf_presenter::run_browse(opts, |action, gamepad, native, force_software, vulkan| {
            match action {
                OverlayAction::Launch { id, title } => {
                    // The carousel only renders for a paired host, so the pin exists; the
                    // guard keeps a logic slip from turning into a pinless connect.
                    let Some(pin) = pin else {
                        tracing::warn!("launch without a stored pin — refusing");
                        return ActionOutcome::Handled;
                    };
                    tracing::info!(%id, %title, "launching from the library");
                    ActionOutcome::Start(Box::new(session_params(
                        &settings,
                        addr.clone(),
                        port,
                        pin,
                        identity.clone(),
                        Some(id),
                        gamepad,
                        native,
                        force_software,
                        vulkan,
                    )))
                }
                OverlayAction::Retry => {
                    spawn_fetch(shared.clone(), addr.clone(), mgmt, identity.clone(), pin);
                    ActionOutcome::Handled
                }
                OverlayAction::Quit => ActionOutcome::Quit,
            }
        });
    match result {
        Ok(()) => 0,
        Err(e) => {
            eprintln!("browse: {e:#}");
            crate::session_main::EXIT_PRESENTER_FAILED
        }
    }
 }
 /// Fetch the library off the main thread, then stream poster art into the shared model
 /// as results land (the GTK launcher's `load` + `load_art`, minus the main-loop hops —
 /// the renderer drains `push_art` per frame).
 fn spawn_fetch(
    shared: LibraryShared,
    addr: String,
    mgmt: u16,
    identity: (String, String),
    pin: Option<[u8; 32]>,
 ) {
    shared.set_phase(LibraryPhase::Loading);
    std::thread::Builder::new()
        .name("punktfunk-library".into())
        .spawn(move || {
            if let Ok(path) = std::env::var("PUNKTFUNK_FAKE_LIBRARY") {
                load_fake(&shared, &path);
                return;
            }
            match library::fetch_games(&addr, mgmt, &identity, pin) {
                Ok(games) => {
                    let base = library::base_url(&addr, mgmt);
                    let jobs: VecDeque<(String, Vec<String>)> = games
                        .iter()
                        .map(|g| (g.id.clone(), g.art.poster_candidates(&base)))
                        .filter(|(_, candidates)| !candidates.is_empty())
                        .collect();
                    shared.set_games(
                        games
                            .iter()
                            .map(|g| LibraryGame {
                                id: g.id.clone(),
                                title: g.title.clone(),
                                store: g.store.clone(),
                            })
                            .collect(),
                    );
                    if !jobs.is_empty() {
                        let rx = library::spawn_art_fetch(base, identity, pin, jobs);
                        while let Ok((id, bytes)) = rx.recv_blocking() {
                            shared.push_art(id, bytes);
                        }
                    }
                }
                Err(e) => shared.set_phase(LibraryPhase::Error {
                    title: "Couldn't load the library".into(),
                    body: e.to_string(),
                    can_retry: true,
                }),
            }
        })
        .ok();
 }
 /// Dev hook: entries from a JSON file; portrait paths starting with `/` load from disk.
 fn load_fake(shared: &LibraryShared, path: &str) {
    let games: Vec<library::GameEntry> = std::fs::read_to_string(path)
        .ok()
        .and_then(|s| serde_json::from_str(&s).ok())
        .unwrap_or_default();
    for g in &games {
        if let Some(p) = g.art.portrait.as_deref().filter(|p| p.starts_with('/')) {
            if let Ok(bytes) = std::fs::read(p) {
                shared.push_art(g.id.clone(), bytes);
            }
        }
    }
    shared.set_games(
        games
            .iter()
            .map(|g| LibraryGame {
                id: g.id.clone(),
                title: g.title.clone(),
                store: g.store.clone(),
            })
            .collect(),
    );
 }
@@ -0,0 +1,321 @@
 //! `punktfunk-session` — the Vulkan session binary (punktfunk-planning
 //! `linux-client-rearchitecture.md`, Phase 1: the software-path presenter MVP, which IS
 //! the power-user CLI build).
 //!
 //! One stream session per invocation: `--connect host[:port]` (+ `--fp HEX`,
 //! `--launch id`, `--fullscreen`), exits when the session ends. Reads the same identity
 //! / known-hosts / settings stores as the GTK client (`punktfunk-client`), so pairing
 //! there (or via its headless `--pair`) makes this binary connect silently.
 //!
 //! Stdout is the machine interface (the shell↔session contract): `{"ready":true}` after
 //! the first presented frame, `stats:` lines per 1 s window, one `{"error": …}` /
 //! `{"ended": …}` JSON line on the way out. Logs go to stderr. Exit codes: 0 clean end,
 //! 2 connect failed, 3 trust rejected / pairing required, 4 presenter init failed.
 #[cfg(all(target_os = "linux", feature = "ui"))]
 mod browse;
 #[cfg(target_os = "linux")]
 mod session_main {
    use pf_client_core::gamepad::GamepadService;
    use pf_client_core::session::SessionParams;
    use pf_client_core::trust;
    use punktfunk_core::config::{CompositorPref, GamepadPref, Mode};
    use std::sync::atomic::AtomicBool;
    use std::sync::Arc;
    use std::time::Duration;
    pub const EXIT_CONNECT_FAILED: u8 = 2;
    pub const EXIT_TRUST_REJECTED: u8 = 3;
    pub const EXIT_PRESENTER_FAILED: u8 = 4;
    /// The value following `flag` in argv, if present (`--flag value`).
    pub(crate) fn arg_value(flag: &str) -> Option<String> {
        std::env::args()
            .skip_while(|a| a != flag)
            .nth(1)
            .filter(|v| !v.starts_with("--"))
    }
    pub(crate) fn arg_flag(flag: &str) -> bool {
        std::env::args().any(|a| a == flag)
    }
    /// Run fullscreen: `--fullscreen`, or the Deck/gamescope env as a fallback so a
    /// manual launch under Gaming Mode does the right thing too.
    pub(crate) fn fullscreen_mode() -> bool {
        arg_flag("--fullscreen")
            || std::env::var_os("SteamDeck").is_some()
            || std::env::var_os("GAMESCOPE_WAYLAND_DISPLAY").is_some()
    }
    /// `host[:port]`, port defaulting to the native 9777.
    pub(crate) fn parse_host_port(target: &str) -> (String, u16) {
        match target.rsplit_once(':') {
            Some((a, p)) => match p.parse() {
                Ok(port) => (a.to_string(), port),
                Err(_) => {
                    eprintln!("unparsable port in '{target}', using default 9777");
                    (a.to_string(), 9777)
                }
            },
            None => (target.to_string(), 9777),
        }
    }
    /// The connect budget: 15 s normally; `--connect-timeout SECS` overrides — the
    /// shell's request-access flow passes ~185 s because the host PARKS the connection
    /// until the operator clicks Approve.
    pub(crate) fn connect_timeout() -> Duration {
        Duration::from_secs(
            arg_value("--connect-timeout")
                .and_then(|v| v.parse().ok())
                .unwrap_or(15),
        )
    }
    /// One session's pump parameters from the Settings store — shared by `--connect`
    /// and every `--browse` launch. Explicit settings, `0` fields resolved to the
    /// window's display (the GTK client reads the monitor under its window — same
    /// contract).
    #[allow(clippy::too_many_arguments)]
    pub(crate) fn session_params(
        settings: &trust::Settings,
        addr: String,
        port: u16,
        pin: [u8; 32],
        identity: (String, String),
        launch: Option<String>,
        gamepad: &GamepadService,
        native: Mode,
        force_software: Arc<AtomicBool>,
        vulkan: Option<pf_client_core::video::VulkanDecodeDevice>,
    ) -> SessionParams {
        let mode = Mode {
            width: if settings.width == 0 {
                native.width
            } else {
                settings.width
            },
            height: if settings.width == 0 {
                native.height
            } else {
                settings.height
            },
            refresh_hz: if settings.refresh_hz == 0 {
                native.refresh_hz.max(30)
            } else {
                settings.refresh_hz
            },
        };
        SessionParams {
            host: addr,
            port,
            mode,
            compositor: CompositorPref::from_name(&settings.compositor)
                .unwrap_or(CompositorPref::Auto),
            gamepad: match GamepadPref::from_name(&settings.gamepad) {
                Some(GamepadPref::Auto) | None => gamepad.auto_pref(),
                Some(explicit) => explicit,
            },
            bitrate_kbps: settings.bitrate_kbps,
            audio_channels: settings.audio_channels,
            preferred_codec: settings.preferred_codec(),
            mic_enabled: settings.mic_enabled,
            // The Settings preference (auto → VAAPI where it exists; the presenter
            // demotes to software on boxes whose Vulkan can't import the dmabufs).
            // PUNKTFUNK_DECODER still overrides inside the decoder for bisects.
            decoder: settings.decoder.clone(),
            launch,
            vulkan,
            pin: Some(pin),
            identity,
            connect_timeout: connect_timeout(),
            force_software,
        }
    }
    /// One JSON status line on stdout (the shell parses these; strings hand-escaped via
    /// the minimal rules a reason string can need).
    fn json_line(key: &str, msg: &str, trust_rejected: Option<bool>) {
        let escaped: String = msg
            .chars()
            .flat_map(|c| match c {
                '"' => vec!['\\', '"'],
                '\\' => vec!['\\', '\\'],
                '\n' => vec!['\\', 'n'],
                c if (c as u32) < 0x20 => vec![' '],
                c => vec![c],
            })
            .collect();
        match trust_rejected {
            Some(t) => println!("{{\"{key}\":\"{escaped}\",\"trust_rejected\":{t}}}"),
            None => println!("{{\"{key}\":\"{escaped}\"}}"),
        }
    }
    pub fn run() -> u8 {
        // Logs to STDERR — stdout is the machine interface (ready/stats/error lines).
        tracing_subscriber::fmt()
            .with_writer(std::io::stderr)
            .with_env_filter(
                tracing_subscriber::EnvFilter::try_from_default_env()
                    .unwrap_or_else(|_| "info".into()),
            )
            .init();
        // Steam launches its shortcuts with SDL_GAMECONTROLLER_IGNORE_DEVICES naming
        // every pad Steam Input has virtualized; capturing the Deck's real built-in
        // controller needs it cleared (same rationale as the GTK client's `app::run`).
        for var in [
            "SDL_GAMECONTROLLER_IGNORE_DEVICES",
            "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT",
        ] {
            if let Ok(v) = std::env::var(var) {
                tracing::info!(var, value = %v, "clearing Steam's SDL device filter");
                std::env::remove_var(var);
            }
        }
        if let Some(target) = arg_value("--browse") {
            #[cfg(feature = "ui")]
            return crate::browse::run(&target);
            #[cfg(not(feature = "ui"))]
            {
                let _ = target;
                eprintln!(
                    "--browse needs the console UI — this is the minimal build \
                     (rebuild without --no-default-features)"
                );
                return EXIT_PRESENTER_FAILED;
            }
        }
        let Some(target) = arg_value("--connect") else {
            eprintln!(
                "usage: punktfunk-session --connect host[:port] [--fp HEX] [--launch id] [--fullscreen]\n\
                 \x20      punktfunk-session --browse host[:port] [--mgmt PORT] [--fullscreen]\n\
                 \n\
                 Streams from a paired punktfunk host in a Vulkan window; --browse opens the\n\
                 console game library instead (paired hosts only). Pair first via the\n\
                 desktop client or `punktfunk-client --pair <PIN> --connect host[:port]` —\n\
                 this binary never connects to a host it has no pinned fingerprint for."
            );
            return EXIT_CONNECT_FAILED;
        };
        let (addr, port) = parse_host_port(&target);
        let identity = match trust::load_or_create_identity() {
            Ok(i) => i,
            Err(e) => {
                json_line("error", &format!("client identity: {e:#}"), None);
                return EXIT_CONNECT_FAILED;
            }
        };
        let settings = trust::Settings::load();
        // Trust follows the GTK client's `--connect` rules: a stored (or `--fp`) pin
        // connects silently; an unknown host is REFUSED — there is no dialog here, and a
        // silent TOFU would defeat the pinning model. Pair via the desktop client.
        let known = trust::KnownHosts::load();
        let known_host = known
            .hosts
            .iter()
            .find(|h| h.addr == addr && h.port == port);
        let pin = arg_value("--fp")
            .as_deref()
            .and_then(trust::parse_hex32)
            .or_else(|| known_host.and_then(|h| trust::parse_hex32(&h.fp_hex)));
        let Some(pin) = pin else {
            json_line(
                "error",
                &format!(
                    "no pinned fingerprint for {addr}:{port} — pair first \
                     (punktfunk-client --pair <PIN> --connect {addr}:{port}) or pass --fp HEX"
                ),
                Some(true),
            );
            return EXIT_TRUST_REJECTED;
        };
        let host_label = known_host.map_or_else(|| addr.clone(), |h| h.name.clone());
        let launch = arg_value("--launch");
        let title = launch
            .clone()
            .map_or_else(|| host_label.clone(), |id| format!("{host_label} · {id}"));
        let fullscreen = arg_flag("--fullscreen")
            || std::env::var_os("SteamDeck").is_some()
            || std::env::var_os("GAMESCOPE_WAYLAND_DISPLAY").is_some();
        let opts = pf_presenter::SessionOpts {
            window_title: format!("Punktfunk · {title}"),
            fullscreen,
            print_stats: settings.show_stats || arg_flag("--stats"),
            json_status: true,
            on_connected: Some(Box::new(|fingerprint: [u8; 32]| {
                // This host's card carries the accent bar in the desktop client now.
                trust::touch_last_used(&trust::hex(&fingerprint));
            })),
            // The Skia console UI (stats OSD, capture HUD) — compiled out of the
            // power-user build (`--no-default-features` drops the `ui` feature).
            #[cfg(feature = "ui")]
            overlay: Some(Box::new(pf_console_ui::SkiaOverlay::new())),
            #[cfg(not(feature = "ui"))]
            overlay: None,
        };
        let outcome =
            pf_presenter::run_session(opts, move |gamepad, native, force_software, vulkan| {
                session_params(
                    &settings,
                    addr,
                    port,
                    pin,
                    identity,
                    launch,
                    gamepad,
                    native,
                    force_software,
                    vulkan,
                )
            });
        match outcome {
            Ok(pf_presenter::Outcome::Ended(None)) => 0,
            Ok(pf_presenter::Outcome::Ended(Some(reason))) => {
                // The host ending the session (game quit, host shutdown) is a normal end
                // for a one-shot stream binary — report the reason, exit clean.
                json_line("ended", &reason, None);
                0
            }
            Ok(pf_presenter::Outcome::ConnectFailed {
                msg,
                trust_rejected,
            }) => {
                json_line("error", &msg, Some(trust_rejected));
                if trust_rejected {
                    EXIT_TRUST_REJECTED
                } else {
                    EXIT_CONNECT_FAILED
                }
            }
            Err(e) => {
                json_line("error", &format!("presenter: {e:#}"), None);
                EXIT_PRESENTER_FAILED
            }
        }
    }
 }
 #[cfg(target_os = "linux")]
 fn main() -> std::process::ExitCode {
    std::process::ExitCode::from(session_main::run())
 }
 /// Vulkan/SDL3/PipeWire are Linux turf; this stub keeps `cargo build --workspace` green
 /// elsewhere (the Mac client lives in clients/apple).
 #[cfg(not(target_os = "linux"))]
 fn main() {
    eprintln!("punktfunk-session is Linux-only — the macOS client lives in clients/apple");
    std::process::exit(2);
 }
@@ -15,6 +15,10 @@ path = "src/main.rs"
 # Everything is Linux-gated so `cargo build --workspace` stays green on macOS (the Mac
 # client lives in clients/apple); on other platforms this builds as a stub binary.
 [target.'cfg(target_os = "linux")'.dependencies]
 # Session pump, decode, audio, gamepads, trust, discovery, keymap — the UI-agnostic
 # plumbing, shared with the upcoming Vulkan session binary (design: punktfunk-planning
 # linux-client-rearchitecture.md). This crate keeps only the GTK shell + GL presenter.
 pf-client-core = { path = "../../crates/pf-client-core" }
 punktfunk-core = { path = "../../crates/punktfunk-core", features = ["quic"] }
 # UI shell. GraphicsOffload needs GTK ≥ 4.14; black-background ≥ 4.16. AlertDialog/
@@ -23,26 +27,8 @@ gtk = { package = "gtk4", version = "0.11", features = ["v4_16"] }
 adw = { package = "libadwaita", version = "0.9", features = ["v1_5"] }
 async-channel = "2"
 # Video decode (same FFmpeg pin as the host) and audio.
 ffmpeg-next = "8"
 opus = "0.3"
 pipewire = "0.9"
 # Gamepads: capture + feedback (full DualSense fidelity — touchpad/motion/triggers/LEDs
 # need the hidapi driver).
 sdl3 = { version = "0.18", features = ["hidapi"] }
 # The VAAPI GL presenter (video_gl.rs): EGL dmabuf import into a GDK-shared context, dlopened
 # at runtime (`dynamic`) so GPU-less boxes and the software path never touch libEGL.
 khronos-egl = { version = "6", features = ["dynamic"] }
 mdns-sd = "0.20"
 # Game-library fetch from the host's management API over mTLS + fingerprint pinning.
 # `ureq` is small + sync (the host uses it too) and its rustls unifies with the
 # workspace's (quinn's) 0.23; the pinning verifier mirrors core's private `PinVerify`.
 ureq = "2"
 rustls = { version = "0.23", features = ["ring"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 anyhow = "1"
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 relm4 = { version = "0.11", features = ["libadwaita"] }
@@ -57,36 +57,35 @@ cargo run -p punktfunk-client-linux -- --connect HOST[:PORT]   # skip the host l
 cargo run -p punktfunk-client-linux -- --browse HOST           # the gamepad library launcher
 ```
-The binary is named **`punktfunk-client`**. Handy flags: `--connect host[:port]` (start a session
+The binary is named **`punktfunk-client`** — the relm4/libadwaita desktop shell (hosts,
-immediately — for scripting and the Steam Deck launcher) with optional `--launch <id>` (ask the
+pairing/trust, settings, the desktop library page). Every stream and the console game
-host to launch that library title, id from `--library`), `--browse host[:port]` (the gamepad
+library run in the sibling **`punktfunk-session`** Vulkan binary; the shell spawns it
-library launcher; `--mgmt <port>` overrides the management port it fetches from),
+for connects, and `--connect`/`--browse` on the shell exec it directly (so the Decky
-`--pair <PIN> --connect host[:port]` (run the pairing ceremony headlessly), and
+wrapper keeps working unchanged). Headless flags stay in the shell:
-`--library host[:mgmt_port]` (print a host's game library headlessly). Force a decoder with
+`--pair <PIN> --connect host[:port]` (pairing ceremony), `--wake host[:port]`, and
-`PUNKTFUNK_DECODER=software|vaapi`; `PUNKTFUNK_FAKE_LIBRARY=<file.json>` feeds the launcher
+`--library host[:mgmt_port]` (print a host's game library).
 canned entries for UI work with no host.
 ## Layout
 ```
 src/
-  main.rs · app.rs        entry point, GTK application, primary menu, CSS
+  main.rs · app.rs        entry point, relm4 AppModel (window, trust gate, session child
-  cli.rs                  CLI paths (--connect/--launch, --browse, headless --pair, screenshot scenes)
+                          lifecycle, typed messages), primary menu, CSS
-  ui_hosts.rs             host card grids (saved + discovered) · add-host dialog · banner
+  cli.rs                  headless paths (--pair/--wake/--library), the --connect/--browse
                          exec handoff to punktfunk-session, screenshot scenes
  ui_hosts.rs             hosts page component (FactoryVecDeque cards, saved + discovered
                          grids, add-host dialog, banner)
  ui_library.rs           game-library poster grid (per-host, launches titles)
  ui_gamepad_library.rs   the --browse gamepad launcher (aurora · coverflow · hint bar)
  ui_trust.rs             TOFU / PIN-pairing / request-access dialogs
  ui_settings.rs          resolution · refresh · decoder · bitrate · compositor · mic
-  ui_stream.rs            the stream window (GtkGraphicsOffload present) + input capture
+  spawn.rs                the session-child plumbing (stdout contract → AppMsg)
  launch.rs · session.rs  session launch/UI glue; lifecycle over the NativeClient connector
  video.rs                FFmpeg VAAPI / software decode → dmabuf / texture
  audio.rs                PipeWire playback + mic uplink
  gamepad.rs · keymap.rs  SDL3 controllers + feedback; keyboard VK mapping
  trust.rs · discovery.rs persistent identity, known hosts + settings, mDNS browse
  library.rs              mgmt-API library client (mTLS + pinned fingerprint, art proxy)
 tools/screenshots.sh      store screenshot capture (app self-capture; Xvfb fallback)
 ```
 The UI-agnostic plumbing — session pump, FFmpeg decode, PipeWire audio, SDL3 gamepads +
 keymap, trust store, mDNS discovery, library client, Wake-on-LAN — lives in
 `crates/pf-client-core`, shared with the Vulkan session binary.
 ## Related
 - **[Documentation](https://docs.punktfunk.unom.io)** — quick start, pairing, troubleshooting
@@ -1,23 +1,32 @@
-//! The application shell: window, navigation, and top-level glue. The trust/pairing
+//! The application shell as a relm4 component tree (phase 5 of punktfunk-planning
-//! dialogs live in `ui_trust`, session launch in `launch`, CLI entry paths in `cli`, the
+//! `linux-client-rearchitecture.md`): [`AppModel`] owns the window, navigation, trust
-//! hosts grid in `ui_hosts`.
+//! gate, and the spawned session child's lifecycle; the hosts page is a child component
 //! ([`crate::ui_hosts`]); dialogs (trust, settings, library) are plain GTK invoked from
 //! `update`. Every stream runs in the `punktfunk-session` Vulkan binary — the shell
 //! never touches video.
-use crate::trust::Settings;
+use crate::spawn::{self, SpawnOpts};
-use crate::ui_hosts::{ConnectRequest, HostsCallbacks, HostsUi};
+use crate::trust::{self, Settings};
 use crate::ui_hosts::{ConnectRequest, HostsMsg, HostsOutput, HostsPage};
 use adw::prelude::*;
 use gtk::{gdk, gio, glib};
 use punktfunk_core::client::NativeClient;
 use punktfunk_core::config::{CompositorPref, GamepadPref};
 use relm4::prelude::*;
 use std::cell::RefCell;
 use std::rc::Rc;
-const APP_ID: &str = "io.unom.Punktfunk";
+pub const APP_ID: &str = "io.unom.Punktfunk";
 /// Custom styles on top of libadwaita for the host cards: status pills, presence pips,
 /// the most-recent accent bar, dashed discovered cards. Colours come from the adwaita
 /// named palette so dark mode just works.
 const CSS: &str = "
 .pf-host-card { padding: 16px; }
 /* The FlowBoxChild draws the hover/selection highlight AROUND the card (it wraps it
   with its own padding), so its corners must run concentric with the card's 12px —
   radius = card radius + the child's padding ring. */
 .pf-host-grid > flowboxchild { border-radius: 15px; }
 .pf-pill { font-size: 0.72em; font-weight: bold; padding: 2px 10px; border-radius: 999px;
           color: alpha(currentColor, 0.8); background: alpha(currentColor, 0.1); }
 .pf-pill.pf-green { color: @success_color; background: alpha(@success_color, 0.15); }
@@ -34,79 +43,479 @@ const CSS: &str = "
 .pf-poster { border-radius: 10px; background: alpha(currentColor, 0.08); }
 .pf-poster-monogram { font-size: 2.4em; font-weight: bold; color: alpha(currentColor, 0.45); }
 .pf-store-badge { color: white; background: rgba(0, 0, 0, 0.55); }
 /* Gaming-Mode launches: gamescope displays the window fullscreen but never ACKs the
   xdg_toplevel fullscreen state, so GTK keeps the floating-CSD styling — libadwaita's
   rounded corners + shadow margin stay visible over the stream. Flatten them outright. */
 window.pf-chromeless { border-radius: 0; box-shadow: none; }
 /* The gamepad library launcher (`--browse`, ui_gamepad_library) — always-dark console
   chrome over the aurora, independent of the desktop theme. */
 .pf-gl-page { background: black; color: white; }
 .pf-gl-host { font-size: 1.15em; font-weight: bold; color: rgba(255, 255, 255, 0.9); }
 .pf-gl-chip { font-size: 0.8em; color: rgba(255, 255, 255, 0.7);
              background: rgba(255, 255, 255, 0.08);
              border: 1px solid rgba(255, 255, 255, 0.12);
              border-radius: 999px; padding: 4px 12px; }
 /* Solid face, not glass: coverflow side cards OVERLAP — a translucent card would bleed
   the stack through the one on top. */
 .pf-gl-poster { border-radius: 16px; background: rgb(30, 30, 37);
                border: 1px solid rgba(255, 255, 255, 0.07); }
 .pf-gl-dim { background: black; border-radius: 16px; }
 .pf-gl-detail-title { font-size: 1.7em; font-weight: bold; color: white; }
 .pf-gl-detail-store { font-size: 0.75em; font-weight: 600; letter-spacing: 2px;
                      color: rgba(255, 255, 255, 0.5); }
 .pf-gl-glyph { font-size: 0.85em; font-weight: bold; color: white;
               background: rgba(255, 255, 255, 0.14);
               border-radius: 999px; min-width: 26px; min-height: 26px; padding: 2px 8px; }
 .pf-gl-hint { color: rgba(255, 255, 255, 0.85); }
 .pf-gl-status { font-size: 0.85em; color: #ff938a; }
 .pf-gl-error-title { font-size: 1.4em; font-weight: bold; color: white; }
 ";
-pub struct App {
+/// Everything the shell shares below the component tree.
 pub struct AppModel {
    pub window: adw::ApplicationWindow,
    pub nav: adw::NavigationView,
-    pub toasts: adw::ToastOverlay,
+    toasts: adw::ToastOverlay,
    pub settings: Rc<RefCell<Settings>>,
    pub identity: (String, String),
-    /// App-lifetime SDL gamepad service: Settings list + per-session capture/feedback.
+    /// App-lifetime SDL gamepad service (Settings' controller list + pinning). Streams
    /// run in the session binary, which has its own.
    pub gamepad: crate::gamepad::GamepadService,
-    /// One session at a time — ignore connects while one is starting/running.
+    hosts: Controller<HostsPage>,
-    pub busy: std::cell::Cell<bool>,
+    /// One session child at a time — connects while one runs are ignored.
-    /// Steam Deck / Gaming-Mode launch: fullscreen the window (chrome-less) when a stream starts.
+    busy: bool,
-    pub fullscreen: bool,
+    /// The request-access "waiting for approval" dialog, closed on the first child
-    /// Quit when the session ends (Gaming-Mode `--connect` launch): the app IS the stream —
+    /// event. A shared slot (not a message): dialogs are main-thread GTK objects and
-    /// exiting ends the Steam "game" so the Deck returns to Gaming Mode instead of stranding
+    /// `AppMsg` must stay `Send` for the session child's reader thread.
-    /// the user on the client's own hosts page.
+    waiting: Rc<RefCell<Option<adw::AlertDialog>>>,
    pub quit_on_session_end: bool,
    /// The hosts page handle (banner + per-card connecting spinner), set right after the
    /// page is built — `None` only during construction.
    pub hosts: RefCell<Option<Rc<HostsUi>>>,
    /// The gamepad library launcher — `Some` only under `--browse`, where it replaces the
    /// hosts page as the root (and session end returns here instead of quitting).
    pub browse: RefCell<Option<Rc<crate::ui_gamepad_library::LauncherUi>>>,
 }
-impl App {
+#[derive(Debug)]
 pub enum AppMsg {
    /// The trust gate in front of every connect (rules 1–3, see `update`).
    Connect(ConnectRequest),
    /// Wake an offline saved host, poll until it advertises, then `Connect`.
    WakeConnect(ConnectRequest),
    /// The SPAKE2 PIN ceremony dialog.
    Pair(ConnectRequest),
    SpeedTest(ConnectRequest),
    /// The desktop library page (mgmt port from the live advert when known).
    OpenLibrary(ConnectRequest, Option<u16>),
    /// Spawn the session child now (trust already decided; `tofu` = persist the
    /// fingerprint once the child proves it).
    StartSession {
        req: ConnectRequest,
        fp_hex: String,
        tofu: bool,
        opts: SpawnOpts,
    },
    /// The child presented its first frame.
    SessionReady {
        req: ConnectRequest,
        fp_hex: String,
        tofu: bool,
        persist_paired: bool,
    },
    /// The child exited (the session is over, or the connect failed).
    SessionExited {
        req: ConnectRequest,
        code: i32,
        error: Option<(String, bool)>,
        ended: Option<String>,
        tofu: bool,
    },
    /// Request-access Cancel: the child was killed; release busy quietly.
    CancelPending,
    /// The speed-test dialog resolved (either way) — release `busy`.
    SpeedTestDone,
    ShowPreferences,
    ShowShortcuts,
    ShowAbout,
    ShowAddHost,
    Toast(String),
 }
 pub struct AppInit {
    pub gamepad: crate::gamepad::GamepadService,
 }
 pub struct AppWidgets {}
 impl SimpleComponent for AppModel {
    type Init = AppInit;
    type Input = AppMsg;
    type Output = ();
    type Root = adw::ApplicationWindow;
    type Widgets = AppWidgets;
    fn init_root() -> Self::Root {
        adw::ApplicationWindow::builder()
            .title("Punktfunk")
            .default_width(1200)
            .default_height(780)
            .build()
    }
    fn init(
        init: Self::Init,
        window: Self::Root,
        sender: ComponentSender<Self>,
    ) -> ComponentParts<Self> {
        let identity = match trust::load_or_create_identity() {
            Ok(i) => i,
            Err(e) => {
                tracing::error!("client identity: {e:#}");
                std::process::exit(1);
            }
        };
        load_css();
        // Screenshot scenes must capture settled frames: kill every GTK/libadwaita
        // animation (a headless session may starve the frame clock and leave a
        // transition frozen mid-flight in the capture).
        if crate::cli::shot_scene().is_some() {
            if let Some(s) = gtk::Settings::default() {
                s.set_gtk_enable_animations(false);
            }
        }
        let settings = Rc::new(RefCell::new(Settings::load()));
        // Re-apply the persisted forwarded-controller pin (stable key; the service
        // matches it whenever such a pad connects).
        {
            let forward = settings.borrow().forward_pad.clone();
            if !forward.is_empty() {
                init.gamepad.set_pinned(Some(forward));
            }
        }
        let hosts =
            HostsPage::builder()
                .launch(settings.clone())
                .forward(sender.input_sender(), |out| match out {
                    HostsOutput::Connect(req) => AppMsg::Connect(req),
                    HostsOutput::WakeConnect(req) => AppMsg::WakeConnect(req),
                    HostsOutput::Pair(req) => AppMsg::Pair(req),
                    HostsOutput::SpeedTest(req) => AppMsg::SpeedTest(req),
                    HostsOutput::Library(req, mgmt) => AppMsg::OpenLibrary(req, mgmt),
                });
        let nav = adw::NavigationView::new();
        nav.add(hosts.widget());
        let toasts = adw::ToastOverlay::new();
        toasts.set_child(Some(&nav));
        window.set_content(Some(&toasts));
        // Gaming-mode fallback (a bare launch under gamescope): fullscreen the shell.
        if crate::cli::fullscreen_mode() {
            window.fullscreen();
        }
        let model = AppModel {
            window: window.clone(),
            nav,
            toasts,
            settings,
            identity,
            gamepad: init.gamepad,
            hosts,
            busy: false,
            waiting: Rc::new(RefCell::new(None)),
        };
        install_actions(&model.window, &sender);
        // CI screenshot mode: dispatch the scripted scene once the window is actually
        // mapped (AdwDialogs need a live window; relm4 maps it after `init` returns, so
        // this can't run inline like the pre-relm4 `activate` path did).
        if let Some(scene) = crate::cli::shot_scene() {
            let ctx = crate::cli::ShotCtx {
                window: model.window.clone(),
                nav: model.nav.clone(),
                hosts: model.hosts.sender().clone(),
                settings: model.settings.clone(),
                gamepad: model.gamepad.clone(),
                identity: model.identity.clone(),
                sender: sender.clone(),
            };
            let fired = std::cell::Cell::new(false);
            model.window.connect_map(move |_| {
                if fired.replace(true) {
                    return; // map can fire more than once; the scene runs on the first
                }
                crate::cli::run_shot(&ctx, &scene);
            });
        }
        window.present();
        ComponentParts {
            model,
            widgets: AppWidgets {},
        }
    }
    fn update(&mut self, msg: AppMsg, sender: ComponentSender<Self>) {
        match msg {
            // The trust gate (the host is the policy authority — it advertises
            // `pair=optional` only when it accepts unpaired clients):
            //   1. PINNED RECONNECT — a stored fingerprint connects silently.
            //   2. FINGERPRINT CHANGED — known address, different fp: the impostor
            //      signal; force the PIN ceremony.
            //   3a. NEW + pair=optional — offer TOFU alongside PIN.
            //   3b. NEW otherwise — delegated approval (request access) or PIN.
            AppMsg::Connect(req) => {
                if self.busy {
                    return;
                }
                let known = trust::KnownHosts::load();
                match &req.fp_hex {
                    Some(fp_hex) => {
                        if known.find_by_fp(fp_hex).is_some() {
                            let fp_hex = fp_hex.clone();
                            sender.input(AppMsg::StartSession {
                                req,
                                fp_hex,
                                tofu: false,
                                opts: SpawnOpts::default(),
                            });
                        } else if known.find_by_addr(&req.addr, req.port).is_some() {
                            self.toast("Host fingerprint changed — re-pair with a PIN to continue");
                            crate::ui_trust::pin_dialog(
                                &self.window,
                                &sender,
                                self.identity.clone(),
                                req,
                            );
                        } else if req.pair_optional {
                            crate::ui_trust::tofu_dialog(&self.window, &sender, req);
                        } else {
                            crate::ui_trust::approval_dialog(
                                &self.window,
                                &sender,
                                self.waiting.clone(),
                                req,
                            );
                        }
                    }
                    None => {
                        // Manual entry: a known address connects on its stored pin;
                        // an unknown one must pair — never silent TOFU.
                        match known
                            .find_by_addr(&req.addr, req.port)
                            .map(|k| k.fp_hex.clone())
                        {
                            Some(fp_hex) => sender.input(AppMsg::StartSession {
                                req,
                                fp_hex,
                                tofu: false,
                                opts: SpawnOpts::default(),
                            }),
                            None => crate::ui_trust::approval_dialog(
                                &self.window,
                                &sender,
                                self.waiting.clone(),
                                req,
                            ),
                        }
                    }
                }
            }
            AppMsg::WakeConnect(req) => {
                if !self.busy {
                    crate::ui_trust::wake_and_connect(&self.window, &sender, req);
                }
            }
            AppMsg::Pair(req) => {
                if !self.busy {
                    crate::ui_trust::pin_dialog(&self.window, &sender, self.identity.clone(), req);
                }
            }
            AppMsg::SpeedTest(req) => self.speed_test(req, &sender),
            AppMsg::SpeedTestDone => self.busy = false,
            AppMsg::OpenLibrary(req, mgmt_port) => {
                crate::ui_library::open(self, &sender, req, mgmt_port);
            }
            AppMsg::StartSession {
                req,
                fp_hex,
                tofu,
                opts,
            } => {
                if std::mem::replace(&mut self.busy, true) {
                    return;
                }
                self.hosts.emit(HostsMsg::ClearError);
                self.hosts
                    .emit(HostsMsg::SetConnecting(Some(req.card_key())));
                let fullscreen = self.settings.borrow().fullscreen_on_stream;
                if let Err(e) = spawn::spawn_session(
                    sender.input_sender().clone(),
                    req,
                    fp_hex,
                    tofu,
                    fullscreen,
                    opts,
                ) {
                    self.busy = false;
                    self.hosts.emit(HostsMsg::SetConnecting(None));
                    self.hosts.emit(HostsMsg::ShowError(e));
                }
            }
            AppMsg::SessionReady {
                req,
                fp_hex,
                tofu,
                persist_paired,
            } => {
                self.close_waiting();
                self.hosts.emit(HostsMsg::SetConnecting(None));
                if persist_paired {
                    // Request-access: the operator approved this device — a trusted
                    // PAIRED host from now on, like after a PIN ceremony.
                    trust::persist_host(&req.name, &req.addr, req.port, &fp_hex, true);
                    self.toast("Approved — connected");
                } else if tofu {
                    // The advertised fingerprint proved itself on a real connect.
                    trust::persist_host(&req.name, &req.addr, req.port, &fp_hex, false);
                    self.toast(&format!(
                        "Trusted on first use — fingerprint {}…",
                        &fp_hex[..16.min(fp_hex.len())]
                    ));
                }
                self.hosts.emit(HostsMsg::Refresh);
            }
            AppMsg::SessionExited {
                req,
                code,
                error,
                ended,
                tofu,
            } => {
                self.close_waiting();
                self.busy = false;
                self.hosts.emit(HostsMsg::SetConnecting(None));
                match (code, error, ended) {
                    (0, _, None) => {} // clean end — back on the hosts page, no noise
                    (0, _, Some(reason)) => self.hosts.emit(HostsMsg::ShowError(reason)),
                    (_, Some((_, true)), _) if !tofu => {
                        // The stored pin no longer matches (rotated cert or impostor).
                        self.toast("Host fingerprint changed — re-pair with a PIN to continue");
                        crate::ui_trust::pin_dialog(
                            &self.window,
                            &sender,
                            self.identity.clone(),
                            req,
                        );
                    }
                    (_, Some((msg, _)), _) => self
                        .hosts
                        .emit(HostsMsg::ShowError(format!("Couldn't connect — {msg}"))),
                    (-1, None, _) => {} // killed (request-access cancel) — already handled
                    (code, None, _) => self.hosts.emit(HostsMsg::ShowError(format!(
                        "Stream session failed (punktfunk-session exit {code})"
                    ))),
                }
            }
            AppMsg::CancelPending => {
                self.close_waiting();
                self.busy = false;
                self.hosts.emit(HostsMsg::SetConnecting(None));
                self.toast("Cancelled — the request may still be pending on the host.");
            }
            AppMsg::ShowPreferences => {
                let hosts = self.hosts.sender().clone();
                crate::ui_settings::show(
                    &self.window,
                    self.settings.clone(),
                    &self.gamepad,
                    move || {
                        // The library toggle changes the saved cards' menu — re-render.
                        let _ = hosts.send(HostsMsg::Refresh);
                    },
                );
            }
            AppMsg::ShowShortcuts => shortcuts_window(&self.window).present(),
            AppMsg::ShowAbout => crate::ui_settings::show_about(&self.window),
            AppMsg::ShowAddHost => self.hosts.emit(HostsMsg::ShowAddHost),
            AppMsg::Toast(msg) => self.toast(&msg),
        }
    }
 }
 impl AppModel {
    pub fn toast(&self, msg: &str) {
        self.toasts.add_toast(adw::Toast::new(msg));
    }
-    pub fn hosts_ui(&self) -> Option<Rc<HostsUi>> {
+    fn close_waiting(&mut self) {
-        self.hosts.borrow().clone()
+        if let Some(w) = self.waiting.borrow_mut().take() {
            w.close();
        }
    }
-    pub fn browse_ui(&self) -> Option<Rc<crate::ui_gamepad_library::LauncherUi>> {
+    /// Measure the path to a host over the real data plane: connect, burst probe filler
-        self.browse.borrow().clone()
+    /// for 2 s, report goodput · loss · a recommended bitrate, and apply it in one tap.
    fn speed_test(&mut self, req: ConnectRequest, sender: &ComponentSender<AppModel>) {
        if std::mem::replace(&mut self.busy, true) {
            return;
        }
        let pin = req.fp_hex.as_deref().and_then(trust::parse_hex32);
        let status = gtk::Label::new(Some("Connecting…"));
        let dialog = adw::AlertDialog::new(Some("Network Speed Test"), Some(&req.name));
        dialog.set_extra_child(Some(&status));
        dialog.add_responses(&[("close", "Close"), ("apply", "Apply")]);
        dialog.set_response_enabled("apply", false);
        dialog.set_close_response("close");
        dialog.present(Some(&self.window));
-    /// Surface a connect failure: the launcher in browse mode, else the hosts page banner
+        let (tx, rx) =
-    /// (toast fallback pre-build).
+            async_channel::bounded::<Result<punktfunk_core::client::ProbeOutcome, String>>(1);
-    pub fn connect_error(&self, msg: &str) {
+        let identity = self.identity.clone();
-        match (self.browse_ui(), self.hosts_ui()) {
+        let (host, port) = (req.addr.clone(), req.port);
-            (Some(l), _) => l.show_error(msg),
+        std::thread::spawn(move || {
-            (_, Some(h)) => h.show_error(msg),
+            let result = (|| {
-            _ => self.toast(msg),
+                let c = NativeClient::connect(
                    &host,
                    port,
                    punktfunk_core::config::Mode {
                        width: 1280,
                        height: 720,
                        refresh_hz: 60,
                    },
                    CompositorPref::Auto,
                    GamepadPref::Auto,
                    0,                                // bitrate_kbps (host default)
                    0,                                // video_caps: probe connect, nothing presents
                    2,                                // audio_channels: stereo
                    crate::video::decodable_codecs(), // codecs (unused by the probe, but honest)
                    0,                                // preferred_codec: no preference
                    None,                             // launch: probe connect, no game
                    pin,
                    Some(identity),
                    std::time::Duration::from_secs(15),
                )
                .map_err(|e| format!("connect: {e:?}"))?;
                c.request_probe(3_000_000, 2_000)
                    .map_err(|e| format!("probe: {e:?}"))?;
                let deadline = std::time::Instant::now() + std::time::Duration::from_secs(10);
                loop {
                    std::thread::sleep(std::time::Duration::from_millis(250));
                    let r = c.probe_result();
                    if r.done {
                        // Let the last UDP shards land before tearing down.
                        std::thread::sleep(std::time::Duration::from_millis(400));
                        return Ok(c.probe_result());
                    }
                    if std::time::Instant::now() > deadline {
                        return Err("probe timed out".to_string());
                    }
                }
            })();
            let _ = tx.send_blocking(result);
        });
        let settings = self.settings.clone();
        let toasts = self.toasts.clone();
        let sender = sender.clone();
        glib::spawn_future_local(async move {
            let outcome = rx.recv().await;
            sender.input(AppMsg::SpeedTestDone);
            match outcome {
                Ok(Ok(r)) => {
                    let mbps = f64::from(r.throughput_kbps) / 1000.0;
                    let recommended_kbps = r.throughput_kbps / 10 * 7;
                    status.set_text(&format!(
                        "{mbps:.0} Mbit/s measured · {:.1} % loss\nRecommended bitrate: {:.0} Mbit/s",
                        r.loss_pct,
                        f64::from(recommended_kbps) / 1000.0,
                    ));
                    dialog.set_response_enabled("apply", true);
                    dialog.set_response_appearance("apply", adw::ResponseAppearance::Suggested);
                    dialog.connect_response(Some("apply"), move |_, _| {
                        let mut s = settings.borrow_mut();
                        s.bitrate_kbps = recommended_kbps;
                        s.save();
                        toasts.add_toast(adw::Toast::new(&format!(
                            "Bitrate set to {:.0} Mbit/s",
                            f64::from(recommended_kbps) / 1000.0
                        )));
                    });
                }
                Ok(Err(msg)) => status.set_text(&msg),
                Err(_) => {}
            }
        });
    }
 }
@@ -117,13 +526,8 @@ pub fn run() -> glib::ExitCode {
        )
        .init();
    // Steam launches its shortcuts with SDL_GAMECONTROLLER_IGNORE_DEVICES naming every
-    // physical pad Steam Input has virtualized — SDL then hides the real device so games
+    // physical pad Steam Input has virtualized; the Settings controller list needs the
-    // only see the virtual X360 pad. Right for games, wrong for us: capturing the Deck's
+    // real devices (same rationale as the session binary).
    // built-in controller (trackpads/paddles/gyro, 28DE:1205) needs SDL's HIDAPI driver
    // to enumerate the REAL device, and the built-in pad can never leave Steam Input
    // ("Steam Controller" is always-required), so this filter is the only off switch we
    // get. Clear it while still single-threaded (the gamepad worker starts with the UI);
    // we dedupe the virtual pad ourselves (`gamepad.rs` `active_id` skips steam_virtual).
    for var in [
        "SDL_GAMECONTROLLER_IGNORE_DEVICES",
        "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT",
@@ -133,148 +537,35 @@ pub fn run() -> glib::ExitCode {
            std::env::remove_var(var);
        }
    }
-    // Headless pairing path (no GTK window): `--pair <PIN> --connect host[:port] [--name N]`.
+    // Headless paths (no GTK window).
    // Used by the Decky plugin (a GTK dialog can't pop under gamescope) and for scripting.
    if let Some(pin) = crate::cli::arg_value("--pair") {
        return crate::cli::headless_pair(&pin);
    }
    // Headless library fetch (no GTK window): `--library host[:mgmt_port] [--fp HEX]`.
    if let Some(target) = crate::cli::arg_value("--library") {
        return crate::cli::headless_library(&target);
    }
    // Headless Wake-on-LAN (no GTK window): `--wake host[:port]`. The Decky wrapper calls this
    // before the stream launch so a sleeping host is up by the time `--connect` runs.
    if crate::cli::arg_value("--wake").is_some() {
        return crate::cli::cli_wake();
    }
    // Streams and the console library live in the session binary now — exec it,
    // forwarding the relevant argv (the Decky wrapper keeps working through the shell
    // until it's repointed).
    if crate::cli::arg_value("--connect").is_some() || crate::cli::arg_value("--browse").is_some() {
        return crate::cli::exec_session();
    }
    let mut builder = adw::Application::builder().application_id(APP_ID);
-    // Screenshot mode launches the app once per scene back-to-back; NON_UNIQUE keeps each
+    // Screenshot mode launches the app once per scene back-to-back; NON_UNIQUE keeps
-    // launch its own primary instance instead of forwarding to a still-registered name.
+    // each launch its own primary instance.
    if crate::cli::shot_scene().is_some() {
-        builder = builder.flags(gtk::gio::ApplicationFlags::NON_UNIQUE);
+        builder = builder.flags(gio::ApplicationFlags::NON_UNIQUE);
    }
    let app = builder.build();
    app.connect_activate(build_ui);
    // GTK doesn't see our argv (`--connect` is handled in `build_ui`); an empty argv also
    // keeps GApplication from rejecting unknown options.
    app.run_with_args(&[] as &[&str])
 }
 fn build_ui(gtk_app: &adw::Application) {
    let identity = match crate::trust::load_or_create_identity() {
        Ok(i) => i,
        Err(e) => {
            tracing::error!("client identity: {e:#}");
            std::process::exit(1);
        }
    };
    load_css();
    // Screenshot scenes must capture settled frames: kill every GTK/libadwaita animation
    // (nav-push slides especially — a headless session may starve the frame clock and
    // leave a transition frozen mid-flight in the capture).
    if crate::cli::shot_scene().is_some() {
        if let Some(s) = gtk::Settings::default() {
            s.set_gtk_enable_animations(false);
        }
    }
    let nav = adw::NavigationView::new();
    let toasts = adw::ToastOverlay::new();
    toasts.set_child(Some(&nav));
    let window = adw::ApplicationWindow::builder()
        .application(gtk_app)
        .title("Punktfunk")
        .default_width(1200)
        .default_height(780)
        .content(&toasts)
        .build();
    let fullscreen = crate::cli::fullscreen_mode();
    if fullscreen {
        // Chrome-less shell: no CSD rounding/shadow (see CSS — gamescope never ACKs the
        // fullscreen state, so GTK would keep them), and ask for fullscreen up front.
        window.add_css_class("pf-chromeless");
        window.fullscreen();
    }
    let app = Rc::new(App {
        window: window.clone(),
        nav: nav.clone(),
        toasts,
        settings: Rc::new(RefCell::new(Settings::load())),
        identity,
        gamepad: crate::gamepad::GamepadService::start(),
        busy: std::cell::Cell::new(false),
        fullscreen,
        // (`--browse` makes cli_connect_request None — browse mode returns to the
        // launcher on session end instead of quitting.)
        quit_on_session_end: fullscreen && crate::cli::cli_connect_request().is_some(),
        hosts: RefCell::new(None),
        browse: RefCell::new(None),
    });
    // Re-apply the persisted forwarded-controller pin (stable key; the service matches it
    // whenever such a pad connects) — without this the pin silently resets to Automatic on
    // every launch, and Automatic may resolve to a gyro-less pad (Steam's virtual gamepad).
    {
        let forward = app.settings.borrow().forward_pad.clone();
        if !forward.is_empty() {
            app.gamepad.set_pinned(Some(forward));
        }
    }
    // Browse mode (`--browse host`): the app IS the gamepad library launcher — it becomes
    // the ONE root page. No hosts page (whose construction starts the mDNS browse), no
    // header-menu actions; `Settings::library_enabled` is deliberately ignored (the flag
    // gates the desktop menu item — asking to browse IS the opt-in here).
    if let Some((req, paired, mgmt_port)) = crate::cli::cli_browse_request() {
        let launcher = crate::ui_gamepad_library::open(app.clone(), req, paired, mgmt_port);
        nav.add(&launcher.page);
        *app.browse.borrow_mut() = Some(launcher);
        window.present();
        return;
    }
    let hosts_ui = Rc::new(crate::ui_hosts::new(
        app.settings.clone(),
        HostsCallbacks {
            on_connect: {
                let app = app.clone();
                Rc::new(move |req| crate::ui_trust::initiate_connect(app.clone(), req))
            },
            on_speed_test: {
                let app = app.clone();
                Rc::new(move |req| speed_test(app.clone(), req))
            },
            on_pair: {
                let app = app.clone();
                Rc::new(move |req| {
                    if !app.busy.get() {
                        crate::ui_trust::pin_dialog(app.clone(), req);
                    }
                })
            },
            on_library: {
                let app = app.clone();
                Rc::new(move |req| crate::ui_library::open(app.clone(), req))
            },
        },
    ));
    *app.hosts.borrow_mut() = Some(hosts_ui.clone());
    install_actions(&app, &hosts_ui);
    nav.add(&hosts_ui.page);
    window.present();
    // CI screenshot mode: render one scripted, host-free scene and signal readiness
    // (clients/linux/tools/screenshots.sh). Mutually exclusive with a real connect.
    if let Some(scene) = crate::cli::shot_scene() {
        crate::cli::run_shot(app, &scene);
        return;
    }
    if let Some(req) = crate::cli::cli_connect_request() {
        crate::ui_trust::initiate_connect(app, req);
    }
    let adw_app = builder.build();
    // One SDL context for the whole process, started while single-threaded.
    let gamepad = crate::gamepad::GamepadService::start();
    let app = relm4::RelmApp::from_app(adw_app).with_args(Vec::new());
    app.run::<AppModel>(AppInit { gamepad });
    glib::ExitCode::SUCCESS
 }
 fn load_css() {
@@ -289,54 +580,23 @@ fn load_css() {
    }
 }
-/// Window actions behind the hosts page's header: the primary (hamburger) menu entries
+/// Window actions behind the hosts page's header (the primary menu + "+") — thin
-/// plus the "+" add-host button and the empty state's call to action.
+/// forwards into the message loop.
-fn install_actions(app: &Rc<App>, hosts: &Rc<HostsUi>) {
+fn install_actions(window: &adw::ApplicationWindow, sender: &ComponentSender<AppModel>) {
-    let add = |name: &str, f: Box<dyn Fn()>| {
+    let add = |name: &str, msg: fn() -> AppMsg| {
        let action = gio::SimpleAction::new(name, None);
-        action.connect_activate(move |_, _| f());
+        let sender = sender.clone();
-        app.window.add_action(&action);
+        action.connect_activate(move |_, _| sender.input(msg()));
        action
    };
-    {
+    window.add_action(&add("preferences", || AppMsg::ShowPreferences));
-        let app = app.clone();
+    window.add_action(&add("shortcuts", || AppMsg::ShowShortcuts));
-        add(
+    window.add_action(&add("about", || AppMsg::ShowAbout));
-            "preferences",
+    window.add_action(&add("add-host", || AppMsg::ShowAddHost));
            Box::new(move || {
                let refresh = {
                    let app = app.clone();
                    // The library toggle changes the saved cards' menu — re-render on close.
                    move || {
                        if let Some(h) = app.hosts_ui() {
                            h.refresh();
                        }
                    }
                };
                crate::ui_settings::show(&app.window, app.settings.clone(), &app.gamepad, refresh)
            }),
        );
    }
    {
        let window = app.window.clone();
        add(
            "shortcuts",
            Box::new(move || shortcuts_window(&window).present()),
        );
    }
    {
        let window = app.window.clone();
        add(
            "about",
            Box::new(move || crate::ui_settings::show_about(&window)),
        );
    }
    {
        let hosts = hosts.clone();
        add("add-host", Box::new(move || hosts.show_add_host()));
    }
 }
-/// The Keyboard Shortcuts window (menu + the shortcuts scene). GtkShortcutsWindow is
+/// The Keyboard Shortcuts window — the SESSION window's keys (the shell itself has
-/// builder-XML-first, so it's assembled from a snippet rather than widget calls.
+/// none); kept here as discoverable documentation.
 pub fn shortcuts_window(parent: &adw::ApplicationWindow) -> gtk::ShortcutsWindow {
    const UI: &str = r#"
 <interface>
@@ -346,11 +606,11 @@ pub fn shortcuts_window(parent: &adw::ApplicationWindow) -> gtk::ShortcutsWindow
      <object class="GtkShortcutsSection">
        <child>
          <object class="GtkShortcutsGroup">
-            <property name="title">Stream</property>
+            <property name="title">Stream (session window)</property>
            <child>
              <object class="GtkShortcutsShortcut">
                <property name="title">Toggle fullscreen</property>
-                <property name="accelerator">F11</property>
+                <property name="accelerator">F11 &lt;Alt&gt;Return</property>
              </object>
            </child>
            <child>
@@ -385,97 +645,3 @@ pub fn shortcuts_window(parent: &adw::ApplicationWindow) -> gtk::ShortcutsWindow
    window.set_transient_for(Some(parent));
    window
 }
 /// Measure the path to a host over the real data plane (Swift's "Test Network Speed…"):
 /// connect, have the host burst probe filler for 2 s up to its 3 Gbps ceiling, report
 /// goodput · loss · a recommended bitrate (≈70 % of measured), and apply it in one tap.
 fn speed_test(app: Rc<App>, req: ConnectRequest) {
    if app.busy.replace(true) {
        return;
    }
    let pin = req.fp_hex.as_deref().and_then(crate::trust::parse_hex32);
    let status = gtk::Label::new(Some("Connecting…"));
    let dialog = adw::AlertDialog::new(Some("Network Speed Test"), Some(&req.name));
    dialog.set_extra_child(Some(&status));
    dialog.add_responses(&[("close", "Close"), ("apply", "Apply")]);
    dialog.set_response_enabled("apply", false);
    dialog.set_close_response("close");
    dialog.present(Some(&app.window));
    let (tx, rx) =
        async_channel::bounded::<Result<punktfunk_core::client::ProbeOutcome, String>>(1);
    let identity = app.identity.clone();
    let (host, port) = (req.addr.clone(), req.port);
    std::thread::spawn(move || {
        let result = (|| {
            let c = NativeClient::connect(
                &host,
                port,
                punktfunk_core::config::Mode {
                    width: 1280,
                    height: 720,
                    refresh_hz: 60,
                },
                CompositorPref::Auto,
                GamepadPref::Auto,
                0,                                // bitrate_kbps (host default)
                0, // video_caps: the Linux client has no 10-bit/HDR present path yet
                2, // audio_channels: speed-test probe, stereo
                crate::video::decodable_codecs(), // codecs (unused by the probe, but honest)
                0, // preferred_codec: no preference for a speed-test probe
                None, // launch: speed-test probe connect, no game
                pin,
                Some(identity),
                std::time::Duration::from_secs(15),
            )
            .map_err(|e| format!("connect: {e:?}"))?;
            c.request_probe(3_000_000, 2_000)
                .map_err(|e| format!("probe: {e:?}"))?;
            let deadline = std::time::Instant::now() + std::time::Duration::from_secs(10);
            loop {
                std::thread::sleep(std::time::Duration::from_millis(250));
                let r = c.probe_result();
                if r.done {
                    // Let the last UDP shards land before tearing down.
                    std::thread::sleep(std::time::Duration::from_millis(400));
                    return Ok(c.probe_result());
                }
                if std::time::Instant::now() > deadline {
                    return Err("probe timed out".to_string());
                }
            }
        })();
        let _ = tx.send_blocking(result);
    });
    glib::spawn_future_local(async move {
        let outcome = rx.recv().await;
        app.busy.set(false);
        match outcome {
            Ok(Ok(r)) => {
                let mbps = f64::from(r.throughput_kbps) / 1000.0;
                let recommended_kbps = r.throughput_kbps / 10 * 7;
                status.set_text(&format!(
                    "{mbps:.0} Mbit/s measured · {:.1} % loss\nRecommended bitrate: {:.0} Mbit/s",
                    r.loss_pct,
                    f64::from(recommended_kbps) / 1000.0,
                ));
                dialog.set_response_enabled("apply", true);
                dialog.set_response_appearance("apply", adw::ResponseAppearance::Suggested);
                let settings = app.settings.clone();
                let toasts = app.toasts.clone();
                dialog.connect_response(Some("apply"), move |_, _| {
                    let mut s = settings.borrow_mut();
                    s.bitrate_kbps = recommended_kbps;
                    s.save();
                    toasts.add_toast(adw::Toast::new(&format!(
                        "Bitrate set to {:.0} Mbit/s",
                        f64::from(recommended_kbps) / 1000.0
                    )));
                });
            }
            Ok(Err(msg)) => status.set_text(&msg),
            Err(_) => {}
        }
    });
 }
@@ -1,12 +1,27 @@
-//! Command-line entry paths: argv helpers, headless pairing, `--connect`, and the CI
+//! Command-line entry paths: argv helpers, the headless flows (pair/wake/library), the
-//! screenshot scenes.
+//! exec handoff to `punktfunk-session` for `--connect`/`--browse`, and the CI screenshot
 //! scenes.
-use crate::app::App;
+use crate::app::AppModel;
-use crate::ui_hosts::ConnectRequest;
+use crate::ui_hosts::{ConnectRequest, HostsMsg};
 use gtk::glib;
 use gtk::prelude::*;
 use relm4::prelude::*;
 use std::cell::RefCell;
 use std::rc::Rc;
 /// The handles `run_shot` needs — cloned out of `AppModel` before it moves into the
 /// component parts, so the scene can be dispatched from the window's `map` callback.
 pub struct ShotCtx {
    pub window: adw::ApplicationWindow,
    pub nav: adw::NavigationView,
    pub hosts: relm4::Sender<HostsMsg>,
    pub settings: Rc<RefCell<crate::trust::Settings>>,
    pub gamepad: crate::gamepad::GamepadService,
    pub identity: (String, String),
    pub sender: ComponentSender<AppModel>,
 }
 /// The value following `flag` in argv, if present (`--flag value`).
 pub fn arg_value(flag: &str) -> Option<String> {
    std::env::args()
@@ -20,9 +35,8 @@ fn arg_flag(flag: &str) -> bool {
    std::env::args().any(|a| a == flag)
 }
-/// Run the stream fullscreen with no window chrome — the Steam Deck / Gaming-Mode launch path.
+/// Fullscreen the shell — the Gaming-Mode fallback for a bare launch (streams and the
-/// The Decky wrapper passes `--fullscreen`; we also honor the Deck/gamescope env as a fallback
+/// console library exec the session binary, which handles its own fullscreen).
 /// so a manual launch under Gaming Mode does the right thing too.
 pub fn fullscreen_mode() -> bool {
    arg_flag("--fullscreen")
        || std::env::var_os("SteamDeck").is_some()
@@ -38,9 +52,42 @@ fn parse_host_port(target: &str) -> (String, Option<u16>) {
    }
 }
 /// `--connect` / `--browse`: streams and the console library live in the
 /// `punktfunk-session` Vulkan binary — replace this process with it, forwarding the
 /// relevant argv verbatim. This keeps the Decky wrapper (which launches the SHELL with
 /// these flags) working unchanged until it's repointed at the session binary.
 pub fn exec_session() -> glib::ExitCode {
    use std::os::unix::process::CommandExt as _;
    let forward = [
        "--connect",
        "--browse",
        "--fp",
        "--launch",
        "--mgmt",
        "--connect-timeout",
    ];
    let mut cmd = std::process::Command::new(crate::spawn::session_binary());
    let mut args = std::env::args().skip(1).peekable();
    while let Some(a) = args.next() {
        if a == "--fullscreen" || a == "--stats" {
            cmd.arg(a);
        } else if forward.contains(&a.as_str()) {
            cmd.arg(&a);
            if let Some(v) = args.peek() {
                if !v.starts_with("--") {
                    cmd.arg(args.next().unwrap());
                }
            }
        }
    }
    let err = cmd.exec(); // only returns on failure
    eprintln!("exec punktfunk-session: {err}");
    glib::ExitCode::FAILURE
 }
 /// Run the SPAKE2 PIN ceremony without a GTK window and persist the verified host to the
 /// known-hosts store as paired, so a later `--connect` connects silently. Same identity
-/// store the streaming path uses (same binary), so pairing here makes the stream work.
+/// store the streaming path uses, so pairing here makes the stream work.
 /// Prints a one-line `paired <addr>:<port> fp=<hex>` on success; exits non-zero on failure.
 pub fn headless_pair(pin: &str) -> glib::ExitCode {
    let Some(target) = arg_value("--connect") else {
@@ -79,50 +126,8 @@ pub fn headless_pair(pin: &str) -> glib::ExitCode {
    }
 }
-/// `--connect host[:port]` — skip the hosts page and start a session immediately
+/// `--wake host[:port]` — send a Wake-on-LAN magic packet to a saved host and exit,
-/// (scripting + headless testing). Trust follows the same rules as a manual entry: a host
+/// without opening a window. The MAC comes from the known-hosts store (learned from the
 /// already pinned at this address connects silently on its stored pin; an unknown host is
 /// routed to the PIN ceremony (never a silent TOFU connect — `fp_hex`/`pair_optional` are
 /// unset, so `initiate_connect`'s manual arm mandates pairing).
 ///
 /// `--launch <id>` asks the host to launch that library title (store-qualified id from
 /// `--library`, e.g. `steam:570` — the Decky wrapper's `PF_LAUNCH`); the raw id doubles
 /// as the stream title (best-effort — no extra fetch just for a prettier label).
 pub fn cli_connect_request() -> Option<ConnectRequest> {
    if arg_value("--browse").is_some() {
        return None; // browse mode owns the session lifecycle (precedence over --connect)
    }
    let target = std::env::args().skip_while(|a| a != "--connect").nth(1)?;
    let (addr, port) = parse_host_port(&target);
    // An unparsable port (`host:notaport`) used to make the whole request `None` → the app
    // silently landed on the hosts page with no session and no message. Fall back to the
    // native default like the add-host dialog, and say so, instead of doing nothing.
    let port = port.unwrap_or_else(|| {
        eprintln!("--connect: unparsable port in '{target}', using default 9777");
        9777
    });
    // Pull the wake MAC(s) from the store (learned from the host's mDNS `mac` TXT while it was
    // online) so a `--connect` to a known host can still be woken if we add that later.
    let mac = crate::trust::KnownHosts::load()
        .hosts
        .iter()
        .find(|h| h.addr == addr && h.port == port)
        .map(|h| h.mac.clone())
        .unwrap_or_default();
    Some(ConnectRequest {
        name: addr.clone(),
        addr,
        port,
        fp_hex: None,
        pair_optional: false,
        launch: arg_value("--launch").map(|id| (id.clone(), id)),
        mac,
    })
 }
 /// `--wake host[:port]` — send a Wake-on-LAN magic packet to a saved host and exit, without
 /// opening a window. The Decky wrapper calls this before launching the stream so a sleeping host
 /// is up by the time `--connect` runs. The MAC comes from the known-hosts store (learned from the
 /// host's mDNS `mac` TXT while it was online); exits non-zero if none is known yet.
 pub fn cli_wake() -> glib::ExitCode {
    let Some(target) = arg_value("--wake") else {
@@ -149,44 +154,9 @@ pub fn cli_wake() -> glib::ExitCode {
    glib::ExitCode::SUCCESS
 }
 /// `--browse host[:port]` — open the gamepad library launcher for that host instead of
 /// connecting (the Decky wrapper's `PF_BROWSE`; native port, default 9777). The host must
 /// already be paired: the stored pin is what lets the launcher fetch the library and
 /// connect silently — no dialog can run under gamescope, so an unpaired target renders
 /// the launcher's pair-first scene. Returns the request (name + stored fingerprint from
 /// the known-hosts store), whether it's paired, and the mgmt port (`--mgmt <port>`, the
 /// wrapper's `PF_MGMT`; default 47990 — browse mode runs no mDNS to learn it).
 pub fn cli_browse_request() -> Option<(ConnectRequest, bool, u16)> {
    let target = arg_value("--browse")?;
    let (addr, port) = parse_host_port(&target);
    let port = port.unwrap_or(9777);
    let known = crate::trust::KnownHosts::load();
    let k = known
        .hosts
        .iter()
        .find(|h| h.addr == addr && h.port == port);
    let mgmt = arg_value("--mgmt")
        .and_then(|p| p.parse().ok())
        .unwrap_or(crate::library::DEFAULT_MGMT_PORT);
    Some((
        ConnectRequest {
            name: k.map_or_else(|| addr.clone(), |k| k.name.clone()),
            addr,
            port,
            fp_hex: k.map(|k| k.fp_hex.clone()),
            pair_optional: false,
            launch: None,
            mac: k.map(|k| k.mac.clone()).unwrap_or_default(),
        },
        k.is_some_and(|k| k.paired),
        mgmt,
    ))
 }
 /// `--library host[:mgmt_port]` — fetch and print the host's game library over the real
-/// mTLS + pinned-fingerprint client, no GTK window (scripting, and the live-API proof
+/// mTLS + pinned-fingerprint client, no GTK window. The pin comes from `--fp HEX` when
-/// that the library HTTP path works against a real host). The pin comes from `--fp HEX`
+/// given, else the known-hosts store (matched by address), else none (TOFU-accept).
 /// when given, else the known-hosts store (matched by address), else none (TOFU-accept).
 pub fn headless_library(target: &str) -> glib::ExitCode {
    let (addr, port) = match target.rsplit_once(':') {
        Some((a, p)) if p.parse::<u16>().is_ok() => (a.to_string(), p.parse().unwrap()),
@@ -231,15 +201,14 @@ pub fn shot_scene() -> Option<String> {
        .filter(|s| !s.is_empty())
 }
-/// Render one mock-populated, host-free scene over the already-presented window, then print
+/// Render one mock-populated, host-free scene over the already-presented window, then
-/// `PF_SHOT_READY` once it has had a moment to map + settle so the driver knows when to capture.
+/// print `PF_SHOT_READY` once it has settled. When `PUNKTFUNK_SHOT_OUT=/path.png` is set
-/// When `PUNKTFUNK_SHOT_OUT=/path.png` is set the app CAPTURES ITSELF first (widget snapshot →
+/// the app CAPTURES ITSELF (widget snapshot → gsk render → PNG) — no Xvfb/ImageMagick
-/// gsk render → PNG, see `save_png`) — no Xvfb/ImageMagick needed, and libadwaita dialogs are
+/// needed. The stream and gamepad-library scenes are gone with the pages (both live in
-/// in-window overlays so they land in the frame. No `NativeClient` or session is created. The
+/// the session binary now).
-/// stream scene is deliberately absent — its page requires a live connector (`ui_stream::new`
+pub fn run_shot(ctx: &ShotCtx, scene: &str) {
-/// takes an `Arc<NativeClient>`).
+    let sender = &ctx.sender;
-pub fn run_shot(app: Rc<App>, scene: &str) {
+    // A plausible host for the trust/pair dialogs (fp_hex = 64 hex chars).
    // A plausible host for the trust/pair dialogs (fp_hex is 64 hex chars, like a real SHA-256).
    let mock_req = || ConnectRequest {
        name: "Living Room PC".to_string(),
        addr: "192.168.1.42".to_string(),
@@ -266,57 +235,52 @@ pub fn run_shot(app: Rc<App>, scene: &str) {
    // What the self-capture renders: the main window, except for scenes that open their
    // own toplevel (the shortcuts window).
-    let mut target: gtk::Widget = app.window.clone().upcast();
+    let mut target: gtk::Widget = ctx.window.clone().upcast();
    let hosts = &ctx.hosts;
    match scene {
-        // The saved-hosts grid reads ~/.config/punktfunk/client-known-hosts.json, which the
+        // Saved hosts come from the seeded known-hosts store; on top, inject synthetic
-        // driver seeds. On top, inject synthetic adverts through the same path the mDNS
+        // adverts through the same path the mDNS stream feeds.
        // stream feeds: one matching the seeded saved host (ONLINE pip + dedup out of the
        // discovered grid) and one unknown pair=required host (PIN pill).
        "hosts" | "02-hosts" => {
-            if let Some(h) = app.hosts_ui() {
+            let _ = hosts.send(HostsMsg::Advert(mock_advert(
                h.inject_advert(mock_advert(
                "mock-online",
                "Living Room PC",
                "192.168.1.42",
                "9f8e7d6c5b4a39281706f5e4d3c2b1a0998877665544332211ffeeddccbbaa00",
-                ));
+            )));
-                h.inject_advert(mock_advert(
+            let _ = hosts.send(HostsMsg::Advert(mock_advert(
                "mock-new",
                "steamdeck",
                "192.168.1.77",
                "00aabbccddeeff112233445566778899a0b1c2d3e4f5061728394a5b6c7d8e9f",
-                ));
+            )));
            }
        }
        "settings" | "03-settings" => {
-            crate::ui_settings::show(&app.window, app.settings.clone(), &app.gamepad, || {});
+            crate::ui_settings::show(&ctx.window, ctx.settings.clone(), &ctx.gamepad, || {});
        }
        "trust" | "04-trust" => crate::ui_trust::tofu_dialog(&ctx.window, sender, mock_req()),
        "pair" | "05-pair" => {
            crate::ui_trust::pin_dialog(&ctx.window, sender, ctx.identity.clone(), mock_req())
        }
        "trust" | "04-trust" => crate::ui_trust::tofu_dialog(app.clone(), mock_req()),
        "pair" | "05-pair" => crate::ui_trust::pin_dialog(app.clone(), mock_req()),
        "addhost" | "06-addhost" => {
-            if let Some(h) = app.hosts_ui() {
+            let _ = hosts.send(HostsMsg::ShowAddHost);
                h.show_add_host();
            }
        }
        "shortcuts" | "07-shortcuts" => {
-            let w = crate::app::shortcuts_window(&app.window);
+            let w = crate::app::shortcuts_window(&ctx.window);
            w.present();
            target = w.upcast();
        }
        // The library page with injected entries: mixed stores exercising the badge set,
-        // no-art placeholders (monogram tiles), and one solid-color texture standing in
+        // no-art placeholders, and one solid-color texture standing in for a poster.
        // for a loaded poster (the real poster path, minus the network).
        "library" | "08-library" => {
            let (games, art) = mock_library();
-            crate::ui_library::open_mock(app.clone(), mock_req(), games, art);
+            crate::ui_library::open_mock(
-        }
+                &ctx.nav,
-        // The gamepad launcher (`--browse`) with the same injected entries — cursor sits
+                ctx.identity.clone(),
-        // at 1 so both recede directions show; aurora + easing render frozen (shot mode).
+                sender,
-        "gamepad-library" | "09-gamepad-library" => {
+                mock_req(),
-            let (games, art) = mock_library();
+                games,
-            let ui = crate::ui_gamepad_library::open_mock(app.clone(), mock_req(), games, art);
+                art,
-            app.nav.push(&ui.page);
+            );
            *app.browse.borrow_mut() = Some(ui);
        }
        other => tracing::warn!("unknown PUNKTFUNK_SHOT_SCENE={other:?}; showing hosts only"),
    }
@@ -328,6 +292,10 @@ pub fn run_shot(app: Rc<App>, scene: &str) {
    let scene = scene.to_string();
    glib::timeout_add_local_once(std::time::Duration::from_millis(settle_ms), move || {
        use std::io::Write as _;
        // Self-capture of the dialog scenes (trust/pair/settings/addhost) needs a GL
        // renderer: `WidgetPaintable(window)` under the cairo software renderer doesn't
        // composite the `AdwDialog` overlay layer (the dialog IS presented — the
        // page-content scenes capture fine either way; CI uses GL or the X11 root-grab).
        let self_capture = std::env::var("PUNKTFUNK_SHOT_OUT")
            .ok()
            .filter(|p| !p.is_empty());
@@ -338,17 +306,16 @@ pub fn run_shot(app: Rc<App>, scene: &str) {
        }
        println!("PF_SHOT_READY scene={scene}");
        let _ = std::io::stdout().flush();
-        // Self-capture mode: the shot is on disk — exit so back-to-back scene runs don't
+        // Self-capture mode: the shot is on disk — exit so back-to-back scene runs
-        // stack windows on a live desktop. (The X11-fallback driver captures externally
+        // don't stack windows on a live desktop.
        // after READY and kills us itself.)
        if self_capture.is_some() {
            std::process::exit(0);
        }
    });
 }
-/// The mock game set shared by the `library` and `gamepad-library` scenes: mixed stores
+/// The mock game set for the `library` scene: mixed stores exercising the badge set,
-/// exercising the badge set, plus one solid-colour poster texture.
+/// plus one solid-colour poster texture.
 fn mock_library() -> (
    Vec<crate::library::GameEntry>,
    Vec<(String, gtk::gdk::Texture)>,
@@ -391,7 +358,6 @@ fn solid_texture(w: i32, h: i32, r: u8, g: u8, b: u8) -> gtk::gdk::Texture {
 /// `gtk::Snapshot` → the realized native's gsk renderer → `GdkTexture::save_to_png`.
 fn save_png(widget: &gtk::Widget, path: &str) -> anyhow::Result<()> {
    use anyhow::Context as _;
    use gtk::prelude::*;
    let (w, h) = (widget.width(), widget.height());
    anyhow::ensure!(w > 0 && h > 0, "widget not laid out yet ({w}x{h})");
    let paintable = gtk::WidgetPaintable::new(Some(widget));
@@ -1,396 +0,0 @@
 //! Session launch: resolve the stream mode, spawn the session worker, and drive its
 //! event stream into the UI (trust persistence, stream-page push, teardown).
 use crate::app::App;
 use crate::session::{SessionEvent, SessionParams, Stats};
 use crate::trust;
 use crate::ui_hosts::ConnectRequest;
 use crate::video::DecodedFrame;
 use adw::prelude::*;
 use gtk::{gdk, glib};
 use punktfunk_core::client::NativeClient;
 use punktfunk_core::config::{CompositorPref, GamepadPref, Mode};
 use std::rc::Rc;
 use std::sync::atomic::AtomicBool;
 use std::sync::Arc;
 /// The mode to request: explicit settings, with `0` fields resolved to the native
 /// size/refresh of the monitor the window currently occupies (mirrors the Swift client's
 /// native-display default).
 fn resolve_mode(app: &App) -> Mode {
    let s = app.settings.borrow();
    let mut mode = Mode {
        width: s.width,
        height: s.height,
        refresh_hz: s.refresh_hz,
    };
    if mode.width == 0 || mode.refresh_hz == 0 {
        // Prefer the monitor the window is on; fall back to the display's first monitor. On a
        // `--connect` launch the window may not be mapped yet when this runs, and without the
        // fallback we'd drop to the 1920×1080 floor below — wrong on the Deck (1280×800).
        let monitor = app
            .window
            .surface()
            .zip(gdk::Display::default())
            .and_then(|(surf, d)| d.monitor_at_surface(&surf))
            .or_else(|| {
                gdk::Display::default()
                    .and_then(|d| d.monitors().item(0))
                    .and_then(|o| o.downcast::<gdk::Monitor>().ok())
            });
        if let Some(m) = monitor {
            let geo = m.geometry();
            let scale = m.scale_factor().max(1);
            if mode.width == 0 {
                mode.width = (geo.width() * scale) as u32;
                mode.height = (geo.height() * scale) as u32;
            }
            if mode.refresh_hz == 0 {
                mode.refresh_hz = ((m.refresh_rate() + 500) / 1000).max(30) as u32;
            }
        }
    }
    // No monitor info (early call, odd compositor) — a sane floor.
    if mode.width == 0 {
        (mode.width, mode.height) = (1920, 1080);
    }
    if mode.refresh_hz == 0 {
        mode.refresh_hz = 60;
    }
    mode
 }
 /// Tunables for a session start that differ between the normal connect and the "request access"
 /// (delegated-approval) flow. `Default` is the normal connect.
 pub struct StartOpts {
    /// Handshake budget. The request-access flow uses a long one because the host PARKS the
    /// connection until the operator clicks Approve (see the host's `PENDING_APPROVAL_WAIT`).
    pub connect_timeout: std::time::Duration,
    /// Persist the host as *paired* on a successful connect. Set for request-access, where the
    /// operator's approval IS the pairing, so future connects are silent (rule 1). Normal TOFU
    /// persists the host *unpaired* (pinned, but not PIN/approval-verified).
    pub persist_paired: bool,
    /// A "waiting for approval" dialog to dismiss on the first session event (request-access only).
    pub waiting: Option<adw::AlertDialog>,
    /// Set by the waiting dialog's Cancel button. `NativeClient::connect` is a blocking call with
    /// no abort, so Cancel returns the UI immediately (clears busy, closes the dialog) and leaves
    /// the in-flight connect to time out; when it finally resolves, the event loop sees this flag
    /// and tears down silently (drops the connector → closes the connection) without touching the
    /// UI a new session may already own.
    pub cancel: Option<Rc<std::cell::Cell<bool>>>,
 }
 impl Default for StartOpts {
    fn default() -> Self {
        Self {
            connect_timeout: std::time::Duration::from_secs(15),
            persist_paired: false,
            waiting: None,
            cancel: None,
        }
    }
 }
 pub fn start_session(app: Rc<App>, req: ConnectRequest, pin: Option<[u8; 32]>) {
    start_session_with(app, req, pin, StartOpts::default());
 }
 pub fn start_session_with(
    app: Rc<App>,
    req: ConnectRequest,
    pin: Option<[u8; 32]>,
    opts: StartOpts,
 ) {
    if app.busy.replace(true) {
        return;
    }
    let mode = resolve_mode(&app);
    let s = app.settings.borrow();
    // The presenter raises this when hardware frames can't be displayed; the session pump
    // demotes the decoder to software (see `SessionParams::force_software`).
    let force_software = Arc::new(AtomicBool::new(false));
    let params = SessionParams {
        host: req.addr.clone(),
        port: req.port,
        mode,
        compositor: CompositorPref::from_name(&s.compositor).unwrap_or(CompositorPref::Auto),
        // "Automatic" matches the physical pad (Swift parity); an explicit choice wins.
        gamepad: match GamepadPref::from_name(&s.gamepad) {
            Some(GamepadPref::Auto) | None => app.gamepad.auto_pref(),
            Some(explicit) => explicit,
        },
        bitrate_kbps: s.bitrate_kbps,
        mic_enabled: s.mic_enabled,
        audio_channels: s.audio_channels,
        preferred_codec: s.preferred_codec(),
        decoder: s.decoder.clone(),
        launch: req.launch.as_ref().map(|(id, _)| id.clone()),
        pin,
        identity: app.identity.clone(),
        connect_timeout: opts.connect_timeout,
        force_software: force_software.clone(),
    };
    let inhibit = s.inhibit_shortcuts;
    let show_stats = s.show_stats;
    drop(s);
    let cancel = opts.cancel;
    // Card feedback while the connect is in flight: spinner on the matching hosts card,
    // stale failure banner dismissed. Cleared again on Connected/Failed/Ended.
    if let Some(h) = app.hosts_ui() {
        h.clear_error();
        h.set_connecting(Some(req.card_key()));
    }
    let mut handle = crate::session::start(params);
    let frames = std::mem::replace(&mut handle.frames, async_channel::bounded(1).1);
    let mut ctx = SessionUi {
        stop: handle.stop.clone(),
        app,
        req,
        persist_paired: opts.persist_paired,
        tofu: pin.is_none(),
        inhibit,
        show_stats,
        frames: Some(frames),
        force_software,
        waiting: opts.waiting,
        page: None,
    };
    glib::spawn_future_local(async move {
        while let Ok(event) = handle.events.recv().await {
            // A cancelled request-access connect resolved late: tear down silently. Don't touch
            // app.busy — Cancel already cleared it, and a fresh session may now own it.
            if cancel.as_ref().is_some_and(|c| c.get()) {
                ctx.close_waiting();
                break;
            }
            match event {
                SessionEvent::Connected {
                    connector,
                    mode,
                    fingerprint,
                } => ctx.on_connected(connector, mode, fingerprint),
                SessionEvent::Stats(s) => ctx.on_stats(s),
                SessionEvent::Failed {
                    msg,
                    trust_rejected,
                } => {
                    ctx.on_failed(&msg, trust_rejected);
                    break;
                }
                SessionEvent::Ended(err) => {
                    ctx.on_ended(err);
                    break;
                }
            }
        }
    });
 }
 /// UI-side state one session's event loop carries between events.
 struct SessionUi {
    app: Rc<App>,
    req: ConnectRequest,
    /// Persist the host as PAIRED on `Connected` (request-access — the approval IS the pairing).
    persist_paired: bool,
    /// This is a TOFU connect (no stored pin): pin the observed fingerprint on `Connected`.
    tofu: bool,
    /// Grab compositor shortcuts while input is captured (Settings).
    inhibit: bool,
    /// Show the stats OSD when the stream page opens (Settings; live-toggled on-page).
    show_stats: bool,
    stop: Arc<AtomicBool>,
    /// Decoded-frame receiver, handed to the stream page once on `Connected`.
    frames: Option<async_channel::Receiver<DecodedFrame>>,
    /// Shared with the session pump — the stream page's presenter raises it to demote
    /// the decoder to software when hardware frames can't be displayed.
    force_software: Arc<AtomicBool>,
    /// The "waiting for approval" dialog (request-access flow), dismissed on the first event.
    waiting: Option<adw::AlertDialog>,
    page: Option<crate::ui_stream::StreamPage>,
 }
 impl SessionUi {
    /// Dismiss the "waiting for approval" dialog (request-access flow), if any.
    fn close_waiting(&mut self) {
        if let Some(w) = self.waiting.take() {
            w.close();
        }
    }
    /// `Connected`: record the configured trust decision, attach gamepads, and push the
    /// stream page.
    fn on_connected(&mut self, connector: Arc<NativeClient>, mode: Mode, fingerprint: [u8; 32]) {
        self.close_waiting();
        if let Some(h) = self.app.hosts_ui() {
            h.set_connecting(None);
        }
        if self.persist_paired {
            // Request-access: the operator approved this device, so record the host as
            // a trusted PAIRED host (pinning the fingerprint we observed) — future
            // connects are then silent (rule 1), exactly like after a PIN ceremony.
            let fp_hex = trust::hex(&fingerprint);
            trust::persist_host(&self.req.name, &self.req.addr, self.req.port, &fp_hex, true);
            self.app.toast("Approved — connecting…");
        } else if self.tofu {
            // A TOFU connect just observed the real fingerprint — pin it from now on.
            let fp_hex = trust::hex(&fingerprint);
            trust::persist_host(
                &self.req.name,
                &self.req.addr,
                self.req.port,
                &fp_hex,
                false,
            );
            self.app.toast(&format!(
                "Trusted on first use — fingerprint {}…",
                &fp_hex[..16]
            ));
        }
        // Stamp the successful connect — this host's card carries the accent bar now.
        trust::touch_last_used(&trust::hex(&fingerprint));
        tracing::debug!(?mode, "connected — pushing stream page");
        // A library launch titles the stream with the game, not the host.
        let name = self
            .req
            .launch
            .as_ref()
            .map_or(self.req.name.as_str(), |(_, game)| game.as_str());
        let title = format!(
            "{name} · {}×{}@{}",
            mode.width, mode.height, mode.refresh_hz
        );
        self.app.gamepad.attach(connector.clone());
        let clock_offset_ns = connector.clock_offset_ns;
        let p = crate::ui_stream::new(crate::ui_stream::StreamPageArgs {
            window: self.app.window.clone(),
            connector,
            frames: self.frames.take().expect("Connected delivered once"),
            force_software: self.force_software.clone(),
            clock_offset_ns,
            escape_rx: self.app.gamepad.escape_events(),
            disconnect_rx: self.app.gamepad.disconnect_events(),
            stop: self.stop.clone(),
            inhibit_shortcuts: self.inhibit,
            show_stats: self.show_stats,
            chromeless: self.app.fullscreen,
            // The attach just went out, so a Deck's built-in pad may not have enumerated
            // yet — chromeless (controller-first) shows the chord hint regardless.
            pad_connected: self.app.gamepad.active().is_some(),
            title,
        });
        self.app.nav.push(&p.page);
        // Streams start fullscreen by default (Settings toggle) — a streaming window with
        // chrome is never what anyone wants mid-game; F11 / the controller chord / the
        // top-edge header reveal lead back out. Gaming-Mode launches (`--fullscreen`)
        // fullscreen regardless: gamescope fullscreens the window at its level but GTK
        // doesn't know it, so the header bar would stay drawn.
        if self.app.fullscreen || self.app.settings.borrow().fullscreen_on_stream {
            self.app.window.fullscreen();
        }
        // A Deck streaming without its raw built-in controller is invisible degradation:
        // SDL sees only Steam's virtual X360 pad, so the right trackpad arrives at the
        // host as whatever Steam's template synthesizes (a right stick by default) and
        // the left trackpad, paddles and gyro not at all. The built-in pad can never
        // leave Steam Input ("Steam Controller" is always-required in the shortcut's
        // matrix — Disable Steam Input only affects other brands), so raw capture rides
        // the session-scoped Valve HIDAPI drivers + the cleared SDL device filter (see
        // `app::run`). The real 28DE:1205 identity enumerates shortly after attach —
        // check once that settles and say so, instead of streaming silently degraded.
        if crate::gamepad::is_steam_deck() {
            let app = self.app.clone();
            let stop = self.stop.clone();
            glib::timeout_add_seconds_local_once(4, move || {
                if stop.load(std::sync::atomic::Ordering::Relaxed) {
                    return; // session already over
                }
                if app.gamepad.active().is_none_or(|pad| pad.steam_virtual) {
                    tracing::warn!(
                        "the Deck's raw built-in controller (28DE:1205) never enumerated \
                         — only Steam's virtual pad is visible, so trackpads, paddles and \
                         gyro can't be captured (sticks + buttons still work). Check the \
                         startup log for SDL_GAMECONTROLLER_IGNORE_DEVICES and the \
                         Settings controller list."
                    );
                    let toast = adw::Toast::new(
                        "Steam is only exposing its virtual gamepad — trackpads, paddles \
                         and gyro won't reach the game (sticks and buttons still work).",
                    );
                    toast.set_timeout(12);
                    app.toasts.add_toast(toast);
                }
            });
        }
        self.page = Some(p);
    }
    fn on_stats(&self, s: Stats) {
        if let Some(p) = &self.page {
            p.update_stats(s);
        }
    }
    /// `Failed`: surface the error; a trust rejection on a pinned connect routes to re-pairing.
    fn on_failed(&mut self, msg: &str, trust_rejected: bool) {
        self.close_waiting();
        tracing::warn!(%msg, trust_rejected, "connect failed");
        self.app.busy.set(false);
        if let Some(h) = self.app.hosts_ui() {
            h.set_connecting(None);
        }
        // A pinned connect rejected on trust grounds means the host's cert no
        // longer matches the stored pin (rotated cert or impostor) — route to
        // the PIN ceremony to re-establish trust rather than dead-ending. Browse
        // mode can't: gamescope never maps dialogs, so it renders the advice instead
        // (re-pairing is the plugin's job there).
        if trust_rejected && !self.tofu && self.app.browse_ui().is_none() {
            self.app
                .toast("Host fingerprint changed — re-pair with a PIN to continue");
            crate::ui_trust::pin_dialog(self.app.clone(), self.req.clone());
        } else if trust_rejected && !self.tofu {
            self.app
                .connect_error("Host identity changed — re-pair from the Punktfunk plugin.");
        } else {
            // Errors land on the hosts page banner / launcher strip, not a transient toast.
            self.app.connect_error(&format!("Couldn't connect — {msg}"));
        }
    }
    /// `Ended`: detach gamepads, pop back to the launcher (browse mode) or the hosts
    /// page, and surface the reason.
    fn on_ended(&mut self, err: Option<String>) {
        self.close_waiting();
        self.app.gamepad.detach();
        // Gaming-Mode `--connect` launch: the app IS the stream. Quit so Steam ends the
        // "game" and the Deck returns to Gaming Mode — popping to our own hosts page would
        // strand the user in a fullscreen shell with no way back.
        if self.app.quit_on_session_end {
            if let Some(e) = err {
                tracing::warn!(error = %e, "session ended");
            }
            self.app.window.close();
            return;
        }
        // Browse mode: back to the launcher to pick the next game — B there quits to
        // Gaming Mode. (The gamepad worker re-opened the pad and armed the held-state
        // snapshot on the detach above, so the chord that ended the session fires nothing.)
        if let Some(l) = self.app.browse_ui() {
            self.app.nav.pop_to_tag("launcher");
            l.on_session_ended();
            if let Some(e) = err {
                self.app.connect_error(&e);
            }
            self.app.busy.set(false);
            return;
        }
        self.app.nav.pop_to_tag("hosts");
        if let Some(h) = self.app.hosts_ui() {
            h.set_connecting(None);
        }
        if let Some(e) = err {
            self.app.connect_error(&e);
        }
        self.app.busy.set(false);
    }
 }
@@ -1,32 +1,20 @@
-//! `punktfunk-client` — the native Linux punktfunk/1 client (design: Option A, 2026-06-12).
+//! `punktfunk-client` — the native Linux punktfunk/1 desktop shell (relm4/libadwaita).
 //!
-//! GTK4/libadwaita shell · `NativeClient` linked as a crate (no C ABI) · FFmpeg decode →
+//! Hosts, pairing/trust, settings, and the desktop library page; every stream (and the
-//! `GtkGraphicsOffload` present · PipeWire audio · SDL3 gamepads. The trust surface
+//! console game library) runs in the spawned `punktfunk-session` Vulkan binary — the
-//! mirrors the Apple client: persistent identity, TOFU prompt with the host fingerprint,
+//! shell never touches video (punktfunk-planning `linux-client-rearchitecture.md`).
-//! SPAKE2 PIN pairing.
+
 // The UI-agnostic plumbing lives in `pf-client-core`, shared with the session binary.
 // Root re-exports keep every `crate::trust`-style path resolving unchanged.
 #[cfg(target_os = "linux")]
 pub use pf_client_core::{discovery, gamepad, library, trust, video, wol};
 #[cfg(target_os = "linux")]
 mod app;
 #[cfg(target_os = "linux")]
 mod audio;
 #[cfg(target_os = "linux")]
 mod cli;
 #[cfg(target_os = "linux")]
-mod discovery;
+mod spawn;
 #[cfg(target_os = "linux")]
 mod gamepad;
 #[cfg(target_os = "linux")]
 mod keymap;
 #[cfg(target_os = "linux")]
 mod launch;
 #[cfg(target_os = "linux")]
 mod library;
 #[cfg(target_os = "linux")]
 mod session;
 #[cfg(target_os = "linux")]
 mod trust;
 #[cfg(target_os = "linux")]
 mod ui_gamepad_library;
 #[cfg(target_os = "linux")]
 mod ui_hosts;
 #[cfg(target_os = "linux")]
@@ -34,23 +22,15 @@ mod ui_library;
 #[cfg(target_os = "linux")]
 mod ui_settings;
 #[cfg(target_os = "linux")]
 mod ui_stream;
 #[cfg(target_os = "linux")]
 mod ui_trust;
 #[cfg(target_os = "linux")]
 mod video;
 #[cfg(target_os = "linux")]
 mod video_gl;
 mod wol;
 #[cfg(target_os = "linux")]
 fn main() -> gtk::glib::ExitCode {
    app::run()
 }
-/// GTK4/PipeWire/SDL3 are Linux turf; this stub keeps `cargo build --workspace` green on
+/// GTK4/SDL3 are Linux turf; this stub keeps `cargo build --workspace` green on macOS
-/// macOS (the Mac client lives in clients/apple).
+/// (the Mac client lives in clients/apple).
 #[cfg(not(target_os = "linux"))]
 fn main() {
    eprintln!("punktfunk-client is Linux-only — the macOS client lives in clients/apple");
@@ -0,0 +1,203 @@
 //! The shell↔session handoff: every stream runs in the spawned `punktfunk-session`
 //! Vulkan binary (the legacy in-process presenter is gone — phase 5 of
 //! punktfunk-planning `linux-client-rearchitecture.md`). This module owns the child's
 //! lifecycle plumbing — its stdout contract parsed into typed [`AppMsg`]s the relm4 app
 //! consumes: spinner until `{"ready":true}`, banner from the `{"error"|"ended": …}`
 //! line, exit code 3 + `trust_rejected` routed to the re-pair PIN ceremony.
 use crate::app::AppMsg;
 use crate::ui_hosts::ConnectRequest;
 use std::io::BufRead as _;
 use std::process::{Child, Command, Stdio};
 use std::sync::{Arc, Mutex};
 /// Spawn tunables beyond a plain connect.
 #[derive(Debug, Default)]
 pub struct SpawnOpts {
    /// Handshake budget override (`--connect-timeout`) — the request-access flow passes
    /// ~185 s because the host PARKS the connection until the operator approves.
    pub connect_timeout_secs: Option<u64>,
    /// Persist the host as *paired* once the child reports ready (request-access: the
    /// operator's approval IS the pairing). Plain TOFU persists unpaired.
    pub persist_paired: bool,
    /// A cancel handle to arm (request-access's waiting dialog): killing the child is
    /// the only abort a parked connect has.
    pub cancel: Option<CancelHandle>,
 }
 /// Kills the spawned session child (the request-access Cancel button). Safe to call
 /// any time; a child that already exited is a no-op.
 #[derive(Clone, Debug, Default)]
 pub struct CancelHandle(Arc<Mutex<Option<Child>>>);
 impl CancelHandle {
    pub fn kill(&self) {
        if let Some(child) = self.0.lock().unwrap().as_mut() {
            let _ = child.kill();
        }
    }
 }
 /// One parsed stdout line from the session child's contract.
 enum ChildEvent {
    Ready,
    Error { msg: String, trust_rejected: bool },
    Ended(String),
 }
 /// Parse one stdout line of the session contract; `None` for anything else (stats…).
 fn parse_line(line: &str) -> Option<ChildEvent> {
    let v: serde_json::Value = serde_json::from_str(line).ok()?;
    if v.get("ready").and_then(|r| r.as_bool()) == Some(true) {
        return Some(ChildEvent::Ready);
    }
    if let Some(msg) = v.get("error").and_then(|m| m.as_str()) {
        return Some(ChildEvent::Error {
            msg: msg.to_string(),
            trust_rejected: v.get("trust_rejected").and_then(|t| t.as_bool()) == Some(true),
        });
    }
    if let Some(msg) = v.get("ended").and_then(|m| m.as_str()) {
        return Some(ChildEvent::Ended(msg.to_string()));
    }
    None
 }
 /// The session binary: installed next to the shell, else `$PATH` (dev runs from
 /// `target/…` land on the sibling).
 pub fn session_binary() -> std::path::PathBuf {
    if let Ok(exe) = std::env::current_exe() {
        let sibling = exe.with_file_name("punktfunk-session");
        if sibling.exists() {
            return sibling;
        }
    }
    "punktfunk-session".into()
 }
 /// Spawn the session binary for a connect with `fp_hex` pinned and translate its
 /// lifecycle into [`AppMsg`]s. `tofu` = the fingerprint came from the host's advert
 /// rather than the store — the app persists it once the child reports ready (the child
 /// connects pinned to it, so ready proves the host really holds that identity).
 ///
 /// The caller has already taken `busy`; [`AppMsg::SessionExited`] releases it. `Err` =
 /// the spawn itself failed (binary missing?) — surfaced as a connect error.
 pub fn spawn_session(
    sender: relm4::Sender<AppMsg>,
    req: ConnectRequest,
    fp_hex: String,
    tofu: bool,
    fullscreen_on_stream: bool,
    opts: SpawnOpts,
 ) -> Result<(), String> {
    let mut cmd = Command::new(session_binary());
    cmd.arg("--connect")
        .arg(format!("{}:{}", req.addr, req.port))
        .arg("--fp")
        .arg(&fp_hex)
        .stdin(Stdio::null())
        .stdout(Stdio::piped())
        .stderr(Stdio::inherit()); // session logs interleave with the shell's
    if let Some((id, _)) = &req.launch {
        cmd.arg("--launch").arg(id);
    }
    if let Some(secs) = opts.connect_timeout_secs {
        cmd.arg("--connect-timeout").arg(secs.to_string());
    }
    if fullscreen_on_stream {
        cmd.arg("--fullscreen");
    }
    let mut child = cmd
        .spawn()
        .map_err(|e| format!("couldn't start punktfunk-session: {e}"))?;
    tracing::info!(host = %req.addr, port = req.port, "session binary spawned");
    let stdout = child.stdout.take().expect("piped stdout");
    // Park the child where the cancel handle (and the reader, for the final reap) can
    // reach it.
    let slot = opts.cancel.clone().unwrap_or_default();
    *slot.0.lock().unwrap() = Some(child);
    let persist_paired = opts.persist_paired;
    std::thread::Builder::new()
        .name("punktfunk-session-io".into())
        .spawn(move || {
            let mut error: Option<(String, bool)> = None;
            let mut ended: Option<String> = None;
            for line in std::io::BufReader::new(stdout).lines() {
                let Ok(line) = line else { break };
                match parse_line(&line) {
                    Some(ChildEvent::Ready) => {
                        let _ = sender.send(AppMsg::SessionReady {
                            req: req.clone(),
                            fp_hex: fp_hex.clone(),
                            tofu,
                            persist_paired,
                        });
                    }
                    Some(ChildEvent::Error {
                        msg,
                        trust_rejected,
                    }) => {
                        error = Some((msg, trust_rejected));
                    }
                    Some(ChildEvent::Ended(msg)) => ended = Some(msg),
                    None => {}
                }
            }
            // EOF — reap the child (killed-by-cancel lands here too; -1 = signal).
            let code = slot
                .0
                .lock()
                .unwrap()
                .take()
                .and_then(|mut c| c.wait().ok())
                .and_then(|s| s.code())
                .unwrap_or(-1);
            tracing::info!(code, "session binary exited");
            let _ = sender.send(AppMsg::SessionExited {
                req,
                code,
                error,
                ended,
                tofu,
            });
        })
        .map_err(|e| format!("session reader thread: {e}"))?;
    Ok(())
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn parses_the_stdout_contract() {
        assert!(matches!(
            parse_line("{\"ready\":true}"),
            Some(ChildEvent::Ready)
        ));
        match parse_line("{\"error\":\"no route\",\"trust_rejected\":false}") {
            Some(ChildEvent::Error {
                msg,
                trust_rejected,
            }) => {
                assert_eq!(msg, "no route");
                assert!(!trust_rejected);
            }
            _ => panic!("error line"),
        }
        match parse_line("{\"error\":\"pin\",\"trust_rejected\":true}") {
            Some(ChildEvent::Error { trust_rejected, .. }) => assert!(trust_rejected),
            _ => panic!("trust line"),
        }
        match parse_line("{\"ended\":\"Host ended the session\"}") {
            Some(ChildEvent::Ended(m)) => assert_eq!(m, "Host ended the session"),
            _ => panic!("ended line"),
        }
        // Stats and stray output never become events.
        assert!(parse_line("stats: 1280×800@60 · 60 fps").is_none());
        assert!(parse_line("").is_none());
        assert!(parse_line("{\"other\":1}").is_none());
    }
 }
@@ -5,12 +5,13 @@
 //! a title starts a session that asks the host to launch it (the library id rides the
 //! Hello via `ConnectRequest::launch`).
-use crate::app::App;
+use crate::app::{AppModel, AppMsg};
 use crate::library::{self, GameEntry};
 use crate::trust;
 use crate::ui_hosts::ConnectRequest;
 use adw::prelude::*;
 use gtk::{gdk, glib};
 use relm4::prelude::*;
 use std::cell::{Cell, RefCell};
 use std::collections::{HashMap, VecDeque};
 use std::rc::Rc;
@@ -19,7 +20,10 @@ use std::rc::Rc;
 /// card activation); dropped when the page is popped, which also winds down any in-flight
 /// art consumer (its weak upgrade fails).
 struct State {
-    app: Rc<App>,
+    sender: ComponentSender<AppModel>,
    identity: (String, String),
    /// The advertised mgmt port when the host was live at open time (else the default).
    mgmt_port: u16,
    /// The host this library belongs to — cards clone it and add `launch`.
    req: ConnectRequest,
    stack: gtk::Stack,
@@ -34,21 +38,29 @@ struct State {
    mock: Cell<bool>,
 }
-/// Open the library page for a saved host and start the fetch.
+/// Open the library page for a saved host and start the fetch. `mgmt_port` comes from
-pub fn open(app: Rc<App>, req: ConnectRequest) {
+/// the live mDNS `mgmt` TXT when the host is advertising (the hosts page resolves it).
-    let state = build(app.clone(), req);
+pub fn open(
    app: &AppModel,
    sender: &ComponentSender<AppModel>,
    req: ConnectRequest,
    mgmt_port: Option<u16>,
 ) {
    let state = build(&app.nav, app.identity.clone(), sender, req, mgmt_port);
    load(&state);
 }
 /// Screenshot-scene entry: render injected entries (plus pre-seeded textures, keyed by
 /// entry id) with no host and no network — the CI `library` scene.
 pub fn open_mock(
-    app: Rc<App>,
+    nav: &adw::NavigationView,
    identity: (String, String),
    sender: &ComponentSender<AppModel>,
    req: ConnectRequest,
    games: Vec<GameEntry>,
    art: Vec<(String, gdk::Texture)>,
 ) {
-    let state = build(app.clone(), req);
+    let state = build(nav, identity, sender, req, None);
    state.mock.set(true);
    state.art.borrow_mut().extend(art);
    if games.is_empty() {
@@ -60,7 +72,13 @@ pub fn open_mock(
 }
 /// Build the page (loading / error / empty / grid states in a stack) and push it.
-fn build(app: Rc<App>, req: ConnectRequest) -> Rc<State> {
+fn build(
    nav: &adw::NavigationView,
    identity: (String, String),
    sender: &ComponentSender<AppModel>,
    req: ConnectRequest,
    mgmt_port: Option<u16>,
 ) -> Rc<State> {
    let flow = gtk::FlowBox::builder()
        .selection_mode(gtk::SelectionMode::None)
        .activate_on_single_click(true)
@@ -142,7 +160,9 @@ fn build(app: Rc<App>, req: ConnectRequest) -> Rc<State> {
        .build();
    let state = Rc::new(State {
-        app: app.clone(),
+        sender: sender.clone(),
        identity,
        mgmt_port: mgmt_port.unwrap_or(library::DEFAULT_MGMT_PORT),
        req,
        stack,
        flow,
@@ -159,20 +179,10 @@ fn build(app: Rc<App>, req: ConnectRequest) -> Rc<State> {
        let state = state.clone();
        retry.connect_clicked(move |_| load(&state));
    }
-    app.nav.push(&page);
+    nav.push(&page);
    state
 }
 /// The mgmt port for this host: the live mDNS `mgmt` TXT when the host is advertising,
 /// else the well-known default (Apple's `effectiveMgmtPort`).
 fn mgmt_port(state: &State) -> u16 {
    state
        .app
        .hosts_ui()
        .and_then(|h| h.mgmt_port_for(&state.req))
        .unwrap_or(library::DEFAULT_MGMT_PORT)
 }
 /// Fetch the library off the main thread and route the result into the grid or the
 /// error/empty states.
 fn load(state: &Rc<State>) {
@@ -180,9 +190,9 @@ fn load(state: &Rc<State>) {
        return; // screenshot scene renders injected entries only
    }
    state.stack.set_visible_child_name("loading");
-    let port = mgmt_port(state);
+    let port = state.mgmt_port;
    let addr = state.req.addr.clone();
-    let identity = state.app.identity.clone();
+    let identity = state.identity.clone();
    let pin = state.req.fp_hex.as_deref().and_then(trust::parse_hex32);
    let (tx, rx) = async_channel::bounded(1);
    std::thread::Builder::new()
@@ -268,10 +278,10 @@ fn game_card(state: &Rc<State>, game: &GameEntry) -> gtk::FlowBoxChild {
    let child = gtk::FlowBoxChild::new();
    child.set_child(Some(&card));
-    let app = state.app.clone();
+    let sender = state.sender.clone();
    let mut req = state.req.clone();
    req.launch = Some((game.id.clone(), game.title.clone()));
-    child.connect_activate(move |_| crate::ui_trust::initiate_connect(app.clone(), req.clone()));
+    child.connect_activate(move |_| sender.input(AppMsg::Connect(req.clone())));
    child
 }
@@ -279,8 +289,7 @@ fn game_card(state: &Rc<State>, game: &GameEntry) -> gtk::FlowBoxChild {
 /// entry's candidates in the Apple fallback order (portrait → header → hero) and
 /// texturing the first that loads on the main loop.
 fn load_art(state: &Rc<State>, games: &[GameEntry]) {
-    let port = mgmt_port(state);
+    let base = library::base_url(&state.req.addr, state.mgmt_port);
    let base = library::base_url(&state.req.addr, port);
    let jobs: VecDeque<(String, Vec<String>)> = {
        let cache = state.art.borrow();
        games
@@ -293,7 +302,7 @@ fn load_art(state: &Rc<State>, games: &[GameEntry]) {
    if jobs.is_empty() {
        return;
    }
-    let identity = state.app.identity.clone();
+    let identity = state.identity.clone();
    let pin = state.req.fp_hex.as_deref().and_then(trust::parse_hex32);
    let rx = library::spawn_art_fetch(base, identity, pin, jobs);
    let weak = Rc::downgrade(state);
@@ -1,68 +1,100 @@
-//! The trust gate and dialogs in front of every connect: TOFU, the SPAKE2 PIN ceremony,
+//! The trust dialogs in front of a connect: TOFU, the SPAKE2 PIN ceremony, and
-//! and delegated (request-access) approval.
+//! delegated (request-access) approval. The trust GATE itself (rules 1–3) lives in
 //! `AppModel::update` (`AppMsg::Connect`); these are the interaction surfaces it opens,
 //! each resolving into typed [`AppMsg`]s.
-use crate::app::App;
+use crate::app::{AppModel, AppMsg};
-use crate::launch::{start_session, start_session_with, StartOpts};
+use crate::spawn::{CancelHandle, SpawnOpts};
 use crate::trust;
 use crate::ui_hosts::ConnectRequest;
 use adw::prelude::*;
 use gtk::glib;
-use std::rc::Rc;
+use relm4::prelude::*;
-/// The trust gate in front of every connect. The host is the policy authority (it
+/// Wake-and-wait: an **offline** saved host with a known MAC is sent a magic packet,
-/// advertises `pair=optional` only when it accepts unpaired clients); the client renders
+/// then we poll mDNS until it comes back online — re-sending every few seconds up to a
-/// its trust UI from that:
+/// timeout — and route back into the trust gate, **re-keying the saved record if the
-///   1. PINNED RECONNECT — a host already pinned to this exact fingerprint connects silently.
+/// host woke on a new DHCP IP** (matched by fingerprint). A "Waking…" dialog lets the
-///   2. FINGERPRINT CHANGED — a host we know at this address but whose fingerprint no longer
+/// user cancel. Mirrors the Apple/Android `HostWaker` (90 s budget, resend every 6 s).
-///      matches is the impostor signal: force re-pairing via the PIN ceremony, regardless of
+pub fn wake_and_connect(
-///      the advertised policy.
+    window: &adw::ApplicationWindow,
-///   3. NEW host — TOFU is offered only when the host advertised `pair=optional` (rule 3a);
+    sender: &ComponentSender<AppModel>,
-///      otherwise (pair=required, unknown/empty policy, or a manual entry) PIN pairing is
+    req: ConnectRequest,
-///      mandatory (rule 3b).
+) {
-///
+    let cancel = std::rc::Rc::new(std::cell::Cell::new(false));
-/// A new host is never auto-connected without a stored pin or an explicit trust decision.
+    let waiting = adw::AlertDialog::new(
-pub fn initiate_connect(app: Rc<App>, req: ConnectRequest) {
+        Some("Waking Host"),
-    if app.busy.get() {
+        Some(&format!(
            "Sent a wake signal to “{}”. Waiting for it to come online…",
            req.name
        )),
    );
    waiting.add_responses(&[("cancel", "Cancel")]);
    waiting.set_close_response("cancel");
    {
        let cancel = cancel.clone();
        waiting.connect_response(Some("cancel"), move |_, _| cancel.set(true));
    }
    waiting.present(Some(window));
    let sender = sender.clone();
    glib::spawn_future_local(async move {
        use std::time::{Duration, Instant};
        let events = crate::discovery::browse();
        let started = Instant::now();
        let budget = Duration::from_secs(90);
        let resend = Duration::from_secs(6);
        crate::wol::wake(&req.mac, req.addr.parse().ok());
        let mut last_wake = Instant::now();
        loop {
            if cancel.get() {
                waiting.close();
                return;
            }
-    let known = trust::KnownHosts::load();
+            if last_wake.elapsed() >= resend {
-    match &req.fp_hex {
+                crate::wol::wake(&req.mac, req.addr.parse().ok());
-        Some(fp_hex) => {
+                last_wake = Instant::now();
-            if known.find_by_fp(fp_hex).is_some() {
+            }
-                // Rule 1: pinned fingerprint matches — silent connect.
+            // Drain resolved adverts; a match (fingerprint, else addr:port) = it's up.
-                start_session(app, req.clone(), trust::parse_hex32(fp_hex));
+            while let Ok(ev) = events.try_recv() {
-            } else if known.find_by_addr(&req.addr, req.port).is_some() {
+                let crate::discovery::DiscoveryEvent::Resolved(h) = ev else {
-                // Rule 2: we trust a host at this address but the fingerprint changed —
+                    continue;
-                // the impostor signal. Re-pair via the PIN ceremony (no TOFU shortcut).
+                };
-                app.toast("Host fingerprint changed — re-pair with a PIN to continue");
+                let matched = match &req.fp_hex {
-                pin_dialog(app, req);
+                    Some(fp) => !h.fp_hex.is_empty() && &h.fp_hex == fp,
-            } else if req.pair_optional {
+                    None => h.addr == req.addr && h.port == req.port,
-                // Rule 3a: the host opted into reduced-security TOFU; offer it alongside PIN.
+                };
-                tofu_dialog(app, req);
+                if matched {
-            } else {
+                    waiting.close();
-                // Rule 3b: pair=required or unknown policy — offer no-PIN delegated approval
+                    let mut req = req.clone();
-                // (request access → approve in the console) or the PIN ceremony.
+                    // Re-key on a new DHCP lease so this + future connects dial the
-                approval_dialog(app, req);
+                    // live address.
                    if h.addr != req.addr || h.port != req.port {
                        if let Some(fp) = &req.fp_hex {
                            trust::rekey_addr(fp, &h.addr, h.port);
                        }
                        req.addr = h.addr;
                        req.port = h.port;
                    }
                    sender.input(AppMsg::Connect(req));
                    return;
                }
            }
-        None => {
+            if started.elapsed() >= budget {
-            // Manual entry (no advertised fingerprint). A known address connects silently
+                waiting.close();
-            // on its stored pin (rule 1); an unknown one must pair — request access (approve in
+                sender.input(AppMsg::Toast(format!(
-            // the console) or use a PIN; never silent TOFU.
+                    "Couldn't reach “{}” — is it powered and on the network?",
-            match known
+                    req.name
-                .find_by_addr(&req.addr, req.port)
+                )));
-                .and_then(|k| trust::parse_hex32(&k.fp_hex))
+                return;
            {
                Some(pin) => start_session(app, req, Some(pin)),
                None => approval_dialog(app, req), // rule 3b
            }
            }
            glib::timeout_future(Duration::from_millis(500)).await;
        }
    });
 }
-/// The certificate fingerprint as grouped monospaced hex — 4-char groups over 2 lines
+/// The certificate fingerprint as grouped monospaced hex — 4-char groups over 2 lines,
-/// (the Apple TrustCardView format), far easier to compare against the host's log than
+/// far easier to compare against the host's log than one 64-char run.
 /// one 64-char run.
 fn grouped_fingerprint(fp: &str) -> String {
    let groups: Vec<&str> = fp
        .as_bytes()
@@ -76,9 +108,15 @@ fn grouped_fingerprint(fp: &str) -> String {
        .join("\n")
 }
-/// First contact with a discovered host: show the advertised fingerprint and let the user
+/// First contact with a discovered host that opted into TOFU: show the advertised
-/// trust it (TOFU), run the PIN ceremony instead, or walk away.
+/// fingerprint and let the user trust it, run the PIN ceremony instead, or walk away.
-pub fn tofu_dialog(app: Rc<App>, req: ConnectRequest) {
+/// Trusting starts a session pinned to the advertised fp; it persists once the child
 /// proves the host holds that identity (`AppMsg::SessionReady` with `tofu`).
 pub fn tofu_dialog(
    window: &adw::ApplicationWindow,
    sender: &ComponentSender<AppModel>,
    req: ConnectRequest,
 ) {
    let fp = req.fp_hex.clone().unwrap_or_default();
    let dialog = adw::AlertDialog::new(
        Some("New Host"),
@@ -102,29 +140,35 @@ pub fn tofu_dialog(app: Rc<App>, req: ConnectRequest) {
    dialog.set_response_appearance("trust", adw::ResponseAppearance::Suggested);
    dialog.set_default_response(Some("trust"));
    dialog.set_close_response("cancel");
-    let parent = app.window.clone();
+    let sender = sender.clone();
    dialog.connect_response(None, move |_, response| match response {
-        "trust" => {
+        "trust" => sender.input(AppMsg::StartSession {
-            trust::persist_host(&req.name, &req.addr, req.port, &fp, false);
+            req: req.clone(),
-            start_session(app.clone(), req.clone(), trust::parse_hex32(&fp));
+            fp_hex: fp.clone(),
-        }
+            tofu: true,
-        "pair" => pin_dialog(app.clone(), req.clone()),
+            opts: SpawnOpts::default(),
        }),
        "pair" => sender.input(AppMsg::Pair(req.clone())),
        _ => {}
    });
-    dialog.present(Some(&parent));
+    dialog.present(Some(window));
 }
 /// The SPAKE2 ceremony: the host is armed and displays a 4-digit PIN; proving knowledge
 /// of it pins the host's certificate (and registers ours) with no offline-guessable
-/// transcript.
+/// transcript. Success persists the host as paired and connects.
-pub fn pin_dialog(app: Rc<App>, req: ConnectRequest) {
+pub fn pin_dialog(
    window: &adw::ApplicationWindow,
    sender: &ComponentSender<AppModel>,
    identity: (String, String),
    req: ConnectRequest,
 ) {
    let entry = gtk::Entry::builder()
        .input_purpose(gtk::InputPurpose::Digits)
        .placeholder_text("4-digit PIN shown by the host")
        .activates_default(true)
        .build();
-    // The label the HOST stores this client under (its paired-devices list) — prefilled
+    // The label the HOST stores this client under — prefilled with the hostname.
    // with the machine hostname, editable (the Apple pair sheet does the same).
    let name_entry = gtk::Entry::builder()
        .text(glib::host_name().as_str())
        .activates_default(true)
@@ -154,12 +198,12 @@ pub fn pin_dialog(app: Rc<App>, req: ConnectRequest) {
    dialog.set_response_appearance("pair", adw::ResponseAppearance::Suggested);
    dialog.set_default_response(Some("pair"));
    dialog.set_close_response("cancel");
-    let parent = app.window.clone();
+    let sender = sender.clone();
    dialog.connect_response(Some("pair"), move |_, _| {
        let pin = entry.text().to_string();
        let app = app.clone();
        let req = req.clone();
-        let identity = app.identity.clone();
+        let identity = identity.clone();
        let sender = sender.clone();
        let (tx, rx) = async_channel::bounded::<Result<[u8; 32], String>>(1);
        let device = name_entry.text().trim().to_string();
        let name = if device.is_empty() {
@@ -176,22 +220,33 @@ pub fn pin_dialog(app: Rc<App>, req: ConnectRequest) {
        glib::spawn_future_local(async move {
            match rx.recv().await {
                Ok(Ok(fp)) => {
-                    trust::persist_host(&req.name, &req.addr, req.port, &trust::hex(&fp), true);
+                    let fp_hex = trust::hex(&fp);
-                    app.toast("Paired — connecting…");
+                    trust::persist_host(&req.name, &req.addr, req.port, &fp_hex, true);
-                    start_session(app.clone(), req, Some(fp));
+                    sender.input(AppMsg::Toast("Paired — connecting…".into()));
                    sender.input(AppMsg::StartSession {
                        req,
                        fp_hex,
                        tofu: false,
                        opts: SpawnOpts::default(),
                    });
                }
-                Ok(Err(msg)) => app.toast(&msg),
+                Ok(Err(msg)) => sender.input(AppMsg::Toast(msg)),
                Err(_) => {}
            }
        });
    });
-    dialog.present(Some(&parent));
+    dialog.present(Some(window));
 }
-/// A fresh host that requires pairing: offer the two ways in. "Request access" is the no-PIN
+/// A fresh host that requires pairing: "Request access" (connect and wait for the
-/// path — connect and wait for the operator to click Approve in the host's console/web UI
+/// operator to click Approve in the host's console — delegated approval) or the PIN
-/// (delegated approval); "Use a PIN instead…" runs the SPAKE2 ceremony.
+/// ceremony.
-fn approval_dialog(app: Rc<App>, req: ConnectRequest) {
+pub fn approval_dialog(
    window: &adw::ApplicationWindow,
    sender: &ComponentSender<AppModel>,
    waiting_slot: std::rc::Rc<std::cell::RefCell<Option<adw::AlertDialog>>>,
    req: ConnectRequest,
 ) {
    let dialog = adw::AlertDialog::new(
        Some("Pairing Required"),
        Some(&format!(
@@ -208,24 +263,42 @@ fn approval_dialog(app: Rc<App>, req: ConnectRequest) {
    dialog.set_response_appearance("request", adw::ResponseAppearance::Suggested);
    dialog.set_default_response(Some("request"));
    dialog.set_close_response("cancel");
-    let parent = app.window.clone();
+    let parent = window.clone();
    let window = window.clone();
    let sender = sender.clone();
    dialog.connect_response(None, move |_, response| match response {
-        "request" => request_access(app.clone(), req.clone()),
+        "request" => request_access(&window, &sender, waiting_slot.clone(), req.clone()),
-        "pin" => pin_dialog(app.clone(), req.clone()),
+        "pin" => sender.input(AppMsg::Pair(req.clone())),
        _ => {}
    });
    dialog.present(Some(&parent));
 }
-/// The no-PIN "request access" flow: open an identified connect that the host PARKS until the
+/// The no-PIN "request access" flow: the session child opens an identified connect the
-/// operator approves it in the console, showing a cancelable "waiting" dialog meanwhile. On
+/// host PARKS until the operator approves it in the console; a cancelable "waiting"
-/// approval the same connection is admitted (no reconnect) and the host is saved as paired.
+/// dialog covers the wait. On approval the same connection is admitted and the host is
-fn request_access(app: Rc<App>, req: ConnectRequest) {
+/// saved as paired. Cancel kills the child (the only abort a parked connect has).
-    // Pin the advertised certificate for a discovered host (defence against a host impostor while
+///
-    // we wait); a manually-typed host has no advertised fingerprint, so trust-on-first-use.
+/// The pinned fingerprint is the advertised one for a discovered host (defence against
-    let pin = req.fp_hex.as_deref().and_then(trust::parse_hex32);
+/// an impostor while we wait). A manually-typed host has no advertised fingerprint —
-    let cancel = Rc::new(std::cell::Cell::new(false));
+/// the session binary refuses pinless connects, so this path requires the advert; a
-
+/// manual entry's Request Access rides the same flow only when a fingerprint exists.
 fn request_access(
    window: &adw::ApplicationWindow,
    sender: &ComponentSender<AppModel>,
    waiting_slot: std::rc::Rc<std::cell::RefCell<Option<adw::AlertDialog>>>,
    req: ConnectRequest,
 ) {
    let Some(fp_hex) = req.fp_hex.clone() else {
        // No fingerprint to pin (manual entry): the strict child can't do a
        // trust-on-approval connect — route to the PIN ceremony instead.
        sender.input(AppMsg::Toast(
            "No advertised identity for this host — pair with a PIN instead.".into(),
        ));
        sender.input(AppMsg::Pair(req));
        return;
    };
    let cancel = CancelHandle::default();
    let waiting = adw::AlertDialog::new(
        Some("Waiting for Approval"),
        Some(&format!(
@@ -238,29 +311,26 @@ fn request_access(app: Rc<App>, req: ConnectRequest) {
    waiting.add_responses(&[("cancel", "Cancel")]);
    waiting.set_close_response("cancel");
    {
-        let app = app.clone();
+        let sender = sender.clone();
        let cancel = cancel.clone();
        waiting.connect_response(Some("cancel"), move |_, _| {
-            // Return the UI immediately; the in-flight connect is left to time out and is torn
+            cancel.kill();
-            // down silently by the event loop (see StartOpts::cancel).
+            sender.input(AppMsg::CancelPending);
            cancel.set(true);
            app.busy.set(false);
            app.toast("Cancelled — the request may still be pending on the host.");
        });
    }
-    waiting.present(Some(&app.window));
+    waiting.present(Some(window));
    *waiting_slot.borrow_mut() = Some(waiting);
-    start_session_with(
+    sender.input(AppMsg::StartSession {
        app,
        req,
-        pin,
+        fp_hex,
-        StartOpts {
+        tofu: false,
-            // Must exceed the host's approval window (PENDING_APPROVAL_WAIT) so a slow operator
+        opts: SpawnOpts {
-            // approval still lands on this connection rather than timing the client out first.
+            // Must exceed the host's approval window (PENDING_APPROVAL_WAIT) so a slow
-            connect_timeout: std::time::Duration::from_secs(185),
+            // operator approval still lands on this connection.
            connect_timeout_secs: Some(185),
            persist_paired: true,
            waiting: Some(waiting),
            cancel: Some(cancel),
        },
-    );
+    });
 }
@@ -1,664 +0,0 @@
 //! VAAPI dmabuf → RGBA GL texture converter — the Steam Deck's hardware-decode presenter.
 //!
 //! The direct path hands the decoder's NV12 dmabuf (fds + AMD tiled modifier) to
 //! `GdkDmabufTexture` and lets GTK import + color-convert it. On the Deck that renders
 //! corrupt/gray/washed-out: since Mesa 25.1 radeonsi exports VCN decode surfaces TILED, and
 //! GTK's tiled-NV12 import mishandles the layout (the Flatpak runtime's Mesa drives both
 //! sides). Moonlight-qt and mpv are clean on the same box because they never let a toolkit
 //! near the YUV: they import the dmabuf into their own EGL context and convert with their
 //! own shader. This module is that architecture for the GTK client:
 //!
 //!   VAAPI frame → per-plane `EGLImage`s (R8 luma + GR88 chroma, modifier passed through)
 //!   → our YUV→RGB shader (matrix + range from the stream's real CICP signaling)
 //!   → an RGBA texture in a `GdkGLContext`-shared context → `GdkGLTexture` (fence-synced).
 //!
 //! GTK then composites a plain RGBA texture — no YUV format negotiation, no modifier
 //! handling, no compositor CSC. Same-Mesa export/import is the exact proven-working path.
 //! Everything runs on the GTK main thread (the converter is driven by the frame consumer);
 //! one 800p–4K NV12→RGB pass is sub-millisecond GPU work.
 //!
 //! Failure at any step (GLX-backed GDK context, missing EGL extensions, import rejection)
 //! is surfaced as an error — the caller falls back to software decode, never to the broken
 //! direct path.
 use crate::video::{ColorDesc, DmabufFrame};
 use anyhow::{anyhow, bail, Context as _, Result};
 use gtk::{gdk, prelude::*};
 use khronos_egl as egl;
 use std::ffi::c_void;
 use std::sync::{Arc, Mutex};
 // --- EGL_EXT_image_dma_buf_import(+_modifiers) constants (khronos-egl exposes none) ------
 const EGL_LINUX_DMA_BUF_EXT: egl::Enum = 0x3270;
 // eglCreateImageKHR takes 32-bit EGLint attribs (the core-1.5 eglCreateImage variant is the
 // one with pointer-sized EGLAttrib) — using the wrong width feeds the driver garbage pairs.
 const EGL_LINUX_DRM_FOURCC_EXT: i32 = 0x3271;
 const EGL_DMA_BUF_PLANE0_FD_EXT: i32 = 0x3272;
 const EGL_DMA_BUF_PLANE0_OFFSET_EXT: i32 = 0x3273;
 const EGL_DMA_BUF_PLANE0_PITCH_EXT: i32 = 0x3274;
 const EGL_DMA_BUF_PLANE0_MODIFIER_LO_EXT: i32 = 0x3443;
 const EGL_DMA_BUF_PLANE0_MODIFIER_HI_EXT: i32 = 0x3444;
 const EGL_WIDTH: i32 = 0x3057;
 const EGL_HEIGHT: i32 = 0x3056;
 const EGL_NONE: i32 = 0x3038;
 const DRM_FORMAT_MOD_INVALID: u64 = 0x00ff_ffff_ffff_ffff;
 /// `fourcc('N','V','1','2')` — the only decoder output today (8-bit 4:2:0). P010 joins when
 /// the Linux host grows 10-bit.
 const DRM_FORMAT_NV12: u32 = 0x3231_564e;
 const DRM_FORMAT_R8: u32 = 0x2020_3852;
 const DRM_FORMAT_GR88: u32 = 0x3838_5247;
 // --- The slice of GL we use (loaded via eglGetProcAddress — Mesa/NVIDIA both implement
 // --- EGL_KHR_get_all_proc_addresses, so core functions resolve too) ----------------------
 const GL_TEXTURE_2D: u32 = 0x0DE1;
 const GL_TEXTURE0: u32 = 0x84C0;
 const GL_TEXTURE_MIN_FILTER: u32 = 0x2801;
 const GL_TEXTURE_MAG_FILTER: u32 = 0x2800;
 const GL_TEXTURE_WRAP_S: u32 = 0x2802;
 const GL_TEXTURE_WRAP_T: u32 = 0x2803;
 const GL_LINEAR: i32 = 0x2601;
 const GL_CLAMP_TO_EDGE: i32 = 0x812F;
 const GL_FRAMEBUFFER: u32 = 0x8D40;
 const GL_COLOR_ATTACHMENT0: u32 = 0x8CE0;
 const GL_FRAMEBUFFER_COMPLETE: u32 = 0x8CD5;
 const GL_RGBA8: u32 = 0x8058;
 const GL_RGBA: u32 = 0x1908;
 const GL_UNSIGNED_BYTE: u32 = 0x1401;
 const GL_TRIANGLES: u32 = 0x0004;
 const GL_VERTEX_SHADER: u32 = 0x8B31;
 const GL_FRAGMENT_SHADER: u32 = 0x8B30;
 const GL_COMPILE_STATUS: u32 = 0x8B81;
 const GL_LINK_STATUS: u32 = 0x8B82;
 const GL_SYNC_GPU_COMMANDS_COMPLETE: u32 = 0x9117;
 macro_rules! gl_fns {
    ($($name:ident : fn($($arg:ty),*) $(-> $ret:ty)?;)*) => {
        #[allow(non_snake_case)]
        struct GlFns { $($name: unsafe extern "C" fn($($arg),*) $(-> $ret)?,)* }
        impl GlFns {
            #[allow(non_snake_case)]
            fn load(egl: &Egl) -> Result<GlFns> {
                $(
                    // eglGetProcAddress returns a plain fn pointer; the signature is fixed
                    // by the GL spec for each name.
                    let $name = egl
                        .get_proc_address(concat!("gl", stringify!($name)))
                        .ok_or_else(|| anyhow!(concat!("gl", stringify!($name), " unresolvable")))?;
                )*
                // SAFETY: each pointer came from eglGetProcAddress for exactly that GL entry
                // point; the transmute only fixes the signature the spec defines for it.
                unsafe {
                    Ok(GlFns { $($name: std::mem::transmute::<extern "system" fn(), unsafe extern "C" fn($($arg),*) $(-> $ret)?>($name),)* })
                }
            }
        }
    };
 }
 gl_fns! {
    GenTextures: fn(i32, *mut u32);
    DeleteTextures: fn(i32, *const u32);
    BindTexture: fn(u32, u32);
    TexParameteri: fn(u32, u32, i32);
    TexImage2D: fn(u32, i32, i32, i32, i32, i32, u32, u32, *const c_void);
    ActiveTexture: fn(u32);
    EGLImageTargetTexture2DOES: fn(u32, *const c_void);
    GenFramebuffers: fn(i32, *mut u32);
    DeleteFramebuffers: fn(i32, *const u32);
    BindFramebuffer: fn(u32, u32);
    FramebufferTexture2D: fn(u32, u32, u32, u32, i32);
    CheckFramebufferStatus: fn(u32) -> u32;
    Viewport: fn(i32, i32, i32, i32);
    CreateShader: fn(u32) -> u32;
    ShaderSource: fn(u32, i32, *const *const u8, *const i32);
    CompileShader: fn(u32);
    GetShaderiv: fn(u32, u32, *mut i32);
    GetShaderInfoLog: fn(u32, i32, *mut i32, *mut u8);
    DeleteShader: fn(u32);
    CreateProgram: fn() -> u32;
    AttachShader: fn(u32, u32);
    LinkProgram: fn(u32);
    GetProgramiv: fn(u32, u32, *mut i32);
    UseProgram: fn(u32);
    GetUniformLocation: fn(u32, *const u8) -> i32;
    Uniform1i: fn(i32, i32);
    Uniform3fv: fn(i32, i32, *const f32);
    UniformMatrix3fv: fn(i32, i32, u8, *const f32);
    GenVertexArrays: fn(i32, *mut u32);
    DeleteVertexArrays: fn(i32, *const u32);
    DeleteProgram: fn(u32);
    BindVertexArray: fn(u32);
    DrawArrays: fn(u32, i32, i32);
    FenceSync: fn(u32, u32) -> *const c_void;
    DeleteSync: fn(*const c_void);
    Flush: fn();
    GetError: fn() -> u32;
 }
 type Egl = egl::DynamicInstance<egl::EGL1_4>;
 type EglCreateImageKhr = unsafe extern "C" fn(
    *mut c_void, // EGLDisplay
    *mut c_void, // EGLContext (EGL_NO_CONTEXT for dmabuf)
    egl::Enum,
    *mut c_void, // EGLClientBuffer (null for dmabuf)
    *const i32,  // EGLint attrib list (KHR variant — NOT pointer-sized EGLAttrib)
 ) -> *const c_void;
 type EglDestroyImageKhr = unsafe extern "C" fn(*mut c_void, *const c_void) -> egl::Boolean;
 /// The YUV→RGB conversion for a stream's CICP signaling: `rgb = mat * (yuv + off)`, with the
 /// limited/full-range expansion folded in. `mat` is column-major (GL convention). Pure —
 /// unit-tested against the reference white/black points.
 pub fn yuv_to_rgb(desc: ColorDesc) -> ([f32; 9], [f32; 3]) {
    // BT.601 (5/6), BT.2020 (9/10); everything else — incl. unspecified — is the host's
    // BT.709 SDR default (mirrors the software path's swscale coefficient choice).
    let (kr, kb) = match desc.matrix {
        5 | 6 => (0.299, 0.114),
        9 | 10 => (0.2627, 0.0593),
        _ => (0.2126, 0.0722),
    };
    let kg = 1.0 - kr - kb;
    let (sy, oy, sc) = if desc.full_range {
        (1.0f32, 0.0f32, 1.0f32)
    } else {
        (255.0 / 219.0, -16.0 / 255.0, 255.0 / 224.0)
    };
    let (kr, kb, kg) = (kr as f32, kb as f32, kg as f32);
    // Column-major: columns are the Y, U, V contributions to (R, G, B).
    let mat = [
        sy,
        sy,
        sy, // Y column
        0.0,
        -2.0 * (1.0 - kb) * kb / kg * sc,
        2.0 * (1.0 - kb) * sc, // U column
        2.0 * (1.0 - kr) * sc,
        -2.0 * (1.0 - kr) * kr / kg * sc,
        0.0, // V column
    ];
    (mat, [oy, -0.5, -0.5])
 }
 /// An output texture GTK has released, waiting to be recycled (or its fence deleted). GL
 /// objects can only be touched with our context current, so releases park here and
 /// [`GlConverter::convert`] drains them.
 struct Retired {
    tex: u32,
    sync: usize, // GLsync as usize — the release closure must be Send
    size: (u32, u32),
 }
 pub struct GlConverter {
    ctx: gdk::GLContext,
    egl: Egl,
    egl_display: *mut c_void,
    create_image: EglCreateImageKhr,
    destroy_image: EglDestroyImageKhr,
    gl: GlFns,
    program: u32,
    vao: u32,
    fbo: u32,
    u_mat: i32,
    u_off: i32,
    /// Uniforms match this signaling; a change (mid-stream SDR↔HDR) re-uploads them.
    uniforms_for: Option<ColorDesc>,
    /// Free output textures + fences returned by GTK's release funcs (shared with the
    /// `Send` release closures; drained/recycled at each convert).
    retired: Arc<Mutex<Vec<Retired>>>,
 }
 impl GlConverter {
    /// Build against the widget's display. Must run on the GTK main thread; fails cleanly
    /// on a GLX-backed GDK context or missing EGL dmabuf-import extensions (the caller
    /// falls back to software decode).
    pub fn new(widget: &impl IsA<gtk::Widget>) -> Result<GlConverter> {
        let display = widget.display();
        let ctx = display.create_gl_context().context("create GdkGLContext")?;
        ctx.realize().context("realize GdkGLContext")?;
        ctx.make_current();
        // SAFETY (whole block): the GdkGLContext is current on this thread, so EGL/GL
        // queries and object creation target it; pointers are only used while it lives.
        unsafe {
            let egl = Egl::load_required().context("dlopen libEGL")?;
            let egl_display = egl
                .get_current_display()
                .ok_or_else(|| anyhow!("GDK context is not EGL-backed (GLX?)"))?;
            let exts = egl
                .query_string(Some(egl_display), egl::EXTENSIONS)
                .context("EGL_EXTENSIONS")?
                .to_string_lossy()
                .into_owned();
            for need in ["EGL_EXT_image_dma_buf_import", "EGL_KHR_image_base"] {
                if !exts.contains(need) {
                    bail!("EGL lacks {need}");
                }
            }
            // Tiled surfaces carry an explicit modifier — without the _modifiers extension
            // the import would silently assume implied/linear and sample garbage.
            if !exts.contains("EGL_EXT_image_dma_buf_import_modifiers") {
                bail!("EGL lacks EGL_EXT_image_dma_buf_import_modifiers");
            }
            let create_image: EglCreateImageKhr =
                std::mem::transmute::<extern "system" fn(), EglCreateImageKhr>(
                    egl.get_proc_address("eglCreateImageKHR")
                        .ok_or_else(|| anyhow!("no eglCreateImageKHR"))?,
                );
            let destroy_image: EglDestroyImageKhr =
                std::mem::transmute::<extern "system" fn(), EglDestroyImageKhr>(
                    egl.get_proc_address("eglDestroyImageKHR")
                        .ok_or_else(|| anyhow!("no eglDestroyImageKHR"))?,
                );
            let gl = GlFns::load(&egl)?;
            let es = ctx.api().contains(gdk::GLAPI::GLES);
            let program = build_program(&gl, es)?;
            (gl.UseProgram)(program);
            let u_mat = (gl.GetUniformLocation)(program, c"u_mat".as_ptr() as *const u8);
            let u_off = (gl.GetUniformLocation)(program, c"u_off".as_ptr() as *const u8);
            let u_y = (gl.GetUniformLocation)(program, c"u_y".as_ptr() as *const u8);
            let u_c = (gl.GetUniformLocation)(program, c"u_c".as_ptr() as *const u8);
            (gl.Uniform1i)(u_y, 0);
            (gl.Uniform1i)(u_c, 1);
            let mut vao = 0u32;
            (gl.GenVertexArrays)(1, &mut vao);
            let mut fbo = 0u32;
            (gl.GenFramebuffers)(1, &mut fbo);
            tracing::info!(
                gles = es,
                "GL presenter ready — VAAPI dmabufs convert in-process (own EGL import + shader)"
            );
            Ok(GlConverter {
                ctx,
                egl,
                egl_display: egl_display.as_ptr(),
                create_image,
                destroy_image,
                gl,
                program,
                vao,
                fbo,
                u_mat,
                u_off,
                uniforms_for: None,
                retired: Arc::new(Mutex::new(Vec::new())),
            })
        }
    }
    /// Convert one decoded frame into an RGBA `GdkTexture`. The source surface (guard) is
    /// held until GTK releases the output texture — the GPU read is long finished by then.
    /// `color_state` tags the output (full-range RGB, transfer left baked — same semantics
    /// as the software path's tagged `GdkMemoryTexture`); `None` = untagged sRGB.
    pub fn convert(
        &mut self,
        frame: DmabufFrame,
        color_state: Option<&gdk::ColorState>,
    ) -> Result<gdk::Texture> {
        if frame.fourcc != DRM_FORMAT_NV12 {
            bail!("GL presenter handles NV12 only (got {:#x})", frame.fourcc);
        }
        if frame.planes.len() < 2 {
            bail!("NV12 needs 2 planes (got {})", frame.planes.len());
        }
        self.ctx.make_current();
        let gl = &self.gl;
        // SAFETY (whole body): our context is current; every GL/EGL object created here is
        // either destroyed before return or owned by the pool/release machinery.
        unsafe {
            // Recycle what GTK released since last frame (GL objects need the context, so
            // the release closures only park entries — this is where they die/revive).
            let size = (frame.width, frame.height);
            let mut out_tex = 0u32;
            {
                let mut retired = self.retired.lock().unwrap();
                retired.retain_mut(|r| {
                    if r.sync != 0 {
                        (gl.DeleteSync)(r.sync as *const c_void);
                        r.sync = 0;
                    }
                    if out_tex == 0 && r.size == size {
                        out_tex = r.tex;
                        false
                    } else if r.size != size {
                        (gl.DeleteTextures)(1, &r.tex); // stale size (mode change)
                        false
                    } else {
                        true // spare same-size texture for a later frame
                    }
                });
            }
            if out_tex == 0 {
                (gl.GenTextures)(1, &mut out_tex);
                (gl.BindTexture)(GL_TEXTURE_2D, out_tex);
                (gl.TexParameteri)(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
                (gl.TexParameteri)(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
                (gl.TexImage2D)(
                    GL_TEXTURE_2D,
                    0,
                    GL_RGBA8 as i32,
                    frame.width as i32,
                    frame.height as i32,
                    0,
                    GL_RGBA,
                    GL_UNSIGNED_BYTE,
                    std::ptr::null(),
                );
            }
            // Import both planes with the surface's modifier — exactly the layer-wise
            // import Moonlight/mpv drive on this hardware.
            let y = &frame.planes[0];
            let c = &frame.planes[1];
            let img_y =
                self.plane_image(frame.width, frame.height, DRM_FORMAT_R8, y, frame.modifier)?;
            let img_c = match self.plane_image(
                frame.width.div_ceil(2),
                frame.height.div_ceil(2),
                DRM_FORMAT_GR88,
                c,
                frame.modifier,
            ) {
                Ok(img) => img,
                Err(e) => {
                    (self.destroy_image)(self.egl_display, img_y);
                    return Err(e);
                }
            };
            let mut planes = [0u32; 2];
            (gl.GenTextures)(2, planes.as_mut_ptr());
            for (tex, img) in planes.iter().zip([img_y, img_c]) {
                (gl.BindTexture)(GL_TEXTURE_2D, *tex);
                (gl.TexParameteri)(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
                (gl.TexParameteri)(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
                (gl.TexParameteri)(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
                (gl.TexParameteri)(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
                (gl.EGLImageTargetTexture2DOES)(GL_TEXTURE_2D, img);
            }
            (gl.UseProgram)(self.program);
            if self.uniforms_for != Some(frame.color) {
                let (mat, off) = yuv_to_rgb(frame.color);
                (gl.UniformMatrix3fv)(self.u_mat, 1, 0, mat.as_ptr());
                (gl.Uniform3fv)(self.u_off, 1, off.as_ptr());
                self.uniforms_for = Some(frame.color);
            }
            (gl.BindFramebuffer)(GL_FRAMEBUFFER, self.fbo);
            (gl.FramebufferTexture2D)(
                GL_FRAMEBUFFER,
                GL_COLOR_ATTACHMENT0,
                GL_TEXTURE_2D,
                out_tex,
                0,
            );
            let status = (gl.CheckFramebufferStatus)(GL_FRAMEBUFFER);
            if status != GL_FRAMEBUFFER_COMPLETE {
                (gl.BindFramebuffer)(GL_FRAMEBUFFER, 0);
                (gl.DeleteTextures)(2, planes.as_ptr());
                (self.destroy_image)(self.egl_display, img_y);
                (self.destroy_image)(self.egl_display, img_c);
                (gl.DeleteTextures)(1, &out_tex);
                bail!("FBO incomplete ({status:#x})");
            }
            (gl.Viewport)(0, 0, frame.width as i32, frame.height as i32);
            (gl.BindVertexArray)(self.vao);
            (gl.ActiveTexture)(GL_TEXTURE0);
            (gl.BindTexture)(GL_TEXTURE_2D, planes[0]);
            (gl.ActiveTexture)(GL_TEXTURE0 + 1);
            (gl.BindTexture)(GL_TEXTURE_2D, planes[1]);
            (gl.DrawArrays)(GL_TRIANGLES, 0, 3);
            (gl.BindFramebuffer)(GL_FRAMEBUFFER, 0);
            let sync = (gl.FenceSync)(GL_SYNC_GPU_COMMANDS_COMPLETE, 0);
            (gl.Flush)();
            // The draw is queued: plane textures + images can go now (the driver keeps the
            // underlying buffers alive until the queued commands execute).
            (gl.DeleteTextures)(2, planes.as_ptr());
            (self.destroy_image)(self.egl_display, img_y);
            (self.destroy_image)(self.egl_display, img_c);
            let err = (gl.GetError)();
            if err != 0 {
                (gl.DeleteTextures)(1, &out_tex);
                bail!("GL error {err:#x} during convert");
            }
            let mut b = gdk::GLTextureBuilder::new()
                .set_context(Some(&self.ctx))
                .set_id(out_tex)
                .set_width(frame.width as i32)
                .set_height(frame.height as i32)
                .set_format(gdk::MemoryFormat::R8g8b8a8)
                .set_sync(Some(sync));
            if let Some(state) = color_state {
                b = b.set_color_state(state);
            }
            let retired = self.retired.clone();
            let guard = frame.guard;
            let sync_bits = sync as usize; // GLsync as usize — the closure must be Send
            let texture = b.build_with_release_func(move || {
                drop(guard); // the decoder surface outlived every GPU read of it
                retired.lock().unwrap().push(Retired {
                    tex: out_tex,
                    sync: sync_bits,
                    size,
                });
            });
            Ok(texture)
        }
    }
    /// One single-plane `EGLImage` over a dmabuf plane (R8 luma / GR88 chroma), modifier
    /// passed explicitly.
    ///
    /// # Safety
    /// `self.ctx` must be current; the fd stays owned by the caller (EGL dups internally).
    unsafe fn plane_image(
        &self,
        width: u32,
        height: u32,
        fourcc: u32,
        plane: &crate::video::DmabufPlane,
        modifier: u64,
    ) -> Result<*const c_void> {
        let mut attribs = vec![
            EGL_WIDTH,
            width as i32,
            EGL_HEIGHT,
            height as i32,
            EGL_LINUX_DRM_FOURCC_EXT,
            fourcc as i32,
            EGL_DMA_BUF_PLANE0_FD_EXT,
            plane.fd,
            EGL_DMA_BUF_PLANE0_OFFSET_EXT,
            plane.offset as i32,
            EGL_DMA_BUF_PLANE0_PITCH_EXT,
            plane.stride as i32,
        ];
        if modifier != DRM_FORMAT_MOD_INVALID && modifier != 0 {
            attribs.extend_from_slice(&[
                EGL_DMA_BUF_PLANE0_MODIFIER_LO_EXT,
                (modifier & 0xffff_ffff) as u32 as i32,
                EGL_DMA_BUF_PLANE0_MODIFIER_HI_EXT,
                (modifier >> 32) as u32 as i32,
            ]);
        }
        attribs.push(EGL_NONE);
        // SAFETY: attribs is a valid EGL_NONE-terminated list; display/context are live.
        let img = unsafe {
            (self.create_image)(
                self.egl_display,
                std::ptr::null_mut(), // EGL_NO_CONTEXT — dmabuf import
                EGL_LINUX_DMA_BUF_EXT,
                std::ptr::null_mut(),
                attribs.as_ptr(),
            )
        };
        if img.is_null() {
            bail!(
                "eglCreateImageKHR rejected plane ({}x{} {:#x} mod {:#018x}): {:?}",
                width,
                height,
                fourcc,
                modifier,
                self.egl.get_error()
            );
        }
        Ok(img)
    }
 }
 impl Drop for GlConverter {
    /// Delete our objects from the shared context group (the context lives in GDK's share
    /// group — per-session leftovers would pile up across sessions). Textures GTK still
    /// holds at this moment release into `retired` afterwards, where nobody drains them:
    /// those names leak, but it's ≤ the pool depth once per session, not per frame.
    fn drop(&mut self) {
        self.ctx.make_current();
        let gl = &self.gl;
        // SAFETY: context current; only objects this converter created are deleted.
        unsafe {
            for r in self.retired.lock().unwrap().drain(..) {
                if r.sync != 0 {
                    (gl.DeleteSync)(r.sync as *const c_void);
                }
                (gl.DeleteTextures)(1, &r.tex);
            }
            (gl.DeleteFramebuffers)(1, &self.fbo);
            (gl.DeleteVertexArrays)(1, &self.vao);
            (gl.DeleteProgram)(self.program);
        }
    }
 }
 /// Compile the fullscreen-triangle NV12→RGB program (GLSL 300 es / 330 core per the GDK
 /// context's API). `gl_VertexID` drives the geometry — no buffers at all.
 ///
 /// # Safety
 /// A GL context must be current; `gl` must belong to it.
 unsafe fn build_program(gl: &GlFns, es: bool) -> Result<u32> {
    let header = if es {
        "#version 300 es\nprecision highp float;\n"
    } else {
        "#version 330 core\n"
    };
    let vs_src = format!(
        "{header}
 out vec2 v_uv;
 void main() {{
    vec2 p = vec2(float((gl_VertexID & 1) << 2) - 1.0, float((gl_VertexID & 2) << 1) - 1.0);
    v_uv = p * 0.5 + 0.5;
    gl_Position = vec4(p, 0.0, 1.0);
 }}"
    );
    let fs_src = format!(
        "{header}
 in vec2 v_uv;
 out vec4 frag;
 uniform sampler2D u_y;
 uniform sampler2D u_c;
 uniform mat3 u_mat;
 uniform vec3 u_off;
 void main() {{
    vec3 yuv = vec3(texture(u_y, v_uv).r, texture(u_c, v_uv).rg);
    frag = vec4(clamp(u_mat * (yuv + u_off), 0.0, 1.0), 1.0);
 }}"
    );
    // SAFETY: caller holds a current context; sources are valid UTF-8 with explicit lengths.
    unsafe {
        let compile = |kind: u32, src: &str| -> Result<u32> {
            let sh = (gl.CreateShader)(kind);
            let ptr = src.as_ptr();
            let len = src.len() as i32;
            (gl.ShaderSource)(sh, 1, &ptr, &len);
            (gl.CompileShader)(sh);
            let mut ok = 0i32;
            (gl.GetShaderiv)(sh, GL_COMPILE_STATUS, &mut ok);
            if ok == 0 {
                let mut log = vec![0u8; 1024];
                let mut n = 0i32;
                (gl.GetShaderInfoLog)(sh, 1024, &mut n, log.as_mut_ptr());
                (gl.DeleteShader)(sh);
                bail!(
                    "shader compile: {}",
                    String::from_utf8_lossy(&log[..n.max(0) as usize])
                );
            }
            Ok(sh)
        };
        let vs = compile(GL_VERTEX_SHADER, &vs_src)?;
        let fs = match compile(GL_FRAGMENT_SHADER, &fs_src) {
            Ok(fs) => fs,
            Err(e) => {
                (gl.DeleteShader)(vs);
                return Err(e);
            }
        };
        let prog = (gl.CreateProgram)();
        (gl.AttachShader)(prog, vs);
        (gl.AttachShader)(prog, fs);
        (gl.LinkProgram)(prog);
        (gl.DeleteShader)(vs);
        (gl.DeleteShader)(fs);
        let mut ok = 0i32;
        (gl.GetProgramiv)(prog, GL_LINK_STATUS, &mut ok);
        if ok == 0 {
            bail!("program link failed");
        }
        Ok(prog)
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    fn desc(matrix: u8, full_range: bool) -> ColorDesc {
        ColorDesc {
            primaries: 1,
            transfer: 1,
            matrix,
            full_range,
        }
    }
    fn apply(mat: &[f32; 9], off: &[f32; 3], yuv: [f32; 3]) -> [f32; 3] {
        let v = [yuv[0] + off[0], yuv[1] + off[1], yuv[2] + off[2]];
        // Column-major: out[r] = Σ mat[col*3 + r] * v[col]
        core::array::from_fn(|r| (0..3).map(|c| mat[c * 3 + r] * v[c]).sum())
    }
    /// Reference white (Y=235, U=V=128 limited) → RGB 1.0; reference black (Y=16) → 0.0.
    #[test]
    fn bt709_limited_white_black() {
        let (mat, off) = yuv_to_rgb(desc(1, false));
        let white = apply(&mat, &off, [235.0 / 255.0, 128.0 / 255.0, 128.0 / 255.0]);
        let black = apply(&mat, &off, [16.0 / 255.0, 128.0 / 255.0, 128.0 / 255.0]);
        for (w, b) in white.iter().zip(black) {
            assert!((w - 1.0).abs() < 0.005, "white {white:?}");
            assert!(b.abs() < 0.005, "black {black:?}");
        }
    }
    /// Full-range identity points: Y=1 → white, Y=0 → black, and a 601-vs-709 red spot
    /// check (pure V excursion produces R = 2(1−Kr)·0.5).
    #[test]
    fn full_range_and_red_excursion() {
        let (mat, off) = yuv_to_rgb(desc(5, true));
        let white = apply(&mat, &off, [1.0, 0.5, 0.5]);
        assert!(white.iter().all(|v| (v - 1.0).abs() < 1e-5), "{white:?}");
        let red = apply(&mat, &off, [0.0, 0.5, 1.0]);
        assert!((red[0] - 2.0 * (1.0 - 0.299) * 0.5).abs() < 1e-4, "{red:?}");
        // 709 differs from 601 in the same spot — guards the matrix-code dispatch.
        let (mat709, off709) = yuv_to_rgb(desc(1, true));
        let red709 = apply(&mat709, &off709, [0.0, 0.5, 1.0]);
        assert!(
            (red709[0] - 2.0 * (1.0 - 0.2126) * 0.5).abs() < 1e-4,
            "{red709:?}"
        );
        assert!((red[0] - red709[0]).abs() > 0.05);
    }
 }
@@ -27,7 +27,7 @@ GEOMETRY="${GEOMETRY:-1380x860x24}"
 SETTLE="${SETTLE:-1.2}"
 SHOT_DISPLAY="${SHOT_DISPLAY:-:99}"
-if [ "$#" -gt 0 ]; then SCENES=("$@"); else SCENES=(hosts settings trust pair addhost shortcuts library gamepad-library); fi
+if [ "$#" -gt 0 ]; then SCENES=("$@"); else SCENES=(hosts settings trust pair addhost shortcuts library); fi
 [ -x "$BIN" ] || {
 	echo "client binary not found: $BIN (build it first: cargo build --release -p punktfunk-client-linux)" >&2
@@ -1090,7 +1090,7 @@ async fn session(args: Args) -> Result<()> {
                break;
            }
            if started.elapsed() > std::time::Duration::from_secs(cap_secs)
-                || last_rx.elapsed() > std::time::Duration::from_secs(8)
+                || last_rx.elapsed() > std::time::Duration::from_secs(45)
            {
                break;
            }
@@ -5,6 +5,7 @@
 use super::style::*;
 use super::{AppCtx, Screen, Svc, Target};
 use crate::discovery::DiscoveredHost;
 use crate::session::{self, SessionEvent, SessionParams, Stats};
 use crate::trust::{self, KnownHost, KnownHosts, Settings};
 use crate::video::DecoderPref;
@@ -313,6 +314,97 @@ pub(crate) fn request_access(props: &Svc, target: &Target) {
    );
 }
 /// The Wake-on-LAN "wait until up" flow (mirrors the Apple `HostWaker`): the tapped saved host is
 /// offline but has a MAC, so send a magic packet, show a cancelable "Waking…" screen, and POLL mDNS
 /// for the host to reappear — re-sending the packet periodically — on a bounded deadline. A cold box
 /// takes far longer to POST/boot/re-advertise than a connect attempt will sit, so we can't just
 /// fire-and-dial. On reappearance we dial it (re-keying the saved host when it came back on a new
 /// IP); on timeout or Cancel we return to the host list.
 pub(crate) fn wake_and_connect(
    ctx: &Arc<AppCtx>,
    target: Target,
    set_screen: &AsyncSetState<Screen>,
    set_status: &AsyncSetState<String>,
 ) {
    // First packet now; the poll loop re-sends every RESEND_SECS (a single one can be missed, and
    // some NICs only wake on a fresh packet after dropping into a deeper sleep state).
    crate::wol::wake(&target.mac, target.addr.parse().ok());
    // A fresh cancel flag per wake, installed where the "Waking…" screen's Cancel button reads it
    // back (the same shared channel as the request-access flow); the poll loop checks the same `Arc`.
    let cancel = Arc::new(AtomicBool::new(false));
    *ctx.shared.cancel.lock().unwrap() = Some(cancel.clone());
    // The busy page reads the host name from the shared target.
    *ctx.shared.target.lock().unwrap() = target.clone();
    set_status.call(String::new());
    set_screen.call(Screen::Waking);
    let (ctx, ss, st) = (ctx.clone(), set_screen.clone(), set_status.clone());
    std::thread::spawn(move || {
        // Generous — a cold boot + service start can be a minute-plus; re-send periodically.
        const TIMEOUT_SECS: u64 = 90;
        const RESEND_SECS: u64 = 6;
        let rx = crate::discovery::browse();
        let mut seen: Vec<DiscoveredHost> = Vec::new();
        let mut elapsed: u64 = 0;
        loop {
            // Cancel already returned the UI to the host list — stop re-sending and tear down.
            if cancel.load(Ordering::SeqCst) {
                return;
            }
            // Drain freshly-resolved adverts into the accumulator (newest wins per key).
            while let Ok(h) = rx.try_recv() {
                if let Some(e) = seen.iter_mut().find(|e| e.key == h.key) {
                    *e = h;
                } else {
                    seen.push(h);
                }
            }
            // Match on the pinned fingerprint first (it survives an IP change), else last address.
            let resolved = seen
                .iter()
                .find(|h| match &target.fp_hex {
                    Some(fp) if !h.fp_hex.is_empty() => h.fp_hex == *fp,
                    _ => h.addr == target.addr && h.port == target.port,
                })
                .map(|h| (h.addr.clone(), h.port));
            if let Some((addr, port)) = resolved {
                let mut target = target.clone();
                // Came back on a new IP (DHCP): dial the fresh address and re-key the saved host so
                // the pin stays reachable next time (keyed by fingerprint; addr/port overwritten,
                // `paired`/`mac` preserved by `upsert`).
                if addr != target.addr || port != target.port {
                    target.addr = addr;
                    target.port = port;
                    if let Some(fp) = target.fp_hex.clone() {
                        let mut k = KnownHosts::load();
                        k.upsert(KnownHost {
                            name: target.name.clone(),
                            addr: target.addr.clone(),
                            port: target.port,
                            fp_hex: fp,
                            paired: false,
                            mac: target.mac.clone(),
                        });
                        let _ = k.save();
                    }
                }
                initiate(&ctx, target, &ss, &st);
                return;
            }
            if elapsed >= TIMEOUT_SECS {
                st.call("The host didn't come online.".to_string());
                ss.call(Screen::Hosts);
                return;
            }
            std::thread::sleep(Duration::from_secs(1));
            elapsed += 1;
            if elapsed % RESEND_SECS == 0 {
                crate::wol::wake(&target.mac, target.addr.parse().ok());
            }
        }
    });
 }
 /// The plain "Connecting…" screen shown while the session worker handshakes. No hooks.
 pub(crate) fn connecting_page(ctx: &Arc<AppCtx>, status: &str) -> Element {
    let target_name = ctx.shared.target.lock().unwrap().name.clone();
@@ -365,3 +457,35 @@ pub(crate) fn request_access_page(
        vec![cancel_btn.into()],
    )
 }
 /// The cancelable "Waking…" screen (Wake-on-LAN wait-until-up flow): a spinner + guidance while the
 /// poll loop waits for the woken host to reappear on mDNS, plus a Cancel that returns to the host
 /// list and trips the shared cancel flag so the poll loop stops re-sending and tears down. No hooks.
 pub(crate) fn waking_page(ctx: &Arc<AppCtx>, set_screen: &AsyncSetState<Screen>) -> Element {
    let target_name = ctx.shared.target.lock().unwrap().name.clone();
    let headline = if target_name.is_empty() {
        "Waking the host\u{2026}".to_string()
    } else {
        format!("Waking {target_name}\u{2026}")
    };
    let cancel_btn = {
        let (ctx, ss) = (ctx.clone(), set_screen.clone());
        button("Cancel")
            .icon(Symbol::Cancel)
            .on_click(move || {
                // Return the UI immediately and trip the flag the poll loop is watching so it stops
                // re-sending and exits without touching a screen a later action may already own.
                if let Some(c) = ctx.shared.cancel.lock().unwrap().as_ref() {
                    c.store(true, Ordering::SeqCst);
                }
                ss.call(Screen::Hosts);
            })
            .horizontal_alignment(HorizontalAlignment::Center)
    };
    busy_page(
        &headline,
        "Sent a wake signal and waiting for the host to come online \u{2014} this can take up to a \
         minute for a sleeping or powered-off machine.",
        vec![cancel_btn.into()],
    )
 }
@@ -2,7 +2,7 @@
 //! tiles in a responsive grid, with a per-host "…" menu (connect / speed test / rename /
 //! forget) and a manual connect entry — the same card layout as the Linux and Apple clients.
-use super::connect::initiate;
+use super::connect::{initiate, wake_and_connect};
 use super::speed::SpeedState;
 use super::style::*;
 use super::{Screen, Svc, Target};
@@ -386,12 +386,14 @@ pub(crate) fn hosts_page(props: &HostsProps, cx: &mut RenderCx) -> Element {
                ),
                Some(menu),
                Some(Box::new(move || {
-                    // Auto-wake an offline saved host before connecting; the connect's own
+                    // Offline saved host with a known MAC: wake it and WAIT for it to reappear on
-                    // retry/timeout gives a woken host time to come up.
+                    // the network (re-sending periodically) before dialing — a cold box boots far
                    // slower than a connect will sit. An online host dials straight away.
                    if can_wake {
-                        crate::wol::wake(&target.mac, target.addr.parse().ok());
+                        wake_and_connect(&ctx2, target.clone(), &ss, &st);
                    } else {
                        initiate(&ctx2, target.clone(), &ss, &st);
                    }
                    initiate(&ctx2, target.clone(), &ss, &st)
                })),
            ));
        }
@@ -50,6 +50,9 @@ pub(crate) enum Screen {
    /// The no-PIN "request access" wait: an identified connect is in flight, parked by the host
    /// until the operator approves this device in its console. Cancelable.
    RequestAccess,
    /// Wake-on-LAN "wait until up": a magic packet was sent to an offline saved host and we're
    /// polling mDNS for it to reappear (re-sending periodically) before dialing. Cancelable.
    Waking,
    Stream,
    Settings,
    /// Open-source / third-party license notices (reached from Settings).
@@ -244,6 +247,7 @@ fn root(cx: &mut RenderCx, ctx: &Arc<AppCtx>) -> Element {
                    set_hud.call(stream::HudSample {
                        stats: *shared.stats.lock().unwrap(),
                        captured: crate::input::is_captured(),
                        visible: crate::input::hud_visible(),
                        present: crate::render::present_stats(),
                    });
                })
@@ -378,10 +382,11 @@ fn root(cx: &mut RenderCx, ctx: &Arc<AppCtx>) -> Element {
                set_hover,
            },
        ),
-        // connecting_page / request_access_page / settings_page / licenses_page use no hooks
+        // connecting_page / request_access_page / waking_page / settings_page / licenses_page use
-        // (they never touch `cx`), so calling them inline is sound.
+        // no hooks (they never touch `cx`), so calling them inline is sound.
        Screen::Connecting => connect::connecting_page(ctx, &status),
        Screen::RequestAccess => connect::request_access_page(ctx, &set_screen),
        Screen::Waking => connect::waking_page(ctx, &set_screen),
        Screen::Settings => settings::settings_page(
            ctx,
            &set_screen,
@@ -109,6 +109,59 @@ fn settings_card(controls: Vec<Element>) -> Element {
    card(vstack(controls).spacing(10.0)).into()
 }
 /// The in-stream keyboard shortcuts, in the GTK Shortcuts window's order: the chord, then what it
 /// does. Read-only — the bindings themselves live in the input hook (`crate::input`); this is the
 /// Windows analogue of that window, so both clients document the same set.
 const STREAM_SHORTCUTS: &[(&str, &str)] = &[
    ("F11", "Toggle fullscreen"),
    (
        "Ctrl+Alt+Shift+Q",
        "Release captured input (click the stream to recapture)",
    ),
    ("Ctrl+Alt+Shift+D", "Disconnect"),
    ("Ctrl+Alt+Shift+S", "Toggle the statistics overlay"),
 ];
 /// A subtle key-cap chip for the shortcuts reference — the chord on a filled, bordered pill.
 fn key_chip(keys: &str) -> Element {
    border(text_block(keys).font_size(12.0).semibold())
        .background(ThemeRef::SubtleFill)
        .border_brush(ThemeRef::CardStroke)
        .border_thickness(uniform(1.0))
        .corner_radius(6.0)
        .padding(edges(8.0, 3.0, 8.0, 3.0))
        .horizontal_alignment(HorizontalAlignment::Left)
        .into()
 }
 /// A read-only reference card listing the in-stream keyboard shortcuts — the Windows counterpart of
 /// the GTK client's Keyboard Shortcuts window. One grid, chord chip then action, so the actions
 /// line up across rows.
 fn shortcuts_reference() -> Element {
    let mut children: Vec<Element> = Vec::new();
    for (i, (keys, action)) in STREAM_SHORTCUTS.iter().enumerate() {
        let row = i as i32;
        children.push(key_chip(keys).grid_row(row).grid_column(0));
        let action_cell: Element = text_block(*action)
            .foreground(ThemeRef::SecondaryText)
            .vertical_alignment(VerticalAlignment::Center)
            .into();
        children.push(action_cell.grid_row(row).grid_column(1));
    }
    let table = grid(children)
        .columns([GridLength::Auto, GridLength::Star(1.0)])
        .rows(vec![GridLength::Auto; STREAM_SHORTCUTS.len()])
        .column_spacing(12.0)
        .row_spacing(6.0);
    card(vstack((
        text_block("In-stream keyboard shortcuts")
            .semibold()
            .margin(edges(0.0, 0.0, 0.0, 8.0)),
        table,
    )))
    .into()
 }
 /// The settings screen: a stock WinUI `NavigationView` (the Windows-Settings sidebar pattern) —
 /// one pane item per section, the section's card as the content, the built-in back arrow
 /// returning to the host list. `section`/`set_section` are the selected pane tag, held in ROOT
@@ -315,7 +368,10 @@ pub(crate) fn settings_page(
    let hud_toggle = setting_toggle(ctx, "Show the stats overlay (HUD)", s.show_hud, |s, on| {
        s.show_hud = on
    })
-    .tooltip("The in-stream overlay: mode, codec, fps, bitrate, latency, decode path.");
+    .tooltip(
        "The in-stream overlay: mode, codec, fps, bitrate, latency, decode path. \
         Ctrl+Alt+Shift+S toggles it live while streaming.",
    );
    let licenses_button = {
        let ss = set_screen.clone();
@@ -343,11 +399,16 @@ pub(crate) fn settings_page(
        ),
        "input" => (
            "Input",
            vstack((
                settings_card(vec![
                    forward_combo.into(),
                    pad_combo.into(),
                    shortcuts_toggle.into(),
                ]),
                shortcuts_reference(),
            ))
            .spacing(14.0)
            .into(),
        ),
        "audio" => (
            "Audio",
@@ -22,6 +22,11 @@ use windows_reactor::*;
 pub(crate) struct HudSample {
    pub(crate) stats: Stats,
    pub(crate) captured: bool,
    /// Whether the stats overlay should be shown — the Settings default at stream start, then
    /// whatever Ctrl+Alt+Shift+S last set (see [`crate::input::hud_visible`]). Carried in the
    /// sample so a live toggle changes the sample and re-renders the page (the stream page is a
    /// child component — only a changed prop re-renders it).
    pub(crate) visible: bool,
    /// The render thread's glass-side window (presents/s, skips, end-to-end p50/p95, display
    /// stage p50) — see [`crate::render::present_stats`].
    pub(crate) present: crate::render::PresentStats,
@@ -72,7 +77,10 @@ pub(crate) fn stream_page(props: &StreamProps, cx: &mut RenderCx) -> Element {
    let connector_ref = cx.use_ref::<Option<Arc<NativeClient>>>(None);
    cx.use_effect_with_cleanup((), {
        let shared = ctx.shared.clone();
-        let inhibit = ctx.settings.lock().unwrap().inhibit_shortcuts;
+        let (inhibit, show_hud) = {
            let s = ctx.settings.lock().unwrap();
            (s.inhibit_shortcuts, s.show_hud)
        };
        let connector_ref = connector_ref.clone();
        move || {
            if let Some((connector, frames, stop)) = shared.handoff.lock().unwrap().take() {
@@ -80,7 +88,7 @@ pub(crate) fn stream_page(props: &StreamProps, cx: &mut RenderCx) -> Element {
                let clock_offset = connector.clock_offset_ns;
                connector_ref.set(Some(connector.clone()));
                PENDING.with(|c| *c.borrow_mut() = Some((frames, clock_offset)));
-                crate::input::install(connector, mode, inhibit, stop);
+                crate::input::install(connector, mode, inhibit, show_hud, stop);
            }
            Some(|| {
                RENDER.with(|c| {
@@ -96,9 +104,6 @@ pub(crate) fn stream_page(props: &StreamProps, cx: &mut RenderCx) -> Element {
    let mode = connector_ref.borrow().as_ref().map(|c| c.mode());
    let host = ctx.shared.target.lock().unwrap().name.clone();
    // Read per render: this page re-renders on every HUD sample (~400 ms), so toggling the
    // overlay in Settings takes effect mid-stream.
    let show_hud = ctx.settings.lock().unwrap().show_hud;
    let mut layers: Vec<Element> = vec![swap_chain_panel()
        .on_mounted(|panel| {
            // Placeholder size — the first `on_resize` (fired after the first layout pass)
@@ -134,12 +139,48 @@ pub(crate) fn stream_page(props: &StreamProps, cx: &mut RenderCx) -> Element {
            });
        })
        .into()];
-    if show_hud {
+    // The overlay follows the LIVE visibility (Settings default, then Ctrl+Alt+Shift+S): the page
    // re-renders on every HUD sample (~400 ms), so a toggle takes effect promptly mid-stream.
    if props.hud.visible {
        layers.push(hud_overlay(&props.hud, mode, &host));
    }
    // Flash the shortcut key set for the first few seconds of every session, regardless of the
    // HUD setting — so "how do I get back out" is answered the moment the stream comes up (parity
    // with the GTK client's stream-start hint). Uptime drives it, so it needs no timer/state: the
    // HUD poll re-renders the page each second and the banner drops once the session passes the
    // threshold.
    if props.hud.stats.uptime_secs < START_HINT_SECS {
        layers.push(start_hint());
    }
    grid(layers).into()
 }
 /// How long the stream-start shortcut banner stays up (seconds of session uptime).
 const START_HINT_SECS: u32 = 6;
 /// The stream-start shortcut banner: the full client key set on a translucent pill, bottom-centre,
 /// shown for [`START_HINT_SECS`] at the start of every session (see the call site). Independent of
 /// the stats overlay, so it appears even with the HUD turned off.
 fn start_hint() -> Element {
    border(
        text_block(
            "Click the stream to capture \u{00B7} Ctrl+Alt+Shift+Q releases \u{00B7} \
             Ctrl+Alt+Shift+D disconnects \u{00B7} Ctrl+Alt+Shift+S stats \u{00B7} F11 fullscreen",
        )
        .font_size(12.0)
        .semibold()
        .foreground(Color::rgb(235, 235, 235)),
    )
    .background(Color::rgb(0, 0, 0))
    .corner_radius(10.0)
    .padding(edges(14.0, 8.0, 14.0, 8.0))
    .opacity(0.82)
    .horizontal_alignment(HorizontalAlignment::Center)
    .vertical_alignment(VerticalAlignment::Bottom)
    .margin(edges(0.0, 0.0, 0.0, 28.0))
    .into()
 }
 /// A small chip for the dark HUD: coloured text on a translucent dark fill.
 fn hud_chip(text: &str, color: Color) -> Border {
    border(
@@ -241,9 +282,11 @@ fn hud_overlay(hud: &HudSample, mode: Option<Mode>, host: &str) -> Element {
    }
    let session_line = session_bits.join(" \u{00B7} ");
    let hint = if hud.captured {
-        "Ctrl+Alt+Shift+Q releases the mouse \u{00B7} Ctrl+Alt+Shift+D disconnects"
+        "Ctrl+Alt+Shift+Q releases the mouse \u{00B7} Ctrl+Alt+Shift+D disconnects \u{00B7} \
         Ctrl+Alt+Shift+S stats \u{00B7} F11 fullscreen"
    } else {
-        "Click the stream to capture \u{00B7} Ctrl+Alt+Shift+D disconnects"
+        "Click the stream to capture \u{00B7} Ctrl+Alt+Shift+D disconnects \u{00B7} \
         Ctrl+Alt+Shift+S stats \u{00B7} F11 fullscreen"
    };
    let dim = |t: &str| {
        text_block(t)
@@ -26,6 +26,8 @@
 //! desktop instead of being forwarded. **Ctrl+Alt+Shift+D disconnects** the session (consumed
 //! locally, works captured or released while our window is foreground): it trips the session's
 //! stop flag, the pump winds down, and the event loop navigates back to the host list.
 //! **Ctrl+Alt+Shift+S** toggles the stats overlay live and **F11** toggles fullscreen — both are
 //! client-local shortcuts (consumed, never forwarded), matching the GTK client's stream key set.
 use punktfunk_core::client::NativeClient;
 use punktfunk_core::config::Mode;
@@ -36,7 +38,7 @@ use std::sync::{Arc, Mutex};
 use windows::Win32::Foundation::{HWND, LPARAM, LRESULT, POINT, RECT, WPARAM};
 use windows::Win32::Graphics::Gdi::ClientToScreen;
 use windows::Win32::System::LibraryLoader::GetModuleHandleW;
-use windows::Win32::UI::Input::KeyboardAndMouse::{VK_D, VK_Q};
+use windows::Win32::UI::Input::KeyboardAndMouse::{VK_D, VK_F11, VK_Q, VK_S};
 use windows::Win32::UI::WindowsAndMessaging::{
    CallNextHookEx, ClipCursor, GetClientRect, GetForegroundWindow, SetCursorPos,
    SetWindowsHookExW, ShowCursor, UnhookWindowsHookEx, HC_ACTION, HHOOK, KBDLLHOOKSTRUCT,
@@ -85,12 +87,22 @@ static KBD_HOOK: AtomicIsize = AtomicIsize::new(0);
 static MOUSE_HOOK: AtomicIsize = AtomicIsize::new(0);
 /// Mirror of `State::captured` for lock-free reads off the UI thread (the HUD poll).
 static CAPTURED: AtomicBool = AtomicBool::new(false);
 /// Live stats-overlay visibility. Seeded from `Settings::show_hud` at `install`, then toggled by
 /// Ctrl+Alt+Shift+S for the session (parity with the GTK client's live `s` toggle); the HUD poll
 /// reads it lock-free to drive the overlay.
 static HUD_VISIBLE: AtomicBool = AtomicBool::new(false);
 /// Whether stream input is currently captured (drives the HUD's release/capture hint).
 pub fn is_captured() -> bool {
    CAPTURED.load(Ordering::Relaxed)
 }
 /// Whether the stats overlay should be shown: the Settings default at stream start, then whatever
 /// Ctrl+Alt+Shift+S last set for the session. Read by the HUD poll thread.
 pub fn hud_visible() -> bool {
    HUD_VISIBLE.load(Ordering::Relaxed)
 }
 /// Set the capture intent and engage/release the pointer lock to match.
 fn set_captured(st: &mut State, on: bool) {
    st.captured = on;
@@ -103,13 +115,16 @@ fn set_captured(st: &mut State, on: bool) {
 /// Install the hooks for a streaming session. Call from the UI thread once the window is shown.
 /// `inhibit_shortcuts` forwards system shortcuts (Alt+Tab, Win, …) to the host; off = local.
 /// `show_hud` seeds the stats-overlay visibility that Ctrl+Alt+Shift+S then toggles live.
 /// `stop` is the session's stop flag, tripped by the disconnect shortcut.
 pub fn install(
    connector: Arc<NativeClient>,
    mode: Mode,
    inhibit_shortcuts: bool,
    show_hud: bool,
    stop: Arc<AtomicBool>,
 ) {
    HUD_VISIBLE.store(show_hud, Ordering::Relaxed);
    let hwnd = unsafe { GetForegroundWindow() };
    let mut st = State {
        connector,
@@ -229,6 +244,73 @@ fn set_locked(st: &mut State, on: bool) {
    st.locked = on;
 }
 /// Toggle borderless fullscreen for our top-level window (F11). The classic Win32 dance: entering,
 /// save the window placement and strip `WS_OVERLAPPEDWINDOW`, then size the window to the whole
 /// monitor; exiting, restore the style and the saved placement. The window's own style bit doubles
 /// as the fullscreen flag, so no extra state beyond the saved placement is needed. windows-reactor
 /// owns the WinUI window but exposes no fullscreen API, so we drive the HWND directly (parity with
 /// the GTK client's F11). The SwapChainPanel follows the resulting `WM_SIZE` like any window resize.
 fn toggle_fullscreen(hwnd: isize) {
    use windows::Win32::Graphics::Gdi::{
        GetMonitorInfoW, MonitorFromWindow, MONITORINFO, MONITOR_DEFAULTTOPRIMARY,
    };
    use windows::Win32::UI::WindowsAndMessaging::{
        GetWindowLongPtrW, GetWindowPlacement, SetWindowLongPtrW, SetWindowPlacement, SetWindowPos,
        GWL_STYLE, SWP_FRAMECHANGED, SWP_NOMOVE, SWP_NOOWNERZORDER, SWP_NOSIZE, SWP_NOZORDER,
        WINDOWPLACEMENT, WS_OVERLAPPEDWINDOW,
    };
    // The pre-fullscreen placement, so exiting restores the exact windowed size + position. Only
    // ever touched on the UI thread (the hook proc), but a Mutex keeps the static sound + `Sync`.
    static SAVED: Mutex<Option<WINDOWPLACEMENT>> = Mutex::new(None);
    let hwnd = HWND(hwnd as *mut _);
    let overlapped = WS_OVERLAPPEDWINDOW.0 as isize;
    unsafe {
        let style = GetWindowLongPtrW(hwnd, GWL_STYLE);
        if style & overlapped != 0 {
            // Windowed → fullscreen: remember where we were, drop the frame, cover the monitor.
            let mut wp = WINDOWPLACEMENT {
                length: std::mem::size_of::<WINDOWPLACEMENT>() as u32,
                ..Default::default()
            };
            let mut mi = MONITORINFO {
                cbSize: std::mem::size_of::<MONITORINFO>() as u32,
                ..Default::default()
            };
            let mon = MonitorFromWindow(hwnd, MONITOR_DEFAULTTOPRIMARY);
            if GetWindowPlacement(hwnd, &mut wp).is_ok() && GetMonitorInfoW(mon, &mut mi).as_bool()
            {
                *SAVED.lock().unwrap() = Some(wp);
                SetWindowLongPtrW(hwnd, GWL_STYLE, style & !overlapped);
                let r = mi.rcMonitor;
                let _ = SetWindowPos(
                    hwnd,
                    None,
                    r.left,
                    r.top,
                    r.right - r.left,
                    r.bottom - r.top,
                    SWP_NOZORDER | SWP_NOOWNERZORDER | SWP_FRAMECHANGED,
                );
            }
        } else {
            // Fullscreen → windowed: restore the frame, then the saved placement.
            SetWindowLongPtrW(hwnd, GWL_STYLE, style | overlapped);
            if let Some(wp) = SAVED.lock().unwrap().take() {
                let _ = SetWindowPlacement(hwnd, &wp);
            }
            let _ = SetWindowPos(
                hwnd,
                None,
                0,
                0,
                0,
                0,
                SWP_NOMOVE | SWP_NOSIZE | SWP_NOZORDER | SWP_NOOWNERZORDER | SWP_FRAMECHANGED,
            );
        }
    }
 }
 fn send(c: &NativeClient, kind: InputKind, code: u32, x: i32, y: i32, flags: u32) {
    let _ = c.send_input(&InputEvent {
        kind,
@@ -281,10 +363,34 @@ unsafe extern "system" fn kbd_proc(code: i32, wparam: WPARAM, lparam: LPARAM) ->
                // the cursor is free while the session winds down and the UI navigates home.
                if !up && vk == VK_D.0 && st.ctrl && st.alt && st.shift {
                    set_captured(st, false);
                    // Deliberate user exit → close with QUIT_CLOSE_CODE so the host tears the session
                    // down immediately instead of holding the keep-alive linger for a reconnect.
                    st.connector.disconnect_quit();
                    st.stop.store(true, Ordering::SeqCst);
                    tracing::info!("disconnect requested (Ctrl+Alt+Shift+D)");
                    return LRESULT(1);
                }
                // Toggle the stats overlay: Ctrl+Alt+Shift+S (consumed locally). Seeded from
                // Settings at install; this live toggle overrides it for the session — parity
                // with the GTK client, where `s` flips the OSD without leaving the stream.
                if !up && vk == VK_S.0 && st.ctrl && st.alt && st.shift {
                    let on = !HUD_VISIBLE.load(Ordering::Relaxed);
                    HUD_VISIBLE.store(on, Ordering::Relaxed);
                    tracing::info!(hud = on, "stats overlay toggled (Ctrl+Alt+Shift+S)");
                    return LRESULT(1);
                }
                // Toggle fullscreen: F11 (consumed locally, no modifiers — a client shortcut,
                // never a wire key). Works captured or released. The window resize changes the
                // client rect, so re-lock to recompute the pointer confinement + recentre.
                if !up && vk == VK_F11.0 {
                    toggle_fullscreen(st.hwnd);
                    if st.locked {
                        set_locked(st, false);
                        set_locked(st, true);
                    }
                    tracing::info!("fullscreen toggled (F11)");
                    return LRESULT(1);
                }
                if st.captured {
                    // With shortcut capture off, hand Alt+Tab & co. to the local desktop —
                    // neither forwarded nor swallowed.
@@ -0,0 +1,38 @@
 [package]
 name = "pf-client-core"
 description = "Shared Linux-client plumbing — session pump, FFmpeg decode, PipeWire audio, SDL3 gamepads, trust store, discovery — extracted from the GTK client so the shell and the Vulkan session binary build on one implementation"
 version.workspace = true
 edition.workspace = true
 rust-version.workspace = true
 license.workspace = true
 authors.workspace = true
 repository.workspace = true
 # Same Linux gating as clients/linux: `cargo build --workspace` stays green on macOS
 # (the Mac client lives in clients/apple); elsewhere this crate is `wol` plus stubs-free
 # emptiness. `wol` is pure std and stays cross-platform, matching the old main.rs.
 [target.'cfg(target_os = "linux")'.dependencies]
 punktfunk-core = { path = "../punktfunk-core", features = ["quic"] }
 # FFmpeg's Vulkan hwcontext surface (Vulkan Video decode on the presenter's device).
 pf-ffvk = { path = "../pf-ffvk" }
 async-channel = "2"
 # Video decode (same FFmpeg pin as the host) and audio.
 ffmpeg-next = "8"
 opus = "0.3"
 pipewire = "0.9"
 # Gamepads: capture + feedback (full DualSense fidelity — touchpad/motion/triggers/LEDs
 # need the hidapi driver).
 sdl3 = { version = "0.18", features = ["hidapi"] }
 mdns-sd = "0.20"
 # Game-library fetch from the host's management API over mTLS + fingerprint pinning.
 # `ureq` is small + sync (the host uses it too) and its rustls unifies with the
 # workspace's (quinn's) 0.23; the pinning verifier mirrors core's private `PinVerify`.
 ureq = "2"
 rustls = { version = "0.23", features = ["ring"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 anyhow = "1"
 tracing = "0.1"
@@ -339,7 +339,7 @@ impl GamepadService {
        if let Err(e) = std::thread::Builder::new()
            .name("punktfunk-gamepad".into())
            .spawn(move || {
-                if let Err(e) = run(&p, &a, &ctl_rx, &escape_tx, &disconnect_tx, &menu_tx) {
+                if let Err(e) = run(p, a, &ctl_rx, &escape_tx, &disconnect_tx, &menu_tx) {
                    tracing::warn!(error = %e, "gamepad service ended — pads disabled");
                }
            })
@@ -356,6 +356,45 @@ impl GamepadService {
        }
    }
    /// The caller-pumped variant for the session binary: SDL video+events live on ITS
    /// main thread, and SDL only ever grants one thread the event queue — a second
    /// `start()`-style worker thread could never see gamepad events there. The caller
    /// owns the SDL context, feeds every polled event to [`GamepadPump::handle_event`],
    /// and calls [`GamepadPump::tick`] once per loop iteration (the threaded worker's
    /// per-wakeup work: ctl drain, chord-hold check, menu repeat, feedback).
    ///
    /// Like the threaded worker, this disables the Valve HIDAPI drivers up front (their
    /// mere enumeration kills the Deck's trackpad-mouse system-wide); they are enabled
    /// for the duration of an attached session only.
    pub fn pumped(subsystem: sdl3::GamepadSubsystem) -> (GamepadService, GamepadPump) {
        set_valve_hidapi(false);
        let pads = Arc::new(Mutex::new(Vec::new()));
        let active = Arc::new(Mutex::new(None));
        let (ctl, ctl_rx) = std::sync::mpsc::channel();
        let (escape_tx, escape_rx) = async_channel::unbounded();
        let (disconnect_tx, disconnect_rx) = async_channel::unbounded();
        let (menu_tx, menu_rx) = async_channel::unbounded();
        let worker = Worker::new(
            subsystem,
            pads.clone(),
            active.clone(),
            escape_tx,
            disconnect_tx,
            menu_tx,
        );
        (
            GamepadService {
                pads,
                active,
                ctl,
                escape_rx,
                disconnect_rx,
                menu_rx,
            },
            GamepadPump { worker, ctl_rx },
        )
    }
    /// A receiver that yields one `()` each time the controller escape chord is pressed.
    /// A fresh clone per call (shared mpmc channel); the stream page spawns a future on it.
    pub fn escape_events(&self) -> async_channel::Receiver<()> {
@@ -431,6 +470,32 @@ impl GamepadService {
    }
 }
 /// The caller-pumped worker half of [`GamepadService::pumped`]: the session binary owns
 /// SDL and its event loop; this just needs the events and a periodic tick.
 pub struct GamepadPump {
    worker: Worker,
    ctl_rx: Receiver<Ctl>,
 }
 impl GamepadPump {
    /// Feed one polled SDL event. Non-gamepad events (window, keyboard, mouse) are
    /// ignored, so the caller can forward everything unfiltered.
    pub fn handle_event(&mut self, event: sdl3::event::Event) {
        self.worker.handle_event(event);
    }
    /// The per-wakeup polled work the threaded worker runs after each event wait: ctl
    /// drain (attach/detach/pin/menu), the escape-chord hold check, menu repeat timing,
    /// and rumble/HID feedback. Call once per loop iteration (≲30 ms cadence keeps
    /// chord-hold and haptics inside the threaded worker's tolerances).
    pub fn tick(&mut self) {
        let _ = self.worker.drain_ctl(&self.ctl_rx);
        self.worker.maybe_fire_disconnect();
        self.worker.menu_poll();
        self.worker.render_feedback();
    }
 }
 fn send(connector: &NativeClient, kind: InputKind, code: u32, x: i32) {
    let _ = connector.send_input(&InputEvent {
        kind,
@@ -528,11 +593,11 @@ impl Ds5Feedback {
    }
 }
-struct Worker<'a> {
+struct Worker {
    subsystem: sdl3::GamepadSubsystem,
    /// UI-facing state (the `GamepadService` accessors): pad list, active pad, pin.
-    pads_out: &'a Mutex<Vec<PadInfo>>,
+    pads_out: Arc<Mutex<Vec<PadInfo>>>,
-    active_out: &'a Mutex<Option<PadInfo>>,
+    active_out: Arc<Mutex<Option<PadInfo>>>,
    /// The ONE device held open — the active pad while a session is attached, `None`
    /// otherwise. Opening is what grabs the hardware (SDL's HIDAPI drivers take the
    /// hidraw device away from the system), so idle keeps this empty; see the module doc.
@@ -578,7 +643,7 @@ struct Worker<'a> {
    menu_tx: async_channel::Sender<MenuEvent>,
 }
-impl Worker<'_> {
+impl Worker {
    fn active_id(&self) -> Option<u32> {
        // The pin matches by stable key (most recently connected wins if two identical pads
        // share one); an unmatched pin falls through to automatic without being cleared.
@@ -1217,9 +1282,46 @@ impl Worker<'_> {
    }
 }
 impl Worker {
    /// The blank worker over an SDL gamepad subsystem — shared by the threaded service
    /// (`run`) and the caller-pumped variant (`GamepadService::pumped`).
    fn new(
        subsystem: sdl3::GamepadSubsystem,
        pads_out: Arc<Mutex<Vec<PadInfo>>>,
        active_out: Arc<Mutex<Option<PadInfo>>>,
        escape_tx: async_channel::Sender<()>,
        disconnect_tx: async_channel::Sender<()>,
        menu_tx: async_channel::Sender<MenuEvent>,
    ) -> Worker {
        Worker {
            subsystem,
            pads_out,
            active_out,
            open: None,
            order: Vec::new(),
            pinned: None,
            attached: None,
            last_axis: [i32::MIN; 6],
            held_buttons: Vec::new(),
            held_touches: std::collections::HashSet::new(),
            surface_last: [(0, 0, false); 2],
            held_clicks: [false; 2],
            last_accel: [0; 3],
            escape_tx,
            disconnect_tx,
            chord_armed: false,
            chord_since: None,
            disconnect_fired: false,
            menu_mode: false,
            menu_nav: MenuNav::new(),
            menu_tx,
        }
    }
 }
 fn run(
-    pads_out: &Mutex<Vec<PadInfo>>,
+    pads_out: Arc<Mutex<Vec<PadInfo>>>,
-    active_out: &Mutex<Option<PadInfo>>,
+    active_out: Arc<Mutex<Option<PadInfo>>>,
    ctl: &Receiver<Ctl>,
    escape_tx: &async_channel::Sender<()>,
    disconnect_tx: &async_channel::Sender<()>,
@@ -1237,29 +1339,14 @@ fn run(
    let subsystem = sdl.gamepad().map_err(|e| e.to_string())?;
    let mut pump = sdl.event_pump().map_err(|e| e.to_string())?;
-    let mut w = Worker {
+    let mut w = Worker::new(
        subsystem,
        pads_out,
        active_out,
-        open: None,
+        escape_tx.clone(),
-        order: Vec::new(),
+        disconnect_tx.clone(),
-        pinned: None,
+        menu_tx.clone(),
-        attached: None,
+    );
        last_axis: [i32::MIN; 6],
        held_buttons: Vec::new(),
        held_touches: std::collections::HashSet::new(),
        surface_last: [(0, 0, false); 2],
        held_clicks: [false; 2],
        last_accel: [0; 3],
        escape_tx: escape_tx.clone(),
        disconnect_tx: disconnect_tx.clone(),
        chord_armed: false,
        chord_since: None,
        disconnect_fired: false,
        menu_mode: false,
        menu_nav: MenuNav::new(),
        menu_tx: menu_tx.clone(),
    };
    loop {
        // Control plane from the UI thread.
@@ -0,0 +1,26 @@
 //! Shared, UI-agnostic Linux-client plumbing, extracted verbatim from the GTK client
 //! (design: punktfunk-planning `linux-client-rearchitecture.md`, Phase 0) so the desktop
 //! shell and the Vulkan session binary build on one implementation.
 //!
 //! Nothing here may depend on a UI toolkit: the presenter contract is `session`'s
 //! channels (`SessionHandle`) and `video`'s `DecodedImage` (RGBA bytes or dmabuf fds +
 //! plane layout) — how frames reach the screen is the consumer's business.
 #[cfg(target_os = "linux")]
 pub mod audio;
 #[cfg(target_os = "linux")]
 pub mod discovery;
 #[cfg(target_os = "linux")]
 pub mod gamepad;
 #[cfg(target_os = "linux")]
 pub mod keymap;
 #[cfg(target_os = "linux")]
 pub mod library;
 #[cfg(target_os = "linux")]
 pub mod session;
 #[cfg(target_os = "linux")]
 pub mod trust;
 #[cfg(target_os = "linux")]
 pub mod video;
 pub mod wol;
@@ -35,6 +35,9 @@ pub struct SessionParams {
    /// Library id for the host to launch this session (`"steam:570"`, from the library
    /// page); `None` = plain desktop session.
    pub launch: Option<String>,
    /// The presenter's shared Vulkan device, when its stack can run FFmpeg's Vulkan
    /// Video decoder (decode lands as VkImages the presenter samples directly).
    pub vulkan: Option<crate::video::VulkanDecodeDevice>,
    /// Pinned host fingerprint; `None` = trust on first use (caller persists the observed one).
    pub pin: Option<[u8; 32]>,
    pub identity: (String, String),
@@ -71,7 +74,10 @@ pub struct Stats {
    /// `host + network`. An old host never emits 0xCF, so this stays false and the
    /// combined stage renders unchanged.
    pub split: bool,
-    /// p50 `decode` stage: received → decoded, single-clock client-local (ms).
+    /// p50 `decode` stage: received → decode COMPLETE, single-clock client-local (ms).
    /// Hardware paths measure GPU completion via the frame's timeline fence (an async
    /// decoder's submission returning in ~0.1 ms is not "decoded"); software measures
    /// the synchronous CPU decode.
    pub decode_ms: f32,
    /// Unrecoverable network frame drops this window, and their share of
    /// received+lost (%). The OSD renders the counter line only when nonzero.
@@ -82,6 +88,11 @@ pub struct Stats {
    pub decoder: &'static str,
 }
 /// Consecutive no-output AUs that force a keyframe request. ~50 ms at 60 Hz — long
 /// enough not to fire on a one-frame decoder hiccup, short enough that a lost initial
 /// IDR (or a mid-GOP join) unfreezes almost immediately instead of never.
 const NO_OUTPUT_KEYFRAME_STREAK: u32 = 3;
 /// Frames the pump keeps waiting for their 0xCF host timing (pts → capture→received µs).
 /// ~2 s at 120 Hz — a timing arrives within a frame or two of its AU, and against an old
 /// host (no 0xCF at all) this just caps the dead-weight ring.
@@ -120,6 +131,10 @@ pub struct SessionHandle {
    pub events: async_channel::Receiver<SessionEvent>,
    pub frames: async_channel::Receiver<DecodedFrame>,
    pub stop: Arc<AtomicBool>,
    /// The pump thread. A Vulkan-Video pump SUBMITS to the shared device's decode
    /// queue — the presenter must join this before any `vkDeviceWaitIdle`/teardown
    /// (external-sync rule over every device queue).
    pub thread: Option<std::thread::JoinHandle<()>>,
 }
 pub fn start(params: SessionParams) -> SessionHandle {
@@ -128,7 +143,7 @@ pub fn start(params: SessionParams) -> SessionHandle {
    let (frame_tx, frame_rx) = async_channel::bounded(2);
    let stop = Arc::new(AtomicBool::new(false));
    let stop_w = stop.clone();
-    std::thread::Builder::new()
+    let thread = std::thread::Builder::new()
        .name("punktfunk-session".into())
        .spawn(move || pump(params, ev_tx, frame_tx, stop_w))
        .expect("spawn session thread");
@@ -136,6 +151,7 @@ pub fn start(params: SessionParams) -> SessionHandle {
        events: ev_rx,
        frames: frame_rx,
        stop,
        thread: Some(thread),
    }
 }
@@ -195,7 +211,11 @@ fn pump(
        params.compositor,
        params.gamepad,
        params.bitrate_kbps,
-        0, // video_caps: the Linux client has no 10-bit/HDR present path yet
+        // 10-bit Main10 + PQ HDR10: the Vulkan presenter decodes P010 (Vulkan
        // Video/VAAPI/software) and presents PQ on an HDR10 swapchain where the desktop
        // offers one, tonemapping in the CSC shader where it doesn't. The host still
        // gates the upgrade behind its own PUNKTFUNK_10BIT policy.
        punktfunk_core::quic::VIDEO_CAP_10BIT | punktfunk_core::quic::VIDEO_CAP_HDR,
        params.audio_channels,
        crate::video::decodable_codecs(), // codecs FFmpeg can decode (HEVC/H.264/AV1)
        params.preferred_codec,           // the user's soft codec preference (0 = auto)
@@ -236,7 +256,7 @@ fn pump(
        welcome_codec = connector.codec,
        "negotiated video codec"
    );
-    let mut decoder = match Decoder::new(codec_id, &params.decoder) {
+    let mut decoder = match Decoder::new(codec_id, &params.decoder, params.vulkan.as_ref()) {
        Ok(d) => d,
        Err(e) => {
            let _ = ev_tx.send_blocking(SessionEvent::Ended(Some(format!("video decoder: {e}"))));
@@ -280,6 +300,13 @@ fn pump(
    // The stats window keeps its own drop cursor — the OSD shows the per-window delta.
    let mut window_dropped = last_dropped;
    let mut last_kf_req: Option<Instant> = None;
    // Consecutive received AUs that produced NO decoded frame (decode error, or the
    // decoder swallowed a reference-missing delta and returned nothing). Distinct from
    // `frames_dropped`, which counts reassembler drops: when the initial IDR is lost (or
    // we join mid-GOP) the reassembler delivers complete-but-undecodable deltas — it
    // never drops, so the drop-count trigger below stays silent and the stream freezes
    // on the last good frame. A short streak forces a fresh IDR to re-anchor.
    let mut no_output_streak = 0u32;
    let end: Option<String> = loop {
        if stop.load(Ordering::SeqCst) {
@@ -297,15 +324,18 @@ fn pump(
                bytes_n += frame.data.len() as u64;
                match decoder.decode(&frame.data) {
                    Ok(Some(image)) => {
                        no_output_streak = 0; // a decoded frame — the anchor holds
                        total_frames += 1;
                        dec_path = match &image {
                            DecodedImage::Cpu(_) => "software",
                            DecodedImage::Dmabuf(_) => "vaapi",
                            DecodedImage::VkFrame(_) => "vulkan",
                        };
                        if total_frames == 1 {
                            let (w, h, path) = match &image {
                                DecodedImage::Cpu(c) => (c.width, c.height, "software"),
                                DecodedImage::Dmabuf(d) => (d.width, d.height, "vaapi-dmabuf"),
                                DecodedImage::VkFrame(v) => (v.width, v.height, "vulkan-video"),
                            };
                            tracing::info!(width = w, height = h, path, "first frame decoded");
                        }
@@ -325,17 +355,57 @@ fn pump(
                            }
                            pending_split.push_back((frame.pts_ns, hn / 1000));
                        }
-                        // `decode` stage: received→decoded, single clock, no skew.
+                        // Ship the frame FIRST, then settle the decode stat: on the
-                        decode_us.push(decoded_ns.saturating_sub(received_ns) / 1000);
+                        // Vulkan path receive_frame returns at SUBMISSION (~0.1 ms) and
                        // the hardware decodes asynchronously — waiting the frame's
                        // timeline fence here (after the presenter already has the
                        // frame) measures true received→decode-complete at zero
                        // pipeline cost. Software/VAAPI keep the synchronous stamp.
                        let hw_fence = match &image {
                            DecodedImage::VkFrame(v) => Some((v.timeline_sem, v.decode_done_value)),
                            _ => None,
                        };
                        let _ = frame_tx.force_send(DecodedFrame {
                            pts_ns: frame.pts_ns,
                            decoded_ns,
                            image,
                        });
                        // `decode` stage: received→decode COMPLETE, single clock.
                        let decode_done_ns = match hw_fence {
                            Some((sem, value))
                                if decoder.wait_hw_decoded(sem, value, 50_000_000) =>
                            {
                                now_ns()
                            }
-                    Ok(None) => {}
+                            _ => decoded_ns,
                        };
                        decode_us.push(decode_done_ns.saturating_sub(received_ns) / 1000);
                    }
                    Ok(None) => no_output_streak += 1,
                    // Survivable (loss until the next IDR/RFI recovery) — keep feeding.
-                    Err(e) => tracing::debug!(error = %e, "decode error (recovering)"),
+                    Err(e) => {
                        no_output_streak += 1;
                        tracing::debug!(error = %e, "decode error (recovering)");
                    }
                }
                // The decoder has produced nothing for a short run — under zero-reorder
                // LOW_DELAY (one-in/one-out) that means it's wedged on missing references
                // with no reassembler drop to trigger recovery below. Ask for a fresh IDR
                // (throttled), then re-arm the streak so we wait out the request→IDR round
                // trip before asking again instead of flooding.
                if no_output_streak >= NO_OUTPUT_KEYFRAME_STREAK {
                    let now = Instant::now();
                    if last_kf_req
                        .is_none_or(|t| now.duration_since(t) >= Duration::from_millis(100))
                    {
                        last_kf_req = Some(now);
                        let _ = connector.request_keyframe();
                        tracing::debug!(
                            streak = no_output_streak,
                            "requested keyframe (decoder produced no output)"
                        );
                        no_output_streak = 0;
                    }
                }
                // The presenter's verdict: hardware frames can't be displayed (GL converter
                // init failed / dmabuf import rejected) — demote to software here, on the
@@ -168,6 +168,26 @@ pub fn learn_mac(fp_hex: &str, addr: &str, port: u16, mac: &[String]) {
    let _ = known.save();
 }
 /// Re-key a saved host's address/port after it rediscovered on a new DHCP lease (matched by
 /// fingerprint). No-op — and no disk write — when unchanged. Called from the wake-and-wait flow when
 /// a woken host reappears on a different IP than the stored one, so this and future connects dial the
 /// live address instead of the stale one.
 pub fn rekey_addr(fp_hex: &str, addr: &str, port: u16) {
    if fp_hex.is_empty() {
        return;
    }
    let mut known = KnownHosts::load();
    let Some(h) = known.hosts.iter_mut().find(|h| h.fp_hex == fp_hex) else {
        return;
    };
    if h.addr == addr && h.port == port {
        return;
    }
    h.addr = addr.to_string();
    h.port = port;
    let _ = known.save();
 }
 /// Stamp "now" as this host's last successful connect (drives the hosts page's
 /// most-recent accent). No-op when the fingerprint isn't stored.
 pub fn touch_last_used(fp_hex: &str) {
@@ -232,7 +252,8 @@ pub struct Settings {
    /// preference — the host honors it when it can emit it, else falls back to the best shared codec.
    #[serde(default = "default_codec")]
    pub codec: String,
-    /// Video decoder preference: `"auto"` (VAAPI → software), `"vaapi"`, `"software"`.
+    /// Video decoder preference: `"auto"` (Vulkan Video → VAAPI → software),
    /// `"vulkan"`, `"vaapi"`, `"software"`.
    /// The `PUNKTFUNK_DECODER` env var overrides this (see `video::Decoder::new`).
    pub decoder: String,
    /// Show the on-stream statistics overlay (toggle live with Ctrl+Alt+Shift+S).
@@ -1,15 +1,19 @@
-//! Video decode: reassembled HEVC access units → frames for the GTK presenter.
+//! Video decode: reassembled HEVC access units → frames for the presenter.
 //!
-//! Two backends, picked at session start (override: `PUNKTFUNK_DECODER=software|vaapi`):
+//! Three backends, picked at session start (auto: vulkan → vaapi → software;
 //! override: `PUNKTFUNK_DECODER=vulkan|vaapi|software`):
 //!
-//! * **VAAPI** (Intel/AMD): libavcodec hwaccel decodes on the GPU; each frame is mapped
+//! * **Vulkan Video**: FFmpeg's Vulkan decoder running on the PRESENTER's own VkDevice
-//!   to a DRM-PRIME dmabuf (`av_hwframe_map`, zero copy) and handed to the UI as fds +
+//!   (its handles arrive via [`VulkanDecodeDevice`]) — the decoded VkImage feeds the
-//!   plane layout for `GdkDmabufTextureBuilder` — inside `GtkGraphicsOffload` that is the
+//!   presenter's CSC pass directly, zero copy, every vendor with the video extensions
-//!   decoder-to-subsurface path, direct-scanout eligible when fullscreen. NVIDIA boxes
+//!   (NVIDIA's only hardware path; measured 4K@144 with 0.1 ms decode).
-//!   have no usable VAAPI (nvidia-vaapi-driver is broken for this — Moonlight blacklists
+//! * **VAAPI** (Intel/AMD fallback): libavcodec hwaccel; each frame is mapped to a
-//!   it); device creation fails there and the software path takes over. A mid-session
+//!   DRM-PRIME dmabuf (`av_hwframe_map`, zero copy) and handed over as fds + plane
-//!   VAAPI error also falls back — the host's IDR/RFI recovery resynchronizes.
+//!   layout for the presenter's Vulkan import. NVIDIA has no usable VAAPI
-//! * **Software**: libavcodec on the CPU + swscale to RGBA (`GdkMemoryTexture` upload).
+//!   (nvidia-vaapi-driver is broken for this — Moonlight blacklists it); device
 //!   creation fails there. A mid-session error falls back — the host's IDR/RFI
 //!   recovery resynchronizes.
 //! * **Software**: libavcodec on the CPU + swscale to RGBA (staging upload).
 //!   Slice threading only — frame threading would add a frame of latency per thread.
 //!
 //! Both run `AV_CODEC_FLAG_LOW_DELAY`; the host encodes zero-reorder streams (no
@@ -39,6 +43,44 @@ pub struct DecodedFrame {
 pub enum DecodedImage {
    Cpu(CpuFrame),
    Dmabuf(DmabufFrame),
    /// FFmpeg Vulkan Video output: a VkImage already on the PRESENTER's device.
    VkFrame(VkVideoFrame),
 }
 /// One Vulkan-decoded frame. The image lives on the presenter's own VkDevice (the
 /// decoder was built over its handles), so presenting is: plane views → CSC pass — no
 /// import, no copy. The live synchronization state (layout / timeline value / owning
 /// queue family) is deliberately NOT snapshotted here: FFmpeg updates it per submission,
 /// so the presenter reads it through `vkframe` under the frames-context lock at ITS
 /// submit time (the `AVVulkanFramesContext.lock_frame` contract).
 pub struct VkVideoFrame {
    /// `AVVkFrame*` — img[0] is the (multiplanar) image; sem/sem_value/layout/
    /// queue_family are the live sync state. Valid while `guard` lives.
    pub vkframe: usize,
    /// `AVHWFramesContext*` (FFmpeg's) — the first argument to the lock functions.
    /// Valid while `guard` lives.
    pub frames_ctx: usize,
    /// `AVVulkanFramesContext.lock_frame` / `.unlock_frame` (filled in by FFmpeg's
    /// init): the presenter MUST hold the lock while reading the live sync state and
    /// writing back the incremented semaphore value around its submission.
    pub lock_frame: usize,
    pub unlock_frame: usize,
    /// The frame pool's VkFormat (`AVVulkanFramesContext.format[0]`, raw i32) — the
    /// multiplanar format the presenter builds its per-plane views against.
    pub vk_format: i32,
    /// The frame's timeline semaphore (raw VkSemaphore; creation-constant) and the
    /// value FFmpeg's decode submission signals on completion — the pump waits this
    /// pair AFTER shipping the frame to measure true GPU decode time (zero pipeline
    /// cost: the presenter already waits the same pair on the GPU).
    pub timeline_sem: u64,
    pub decode_done_value: u64,
    pub width: u32,
    pub height: u32,
    pub color: ColorDesc,
    /// Keeps the cloned AVFrame (and through it the VkImage + frames context) alive
    /// until the presenter's fence proves the GPU reads done — same mechanism as the
    /// VAAPI path's DRM guard.
    pub guard: DrmFrameGuard,
 }
 /// The stream's colour signaling, read PER-FRAME from the decoder (HEVC VUI → the
@@ -127,6 +169,7 @@ impl Drop for DrmFrameGuard {
 }
 enum Backend {
    Vulkan(VulkanDecoder),
    Vaapi(VaapiDecoder),
    Software(SoftwareDecoder),
 }
@@ -136,8 +179,9 @@ pub struct Decoder {
    /// The negotiated codec (from the host's Welcome), so a mid-session VAAPI→software demotion
    /// rebuilds the software decoder for the SAME codec.
    codec_id: ffmpeg::codec::Id,
-    /// Consecutive VAAPI decode errors — a single transient failure (e.g. a reference-missing
+    /// Consecutive hardware decode errors (Vulkan or VAAPI) — a single transient failure
-    /// frame after packet loss) shouldn't cost the whole session its hardware decoder.
+    /// (e.g. a reference-missing frame after packet loss) shouldn't cost the whole
    /// session its hardware decoder.
    vaapi_fails: u32,
    /// Set when the decoder needs a fresh IDR to resynchronize (after an error or a demotion).
    /// The pump drains it and asks the host — under the infinite GOP there is no periodic
@@ -175,34 +219,87 @@ pub fn decodable_codecs() -> u8 {
    bits
 }
 /// libavcodec logs reference-frame recovery to the process stderr very verbosely
 /// (`First slice in a frame missing`, `Could not find ref with POC …`, `Error
 /// constructing the frame RPS`) — normal chatter while the decoder waits for a keyframe
 /// after loss, but a raw flood in the user's terminal (it bypasses our tracing). Default
 /// it to fatal-only; `PUNKTFUNK_FFMPEG_LOG=<quiet|error|warning|info|debug>` restores it
 /// for decode debugging. Process-global; set once per decoder build (idempotent).
 fn quiet_ffmpeg_log() {
    use ffmpeg::util::log::Level;
    let level = match std::env::var("PUNKTFUNK_FFMPEG_LOG").ok().as_deref() {
        Some("quiet") => Level::Quiet,
        Some("error") => Level::Error,
        Some("warning") => Level::Warning,
        Some("info") => Level::Info,
        Some("debug" | "trace") => Level::Debug,
        _ => Level::Fatal,
    };
    ffmpeg::util::log::set_level(level);
 }
 impl Decoder {
    /// `codec_id` is the codec the host resolved in the Welcome (never assume HEVC).
-    /// `pref` is the Settings "Video decoder" value (`auto`/`vaapi`/`software`).
+    /// `pref` is the Settings "Video decoder" value (`auto`/`vulkan`/`vaapi`/`software`).
    /// `vk` is the presenter's shared Vulkan device when its stack can run FFmpeg's
    /// Vulkan Video decoder — decode lands as VkImages the presenter samples directly.
    /// Precedence: the `PUNKTFUNK_DECODER` env override wins (support/debug escape
    /// hatch, and the documented knob), then the setting; both default to auto
-    /// (VAAPI → software).
+    /// (Vulkan → VAAPI → software).
-    pub fn new(codec_id: ffmpeg::codec::Id, pref: &str) -> Result<Decoder> {
+    pub fn new(
        codec_id: ffmpeg::codec::Id,
        pref: &str,
        vk: Option<&VulkanDecodeDevice>,
    ) -> Result<Decoder> {
        ffmpeg::init().context("ffmpeg init")?;
        quiet_ffmpeg_log();
        let choice = std::env::var("PUNKTFUNK_DECODER")
            .ok()
            .filter(|v| !v.is_empty())
            .unwrap_or_else(|| pref.to_string());
-        // Deck note: `auto` means VAAPI here too. GTK's tiled-NV12 dmabuf import is broken on
+        let done = |backend| {
-        // the Deck (Mesa ≥ 25.1 exports VCN surfaces TILED; artifacts/gray/washed-out), but the
+            Ok(Decoder {
-        // presenter routes Deck frames through the in-process GL converter (`video_gl`) instead
+                backend,
        // of GdkDmabufTexture — and if THAT can't initialize, it demotes this decoder to
        // software mid-session via [`Decoder::force_software`]. The broken direct path is never
        // the fallback.
        if choice != "software" {
            match VaapiDecoder::new(codec_id) {
                Ok(v) => {
                    tracing::info!(?codec_id, "VAAPI hardware decode active (zero-copy dmabuf)");
                    return Ok(Decoder {
                        backend: Backend::Vaapi(v),
                codec_id,
                vaapi_fails: 0,
                want_keyframe: false,
-                    });
+            })
        };
        if matches!(choice.as_str(), "auto" | "" | "vulkan") {
            match vk {
                Some(vk) => match VulkanDecoder::new(codec_id, vk) {
                    Ok(v) => {
                        tracing::info!(
                            ?codec_id,
                            "Vulkan Video hardware decode active (presenter-shared device)"
                        );
                        return done(Backend::Vulkan(v));
                    }
                    Err(e) => {
                        if choice == "vulkan" {
                            return Err(e.context("PUNKTFUNK_DECODER=vulkan but it failed"));
                        }
                        tracing::info!(reason = %format!("{e:#}"),
                            "Vulkan Video unavailable — trying VAAPI");
                    }
                },
                None if choice == "vulkan" => {
                    bail!(
                        "PUNKTFUNK_DECODER=vulkan but the presenter's device can't (missing \
                           video extensions/queue) — see the presenter log"
                    )
                }
                None => {}
            }
        }
        // Deck note: `auto` reaches VAAPI when Vulkan Video isn't available. A presenter
        // that can't display the dmabufs demotes this decoder to software mid-session
        // via [`Decoder::force_software`].
        if choice != "software" && choice != "vulkan" {
            match VaapiDecoder::new(codec_id) {
                Ok(v) => {
                    tracing::info!(?codec_id, "VAAPI hardware decode active (zero-copy dmabuf)");
                    return done(Backend::Vaapi(v));
                }
                Err(e) => {
                    if choice == "vaapi" {
@@ -212,12 +309,25 @@ impl Decoder {
                }
            }
        }
-        Ok(Decoder {
+        if choice == "software" {
-            backend: Backend::Software(SoftwareDecoder::new(codec_id)?),
+            // Say WHY hardware wasn't even attempted — a stored "software" preference
-            codec_id,
+            // (or the env override) silently skipping vulkan/vaapi has burned real
-            vaapi_fails: 0,
+            // debugging time on boxes that could do better.
-            want_keyframe: false,
+            tracing::info!(
-        })
+                "software decode by preference (Settings decoder / PUNKTFUNK_DECODER) — \
                 hardware decode not attempted"
            );
        }
        done(Backend::Software(SoftwareDecoder::new(codec_id)?))
    }
    /// Wait for a Vulkan-Video frame's GPU decode to complete (timeline semaphore) —
    /// the pump's decode-stat measurement. `false` = not the Vulkan backend, or timeout.
    pub fn wait_hw_decoded(&self, timeline_sem: u64, value: u64, timeout_ns: u64) -> bool {
        match &self.backend {
            Backend::Vulkan(v) => v.wait_timeline(timeline_sem, value, timeout_ns),
            _ => false,
        }
    }
    /// Drain the "please ask the host for an IDR" flag — the pump calls this each iteration
@@ -249,28 +359,34 @@ impl Decoder {
    /// pump asks the host for a fresh IDR — under the infinite GOP nothing else resyncs a
    /// rebuilt/erroring decoder, so skipping this leaves the picture gray/frozen for good.
    pub fn decode(&mut self, au: &[u8]) -> Result<Option<DecodedImage>> {
-        match &mut self.backend {
+        let result = match &mut self.backend {
-            Backend::Vaapi(v) => match v.decode(au) {
+            Backend::Vulkan(v) => v.decode(au).map(|f| f.map(DecodedImage::VkFrame)),
            Backend::Vaapi(v) => v.decode(au).map(|f| f.map(DecodedImage::Dmabuf)),
            Backend::Software(s) => return Ok(s.decode(au)?.map(DecodedImage::Cpu)),
        };
        match result {
            Ok(f) => {
                self.vaapi_fails = 0;
-                    Ok(f.map(DecodedImage::Dmabuf))
+                Ok(f)
            }
            Err(e) => {
                let which = match self.backend {
                    Backend::Vulkan(_) => "Vulkan Video",
                    _ => "VAAPI",
                };
                self.vaapi_fails += 1;
                self.want_keyframe = true;
                if self.vaapi_fails >= VAAPI_DEMOTE_AFTER {
                    tracing::warn!(error = %e, fails = self.vaapi_fails,
-                            "VAAPI decode failing repeatedly — demoting to software");
+                        "{which} decode failing repeatedly — demoting to software");
                    self.backend = Backend::Software(SoftwareDecoder::new(self.codec_id)?);
                    self.vaapi_fails = 0;
                } else {
                    tracing::warn!(error = %e,
-                            "VAAPI decode error — requesting keyframe, keeping hardware decode");
+                        "{which} decode error — requesting keyframe, keeping hardware decode");
                }
                Ok(None)
            }
            },
            Backend::Software(s) => Ok(s.decode(au)?.map(DecodedImage::Cpu)),
        }
    }
 }
@@ -608,6 +724,39 @@ impl VaapiDecoder {
    }
 }
 /// The presenter's Vulkan device handles, exported so FFmpeg's Vulkan Video decoder
 /// runs on the SAME device the presenter samples from — the whole point: the decoded
 /// VkImage is composited directly, no interop, no copy (plan: Vulkan Video phase).
 ///
 /// Plain integers/strings on purpose: pf-client-core has no ash dependency; pf-ffvk
 /// casts these into vulkan.h handle types when filling `AVVulkanDeviceContext`. All
 /// handles stay valid for the presenter's lifetime, which outlives every session pump
 /// (the run loop tears the pump down before the presenter).
 #[derive(Clone)]
 pub struct VulkanDecodeDevice {
    /// `PFN_vkGetInstanceProcAddr` from the loader — FFmpeg resolves everything else.
    pub get_instance_proc_addr: usize,
    pub instance: usize,
    pub physical_device: usize,
    pub device: usize,
    /// The presenter's graphics+present family (FFmpeg's "required" tx/comp family too).
    pub graphics_qf: u32,
    /// Raw `VkQueueFlags` of that family (the qf[] entry wants the real capabilities).
    pub graphics_queue_flags: u32,
    /// The video-decode family (may equal `graphics_qf` on some hardware).
    pub decode_qf: u32,
    /// Raw `VkVideoCodecOperationFlagsKHR` the decode family advertises.
    pub decode_video_caps: u32,
    /// Everything enabled at instance/device creation — FFmpeg keys code paths off the
    /// extension STRINGS, so the lists must match reality exactly.
    pub instance_extensions: Vec<std::ffi::CString>,
    pub device_extensions: Vec<std::ffi::CString>,
    /// Features enabled at device creation (reported via `device_features`).
    pub f_sampler_ycbcr: bool,
    pub f_timeline_semaphore: bool,
    pub f_synchronization2: bool,
 }
 /// `fourcc(a,b,c,d)` — the DRM FourCC packing (little-endian, `a | b<<8 | c<<16 | d<<24`).
 const fn fourcc(a: u8, b: u8, c: u8, d: u8) -> u32 {
    (a as u32) | ((b as u32) << 8) | ((c as u32) << 16) | ((d as u32) << 24)
@@ -664,6 +813,365 @@ impl Drop for VaapiDecoder {
    }
 }
 // --- Vulkan Video backend -------------------------------------------------------------
 /// FFmpeg's Vulkan Video decoder over the PRESENTER's device: the hwdevice context is
 /// built from [`VulkanDecodeDevice`]'s handles (not `av_hwdevice_ctx_create`, which
 /// would make FFmpeg create its own device the presenter can't sample from). Output
 /// frames are `AVVkFrame`s whose VkImage the presenter feeds straight to its CSC pass.
 struct VulkanDecoder {
    ctx: *mut ffmpeg::ffi::AVCodecContext,
    hw_device: *mut ffmpeg::ffi::AVBufferRef,
    packet: *mut ffmpeg::ffi::AVPacket,
    frame: *mut ffmpeg::ffi::AVFrame,
    /// `vkWaitSemaphores` on the shared device — the decode-complete measurement
    /// (resolved through the same get_proc_addr chain FFmpeg uses).
    wait_semaphores: pf_ffvk::PFN_vkWaitSemaphores,
    vk_device: pf_ffvk::VkDevice,
    /// Storage `AVVulkanDeviceContext` points into (extension string arrays + the
    /// feature chain) — FFmpeg reads the extension lists past init (frames-context
    /// setup keys code paths off them), so this lives exactly as long as `hw_device`.
    _ctx_storage: Box<VkCtxStorage>,
 }
 // Single-owner pointers, only touched from the session pump thread.
 unsafe impl Send for VulkanDecoder {}
 struct VkCtxStorage {
    _inst: Vec<std::ffi::CString>,
    inst_ptrs: Vec<*const std::os::raw::c_char>,
    _dev: Vec<std::ffi::CString>,
    dev_ptrs: Vec<*const std::os::raw::c_char>,
    f11: pf_ffvk::VkPhysicalDeviceVulkan11Features,
    f12: pf_ffvk::VkPhysicalDeviceVulkan12Features,
    f13: pf_ffvk::VkPhysicalDeviceVulkan13Features,
 }
 impl VulkanDecoder {
    fn new(codec_id: ffmpeg::codec::Id, vk: &VulkanDecodeDevice) -> Result<VulkanDecoder> {
        use ffmpeg::ffi;
        unsafe {
            let mut hw_device =
                ffi::av_hwdevice_ctx_alloc(ffi::AVHWDeviceType::AV_HWDEVICE_TYPE_VULKAN);
            if hw_device.is_null() {
                bail!("av_hwdevice_ctx_alloc(VULKAN) failed (FFmpeg built without Vulkan?)");
            }
            let devctx = (*hw_device).data as *mut ffi::AVHWDeviceContext;
            let hwctx = (*devctx).hwctx as *mut pf_ffvk::AVVulkanDeviceContext;
            // Pinned storage for everything the context points into.
            let mut store = Box::new(VkCtxStorage {
                _inst: vk.instance_extensions.clone(),
                inst_ptrs: Vec::new(),
                _dev: vk.device_extensions.clone(),
                dev_ptrs: Vec::new(),
                f11: std::mem::zeroed(),
                f12: std::mem::zeroed(),
                f13: std::mem::zeroed(),
            });
            store.inst_ptrs = store._inst.iter().map(|c| c.as_ptr()).collect();
            store.dev_ptrs = store._dev.iter().map(|c| c.as_ptr()).collect();
            // The features enabled at device creation, as the 1.1/1.2/1.3 chain FFmpeg
            // walks to learn what it may use (sType values are vulkan.h constants).
            store.f11.sType =
                pf_ffvk::VkStructureType_VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_1_FEATURES;
            store.f11.samplerYcbcrConversion = vk.f_sampler_ycbcr as u32;
            store.f12.sType =
                pf_ffvk::VkStructureType_VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_2_FEATURES;
            store.f12.timelineSemaphore = vk.f_timeline_semaphore as u32;
            store.f13.sType =
                pf_ffvk::VkStructureType_VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_3_FEATURES;
            store.f13.synchronization2 = vk.f_synchronization2 as u32;
            store.f11.pNext = &mut store.f12 as *mut _ as *mut std::ffi::c_void;
            store.f12.pNext = &mut store.f13 as *mut _ as *mut std::ffi::c_void;
            (*hwctx).get_proc_addr = std::mem::transmute::<usize, pf_ffvk::PFN_vkGetInstanceProcAddr>(
                vk.get_instance_proc_addr,
            );
            (*hwctx).inst = vk.instance as pf_ffvk::VkInstance;
            (*hwctx).phys_dev = vk.physical_device as pf_ffvk::VkPhysicalDevice;
            (*hwctx).act_dev = vk.device as pf_ffvk::VkDevice;
            (*hwctx).device_features.sType =
                pf_ffvk::VkStructureType_VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2;
            (*hwctx).device_features.pNext = &mut store.f11 as *mut _ as *mut std::ffi::c_void;
            (*hwctx).enabled_inst_extensions = store.inst_ptrs.as_ptr();
            (*hwctx).nb_enabled_inst_extensions = store.inst_ptrs.len() as i32;
            (*hwctx).enabled_dev_extensions = store.dev_ptrs.as_ptr();
            (*hwctx).nb_enabled_dev_extensions = store.dev_ptrs.len() as i32;
            // Queue map: the deprecated per-role indices (tx/comp are "Required") plus
            // the qf[] list, which per the header must also carry every family named
            // above. One merged entry when decode shares the graphics family.
            let g = vk.graphics_qf as i32;
            let d = vk.decode_qf as i32;
            (*hwctx).queue_family_index = g;
            (*hwctx).nb_graphics_queues = 1;
            (*hwctx).queue_family_tx_index = g;
            (*hwctx).nb_tx_queues = 1;
            (*hwctx).queue_family_comp_index = g;
            (*hwctx).nb_comp_queues = 1;
            (*hwctx).queue_family_encode_index = -1;
            (*hwctx).nb_encode_queues = 0;
            (*hwctx).queue_family_decode_index = d;
            (*hwctx).nb_decode_queues = 1;
            const VIDEO_DECODE_BIT: u32 = 0x20; // VK_QUEUE_VIDEO_DECODE_BIT_KHR
            if g == d {
                (*hwctx).qf[0] = pf_ffvk::AVVulkanDeviceQueueFamily {
                    idx: g,
                    num: 1,
                    flags: vk.graphics_queue_flags | VIDEO_DECODE_BIT,
                    video_caps: vk.decode_video_caps,
                };
                (*hwctx).nb_qf = 1;
            } else {
                (*hwctx).qf[0] = pf_ffvk::AVVulkanDeviceQueueFamily {
                    idx: g,
                    num: 1,
                    flags: vk.graphics_queue_flags,
                    video_caps: 0,
                };
                (*hwctx).qf[1] = pf_ffvk::AVVulkanDeviceQueueFamily {
                    idx: d,
                    num: 1,
                    flags: VIDEO_DECODE_BIT,
                    video_caps: vk.decode_video_caps,
                };
                (*hwctx).nb_qf = 2;
            }
            let r = ffi::av_hwdevice_ctx_init(hw_device);
            if r < 0 {
                ffi::av_buffer_unref(&mut hw_device);
                return Err(averr("av_hwdevice_ctx_init(VULKAN)", r));
            }
            // vkWaitSemaphores for the pump's decode-complete stat: loader →
            // vkGetDeviceProcAddr → device fn (core 1.2, guaranteed by our gate).
            let gipa = (*hwctx)
                .get_proc_addr
                .expect("get_proc_addr was just set above");
            let gdpa: pf_ffvk::PFN_vkGetDeviceProcAddr =
                std::mem::transmute(gipa((*hwctx).inst, c"vkGetDeviceProcAddr".as_ptr()));
            let wait_semaphores: pf_ffvk::PFN_vkWaitSemaphores = std::mem::transmute(gdpa
                .expect("vkGetDeviceProcAddr resolvable")(
                (*hwctx).act_dev,
                c"vkWaitSemaphores".as_ptr(),
            ));
            if wait_semaphores.is_none() {
                ffi::av_buffer_unref(&mut hw_device);
                bail!("vkWaitSemaphores unresolvable on this device");
            }
            let vk_device = (*hwctx).act_dev;
            let codec = ffi::avcodec_find_decoder(codec_id.into());
            if codec.is_null() {
                ffi::av_buffer_unref(&mut hw_device);
                bail!("no {codec_id:?} decoder");
            }
            let ctx = ffi::avcodec_alloc_context3(codec);
            (*ctx).hw_device_ctx = ffi::av_buffer_ref(hw_device);
            (*ctx).get_format = Some(pick_vulkan);
            (*ctx).flags |= ffi::AV_CODEC_FLAG_LOW_DELAY as i32;
            (*ctx).thread_count = 1; // hwaccel: threads only add latency
                                     // Same pool headroom rationale as VAAPI: the presenter pins the on-screen
                                     // frame + the newest in flight past receive_frame.
            (*ctx).extra_hw_frames = 4;
            let r = ffi::avcodec_open2(ctx, codec, ptr::null_mut());
            if r < 0 {
                let mut ctx = ctx;
                ffi::avcodec_free_context(&mut ctx);
                ffi::av_buffer_unref(&mut hw_device);
                return Err(averr("avcodec_open2 (vulkan)", r));
            }
            Ok(VulkanDecoder {
                ctx,
                hw_device,
                packet: ffi::av_packet_alloc(),
                frame: ffi::av_frame_alloc(),
                wait_semaphores,
                vk_device,
                _ctx_storage: store,
            })
        }
    }
    fn decode(&mut self, au: &[u8]) -> Result<Option<VkVideoFrame>> {
        use ffmpeg::ffi;
        unsafe {
            let r = ffi::av_new_packet(self.packet, au.len() as i32);
            if r < 0 {
                return Err(averr("av_new_packet", r));
            }
            ptr::copy_nonoverlapping(au.as_ptr(), (*self.packet).data, au.len());
            let r = ffi::avcodec_send_packet(self.ctx, self.packet);
            ffi::av_packet_unref(self.packet);
            if r < 0 {
                return Err(averr("send_packet", r));
            }
            let mut out = None;
            loop {
                let r = ffi::avcodec_receive_frame(self.ctx, self.frame);
                if r == AVERROR_EAGAIN {
                    break;
                }
                if r < 0 {
                    return Err(averr("receive_frame", r));
                }
                out = Some(self.extract()?); // newest wins; older guards drop here
                ffi::av_frame_unref(self.frame);
            }
            Ok(out)
        }
    }
    /// Block until the timeline semaphore reaches `value` (GPU decode complete) or the
    /// timeout passes. Pure measurement — the presenter's own GPU wait is what gates
    /// sampling, so a timeout here only degrades the stat, never the picture.
    fn wait_timeline(&self, sem: u64, value: u64, timeout_ns: u64) -> bool {
        let sems = [sem as pf_ffvk::VkSemaphore];
        let values = [value];
        let info = pf_ffvk::VkSemaphoreWaitInfo {
            sType: pf_ffvk::VkStructureType_VK_STRUCTURE_TYPE_SEMAPHORE_WAIT_INFO,
            pNext: std::ptr::null(),
            flags: 0,
            semaphoreCount: 1,
            pSemaphores: sems.as_ptr(),
            pValues: values.as_ptr(),
        };
        // SAFETY: resolved from this device at init; handles outlive the decoder.
        let r = unsafe {
            self.wait_semaphores.expect("checked at init")(self.vk_device, &info, timeout_ns)
        };
        r == 0 // VK_SUCCESS (VK_TIMEOUT = 2)
    }
    /// Lift the decoded `AVVkFrame` into a [`VkVideoFrame`]: clone the AVFrame (the
    /// guard — keeps the image + frames context alive through present) and ship the
    /// POINTERS; the presenter reads the live sync state under the frames-context lock
    /// at its own submit time.
    unsafe fn extract(&mut self) -> Result<VkVideoFrame> {
        use ffmpeg::ffi;
        unsafe {
            if (*self.frame).format != ffi::AVPixelFormat::AV_PIX_FMT_VULKAN as i32 {
                bail!("decoder returned a non-Vulkan frame");
            }
            let hwfc_ref = (*self.frame).hw_frames_ctx;
            if hwfc_ref.is_null() {
                bail!("Vulkan frame without a hardware frames context");
            }
            let fc = (*hwfc_ref).data as *mut ffi::AVHWFramesContext;
            let sw = (*fc).sw_format;
            if sw != ffi::AVPixelFormat::AV_PIX_FMT_NV12
                && sw != ffi::AVPixelFormat::AV_PIX_FMT_P010LE
            {
                bail!("Vulkan decode output {sw:?} unsupported (NV12/P010 only)");
            }
            let vkfc = (*fc).hwctx as *const pf_ffvk::AVVulkanFramesContext;
            let vk_format = (*vkfc).format[0] as i32;
            let lock_frame = (*vkfc).lock_frame.map_or(0, |f| f as usize);
            let unlock_frame = (*vkfc).unlock_frame.map_or(0, |f| f as usize);
            if lock_frame == 0 || unlock_frame == 0 {
                bail!("Vulkan frames context without lock functions");
            }
            let clone = ffi::av_frame_clone(self.frame);
            if clone.is_null() {
                bail!("av_frame_clone failed");
            }
            let vkf = (*clone).data[0] as *mut pf_ffvk::AVVkFrame;
            // v1 handles the (default) single multiplanar image; a disjoint/multi-image
            // pool would need per-plane images — bail so the session demotes cleanly.
            if !(*vkf).img[1].is_null() {
                let mut clone = clone;
                ffi::av_frame_free(&mut clone);
                bail!("multi-image Vulkan frames unsupported (disjoint pool)");
            }
            // Safe without the frames lock: the handle is creation-constant and
            // sem_value was last written by the decode submission on THIS thread.
            let timeline_sem = (*vkf).sem[0] as u64;
            let decode_done_value = (*vkf).sem_value[0];
            Ok(VkVideoFrame {
                vkframe: vkf as usize,
                frames_ctx: fc as usize,
                lock_frame,
                unlock_frame,
                vk_format,
                timeline_sem,
                decode_done_value,
                width: (*self.frame).width as u32,
                height: (*self.frame).height as u32,
                color: ColorDesc::from_raw(self.frame),
                guard: DrmFrameGuard(clone),
            })
        }
    }
 }
 impl Drop for VulkanDecoder {
    fn drop(&mut self) {
        use ffmpeg::ffi;
        unsafe {
            ffi::av_packet_free(&mut self.packet);
            ffi::av_frame_free(&mut self.frame);
            ffi::avcodec_free_context(&mut self.ctx);
            ffi::av_buffer_unref(&mut self.hw_device);
        }
    }
 }
 /// libavcodec offers the formats it can decode into; pick the Vulkan hw surface and
 /// hand the decoder OUR frames context — the default one lacks
 /// `VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT`, without which the presenter can't create the
 /// per-plane views its CSC pass samples. Returning NONE (over the software entry) keeps
 /// failures loud: the session demotes explicitly instead of silently CPU-decoding.
 unsafe extern "C" fn pick_vulkan(
    ctx: *mut ffmpeg::ffi::AVCodecContext,
    mut list: *const ffmpeg::ffi::AVPixelFormat,
 ) -> ffmpeg::ffi::AVPixelFormat {
    use ffmpeg::ffi;
    unsafe {
        let mut offered = false;
        while *list != ffi::AVPixelFormat::AV_PIX_FMT_NONE {
            if *list == ffi::AVPixelFormat::AV_PIX_FMT_VULKAN {
                offered = true;
                break;
            }
            list = list.add(1);
        }
        if !offered {
            return ffi::AVPixelFormat::AV_PIX_FMT_NONE;
        }
        let mut fr: *mut ffi::AVBufferRef = ptr::null_mut();
        let r = ffi::avcodec_get_hw_frames_parameters(
            ctx,
            (*ctx).hw_device_ctx,
            ffi::AVPixelFormat::AV_PIX_FMT_VULKAN,
            &mut fr,
        );
        if r < 0 || fr.is_null() {
            tracing::warn!("avcodec_get_hw_frames_parameters(VULKAN) failed ({r})");
            return ffi::AVPixelFormat::AV_PIX_FMT_NONE;
        }
        let fc = (*fr).data as *mut ffi::AVHWFramesContext;
        let vkfc = (*fc).hwctx as *mut pf_ffvk::AVVulkanFramesContext;
        // MUTABLE_FORMAT: per-plane views (spec requirement); ALIAS is FFmpeg's default.
        (*vkfc).img_flags = pf_ffvk::VkImageCreateFlagBits_VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
            | pf_ffvk::VkImageCreateFlagBits_VK_IMAGE_CREATE_ALIAS_BIT;
        let r = ffi::av_hwframe_ctx_init(fr);
        if r < 0 {
            tracing::warn!("av_hwframe_ctx_init(VULKAN) failed ({r})");
            let mut fr = fr;
            ffi::av_buffer_unref(&mut fr);
            return ffi::AVPixelFormat::AV_PIX_FMT_NONE;
        }
        if !(*ctx).hw_frames_ctx.is_null() {
            ffi::av_buffer_unref(&mut (*ctx).hw_frames_ctx);
        }
        (*ctx).hw_frames_ctx = fr; // the codec owns our ref now
        ffi::AVPixelFormat::AV_PIX_FMT_VULKAN
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
@@ -0,0 +1,24 @@
 [package]
 name = "pf-console-ui"
 description = "The Skia console UI for the Vulkan session binary — stats OSD, capture HUD, and (next) the gamepad library; renders on the presenter's device via the Overlay contract"
 version.workspace = true
 edition.workspace = true
 rust-version.workspace = true
 license.workspace = true
 authors.workspace = true
 repository.workspace = true
 [target.'cfg(target_os = "linux")'.dependencies]
 pf-presenter = { path = "../pf-presenter" }
 # MenuEvent/MenuPulse (the gamepad service's menu mode drives the library).
 pf-client-core = { path = "../pf-client-core" }
 # Skia on the presenter's VkDevice (`vulkan`); `textlayout` = skparagraph/harfbuzz for
 # the typography the console library needs (~15 MB stripped, prebuilt binaries exist for
 # this feature set on x86_64-unknown-linux-gnu — a source build is never triggered).
 skia-safe = { version = "0.87", features = ["vulkan", "textlayout"] }
 ash = { version = "0.38", features = ["loaded"] }
 sdl3 = { version = "0.18", features = ["hidapi", "ash"] }
 anyhow = "1"
 tracing = "0.1"
@@ -0,0 +1,21 @@
 //! The Skia console UI (punktfunk-planning `linux-client-rearchitecture.md` §6): an
 //! [`Overlay`] implementation rendering on the PRESENTER's Vulkan device into offscreen
 //! RGBA images the presenter composites as one premultiplied quad. Skia never touches
 //! the swapchain, and nothing here runs while the overlay has nothing to show — the
 //! §6.1 invariants live or die in this crate.
 //!
 //! Milestone 1 (this file): the stats OSD panel + the capture-hint pill — small on
 //! purpose, it proves the whole shared-device pipeline. The gamepad library moves in
 //! next.
 #[cfg(target_os = "linux")]
 pub mod library;
 #[cfg(target_os = "linux")]
 mod library_ui;
 #[cfg(target_os = "linux")]
 mod skia_overlay;
 #[cfg(target_os = "linux")]
 pub use library::{LibraryGame, LibraryPhase, LibraryShared};
 #[cfg(target_os = "linux")]
 pub use skia_overlay::SkiaOverlay;
@@ -0,0 +1,493 @@
 //! The console library's model and math — everything about the coverflow that isn't
 //! Skia: the shared binary↔overlay state (games, phase, incoming art bytes), the
 //! spring-driven motion and cursor arithmetic (ported verbatim from the GTK launcher,
 //! tests included), and the geometry constants. Rendering lives in `skia_overlay`.
 use std::collections::VecDeque;
 use std::sync::{Arc, Mutex};
 // --- Geometry (the GTK launcher's constants — Apple coverflow parity) --------------------
 /// Poster geometry: 2:3 covers, sized so the focused poster + detail panel + hint bar
 /// fit a Deck's 1280×800 with air. Scaled uniformly for other window sizes.
 pub const POSTER_W: f64 = 220.0;
 pub const POSTER_H: f64 = 330.0;
 /// Center of the focused card to the center of its first neighbor.
 pub const FOCUS_GAP: f64 = 230.0;
 /// Center-to-center distance between successive SIDE cards — much tighter than their
 /// projected width, so the side stacks overlap like the classic coverflow shelf.
 pub const SIDE_SPACING: f64 = 104.0;
 /// Cards farther than this from the eased position aren't drawn at all.
 pub const VISIBLE_RANGE: f64 = 5.5;
 /// Neighbors recede to this scale…
 pub const RECEDE_SCALE: f64 = 0.24;
 /// …and swing this many degrees about their own vertical axis under perspective, side
 /// cards facing the corridor (their inner edge recedes behind the focus).
 pub const ROTATE_DEG: f64 = 38.0;
 /// Perspective depth for the tilt, px (CSS `perspective()` semantics).
 pub const PERSPECTIVE: f64 = 800.0;
 /// The darkening veil's max opacity (side cards stay opaque — they overlap).
 pub const RECEDE_DIM: f64 = 0.30;
 /// Boundary recoil: a refused move deflects the strip this many px against the push.
 pub const BUMP_PX: f64 = 16.0;
 /// L1/R1 jump distance.
 pub const JUMP: i32 = 5;
 // The motion is spring-driven (semi-implicit Euler), not eased — velocity carries across
 // retargets, so holding a direction glides and a release settles like a detent.
 /// Cursor chase: ζ ≈ 0.85 — settles in ~0.3 s with a whisker of overshoot.
 pub const SPRING_K: f64 = 200.0;
 pub const SPRING_C: f64 = 24.0;
 /// Boundary recoil: stiffer and more underdamped (ζ ≈ 0.55) — one visible wobble.
 pub const BUMP_K: f64 = 600.0;
 pub const BUMP_C: f64 = 27.0;
 /// One semi-implicit-Euler step of a damped spring toward `target`.
 fn spring_step(pos: f64, vel: f64, target: f64, k: f64, c: f64, dt: f64) -> (f64, f64) {
    let vel = vel + (k * (target - pos) - c * vel) * dt;
    (pos + vel * dt, vel)
 }
 /// Advance a damped spring by a whole frame, integrating in ≤ 8 ms substeps — a stalled
 /// frame stays far inside the integrator's stability bound, so the motion feels
 /// identical at any frame rate.
 pub fn spring_advance(
    mut pos: f64,
    mut vel: f64,
    target: f64,
    k: f64,
    c: f64,
    dt: f64,
 ) -> (f64, f64) {
    let n = (dt / 0.008).ceil().max(1.0) as usize;
    let h = dt / n as f64;
    for _ in 0..n {
        (pos, vel) = spring_step(pos, vel, target, k, c, h);
    }
    (pos, vel)
 }
 /// Pure cursor arithmetic for a move/jump: `clamp` lands jumps on the ends, a plain
 /// step refuses to leave them.
 #[derive(Debug, PartialEq, Eq)]
 pub enum StepResult {
    Moved(i32),
    Boundary,
 }
 pub fn step_cursor(cursor: i32, len: usize, delta: i32, clamp: bool) -> StepResult {
    if len == 0 {
        return StepResult::Boundary;
    }
    let max = len as i32 - 1;
    let target = if clamp {
        (cursor + delta).clamp(0, max)
    } else {
        cursor + delta
    };
    if target == cursor || target < 0 || target > max {
        StepResult::Boundary
    } else {
        StepResult::Moved(target)
    }
 }
 // --- 4×4 matrix (row-major) — the coverflow card transform ------------------------------
 /// `T(cx,cy) · P(depth) · Ry(angle) · S(s) · T(-w/2,-h/2)`: card-local (0..w, 0..h) →
 /// screen, rotated about the card's own vertical center axis under perspective — the
 /// GSK transform chain from the GTK launcher, as one row-major matrix for
 /// `Canvas::concat_44`.
 #[allow(clippy::too_many_arguments)]
 pub fn card_matrix(
    cx: f64,
    cy: f64,
    angle_deg: f64,
    scale: f64,
    w: f64,
    h: f64,
    depth: f64,
 ) -> [f32; 16] {
    let t1 = translate(cx, cy);
    let p = perspective(depth);
    let r = rotate_y(angle_deg.to_radians());
    let s = scale_xy(scale);
    let t2 = translate(-w / 2.0, -h / 2.0);
    let m = mat_mul(&mat_mul(&mat_mul(&mat_mul(&t1, &p), &r), &s), &t2);
    core::array::from_fn(|i| m[i] as f32)
 }
 fn translate(x: f64, y: f64) -> [f64; 16] {
    let mut m = identity();
    m[3] = x;
    m[7] = y;
    m
 }
 fn perspective(d: f64) -> [f64; 16] {
    let mut m = identity();
    m[14] = -1.0 / d; // row 3, col 2 — w' = 1 − z/d (CSS convention)
    m
 }
 fn rotate_y(rad: f64) -> [f64; 16] {
    let (s, c) = rad.sin_cos();
    let mut m = identity();
    m[0] = c;
    m[2] = s;
    m[8] = -s;
    m[10] = c;
    m
 }
 fn scale_xy(s: f64) -> [f64; 16] {
    let mut m = identity();
    m[0] = s;
    m[5] = s;
    m
 }
 fn identity() -> [f64; 16] {
    let mut m = [0.0; 16];
    m[0] = 1.0;
    m[5] = 1.0;
    m[10] = 1.0;
    m[15] = 1.0;
    m
 }
 fn mat_mul(a: &[f64; 16], b: &[f64; 16]) -> [f64; 16] {
    let mut out = [0.0; 16];
    for r in 0..4 {
        for c in 0..4 {
            out[r * 4 + c] = (0..4).map(|k| a[r * 4 + k] * b[k * 4 + c]).sum();
        }
    }
    out
 }
 // --- Mesh-gradient background (the Swift `GamepadScreenBackground` MeshGradient, ported) --
 /// The 16 mesh colours, row-major 4×4 (sRGB) — a verbatim port of the Swift client's
 /// `meshColors`: dark-violet corners sink the frame, the edges carry mid-tone violets, and
 /// the four interior points hold the bright brand family (warm pools left, cool right).
 pub const MESH_COLORS: [(f64, f64, f64); 16] = [
    (0.075, 0.060, 0.160),
    (0.34, 0.27, 0.72),
    (0.30, 0.26, 0.74),
    (0.075, 0.060, 0.160),
    (0.42, 0.20, 0.54),
    (0.49, 0.39, 0.95),
    (0.28, 0.31, 0.84),
    (0.16, 0.26, 0.64),
    (0.45, 0.23, 0.60),
    (0.53, 0.31, 0.75),
    (0.35, 0.35, 0.91),
    (0.19, 0.28, 0.70),
    (0.075, 0.060, 0.160),
    (0.22, 0.18, 0.54),
    (0.24, 0.20, 0.58),
    (0.075, 0.060, 0.160),
 ];
 /// The four interior control points that wander; the 12 boundary points stay pinned to the
 /// frame (a drifting edge point would shrink the field and expose the black behind it). Each
 /// row is `(base_ux, base_uy, amplitude, speed_x, speed_y, phase)` in unit UV / rad·s⁻¹ —
 /// the exact `wob()` parameters from the Swift `meshPoints(at:)`. Their live displacement
 /// `(amp·sin(t·sx+ph), amp·cos(t·sy+ph·1.3))` drives a domain warp, so the bright colour
 /// pools follow the points as they breathe (periods ~90–130 s, out of phase so it never loops).
 pub const MESH_INTERIOR: [(f64, f64, f64, f64, f64, f64); 4] = [
    (0.333, 0.333, 0.11, 0.049, 0.063, 0.4),
    (0.667, 0.333, 0.10, 0.055, 0.052, 2.1),
    (0.333, 0.667, 0.10, 0.058, 0.049, 3.6),
    (0.667, 0.667, 0.12, 0.047, 0.061, 5.0),
 ];
 /// The mesh gradient as SkSL, palette + motion baked into the source (only time and
 /// resolution are uniforms). A smooth bicubic blend of the 16 colours — a separable
 /// cubic-Bézier basis in x then y, C∞ and edge-to-edge, the fragment-shader analogue of
 /// SwiftUI's `MeshGradient(smoothsColors: true)`. The four interior points drive a
 /// bounded (weighted-average) domain warp so the bright pools drift; then the whole field
 /// gets the ±8°/~5-min hue sway, an elliptical vignette, and the vertical legibility scrim,
 /// all matching the Swift `composite(at:)`. Runs on the GPU at full rate.
 pub fn mesh_sksl() -> String {
    // Colours as `float3(r, g, b)` literals, indices 0..15 (row-major 4×4).
    let c = |i: usize| {
        let (r, g, b) = MESH_COLORS[i];
        format!("float3({r}, {g}, {b})")
    };
    // The four interior-point domain-warp accumulators. Displacement matches Swift `wob()`:
    // x uses sin(t·sx+ph), y uses cos(t·sy+ph·1.3). SIG sets how far each point's pull
    // reaches; the warp is the weight-normalised average displacement, so |warp| ≤ max|amp|.
    let mut warp = String::new();
    for (bx, by, amp, sx, sy, ph) in MESH_INTERIOR {
        warp.push_str(&format!(
            "    q = uv - float2({bx}, {by});\n\
                 ww = exp(-dot(q, q) / (2.0 * 0.30 * 0.30));\n\
                 d = float2({amp} * sin(u_t * {sx} + {ph}), \
                            {amp} * cos(u_t * {sy} + {ph} * 1.3));\n\
                 wsum += d * ww; wtot += ww;\n",
        ));
    }
    format!(
        "uniform float2 u_res;\n\
         uniform float u_t;\n\
         \n\
         // Cubic-Bézier basis over four control values — the smooth 4-point blend per axis.\n\
         float bz(float t, float a, float b, float c, float d) {{\n\
         \x20   float u = 1.0 - t;\n\
         \x20   return u*u*u*a + 3.0*u*u*t*b + 3.0*u*t*t*c + t*t*t*d;\n\
         }}\n\
         float3 bz3(float t, float3 a, float3 b, float3 c, float3 d) {{\n\
         \x20   return float3(bz(t, a.r, b.r, c.r, d.r), bz(t, a.g, b.g, c.g, d.g), \
                              bz(t, a.b, b.b, c.b, d.b));\n\
         }}\n\
         // Hue rotation about the grey axis (Rodrigues) — the ±8° warm/cool sway.\n\
         float3 hue(float3 col, float a) {{\n\
         \x20   float3 k = float3(0.5773503);\n\
         \x20   float cs = cos(a); float sn = sin(a);\n\
         \x20   return col*cs + cross(k, col)*sn + k*dot(k, col)*(1.0 - cs);\n\
         }}\n\
         \n\
         half4 main(float2 xy) {{\n\
         \x20   float2 uv = xy / u_res;\n\
         \x20   // Interior control points wander → bounded domain warp (pools follow them).\n\
         \x20   float2 wsum = float2(0.0); float wtot = 0.0; float2 q; float ww; float2 d;\n\
         {warp}\
         \x20   uv = clamp(uv - wsum / (wtot + 1e-4), 0.0, 1.0);\n\
         \n\
         \x20   // Bicubic blend of the 16 mesh colours: cubic-Bézier in x per row, then in y.\n\
         \x20   float3 r0 = bz3(uv.x, {c0}, {c1}, {c2}, {c3});\n\
         \x20   float3 r1 = bz3(uv.x, {c4}, {c5}, {c6}, {c7});\n\
         \x20   float3 r2 = bz3(uv.x, {c8}, {c9}, {c10}, {c11});\n\
         \x20   float3 r3 = bz3(uv.x, {c12}, {c13}, {c14}, {c15});\n\
         \x20   float3 col = bz3(uv.y, r0, r1, r2, r3);\n\
         \n\
         \x20   col = hue(col, sin(u_t * 0.021) * 0.1396263);\n\
         \n\
         \x20   // Elliptical vignette: clear at r=0.25 → black·0.42 at r=1.15 (aspect-fit ellipse).\n\
         \x20   float2 e = (xy / u_res - 0.5) * 2.0;\n\
         \x20   float vig = clamp((length(e) - 0.25) / 0.90, 0.0, 1.0) * 0.42;\n\
         \x20   col *= 1.0 - vig;\n\
         \n\
         \x20   // Vertical legibility scrim: black 0.38/0.06/0.08/0.40 at 0/0.32/0.68/1.\n\
         \x20   float v = xy.y / u_res.y;\n\
         \x20   float s = v < 0.32 ? mix(0.38, 0.06, v / 0.32)\n\
         \x20           : v < 0.68 ? mix(0.06, 0.08, (v - 0.32) / 0.36)\n\
         \x20           : mix(0.08, 0.40, (v - 0.68) / 0.32);\n\
         \x20   col *= 1.0 - s;\n\
         \n\
         \x20   return half4(half3(col), 1.0);\n\
         }}\n",
        c0 = c(0), c1 = c(1), c2 = c(2), c3 = c(3),
        c4 = c(4), c5 = c(5), c6 = c(6), c7 = c(7),
        c8 = c(8), c9 = c(9), c10 = c(10), c11 = c(11),
        c12 = c(12), c13 = c(13), c14 = c(14), c15 = c(15),
    )
 }
 // --- The shared binary↔overlay model ------------------------------------------------------
 #[derive(Clone, PartialEq)]
 pub enum LibraryPhase {
    Loading,
    /// Browse target isn't paired — pairing is the plugin's job, render the advice.
    PairFirst,
    Error {
        title: String,
        body: String,
        can_retry: bool,
    },
    Empty,
    /// Games are loaded — the carousel.
    Ready,
 }
 #[derive(Clone)]
 pub struct LibraryGame {
    pub id: String,
    pub title: String,
    pub store: String,
 }
 struct Shared {
    phase: LibraryPhase,
    games: Vec<LibraryGame>,
    /// Fetched poster bytes the renderer hasn't decoded yet (id, encoded image).
    art_in: VecDeque<(String, Vec<u8>)>,
    /// Bumped on phase/games changes so the renderer re-syncs its snapshot.
    generation: u64,
 }
 /// The binary's write handle / the overlay's read handle — fetch threads push into it,
 /// the renderer drains per frame. Cheap locks, no rendering data inside.
 #[derive(Clone)]
 pub struct LibraryShared(Arc<Mutex<Shared>>);
 impl Default for LibraryShared {
    fn default() -> Self {
        LibraryShared(Arc::new(Mutex::new(Shared {
            phase: LibraryPhase::Loading,
            games: Vec::new(),
            art_in: VecDeque::new(),
            generation: 0,
        })))
    }
 }
 impl LibraryShared {
    pub fn set_phase(&self, phase: LibraryPhase) {
        let mut s = self.0.lock().unwrap();
        s.phase = phase;
        s.generation += 1;
    }
    /// Loaded games → the carousel (empty = the empty scene).
    pub fn set_games(&self, games: Vec<LibraryGame>) {
        let mut s = self.0.lock().unwrap();
        s.phase = if games.is_empty() {
            LibraryPhase::Empty
        } else {
            LibraryPhase::Ready
        };
        s.games = games;
        s.generation += 1;
    }
    pub fn push_art(&self, id: String, bytes: Vec<u8>) {
        self.0.lock().unwrap().art_in.push_back((id, bytes));
    }
    /// Renderer side: the generation stamp (re-snapshot on change).
    pub(crate) fn generation(&self) -> u64 {
        self.0.lock().unwrap().generation
    }
    pub(crate) fn snapshot(&self) -> (LibraryPhase, Vec<LibraryGame>, u64) {
        let s = self.0.lock().unwrap();
        (s.phase.clone(), s.games.clone(), s.generation)
    }
    pub(crate) fn drain_art(&self) -> Vec<(String, Vec<u8>)> {
        self.0.lock().unwrap().art_in.drain(..).collect()
    }
 }
 /// Store id → display label (the GTK `ui_library` table).
 pub fn store_label(store: &str) -> &'static str {
    match store {
        "steam" => "Steam",
        "custom" => "Custom",
        "heroic" => "Heroic",
        "lutris" => "Lutris",
        "epic" => "Epic",
        "gog" => "GOG",
        "xbox" => "Xbox",
        _ => "Game",
    }
 }
 /// Monogram for the placeholder tile: the first letters of the first two words.
 pub fn initials(title: &str) -> String {
    title
        .split_whitespace()
        .take(2)
        .filter_map(|w| w.chars().next())
        .flat_map(char::to_uppercase)
        .collect()
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    /// The GTK launcher's cursor tests, ported with the math.
    #[test]
    fn step_refuses_the_ends() {
        assert_eq!(step_cursor(0, 5, -1, false), StepResult::Boundary);
        assert_eq!(step_cursor(4, 5, 1, false), StepResult::Boundary);
        assert_eq!(step_cursor(2, 5, 1, false), StepResult::Moved(3));
        assert_eq!(step_cursor(0, 0, 1, false), StepResult::Boundary);
    }
    #[test]
    fn jump_clamps_onto_the_ends() {
        assert_eq!(step_cursor(1, 5, -JUMP, true), StepResult::Moved(0));
        assert_eq!(step_cursor(3, 5, JUMP, true), StepResult::Moved(4));
        assert_eq!(step_cursor(0, 5, -JUMP, true), StepResult::Boundary);
    }
    /// Springs converge onto the target and stay finite through a stalled frame.
    #[test]
    fn springs_converge() {
        let (mut pos, mut vel) = (0.0, 0.0);
        for _ in 0..120 {
            (pos, vel) = spring_advance(pos, vel, 3.0, SPRING_K, SPRING_C, 1.0 / 60.0);
        }
        assert!((pos - 3.0).abs() < 0.01, "{pos}");
        let (p, v) = spring_advance(0.0, 0.0, 1.0, BUMP_K, BUMP_C, 0.05);
        assert!(
            p.is_finite() && v.is_finite() && p > 0.0 && p < 2.0,
            "{p}/{v}"
        );
    }
    /// The focused card (angle 0, scale 1) maps its center to (cx, cy) exactly.
    #[test]
    fn card_matrix_centers_the_focused_card() {
        let m = card_matrix(640.0, 400.0, 0.0, 1.0, POSTER_W, POSTER_H, PERSPECTIVE);
        // Apply to the card-local center (w/2, h/2, 0, 1).
        let (x, y) = (POSTER_W as f32 / 2.0, POSTER_H as f32 / 2.0);
        let px = m[0] * x + m[1] * y + m[3];
        let py = m[4] * x + m[5] * y + m[7];
        let pw = m[12] * x + m[13] * y + m[15];
        assert!((px / pw - 640.0).abs() < 0.01, "{}", px / pw);
        assert!((py / pw - 400.0).abs() < 0.01, "{}", py / pw);
    }
    /// A right-side card's INNER (left) edge recedes: its projected x compresses toward
    /// the center relative to the flat card — the coverflow corridor.
    #[test]
    fn side_card_inner_edge_recedes() {
        let flat = card_matrix(900.0, 400.0, 0.0, 1.0, POSTER_W, POSTER_H, PERSPECTIVE);
        let tilted = card_matrix(
            900.0,
            400.0,
            -ROTATE_DEG,
            1.0,
            POSTER_W,
            POSTER_H,
            PERSPECTIVE,
        );
        let project = |m: &[f32; 16], x: f32, y: f32| {
            let px = m[0] * x + m[1] * y + m[3];
            let pw = m[12] * x + m[13] * y + m[15];
            px / pw
        };
        // The inner edge is x=0 in card space. Perspective divide: receding (w < 1 side)
        // pushes it AWAY from the vanishing center — the edge reads as farther.
        let flat_left = project(&flat, 0.0, POSTER_H as f32 / 2.0);
        let tilt_left = project(&tilted, 0.0, POSTER_H as f32 / 2.0);
        let flat_right = project(&flat, POSTER_W as f32, POSTER_H as f32 / 2.0);
        let tilt_right = project(&tilted, POSTER_W as f32, POSTER_H as f32 / 2.0);
        // Tilt narrows the card's projected width (it turned away from the viewer).
        assert!((tilt_right - tilt_left) < (flat_right - flat_left) * 0.95);
    }
    #[test]
    fn initials_take_two_words() {
        assert_eq!(initials("Dota 2"), "D2");
        assert_eq!(initials("half-life"), "H");
    }
    /// The generated SkSL parses as far as syntax we control (sanity: balanced braces, all
    /// 16 colours baked in, the five bicubic evals and four interior warp terms present).
    #[test]
    fn mesh_sksl_shape() {
        let src = mesh_sksl();
        assert!(src.matches("float3(").count() >= 16, "16 colours baked");
        assert_eq!(src.matches("bz3(").count(), 6); // 1 definition + 5 call sites
        assert_eq!(src.matches("wtot +=").count(), 4); // one per interior point
        assert_eq!(src.matches('{').count(), src.matches('}').count());
    }
 }
@@ -0,0 +1,709 @@
 //! The console library's Skia side: navigation state, scene selection, and rendering —
 //! the GTK launcher (`ui_gamepad_library.rs`) re-homed onto the presenter surface. The
 //! mesh-gradient background runs as an SkSL shader at full rate (the 30 Hz CPU path is
 //! gone), the coverflow is `concat_44` perspective with paint order = draw order (the
 //! restack hack is gone), and every state renders in-scene (gamescope maps no dialogs).
 use crate::library::{
    card_matrix, initials, mesh_sksl, spring_advance, step_cursor, store_label, LibraryGame,
    LibraryPhase, LibraryShared, StepResult, BUMP_C, BUMP_K, BUMP_PX, FOCUS_GAP, JUMP, PERSPECTIVE,
    POSTER_H, POSTER_W, RECEDE_DIM, RECEDE_SCALE, ROTATE_DEG, SIDE_SPACING, SPRING_C, SPRING_K,
    VISIBLE_RANGE,
 };
 use anyhow::{anyhow, Result};
 use pf_client_core::gamepad::{MenuDir, MenuEvent, MenuPulse};
 use pf_presenter::overlay::OverlayAction;
 use skia_safe::textlayout::{
    FontCollection, ParagraphBuilder, ParagraphStyle, TextAlign, TextStyle,
 };
 use skia_safe::{
    Canvas, Color4f, Data, Font, FontStyle, Image, Paint, Point, RRect, Rect, RuntimeEffect,
    Typeface, M44,
 };
 use std::collections::{HashMap, VecDeque};
 use std::time::Instant;
 pub(crate) struct LibraryUi {
    shared: LibraryShared,
    host_label: String,
    // Synced snapshot of the shared model (re-pulled when the generation bumps).
    generation: u64,
    phase: LibraryPhase,
    games: Vec<LibraryGame>,
    // Navigation: the integer cursor is the authority; the eased position chases it.
    cursor: i32,
    anim_pos: f64,
    anim_vel: f64,
    bump: f64,
    bump_vel: f64,
    last_frame: Option<Instant>,
    t0: Instant,
    /// Decoded posters by game id (decode once; Skia uploads lazily on first draw).
    art: HashMap<String, Image>,
    /// The animated mesh-gradient background (compiled once; drawn first each frame).
    mesh: RuntimeEffect,
    /// A launch is in flight — menu input parks, the hint bar says Connecting….
    connecting: bool,
    /// A session is on screen — the library doesn't render (stream chrome does).
    pub(crate) in_stream: bool,
    /// Transient error strip on the carousel (connect failures land here).
    status: Option<String>,
    actions: VecDeque<OverlayAction>,
 }
 impl LibraryUi {
    pub(crate) fn new(shared: LibraryShared, host_label: String) -> Result<LibraryUi> {
        let mesh = RuntimeEffect::make_for_shader(mesh_sksl(), None)
            .map_err(|e| anyhow!("mesh-gradient SkSL: {e}"))?;
        Ok(LibraryUi {
            shared,
            host_label,
            generation: u64::MAX, // force the first sync
            phase: LibraryPhase::Loading,
            games: Vec::new(),
            cursor: 0,
            anim_pos: 0.0,
            anim_vel: 0.0,
            bump: 0.0,
            bump_vel: 0.0,
            last_frame: None,
            t0: Instant::now(),
            art: HashMap::new(),
            mesh,
            connecting: false,
            in_stream: false,
            status: None,
            actions: VecDeque::new(),
        })
    }
    /// Pull the shared model when it changed; decode any newly arrived poster bytes.
    pub(crate) fn sync(&mut self) {
        if self.shared.generation() != self.generation {
            let (phase, games, generation) = self.shared.snapshot();
            let fresh_games = self.games.len() != games.len()
                || self.games.iter().zip(&games).any(|(a, b)| a.id != b.id);
            self.phase = phase;
            self.games = games;
            self.generation = generation;
            if fresh_games {
                // Fresh library: snap the sprung position onto the (reset) cursor.
                self.cursor = 0;
                self.anim_pos = 0.0;
                self.anim_vel = 0.0;
                self.bump = 0.0;
                self.bump_vel = 0.0;
            }
            self.cursor = self.cursor.clamp(0, (self.games.len() as i32 - 1).max(0));
        }
        for (id, bytes) in self.shared.drain_art() {
            match Image::from_encoded(Data::new_copy(&bytes)) {
                Some(img) => {
                    self.art.insert(id, img);
                }
                None => tracing::debug!(%id, "undecodable poster"),
            }
        }
    }
    /// Menu-mode navigation (gamepad; the keyboard fallback funnels in here too).
    pub(crate) fn menu(&mut self, ev: MenuEvent) -> Option<MenuPulse> {
        if self.connecting {
            return None; // a connect is in flight — input is parked
        }
        match &self.phase {
            LibraryPhase::Ready => match ev {
                MenuEvent::Move(MenuDir::Left) => self.step(-1, false),
                MenuEvent::Move(MenuDir::Right) => self.step(1, false),
                MenuEvent::JumpBack => self.step(-JUMP, true),
                MenuEvent::JumpForward => self.step(JUMP, true),
                MenuEvent::Confirm => {
                    let g = self.games.get(self.cursor as usize)?;
                    self.actions.push_back(OverlayAction::Launch {
                        id: g.id.clone(),
                        title: g.title.clone(),
                    });
                    self.status = None;
                    self.connecting = true;
                    Some(MenuPulse::Confirm)
                }
                MenuEvent::Back => {
                    self.actions.push_back(OverlayAction::Quit);
                    None
                }
                MenuEvent::Move(_) | MenuEvent::Secondary | MenuEvent::Tertiary => None,
            },
            LibraryPhase::Error { can_retry, .. } => match ev {
                MenuEvent::Confirm if *can_retry => {
                    self.phase = LibraryPhase::Loading; // local; the fetch re-syncs it
                    self.actions.push_back(OverlayAction::Retry);
                    Some(MenuPulse::Confirm)
                }
                MenuEvent::Back => {
                    self.actions.push_back(OverlayAction::Quit);
                    None
                }
                _ => None,
            },
            LibraryPhase::Loading | LibraryPhase::Empty | LibraryPhase::PairFirst => {
                if ev == MenuEvent::Back {
                    self.actions.push_back(OverlayAction::Quit);
                }
                None
            }
        }
    }
    /// Keyboard fallback (arrows/Enter/Esc/PageUp/PageDown) — the launcher is fully
    /// drivable with no pad. Returns true when consumed.
    pub(crate) fn key(&mut self, sc: sdl3::keyboard::Scancode, repeat: bool) -> bool {
        use sdl3::keyboard::Scancode as S;
        let ev = match sc {
            S::Left => MenuEvent::Move(MenuDir::Left),
            S::Right => MenuEvent::Move(MenuDir::Right),
            S::Up => MenuEvent::Move(MenuDir::Up),
            S::Down => MenuEvent::Move(MenuDir::Down),
            S::Return | S::KpEnter | S::Space if !repeat => MenuEvent::Confirm,
            S::Escape | S::Backspace if !repeat => MenuEvent::Back,
            S::PageUp if !repeat => MenuEvent::JumpBack,
            S::PageDown if !repeat => MenuEvent::JumpForward,
            _ => return false,
        };
        self.menu(ev); // no pad to pulse
        true
    }
    pub(crate) fn take_action(&mut self) -> Option<OverlayAction> {
        self.actions.pop_front()
    }
    pub(crate) fn set_connecting(&mut self, on: bool) {
        self.connecting = on;
        if on {
            self.status = None;
        }
    }
    /// A launch that didn't stick (connect failed / session ended with a reason):
    /// carousel-visible errors land on the transient strip, anything else becomes the
    /// error scene (no retry — the library itself is fine).
    pub(crate) fn session_error(&mut self, msg: &str) {
        self.connecting = false;
        self.in_stream = false;
        if self.phase == LibraryPhase::Ready {
            self.status = Some(format!("Couldn't connect — {msg}"));
        } else {
            self.phase = LibraryPhase::Error {
                title: "Couldn't connect".into(),
                body: msg.to_string(),
                can_retry: false,
            };
        }
    }
    fn step(&mut self, delta: i32, clamp: bool) -> Option<MenuPulse> {
        match step_cursor(self.cursor, self.games.len(), delta, clamp) {
            StepResult::Moved(to) => {
                self.cursor = to;
                Some(MenuPulse::Move)
            }
            StepResult::Boundary => {
                // Recoil against the push; the stiff bump spring wobbles it back.
                self.bump = -BUMP_PX * f64::from(delta.signum());
                self.bump_vel = 0.0;
                Some(MenuPulse::Boundary)
            }
        }
    }
    /// Render the whole library scene. Always a full repaint — the aurora animates
    /// every frame (that's the point of the GPU port).
    pub(crate) fn render(&mut self, canvas: &Canvas, w: u32, h: u32, fonts: &Fonts) {
        let (wf, hf) = (w as f64, h as f64);
        // Uniform scale off the Deck's 800p design height; fonts and geometry follow.
        let k = (hf / 800.0).clamp(0.75, 3.0);
        // Springs (Ready only — other scenes have no strip).
        let now = Instant::now();
        let dt = self
            .last_frame
            .replace(now)
            .map_or(1.0 / 60.0, |t| (now - t).as_secs_f64().clamp(0.0, 0.05));
        if self.phase == LibraryPhase::Ready {
            let target = f64::from(self.cursor);
            (self.anim_pos, self.anim_vel) =
                spring_advance(self.anim_pos, self.anim_vel, target, SPRING_K, SPRING_C, dt);
            if (target - self.anim_pos).abs() < 0.001 && self.anim_vel.abs() < 0.01 {
                self.anim_pos = target;
                self.anim_vel = 0.0;
            }
            (self.bump, self.bump_vel) =
                spring_advance(self.bump, self.bump_vel, 0.0, BUMP_K, BUMP_C, dt);
            if self.bump.abs() < 0.3 && self.bump_vel.abs() < 4.0 {
                self.bump = 0.0;
                self.bump_vel = 0.0;
            }
        }
        self.draw_background(canvas, wf, hf);
        match self.phase.clone() {
            LibraryPhase::Ready => self.draw_carousel(canvas, wf, hf, k, fonts),
            LibraryPhase::Loading => {
                self.draw_spinner(canvas, wf / 2.0, hf / 2.0 - 24.0 * k, 16.0 * k);
                fonts.centered(
                    canvas,
                    "Loading library…",
                    14.0 * k,
                    DIM_TEXT,
                    wf / 2.0,
                    hf / 2.0 + 16.0 * k,
                    wf * 0.8,
                );
            }
            LibraryPhase::PairFirst => {
                fonts.centered_bold(
                    canvas,
                    "Not paired with this host",
                    22.0 * k,
                    WHITE,
                    wf / 2.0,
                    hf / 2.0 - 20.0 * k,
                    wf * 0.8,
                );
                fonts.centered(
                    canvas,
                    "Pair from the Punktfunk plugin first.",
                    14.0 * k,
                    DIM_TEXT,
                    wf / 2.0,
                    hf / 2.0 + 12.0 * k,
                    wf * 0.8,
                );
            }
            LibraryPhase::Empty => {
                fonts.centered_bold(
                    canvas,
                    "No games found",
                    22.0 * k,
                    WHITE,
                    wf / 2.0,
                    hf / 2.0 - 20.0 * k,
                    wf * 0.8,
                );
                fonts.centered(
                    canvas,
                    "Install Steam titles or add custom entries in the host's web console.",
                    14.0 * k,
                    DIM_TEXT,
                    wf / 2.0,
                    hf / 2.0 + 12.0 * k,
                    wf * 0.8,
                );
            }
            LibraryPhase::Error { title, body, .. } => {
                fonts.centered_bold(
                    canvas,
                    &title,
                    22.0 * k,
                    WHITE,
                    wf / 2.0,
                    hf / 2.0 - 32.0 * k,
                    wf * 0.8,
                );
                fonts.centered(
                    canvas,
                    &body,
                    14.0 * k,
                    DIM_TEXT,
                    wf / 2.0,
                    hf / 2.0 + 4.0 * k,
                    (600.0 * k).min(wf * 0.85),
                );
            }
        }
        self.draw_chrome(canvas, wf, hf, k, fonts);
    }
    fn draw_background(&self, canvas: &Canvas, w: f64, h: f64) {
        let t = self.t0.elapsed().as_secs_f64();
        // Uniform layout: float2 u_res, float u_t (declared order, no padding needed).
        let uniforms: [f32; 3] = [w as f32, h as f32, t as f32];
        let data = Data::new_copy(bytemuck_bytes(&uniforms));
        match self.mesh.make_shader(data, &[], None) {
            Some(shader) => {
                let mut paint = Paint::default();
                paint.set_shader(shader);
                canvas.draw_rect(Rect::from_wh(w as f32, h as f32), &paint);
            }
            None => {
                canvas.clear(Color4f::new(0.0, 0.0, 0.0, 1.0));
            }
        }
    }
    fn draw_carousel(&mut self, canvas: &Canvas, w: f64, h: f64, k: f64, fonts: &Fonts) {
        let (card_w, card_h) = (POSTER_W * k, POSTER_H * k);
        // The strip's vertical center: the space between the top bar and the detail
        // block (the GTK vexpand'ed scroller, approximated).
        let cy = h * 0.44;
        let pos = self.anim_pos;
        let bump = self.bump * k;
        // Paint order = draw order: farthest from the (integer) cursor first, so the
        // dense side stacks overlap toward the focus. Stable → the equidistant
        // neighbors keep a deterministic order.
        let mut order: Vec<usize> = (0..self.games.len()).collect();
        order.sort_by_key(|&i| std::cmp::Reverse((i as i32 - self.cursor).abs()));
        for i in order {
            let d = i as f64 - pos;
            let a = d.abs();
            if a > VISIBLE_RANGE {
                continue;
            }
            let prox = a.min(1.0);
            let scale = 1.0 - prox * RECEDE_SCALE;
            let angle = -d.clamp(-1.0, 1.0) * ROTATE_DEG;
            // Piecewise strip: a full FOCUS_GAP around the focus, then the dense side
            // stacks (the classic coverflow shelf).
            let offset = if a <= 1.0 {
                d * FOCUS_GAP * k
            } else {
                d.signum() * (FOCUS_GAP + (a - 1.0) * SIDE_SPACING) * k
            };
            let cx = w / 2.0 + offset + bump;
            let m = card_matrix(cx, cy, angle, scale, card_w, card_h, PERSPECTIVE * k);
            let game = &self.games[i];
            canvas.save();
            canvas.concat_44(&M44::row_major(&m));
            let rect = Rect::from_wh(card_w as f32, card_h as f32);
            let rr = RRect::new_rect_xy(rect, 16.0 * k as f32, 16.0 * k as f32);
            canvas.clip_rrect(rr, None, true);
            match self.art.get(&game.id) {
                Some(img) => {
                    // Cover-fit: center-crop the source to the card's 2:3.
                    let (iw, ih) = (img.width() as f32, img.height() as f32);
                    let card_aspect = rect.width() / rect.height();
                    let src = if iw / ih > card_aspect {
                        let sw = ih * card_aspect;
                        Rect::from_xywh((iw - sw) / 2.0, 0.0, sw, ih)
                    } else {
                        let sh = iw / card_aspect;
                        Rect::from_xywh(0.0, (ih - sh) / 2.0, iw, sh)
                    };
                    canvas.draw_image_rect(
                        img,
                        Some((&src, skia_safe::canvas::SrcRectConstraint::Fast)),
                        rect,
                        &Paint::default(),
                    );
                }
                None => {
                    // Solid face, not glass: the side cards OVERLAP (GTK CSS note).
                    canvas.draw_rect(
                        rect,
                        &Paint::new(Color4f::new(0.118, 0.118, 0.145, 1.0), None),
                    );
                    let mono = initials(&game.title);
                    let font = fonts.sans_bold(38.0 * k);
                    let tw = font.measure_str(&mono, None).0;
                    canvas.draw_str(
                        &mono,
                        Point::new(
                            (card_w as f32 - tw) / 2.0,
                            card_h as f32 / 2.0 + 13.0 * k as f32,
                        ),
                        &font,
                        &Paint::new(Color4f::new(1.0, 1.0, 1.0, 0.45), None),
                    );
                }
            }
            // Store badge, top-left.
            {
                let label = store_label(&game.store);
                let font = fonts.sans_bold(11.0 * k);
                let tw = font.measure_str(label, None).0;
                let (px, py) = (8.0 * k as f32, 8.0 * k as f32);
                let (bw, bh) = (tw + 16.0 * k as f32, 20.0 * k as f32);
                canvas.draw_rrect(
                    RRect::new_rect_xy(Rect::from_xywh(px, py, bw, bh), bh / 2.0, bh / 2.0),
                    &Paint::new(Color4f::new(0.0, 0.0, 0.0, 0.55), None),
                );
                canvas.draw_str(
                    label,
                    Point::new(px + 8.0 * k as f32, py + 14.0 * k as f32),
                    &font,
                    &Paint::new(Color4f::new(1.0, 1.0, 1.0, 1.0), None),
                );
            }
            // The brightness recede: an opaque-black veil, never whole-card alpha.
            if prox > 0.0 {
                canvas.draw_rect(
                    rect,
                    &Paint::new(
                        Color4f::new(0.0, 0.0, 0.0, (prox * RECEDE_DIM) as f32),
                        None,
                    ),
                );
            }
            canvas.restore();
        }
        // Detail block: focused title + store, centered between strip and hints.
        if let Some(g) = self.games.get(self.cursor as usize) {
            fonts.centered_bold(
                canvas,
                &g.title,
                27.0 * k,
                WHITE,
                w / 2.0,
                h - 96.0 * k,
                w * 0.8,
            );
            fonts.centered(
                canvas,
                &store_label(&g.store).to_uppercase(),
                12.0 * k,
                Color4f::new(1.0, 1.0, 1.0, 0.5),
                w / 2.0,
                h - 66.0 * k,
                w * 0.5,
            );
        }
        if let Some(status) = &self.status {
            fonts.centered(
                canvas,
                status,
                13.0 * k,
                Color4f::new(1.0, 0.576, 0.541, 1.0), // the GTK #ff938a
                w / 2.0,
                h - 44.0 * k,
                w * 0.85,
            );
        }
    }
    /// Top bar (host + controller chip) and the bottom hint bar — per-scene affordances.
    fn draw_chrome(&self, canvas: &Canvas, w: f64, h: f64, k: f64, fonts: &Fonts) {
        let font = fonts.sans_bold(18.0 * k);
        canvas.draw_str(
            &self.host_label,
            Point::new(24.0 * k as f32, 32.0 * k as f32),
            &font,
            &Paint::new(Color4f::new(1.0, 1.0, 1.0, 0.9), None),
        );
        if let Some(chip) = &fonts.chip_text {
            let cf = fonts.sans(12.0 * k);
            let tw = cf.measure_str(chip, None).0;
            let (bh, pad) = (24.0 * k as f32, 12.0 * k as f32);
            let bx = w as f32 - 24.0 * k as f32 - tw - 2.0 * pad;
            canvas.draw_rrect(
                RRect::new_rect_xy(
                    Rect::from_xywh(bx, 18.0 * k as f32, tw + 2.0 * pad, bh),
                    bh / 2.0,
                    bh / 2.0,
                ),
                &Paint::new(Color4f::new(1.0, 1.0, 1.0, 0.08), None),
            );
            canvas.draw_str(
                chip,
                Point::new(bx + pad, 18.0 * k as f32 + 16.0 * k as f32),
                &cf,
                &Paint::new(Color4f::new(1.0, 1.0, 1.0, 0.7), None),
            );
        }
        let hint = if self.connecting {
            "Connecting…".to_string()
        } else {
            match &self.phase {
                LibraryPhase::Ready => "A  Play    B  Quit    L1 / R1  Jump".to_string(),
                LibraryPhase::Error {
                    can_retry: true, ..
                } => "A  Retry    B  Quit".to_string(),
                _ => "B  Quit".to_string(),
            }
        };
        fonts.left(
            canvas,
            &hint,
            13.0 * k,
            Color4f::new(1.0, 1.0, 1.0, 0.85),
            24.0 * k,
            h - 20.0 * k,
        );
    }
    /// The loading spinner: a rotating arc off the aurora clock.
    fn draw_spinner(&self, canvas: &Canvas, cx: f64, cy: f64, r: f64) {
        let t = self.t0.elapsed().as_secs_f64();
        let start = (t * 300.0) % 360.0;
        let mut paint = Paint::new(Color4f::new(1.0, 1.0, 1.0, 0.85), None);
        paint.set_style(skia_safe::PaintStyle::Stroke);
        paint.set_stroke_width(3.0);
        paint.set_anti_alias(true);
        canvas.draw_arc(
            Rect::from_xywh(
                (cx - r) as f32,
                (cy - r) as f32,
                2.0 * r as f32,
                2.0 * r as f32,
            ),
            start as f32,
            270.0,
            false,
            &paint,
        );
    }
 }
 const WHITE: Color4f = Color4f::new(1.0, 1.0, 1.0, 1.0);
 const DIM_TEXT: Color4f = Color4f::new(1.0, 1.0, 1.0, 0.7);
 fn bytemuck_bytes(v: &[f32; 3]) -> &[u8] {
    unsafe { std::slice::from_raw_parts(v.as_ptr().cast::<u8>(), 12) }
 }
 /// The text toolkit shared by every scene: typefaces + a paragraph-based centered-text
 /// helper (shaping + font fallback — poster titles can be CJK; `draw_str` can't).
 pub(crate) struct Fonts {
    pub sans: Typeface,
    pub collection: FontCollection,
    /// The controller chip's current text (fed per frame by the overlay).
    pub chip_text: Option<String>,
 }
 impl Fonts {
    fn sans(&self, size: f64) -> Font {
        Font::new(self.sans.clone(), size as f32)
    }
    fn sans_bold(&self, size: f64) -> Font {
        let mut f = Font::new(self.sans.clone(), size as f32);
        f.set_embolden(true);
        f
    }
    fn paragraph(
        &self,
        text: &str,
        size: f64,
        color: Color4f,
        bold: bool,
        align: TextAlign,
        max_w: f64,
    ) -> skia_safe::textlayout::Paragraph {
        let mut style = ParagraphStyle::new();
        style.set_text_align(align);
        let mut ts = TextStyle::new();
        ts.set_font_size(size as f32);
        ts.set_color(color.to_color());
        ts.set_font_style(if bold {
            FontStyle::bold()
        } else {
            FontStyle::normal()
        });
        style.set_text_style(&ts);
        let mut b = ParagraphBuilder::new(&style, self.collection.clone());
        b.add_text(text);
        let mut p = b.build();
        p.layout(max_w as f32);
        p
    }
    /// Centered paragraph with `y` as its top edge.
    #[allow(clippy::too_many_arguments)]
    fn centered(
        &self,
        canvas: &Canvas,
        text: &str,
        size: f64,
        color: Color4f,
        cx: f64,
        y: f64,
        max_w: f64,
    ) {
        let p = self.paragraph(text, size, color, false, TextAlign::Center, max_w);
        p.paint(canvas, Point::new((cx - max_w / 2.0) as f32, y as f32));
    }
    #[allow(clippy::too_many_arguments)]
    fn centered_bold(
        &self,
        canvas: &Canvas,
        text: &str,
        size: f64,
        color: Color4f,
        cx: f64,
        y: f64,
        max_w: f64,
    ) {
        let p = self.paragraph(text, size, color, true, TextAlign::Center, max_w);
        p.paint(canvas, Point::new((cx - max_w / 2.0) as f32, y as f32));
    }
    fn left(&self, canvas: &Canvas, text: &str, size: f64, color: Color4f, x: f64, y: f64) {
        canvas.draw_str(
            text,
            Point::new(x as f32, y as f32),
            &self.sans(size),
            &Paint::new(color, None),
        );
    }
 }
 pub(crate) fn build_fonts() -> Result<Fonts> {
    let mgr = skia_safe::FontMgr::new();
    let sans = mgr
        .match_family_style("sans-serif", FontStyle::normal())
        .ok_or_else(|| anyhow!("no sans-serif typeface via fontconfig"))?;
    let mut collection = FontCollection::new();
    collection.set_default_font_manager(mgr, None);
    Ok(Fonts {
        sans,
        collection,
        chip_text: None,
    })
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    /// The generated mesh-gradient SkSL must actually compile (Skia's SkSL frontend runs
    /// on the CPU — no GPU needed) — the shape test in `library` can't catch type errors.
    #[test]
    fn mesh_sksl_compiles() {
        RuntimeEffect::make_for_shader(mesh_sksl(), None)
            .unwrap_or_else(|e| panic!("mesh-gradient SkSL rejected:\n{e}"));
    }
    /// Render the background on a CPU raster surface at a few times and dump PNGs — a visual
    /// check of the mesh-gradient look (ignored; run with `--ignored` + PF_MESH_DUMP=<dir>).
    #[test]
    #[ignore]
    fn mesh_dump_png() {
        let dir = std::env::var("PF_MESH_DUMP").expect("set PF_MESH_DUMP to an output dir");
        let effect = RuntimeEffect::make_for_shader(mesh_sksl(), None).unwrap();
        let (w, h) = (1280i32, 800i32);
        for t in [0.0f32, 20.0, 60.0, 300.0] {
            let mut surface = skia_safe::surfaces::raster_n32_premul((w, h)).unwrap();
            let uniforms: [f32; 3] = [w as f32, h as f32, t];
            let data = Data::new_copy(bytemuck_bytes(&uniforms));
            let shader = effect.make_shader(data, &[], None).unwrap();
            let mut paint = Paint::default();
            paint.set_shader(shader);
            surface
                .canvas()
                .draw_rect(Rect::from_wh(w as f32, h as f32), &paint);
            let png = surface
                .image_snapshot()
                .encode(None, skia_safe::EncodedImageFormat::PNG, 100)
                .unwrap();
            std::fs::write(format!("{dir}/mesh_t{t}.png"), png.as_bytes()).unwrap();
        }
    }
 }
@@ -0,0 +1,434 @@
 //! Skia on the presenter's device: `DirectContext` over the shared handles, a ring of
 //! two offscreen render-target surfaces (the presenter runs one frame in flight and may
 //! still be sampling the previous image while we render the next), damage-driven
 //! redraws (content/size change only — an unchanged OSD costs zero GPU work per frame).
 use crate::library::LibraryShared;
 use crate::library_ui::{build_fonts, Fonts, LibraryUi};
 use anyhow::{anyhow, Context as _, Result};
 use ash::vk as avk;
 use ash::vk::Handle as _;
 use pf_client_core::gamepad::{MenuEvent, MenuPulse};
 use pf_presenter::overlay::{
    FrameCtx, Overlay, OverlayAction, OverlayFrame, SessionPhase, SharedDevice,
 };
 use skia_safe::gpu::vk as skvk;
 use skia_safe::gpu::{self, DirectContext, SurfaceOrigin};
 use skia_safe::{Canvas, Color4f, Font, FontMgr, Paint, Point, RRect, Rect, Surface};
 /// Skia's GPU resource budget — the OSD/HUD need a few MB; the console library will
 /// revisit (the plan budgets 64 MB on Deck-class shared memory).
 const RESOURCE_CACHE_BYTES: usize = 64 << 20;
 /// One offscreen target: the Skia surface + the raw Vulkan handles the presenter
 /// samples. The image is Skia-owned (freed with the surface); the view is ours.
 struct Slot {
    surface: Surface,
    image: avk::Image,
    view: avk::ImageView,
    width: u32,
    height: u32,
 }
 /// What the current ring slot has drawn — re-render only when this changes.
 #[derive(PartialEq, Clone, Default)]
 struct Drawn {
    width: u32,
    height: u32,
    stats: Option<String>,
    hint: Option<String>,
 }
 pub struct SkiaOverlay {
    /// Set by `init`; `None` until then (and after an init failure the run loop drops
    /// the whole overlay, so mid-session these are always `Some`).
    gpu: Option<Gpu>,
    slots: [Option<Slot>; 2],
    /// Which slot the LAST returned frame lives in — the next render takes the other.
    current: usize,
    drawn: Drawn,
    font: Option<Font>,
    /// The console library (`--browse`) — `None` for a plain `--connect` session.
    library: Option<LibraryUi>,
    fonts: Option<Fonts>,
 }
 struct Gpu {
    device: ash::Device,
    queue_family_index: u32,
    context: DirectContext,
    // Keep the loader library + instance dispatch alive as long as the DirectContext
    // (its baked fn pointers live inside libvulkan).
    _entry: ash::Entry,
    _instance: ash::Instance,
 }
 impl SkiaOverlay {
    #[allow(clippy::new_without_default)]
    pub fn new() -> SkiaOverlay {
        SkiaOverlay {
            gpu: None,
            slots: [None, None],
            current: 0,
            drawn: Drawn::default(),
            font: None,
            library: None,
            fonts: None,
        }
    }
    /// The `--browse` overlay: the console library between streams, stream chrome
    /// during them. Returns the shared model the binary's fetch threads write into.
    pub fn with_library(host_label: String) -> Result<(SkiaOverlay, LibraryShared)> {
        let shared = LibraryShared::default();
        let mut o = SkiaOverlay::new();
        o.library = Some(LibraryUi::new(shared.clone(), host_label)?);
        Ok((o, shared))
    }
    fn library_visible(&self) -> bool {
        self.library.as_ref().is_some_and(|l| !l.in_stream)
    }
 }
 impl Drop for SkiaOverlay {
    /// The run loop quiesces the queue before dropping us; releasing the views + Skia
    /// surfaces (which free their VkImages) is then safe. Field order drops the slots
    /// before the DirectContext.
    fn drop(&mut self) {
        if let Some(gpu) = &mut self.gpu {
            for slot in self.slots.iter_mut().flat_map(Option::take) {
                unsafe { gpu.device.destroy_image_view(slot.view, None) };
                drop(slot.surface);
            }
            gpu.context.flush_and_submit();
        }
    }
 }
 impl Overlay for SkiaOverlay {
    fn init(&mut self, shared: &SharedDevice) -> Result<()> {
        // Skia resolves its Vulkan entry points through us: instance-scoped names via
        // the loader, device-scoped via the device — the exact same dispatch ash uses.
        // Resolution completes inside `make_vulkan` (the DirectContext bakes its fn
        // table); the closure and its clones end with `init`.
        let entry = shared.entry.clone();
        let instance = shared.instance.clone();
        let get_proc = move |of: skvk::GetProcOf| -> *const std::ffi::c_void {
            unsafe {
                match of {
                    skvk::GetProcOf::Instance(raw_instance, name) => entry
                        .get_instance_proc_addr(avk::Instance::from_raw(raw_instance as _), name)
                        .map_or(std::ptr::null(), |f| f as *const std::ffi::c_void),
                    skvk::GetProcOf::Device(raw_device, name) => {
                        (instance.fp_v1_0().get_device_proc_addr)(
                            avk::Device::from_raw(raw_device as _),
                            name,
                        )
                        .map_or(std::ptr::null(), |f| f as *const std::ffi::c_void)
                    }
                }
            }
        };
        let backend = unsafe {
            skvk::BackendContext::new(
                shared.instance.handle().as_raw() as _,
                shared.physical_device.as_raw() as _,
                shared.device.handle().as_raw() as _,
                (
                    shared.queue.as_raw() as _,
                    shared.queue_family_index as usize,
                ),
                &get_proc,
            )
        };
        let mut context = gpu::direct_contexts::make_vulkan(&backend, None)
            .ok_or_else(|| anyhow!("Skia DirectContext over the shared device"))?;
        context.set_resource_cache_limit(RESOURCE_CACHE_BYTES);
        let typeface = FontMgr::new()
            .match_family_style("monospace", skia_safe::FontStyle::normal())
            .context("no monospace typeface via fontconfig")?;
        self.font = Some(Font::new(typeface, 14.0));
        self.fonts = Some(build_fonts()?);
        self.gpu = Some(Gpu {
            device: shared.device.clone(),
            queue_family_index: shared.queue_family_index,
            context,
            _entry: shared.entry.clone(),
            _instance: shared.instance.clone(),
        });
        tracing::info!("Skia console UI on the presenter's device");
        Ok(())
    }
    fn handle_event(&mut self, event: &sdl3::event::Event) -> bool {
        // The library's keyboard fallback (arrows/Enter/Esc) — only while it's on
        // screen, and never for chord-modified keys (those stay the run loop's).
        if self.library_visible() {
            if let sdl3::event::Event::KeyDown {
                scancode: Some(sc),
                keymod,
                repeat,
                ..
            } = event
            {
                use sdl3::keyboard::Mod;
                if !keymod.intersects(Mod::LCTRLMOD | Mod::RCTRLMOD | Mod::LALTMOD | Mod::RALTMOD) {
                    return self.library.as_mut().is_some_and(|l| l.key(*sc, *repeat));
                }
            }
        }
        false
    }
    fn handle_menu(&mut self, event: MenuEvent) -> Option<MenuPulse> {
        if self.library_visible() {
            self.library.as_mut().and_then(|l| l.menu(event))
        } else {
            None
        }
    }
    fn take_action(&mut self) -> Option<OverlayAction> {
        self.library.as_mut().and_then(|l| l.take_action())
    }
    fn session_phase(&mut self, phase: SessionPhase) {
        let Some(lib) = &mut self.library else { return };
        match phase {
            SessionPhase::Connecting => lib.set_connecting(true),
            SessionPhase::Streaming => {
                lib.in_stream = true;
                lib.set_connecting(false);
            }
            SessionPhase::Failed(msg) => lib.session_error(msg),
            SessionPhase::Ended(None) => {
                lib.in_stream = false;
                lib.set_connecting(false);
            }
            SessionPhase::Ended(Some(reason)) => lib.session_error(reason),
        }
    }
    fn frame(&mut self, ctx: &FrameCtx) -> Result<Option<OverlayFrame>> {
        // The console library: full-screen, opaque, and always dirty (the aurora
        // animates every frame — the GPU port's whole point).
        if self.library_visible() {
            let next = 1 - self.current;
            self.ensure_slot(next, ctx.width, ctx.height)?;
            let Self {
                gpu,
                slots,
                library,
                fonts,
                ..
            } = self;
            let gpu = gpu.as_mut().expect("init ran");
            let slot = slots[next].as_mut().expect("just ensured");
            let lib = library.as_mut().expect("library_visible");
            let fonts = fonts.as_mut().expect("init ran");
            fonts.chip_text = Some(ctx.pad.map_or(
                "No controller — keyboard works too".to_string(),
                str::to_owned,
            ));
            lib.sync();
            lib.render(slot.surface.canvas(), ctx.width, ctx.height, fonts);
            gpu.context.flush_surface_with_texture_state(
                &mut slot.surface,
                &gpu::FlushInfo::default(),
                Some(&skvk::mutable_texture_states::new_vulkan(
                    skvk::ImageLayout::SHADER_READ_ONLY_OPTIMAL,
                    gpu.queue_family_index,
                )),
            );
            gpu.context.submit(None);
            self.current = next;
            self.drawn = Drawn::default(); // stream chrome re-renders when it returns
            let slot = self.slots[next].as_ref().expect("just rendered");
            return Ok(Some(OverlayFrame {
                image: slot.image,
                view: slot.view,
                width: slot.width,
                height: slot.height,
            }));
        }
        if ctx.stats.is_none() && ctx.hint.is_none() {
            self.drawn = Drawn::default(); // forget content so re-show re-renders
            return Ok(None);
        }
        let want = Drawn {
            width: ctx.width,
            height: ctx.height,
            stats: ctx.stats.map(str::to_owned),
            hint: ctx.hint.map(str::to_owned),
        };
        if want == self.drawn {
            // Unchanged — hand the presenter the already-rendered image.
            return Ok(self.slots[self.current].as_ref().map(|s| OverlayFrame {
                image: s.image,
                view: s.view,
                width: s.width,
                height: s.height,
            }));
        }
        // Render into the OTHER slot — the presenter may still be sampling the current
        // one (one frame in flight; the ring of two is exactly deep enough).
        let next = 1 - self.current;
        self.ensure_slot(next, ctx.width, ctx.height)?;
        let gpu = self.gpu.as_mut().expect("init ran");
        let slot = self.slots[next].as_mut().expect("just ensured");
        let canvas = slot.surface.canvas();
        canvas.clear(Color4f::new(0.0, 0.0, 0.0, 0.0));
        let font = self.font.as_ref().expect("init ran");
        if let Some(stats) = &want.stats {
            draw_osd_panel(canvas, font, stats, 12.0, 12.0);
        }
        if let Some(hint) = &want.hint {
            draw_hint_pill(canvas, font, hint, ctx.width, ctx.height);
        }
        // Flush on the shared queue, ending in SHADER_READ_ONLY on our family — the
        // layout the presenter's composite samples (its own barrier covers visibility).
        gpu.context.flush_surface_with_texture_state(
            &mut slot.surface,
            &gpu::FlushInfo::default(),
            Some(&skvk::mutable_texture_states::new_vulkan(
                skvk::ImageLayout::SHADER_READ_ONLY_OPTIMAL,
                gpu.queue_family_index,
            )),
        );
        gpu.context.submit(None);
        self.current = next;
        self.drawn = want;
        Ok(Some(OverlayFrame {
            image: slot.image,
            view: slot.view,
            width: slot.width,
            height: slot.height,
        }))
    }
 }
 impl SkiaOverlay {
    /// Make `slots[i]` a render target of exactly `width`×`height` (rebuilt on resize).
    fn ensure_slot(&mut self, i: usize, width: u32, height: u32) -> Result<()> {
        if self.slots[i]
            .as_ref()
            .is_some_and(|s| s.width == width && s.height == height)
        {
            return Ok(());
        }
        let gpu = self.gpu.as_mut().expect("init ran");
        if let Some(old) = self.slots[i].take() {
            // Any in-flight sampling of THIS slot ended two presents ago (the ring
            // alternates and the presenter waits its fence before each record).
            unsafe { gpu.device.destroy_image_view(old.view, None) };
        }
        let info =
            skia_safe::ImageInfo::new_n32_premul((width.max(1) as i32, height.max(1) as i32), None);
        let mut surface = gpu::surfaces::render_target(
            &mut gpu.context,
            gpu::Budgeted::Yes,
            &info,
            None,
            SurfaceOrigin::TopLeft,
            None,
            false,
            None,
        )
        .context("Skia render-target surface")?;
        let texture = gpu::surfaces::get_backend_texture(
            &mut surface,
            skia_safe::surface::BackendHandleAccess::FlushRead,
        )
        .context("surface backend texture")?;
        let image_info = texture
            .vulkan_image_info()
            .context("backend texture is not Vulkan")?;
        let image = avk::Image::from_raw(*image_info.image() as u64);
        let view = unsafe {
            gpu.device.create_image_view(
                &avk::ImageViewCreateInfo::default()
                    .image(image)
                    .view_type(avk::ImageViewType::TYPE_2D)
                    .format(avk::Format::from_raw(image_info.format as i32))
                    .subresource_range(
                        avk::ImageSubresourceRange::default()
                            .aspect_mask(avk::ImageAspectFlags::COLOR)
                            .level_count(1)
                            .layer_count(1),
                    ),
                None,
            )
        }
        .context("overlay image view")?;
        self.slots[i] = Some(Slot {
            surface,
            image,
            view,
            width,
            height,
        });
        Ok(())
    }
 }
 /// The stats OSD: a translucent rounded panel, one text line per `\n` (the GTK OSD's
 /// look, minus the toolkit).
 fn draw_osd_panel(canvas: &Canvas, font: &Font, text: &str, x: f32, y: f32) {
    let (_, metrics) = font.metrics();
    let line_h = metrics.descent - metrics.ascent + metrics.leading;
    let lines: Vec<&str> = text.lines().collect();
    let widest = lines
        .iter()
        .map(|l| font.measure_str(l, None).0)
        .fold(0.0f32, f32::max);
    let (pad_x, pad_y) = (10.0, 8.0);
    let panel = Rect::from_xywh(
        x,
        y,
        widest + 2.0 * pad_x,
        line_h * lines.len() as f32 + 2.0 * pad_y,
    );
    canvas.draw_rrect(
        RRect::new_rect_xy(panel, 8.0, 8.0),
        &Paint::new(Color4f::new(0.0, 0.0, 0.0, 0.62), None),
    );
    let text_paint = Paint::new(Color4f::new(1.0, 1.0, 1.0, 0.92), None);
    for (i, line) in lines.iter().enumerate() {
        canvas.draw_str(
            line,
            Point::new(x + pad_x, y + pad_y - metrics.ascent + line_h * i as f32),
            font,
            &text_paint,
        );
    }
 }
 /// The capture hint: a centered pill near the bottom edge (the GTK hint's position).
 fn draw_hint_pill(canvas: &Canvas, font: &Font, text: &str, width: u32, height: u32) {
    let (_, metrics) = font.metrics();
    let line_h = metrics.descent - metrics.ascent;
    let text_w = font.measure_str(text, None).0;
    let (pad_x, pad_y) = (14.0, 8.0);
    let w = text_w + 2.0 * pad_x;
    let h = line_h + 2.0 * pad_y;
    let x = (width as f32 - w) / 2.0;
    let y = height as f32 - h - 24.0;
    canvas.draw_rrect(
        RRect::new_rect_xy(Rect::from_xywh(x, y, w, h), h / 2.0, h / 2.0),
        &Paint::new(Color4f::new(0.0, 0.0, 0.0, 0.62), None),
    );
    canvas.draw_str(
        text,
        Point::new(x + pad_x, y + pad_y - metrics.ascent),
        font,
        &Paint::new(Color4f::new(1.0, 1.0, 1.0, 0.92), None),
    );
 }
@@ -0,0 +1,22 @@
 [package]
 name = "pf-ffvk"
 description = "Bindgen shim for FFmpeg's Vulkan hwcontext (libavutil/hwcontext_vulkan.h) — the AVVulkanDeviceContext/AVVkFrame surface ffmpeg-sys-next doesn't bind; enables Vulkan Video decode straight onto the presenter's device"
 version.workspace = true
 edition.workspace = true
 rust-version.workspace = true
 license.workspace = true
 authors.workspace = true
 repository.workspace = true
 # The bindings are generated at build time from the SYSTEM headers (libavutil +
 # vulkan-headers), so they are ABI-exact for the installed FFmpeg — including the
 # FF_API_VULKAN_* deprecation gates that change AVVulkanDeviceContext's layout between
 # FFmpeg builds. This is deliberately not hand-transcribed.
 [target.'cfg(target_os = "linux")'.dependencies]
 ash = { version = "0.38", features = ["loaded"] }
 [build-dependencies]
 # Same bindgen configuration as ffmpeg-sys-next (runtime = dlopen libclang).
 bindgen = { version = "0.72", features = ["runtime"], default-features = false }
 pkg-config = "0.3"
@@ -0,0 +1,86 @@
 //! Generate bindings for `libavutil/hwcontext_vulkan.h` against the SYSTEM headers.
 //!
 //! ffmpeg-sys-next binds a curated header list that omits every hwcontext_*.h; the
 //! Vulkan hwcontext structs (`AVVulkanDeviceContext`, `AVVkFrame`) are what let us run
 //! FFmpeg's Vulkan Video decoder on the presenter's own VkDevice and read the decoded
 //! VkImages back. Their layout depends on compile-time FF_API_* deprecation gates in
 //! libavutil/version.h, so bindgen over the installed header is the only ABI-safe
 //! source of truth — hand transcription would silently skew on the next FFmpeg bump.
 //!
 //! Non-Linux targets get an empty file: the workspace builds on macOS (clients/apple is
 //! the client there), and this shim is Linux-client plumbing only.
 use std::env;
 use std::path::PathBuf;
 fn main() {
    println!("cargo:rerun-if-changed=wrapper.h");
    let out = PathBuf::from(env::var("OUT_DIR").unwrap()).join("bindings.rs");
    if env::var("CARGO_CFG_TARGET_OS").as_deref() != Ok("linux") {
        std::fs::write(&out, "// pf-ffvk: Linux-only, empty on this target\n").unwrap();
        return;
    }
    // Include paths from pkg-config (libavutil for the hwcontext header; the Vulkan
    // headers usually live in /usr/include, but honor a registered vulkan.pc too).
    // PF_FFVK_VULKAN_INCLUDE prepends an explicit Vulkan-Headers include dir — for
    // cross builds and boxes without the system package.
    println!("cargo:rerun-if-env-changed=PF_FFVK_VULKAN_INCLUDE");
    let mut includes: Vec<PathBuf> = Vec::new();
    if let Ok(dir) = env::var("PF_FFVK_VULKAN_INCLUDE") {
        includes.push(PathBuf::from(dir));
    }
    let avutil = pkg_config::Config::new()
        .cargo_metadata(false)
        .probe("libavutil")
        .expect("pkg-config: libavutil not found — install the FFmpeg dev package");
    includes.extend(avutil.include_paths);
    if let Ok(vk) = pkg_config::Config::new()
        .cargo_metadata(false)
        .probe("vulkan")
    {
        includes.extend(vk.include_paths);
    }
    let mut builder = bindgen::Builder::default()
        .header("wrapper.h")
        // The whole point of this crate: the Vulkan hwcontext surface…
        .allowlist_type("AVVulkan.*")
        .allowlist_type("AVVkFrame.*")
        .allowlist_function("av_vk_frame_alloc")
        .allowlist_function("av_vkfmt_from_pixfmt")
        // The feature structs chained into AVVulkanDeviceContext.device_features (plain
        // vulkan.h types; generating them here keeps the chain in one type system).
        .allowlist_type("VkPhysicalDeviceVulkan11Features")
        .allowlist_type("VkPhysicalDeviceVulkan12Features")
        .allowlist_type("VkPhysicalDeviceVulkan13Features")
        // AVVulkanFramesContext.img_flags values (plane views need MUTABLE_FORMAT).
        .allowlist_type("VkImageCreateFlagBits")
        // Timeline-semaphore wait — the pump measures true GPU decode completion.
        .allowlist_type("VkSemaphoreWaitInfo")
        .allowlist_type("PFN_vkWaitSemaphores")
        .allowlist_type("PFN_vkGetDeviceProcAddr")
        // …plus nothing else of FFmpeg: the core types these structs reference only
        // ever appear behind pointers here, so keep them opaque instead of duplicating
        // ffmpeg-sys-next's definitions (callers cast pointers between the crates).
        .opaque_type("AVHWDeviceContext")
        .opaque_type("AVHWFramesContext")
        .opaque_type("AVBufferRef")
        .opaque_type("AVFrame")
        .derive_debug(false)
        .layout_tests(true);
    for dir in &includes {
        builder = builder.clang_arg(format!("-I{}", dir.display()));
    }
    let bindings = builder.generate().expect(
        "bindgen over libavutil/hwcontext_vulkan.h failed — is `vulkan-headers` installed? \
         (the header includes <vulkan/vulkan.h>)",
    );
    bindings.write_to_file(&out).unwrap();
    // The av_vk_* symbols live in libavutil, which ffmpeg-sys-next already links into
    // every consumer of this crate; no extra link flags needed. Emitting the lib anyway
    // keeps `cargo test -p pf-ffvk` linking standalone.
    println!("cargo:rustc-link-lib=avutil");
 }
@@ -0,0 +1,91 @@
 //! FFmpeg's Vulkan hwcontext surface (`AVVulkanDeviceContext`, `AVVulkanFramesContext`,
 //! `AVVkFrame`), bindgen-generated from the system headers at build time — see build.rs
 //! for why this must not be hand-transcribed.
 //!
 //! The raw bindings use vulkan.h's own handle types (pointers on 64-bit). The [`ash`]
 //! conversion helpers below cross between them and ash's u64-newtype handles; both sides
 //! are the same underlying Vulkan object handles, so the casts are value-preserving.
 #![allow(non_upper_case_globals)]
 #![allow(non_camel_case_types)]
 #![allow(non_snake_case)]
 #![allow(clippy::missing_safety_doc)]
 // bindgen's layout tests deref-null-pointer by design; silence the lints they trip.
 #![allow(deref_nullptr)]
 #![allow(unnecessary_transmutes)]
 #[cfg(target_os = "linux")]
 include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
 /// Conversions between the generated vulkan.h handle types and ash's.
 #[cfg(target_os = "linux")]
 pub mod ashx {
    use super::*;
    use ash::vk::Handle as _;
    /// vulkan.h non-dispatchable handles are `*mut T` on 64-bit; ash's are `u64`
    /// newtypes. Same bits either way.
    pub fn image(h: VkImage) -> ash::vk::Image {
        ash::vk::Image::from_raw(h as u64)
    }
    pub fn semaphore(h: VkSemaphore) -> ash::vk::Semaphore {
        ash::vk::Semaphore::from_raw(h as u64)
    }
    pub fn image_layout(l: VkImageLayout) -> ash::vk::ImageLayout {
        ash::vk::ImageLayout::from_raw(l as i32)
    }
    // --- ash → vulkan.h (filling AVVulkanDeviceContext) ---------------------------------
    pub fn to_instance(h: ash::vk::Instance) -> VkInstance {
        h.as_raw() as VkInstance
    }
    pub fn to_physical_device(h: ash::vk::PhysicalDevice) -> VkPhysicalDevice {
        h.as_raw() as VkPhysicalDevice
    }
    pub fn to_device(h: ash::vk::Device) -> VkDevice {
        h.as_raw() as VkDevice
    }
    /// ash's loader-level `vkGetInstanceProcAddr` as the header's PFN type. Both are the
    /// same C ABI function pointer (`extern "system"` == `extern "C"` on the platforms
    /// this crate builds for).
    pub fn to_get_proc_addr(
        f: unsafe extern "system" fn(
            ash::vk::Instance,
            *const std::ffi::c_char,
        ) -> ash::vk::PFN_vkVoidFunction,
    ) -> PFN_vkGetInstanceProcAddr {
        unsafe { std::mem::transmute(f) }
    }
 }
 #[cfg(all(test, target_os = "linux"))]
 mod tests {
    use super::*;
    /// The allocator runs (links against the system libavutil) and the struct is
    /// readable at the offsets bindgen computed — sem_value zero-initialized.
    #[test]
    fn vk_frame_alloc_links_and_zeroes() {
        unsafe {
            let f = av_vk_frame_alloc();
            assert!(!f.is_null(), "av_vk_frame_alloc returned NULL");
            assert_eq!((*f).sem_value[0], 0);
            assert_eq!((*f).queue_family[0], 0);
            // Leak the one test frame rather than binding av_free here.
        }
    }
    /// AV_NUM_DATA_POINTERS-sized arrays came through with the right length.
    #[test]
    fn frame_arrays_are_av_num_data_pointers() {
        let f: AVVkFrame = unsafe { std::mem::zeroed() };
        assert_eq!(f.img.len(), 8);
        assert_eq!(f.sem_value.len(), 8);
    }
 }
@@ -0,0 +1,3 @@
 /* The one header ffmpeg-sys-next's bindgen list omits: FFmpeg's Vulkan hwcontext.
 * Pulls <vulkan/vulkan.h> (the vulkan-headers package) transitively. */
 #include <libavutil/hwcontext_vulkan.h>
@@ -0,0 +1,26 @@
 [package]
 name = "pf-presenter"
 description = "The Vulkan session presenter — SDL3 window, ash swapchain, frame present, input capture; the stage-2 presenter of punktfunk-planning linux-client-rearchitecture.md"
 version.workspace = true
 edition.workspace = true
 rust-version.workspace = true
 license.workspace = true
 authors.workspace = true
 repository.workspace = true
 # Same Linux gating as the rest of the client stack.
 [target.'cfg(target_os = "linux")'.dependencies]
 pf-client-core = { path = "../pf-client-core" }
 # AVVkFrame access (Vulkan Video frames: live sync state under the frames lock).
 pf-ffvk = { path = "../pf-ffvk" }
 punktfunk-core = { path = "../punktfunk-core", features = ["quic"] }
 # `loaded` dlopens libvulkan at runtime (no link-time dependency — GPU-less boxes still
 # start and fail into a clean error). `ash` on sdl3 types SDL_Vulkan_CreateSurface with
 # ash 0.38 handles so the surface hands over without transmutes.
 ash = { version = "0.38", features = ["loaded"] }
 sdl3 = { version = "0.18", features = ["hidapi", "ash"] }
 async-channel = "2"
 anyhow = "1"
 tracing = "0.1"
--- a/Show More
+++ b/Show More