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
115 changed files with 11403 additions and 5332 deletions
@@ -103,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);
@@ -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
@@ -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.2"
+version = "0.8.3"

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

 [[package]]
 name = "loss-harness"
-version = "0.8.2"
+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.2"
+version = "0.8.3"
 dependencies = [
 "android_logger",
 "jni",
@@ -2923,30 +3014,37 @@ dependencies = [

 [[package]]
 name = "punktfunk-client-linux"
-version = "0.8.2"
+version = "0.8.3"
 dependencies = [
 "anyhow",
 "async-channel",
- "ffmpeg-next",
 "gtk4",
- "khronos-egl",
 "libadwaita",
- "mdns-sd",
- "opus",
- "pipewire",
+ "pf-client-core",
+ "punktfunk-core",
+ "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.2"
+version = "0.8.3"
 dependencies = [
 "anyhow",
 "async-channel",
@@ -2969,7 +3067,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-core"
-version = "0.8.2"
+version = "0.8.3"
 dependencies = [
 "aes-gcm",
 "bytes",
@@ -3000,7 +3098,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-host"
-version = "0.8.2"
+version = "0.8.3"
 dependencies = [
 "aes",
 "aes-gcm",
@@ -3072,7 +3170,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-probe"
-version = "0.8.2"
+version = "0.8.3"
 dependencies = [
 "anyhow",
 "mdns-sd",
@@ -3086,7 +3184,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-tray"
-version = "0.8.2"
+version = "0.8.3"
 dependencies = [
 "anyhow",
 "ksni",
@@ -3371,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"
@@ -3691,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",
@@ -3813,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"
@@ -3898,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"
@@ -4033,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"
@@ -4218,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"
@@ -4226,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",
@@ -4241,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"
@@ -4266,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"
@@ -4287,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"
@@ -5330,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"
@@ -5389,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.2"
+version = "0.8.3"
 edition = "2021"
 rust-version = "1.82"
 license = "MIT OR Apache-2.0"
@@ -10,7 +10,7 @@
      "name": "MIT OR Apache-2.0",
      "identifier": "MIT OR Apache-2.0"
    },
-    "version": "0.8.2"
+    "version": "0.8.3"
  },
  "paths": {
    "/api/v1/clients": {
@@ -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).
@@ -327,7 +327,7 @@ private fun buildSettingsRows(s: Settings, update: (Settings) -> Unit): List<GpR
        ) { update(s.copy(hdrEnabled = it)) },
        toggle(
            "lowLatency", null, "Low-latency mode",
-            "Experimental — aggressive decoder and system tuning. Turn off if the stream stutters or glitches.",
+            "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)) },

@@ -55,14 +55,18 @@ data class Settings(
     */
    val libraryEnabled: Boolean = true,
    /**
-     * "Low-latency mode (experimental)" — the master switch over the latency overhaul: decoder
-     * ranking + per-SoC vendor keys + the async decode loop (native), 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.) Off (default): the original decode pipeline, kept as the
-     * known-good baseline until the aggressive stack is proven per-device.
+     * "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 = false,
+    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
@@ -100,7 +104,7 @@ 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, false),
+        lowLatencyMode = prefs.getBoolean(K_LOW_LATENCY, true),
        autoWakeEnabled = prefs.getBoolean(K_AUTO_WAKE, true),
    )

@@ -142,12 +146,16 @@ class SettingsStore(context: Context) {
        const val K_LIBRARY = "library_enabled"

        /**
-         * Deliberately NOT the original `"low_latency_mode"` key: that one shipped default-ON, so
-         * any install that ever saved settings persisted `true` — under the old key, flipping the
-         * default to off would leave exactly the regressed devices stuck on the overhaul. The fresh
-         * key restarts everyone at the safe default; the stale one is abandoned unread.
+         * 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_experimental"
+        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. */
@@ -326,10 +326,10 @@ private fun DisplaySettings(s: Settings, update: (Settings) -> Unit, context: an
        ) { c -> update(s.copy(compositor = c)) }

        ToggleRow(
-            title = "Low-latency mode (experimental)",
-            subtitle = "Aggressive decoder and system tuning (per-device decoder selection, async " +
-                "decode, HDMI game mode). Can lower latency, but may stutter or glitch on " +
-                "some devices — turn off if the stream misbehaves.",
+            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)) },
        )
@@ -65,10 +65,10 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
    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 (experimental)" master toggle, resolved once for the session. Off (the
-    // default) runs the original decode pipeline; on enables the aggressive stack — decoder
-    // ranking + vendor keys + async loop (native side), HDMI ALLM below, game-tagged audio, and
-    // DSCP marking (applied earlier, at connect).
+    // "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.
@@ -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.
@@ -39,8 +39,8 @@ const PENDING_SPLIT_CAP: usize = 256;
 /// 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 (experimental)" toggle is ON — off, the sync loop always runs (the
-/// original pipeline).
+/// 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
@@ -52,10 +52,10 @@ pub(crate) struct DecodeOptions {
    /// 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 (experimental)" master toggle. On ⇒ the full overhaul: async
+    /// 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 (default) ⇒ the original pre-overhaul pipeline, kept as the known-good
-    /// baseline while the overhaul is experimental.
+    /// 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.
@@ -409,10 +409,10 @@ fn create_codec(mime: &str, preferred: Option<&str>) -> Option<MediaCodec> {

 /// Apply the low-latency MediaFormat keys for `codec_name`.
 ///
-/// `aggressive` = the "Low-latency mode (experimental)" master toggle. **Off** (default) ⇒ 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 known-good baseline
-/// (the profile every device streamed with before the overhaul). **On** ⇒ the Moonlight-parity
+/// `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.
@@ -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
@@ -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
-immediately — for scripting and the Steam Deck launcher) with optional `--launch <id>` (ask the
-host to launch that library title, id from `--library`), `--browse host[:port]` (the gamepad
-library launcher; `--mgmt <port>` overrides the management port it fetches from),
-`--pair <PIN> --connect host[:port]` (run the pairing ceremony headlessly), and
-`--library host[:mgmt_port]` (print a host's game library headlessly). Force a decoder with
-`PUNKTFUNK_DECODER=software|vaapi`; `PUNKTFUNK_FAKE_LIBRARY=<file.json>` feeds the launcher
-canned entries for UI work with no host.
+The binary is named **`punktfunk-client`** — the relm4/libadwaita desktop shell (hosts,
+pairing/trust, settings, the desktop library page). Every stream and the console game
+library run in the sibling **`punktfunk-session`** Vulkan binary; the shell spawns it
+for connects, and `--connect`/`--browse` on the shell exec it directly (so the Decky
+wrapper keeps working unchanged). Headless flags stay in the shell:
+`--pair <PIN> --connect host[:port]` (pairing ceremony), `--wake host[:port]`, and
+`--library host[:mgmt_port]` (print a host's game library).

 ## Layout

 ```
 src/
-  main.rs · app.rs        entry point, GTK application, primary menu, CSS
-  cli.rs                  CLI paths (--connect/--launch, --browse, headless --pair, screenshot scenes)
-  ui_hosts.rs             host card grids (saved + discovered) · add-host dialog · banner
+  main.rs · app.rs        entry point, relm4 AppModel (window, trust gate, session child
+                          lifecycle, typed messages), primary menu, CSS
+  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
-  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)
+  spawn.rs                the session-child plumbing (stdout contract → AppMsg)
 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
-//! dialogs live in `ui_trust`, session launch in `launch`, CLI entry paths in `cli`, the
-//! hosts grid in `ui_hosts`.
+//! The application shell as a relm4 component tree (phase 5 of punktfunk-planning
+//! `linux-client-rearchitecture.md`): [`AppModel`] owns the window, navigation, trust
+//! 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::ui_hosts::{ConnectRequest, HostsCallbacks, HostsUi};
+use crate::spawn::{self, SpawnOpts};
+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,80 +43,480 @@ 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.
-    pub busy: std::cell::Cell<bool>,
-    /// Steam Deck / Gaming-Mode launch: fullscreen the window (chrome-less) when a stream starts.
-    pub fullscreen: bool,
-    /// Quit when the session ends (Gaming-Mode `--connect` launch): the app IS the stream —
-    /// exiting ends the Steam "game" so the Deck returns to Gaming Mode instead of stranding
-    /// the user on the client's own hosts page.
-    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>>>,
+    hosts: Controller<HostsPage>,
+    /// One session child at a time — connects while one runs are ignored.
+    busy: bool,
+    /// The request-access "waiting for approval" dialog, closed on the first child
+    /// event. A shared slot (not a message): dialogs are main-thread GTK objects and
+    /// `AppMsg` must stay `Send` for the session child's reader thread.
+    waiting: Rc<RefCell<Option<adw::AlertDialog>>>,
 }

-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>> {
-        self.hosts.borrow().clone()
-    }
-
-    pub fn browse_ui(&self) -> Option<Rc<crate::ui_gamepad_library::LauncherUi>> {
-        self.browse.borrow().clone()
-    }
-
-    /// Surface a connect failure: the launcher in browse mode, else the hosts page banner
-    /// (toast fallback pre-build).
-    pub fn connect_error(&self, msg: &str) {
-        match (self.browse_ui(), self.hosts_ui()) {
-            (Some(l), _) => l.show_error(msg),
-            (_, Some(h)) => h.show_error(msg),
-            _ => self.toast(msg),
+    fn close_waiting(&mut self) {
+        if let Some(w) = self.waiting.borrow_mut().take() {
+            w.close();
        }
    }
+
+    /// Measure the path to a host over the real data plane: connect, burst probe filler
+    /// 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));
+
+        let (tx, rx) =
+            async_channel::bounded::<Result<punktfunk_core::client::ProbeOutcome, String>>(1);
+        let identity = self.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: 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(_) => {}
+            }
+        });
+    }
 }

 pub fn run() -> glib::ExitCode {
@@ -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
-    // only see the virtual X360 pad. Right for games, wrong for us: capturing the Deck's
-    // 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).
+    // physical pad Steam Input has virtualized; the Settings controller list needs the
+    // real devices (same rationale as the session binary).
    for var in [
        "SDL_GAMECONTROLLER_IGNORE_DEVICES",
        "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT",
@@ -133,160 +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]`.
-    // Used by the Decky plugin (a GTK dialog can't pop under gamescope) and for scripting.
+    // Headless paths (no GTK window).
    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
-    // launch its own primary instance instead of forwarding to a still-registered name.
+    // Screenshot mode launches the app once per scene back-to-back; NON_UNIQUE keeps
+    // 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();
-    // One SDL context for the whole process: `activate` fires again on every subsequent
-    // launch forwarded to this already-running singleton (another `--connect`, the desktop
-    // icon clicked twice, …). SDL only ever lets the FIRST thread that calls `sdl3::init()`
-    // hold the "main thread" — a second `GamepadService::start()` from a later `activate`
-    // would spawn a new thread that fails that check forever. Starting it once here and
-    // cloning it into each `build_ui` keeps the worker thread (and its pad state) shared
-    // across every window instead.
+    let adw_app = builder.build();
+    // One SDL context for the whole process, started while single-threaded.
    let gamepad = crate::gamepad::GamepadService::start();
-    app.connect_activate(move |gtk_app| build_ui(gtk_app, gamepad.clone()));
-    // 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, gamepad: crate::gamepad::GamepadService) {
-    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,
-        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_wake_connect: {
-                let app = app.clone();
-                Rc::new(move |req| crate::ui_trust::wake_and_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 app = relm4::RelmApp::from_app(adw_app).with_args(Vec::new());
+    app.run::<AppModel>(AppInit { gamepad });
+    glib::ExitCode::SUCCESS
 }

 fn load_css() {
@@ -301,54 +580,23 @@ fn load_css() {
    }
 }

-/// Window actions behind the hosts page's header: the primary (hamburger) menu entries
-/// plus the "+" add-host button and the empty state's call to action.
-fn install_actions(app: &Rc<App>, hosts: &Rc<HostsUi>) {
-    let add = |name: &str, f: Box<dyn Fn()>| {
+/// Window actions behind the hosts page's header (the primary menu + "+") — thin
+/// forwards into the message loop.
+fn install_actions(window: &adw::ApplicationWindow, sender: &ComponentSender<AppModel>) {
+    let add = |name: &str, msg: fn() -> AppMsg| {
        let action = gio::SimpleAction::new(name, None);
-        action.connect_activate(move |_, _| f());
-        app.window.add_action(&action);
+        let sender = sender.clone();
+        action.connect_activate(move |_, _| sender.input(msg()));
+        action
    };
-    {
-        let app = app.clone();
-        add(
-            "preferences",
-            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()));
-    }
+    window.add_action(&add("preferences", || AppMsg::ShowPreferences));
+    window.add_action(&add("shortcuts", || AppMsg::ShowShortcuts));
+    window.add_action(&add("about", || AppMsg::ShowAbout));
+    window.add_action(&add("add-host", || AppMsg::ShowAddHost));
 }

-/// The Keyboard Shortcuts window (menu + the shortcuts scene). GtkShortcutsWindow is
-/// builder-XML-first, so it's assembled from a snippet rather than widget calls.
+/// The Keyboard Shortcuts window — the SESSION window's keys (the shell itself has
+/// none); kept here as discoverable documentation.
 pub fn shortcuts_window(parent: &adw::ApplicationWindow) -> gtk::ShortcutsWindow {
    const UI: &str = r#"
 <interface>
@@ -358,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>
@@ -397,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
-//! screenshot scenes.
+//! Command-line entry paths: argv helpers, the headless flows (pair/wake/library), the
+//! exec handoff to `punktfunk-session` for `--connect`/`--browse`, and the CI screenshot
+//! scenes.

-use crate::app::App;
-use crate::ui_hosts::ConnectRequest;
+use crate::app::AppModel;
+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.
-/// The Decky wrapper passes `--fullscreen`; we also honor the Deck/gamescope env as a fallback
-/// so a manual launch under Gaming Mode does the right thing too.
+/// Fullscreen the shell — the Gaming-Mode fallback for a bare launch (streams and the
+/// console library exec the session binary, which handles its own fullscreen).
 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
-/// (scripting + headless testing). Trust follows the same rules as a manual entry: a host
-/// 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
+/// `--wake host[:port]` — send a Wake-on-LAN magic packet to a saved host and exit,
+/// without opening a window. 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
-/// that the library HTTP path works against a real host). The pin comes from `--fp HEX`
-/// when given, else the known-hosts store (matched by address), else none (TOFU-accept).
+/// mTLS + pinned-fingerprint client, no GTK window. The pin comes from `--fp HEX` 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
-/// `PF_SHOT_READY` once it has had a moment to map + settle so the driver knows when to capture.
-/// When `PUNKTFUNK_SHOT_OUT=/path.png` is set the app CAPTURES ITSELF first (widget snapshot →
-/// gsk render → PNG, see `save_png`) — no Xvfb/ImageMagick needed, and libadwaita dialogs are
-/// in-window overlays so they land in the frame. No `NativeClient` or session is created. The
-/// stream scene is deliberately absent — its page requires a live connector (`ui_stream::new`
-/// takes an `Arc<NativeClient>`).
-pub fn run_shot(app: Rc<App>, scene: &str) {
-    // A plausible host for the trust/pair dialogs (fp_hex is 64 hex chars, like a real SHA-256).
+/// Render one mock-populated, host-free scene over the already-presented window, then
+/// print `PF_SHOT_READY` once it has settled. When `PUNKTFUNK_SHOT_OUT=/path.png` is set
+/// the app CAPTURES ITSELF (widget snapshot → gsk render → PNG) — no Xvfb/ImageMagick
+/// needed. The stream and gamepad-library scenes are gone with the pages (both live in
+/// the session binary now).
+pub fn run_shot(ctx: &ShotCtx, scene: &str) {
+    let sender = &ctx.sender;
+    // A plausible host for the trust/pair dialogs (fp_hex = 64 hex chars).
    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
-        // driver seeds. On top, inject synthetic adverts through the same path the mDNS
-        // stream feeds: one matching the seeded saved host (ONLINE pip + dedup out of the
-        // discovered grid) and one unknown pair=required host (PIN pill).
+        // Saved hosts come from the seeded known-hosts store; on top, inject synthetic
+        // adverts through the same path the mDNS stream feeds.
        "hosts" | "02-hosts" => {
-            if let Some(h) = app.hosts_ui() {
-                h.inject_advert(mock_advert(
-                    "mock-online",
-                    "Living Room PC",
-                    "192.168.1.42",
-                    "9f8e7d6c5b4a39281706f5e4d3c2b1a0998877665544332211ffeeddccbbaa00",
-                ));
-                h.inject_advert(mock_advert(
-                    "mock-new",
-                    "steamdeck",
-                    "192.168.1.77",
-                    "00aabbccddeeff112233445566778899a0b1c2d3e4f5061728394a5b6c7d8e9f",
-                ));
-            }
+            let _ = hosts.send(HostsMsg::Advert(mock_advert(
+                "mock-online",
+                "Living Room PC",
+                "192.168.1.42",
+                "9f8e7d6c5b4a39281706f5e4d3c2b1a0998877665544332211ffeeddccbbaa00",
+            )));
+            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() {
-                h.show_add_host();
-            }
+            let _ = hosts.send(HostsMsg::ShowAddHost);
        }
        "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
-        // for a loaded poster (the real poster path, minus the network).
+        // no-art placeholders, and one solid-color texture standing in for a poster.
        "library" | "08-library" => {
            let (games, art) = mock_library();
-            crate::ui_library::open_mock(app.clone(), mock_req(), games, art);
-        }
-        // The gamepad launcher (`--browse`) with the same injected entries — cursor sits
-        // at 1 so both recede directions show; aurora + easing render frozen (shot mode).
-        "gamepad-library" | "09-gamepad-library" => {
-            let (games, art) = mock_library();
-            let ui = crate::ui_gamepad_library::open_mock(app.clone(), mock_req(), games, art);
-            app.nav.push(&ui.page);
-            *app.browse.borrow_mut() = Some(ui);
+            crate::ui_library::open_mock(
+                &ctx.nav,
+                ctx.identity.clone(),
+                sender,
+                mock_req(),
+                games,
+                art,
+            );
        }
        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
-        // stack windows on a live desktop. (The X11-fallback driver captures externally
-        // after READY and kills us itself.)
+        // Self-capture mode: the shot is on disk — exit so back-to-back scene runs
+        // don't stack windows on a live desktop.
        if self_capture.is_some() {
            std::process::exit(0);
        }
    });
 }

-/// The mock game set shared by the `library` and `gamepad-library` scenes: mixed stores
-/// exercising the badge set, plus one solid-colour poster texture.
+/// The mock game set for the `library` scene: mixed stores exercising the badge set,
+/// 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 →
-//! `GtkGraphicsOffload` present · PipeWire audio · SDL3 gamepads. The trust surface
-//! mirrors the Apple client: persistent identity, TOFU prompt with the host fingerprint,
-//! SPAKE2 PIN pairing.
+//! Hosts, pairing/trust, settings, and the desktop library page; every stream (and the
+//! console game library) runs in the spawned `punktfunk-session` Vulkan binary — the
+//! shell never touches video (punktfunk-planning `linux-client-rearchitecture.md`).
+
+// 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;
-#[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;
+mod spawn;
 #[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
-/// macOS (the Mac client lives in clients/apple).
+/// GTK4/SDL3 are Linux turf; this stub keeps `cargo build --workspace` green on macOS
+/// (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.
-pub fn open(app: Rc<App>, req: ConnectRequest) {
-    let state = build(app.clone(), req);
+/// Open the library page for a saved host and start the fetch. `mgmt_port` comes from
+/// the live mDNS `mgmt` TXT when the host is advertising (the hosts page resolves it).
+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, port);
+    let base = library::base_url(&state.req.addr, state.mgmt_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,76 +1,27 @@
-//! The trust gate and dialogs in front of every connect: TOFU, the SPAKE2 PIN ceremony,
-//! and delegated (request-access) approval.
+//! The trust dialogs in front of a connect: TOFU, the SPAKE2 PIN ceremony, and
+//! 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::launch::{start_session, start_session_with, StartOpts};
+use crate::app::{AppModel, AppMsg};
+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
-/// advertises `pair=optional` only when it accepts unpaired clients); the client renders
-/// its trust UI from that:
-///   1. PINNED RECONNECT — a host already pinned to this exact fingerprint connects silently.
-///   2. FINGERPRINT CHANGED — a host we know at this address but whose fingerprint no longer
-///      matches is the impostor signal: force re-pairing via the PIN ceremony, regardless of
-///      the advertised policy.
-///   3. NEW host — TOFU is offered only when the host advertised `pair=optional` (rule 3a);
-///      otherwise (pair=required, unknown/empty policy, or a manual entry) PIN pairing is
-///      mandatory (rule 3b).
-///
-/// A new host is never auto-connected without a stored pin or an explicit trust decision.
-pub fn initiate_connect(app: Rc<App>, req: ConnectRequest) {
-    if app.busy.get() {
-        return;
-    }
-    let known = trust::KnownHosts::load();
-    match &req.fp_hex {
-        Some(fp_hex) => {
-            if known.find_by_fp(fp_hex).is_some() {
-                // Rule 1: pinned fingerprint matches — silent connect.
-                start_session(app, req.clone(), trust::parse_hex32(fp_hex));
-            } else if known.find_by_addr(&req.addr, req.port).is_some() {
-                // Rule 2: we trust a host at this address but the fingerprint changed —
-                // the impostor signal. Re-pair via the PIN ceremony (no TOFU shortcut).
-                app.toast("Host fingerprint changed — re-pair with a PIN to continue");
-                pin_dialog(app, req);
-            } else if req.pair_optional {
-                // Rule 3a: the host opted into reduced-security TOFU; offer it alongside PIN.
-                tofu_dialog(app, req);
-            } else {
-                // Rule 3b: pair=required or unknown policy — offer no-PIN delegated approval
-                // (request access → approve in the console) or the PIN ceremony.
-                approval_dialog(app, req);
-            }
-        }
-        None => {
-            // Manual entry (no advertised fingerprint). A known address connects silently
-            // on its stored pin (rule 1); an unknown one must pair — request access (approve in
-            // the console) or use a PIN; never silent TOFU.
-            match known
-                .find_by_addr(&req.addr, req.port)
-                .and_then(|k| trust::parse_hex32(&k.fp_hex))
-            {
-                Some(pin) => start_session(app, req, Some(pin)),
-                None => approval_dialog(app, req), // rule 3b
-            }
-        }
-    }
-}
-
-/// Wake-and-wait: an **offline** saved host with a known MAC is sent a magic packet, then we poll
-/// mDNS until it comes back online — re-sending every few seconds up to a timeout — and dial it via
-/// [`initiate_connect`], **re-keying the saved record if the host woke on a new DHCP IP** (matched by
-/// fingerprint). A "Waking…" dialog lets the user cancel. Mirrors the Apple/Android `HostWaker` (a
-/// 90 s budget, resend every 6 s). The online path stays on the fast [`initiate_connect`]; this runs
-/// only from the hosts page's auto-wake when a saved host isn't advertising.
-pub fn wake_and_connect(app: Rc<App>, req: ConnectRequest) {
-    if app.busy.get() {
-        return;
-    }
-    let cancel = Rc::new(std::cell::Cell::new(false));
+/// Wake-and-wait: an **offline** saved host with a known MAC is sent a magic packet,
+/// then we poll mDNS until it comes back online — re-sending every few seconds up to a
+/// timeout — and route back into the trust gate, **re-keying the saved record if the
+/// host woke on a new DHCP IP** (matched by fingerprint). A "Waking…" dialog lets the
+/// user cancel. Mirrors the Apple/Android `HostWaker` (90 s budget, resend every 6 s).
+pub fn wake_and_connect(
+    window: &adw::ApplicationWindow,
+    sender: &ComponentSender<AppModel>,
+    req: ConnectRequest,
+) {
+    let cancel = std::rc::Rc::new(std::cell::Cell::new(false));
    let waiting = adw::AlertDialog::new(
        Some("Waking Host"),
        Some(&format!(
@@ -84,15 +35,15 @@ pub fn wake_and_connect(app: Rc<App>, req: ConnectRequest) {
        let cancel = cancel.clone();
        waiting.connect_response(Some("cancel"), move |_, _| cancel.set(true));
    }
-    waiting.present(Some(&app.window));
+    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);
-        // Fire the first packet now, then re-send on the resend cadence.
        crate::wol::wake(&req.mac, req.addr.parse().ok());
        let mut last_wake = Instant::now();
        loop {
@@ -104,7 +55,7 @@ pub fn wake_and_connect(app: Rc<App>, req: ConnectRequest) {
                crate::wol::wake(&req.mac, req.addr.parse().ok());
                last_wake = Instant::now();
            }
-            // Drain resolved adverts; a match (by fingerprint, else addr:port) means the host is up.
+            // Drain resolved adverts; a match (fingerprint, else addr:port) = it's up.
            while let Ok(ev) = events.try_recv() {
                let crate::discovery::DiscoveryEvent::Resolved(h) = ev else {
                    continue;
@@ -116,7 +67,8 @@ pub fn wake_and_connect(app: Rc<App>, req: ConnectRequest) {
                if matched {
                    waiting.close();
                    let mut req = req.clone();
-                    // Re-key on a new DHCP lease so this + future connects dial the live address.
+                    // Re-key on a new DHCP lease so this + future connects dial the
+                    // 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);
@@ -124,16 +76,16 @@ pub fn wake_and_connect(app: Rc<App>, req: ConnectRequest) {
                        req.addr = h.addr;
                        req.port = h.port;
                    }
-                    initiate_connect(app.clone(), req);
+                    sender.input(AppMsg::Connect(req));
                    return;
                }
            }
            if started.elapsed() >= budget {
                waiting.close();
-                app.toast(&format!(
+                sender.input(AppMsg::Toast(format!(
                    "Couldn't reach “{}” — is it powered and on the network?",
                    req.name
-                ));
+                )));
                return;
            }
            glib::timeout_future(Duration::from_millis(500)).await;
@@ -141,9 +93,8 @@ pub fn wake_and_connect(app: Rc<App>, req: ConnectRequest) {
    });
 }

-/// 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
-/// one 64-char run.
+/// The certificate fingerprint as grouped monospaced hex — 4-char groups over 2 lines,
+/// far easier to compare against the host's log than one 64-char run.
 fn grouped_fingerprint(fp: &str) -> String {
    let groups: Vec<&str> = fp
        .as_bytes()
@@ -157,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
-/// trust it (TOFU), run the PIN ceremony instead, or walk away.
-pub fn tofu_dialog(app: Rc<App>, req: ConnectRequest) {
+/// First contact with a discovered host that opted into TOFU: show the advertised
+/// fingerprint and let the user trust it, run the PIN ceremony instead, or walk away.
+/// 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"),
@@ -183,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::persist_host(&req.name, &req.addr, req.port, &fp, false);
-            start_session(app.clone(), req.clone(), trust::parse_hex32(&fp));
-        }
-        "pair" => pin_dialog(app.clone(), req.clone()),
+        "trust" => sender.input(AppMsg::StartSession {
+            req: req.clone(),
+            fp_hex: fp.clone(),
+            tofu: true,
+            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.
-pub fn pin_dialog(app: Rc<App>, req: ConnectRequest) {
+/// transcript. Success persists the host as paired and connects.
+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
-    // with the machine hostname, editable (the Apple pair sheet does the same).
+    // The label the HOST stores this client under — prefilled with the hostname.
    let name_entry = gtk::Entry::builder()
        .text(glib::host_name().as_str())
        .activates_default(true)
@@ -235,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() {
@@ -257,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);
-                    app.toast("Paired — connecting…");
-                    start_session(app.clone(), req, Some(fp));
+                    let fp_hex = trust::hex(&fp);
+                    trust::persist_host(&req.name, &req.addr, req.port, &fp_hex, true);
+                    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
-/// path — connect and wait for the operator to click Approve in the host's console/web UI
-/// (delegated approval); "Use a PIN instead…" runs the SPAKE2 ceremony.
-fn approval_dialog(app: Rc<App>, req: ConnectRequest) {
+/// A fresh host that requires pairing: "Request access" (connect and wait for the
+/// operator to click Approve in the host's console — delegated approval) or the PIN
+/// ceremony.
+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!(
@@ -289,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()),
-        "pin" => pin_dialog(app.clone(), req.clone()),
+        "request" => request_access(&window, &sender, waiting_slot.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
-/// operator approves it in the console, showing a cancelable "waiting" dialog meanwhile. On
-/// approval the same connection is admitted (no reconnect) and the host is saved as paired.
-fn request_access(app: Rc<App>, req: ConnectRequest) {
-    // 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.
-    let pin = req.fp_hex.as_deref().and_then(trust::parse_hex32);
-    let cancel = Rc::new(std::cell::Cell::new(false));
-
+/// The no-PIN "request access" flow: the session child opens an identified connect the
+/// host PARKS until the operator approves it in the console; a cancelable "waiting"
+/// dialog covers the wait. On approval the same connection is admitted and the host is
+/// saved as paired. Cancel kills the child (the only abort a parked connect has).
+///
+/// The pinned fingerprint is the advertised one for a discovered host (defence against
+/// an impostor while we wait). A manually-typed host has no advertised fingerprint —
+/// 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!(
@@ -319,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
-            // down silently by the event loop (see StartOpts::cancel).
-            cancel.set(true);
-            app.busy.set(false);
-            app.toast("Cancelled — the request may still be pending on the host.");
+            cancel.kill();
+            sender.input(AppMsg::CancelPending);
        });
    }
-    waiting.present(Some(&app.window));
+    waiting.present(Some(window));
+    *waiting_slot.borrow_mut() = Some(waiting);

-    start_session_with(
-        app,
+    sender.input(AppMsg::StartSession {
        req,
-        pin,
-        StartOpts {
-            // Must exceed the host's approval window (PENDING_APPROVAL_WAIT) so a slow operator
-            // approval still lands on this connection rather than timing the client out first.
-            connect_timeout: std::time::Duration::from_secs(185),
+        fp_hex,
+        tofu: false,
+        opts: SpawnOpts {
+            // Must exceed the host's approval window (PENDING_APPROVAL_WAIT) so a slow
+            // 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
@@ -247,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(),
                    });
                })
@@ -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",
-            settings_card(vec![
-                forward_combo.into(),
-                pad_combo.into(),
-                shortcuts_toggle.into(),
-            ]),
+            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,
@@ -288,6 +370,27 @@ unsafe extern "system" fn kbd_proc(code: i32, wparam: WPARAM, lparam: LPARAM) ->
                    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>>,
-    active_out: &'a Mutex<Option<PadInfo>>,
+    pads_out: Arc<Mutex<Vec<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>>,
-    active_out: &Mutex<Option<PadInfo>>,
+    pads_out: Arc<Mutex<Vec<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,
-        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: 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(),
-    };
+        escape_tx.clone(),
+        disconnect_tx.clone(),
+        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.
-                        decode_us.push(decoded_ns.saturating_sub(received_ns) / 1000);
+                        // Ship the frame FIRST, then settle the decode stat: on the
+                        // 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()
+                            }
+                            _ => decoded_ns,
+                        };
+                        decode_us.push(decode_done_ns.saturating_sub(received_ns) / 1000);
                    }
-                    Ok(None) => {}
+                    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
@@ -252,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
-//!   to a DRM-PRIME dmabuf (`av_hwframe_map`, zero copy) and handed to the UI as fds +
-//!   plane layout for `GdkDmabufTextureBuilder` — inside `GtkGraphicsOffload` that is the
-//!   decoder-to-subsurface path, direct-scanout eligible when fullscreen. NVIDIA boxes
-//!   have no usable VAAPI (nvidia-vaapi-driver is broken for this — Moonlight blacklists
-//!   it); device creation fails there and the software path takes over. A mid-session
-//!   VAAPI error also falls back — the host's IDR/RFI recovery resynchronizes.
-//! * **Software**: libavcodec on the CPU + swscale to RGBA (`GdkMemoryTexture` upload).
+//! * **Vulkan Video**: FFmpeg's Vulkan decoder running on the PRESENTER's own VkDevice
+//!   (its handles arrive via [`VulkanDecodeDevice`]) — the decoded VkImage feeds the
+//!   presenter's CSC pass directly, zero copy, every vendor with the video extensions
+//!   (NVIDIA's only hardware path; measured 4K@144 with 0.1 ms decode).
+//! * **VAAPI** (Intel/AMD fallback): libavcodec hwaccel; each frame is mapped to a
+//!   DRM-PRIME dmabuf (`av_hwframe_map`, zero copy) and handed over as fds + plane
+//!   layout for the presenter's Vulkan import. NVIDIA has no usable VAAPI
+//!   (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
-    /// frame after packet loss) shouldn't cost the whole session its hardware decoder.
+    /// Consecutive hardware decode errors (Vulkan or VAAPI) — a single transient failure
+    /// (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).
-    pub fn new(codec_id: ffmpeg::codec::Id, pref: &str) -> Result<Decoder> {
+    /// (Vulkan → VAAPI → software).
+    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
-        // the Deck (Mesa ≥ 25.1 exports VCN surfaces TILED; artifacts/gray/washed-out), but the
-        // presenter routes Deck frames through the in-process GL converter (`video_gl`) instead
-        // 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" {
+        let done = |backend| {
+            Ok(Decoder {
+                backend,
+                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 Ok(Decoder {
-                        backend: Backend::Vaapi(v),
-                        codec_id,
-                        vaapi_fails: 0,
-                        want_keyframe: false,
-                    });
+                    return done(Backend::Vaapi(v));
                }
                Err(e) => {
                    if choice == "vaapi" {
@@ -212,12 +309,25 @@ impl Decoder {
                }
            }
        }
-        Ok(Decoder {
-            backend: Backend::Software(SoftwareDecoder::new(codec_id)?),
-            codec_id,
-            vaapi_fails: 0,
-            want_keyframe: false,
-        })
+        if choice == "software" {
+            // Say WHY hardware wasn't even attempted — a stored "software" preference
+            // (or the env override) silently skipping vulkan/vaapi has burned real
+            // debugging time on boxes that could do better.
+            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 {
-            Backend::Vaapi(v) => match v.decode(au) {
-                Ok(f) => {
+        let result = match &mut self.backend {
+            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)
+            }
+            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,
+                        "{which} decode failing repeatedly — demoting to software");
+                    self.backend = Backend::Software(SoftwareDecoder::new(self.codec_id)?);
                    self.vaapi_fails = 0;
-                    Ok(f.map(DecodedImage::Dmabuf))
+                } else {
+                    tracing::warn!(error = %e,
+                        "{which} decode error — requesting keyframe, keeping hardware decode");
                }
-                Err(e) => {
-                    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");
-                        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");
-                    }
-                    Ok(None)
-                }
-            },
-            Backend::Software(s) => Ok(s.decode(au)?.map(DecodedImage::Cpu)),
+                Ok(None)
+            }
        }
    }
 }
@@ -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"
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Recompile the presenter's shaders to the committed .spv blobs. The blobs are committed
+# so neither developer builds nor CI need a SPIR-V toolchain (glslc is a dev-time tool);
+# rerun this after editing a .vert/.frag and commit both.
+set -euo pipefail
+cd "$(dirname "$0")"
+for f in *.vert *.frag; do
+    glslc -O "$f" -o "$f.spv"
+    echo "compiled $f -> $f.spv"
+done
@@ -0,0 +1,14 @@
+// The bufferless fullscreen triangle (same trick as the GL presenter's gl_VertexID
+// geometry). Vulkan clip space: y=-1 is the TOP, so uv (0,0) lands on the top-left —
+// which is exactly where the video's row 0 lives. No flip anywhere.
+//
+// Regenerate: shaders/build.sh (committed .spv, no build-time toolchain).
+#version 450
+
+layout(location = 0) out vec2 v_uv;
+
+void main() {
+    vec2 uv = vec2((gl_VertexIndex << 1) & 2, gl_VertexIndex & 2);
+    v_uv = uv;
+    gl_Position = vec4(uv * 2.0 - 1.0, 0.0, 1.0);
+}
@@ -0,0 +1,90 @@
+// YCbCr (2-plane 4:2:0) → RGBA with the stream's CICP signaling — the Vulkan port of
+// the GL presenter's fragment shader, grown depth- and HDR-aware.
+//
+// The YUV→RGB matrix + range expansion arrive as three push-constant rows precomputed
+// on the CPU (csc.rs `csc_rows` — bit-depth exact, including the P010/X6 MSB-packing
+// factor): rgb[i] = dot(r_i.xyz, yuv) + r_i.w. One shader for BT.601/709/2020,
+// full/limited, 8- and 10-bit. The chroma plane is half-res; the linear sampler
+// interpolates, same as the GL path.
+//
+// params.x selects the output mode:
+//   0 — passthrough: the transfer stays baked (SDR BT.709 shown as-is; PQ BT.2020
+//       written to an HDR10 swapchain that expects exactly PQ-encoded values).
+//   1 — PQ → SDR tonemap (an HDR stream on a desktop without an HDR10 surface):
+//       PQ EOTF → linear light (nits/10000), exposure anchored at the 203-nit HDR
+//       reference white, BT.2020→709 primaries, a soft maxRGB rolloff for highlights
+//       (BT.2390-flavored simplicity, not libplacebo), then sRGB encode.
+// params.y = tonemap peak (display-relative, ~= peak_nits / 203).
+//
+// Regenerate: shaders/build.sh (committed .spv, no build-time toolchain).
+#version 450
+
+layout(location = 0) in vec2 v_uv;
+layout(location = 0) out vec4 frag;
+
+layout(set = 0, binding = 0) uniform sampler2D u_y;
+layout(set = 0, binding = 1) uniform sampler2D u_c;
+
+layout(push_constant) uniform Csc {
+    vec4 r0;
+    vec4 r1;
+    vec4 r2;
+    vec4 params; // x: mode, y: tonemap peak, z/w: reserved
+} pc;
+
+// SMPTE ST.2084 (PQ) EOTF: code value → display-referred linear, normalized to 1.0 =
+// 10000 nits.
+vec3 pq_eotf(vec3 e) {
+    const float m1 = 0.1593017578125;  // 2610/16384
+    const float m2 = 78.84375;         // 2523/4096 * 128
+    const float c1 = 0.8359375;        // 3424/4096
+    const float c2 = 18.8515625;       // 2413/4096 * 32
+    const float c3 = 18.6875;          // 2392/4096 * 32
+    vec3 p = pow(max(e, vec3(0.0)), vec3(1.0 / m2));
+    return pow(max(p - c1, vec3(0.0)) / (c2 - c3 * p), vec3(1.0 / m1));
+}
+
+// BT.2020 → BT.709 primaries (linear light).
+vec3 bt2020_to_709(vec3 c) {
+    return mat3(
+         1.6605, -0.1246, -0.0182,
+        -0.5876,  1.1329, -0.1006,
+        -0.0728, -0.0083,  1.1187
+    ) * c;
+}
+
+// Linear → sRGB OETF.
+vec3 srgb_oetf(vec3 c) {
+    c = clamp(c, 0.0, 1.0);
+    bvec3 lo = lessThanEqual(c, vec3(0.0031308));
+    vec3 hi = 1.055 * pow(c, vec3(1.0 / 2.4)) - 0.055;
+    return mix(hi, c * 12.92, vec3(lo));
+}
+
+void main() {
+    vec3 yuv = vec3(texture(u_y, v_uv).r, texture(u_c, v_uv).rg);
+    vec3 rgb = vec3(
+        dot(pc.r0.xyz, yuv) + pc.r0.w,
+        dot(pc.r1.xyz, yuv) + pc.r1.w,
+        dot(pc.r2.xyz, yuv) + pc.r2.w
+    );
+
+    if (pc.params.x > 0.5) {
+        // PQ BT.2020 → SDR BT.709: linearize, anchor exposure at the 203-nit HDR
+        // reference white (SDR diffuse white), convert primaries, roll off highlights.
+        vec3 lin = pq_eotf(clamp(rgb, 0.0, 1.0)) * (10000.0 / 203.0);
+        lin = max(bt2020_to_709(lin), vec3(0.0));
+        float peak = max(pc.params.y, 1.0001);
+        float l = max(lin.r, max(lin.g, lin.b));
+        if (l > 1.0) {
+            // Soft maxRGB rolloff: identity below 1.0, asymptotic to `peak` above —
+            // keeps colors from clipping to white the way per-channel clamp would.
+            float mapped = 1.0 + (l - 1.0) / (1.0 + (l - 1.0) / (peak - 1.0));
+            lin *= mapped / l;
+        }
+        rgb = srgb_oetf(lin);
+    } else {
+        rgb = clamp(rgb, 0.0, 1.0);
+    }
+    frag = vec4(rgb, 1.0);
+}
@@ -0,0 +1,15 @@
+// The overlay composite: one premultiplied-alpha RGBA texture (the console UI's
+// offscreen image) sampled over the swapchain. Blending happens in fixed function
+// (src ONE, dst ONE_MINUS_SRC_ALPHA — Skia surfaces are premultiplied).
+//
+// Regenerate: shaders/build.sh (committed .spv, no build-time toolchain).
+#version 450
+
+layout(location = 0) in vec2 v_uv;
+layout(location = 0) out vec4 frag;
+
+layout(set = 0, binding = 0) uniform sampler2D u_tex;
+
+void main() {
+    frag = texture(u_tex, v_uv);
+}
@@ -0,0 +1,454 @@
+//! The NV12→RGBA color-space-conversion pass: coefficient rows from the stream's CICP
+//! signaling (the GL presenter's `yuv_to_rgb`, folded into row form for the shader's
+//! push constants) and the graphics pipeline that renders the two imported planes into
+//! the presenter's video image.
+//!
+//! Deliberately NOT `VK_KHR_sampler_ycbcr_conversion`: the ext can't express the PQ path
+//! coming with the HDR phase and its range handling varies by driver — these are the
+//! proven, unit-tested coefficients (plan §5.2).
+
+use anyhow::{Context as _, Result};
+use ash::vk;
+use pf_client_core::video::ColorDesc;
+
+/// The push-constant block's matrix half: three vec4 rows,
+/// `rgb[i] = dot(r[i].xyz, yuv) + r[i].w` — bit-depth exact.
+///
+/// `depth` picks the limited-range code points (8-bit: 16/235/240 over 255; 10-bit:
+/// 64/940/960 over 1023 — NOT the same normalized values, the difference is ~half a
+/// code). `msb_packed` folds in the P010/X6 packing factor: 10 significant bits live in
+/// the MSBs of 16, so a UNORM16 sample reads `code·64/65535` — multiplying by
+/// `65535/65472` recovers exact `code/1023`.
+pub fn csc_rows(desc: ColorDesc, depth: u8, msb_packed: bool) -> [[f32; 4]; 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 max = f64::from((1u32 << depth) - 1); // 255 / 1023
+    let step = f64::from(1u32 << (depth - 8)); // code points per 8-bit step: 1 / 4
+    let pack = if msb_packed { 65535.0 / 65472.0 } else { 1.0 };
+    let (sy, oy, sc) = if desc.full_range {
+        (pack, 0.0f64, pack)
+    } else {
+        (
+            pack * max / (219.0 * step),
+            -(16.0 * step) / max,
+            pack * max / (224.0 * step),
+        )
+    };
+    // rgb = M * (yuv + off) = M*yuv + M*off — rows of M with the offset dot folded into
+    // w. `yuv` is the SAMPLED (packed) value, so the offsets divide by the packing
+    // factor to land on the same scale.
+    let off = [oy / pack, -0.5 / pack, -0.5 / pack];
+    let m = [
+        [sy, 0.0, 2.0 * (1.0 - kr) * sc],
+        [
+            sy,
+            -2.0 * (1.0 - kb) * kb / kg * sc,
+            -2.0 * (1.0 - kr) * kr / kg * sc,
+        ],
+        [sy, 2.0 * (1.0 - kb) * sc, 0.0],
+    ];
+    core::array::from_fn(|r| {
+        let w: f64 = (0..3).map(|c| m[r][c] * off[c]).sum();
+        [m[r][0] as f32, m[r][1] as f32, m[r][2] as f32, w as f32]
+    })
+}
+
+/// The pass objects (everything except the per-video-size framebuffer, which lives with
+/// the video image). Destroyed explicitly via [`CscPass::destroy`] from the presenter's
+/// `Drop` — no device handle is stored here.
+pub struct CscPass {
+    pub render_pass: vk::RenderPass,
+    pub set_layout: vk::DescriptorSetLayout,
+    pub pipeline_layout: vk::PipelineLayout,
+    pub pipeline: vk::Pipeline,
+    pub desc_pool: vk::DescriptorPool,
+    pub desc_set: vk::DescriptorSet,
+    pub sampler: vk::Sampler,
+}
+
+impl CscPass {
+    /// `attachment_format` = the video image's format: R8G8B8A8 for SDR, a 10-bit
+    /// format when the pass writes PQ (8 bits would band the PQ curve visibly).
+    pub fn new(device: &ash::Device, attachment_format: vk::Format) -> Result<CscPass> {
+        // One color attachment: the presenter's video image. Content is fully
+        // overwritten (DONT_CARE load), and the pass ends in TRANSFER_SRC so the
+        // existing letterbox blit consumes it with no extra barrier.
+        let attachment = [vk::AttachmentDescription::default()
+            .format(attachment_format)
+            .samples(vk::SampleCountFlags::TYPE_1)
+            .load_op(vk::AttachmentLoadOp::DONT_CARE)
+            .store_op(vk::AttachmentStoreOp::STORE)
+            .initial_layout(vk::ImageLayout::UNDEFINED)
+            .final_layout(vk::ImageLayout::TRANSFER_SRC_OPTIMAL)];
+        let color_ref = [vk::AttachmentReference::default()
+            .attachment(0)
+            .layout(vk::ImageLayout::COLOR_ATTACHMENT_OPTIMAL)];
+        let subpass = [vk::SubpassDescription::default()
+            .pipeline_bind_point(vk::PipelineBindPoint::GRAPHICS)
+            .color_attachments(&color_ref)];
+        // Conservative scopes, matching the presenter's per-frame barrier granularity.
+        let deps = [
+            vk::SubpassDependency::default()
+                .src_subpass(vk::SUBPASS_EXTERNAL)
+                .dst_subpass(0)
+                .src_stage_mask(vk::PipelineStageFlags::ALL_COMMANDS)
+                .src_access_mask(vk::AccessFlags::MEMORY_WRITE)
+                .dst_stage_mask(vk::PipelineStageFlags::COLOR_ATTACHMENT_OUTPUT)
+                .dst_access_mask(vk::AccessFlags::COLOR_ATTACHMENT_WRITE),
+            vk::SubpassDependency::default()
+                .src_subpass(0)
+                .dst_subpass(vk::SUBPASS_EXTERNAL)
+                .src_stage_mask(vk::PipelineStageFlags::COLOR_ATTACHMENT_OUTPUT)
+                .src_access_mask(vk::AccessFlags::COLOR_ATTACHMENT_WRITE)
+                .dst_stage_mask(vk::PipelineStageFlags::TRANSFER)
+                .dst_access_mask(vk::AccessFlags::TRANSFER_READ),
+        ];
+        let render_pass = unsafe {
+            device.create_render_pass(
+                &vk::RenderPassCreateInfo::default()
+                    .attachments(&attachment)
+                    .subpasses(&subpass)
+                    .dependencies(&deps),
+                None,
+            )
+        }
+        .context("CSC render pass")?;
+
+        let sampler = unsafe {
+            device.create_sampler(
+                &vk::SamplerCreateInfo::default()
+                    .mag_filter(vk::Filter::LINEAR)
+                    .min_filter(vk::Filter::LINEAR)
+                    .address_mode_u(vk::SamplerAddressMode::CLAMP_TO_EDGE)
+                    .address_mode_v(vk::SamplerAddressMode::CLAMP_TO_EDGE)
+                    .address_mode_w(vk::SamplerAddressMode::CLAMP_TO_EDGE),
+                None,
+            )
+        }?;
+
+        let samplers = [sampler];
+        let bindings = [
+            vk::DescriptorSetLayoutBinding::default()
+                .binding(0)
+                .descriptor_type(vk::DescriptorType::COMBINED_IMAGE_SAMPLER)
+                .descriptor_count(1)
+                .stage_flags(vk::ShaderStageFlags::FRAGMENT)
+                .immutable_samplers(&samplers),
+            vk::DescriptorSetLayoutBinding::default()
+                .binding(1)
+                .descriptor_type(vk::DescriptorType::COMBINED_IMAGE_SAMPLER)
+                .descriptor_count(1)
+                .stage_flags(vk::ShaderStageFlags::FRAGMENT)
+                .immutable_samplers(&samplers),
+        ];
+        let set_layout = unsafe {
+            device.create_descriptor_set_layout(
+                &vk::DescriptorSetLayoutCreateInfo::default().bindings(&bindings),
+                None,
+            )
+        }?;
+        let set_layouts = [set_layout];
+        let push = [vk::PushConstantRange::default()
+            .stage_flags(vk::ShaderStageFlags::FRAGMENT)
+            .size(64)]; // three vec4 rows + a params vec4 (mode, tonemap peak)
+        let pipeline_layout = unsafe {
+            device.create_pipeline_layout(
+                &vk::PipelineLayoutCreateInfo::default()
+                    .set_layouts(&set_layouts)
+                    .push_constant_ranges(&push),
+                None,
+            )
+        }?;
+
+        let pool_sizes = [vk::DescriptorPoolSize::default()
+            .ty(vk::DescriptorType::COMBINED_IMAGE_SAMPLER)
+            .descriptor_count(2)];
+        let desc_pool = unsafe {
+            device.create_descriptor_pool(
+                &vk::DescriptorPoolCreateInfo::default()
+                    .max_sets(1)
+                    .pool_sizes(&pool_sizes),
+                None,
+            )
+        }?;
+        let desc_set = unsafe {
+            device.allocate_descriptor_sets(
+                &vk::DescriptorSetAllocateInfo::default()
+                    .descriptor_pool(desc_pool)
+                    .set_layouts(&set_layouts),
+            )
+        }?[0];
+
+        let pipeline = build_fullscreen_pipeline(
+            device,
+            render_pass,
+            pipeline_layout,
+            include_bytes!("../shaders/nv12_csc.frag.spv"),
+            false, // opaque — the CSC output IS the video
+        )?;
+
+        Ok(CscPass {
+            render_pass,
+            set_layout,
+            pipeline_layout,
+            pipeline,
+            desc_pool,
+            desc_set,
+            sampler,
+        })
+    }
+
+    /// Point the descriptor set at this frame's plane views. Only safe while no
+    /// submitted command buffer references the set — the presenter's single in-flight
+    /// fence is waited before every record, which covers it.
+    pub fn bind_planes(&self, device: &ash::Device, luma: vk::ImageView, chroma: vk::ImageView) {
+        let infos = [luma, chroma].map(|view| {
+            [vk::DescriptorImageInfo::default()
+                .image_view(view)
+                .image_layout(vk::ImageLayout::SHADER_READ_ONLY_OPTIMAL)]
+        });
+        let writes = [
+            vk::WriteDescriptorSet::default()
+                .dst_set(self.desc_set)
+                .dst_binding(0)
+                .descriptor_type(vk::DescriptorType::COMBINED_IMAGE_SAMPLER)
+                .image_info(&infos[0]),
+            vk::WriteDescriptorSet::default()
+                .dst_set(self.desc_set)
+                .dst_binding(1)
+                .descriptor_type(vk::DescriptorType::COMBINED_IMAGE_SAMPLER)
+                .image_info(&infos[1]),
+        ];
+        unsafe { device.update_descriptor_sets(&writes, &[]) };
+    }
+
+    pub fn destroy(&self, device: &ash::Device) {
+        unsafe {
+            device.destroy_pipeline(self.pipeline, None);
+            device.destroy_pipeline_layout(self.pipeline_layout, None);
+            device.destroy_descriptor_pool(self.desc_pool, None);
+            device.destroy_descriptor_set_layout(self.set_layout, None);
+            device.destroy_sampler(self.sampler, None);
+            device.destroy_render_pass(self.render_pass, None);
+        }
+    }
+}
+
+/// A bufferless fullscreen-triangle pipeline over `fullscreen.vert` + the given
+/// fragment SPIR-V, dynamic viewport/scissor. `blend` = premultiplied-alpha over the
+/// destination (the overlay composite); `false` = opaque write (the CSC pass). Shared
+/// by both passes — the geometry and states are identical.
+pub(crate) fn build_fullscreen_pipeline(
+    device: &ash::Device,
+    render_pass: vk::RenderPass,
+    layout: vk::PipelineLayout,
+    frag_spv: &[u8],
+    blend: bool,
+) -> Result<vk::Pipeline> {
+    // Committed SPIR-V (shaders/build.sh) — include_bytes! alignment is unspecified, so
+    // read_spv copies into aligned Vec<u32>s.
+    let vert = ash::util::read_spv(&mut std::io::Cursor::new(
+        &include_bytes!("../shaders/fullscreen.vert.spv")[..],
+    ))?;
+    let frag = ash::util::read_spv(&mut std::io::Cursor::new(frag_spv))?;
+    let vert_mod = unsafe {
+        device.create_shader_module(&vk::ShaderModuleCreateInfo::default().code(&vert), None)
+    }?;
+    let frag_mod = unsafe {
+        device.create_shader_module(&vk::ShaderModuleCreateInfo::default().code(&frag), None)
+    };
+    let frag_mod = match frag_mod {
+        Ok(m) => m,
+        Err(e) => {
+            unsafe { device.destroy_shader_module(vert_mod, None) };
+            return Err(e).context("fragment shader module");
+        }
+    };
+
+    let entry = c"main";
+    let stages = [
+        vk::PipelineShaderStageCreateInfo::default()
+            .stage(vk::ShaderStageFlags::VERTEX)
+            .module(vert_mod)
+            .name(entry),
+        vk::PipelineShaderStageCreateInfo::default()
+            .stage(vk::ShaderStageFlags::FRAGMENT)
+            .module(frag_mod)
+            .name(entry),
+    ];
+    let vertex_input = vk::PipelineVertexInputStateCreateInfo::default(); // bufferless
+    let assembly = vk::PipelineInputAssemblyStateCreateInfo::default()
+        .topology(vk::PrimitiveTopology::TRIANGLE_LIST);
+    // Dynamic viewport/scissor: the video size changes with the stream mode, the
+    // pipeline must not bake one in.
+    let viewport = vk::PipelineViewportStateCreateInfo::default()
+        .viewport_count(1)
+        .scissor_count(1);
+    let dynamic = [vk::DynamicState::VIEWPORT, vk::DynamicState::SCISSOR];
+    let dynamic_state = vk::PipelineDynamicStateCreateInfo::default().dynamic_states(&dynamic);
+    let raster = vk::PipelineRasterizationStateCreateInfo::default()
+        .polygon_mode(vk::PolygonMode::FILL)
+        .cull_mode(vk::CullModeFlags::NONE)
+        .line_width(1.0);
+    let multisample = vk::PipelineMultisampleStateCreateInfo::default()
+        .rasterization_samples(vk::SampleCountFlags::TYPE_1);
+    let blend_attachment = [if blend {
+        // Premultiplied alpha over the destination (Skia surfaces are premultiplied).
+        vk::PipelineColorBlendAttachmentState::default()
+            .color_write_mask(vk::ColorComponentFlags::RGBA)
+            .blend_enable(true)
+            .src_color_blend_factor(vk::BlendFactor::ONE)
+            .dst_color_blend_factor(vk::BlendFactor::ONE_MINUS_SRC_ALPHA)
+            .color_blend_op(vk::BlendOp::ADD)
+            .src_alpha_blend_factor(vk::BlendFactor::ONE)
+            .dst_alpha_blend_factor(vk::BlendFactor::ONE_MINUS_SRC_ALPHA)
+            .alpha_blend_op(vk::BlendOp::ADD)
+    } else {
+        vk::PipelineColorBlendAttachmentState::default()
+            .color_write_mask(vk::ColorComponentFlags::RGBA)
+    }];
+    let blend = vk::PipelineColorBlendStateCreateInfo::default().attachments(&blend_attachment);
+
+    let info = vk::GraphicsPipelineCreateInfo::default()
+        .stages(&stages)
+        .vertex_input_state(&vertex_input)
+        .input_assembly_state(&assembly)
+        .viewport_state(&viewport)
+        .rasterization_state(&raster)
+        .multisample_state(&multisample)
+        .color_blend_state(&blend)
+        .dynamic_state(&dynamic_state)
+        .layout(layout)
+        .render_pass(render_pass);
+    let pipeline =
+        unsafe { device.create_graphics_pipelines(vk::PipelineCache::null(), &[info], None) }
+            .map_err(|(_, e)| e)
+            .context("CSC pipeline");
+    unsafe {
+        device.destroy_shader_module(vert_mod, None);
+        device.destroy_shader_module(frag_mod, None);
+    }
+    Ok(pipeline?[0])
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn desc(matrix: u8, full_range: bool) -> ColorDesc {
+        ColorDesc {
+            primaries: 1,
+            transfer: 1,
+            matrix,
+            full_range,
+        }
+    }
+
+    fn apply(rows: &[[f32; 4]; 3], yuv: [f32; 3]) -> [f32; 3] {
+        core::array::from_fn(|r| {
+            rows[r][0] * yuv[0] + rows[r][1] * yuv[1] + rows[r][2] * yuv[2] + rows[r][3]
+        })
+    }
+
+    /// 10-bit limited MSB-packed (P010/X6): reference white Y=940, black Y=64, neutral
+    /// chroma 512 — sampled as UNORM16 of `code << 6`.
+    #[test]
+    fn bt2020_10bit_limited_white_black() {
+        let rows = csc_rows(desc(9, false), 10, true);
+        let s = |code: u32| ((code << 6) as f32) / 65535.0;
+        let white = apply(&rows, [s(940), s(512), s(512)]);
+        let black = apply(&rows, [s(64), s(512), s(512)]);
+        for (w, b) in white.iter().zip(black) {
+            assert!((w - 1.0).abs() < 0.002, "white {white:?}");
+            assert!(b.abs() < 0.002, "black {black:?}");
+        }
+    }
+
+    /// Reference white (Y=235, U=V=128 limited) → RGB 1.0; reference black (Y=16) → 0.0
+    /// — the GL presenter's test, in row form.
+    #[test]
+    fn bt709_limited_white_black() {
+        let rows = csc_rows(desc(1, false), 8, false);
+        let white = apply(&rows, [235.0 / 255.0, 128.0 / 255.0, 128.0 / 255.0]);
+        let black = apply(&rows, [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 + the 601-vs-709 red excursion (guards the
+    /// matrix-code dispatch), same as the GL presenter's test.
+    #[test]
+    fn full_range_and_red_excursion() {
+        let rows = csc_rows(desc(5, true), 8, false);
+        let white = apply(&rows, [1.0, 0.5, 0.5]);
+        assert!(white.iter().all(|v| (v - 1.0).abs() < 1e-5), "{white:?}");
+        let red = apply(&rows, [0.0, 0.5, 1.0]);
+        assert!((red[0] - 2.0 * (1.0 - 0.299) * 0.5).abs() < 1e-4, "{red:?}");
+        let rows709 = csc_rows(desc(1, true), 8, false);
+        let red709 = apply(&rows709, [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);
+    }
+
+    /// The row form must agree with the GL presenter's column-major `yuv_to_rgb` on a
+    /// grid of inputs — same math, different packing.
+    #[test]
+    fn rows_match_the_gl_matrix_form() {
+        for (matrix, full) in [(1u8, false), (1, true), (5, false), (9, false), (9, true)] {
+            let d = desc(matrix, full);
+            let rows = csc_rows(d, 8, false);
+            // Reimplementation of video_gl::yuv_to_rgb's application for comparison.
+            let (kr, kb) = match matrix {
+                5 | 6 => (0.299f32, 0.114f32),
+                9 | 10 => (0.2627, 0.0593),
+                _ => (0.2126, 0.0722),
+            };
+            let kg = 1.0 - kr - kb;
+            let (sy, oy, sc) = if full {
+                (1.0f32, 0.0f32, 1.0f32)
+            } else {
+                (255.0 / 219.0, -16.0 / 255.0, 255.0 / 224.0)
+            };
+            let mat = [
+                sy,
+                sy,
+                sy,
+                0.0,
+                -2.0 * (1.0 - kb) * kb / kg * sc,
+                2.0 * (1.0 - kb) * sc,
+                2.0 * (1.0 - kr) * sc,
+                -2.0 * (1.0 - kr) * kr / kg * sc,
+                0.0,
+            ];
+            let off = [oy, -0.5, -0.5];
+            for yuv in [
+                [0.1f32, 0.3, 0.7],
+                [0.9, 0.5, 0.5],
+                [0.5, 0.2, 0.8],
+                [16.0 / 255.0, 0.5, 0.5],
+            ] {
+                let v = [yuv[0] + off[0], yuv[1] + off[1], yuv[2] + off[2]];
+                let gl: [f32; 3] =
+                    core::array::from_fn(|r| (0..3).map(|c| mat[c * 3 + r] * v[c]).sum());
+                let ours = apply(&rows, yuv);
+                for (a, b) in gl.iter().zip(ours) {
+                    assert!(
+                        (a - b).abs() < 1e-5,
+                        "{matrix}/{full}: gl {gl:?} rows {ours:?}"
+                    );
+                }
+            }
+        }
+    }
+}
@@ -0,0 +1,307 @@
+//! VAAPI dmabuf → Vulkan import: per-plane `VkImage`s (R8/GR88 for NV12, R16/GR1616
+//! for 10-bit P010) with the
+//! surface's explicit DRM format modifier — the same layer-wise import the EGL presenter
+//! (`video_gl.rs`) proved on this hardware, minus the toolkit. Same-Mesa export/import
+//! is the contract; anything a driver rejects surfaces as a clean error and the caller
+//! demotes the decoder to software (never a black screen).
+
+use anyhow::{bail, Context as _, Result};
+use ash::vk;
+use pf_client_core::video::{DmabufFrame, DrmFrameGuard};
+use std::os::fd::{BorrowedFd, IntoRawFd as _};
+
+/// `fourcc('N','V','1','2')` — 8-bit 4:2:0 VAAPI output.
+const DRM_FORMAT_NV12: u32 = 0x3231_564e;
+/// `fourcc('P','0','1','0')` — 10-bit 4:2:0, 10 bits MSB-aligned in 16 (the HDR path).
+const DRM_FORMAT_P010: u32 = 0x3031_3050;
+const DRM_FORMAT_MOD_INVALID: u64 = 0x00ff_ffff_ffff_ffff;
+/// `DRM_FORMAT_MOD_LINEAR` — the fallback when the export carried no explicit modifier.
+const DRM_FORMAT_MOD_LINEAR: u64 = 0;
+
+/// The four device extensions the import path needs; queried at device creation. All
+/// Mesa drivers (RADV/ANV/radeonsi boxes) expose the set — NVIDIA proprietary has no
+/// usable VAAPI anyway, so the software path owns that vendor by design.
+pub const DEVICE_EXTENSIONS: [&std::ffi::CStr; 4] = [
+    ash::ext::external_memory_dma_buf::NAME,
+    ash::khr::external_memory_fd::NAME,
+    ash::ext::image_drm_format_modifier::NAME,
+    ash::ext::queue_family_foreign::NAME,
+];
+
+/// One imported frame: both plane images + their memory, and the decoder surface guard.
+/// GPU reads outlive the submit — the presenter parks this until the frame's fence has
+/// signaled, then calls [`HwFrame::destroy`] (which finally drops the guard).
+pub struct HwFrame {
+    pub luma_view: vk::ImageView,
+    pub chroma_view: vk::ImageView,
+    pub color: pf_client_core::video::ColorDesc,
+    pub width: u32,
+    pub height: u32,
+    /// 10-bit MSB-packed (P010) — the CSC picks its depth-exact rows off this.
+    fourcc: u32,
+    images: [vk::Image; 2],
+    memories: [vk::DeviceMemory; 2],
+    views: [vk::ImageView; 2],
+    _guard: DrmFrameGuard,
+}
+
+impl HwFrame {
+    /// 10-bit MSB-packed layout (P010)?
+    pub fn is_p010(&self) -> bool {
+        self.fourcc == DRM_FORMAT_P010
+    }
+
+    /// The raw plane images — the presenter's foreign-acquire barriers need them.
+    pub fn luma_image(&self) -> vk::Image {
+        self.images[0]
+    }
+
+    pub fn chroma_image(&self) -> vk::Image {
+        self.images[1]
+    }
+
+    pub fn destroy(self, device: &ash::Device) {
+        unsafe {
+            for v in self.views {
+                device.destroy_image_view(v, None);
+            }
+            for i in self.images {
+                device.destroy_image(i, None);
+            }
+            for m in self.memories {
+                device.free_memory(m, None);
+            }
+        }
+        // _guard (the mapped AVFrame / VAAPI surface) drops here — after every GPU read.
+    }
+}
+
+/// Import one frame's two planes. Fails cleanly (caller demotes) on anything the driver
+/// rejects: unknown fourcc, unsupported modifier, import refusal.
+pub fn import(
+    device: &ash::Device,
+    ext_mem_fd: &ash::khr::external_memory_fd::Device,
+    frame: DmabufFrame,
+) -> Result<HwFrame> {
+    // The demotion test hook (plan §8, Phase 2 acceptance): fault every import so the
+    // failure-streak → force_software → software-decode recovery is exercisable on any
+    // box, no broken driver required. Read per hw frame — demotion silences it within
+    // three frames, so the env lookup never runs hot.
+    if std::env::var_os("PUNKTFUNK_HW_FAULT").is_some_and(|v| v == "import") {
+        bail!("injected import failure (PUNKTFUNK_HW_FAULT=import)");
+    }
+    let (luma_fmt, chroma_fmt) = match frame.fourcc {
+        DRM_FORMAT_NV12 => (vk::Format::R8_UNORM, vk::Format::R8G8_UNORM),
+        DRM_FORMAT_P010 => (vk::Format::R16_UNORM, vk::Format::R16G16_UNORM),
+        other => bail!("hw presenter handles NV12/P010 only (got {other:#x})"),
+    };
+    if frame.planes.len() < 2 {
+        bail!("2-plane 4:2:0 needs 2 planes (got {})", frame.planes.len());
+    }
+    // EGL could leave an INVALID modifier to the driver's implied choice; explicit-
+    // modifier images can't — LINEAR is the only honest guess (debug-visible if wrong).
+    let modifier = if frame.modifier == DRM_FORMAT_MOD_INVALID {
+        tracing::debug!("dmabuf carried no explicit modifier — importing as LINEAR");
+        DRM_FORMAT_MOD_LINEAR
+    } else {
+        frame.modifier
+    };
+
+    let y = &frame.planes[0];
+    let c = &frame.planes[1];
+    let (luma_img, luma_mem) = plane_image(
+        device,
+        ext_mem_fd,
+        frame.width,
+        frame.height,
+        luma_fmt,
+        y.fd,
+        y.offset,
+        y.stride,
+        modifier,
+    )
+    .context("luma plane")?;
+    let (chroma_img, chroma_mem) = match plane_image(
+        device,
+        ext_mem_fd,
+        frame.width.div_ceil(2),
+        frame.height.div_ceil(2),
+        chroma_fmt,
+        c.fd,
+        c.offset,
+        c.stride,
+        modifier,
+    )
+    .context("chroma plane")
+    {
+        Ok(r) => r,
+        Err(e) => {
+            unsafe {
+                device.destroy_image(luma_img, None);
+                device.free_memory(luma_mem, None);
+            }
+            return Err(e);
+        }
+    };
+
+    let view = |image, format| {
+        unsafe {
+            device.create_image_view(
+                &vk::ImageViewCreateInfo::default()
+                    .image(image)
+                    .view_type(vk::ImageViewType::TYPE_2D)
+                    .format(format)
+                    .subresource_range(
+                        vk::ImageSubresourceRange::default()
+                            .aspect_mask(vk::ImageAspectFlags::COLOR)
+                            .level_count(1)
+                            .layer_count(1),
+                    ),
+                None,
+            )
+        }
+        .context("plane image view")
+    };
+    let destroy_images = |views: &[vk::ImageView]| unsafe {
+        for v in views {
+            device.destroy_image_view(*v, None);
+        }
+        device.destroy_image(luma_img, None);
+        device.destroy_image(chroma_img, None);
+        device.free_memory(luma_mem, None);
+        device.free_memory(chroma_mem, None);
+    };
+    let luma_view = match view(luma_img, luma_fmt) {
+        Ok(v) => v,
+        Err(e) => {
+            destroy_images(&[]);
+            return Err(e);
+        }
+    };
+    let chroma_view = match view(chroma_img, chroma_fmt) {
+        Ok(v) => v,
+        Err(e) => {
+            destroy_images(&[luma_view]);
+            return Err(e);
+        }
+    };
+
+    Ok(HwFrame {
+        luma_view,
+        chroma_view,
+        color: frame.color,
+        width: frame.width,
+        height: frame.height,
+        fourcc: frame.fourcc,
+        images: [luma_img, chroma_img],
+        memories: [luma_mem, chroma_mem],
+        views: [luma_view, chroma_view],
+        _guard: frame.guard,
+    })
+}
+
+/// One single-plane image over a dmabuf plane: explicit-modifier tiling with the plane's
+/// (offset, pitch), external-memory dmabuf handle type, dedicated import of a dup'd fd
+/// (Vulkan takes ownership of the fd it's given; the frame guard keeps owning the
+/// original).
+#[allow(clippy::too_many_arguments)]
+fn plane_image(
+    device: &ash::Device,
+    ext_mem_fd: &ash::khr::external_memory_fd::Device,
+    width: u32,
+    height: u32,
+    format: vk::Format,
+    fd: std::os::fd::RawFd,
+    offset: u32,
+    stride: u32,
+    modifier: u64,
+) -> Result<(vk::Image, vk::DeviceMemory)> {
+    let plane_layouts = [vk::SubresourceLayout {
+        offset: u64::from(offset),
+        size: 0, // must be 0 for imports (the driver derives it)
+        row_pitch: u64::from(stride),
+        array_pitch: 0,
+        depth_pitch: 0,
+    }];
+    let mut modifier_info = vk::ImageDrmFormatModifierExplicitCreateInfoEXT::default()
+        .drm_format_modifier(modifier)
+        .plane_layouts(&plane_layouts);
+    let mut external_info = vk::ExternalMemoryImageCreateInfo::default()
+        .handle_types(vk::ExternalMemoryHandleTypeFlags::DMA_BUF_EXT);
+    let image = unsafe {
+        device.create_image(
+            &vk::ImageCreateInfo::default()
+                .push_next(&mut modifier_info)
+                .push_next(&mut external_info)
+                .image_type(vk::ImageType::TYPE_2D)
+                .format(format)
+                .extent(vk::Extent3D {
+                    width,
+                    height,
+                    depth: 1,
+                })
+                .mip_levels(1)
+                .array_layers(1)
+                .samples(vk::SampleCountFlags::TYPE_1)
+                .tiling(vk::ImageTiling::DRM_FORMAT_MODIFIER_EXT)
+                .usage(vk::ImageUsageFlags::SAMPLED)
+                .initial_layout(vk::ImageLayout::UNDEFINED),
+            None,
+        )
+    }
+    .with_context(|| {
+        format!("create {width}x{height} {format:?} image (modifier {modifier:#018x})")
+    })?;
+
+    let result = (|| {
+        // The fd's importable memory types, intersected with the image's requirement.
+        let mut fd_props = vk::MemoryFdPropertiesKHR::default();
+        unsafe {
+            ext_mem_fd.get_memory_fd_properties(
+                vk::ExternalMemoryHandleTypeFlags::DMA_BUF_EXT,
+                fd,
+                &mut fd_props,
+            )
+        }
+        .context("vkGetMemoryFdPropertiesKHR")?;
+        let reqs = unsafe { device.get_image_memory_requirements(image) };
+        let bits = reqs.memory_type_bits & fd_props.memory_type_bits;
+        let type_index = (0..32u32)
+            .find(|i| bits & (1 << i) != 0)
+            .context("no importable memory type for dmabuf")?;
+
+        // Vulkan owns the fd it imports — dup so the decoder guard keeps the original.
+        let owned = unsafe { BorrowedFd::borrow_raw(fd) }
+            .try_clone_to_owned()
+            .context("dup dmabuf fd")?;
+        let mut import_info = vk::ImportMemoryFdInfoKHR::default()
+            .handle_type(vk::ExternalMemoryHandleTypeFlags::DMA_BUF_EXT)
+            .fd(owned.into_raw_fd());
+        let mut dedicated = vk::MemoryDedicatedAllocateInfo::default().image(image);
+        let memory = unsafe {
+            device.allocate_memory(
+                &vk::MemoryAllocateInfo::default()
+                    .push_next(&mut import_info)
+                    .push_next(&mut dedicated)
+                    .allocation_size(reqs.size)
+                    .memory_type_index(type_index),
+                None,
+            )
+        }
+        .context("import dmabuf memory")?;
+        // (On allocate_memory failure Vulkan still closed the dup'd fd — nothing leaks.)
+        if let Err(e) = unsafe { device.bind_image_memory(image, memory, 0) } {
+            unsafe { device.free_memory(memory, None) };
+            return Err(e).context("bind imported memory");
+        }
+        Ok(memory)
+    })();
+
+    match result {
+        Ok(memory) => Ok((image, memory)),
+        Err(e) => {
+            unsafe { device.destroy_image(image, None) };
+            Err(e)
+        }
+    }
+}
@@ -0,0 +1,183 @@
+//! Input capture — the `ui_stream` state machine on SDL events, upgraded to real
+//! pointer lock (the "stage-2 presenter's job" the GTK client deferred).
+//!
+//! Capture is a deliberate, reversible STATE (Moonlight-style): engaged when the stream
+//! starts and when the user clicks into the video (that click is suppressed toward the
+//! host); released by Ctrl+Alt+Shift+Q (toggles) or focus loss — held keys/buttons are
+//! flushed host-side on release so nothing sticks down. While captured the pointer is
+//! LOCKED (SDL relative mouse mode: hidden, confined, raw deltas) and motion goes on
+//! the wire as RELATIVE `MouseMove` — the local cursor can't outrun or escape the
+//! stream, so the only cursor you see is the host's. An auto-release from focus loss
+//! re-engages on focus gain; an explicit user release (the chord) stays released until
+//! the user opts back in.
+//!
+//! Keys are SDL scancodes → VK via `keymap_sdl`, layout-independent. Motion deltas are
+//! COALESCED: one summed `MouseMove` per loop iteration (a 1000 Hz mouse would
+//! otherwise send a datagram per event).
+
+use crate::keymap_sdl;
+use punktfunk_core::client::NativeClient;
+use punktfunk_core::input::{InputEvent, InputKind};
+use std::collections::HashSet;
+use std::sync::Arc;
+
+pub struct Capture {
+    connector: Arc<NativeClient>,
+    captured: bool,
+    /// The user released deliberately (the chord) — focus-gain must NOT re-engage.
+    user_released: bool,
+    /// VKs / GameStream button ids currently held — flushed up on release.
+    held_keys: HashSet<u8>,
+    held_buttons: HashSet<u32>,
+    /// Relative motion not yet on the wire, summed per loop iteration.
+    pending_rel: (i32, i32),
+    /// Fractional wheel remainder per axis (x, y) in 120-unit WHEEL_DELTA space —
+    /// precision surfaces deliver sub-unit deltas; truncating each event drops the tail.
+    scroll_acc: (f64, f64),
+}
+
+fn send(connector: &NativeClient, kind: InputKind, code: u32, x: i32, y: i32, flags: u32) {
+    let _ = connector.send_input(&InputEvent {
+        kind,
+        _pad: [0; 3],
+        code,
+        x,
+        y,
+        flags,
+    });
+}
+
+impl Capture {
+    pub fn new(connector: Arc<NativeClient>) -> Capture {
+        Capture {
+            connector,
+            captured: false,
+            user_released: false,
+            held_keys: HashSet::new(),
+            held_buttons: HashSet::new(),
+            pending_rel: (0, 0),
+            scroll_acc: (0.0, 0.0),
+        }
+    }
+
+    pub fn captured(&self) -> bool {
+        self.captured
+    }
+
+    /// Whether a regained focus should re-engage: yes unless the user released
+    /// deliberately (the chord keeps its meaning across an Alt-Tab).
+    pub fn should_reengage(&self) -> bool {
+        !self.captured && !self.user_released
+    }
+
+    /// Engage capture. The caller flips SDL relative mouse mode on (pointer lock).
+    pub fn engage(&mut self) -> bool {
+        self.user_released = false;
+        !std::mem::replace(&mut self.captured, true)
+    }
+
+    /// Release capture, flushing everything held so nothing sticks down on the host.
+    /// `by_user` = the chord (stays released); focus loss re-engages on focus gain.
+    /// The caller flips SDL relative mouse mode off. Returns false if not engaged.
+    pub fn release(&mut self, by_user: bool) -> bool {
+        if by_user {
+            self.user_released = true;
+        }
+        if !std::mem::replace(&mut self.captured, false) {
+            return false;
+        }
+        self.pending_rel = (0, 0); // never flush motion gathered while captured
+        for vk in self.held_keys.drain() {
+            send(&self.connector, InputKind::KeyUp, vk as u32, 0, 0, 0);
+        }
+        for b in self.held_buttons.drain() {
+            send(&self.connector, InputKind::MouseButtonUp, b, 0, 0, 0);
+        }
+        true
+    }
+
+    /// Forward the coalesced motion delta, if any — one datagram per loop iteration.
+    pub fn flush_motion(&mut self) {
+        let (dx, dy) = std::mem::take(&mut self.pending_rel);
+        if dx != 0 || dy != 0 {
+            send(&self.connector, InputKind::MouseMove, 0, dx, dy, 0);
+        }
+    }
+
+    /// Relative motion (SDL relative mouse mode delivers raw deltas while locked).
+    pub fn on_motion(&mut self, xrel: f32, yrel: f32) {
+        if self.captured {
+            self.pending_rel.0 += xrel as i32;
+            self.pending_rel.1 += yrel as i32;
+        }
+    }
+
+    pub fn on_key_down(&mut self, sc: sdl3::keyboard::Scancode) {
+        if !self.captured {
+            return;
+        }
+        if let Some(vk) = keymap_sdl::scancode_to_vk(sc) {
+            // Keep the wire ordered: the host must see the cursor where the user does
+            // when the key lands (e.g. "press E at the crosshair").
+            self.flush_motion();
+            self.held_keys.insert(vk);
+            send(&self.connector, InputKind::KeyDown, vk as u32, 0, 0, 0);
+        }
+    }
+
+    pub fn on_key_up(&mut self, sc: sdl3::keyboard::Scancode) {
+        if let Some(vk) = keymap_sdl::scancode_to_vk(sc) {
+            // Flush-on-release may have beaten us to it — only forward if still held.
+            if self.held_keys.remove(&vk) {
+                send(&self.connector, InputKind::KeyUp, vk as u32, 0, 0, 0);
+            }
+        }
+    }
+
+    /// A button press while captured. The engaging click is the caller's business (it
+    /// never reaches here). Pending motion flushes first so the button-down lands where
+    /// the host cursor actually is.
+    pub fn on_button_down(&mut self, b: sdl3::mouse::MouseButton) {
+        if !self.captured {
+            return;
+        }
+        self.flush_motion();
+        if let Some(gs) = keymap_sdl::mouse_button_to_gs(b) {
+            self.held_buttons.insert(gs);
+            send(&self.connector, InputKind::MouseButtonDown, gs, 0, 0, 0);
+        }
+    }
+
+    pub fn on_button_up(&mut self, b: sdl3::mouse::MouseButton) {
+        self.flush_motion(); // the release must not beat the motion before it
+        if let Some(gs) = keymap_sdl::mouse_button_to_gs(b) {
+            if self.held_buttons.remove(&gs) {
+                send(&self.connector, InputKind::MouseButtonUp, gs, 0, 0, 0);
+            }
+        }
+    }
+
+    /// Wheel — the wire carries WHEEL_DELTA(120) units, positive = up / right. SDL3's y
+    /// is positive = up and x positive = right already. Fractional remainders
+    /// accumulate per axis.
+    pub fn on_wheel(&mut self, dx: f32, dy: f32) {
+        if !self.captured {
+            return;
+        }
+        self.flush_motion(); // scroll happens at the latest cursor position
+        let (mut ax, mut ay) = self.scroll_acc;
+        ay += f64::from(dy) * 120.0;
+        ax += f64::from(dx) * 120.0;
+        let vy = ay.trunc() as i32;
+        if vy != 0 {
+            ay -= f64::from(vy);
+            send(&self.connector, InputKind::MouseScroll, 0, vy, 0, 0);
+        }
+        let vx = ax.trunc() as i32;
+        if vx != 0 {
+            ax -= f64::from(vx);
+            send(&self.connector, InputKind::MouseScroll, 1, vx, 0, 0);
+        }
+        self.scroll_acc = (ax, ay);
+    }
+}
@@ -0,0 +1,201 @@
+//! SDL scancodes / mouse buttons → the punktfunk input wire contract.
+//!
+//! Same VK codes as `pf_client_core::keymap` (the wire carries Windows Virtual-Keys, the
+//! GameStream convention), keyed on SDL scancodes instead of evdev codes: SDL normalizes
+//! the platform keycode to its USB-HID-derived scancode table, so this stays
+//! layout-independent exactly like the evdev table. Coverage mirrors `keymap::evdev_to_vk`
+//! one-to-one — a key the wire contract doesn't cover (media keys etc.) returns `None`
+//! and is dropped rather than guessed.
+
+use sdl3::keyboard::Scancode;
+
+/// Map an SDL scancode to the Windows VK code the host expects.
+pub fn scancode_to_vk(sc: Scancode) -> Option<u8> {
+    use Scancode as S;
+    Some(match sc {
+        // --- Navigation / editing / whitespace ---
+        S::Backspace => 0x08,
+        S::Tab => 0x09,
+        S::Return => 0x0D,
+        S::Pause => 0x13,
+        S::CapsLock => 0x14,
+        S::Escape => 0x1B,
+        S::Space => 0x20,
+        S::PageUp => 0x21,
+        S::PageDown => 0x22,
+        S::End => 0x23,
+        S::Home => 0x24,
+        S::Left => 0x25,
+        S::Up => 0x26,
+        S::Right => 0x27,
+        S::Down => 0x28,
+        S::PrintScreen => 0x2C,
+        S::Insert => 0x2D,
+        S::Delete => 0x2E,
+
+        // --- Digit row ---
+        S::_0 => 0x30,
+        S::_1 => 0x31,
+        S::_2 => 0x32,
+        S::_3 => 0x33,
+        S::_4 => 0x34,
+        S::_5 => 0x35,
+        S::_6 => 0x36,
+        S::_7 => 0x37,
+        S::_8 => 0x38,
+        S::_9 => 0x39,
+
+        // --- Letters ---
+        S::A => 0x41,
+        S::B => 0x42,
+        S::C => 0x43,
+        S::D => 0x44,
+        S::E => 0x45,
+        S::F => 0x46,
+        S::G => 0x47,
+        S::H => 0x48,
+        S::I => 0x49,
+        S::J => 0x4A,
+        S::K => 0x4B,
+        S::L => 0x4C,
+        S::M => 0x4D,
+        S::N => 0x4E,
+        S::O => 0x4F,
+        S::P => 0x50,
+        S::Q => 0x51,
+        S::R => 0x52,
+        S::S => 0x53,
+        S::T => 0x54,
+        S::U => 0x55,
+        S::V => 0x56,
+        S::W => 0x57,
+        S::X => 0x58,
+        S::Y => 0x59,
+        S::Z => 0x5A,
+
+        // --- Meta / context-menu ---
+        S::LGui => 0x5B,
+        S::RGui => 0x5C,
+        S::Application => 0x5D,
+
+        // --- Numpad ---
+        S::Kp0 => 0x60,
+        S::Kp1 => 0x61,
+        S::Kp2 => 0x62,
+        S::Kp3 => 0x63,
+        S::Kp4 => 0x64,
+        S::Kp5 => 0x65,
+        S::Kp6 => 0x66,
+        S::Kp7 => 0x67,
+        S::Kp8 => 0x68,
+        S::Kp9 => 0x69,
+        S::KpMultiply => 0x6A,
+        S::KpPlus => 0x6B,
+        // KP-Enter → VK_SEPARATOR mirrors the evdev table (KEY_KPENTER → 0x6C).
+        S::KpEnter => 0x6C,
+        S::KpMinus => 0x6D,
+        S::KpPeriod => 0x6E,
+        S::KpDivide => 0x6F,
+
+        // --- Function keys ---
+        S::F1 => 0x70,
+        S::F2 => 0x71,
+        S::F3 => 0x72,
+        S::F4 => 0x73,
+        S::F5 => 0x74,
+        S::F6 => 0x75,
+        S::F7 => 0x76,
+        S::F8 => 0x77,
+        S::F9 => 0x78,
+        S::F10 => 0x79,
+        S::F11 => 0x7A,
+        S::F12 => 0x7B,
+
+        // --- Locks ---
+        S::NumLockClear => 0x90,
+        S::ScrollLock => 0x91,
+
+        // --- Left/right modifiers ---
+        S::LShift => 0xA0,
+        S::RShift => 0xA1,
+        S::LCtrl => 0xA2,
+        S::RCtrl => 0xA3,
+        S::LAlt => 0xA4,
+        S::RAlt => 0xA5,
+
+        // --- OEM punctuation (US-layout positions) ---
+        S::Semicolon => 0xBA,
+        S::Equals => 0xBB,
+        S::Comma => 0xBC,
+        S::Minus => 0xBD,
+        S::Period => 0xBE,
+        S::Slash => 0xBF,
+        S::Grave => 0xC0,
+        S::LeftBracket => 0xDB,
+        S::Backslash => 0xDC,
+        S::RightBracket => 0xDD,
+        S::Apostrophe => 0xDE,
+        S::NonUsBackslash => 0xE2,
+
+        _ => return None,
+    })
+}
+
+/// SDL mouse button → the GameStream button id the wire expects (1=left, 2=middle,
+/// 3=right, 4=X1, 5=X2) — the SDL twin of `keymap::gdk_button_to_gs`.
+pub fn mouse_button_to_gs(b: sdl3::mouse::MouseButton) -> Option<u32> {
+    use sdl3::mouse::MouseButton as B;
+    Some(match b {
+        B::Left => 1,
+        B::Middle => 2,
+        B::Right => 3,
+        B::X1 => 4,
+        B::X2 => 5,
+        _ => return None,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pf_client_core::keymap::evdev_to_vk;
+
+    /// Both tables feed the same wire: for every key the evdev table knows, the SDL
+    /// scancode of the same physical key must map to the same VK.
+    #[test]
+    fn agrees_with_the_evdev_table() {
+        use Scancode as S;
+        let same_key: &[(Scancode, u16)] = &[
+            (S::Backspace, 14),
+            (S::Tab, 15),
+            (S::Return, 28),
+            (S::Escape, 1),
+            (S::Space, 57),
+            (S::PageUp, 104),
+            (S::Left, 105),
+            (S::_0, 11),
+            (S::_1, 2),
+            (S::_9, 10),
+            (S::A, 30),
+            (S::Q, 16),
+            (S::Z, 44),
+            (S::LGui, 125),
+            (S::Kp0, 82),
+            (S::Kp9, 73),
+            (S::KpEnter, 96),
+            (S::F1, 59),
+            (S::F11, 87),
+            (S::F12, 88),
+            (S::NumLockClear, 69),
+            (S::LShift, 42),
+            (S::RAlt, 100),
+            (S::Semicolon, 39),
+            (S::Grave, 41),
+            (S::NonUsBackslash, 86),
+        ];
+        for &(sc, ev) in same_key {
+            assert_eq!(scancode_to_vk(sc), evdev_to_vk(ev), "scancode {sc:?}");
+        }
+        assert_eq!(scancode_to_vk(Scancode::Mute), None); // not in the wire contract
+    }
+}
@@ -0,0 +1,28 @@
+//! The Vulkan session presenter (punktfunk-planning `linux-client-rearchitecture.md`,
+//! Phase 1): an SDL3 window + ash swapchain that presents the shared session pump's
+//! decoded frames, captures input on the `ui_stream` state-machine contract, and reports
+//! the unified stats window on stdout. No UI toolkit anywhere in the dependency tree.
+//!
+//! Two frame paths: software (`CpuFrame` RGBA staging upload) and hardware (the
+//! decoder's NV12 dmabuf imported per-plane into Vulkan + the CICP-driven CSC pass —
+//! `dmabuf.rs`/`csc.rs`), both composited by a letterboxed blit. Devices without the
+//! import extensions, and any import/present failure streak, demote the decoder to
+//! software via the session pump's `force_software` contract, same as the GTK presenter.
+
+#[cfg(target_os = "linux")]
+pub mod csc;
+#[cfg(target_os = "linux")]
+pub mod dmabuf;
+#[cfg(target_os = "linux")]
+pub mod input;
+#[cfg(target_os = "linux")]
+pub mod keymap_sdl;
+#[cfg(target_os = "linux")]
+pub mod overlay;
+#[cfg(target_os = "linux")]
+mod run;
+#[cfg(target_os = "linux")]
+pub mod vk;
+
+#[cfg(target_os = "linux")]
+pub use run::{run_browse, run_session, ActionOutcome, Outcome, SessionOpts};
@@ -0,0 +1,104 @@
+//! The presenter↔console-UI contract (punktfunk-planning
+//! `linux-client-rearchitecture.md` §6.1): the presenter exposes its device and
+//! composites at most ONE sampled RGBA quad per frame; the overlay implementation
+//! (pf-console-ui, Skia) fills offscreen images on its own damage-driven schedule. No
+//! Skia type crosses this line — everything here is ash — and a `frame()` returning
+//! `None` costs the hot path nothing (the quad isn't even recorded).
+
+use ash::vk;
+use pf_client_core::gamepad::{MenuEvent, MenuPulse};
+
+/// The presenter's device, shared with the overlay so its renderer (Skia's
+/// `DirectContext`) creates resources on the same VkDevice/queue. Handles stay valid for
+/// the presenter's lifetime — the overlay must be dropped before it (the run loop owns
+/// both and drops the overlay first).
+pub struct SharedDevice {
+    pub entry: ash::Entry,
+    pub instance: ash::Instance,
+    pub physical_device: vk::PhysicalDevice,
+    pub device: ash::Device,
+    pub queue: vk::Queue,
+    pub queue_family_index: u32,
+}
+
+/// What the overlay may draw this frame — composed by the run loop from session state.
+/// Milestone 1 (OSD/HUD) is text-shaped; the console library replaces this with a
+/// richer scene enum when it moves in.
+pub struct FrameCtx<'a> {
+    /// Swapchain size in pixels — the overlay renders 1:1.
+    pub width: u32,
+    pub height: u32,
+    /// Multi-line stats OSD (top-left panel); `None` = hidden.
+    pub stats: Option<&'a str>,
+    /// The capture hint (bottom-center pill, "click to capture…"); `None` = hidden.
+    pub hint: Option<&'a str>,
+    /// The active gamepad's name (the console library's controller chip).
+    pub pad: Option<&'a str>,
+}
+
+/// One overlay image ready to composite: RGBA, PREMULTIPLIED alpha, already in
+/// `SHADER_READ_ONLY_OPTIMAL`, sized `width`×`height` (normally the `FrameCtx` size; a
+/// stale size during a resize just stretches for a frame).
+pub struct OverlayFrame {
+    pub image: vk::Image,
+    pub view: vk::ImageView,
+    pub width: u32,
+    pub height: u32,
+}
+
+/// An action the overlay raises out of its input handling (browse mode: the console
+/// library's A/B/retry). The run loop hands each to the session binary's callback.
+pub enum OverlayAction {
+    /// Launch this library title as a session (`id` rides the Hello).
+    Launch { id: String, title: String },
+    /// Retry whatever failed (the library fetch).
+    Retry,
+    /// Quit the launcher (B at the root) — ends the process, Gaming Mode returns.
+    Quit,
+}
+
+/// Session lifecycle notifications into the overlay (browse mode drives its scenes off
+/// these; the OSD/HUD ignore them).
+pub enum SessionPhase<'a> {
+    /// A launch action was accepted — the connect is in flight.
+    Connecting,
+    /// Connected; frames are coming.
+    Streaming,
+    /// The connect failed (browse mode returns to the library with this message).
+    Failed(&'a str),
+    /// The session ran and ended (`Some` = abnormal reason for the status strip).
+    Ended(Option<&'a str>),
+}
+
+/// The console-UI side. Object-safe; the session binary passes
+/// `Option<Box<dyn Overlay>>` (None = the Skia-free power-user build).
+pub trait Overlay {
+    /// One-time setup on the presenter's device.
+    fn init(&mut self, shared: &SharedDevice) -> anyhow::Result<()>;
+
+    /// Input routing, before capture sees the event. `true` = consumed (the library or
+    /// a menu is up) — the event must not reach capture/forwarding.
+    fn handle_event(&mut self, event: &sdl3::event::Event) -> bool;
+
+    /// Gamepad menu-mode navigation (browse mode; the run loop drains the service's
+    /// menu channel). Returns a haptic pulse to play on the menu pad, if any.
+    fn handle_menu(&mut self, _event: MenuEvent) -> Option<MenuPulse> {
+        None
+    }
+
+    /// Drain one pending action raised by handled input. Called once per loop
+    /// iteration; return `None` when idle.
+    fn take_action(&mut self) -> Option<OverlayAction> {
+        None
+    }
+
+    /// A session lifecycle edge (browse mode scene driving).
+    fn session_phase(&mut self, _phase: SessionPhase) {}
+
+    /// Once per presenter iteration. Damage-driven: re-render (flush + transition to
+    /// SHADER_READ_ONLY) only when the content or size changed, else return the previous
+    /// image. `None` = nothing to composite. The returned image must stay untouched
+    /// until `frame()` runs again (the presenter runs one frame in flight and the
+    /// implementation keeps a ring of two, so alternating satisfies this).
+    fn frame(&mut self, ctx: &FrameCtx) -> anyhow::Result<Option<OverlayFrame>>;
+}
@@ -0,0 +1,813 @@
+//! The session lifecycle loop: one SDL context on the caller's main thread driving the
+//! window, the Vulkan presenter, input capture, the pumped gamepad service, and the
+//! shared session pump's event/frame channels.
+//!
+//! Two modes over one loop: **single** (`run_session` — one `--connect` stream, exit on
+//! end; the shell↔session contract) and **browse** (`run_browse` — the console library
+//! idles between streams; overlay actions launch sessions, session end returns to the
+//! library; the app quits only on B/window-close).
+//!
+//! Stdout is the machine interface (the shell↔session contract): one `{"ready":true}`
+//! line after the first presented frame, `stats: …` lines once per window while enabled
+//! (Ctrl+Alt+Shift+S toggles). Logs go to stderr (the binary configures tracing so).
+
+use crate::input::Capture;
+use crate::overlay::{FrameCtx, Overlay, OverlayAction, OverlayFrame, SessionPhase};
+use crate::vk::{FrameInput, Presenter};
+use anyhow::{Context as _, Result};
+use pf_client_core::gamepad::GamepadService;
+use pf_client_core::session::{self, SessionEvent, SessionHandle, SessionParams, Stats};
+use pf_client_core::video::VulkanDecodeDevice;
+use pf_client_core::video::{DecodedFrame, DecodedImage};
+use punktfunk_core::client::NativeClient;
+use punktfunk_core::config::Mode;
+use sdl3::event::{Event, WindowEvent};
+use sdl3::keyboard::Mod;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+pub struct SessionOpts {
+    pub window_title: String,
+    /// Start fullscreen (gamescope / `--fullscreen`).
+    pub fullscreen: bool,
+    /// Print `stats:` lines (Ctrl+Alt+Shift+S toggles live).
+    pub print_stats: bool,
+    /// Emit the `{"ready":true}` stdout line after the first presented frame.
+    pub json_status: bool,
+    /// Called once on `Connected` with the host's fingerprint (trust persistence is the
+    /// binary's business — this loop stays store-agnostic).
+    pub on_connected: Option<Box<dyn FnMut([u8; 32])>>,
+    /// The console-UI overlay (§6.1) — `None` is the Skia-free power-user build (stats
+    /// stay stdout-only). An overlay whose `init` fails degrades to `None` with a
+    /// warning rather than killing the session. Browse mode requires one.
+    pub overlay: Option<Box<dyn Overlay>>,
+}
+
+pub enum Outcome {
+    /// The session ran and ended: `None` = deliberate exit (user quit), `Some` = the
+    /// reason the pump reported (host ended, transport error…).
+    Ended(Option<String>),
+    ConnectFailed {
+        msg: String,
+        trust_rejected: bool,
+    },
+}
+
+/// What the session binary decided about an overlay action (browse mode).
+pub enum ActionOutcome {
+    /// Consumed binary-side (a Retry respawned the fetch, …).
+    Handled,
+    /// Start this session (a Launch action; `force_software` from the callback args is
+    /// wired into these params). Boxed: SessionParams is large next to the unit variants.
+    Start(Box<SessionParams>),
+    /// Quit the launcher.
+    Quit,
+}
+
+/// One `--connect` stream session; returns when it ends (the shell↔session contract).
+pub fn run_session<F>(opts: SessionOpts, build_params: F) -> Result<Outcome>
+where
+    F: FnOnce(&GamepadService, Mode, Arc<AtomicBool>, Option<VulkanDecodeDevice>) -> SessionParams,
+{
+    let mut build = Some(build_params);
+    run_inner(
+        opts,
+        ModeCtl::Single(Box::new(move |gp, native, fs, vk| {
+            (build.take().expect("single build runs once"))(gp, native, fs, vk)
+        })),
+    )
+    .map(|o| o.expect("single mode always yields an outcome"))
+}
+
+/// Browse mode: the console library idles between streams. `on_action` receives every
+/// overlay action (Launch/Retry/Quit) plus what a launch needs to build its params —
+/// the gamepad service (`auto_pref`), the native display mode, and a fresh
+/// per-session `force_software` flag.
+pub fn run_browse<F>(opts: SessionOpts, on_action: F) -> Result<()>
+where
+    F: FnMut(
+        OverlayAction,
+        &GamepadService,
+        Mode,
+        Arc<AtomicBool>,
+        Option<VulkanDecodeDevice>,
+    ) -> ActionOutcome,
+{
+    anyhow::ensure!(
+        opts.overlay.is_some(),
+        "--browse needs the console UI (a build with the `ui` feature)"
+    );
+    run_inner(opts, ModeCtl::Browse(Box::new(on_action))).map(|_| ())
+}
+
+/// Params builder for the one single-mode session (called exactly once, post-setup).
+type BuildParams<'a> = Box<
+    dyn FnMut(&GamepadService, Mode, Arc<AtomicBool>, Option<VulkanDecodeDevice>) -> SessionParams
+        + 'a,
+>;
+/// The browse-mode action callback (Launch → params, Retry/Quit → outcome).
+type OnAction<'a> = Box<
+    dyn FnMut(
+            OverlayAction,
+            &GamepadService,
+            Mode,
+            Arc<AtomicBool>,
+            Option<VulkanDecodeDevice>,
+        ) -> ActionOutcome
+        + 'a,
+>;
+
+/// The two run modes, type-erased so one loop serves both.
+enum ModeCtl<'a> {
+    Single(BuildParams<'a>),
+    Browse(OnAction<'a>),
+}
+
+/// Everything one stream session accumulates — created at session start, dropped at
+/// session end (browse mode cycles through several per process lifetime).
+struct StreamState {
+    handle: SessionHandle,
+    connector: Option<Arc<NativeClient>>,
+    capture: Option<Capture>,
+    force_software: Arc<AtomicBool>,
+    ready_announced: bool,
+    mode_line: String,
+    clock_offset_ns: i64,
+    hdr: bool,
+    // Presenter-side 1 s window (design/stats-unification.md): end-to-end
+    // capture→displayed (host-clock corrected) p50+p95, display = decoded→displayed p50.
+    win_e2e_us: Vec<u64>,
+    win_disp_us: Vec<u64>,
+    win_start: Instant,
+    presented: PresentedWindow,
+    // Hardware-path health: a failure streak (or a device with no import support at
+    // all) demotes the decoder to software via the shared flag — once per session.
+    dmabuf_demoted: bool,
+    hw_fails: u32,
+    /// The OSD's text (multi-line; rebuilt each Stats window).
+    osd_text: String,
+}
+
+impl StreamState {
+    fn new(params: SessionParams, force_software: Arc<AtomicBool>) -> StreamState {
+        StreamState {
+            handle: session::start(params),
+            connector: None,
+            capture: None,
+            force_software,
+            ready_announced: false,
+            mode_line: String::new(),
+            clock_offset_ns: 0,
+            hdr: false,
+            win_e2e_us: Vec::with_capacity(256),
+            win_disp_us: Vec::with_capacity(256),
+            win_start: Instant::now(),
+            presented: PresentedWindow::default(),
+            dmabuf_demoted: false,
+            hw_fails: 0,
+            osd_text: String::new(),
+        }
+    }
+
+    /// Stop the pump and JOIN its thread — required before any device-wide idle or
+    /// teardown (the pump submits decode work to the shared device). Quick: the pump
+    /// notices `stop` within its 20 ms receive timeout, and on a normal end it's
+    /// already returning.
+    fn shutdown(mut self) {
+        self.handle.stop.store(true, Ordering::SeqCst);
+        if let Some(t) = self.handle.thread.take() {
+            let _ = t.join();
+        }
+    }
+
+    /// Deliberate user exit (chord / window close): release capture, close with
+    /// QUIT_CLOSE_CODE so the host tears down instead of lingering, stop the pump.
+    /// The pump then emits `Ended(None)` — the loop's normal end path picks it up.
+    fn request_quit(&mut self) {
+        if let Some(cap) = &mut self.capture {
+            cap.release(true);
+        }
+        if let Some(c) = &self.connector {
+            c.disconnect_quit();
+        }
+        self.handle.stop.store(true, Ordering::SeqCst);
+    }
+}
+
+fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>> {
+    sdl3::hint::set("SDL_JOYSTICK_THREAD", "1");
+    let sdl = sdl3::init().context("SDL init")?;
+    let video = sdl.video().context("SDL video")?;
+    let mut window = {
+        let mut b = video.window(&opts.window_title, 1280, 720);
+        b.position_centered().resizable().vulkan();
+        if opts.fullscreen {
+            b.fullscreen();
+        }
+        b.build().context("SDL window")?
+    };
+    let instance_exts = window
+        .vulkan_instance_extensions()
+        .map_err(|e| anyhow::anyhow!("vulkan instance extensions: {e}"))?;
+    let mut presenter = Presenter::new(&window, &instance_exts).context("vulkan presenter")?;
+    // A valid black frame immediately — the window is honest while the connect runs.
+    presenter.present(&window, FrameInput::Redraw, None)?;
+
+    let mut overlay = opts.overlay.take();
+    if let Some(o) = overlay.as_mut() {
+        if let Err(e) = o.init(&presenter.shared_device()) {
+            if matches!(mode, ModeCtl::Browse(_)) {
+                return Err(e).context("console UI init (required for --browse)");
+            }
+            tracing::warn!(error = %format!("{e:#}"),
+                "console-UI overlay init failed — continuing without it");
+            overlay = None;
+        }
+    }
+
+    let gamepad_subsystem = sdl.gamepad().context("SDL gamepad")?;
+    let (gamepad, mut pump) = GamepadService::pumped(gamepad_subsystem);
+    let escape_rx = gamepad.escape_events();
+    let disconnect_rx = gamepad.disconnect_events();
+    let menu_rx = gamepad.menu_events();
+    if matches!(mode, ModeCtl::Browse(_)) {
+        // Menu mode for the launcher's lifetime (an attached session supersedes
+        // translation automatically — the GTK launcher never turned it off either).
+        gamepad.set_menu_mode(true);
+    }
+
+    // The native display mode — the `0 = native` fallback for the requested stream mode
+    // (the GTK client reads the monitor under its window; same idea).
+    let native = window
+        .get_display()
+        .and_then(|d| d.get_mode())
+        .map(|m| Mode {
+            width: m.w.max(0) as u32,
+            height: m.h.max(0) as u32,
+            refresh_hz: m.refresh_rate.round().max(0.0) as u32,
+        })
+        .unwrap_or(Mode {
+            width: 1920,
+            height: 1080,
+            refresh_hz: 60,
+        });
+
+    let mut stream: Option<StreamState> = match &mut mode {
+        ModeCtl::Single(build) => {
+            let force_software = Arc::new(AtomicBool::new(false));
+            let params = build(
+                &gamepad,
+                native,
+                force_software.clone(),
+                presenter.vulkan_decode(),
+            );
+            Some(StreamState::new(params, force_software))
+        }
+        ModeCtl::Browse(_) => None,
+    };
+
+    let mut event_pump = sdl
+        .event_pump()
+        .map_err(|e| anyhow::anyhow!("SDL event pump: {e}"))?;
+    let mouse = sdl.mouse();
+
+    let mut fullscreen = opts.fullscreen;
+    let mut print_stats = opts.print_stats;
+    let mut overlay_frame: Option<OverlayFrame> = None;
+
+    let outcome = 'main: loop {
+        // --- SDL events (input, window, gamepads) ---------------------------------------
+        // Block briefly in SDL's own wait so idle costs nothing; while streaming, frames
+        // arrive on the channel below and 1 ms bounds the added present latency. In
+        // browse-idle the per-iteration FIFO present vsync-throttles the loop anyway.
+        let streaming = stream.as_ref().is_some_and(|s| s.connector.is_some());
+        let timeout = Duration::from_millis(if streaming { 1 } else { 5 });
+        let first = event_pump.wait_event_timeout(timeout);
+        let mut queued: Vec<Event> = Vec::new();
+        if let Some(e) = first {
+            queued.push(e);
+        }
+        while let Some(e) = event_pump.poll_event() {
+            queued.push(e);
+        }
+        for event in queued {
+            // The console UI sees input first: a consumed event (the library's keyboard
+            // navigation, a menu) never reaches capture/forwarding.
+            if let Some(o) = overlay.as_mut() {
+                if o.handle_event(&event) {
+                    continue;
+                }
+            }
+            match event {
+                Event::Quit { .. } => {
+                    // Window close / SIGINT: deliberate exit, host teardown now.
+                    if let Some(st) = &mut stream {
+                        st.request_quit();
+                    }
+                    break 'main Some(Outcome::Ended(None));
+                }
+                Event::Window { win_event, .. } => match win_event {
+                    WindowEvent::FocusLost => {
+                        if let Some(cap) = stream.as_mut().and_then(|s| s.capture.as_mut()) {
+                            if cap.release(false) {
+                                mouse.set_relative_mouse_mode(&window, false);
+                                mouse.show_cursor(true);
+                                tracing::info!("focus lost — input released");
+                            }
+                        }
+                    }
+                    WindowEvent::FocusGained => {
+                        // An auto-release (Alt-Tab) undoes itself; a chord release
+                        // stays released until the user opts back in.
+                        if let Some(cap) = stream.as_mut().and_then(|s| s.capture.as_mut()) {
+                            if cap.should_reengage() {
+                                cap.engage();
+                                mouse.set_relative_mouse_mode(&window, true);
+                                mouse.show_cursor(false);
+                                tracing::info!("focus gained — input recaptured");
+                            }
+                        }
+                    }
+                    WindowEvent::PixelSizeChanged(..) | WindowEvent::Resized(..) => {
+                        presenter.recreate_swapchain(&window)?;
+                        presenter.present(&window, FrameInput::Redraw, overlay_frame.as_ref())?;
+                    }
+                    WindowEvent::Exposed => {
+                        presenter.present(&window, FrameInput::Redraw, overlay_frame.as_ref())?;
+                    }
+                    _ => {}
+                },
+                Event::KeyDown {
+                    scancode: Some(sc),
+                    keymod,
+                    repeat: false,
+                    ..
+                } => {
+                    let chord = keymod.intersects(Mod::LCTRLMOD | Mod::RCTRLMOD)
+                        && keymod.intersects(Mod::LALTMOD | Mod::RALTMOD)
+                        && keymod.intersects(Mod::LSHIFTMOD | Mod::RSHIFTMOD);
+                    use sdl3::keyboard::Scancode;
+                    if chord && sc == Scancode::Q {
+                        if let Some(cap) = stream.as_mut().and_then(|s| s.capture.as_mut()) {
+                            if cap.captured() {
+                                cap.release(true);
+                                mouse.set_relative_mouse_mode(&window, false);
+                                mouse.show_cursor(true);
+                            } else {
+                                cap.engage();
+                                mouse.set_relative_mouse_mode(&window, true);
+                                mouse.show_cursor(false);
+                            }
+                            tracing::info!(captured = cap.captured(), "chord: release/engage");
+                        }
+                        continue;
+                    }
+                    if chord && sc == Scancode::D {
+                        if let Some(st) = &mut stream {
+                            tracing::info!("chord: disconnect");
+                            st.request_quit();
+                            mouse.set_relative_mouse_mode(&window, false);
+                            mouse.show_cursor(true);
+                            // The pump emits Ended(None); the end path routes per mode.
+                        }
+                        continue;
+                    }
+                    if chord && sc == Scancode::S {
+                        print_stats = !print_stats;
+                        continue;
+                    }
+                    // F11 or Alt+Enter (some keyboards' Fn layer sends a media key for
+                    // plain F11 — the Moonlight-standard alias always exists).
+                    let alt_enter =
+                        sc == Scancode::Return && keymod.intersects(Mod::LALTMOD | Mod::RALTMOD);
+                    if sc == Scancode::F11 || alt_enter {
+                        fullscreen = !fullscreen;
+                        tracing::debug!(fullscreen, "fullscreen toggle");
+                        if let Err(e) = window.set_fullscreen(fullscreen) {
+                            tracing::warn!(error = %e, "fullscreen toggle");
+                        }
+                        continue;
+                    }
+                    if let Some(cap) = stream.as_mut().and_then(|s| s.capture.as_mut()) {
+                        cap.on_key_down(sc);
+                    }
+                }
+                Event::KeyUp {
+                    scancode: Some(sc), ..
+                } => {
+                    if let Some(cap) = stream.as_mut().and_then(|s| s.capture.as_mut()) {
+                        cap.on_key_up(sc);
+                    }
+                }
+                Event::MouseMotion { xrel, yrel, .. } => {
+                    if let Some(cap) = stream.as_mut().and_then(|s| s.capture.as_mut()) {
+                        cap.on_motion(xrel, yrel);
+                    }
+                }
+                Event::MouseButtonDown { mouse_btn, .. } => {
+                    if let Some(cap) = stream.as_mut().and_then(|s| s.capture.as_mut()) {
+                        if !cap.captured() {
+                            // The engaging click is suppressed toward the host.
+                            cap.engage();
+                            mouse.set_relative_mouse_mode(&window, true);
+                            mouse.show_cursor(false);
+                        } else {
+                            cap.on_button_down(mouse_btn);
+                        }
+                    }
+                }
+                Event::MouseButtonUp { mouse_btn, .. } => {
+                    if let Some(cap) = stream.as_mut().and_then(|s| s.capture.as_mut()) {
+                        cap.on_button_up(mouse_btn);
+                    }
+                }
+                Event::MouseWheel { x, y, .. } => {
+                    if let Some(cap) = stream.as_mut().and_then(|s| s.capture.as_mut()) {
+                        cap.on_wheel(x, y);
+                    }
+                }
+                // Everything else (gamepad add/remove/button/axis/touchpad/sensor…) is
+                // the pumped gamepad worker's — it ignores what it doesn't know.
+                other => pump.handle_event(other),
+            }
+        }
+        pump.tick();
+        // One coalesced MouseMove per iteration — pure motion must reach the host
+        // without waiting for a click/key to flush it.
+        if let Some(cap) = stream.as_mut().and_then(|s| s.capture.as_mut()) {
+            cap.flush_motion();
+        }
+
+        // Controller escape chord: release capture (+ leave fullscreen on desktop — under
+        // a `--fullscreen` gamescope launch there is nothing to release into). Only
+        // emitted while a session is attached.
+        while escape_rx.try_recv().is_ok() {
+            if let Some(cap) = stream.as_mut().and_then(|s| s.capture.as_mut()) {
+                if cap.release(true) {
+                    mouse.set_relative_mouse_mode(&window, false);
+                    mouse.show_cursor(true);
+                }
+            }
+            if fullscreen && !opts.fullscreen {
+                fullscreen = false;
+                let _ = window.set_fullscreen(false);
+            }
+        }
+        // Escape chord held past the threshold: the controller's Ctrl+Alt+Shift+D.
+        if disconnect_rx.try_recv().is_ok() {
+            if let Some(st) = &mut stream {
+                tracing::info!("controller chord: disconnect");
+                st.request_quit();
+                mouse.set_relative_mouse_mode(&window, false);
+                mouse.show_cursor(true);
+            }
+        }
+
+        // --- Browse: menu navigation + overlay actions (library visible only) ------------
+        if let ModeCtl::Browse(on_action) = &mut mode {
+            if stream.is_none() {
+                while let Ok(ev) = menu_rx.try_recv() {
+                    if let Some(o) = overlay.as_mut() {
+                        if let Some(pulse) = o.handle_menu(ev) {
+                            gamepad.menu_rumble(pulse);
+                        }
+                    }
+                }
+            }
+            if let Some(action) = overlay.as_mut().and_then(|o| o.take_action()) {
+                let force_software = Arc::new(AtomicBool::new(false));
+                match on_action(
+                    action,
+                    &gamepad,
+                    native,
+                    force_software.clone(),
+                    presenter.vulkan_decode(),
+                ) {
+                    ActionOutcome::Handled => {}
+                    ActionOutcome::Start(params) => {
+                        stream = Some(StreamState::new(*params, force_software));
+                        if let Some(o) = overlay.as_mut() {
+                            o.session_phase(SessionPhase::Connecting);
+                        }
+                    }
+                    ActionOutcome::Quit => break Some(Outcome::Ended(None)),
+                }
+            }
+        }
+
+        // --- Session events --------------------------------------------------------------
+        // `stream` may become None mid-drain (browse-mode session end) — re-borrow each
+        // event, act, and stop draining on the terminal ones.
+        while let Some(st) = stream.as_mut() {
+            let Ok(ev) = st.handle.events.try_recv() else {
+                break;
+            };
+            match ev {
+                SessionEvent::Connected {
+                    connector: c,
+                    mode: m,
+                    fingerprint,
+                } => {
+                    st.mode_line = format!("{}×{}@{}", m.width, m.height, m.refresh_hz);
+                    tracing::info!(mode = %st.mode_line, "connected");
+                    window
+                        .set_title(&format!("{} · {}", opts.window_title, st.mode_line))
+                        .ok();
+                    gamepad.attach(c.clone());
+                    st.clock_offset_ns = c.clock_offset_ns;
+                    let mut cap = Capture::new(c.clone());
+                    cap.engage(); // capture engages when the stream starts (ui_stream parity)
+                    mouse.set_relative_mouse_mode(&window, true);
+                    mouse.show_cursor(false);
+                    st.capture = Some(cap);
+                    st.connector = Some(c);
+                    if let Some(f) = opts.on_connected.as_mut() {
+                        f(fingerprint);
+                    }
+                    if let Some(o) = overlay.as_mut() {
+                        o.session_phase(SessionPhase::Streaming);
+                    }
+                }
+                SessionEvent::Stats(s) => {
+                    st.osd_text = stats_text(&st.mode_line, &s, &st.presented, st.hdr);
+                    if print_stats {
+                        println!("stats: {}", st.osd_text.replace('\n', " | "));
+                    }
+                }
+                SessionEvent::Failed {
+                    msg,
+                    trust_rejected,
+                } => match &mode {
+                    ModeCtl::Single(_) => {
+                        break 'main Some(Outcome::ConnectFailed {
+                            msg,
+                            trust_rejected,
+                        })
+                    }
+                    ModeCtl::Browse(_) => {
+                        tracing::warn!(%msg, "connect failed — back to the library");
+                        if let Some(st) = stream.take() {
+                            st.shutdown();
+                        }
+                        mouse.set_relative_mouse_mode(&window, false);
+                        mouse.show_cursor(true);
+                        if let Some(o) = overlay.as_mut() {
+                            o.session_phase(SessionPhase::Failed(&msg));
+                        }
+                        break;
+                    }
+                },
+                SessionEvent::Ended(reason) => {
+                    gamepad.detach();
+                    if let Some(cap) = &mut st.capture {
+                        cap.release(true);
+                    }
+                    mouse.set_relative_mouse_mode(&window, false);
+                    mouse.show_cursor(true);
+                    match &mode {
+                        ModeCtl::Single(_) => break 'main Some(Outcome::Ended(reason)),
+                        ModeCtl::Browse(_) => {
+                            window.set_title(&opts.window_title).ok();
+                            if let Some(st) = stream.take() {
+                                st.shutdown();
+                            }
+                            if let Some(o) = overlay.as_mut() {
+                                o.session_phase(SessionPhase::Ended(reason.as_deref()));
+                            }
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+
+        // --- Console UI: damage-driven overlay re-render for this iteration --------------
+        if let Some(o) = overlay.as_mut() {
+            let (pw, ph) = window.size_in_pixels();
+            let (stats, hint) = match &stream {
+                Some(st) if st.connector.is_some() => {
+                    let hint = match &st.capture {
+                        Some(cap) if !cap.captured() => Some(if gamepad.active().is_some() {
+                            HINT_WITH_PAD
+                        } else {
+                            HINT_KEYBOARD
+                        }),
+                        _ => None,
+                    };
+                    (
+                        (print_stats && !st.osd_text.is_empty()).then_some(st.osd_text.as_str()),
+                        hint,
+                    )
+                }
+                _ => (None, None),
+            };
+            let pad_name = gamepad.active().map(|p| p.name);
+            let ctx = FrameCtx {
+                width: pw,
+                height: ph,
+                stats,
+                hint,
+                pad: pad_name.as_deref(),
+            };
+            match o.frame(&ctx) {
+                Ok(f) => overlay_frame = f,
+                Err(e) => {
+                    if matches!(mode, ModeCtl::Browse(_)) {
+                        return Err(e).context("console UI frame (required for --browse)");
+                    }
+                    tracing::warn!(error = %format!("{e:#}"),
+                        "overlay frame failed — disabling the console UI");
+                    overlay = None;
+                    overlay_frame = None;
+                }
+            }
+        }
+
+        // --- Frames: drain to the newest, upload + present -------------------------------
+        let mut presented_video = false;
+        if let Some(st) = &mut stream {
+            let mut newest: Option<DecodedFrame> = None;
+            while let Ok(f) = st.handle.frames.try_recv() {
+                newest = Some(f);
+            }
+            if let Some(f) = newest {
+                let DecodedFrame {
+                    pts_ns,
+                    decoded_ns,
+                    image,
+                } = f;
+                let did_present = match image {
+                    DecodedImage::Cpu(c) => {
+                        st.hdr = c.color.is_pq();
+                        presenter.present(&window, FrameInput::Cpu(&c), overlay_frame.as_ref())?
+                    }
+                    DecodedImage::Dmabuf(d)
+                        if presenter.supports_dmabuf() && !st.dmabuf_demoted =>
+                    {
+                        st.hdr = d.color.is_pq();
+                        match presenter.present(
+                            &window,
+                            FrameInput::Dmabuf(d),
+                            overlay_frame.as_ref(),
+                        ) {
+                            Ok(p) => {
+                                st.hw_fails = 0;
+                                p
+                            }
+                            // Import/CSC failure is survivable (the stream continues on
+                            // the next frame) — but a streak means this box can't do the
+                            // hw path: demote the decoder to software, same contract as
+                            // the GTK presenter's GL-converter failures.
+                            Err(e) => {
+                                st.hw_fails += 1;
+                                tracing::warn!(error = %format!("{e:#}"), fails = st.hw_fails,
+                                    "hardware present failed");
+                                if st.hw_fails >= 3 && !st.dmabuf_demoted {
+                                    st.dmabuf_demoted = true;
+                                    tracing::warn!("demoting the decoder to software");
+                                    st.force_software.store(true, Ordering::Relaxed);
+                                }
+                                false
+                            }
+                        }
+                    }
+                    DecodedImage::Dmabuf(_) => {
+                        // No import extensions on this device (or already demoted) — the
+                        // pump rebuilds the decoder as software; frames flow again soon.
+                        if !st.dmabuf_demoted {
+                            st.dmabuf_demoted = true;
+                            tracing::warn!(
+                                "no dmabuf import support on this device — demoting the \
+                                 decoder to software"
+                            );
+                            st.force_software.store(true, Ordering::Relaxed);
+                        }
+                        false
+                    }
+                    // Vulkan-Video: decoded on the presenter's own device — present is
+                    // views + CSC, no import step to gate on. Same failure-streak
+                    // demotion contract as the dmabuf path.
+                    DecodedImage::VkFrame(v) if !st.dmabuf_demoted => {
+                        st.hdr = v.color.is_pq();
+                        match presenter.present(
+                            &window,
+                            FrameInput::VkFrame(v),
+                            overlay_frame.as_ref(),
+                        ) {
+                            Ok(p) => {
+                                st.hw_fails = 0;
+                                p
+                            }
+                            Err(e) => {
+                                st.hw_fails += 1;
+                                tracing::warn!(error = %format!("{e:#}"), fails = st.hw_fails,
+                                    "vulkan-video present failed");
+                                if st.hw_fails >= 3 {
+                                    st.dmabuf_demoted = true;
+                                    tracing::warn!("demoting the decoder to software");
+                                    st.force_software.store(true, Ordering::Relaxed);
+                                }
+                                false
+                            }
+                        }
+                    }
+                    DecodedImage::VkFrame(_) => false, // demoted — drain until rebuild
+                };
+                if did_present {
+                    presented_video = true;
+                    let displayed_ns = session::now_ns();
+                    if opts.json_status && !st.ready_announced {
+                        st.ready_announced = true;
+                        println!("{{\"ready\":true}}");
+                    }
+                    // The `displayed` stamp (same clamp rules as the pump's windows).
+                    let e2e = (displayed_ns as i128 + st.clock_offset_ns as i128 - pts_ns as i128)
+                        .max(0) as u64;
+                    if e2e > 0 && e2e < 10_000_000_000 {
+                        st.win_e2e_us.push(e2e / 1000);
+                    }
+                    st.win_disp_us
+                        .push(displayed_ns.saturating_sub(decoded_ns) / 1000);
+                }
+            }
+
+            // Fold the presenter window into the shared stats line once per second.
+            if st.win_start.elapsed() >= Duration::from_secs(1) {
+                let (e2e_p50, e2e_p95) = session::window_percentiles(&mut st.win_e2e_us);
+                let (disp_p50, _) = session::window_percentiles(&mut st.win_disp_us);
+                st.presented = PresentedWindow {
+                    e2e_p50_ms: e2e_p50 as f32 / 1000.0,
+                    e2e_p95_ms: e2e_p95 as f32 / 1000.0,
+                    display_ms: disp_p50 as f32 / 1000.0,
+                };
+                st.win_e2e_us.clear();
+                st.win_disp_us.clear();
+                st.win_start = Instant::now();
+            }
+        }
+
+        // Browse with no video driving presents (library / connecting): composite the
+        // overlay every iteration — FIFO vsync-throttles this to the display rate.
+        if matches!(mode, ModeCtl::Browse(_))
+            && !presented_video
+            && stream.as_ref().is_none_or(|s| s.connector.is_none())
+        {
+            presenter.present(&window, FrameInput::Redraw, overlay_frame.as_ref())?;
+        }
+    };
+
+    // Join the pump BEFORE the device-wide idle: its decode submissions on the shared
+    // device would race vkDeviceWaitIdle otherwise.
+    if let Some(st) = stream.take() {
+        st.shutdown();
+    }
+    // Overlay resources live on the presenter's device: quiesce the queue first, drop
+    // the overlay (its Drop destroys the Skia surfaces), THEN the presenter tears down.
+    presenter.wait_idle();
+    drop(overlay);
+    Ok(outcome)
+}
+
+/// The presenter's share of the unified stats window — folded into each printed line.
+#[derive(Default)]
+struct PresentedWindow {
+    e2e_p50_ms: f32,
+    e2e_p95_ms: f32,
+    display_ms: f32,
+}
+
+/// The capture hints (`ui_stream` parity — the words the user reads while released).
+const HINT_KEYBOARD: &str = "Click the stream to capture input · Ctrl+Alt+Shift+Q releases · \
+     Ctrl+Alt+Shift+D disconnects · Ctrl+Alt+Shift+S stats";
+const HINT_WITH_PAD: &str = "Click the stream to capture input · Ctrl+Alt+Shift+Q releases · \
+     Ctrl+Alt+Shift+D disconnects · hold L1 + R1 + Start + Select to leave";
+
+/// The unified stats window (design/stats-unification.md) as OSD text — multi-line for
+/// the console-UI panel; the stdout `stats:` line joins it with `|`.
+fn stats_text(mode_line: &str, s: &Stats, p: &PresentedWindow, hdr: bool) -> String {
+    let mut text = format!(
+        "{mode_line} · {:.0} fps · {:.1} Mb/s · {}{}",
+        s.fps,
+        s.mbps,
+        if s.decoder.is_empty() { "-" } else { s.decoder },
+        if hdr { " · HDR" } else { "" },
+    );
+    text.push_str(&format!(
+        "\ne2e {:.1}/{:.1} ms (p50/p95)",
+        p.e2e_p50_ms, p.e2e_p95_ms
+    ));
+    if s.split {
+        text.push_str(&format!(" · host {:.1} · net {:.1}", s.host_ms, s.net_ms));
+    } else {
+        text.push_str(&format!(" · host+net {:.1}", s.host_net_ms));
+    }
+    text.push_str(&format!(
+        " · decode {:.1} · display {:.1} ms",
+        s.decode_ms, p.display_ms
+    ));
+    if s.lost > 0 {
+        text.push_str(&format!("\nlost {} ({:.1}%)", s.lost, s.lost_pct));
+    }
+    text
+}
@@ -21,9 +21,10 @@ use crate::quic::{
 };
 use crate::session::{Frame, Session};
 use crate::transport::UdpTransport;
+use std::collections::VecDeque;
 use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
 use std::sync::mpsc::{Receiver, RecvTimeoutError, SyncSender};
-use std::sync::{Arc, Mutex};
+use std::sync::{Arc, Condvar, Mutex};
 use std::time::{Duration, Instant};

 /// A control-stream request the embedder makes on the open handshake stream: a mode switch or a
@@ -118,29 +119,136 @@ pub struct ProbeOutcome {
    pub send_dropped: u32,
 }

-/// Frames buffered between the data-plane pump and the embedder. Small: the embedder
-/// (decoder) should drain at frame rate; when it falls behind, the newest frame is dropped
-/// (display freshness over completeness — FEC/keyframes recover).
-const FRAME_QUEUE: usize = 16;
+/// Depth at/above which the pre-decode hand-off queue counts as "not draining" for the clock-free
+/// standing-queue detector. A consumer that keeps up (or drains newest-per-vsync, like the Apple
+/// client) holds this near 0; a transient Wi-Fi clump or a small jitter buffer spikes it briefly then
+/// drains. Sits above a reasonable jitter buffer (~100 ms @ 60 fps) so only a genuine backlog trips it.
+const QUEUE_HIGH: usize = 6;
+
+/// Depth at/below which the hand-off queue is considered drained — resets the standing-queue counter.
+/// A true standing queue never falls back to this; a clump does within a few frames.
+const QUEUE_LOW: usize = 2;
+
+/// Consecutive frames the hand-off queue must sit ≥ [`QUEUE_HIGH`] (never dropping to [`QUEUE_LOW`])
+/// before the pump declares a standing backlog and jumps to live. ~0.5 s at 60 fps — long enough that
+/// a burst/clump (which drains in a few frames) never reaches it.
+const STANDING_FRAMES: u32 = 30;
+
+/// Memory backstop on the pre-decode hand-off queue. The standing-queue detector jumps to live long
+/// before this (typically ≤ QUEUE_HIGH + STANDING_FRAMES deep), and a jump already requested a
+/// keyframe, so on the rare path that outruns it (a wedged consumer during the flush cooldown) dropping
+/// the OLDEST queued AU is safe — the pending IDR re-anchors decode regardless. Purely bounds memory.
+const FRAME_QUEUE_HARD_CAP: usize = 90;

 /// Backlog latency bound: when completed frames keep arriving further than this behind the host's
-/// capture clock (skew-corrected), the pump flushes the receive backlog
-/// ([`Session::flush_backlog`]) and requests a keyframe instead of playing that far behind
-/// forever. Deliberately generous — an interactive stream is unusable well before 400 ms, but the
-/// bound must sit safely above the skew handshake's own error (≈ RTT/2) plus normal delivery
-/// jitter so a healthy stream can never trip it.
+/// capture clock (skew-corrected), the pump jumps to live (discards the receive backlog + the queued
+/// AUs and requests a keyframe) instead of playing that far behind forever. Deliberately generous — an
+/// interactive stream is unusable well before 400 ms, but the bound must sit safely above the skew
+/// handshake's own error (≈ RTT/2) plus normal delivery jitter so a healthy stream can never trip it.
+/// This is the CLOCK-BASED detector; the clock-free [`QUEUE_HIGH`]/[`STANDING_FRAMES`] detector covers
+/// same-clock and no-handshake sessions (where `clock_offset_ns == 0` disarms this one).
 const FLUSH_LATENCY: Duration = Duration::from_millis(400);

-/// How many CONSECUTIVE over-bound frames arm a flush (~0.5 s at 60 fps). A genuine standing queue
-/// puts EVERY frame over the bound; a one-off burst (an IDR, a Wi-Fi scan blip) clears within a
-/// frame or two and never reaches the count.
+/// How many CONSECUTIVE over-bound frames arm the clock-based jump (~0.5 s at 60 fps). A genuine
+/// standing queue puts EVERY frame over the bound; a one-off burst (an IDR, a Wi-Fi scan blip) clears
+/// within a frame or two and never reaches the count.
 const FLUSH_AFTER_FRAMES: u32 = 30;

-/// Minimum spacing between backlog flushes, so a bottleneck that instantly rebuilds the queue (a
-/// link that can't sustain the bitrate at all) degrades into a periodic skip + a logged warning
-/// instead of a continuous flush/keyframe storm.
+/// Minimum spacing between jump-to-live events, so a bottleneck that instantly rebuilds the queue (a
+/// link/consumer that can't sustain the bitrate at all) degrades into a periodic skip + a logged
+/// warning instead of a continuous flush/keyframe storm.
 const FLUSH_COOLDOWN: Duration = Duration::from_secs(2);

+/// The pre-decode video hand-off from the data-plane pump to the embedder. Unlike the side planes
+/// (self-contained samples that drop the newest on overflow), video AUs are reference-chained under the
+/// host's infinite GOP: dropping ANY frame mid-stream corrupts every dependent frame until the next
+/// IDR. So this queue is strictly FIFO and never drops a frame from the middle. When the embedder falls
+/// PERSISTENTLY behind — the queue stops draining — the pump JUMPS TO LIVE instead ([`clear`] + a
+/// keyframe request), so decode resumes cleanly at an IDR rather than ratcheting latency forever (the
+/// old bounded channel silently dropped the NEWEST AU on overflow — backwards for a live stream, and a
+/// reference-chain break the loss counters never saw). A transient burst fills it briefly and drains on
+/// its own, so a clump never costs a keyframe.
+///
+/// [`clear`]: FrameChannel::clear
+struct FrameChannel {
+    inner: Mutex<FrameQueue>,
+    ready: Condvar,
+}
+
+struct FrameQueue {
+    q: VecDeque<Frame>,
+    /// Set when the pump exits so a blocked [`FrameChannel::pop`] reports the stream ended
+    /// ([`PunktfunkError::Closed`]) rather than a spurious timeout (the old mpsc did this on sender drop).
+    closed: bool,
+}
+
+/// Outcome of [`FrameChannel::pop`] — mirrors the old `recv_timeout` results so `next_frame`'s
+/// Timeout/Closed mapping is unchanged.
+enum FramePop {
+    Frame(Frame),
+    Timeout,
+    Closed,
+}
+
+impl FrameChannel {
+    fn new() -> Self {
+        Self {
+            inner: Mutex::new(FrameQueue {
+                q: VecDeque::new(),
+                closed: false,
+            }),
+            ready: Condvar::new(),
+        }
+    }
+
+    /// Pump side: append a completed AU and wake a blocked consumer. Enforces the memory backstop
+    /// ([`FRAME_QUEUE_HARD_CAP`]) by dropping the oldest (see its doc — a jump-to-live keyframe is
+    /// already in flight by the time this can bite).
+    fn push(&self, frame: Frame) {
+        let mut st = self.inner.lock().unwrap();
+        st.q.push_back(frame);
+        while st.q.len() > FRAME_QUEUE_HARD_CAP {
+            st.q.pop_front();
+        }
+        drop(st);
+        self.ready.notify_one();
+    }
+
+    /// Pump side: current queued depth — the clock-free standing-queue signal.
+    fn depth(&self) -> usize {
+        self.inner.lock().unwrap().q.len()
+    }
+
+    /// Pump side: discard the whole backlog (the jump-to-live path); returns how many were dropped.
+    fn clear(&self) -> usize {
+        let mut st = self.inner.lock().unwrap();
+        let n = st.q.len();
+        st.q.clear();
+        n
+    }
+
+    /// Pump side: mark the stream ended and wake every blocked consumer.
+    fn close(&self) {
+        self.inner.lock().unwrap().closed = true;
+        self.ready.notify_all();
+    }
+
+    /// Consumer side: pop the oldest AU, waiting up to `timeout` for one to arrive.
+    fn pop(&self, timeout: Duration) -> FramePop {
+        let mut st = self.inner.lock().unwrap();
+        if st.q.is_empty() && !st.closed {
+            st = self.ready.wait_timeout(st, timeout).unwrap().0;
+        }
+        if let Some(f) = st.q.pop_front() {
+            FramePop::Frame(f)
+        } else if st.closed {
+            FramePop::Closed
+        } else {
+            FramePop::Timeout
+        }
+    }
+}
+
 /// Audio packets buffered for the embedder: 64 × 5 ms = 320 ms of slack. A lagging
 /// embedder drops the newest packet (the audio renderer conceals the gap).
 const AUDIO_QUEUE: usize = 64;
@@ -177,7 +285,7 @@ pub struct NativeClient {
    // embedders can share one `Arc<NativeClient>` across their plane threads (the same
    // one-thread-per-plane contract the C ABI documents — the lock is uncontended there,
    // and two threads racing one plane now serialize instead of being undefined).
-    frames: Mutex<Receiver<Frame>>,
+    frames: Arc<FrameChannel>,
    audio: Mutex<Receiver<AudioPacket>>,
    rumble: Mutex<Receiver<(u16, u16, u16)>>,
    /// Inbound DualSense feedback (lightbar / player LEDs / adaptive triggers) — 0xCD datagrams.
@@ -365,7 +473,7 @@ impl NativeClient {
        identity: Option<(String, String)>,
        timeout: Duration,
    ) -> Result<NativeClient> {
-        let (frame_tx, frame_rx) = std::sync::mpsc::sync_channel::<Frame>(FRAME_QUEUE);
+        let frame_chan = Arc::new(FrameChannel::new());
        let (audio_tx, audio_rx) = std::sync::mpsc::sync_channel::<AudioPacket>(AUDIO_QUEUE);
        let (rumble_tx, rumble_rx) = std::sync::mpsc::sync_channel::<(u16, u16, u16)>(RUMBLE_QUEUE);
        let (hidout_tx, hidout_rx) = std::sync::mpsc::sync_channel::<HidOutput>(HIDOUT_QUEUE);
@@ -385,6 +493,7 @@ impl NativeClient {
        let hot_tids = Arc::new(Mutex::new(Vec::new()));

        let host = host.to_string();
+        let frame_chan_w = frame_chan.clone();
        let shutdown_w = shutdown.clone();
        let quit_w = quit.clone();
        let mode_slot_w = mode_slot.clone();
@@ -424,7 +533,7 @@ impl NativeClient {
                    launch,
                    pin,
                    identity,
-                    frame_tx,
+                    frames: frame_chan_w,
                    audio_tx,
                    rumble_tx,
                    hidout_tx,
@@ -468,7 +577,7 @@ impl NativeClient {
        };
        *mode_slot.lock().unwrap() = negotiated;
        Ok(NativeClient {
-            frames: Mutex::new(frame_rx),
+            frames: frame_chan,
            audio: Mutex::new(audio_rx),
            rumble: Mutex::new(rumble_rx),
            hidout: Mutex::new(hidout_rx),
@@ -735,10 +844,10 @@ impl NativeClient {
    /// (`&self` here supports the cross-plane sharing; a plane's queue is still
    /// single-consumer by contract).
    pub fn next_frame(&self, timeout: Duration) -> Result<Frame> {
-        match self.frames.lock().unwrap().recv_timeout(timeout) {
-            Ok(f) => Ok(f),
-            Err(RecvTimeoutError::Timeout) => Err(PunktfunkError::NoFrame),
-            Err(RecvTimeoutError::Disconnected) => Err(PunktfunkError::Closed),
+        match self.frames.pop(timeout) {
+            FramePop::Frame(f) => Ok(f),
+            FramePop::Timeout => Err(PunktfunkError::NoFrame),
+            FramePop::Closed => Err(PunktfunkError::Closed),
        }
    }

@@ -860,7 +969,7 @@ struct WorkerArgs {
    launch: Option<String>,
    pin: Option<[u8; 32]>,
    identity: Option<(String, String)>,
-    frame_tx: SyncSender<Frame>,
+    frames: Arc<FrameChannel>,
    audio_tx: SyncSender<AudioPacket>,
    rumble_tx: SyncSender<(u16, u16, u16)>,
    hidout_tx: SyncSender<HidOutput>,
@@ -898,7 +1007,7 @@ async fn worker_main(args: WorkerArgs) {
        launch,
        pin,
        identity,
-        frame_tx,
+        frames,
        audio_tx,
        rumble_tx,
        hidout_tx,
@@ -1231,7 +1340,7 @@ async fn worker_main(args: WorkerArgs) {
    let pump_probe = probe.clone();
    let pump_hot_tids = hot_tids.clone();
    let _ = tokio::task::spawn_blocking(move || {
-        pin_thread_user_interactive(); // feeds frame_tx → the client's user-interactive video pump
+        pin_thread_user_interactive(); // feeds the frame channel → the user-interactive video pump
        register_hot_tid(&pump_hot_tids); // this thread does UDP receive + FEC reassembly — hint it
                                          // Adaptive-FEC loss reporting: every ADAPT_REPORT_INTERVAL, report the loss observed over the
                                          // window (shards FEC recovered, plus a bump if any frame went unrecoverable) so the host can
@@ -1239,10 +1348,12 @@ async fn worker_main(args: WorkerArgs) {
        const ADAPT_REPORT_INTERVAL: Duration = Duration::from_millis(750);
        let mut last_report = Instant::now();
        let (mut last_recovered, mut last_received, mut last_dropped) = (0u64, 0u64, 0u64);
-        // Backlog latency bound (see FLUSH_LATENCY): consecutive over-bound frames + the last
-        // flush, for the cooldown. Armed only when the skew handshake succeeded (offset ≠ 0) —
-        // without it the host and client clocks aren't comparable and the bound would misfire.
+        // Jump-to-live state (see the guard in the loop below): the clock-based over-bound run
+        // (`stale_frames`, armed only when the skew handshake succeeded so the clocks are comparable),
+        // the clock-free non-draining-queue run (`standing_frames`), and the last-jump instant for the
+        // shared cooldown.
        let mut stale_frames: u32 = 0;
+        let mut standing_frames: u32 = 0;
        let mut last_flush: Option<Instant> = None;
        while !pump_shutdown.load(Ordering::SeqCst) {
            // Mirror the reassembler's unrecoverable-drop count for the client's keyframe-recovery
@@ -1278,37 +1389,66 @@ async fn worker_main(args: WorkerArgs) {
                    if frame.flags & FLAG_PROBE as u32 != 0 {
                        continue; // speed-test filler, not video — measured via the counters above
                    }
-                    // Latency bound: a standing receive queue (pump transiently outpaced, a Wi-Fi
-                    // stall, power-save clumping) never drains by itself — the pump consumes at
-                    // exactly the arrival rate, so once behind, the stream stays behind for good
-                    // (observed live: stuck 6–7 s). When frames keep completing over the bound,
-                    // discard the whole backlog and ask for a keyframe: one visible skip instead of
-                    // a permanently unusable stream. Suspended during a speed test (the probe
-                    // MEASURES a saturated queue; flushing would corrupt its receive counters).
-                    if clock_offset_ns != 0 && !probe_active {
-                        let lat_ns =
-                            now_realtime_ns() + clock_offset_ns as i128 - frame.pts_ns as i128;
-                        if lat_ns > FLUSH_LATENCY.as_nanos() as i128 {
+                    // Jump-to-live guard. A standing receive/hand-off queue never drains by itself —
+                    // the pump consumes strictly in order at the arrival rate, so once behind, the
+                    // stream stays behind for good (observed live: stuck 6–7 s). Pre-decode AUs are
+                    // reference-chained (infinite GOP), so we can NOT drop a frame mid-stream to catch
+                    // up; the only safe recovery is to discard the whole backlog and re-anchor decode
+                    // on a fresh keyframe. Two independent "we're behind" signals arm it, both gated by
+                    // FLUSH_COOLDOWN, both suspended during a speed test (the probe MEASURES a saturated
+                    // queue; flushing would corrupt its counters):
+                    //  * clock-based — completed frames sit > FLUSH_LATENCY behind the skew-corrected
+                    //    capture clock for FLUSH_AFTER_FRAMES straight. Needs the skew handshake, and
+                    //    also catches kernel/reassembler backlog the hand-off queue hasn't reached yet.
+                    //  * clock-free — the pre-decode hand-off queue stopped draining: its depth stayed
+                    //    ≥ QUEUE_HIGH (never falling to QUEUE_LOW) for STANDING_FRAMES straight. Works
+                    //    with no handshake / a same-clock session (where the clock path is disarmed),
+                    //    and is the direct signal that the embedder can't keep up. A transient Wi-Fi
+                    //    clump drains in a few frames and never reaches the count.
+                    if probe_active {
+                        // Keep both detectors disarmed across a speed test so its (deliberately)
+                        // saturated queue doesn't leave a primed count that fires the moment it ends.
+                        stale_frames = 0;
+                        standing_frames = 0;
+                    } else {
+                        let lat_ns = if clock_offset_ns != 0 {
+                            now_realtime_ns() + clock_offset_ns as i128 - frame.pts_ns as i128
+                        } else {
+                            0
+                        };
+                        if clock_offset_ns != 0 && lat_ns > FLUSH_LATENCY.as_nanos() as i128 {
                            stale_frames += 1;
                        } else {
                            stale_frames = 0;
                        }
-                        if stale_frames >= FLUSH_AFTER_FRAMES
+                        let depth = frames.depth();
+                        if depth >= QUEUE_HIGH {
+                            standing_frames += 1;
+                        } else if depth <= QUEUE_LOW {
+                            standing_frames = 0;
+                        }
+                        let clock_behind = stale_frames >= FLUSH_AFTER_FRAMES;
+                        let queue_behind = standing_frames >= STANDING_FRAMES;
+                        if (clock_behind || queue_behind)
                            && last_flush.is_none_or(|t| t.elapsed() >= FLUSH_COOLDOWN)
                        {
                            stale_frames = 0;
+                            standing_frames = 0;
                            last_flush = Some(Instant::now());
                            let flushed = session.flush_backlog().unwrap_or(0);
+                            let dropped = frames.clear();
                            let _ = ctrl_tx.send(CtrlRequest::Keyframe);
                            tracing::warn!(
-                                behind_ms = lat_ns / 1_000_000,
+                                behind_ms = if clock_behind { lat_ns / 1_000_000 } else { -1 },
+                                queue_depth = depth,
                                flushed_datagrams = flushed,
-                                "receive backlog exceeded the latency bound — flushed to live"
+                                dropped_frames = dropped,
+                                "receive backlog stopped draining — jumped to live (flush + keyframe)"
                            );
                            continue; // this frame is part of the stale past — don't render it
                        }
                    }
-                    let _ = frame_tx.try_send(frame);
+                    frames.push(frame);
                }
                Err(PunktfunkError::NoFrame) => {
                    std::thread::sleep(Duration::from_micros(300));
@@ -1316,6 +1456,10 @@ async fn worker_main(args: WorkerArgs) {
                Err(_) => break,
            }
        }
+        // The pump exited (shutdown / fatal session error) — wake any consumer blocked in
+        // `next_frame` with a Closed signal instead of a spurious timeout (the old mpsc did this
+        // implicitly when the sender dropped).
+        frames.close();
    })
    .await;

@@ -1328,3 +1472,83 @@ async fn worker_main(args: WorkerArgs) {
    };
    conn.close(close_code.into(), b"client closed");
 }
+
+#[cfg(test)]
+mod frame_channel_tests {
+    use super::{FrameChannel, FramePop, FRAME_QUEUE_HARD_CAP};
+    use crate::session::Frame;
+    use std::time::Duration;
+
+    fn frame(i: u32) -> Frame {
+        Frame {
+            data: vec![i as u8],
+            frame_index: i,
+            pts_ns: i as u64,
+            flags: 0,
+        }
+    }
+
+    fn popped(ch: &FrameChannel) -> Option<u32> {
+        match ch.pop(Duration::from_millis(0)) {
+            FramePop::Frame(f) => Some(f.frame_index),
+            _ => None,
+        }
+    }
+
+    #[test]
+    fn fifo_order_and_depth() {
+        let ch = FrameChannel::new();
+        assert_eq!(ch.depth(), 0);
+        ch.push(frame(1));
+        ch.push(frame(2));
+        assert_eq!(ch.depth(), 2);
+        assert_eq!(popped(&ch), Some(1)); // oldest first (never newest-wins pre-decode)
+        assert_eq!(popped(&ch), Some(2));
+        assert_eq!(ch.depth(), 0);
+    }
+
+    #[test]
+    fn empty_pop_times_out_not_closed() {
+        let ch = FrameChannel::new();
+        assert!(matches!(
+            ch.pop(Duration::from_millis(1)),
+            FramePop::Timeout
+        ));
+    }
+
+    #[test]
+    fn clear_drops_backlog_and_reports_count() {
+        let ch = FrameChannel::new();
+        for i in 0..5 {
+            ch.push(frame(i));
+        }
+        assert_eq!(ch.clear(), 5); // the jump-to-live discard returns what it dropped
+        assert_eq!(ch.depth(), 0);
+        assert!(matches!(
+            ch.pop(Duration::from_millis(1)),
+            FramePop::Timeout
+        ));
+    }
+
+    #[test]
+    fn close_after_drain_reports_closed() {
+        let ch = FrameChannel::new();
+        ch.push(frame(7));
+        ch.close();
+        // Queued frames still drain BEFORE the Closed signal.
+        assert_eq!(popped(&ch), Some(7));
+        assert!(matches!(ch.pop(Duration::from_millis(1)), FramePop::Closed));
+    }
+
+    #[test]
+    fn hard_cap_drops_oldest() {
+        let ch = FrameChannel::new();
+        let total = FRAME_QUEUE_HARD_CAP as u32 + 10;
+        for i in 0..total {
+            ch.push(frame(i));
+        }
+        // Capped at the backstop; the OLDEST were dropped, so the newest survive in order.
+        assert_eq!(ch.depth(), FRAME_QUEUE_HARD_CAP);
+        assert_eq!(popped(&ch), Some(total - FRAME_QUEUE_HARD_CAP as u32));
+    }
+}
@@ -34,7 +34,8 @@ fn parse_compositor(s: &str) -> Option<crate::vdisplay::Compositor> {
        "kwin" | "kde" => Some(Kwin),
        "mutter" | "gnome" => Some(Mutter),
        "gamescope" => Some(Gamescope),
-        "wlroots" | "sway" => Some(Wlroots),
+        "hyprland" => Some(Hyprland),
+        "wlroots" | "sway" | "river" => Some(Wlroots),
        _ => None,
    }
 }
@@ -149,7 +149,12 @@ pub fn default_backend() -> Backend {
            if c.eq_ignore_ascii_case("kwin") {
                return Backend::KwinFakeInput;
            }
-            if c.eq_ignore_ascii_case("wlroots") || c.eq_ignore_ascii_case("sway") {
+            if c.eq_ignore_ascii_case("wlroots")
+                || c.eq_ignore_ascii_case("sway")
+                // Hyprland kept the wlr virtual-input protocols, so it injects through the same
+                // backend as sway/river (design/hyprland-support.md D4).
+                || c.eq_ignore_ascii_case("hyprland")
+            {
                return Backend::WlrVirtual;
            }
            // mutter (GNOME) falls through to the XDG_CURRENT_DESKTOP check below.
@@ -2657,7 +2657,7 @@ mod tests {
        let arr = body.as_array().expect("array");
        // Every backend the host knows, in stable order.
        let ids: Vec<&str> = arr.iter().map(|c| c["id"].as_str().unwrap()).collect();
-        assert_eq!(ids, ["kwin", "gamescope", "mutter", "wlroots"]);
+        assert_eq!(ids, ["kwin", "gamescope", "mutter", "wlroots", "hyprland"]);
        for c in arr {
            assert!(c["available"].is_boolean());
            assert!(c["default"].is_boolean());
@@ -2246,8 +2246,20 @@ fn pick_compositor(
    available: &[crate::vdisplay::Compositor],
    detected: Option<crate::vdisplay::Compositor>,
 ) -> Option<crate::vdisplay::Compositor> {
-    match crate::vdisplay::Compositor::from_pref(pref) {
+    use crate::vdisplay::Compositor;
+    match Compositor::from_pref(pref) {
        Some(want) if available.contains(&want) => Some(want),
+        // `CompositorPref::Wlroots` names the wlroots *family* (D2): sway/river ([`Wlroots`]) and
+        // Hyprland are distinct backends but mutually-exclusive live sessions, so honor the request
+        // with whichever family member is actually available — the detected one if it's a family
+        // member, else the first available of the two.
+        Some(Compositor::Wlroots) => match detected {
+            Some(d @ (Compositor::Wlroots | Compositor::Hyprland)) => Some(d),
+            _ => [Compositor::Wlroots, Compositor::Hyprland]
+                .into_iter()
+                .find(|c| available.contains(c))
+                .or(detected),
+        },
        _ => detected,
    }
 }
@@ -3240,8 +3252,11 @@ fn virtual_stream(ctx: SessionContext) -> Result<()> {
    // compositing), NOT an encoder problem. Logged every 2 s when `PUNKTFUNK_PERF`.
    let (mut diag_new, mut diag_repeat) = (0u64, 0u64);
    let mut diag_at = std::time::Instant::now();
-    // Last client-requested forced IDR — the intra-refresh rate limit window anchor (see below).
-    let mut last_forced_idr: Option<std::time::Instant> = None;
+    // Anchor for the forced-IDR cooldown (see the keyframe-request handling below): the timestamp of
+    // the most recent forced/opening IDR. The session's pipeline just opened on an IDR, so start the
+    // clock now — that coalesces the keyframe storm a client fires while its decoder wedges on the cold
+    // opening GOP, instead of answering it with a redundant second IDR.
+    let mut last_forced_idr: Option<std::time::Instant> = Some(std::time::Instant::now());
    // Per-stage latency breakdown (PUNKTFUNK_PERF): per-call µs for the GPU-bound stages so we see
    // exactly where the capture→encoded latency goes — cap=try_latest (ring read + colour convert),
    // submit=encode_picture launch, wait=lock_bitstream (the scheduling wait + ASIC encode, the one
@@ -3355,6 +3370,7 @@ fn virtual_stream(ctx: SessionContext) -> Result<()> {
                    inflight.clear();
                    last_au_at = std::time::Instant::now();
                    encoder_resets = 0;
+                    last_forced_idr = Some(std::time::Instant::now()); // fresh encoder opens on an IDR — anchor the cooldown
                }
                Err(e) => {
                    tracing::error!(error = %format!("{e:#}"), ?new_mode,
@@ -3371,16 +3387,29 @@ fn virtual_stream(ctx: SessionContext) -> Result<()> {
            want_kf = true;
        }
        if want_kf {
-            // Intra-refresh mode: clients request a keyframe on EVERY FEC-unrecoverable frame
-            // (`frames_dropped` polling), but the refresh wave already heals those within ~half a
-            // second — answering each with a full IDR is the 20-40× spike cascade the wave exists
-            // to avoid. Serve the first request immediately (a genuinely wedged decoder recovers
-            // at once), then suppress further requests for one window and let the wave heal.
-            const IDR_WINDOW: std::time::Duration = std::time::Duration::from_secs(2);
-            let suppress = enc.caps().intra_refresh
-                && last_forced_idr.is_some_and(|t| t.elapsed() < IDR_WINDOW);
+            // Clients request a keyframe on EVERY FEC-unrecoverable frame (`frames_dropped` polling)
+            // and keep asking until the IDR actually arrives + decodes — a full round-trip on a link
+            // that is already behind. Answering each request with a full IDR is a 20-40× bitrate spike
+            // that DEEPENS the very loss it is recovering from: a burst of loss → a storm of IDRs →
+            // more loss, the periodic double-jolt a Wi-Fi client sees. So coalesce a request storm into
+            // at most ONE forced IDR per cooldown, ALWAYS — not only under intra-refresh (the old gate;
+            // a full-IDR recovery is exactly where the storm is worst). Serve the first request
+            // immediately (a genuinely wedged decoder recovers at once), then suppress for the window.
+            //
+            // Intra-refresh heals via its own gradual wave (~0.5 s) and can afford a long window; a
+            // full-IDR recovery relies on the keyframe itself, so its window is shorter — long enough to
+            // swallow the round-trip echo of one recovery event, short enough to re-issue a *lost* IDR
+            // promptly.
+            const IDR_COOLDOWN_INTRA: std::time::Duration = std::time::Duration::from_secs(2);
+            const IDR_COOLDOWN_FULL: std::time::Duration = std::time::Duration::from_millis(750);
+            let window = if enc.caps().intra_refresh {
+                IDR_COOLDOWN_INTRA
+            } else {
+                IDR_COOLDOWN_FULL
+            };
+            let suppress = last_forced_idr.is_some_and(|t| t.elapsed() < window);
            if suppress {
-                tracing::debug!("keyframe request suppressed — intra-refresh wave healing");
+                tracing::debug!("keyframe request coalesced — within the IDR cooldown");
            } else {
                tracing::debug!("forcing keyframe (client decode recovery)");
                enc.request_keyframe();
@@ -3523,6 +3552,7 @@ fn virtual_stream(ctx: SessionContext) -> Result<()> {
                interval = new_interval;
                cur_node_id = new_node_id;
                enc.request_keyframe(); // belt-and-suspenders; a fresh encoder opens on an IDR anyway
+                last_forced_idr = Some(std::time::Instant::now()); // anchor the IDR cooldown from the rebuild
                next = std::time::Instant::now();
                // The owed AUs died with the old encoder — drop their in-flight records and
                // restart the encode-stall clock (the rebuild loop above may have eaten seconds,
@@ -4093,6 +4123,22 @@ mod tests {
            pick_compositor(CompositorPref::Gamescope, &[Gamescope], None),
            Some(Gamescope)
        );
+        // Wlroots family (D2): the shared `Wlroots` pref resolves to whichever of sway/river
+        // (Wlroots) and Hyprland is the live session.
+        assert_eq!(
+            pick_compositor(CompositorPref::Wlroots, &[Hyprland], Some(Hyprland)),
+            Some(Hyprland)
+        );
+        // …and to Wlroots-proper on a sway/river host.
+        assert_eq!(
+            pick_compositor(CompositorPref::Wlroots, &[Wlroots], Some(Wlroots)),
+            Some(Wlroots)
+        );
+        // Family fallback even if detection came back empty but a member is available.
+        assert_eq!(
+            pick_compositor(CompositorPref::Wlroots, &[Hyprland], None),
+            Some(Hyprland)
+        );
    }

    #[test]
@@ -261,7 +261,10 @@ pub fn observe_session_instance(active: &ActiveSession) {
 fn is_desktop_kind(kind: ActiveKind) -> bool {
    matches!(
        kind,
-        ActiveKind::DesktopKde | ActiveKind::DesktopGnome | ActiveKind::DesktopWlroots
+        ActiveKind::DesktopKde
+            | ActiveKind::DesktopGnome
+            | ActiveKind::DesktopWlroots
+            | ActiveKind::DesktopHyprland
    )
 }

@@ -270,12 +273,18 @@ fn is_desktop_kind(kind: ActiveKind) -> bool {
 pub enum Compositor {
    /// KWin / Plasma 6 — `zkde_screencast` virtual output.
    Kwin,
-    /// wlroots (Sway/Hyprland) — headless `create_output`.
+    /// wlroots proper (Sway / River) — headless `swaymsg create_output`.
    Wlroots,
    /// Mutter / GNOME — headless backend + Mutter DBus `RecordVirtual`.
    Mutter,
    /// gamescope — spawned headless at the client's size/refresh; capture its PipeWire node.
    Gamescope,
+    /// Hyprland — headless `hyprctl output create` + the xdg-desktop-portal-hyprland (xdph)
+    /// ScreenCast portal. A distinct backend from [`Wlroots`](Compositor::Wlroots): Hyprland
+    /// dropped wlroots in v0.42 but kept the client-facing wlr protocols, so it shares the wlr
+    /// virtual-input path yet needs its own IPC (`hyprctl`) and portal (xdph) — see
+    /// `design/hyprland-support.md`.
+    Hyprland,
 }

 impl Compositor {
@@ -287,6 +296,7 @@ impl Compositor {
            Compositor::Wlroots => "wlroots",
            Compositor::Mutter => "mutter",
            Compositor::Gamescope => "gamescope",
+            Compositor::Hyprland => "hyprland",
        }
    }

@@ -294,9 +304,10 @@ impl Compositor {
    pub fn label(self) -> &'static str {
        match self {
            Compositor::Kwin => "KWin / KDE Plasma",
-            Compositor::Wlroots => "wlroots (Sway / Hyprland)",
+            Compositor::Wlroots => "wlroots (Sway / River)",
            Compositor::Mutter => "Mutter / GNOME",
            Compositor::Gamescope => "gamescope",
+            Compositor::Hyprland => "Hyprland",
        }
    }

@@ -308,6 +319,10 @@ impl Compositor {
            Compositor::Wlroots => P::Wlroots,
            Compositor::Mutter => P::Mutter,
            Compositor::Gamescope => P::Gamescope,
+            // D2: no distinct wire byte for Hyprland — it shares the wlroots-family `Wlroots` pref.
+            // A client asking for `wlroots`/`hyprland` gets whichever of the two is the live session
+            // ([`pick_compositor`](crate::punktfunk1::pick_compositor) resolves the family).
+            Compositor::Hyprland => P::Wlroots,
        }
    }

@@ -324,12 +339,13 @@ impl Compositor {
    }

    /// Every backend, in a stable display order (for enumeration / UIs).
-    pub fn all() -> [Compositor; 4] {
+    pub fn all() -> [Compositor; 5] {
        [
            Compositor::Kwin,
            Compositor::Gamescope,
            Compositor::Mutter,
            Compositor::Wlroots,
+            Compositor::Hyprland,
        ]
    }
 }
@@ -355,6 +371,9 @@ pub fn available() -> Vec<Compositor> {
        if wlroots::is_available() {
            v.push(Compositor::Wlroots);
        }
+        if hyprland::is_available() {
+            v.push(Compositor::Hyprland);
+        }
        v
    }
    #[cfg(not(target_os = "linux"))]
@@ -375,8 +394,11 @@ pub enum ActiveKind {
    DesktopKde,
    /// A GNOME / Mutter desktop is live.
    DesktopGnome,
-    /// A wlroots (Sway / Hyprland) desktop is live.
+    /// A wlroots-proper (Sway / River) desktop is live.
    DesktopWlroots,
+    /// A Hyprland desktop is live (distinct from [`DesktopWlroots`](ActiveKind::DesktopWlroots):
+    /// its own `hyprctl` IPC + xdph portal, though it shares the wlr virtual-input path).
+    DesktopHyprland,
    /// No recognized graphical session is running for our uid.
    None,
 }
@@ -395,8 +417,14 @@ pub struct SessionEnv {
    pub xdg_runtime_dir: String,
    /// `DBUS_SESSION_BUS_ADDRESS` (defaults to `unix:path=<runtime>/bus`).
    pub dbus_session_bus_address: String,
-    /// `XDG_CURRENT_DESKTOP` to advertise (KDE/GNOME/sway/gamescope) — drives portal/EIS routing.
+    /// `XDG_CURRENT_DESKTOP` to advertise (KDE/GNOME/sway/Hyprland/gamescope) — drives portal/EIS
+    /// routing (xdph keys its Hyprland-specific behavior off `Hyprland`).
    pub xdg_current_desktop: Option<String>,
+    /// `HYPRLAND_INSTANCE_SIGNATURE` of the live Hyprland instance (`Some` only for
+    /// [`ActiveKind::DesktopHyprland`]). `hyprctl` needs it to reach the right instance socket;
+    /// [`apply_session_env`] exports it so the systemd-`--user` host works without inheriting the
+    /// session env (unlike sway's `SWAYSOCK`). `None` for every other compositor.
+    pub hyprland_signature: Option<String>,
 }

 /// The live session: its [`ActiveKind`] plus the [`SessionEnv`] to target it.
@@ -431,6 +459,7 @@ pub fn compositor_for_kind(kind: ActiveKind) -> Option<Compositor> {
        ActiveKind::DesktopKde => Some(Compositor::Kwin),
        ActiveKind::DesktopGnome => Some(Compositor::Mutter),
        ActiveKind::DesktopWlroots => Some(Compositor::Wlroots),
+        ActiveKind::DesktopHyprland => Some(Compositor::Hyprland),
        ActiveKind::None => None,
    }
 }
@@ -495,7 +524,10 @@ pub fn detect_active_session() -> ActiveSession {
                "gamescope" | "gamescope-wl" => (ActiveKind::Gaming, 1),
                "kwin_wayland" => (ActiveKind::DesktopKde, 4),
                "gnome-shell" => (ActiveKind::DesktopGnome, 4),
-                "sway" | "Hyprland" | "hyprland" | "river" => (ActiveKind::DesktopWlroots, 4),
+                // Hyprland is its own backend (hyprctl + xdph) — split it out of the sway/river
+                // wlroots-proper family (design/hyprland-support.md D1).
+                "Hyprland" | "hyprland" => (ActiveKind::DesktopHyprland, 4),
+                "sway" | "river" => (ActiveKind::DesktopWlroots, 4),
                _ => continue,
            };
            let pid = name.parse::<u32>().ok();
@@ -518,10 +550,11 @@ pub fn detect_active_session() -> ActiveSession {
        }
    }

-    // Wayland-protocol backends (KWin, wlroots) need the live socket; Gaming-attach and Mutter are
-    // node/D-Bus driven and don't.
+    // Wayland-protocol backends (KWin, wlroots, Hyprland) need the live socket for input (the wlr
+    // virtual pointer/keyboard client connects to it); Gaming-attach and Mutter are node/D-Bus
+    // driven and don't.
    let wayland_display = match kind {
-        ActiveKind::DesktopKde | ActiveKind::DesktopWlroots => {
+        ActiveKind::DesktopKde | ActiveKind::DesktopWlroots | ActiveKind::DesktopHyprland => {
            find_wayland_socket(&xdg_runtime_dir, uid)
        }
        _ => None,
@@ -530,9 +563,18 @@ pub fn detect_active_session() -> ActiveSession {
        ActiveKind::DesktopKde => Some("KDE".to_string()),
        ActiveKind::DesktopGnome => Some("GNOME".to_string()),
        ActiveKind::DesktopWlroots => Some("sway".to_string()),
+        // G4: advertise the real desktop so portal routing (portals.conf `[Hyprland]`) and xdph's
+        // own Hyprland checks work — NOT the old blanket `sway`.
+        ActiveKind::DesktopHyprland => Some("Hyprland".to_string()),
        ActiveKind::Gaming => Some("gamescope".to_string()),
        ActiveKind::None => None,
    };
+    // Discover the Hyprland instance signature so `hyprctl` can reach the compositor even when the
+    // host runs as a systemd `--user` service that never inherited the session env.
+    let hyprland_signature = match kind {
+        ActiveKind::DesktopHyprland => find_hypr_signature(&xdg_runtime_dir, uid),
+        _ => None,
+    };
    ActiveSession {
        kind,
        env: SessionEnv {
@@ -540,11 +582,44 @@ pub fn detect_active_session() -> ActiveSession {
            xdg_runtime_dir,
            dbus_session_bus_address: dbus,
            xdg_current_desktop,
+            hyprland_signature,
        },
        compositor_pid: winning_pid,
    }
 }

+/// Find the live Hyprland instance signature (`HYPRLAND_INSTANCE_SIGNATURE`) for our uid. Trust a
+/// valid inherited value first (the host launched inside the session); otherwise pick the
+/// newest-mtime instance directory under `$XDG_RUNTIME_DIR/hypr/` that we own and that still has a
+/// live `.socket.sock` — the same "newest wins" heuristic as [`find_wayland_socket`]. A desktop
+/// normally exposes exactly one. (Phase-2 refinement: match the instance to `compositor_pid` via
+/// `hyprctl instances` when several coexist — `design/hyprland-support.md` §Phase-1.1.)
+#[cfg(target_os = "linux")]
+fn find_hypr_signature(runtime: &str, uid: u32) -> Option<String> {
+    use std::os::unix::fs::MetadataExt;
+    let hypr = std::path::Path::new(runtime).join("hypr");
+    if let Ok(sig) = std::env::var("HYPRLAND_INSTANCE_SIGNATURE") {
+        if !sig.is_empty() && hypr.join(&sig).join(".socket.sock").exists() {
+            return Some(sig);
+        }
+    }
+    let mut cands: Vec<(std::time::SystemTime, String)> = Vec::new();
+    for e in std::fs::read_dir(&hypr).ok()?.flatten() {
+        let Ok(md) = e.metadata() else { continue };
+        if !md.is_dir() || md.uid() != uid {
+            continue;
+        }
+        if !e.path().join(".socket.sock").exists() {
+            continue;
+        }
+        let name = e.file_name().to_string_lossy().into_owned();
+        let mtime = md.modified().unwrap_or(std::time::UNIX_EPOCH);
+        cands.push((mtime, name));
+    }
+    cands.sort_by_key(|(m, _)| std::cmp::Reverse(*m));
+    cands.into_iter().next().map(|(_, n)| n)
+}
+
 #[cfg(not(target_os = "linux"))]
 pub fn detect_active_session() -> ActiveSession {
    ActiveSession::none()
@@ -619,6 +694,14 @@ pub fn apply_session_env(active: &ActiveSession) {
    if let Some(d) = &e.xdg_current_desktop {
        std::env::set_var("XDG_CURRENT_DESKTOP", d);
    }
+    // Hyprland: export the discovered instance signature so `hyprctl` reaches the live compositor
+    // (fixes G4 for the systemd `--user` host, which never inherited it). Only set when detection
+    // found a Hyprland session; a stale value from a previous connect is cleared otherwise so a
+    // Hyprland→sway switch can't leave `hyprctl` pointed at a dead instance.
+    match &e.hyprland_signature {
+        Some(sig) => std::env::set_var("HYPRLAND_INSTANCE_SIGNATURE", sig),
+        None => std::env::remove_var("HYPRLAND_INSTANCE_SIGNATURE"),
+    }
    // Topology (Stage 2): the per-compositor backends (KWin/Mutter) now read
    // [`effective_topology`] directly at create time — the console policy, else the legacy
    // `PUNKTFUNK_{KWIN,MUTTER}_VIRTUAL_PRIMARY` env, else the Auto default (exclusive on the
@@ -667,6 +750,20 @@ pub fn settle_desktop_portal(chosen: Compositor) {
            .status();
        std::thread::sleep(std::time::Duration::from_millis(600));
    }
+    // Hyprland capture rides the xdg ScreenCast portal serviced by xdph (G5): on a mid-stream switch
+    // xdph may still hold the old session's Wayland/instance env, so restart it (+ the frontend) to
+    // re-read the now-live session, mirroring the KWin settling above.
+    if chosen == Compositor::Hyprland {
+        let _ = std::process::Command::new("systemctl")
+            .args([
+                "--user",
+                "try-restart",
+                "xdg-desktop-portal-hyprland.service",
+                "xdg-desktop-portal.service",
+            ])
+            .status();
+        std::thread::sleep(std::time::Duration::from_millis(600));
+    }
    tracing::info!(
        compositor = chosen.id(),
        "settled desktop portal env for the switched-to session"
@@ -742,7 +839,9 @@ pub fn apply_input_env(chosen: Compositor, dedicated_launch: bool) {
        Compositor::Kwin => "kwin",
        // GNOME has neither fake_input nor the wlr protocols → RemoteDesktop portal via libei.
        Compositor::Mutter => "libei",
-        Compositor::Wlroots => "wlr",
+        // Hyprland kept `zwlr_virtual_pointer_v1` + `zwp_virtual_keyboard_v1` (D4) — same wlr
+        // injector as sway/river, no code change.
+        Compositor::Wlroots | Compositor::Hyprland => "wlr",
    };
    std::env::set_var("PUNKTFUNK_INPUT_BACKEND", backend);
    if chosen == Compositor::Gamescope {
@@ -857,12 +956,14 @@ pub fn detect() -> Result<Compositor> {
    if let Some(v) = crate::config::config().compositor.as_deref() {
        return match v.trim().to_ascii_lowercase().as_str() {
            "kwin" | "kde" | "plasma" => Ok(Compositor::Kwin),
-            "wlroots" | "sway" | "hyprland" | "wlr" => Ok(Compositor::Wlroots),
+            // `hyprland` names the distinct backend (D1); `wlroots`/`sway`/`wlr` stay wlroots-proper.
+            "hyprland" | "hypr" => Ok(Compositor::Hyprland),
+            "wlroots" | "sway" | "wlr" | "river" => Ok(Compositor::Wlroots),
            "mutter" | "gnome" => Ok(Compositor::Mutter),
            "gamescope" => Ok(Compositor::Gamescope),
            other => {
                anyhow::bail!(
-                    "unknown PUNKTFUNK_COMPOSITOR '{other}' (kwin|wlroots|mutter|gamescope)"
+                    "unknown PUNKTFUNK_COMPOSITOR '{other}' (kwin|wlroots|hyprland|mutter|gamescope)"
                )
            }
        };
@@ -878,10 +979,9 @@ pub fn detect() -> Result<Compositor> {
        Ok(Compositor::Kwin)
    } else if desktop.contains("GNOME") {
        Ok(Compositor::Mutter)
-    } else if desktop.contains("SWAY")
-        || desktop.contains("WLROOTS")
-        || desktop.contains("HYPRLAND")
-    {
+    } else if desktop.contains("HYPRLAND") {
+        Ok(Compositor::Hyprland)
+    } else if desktop.contains("SWAY") || desktop.contains("WLROOTS") {
        Ok(Compositor::Wlroots)
    } else {
        anyhow::bail!(
@@ -900,6 +1000,7 @@ pub fn open(compositor: Compositor) -> Result<Box<dyn VirtualDisplay>> {
            Compositor::Gamescope => Ok(Box::new(gamescope::GamescopeDisplay::new()?)),
            Compositor::Mutter => Ok(Box::new(mutter::MutterDisplay::new()?)),
            Compositor::Wlroots => Ok(Box::new(wlroots::WlrootsDisplay::new()?)),
+            Compositor::Hyprland => Ok(Box::new(hyprland::HyprlandDisplay::new()?)),
        }
    }
    #[cfg(target_os = "windows")]
@@ -935,6 +1036,9 @@ pub fn probe(compositor: Compositor) -> Result<()> {
    {
        match compositor {
            Compositor::Kwin => kwin::probe(),
+            // Hyprland gets a real pre-flight: `hyprctl` must reach the compositor (else a clear
+            // error instead of a create-time failure), plus the permission-system warning.
+            Compositor::Hyprland => hyprland::probe(),
            // gamescope spawns its own nested session per `create`; Mutter is D-Bus on demand;
            // wlroots creates the output on demand — nothing to pre-check beyond "Linux".
            Compositor::Gamescope | Compositor::Mutter | Compositor::Wlroots => Ok(()),
@@ -1076,6 +1180,9 @@ pub(crate) mod identity;
 #[path = "vdisplay/admission.rs"]
 pub(crate) mod admission;
 #[cfg(target_os = "linux")]
+#[path = "vdisplay/linux/hyprland.rs"]
+mod hyprland;
+#[cfg(target_os = "linux")]
 #[path = "vdisplay/linux/kwin.rs"]
 mod kwin;
 #[cfg(target_os = "windows")]
@@ -1113,6 +1220,10 @@ mod tests {
            compositor_for_kind(ActiveKind::DesktopWlroots),
            Some(Compositor::Wlroots)
        );
+        assert_eq!(
+            compositor_for_kind(ActiveKind::DesktopHyprland),
+            Some(Compositor::Hyprland)
+        );
        // No live session → no backend; the caller turns this into a handshake error / fallback.
        assert_eq!(compositor_for_kind(ActiveKind::None), None);
    }
@@ -987,7 +987,10 @@ fn do_restore_tv_session() {
            use super::ActiveKind;
            if matches!(
                super::detect_active_session().kind,
-                ActiveKind::DesktopKde | ActiveKind::DesktopGnome | ActiveKind::DesktopWlroots
+                ActiveKind::DesktopKde
+                    | ActiveKind::DesktopGnome
+                    | ActiveKind::DesktopWlroots
+                    | ActiveKind::DesktopHyprland
            ) {
                tracing::info!(
                    "gamescope (SteamOS): a desktop session is active — removed the headless \
@@ -0,0 +1,600 @@
+//! Hyprland virtual-output backend via `hyprctl` IPC + the xdg ScreenCast portal
+//! (xdg-desktop-portal-hyprland / xdph). See `design/hyprland-support.md`.
+//!
+//! Hyprland dropped wlroots in v0.42 (aquamarine backend) but kept the client-facing wlr
+//! protocols, so it shares the wlr virtual-input path with sway — but it needs its own IPC and
+//! portal, so it is a **distinct backend** from [`super::wlroots`], not a branch inside it (D1):
+//!
+//! 1. `hyprctl output create headless PF-<n>` adds a named headless output — Hyprland supports
+//!    **explicit names**, so no before/after diffing like sway's `HEADLESS-N` (D6). We poll
+//!    `hyprctl -j monitors` until the name shows up.
+//! 2. A monitor rule sets the client's exact mode. [`set_monitor_rule`] uses `hyprctl keyword
+//!    monitor NAME,WxH@Hz,auto,1` (the hyprlang path — the default config manager on every current
+//!    release, ≥0.55 included) and falls back to the Lua `hyprctl eval 'hl.monitor{…}'` only for a
+//!    user on the opt-in Lua config manager, confirming the output actually adopted the mode (D5).
+//! 3. The xdg ScreenCast portal (served by **xdph**) yields the output's PipeWire node. There is
+//!    no GUI to pick an output headlessly, so xdph is steered through its **custom picker**: a
+//!    managed config (`~/.config/hypr/xdph.conf`) points `screencopy:custom_picker_binary` at a tiny
+//!    installed shim that cats a per-session selection file we write (`[SELECTION]screen:<NAME>`)
+//!    right before the handshake — byte-for-byte the xdpw pattern, xdph's picker wire format.
+//! 4. Teardown is RAII: drop stops the portal thread (its zbus connection ends the cast) and runs
+//!    `hyprctl output remove NAME`.
+//!
+//! Requirements: the host runs inside (or can reach) the Hyprland session — either
+//! `HYPRLAND_INSTANCE_SIGNATURE` is inherited, or [`is_available`] discovers it from
+//! `$XDG_RUNTIME_DIR/hypr/` and [`super::super::apply_session_env`] exports it for `hyprctl` — with
+//! the ScreenCast interface routed to xdph (`scripts/headless/portals.conf`).
+//!
+//! Contracts verified on **Hyprland 0.55.4 + xdph 1.3.x** (`design/hyprland-support.md` Phase 0):
+//! `hyprctl` subcommands / JSON shapes, the `[SELECTION]screen:<name>` picker format, the
+//! `~/.config/hypr/xdph.conf` path + `screencopy:custom_picker_binary` key, and that `eval` needs
+//! the Lua config manager. Not yet exercised end-to-end on real DRM hardware: a headless output's
+//! GBM/dmabuf allocation (fails on a nested/NVIDIA test box — Sunshine#4197); `set_monitor_rule`
+//! surfaces that as a clear error instead of streaming a 0×0 output.
+
+use super::{DisplayOwnership, Mode, VirtualDisplay, VirtualOutput};
+use anyhow::{anyhow, bail, Context, Result};
+use std::os::fd::OwnedFd;
+use std::process::Command;
+use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
+use std::sync::mpsc::Sender;
+use std::sync::{Arc, Once};
+use std::thread;
+use std::time::{Duration, Instant};
+
+/// Per-session file the xdph custom picker reads the selected output from. We write
+/// `screen:<NAME>\n` here right before the portal handshake selects sources. Lives under
+/// `$XDG_RUNTIME_DIR` (per-user, 0700) — NOT a world-writable /tmp path another local user could
+/// pre-create or rewrite between our write and xdph's read (steer capture elsewhere). Mirrors the
+/// wlroots chooser file.
+fn selection_file() -> String {
+    let dir = std::env::var("XDG_RUNTIME_DIR").unwrap_or_else(|_| "/tmp".into());
+    format!("{dir}/punktfunk-xdph-output")
+}
+
+/// The installed custom-picker shim: a tiny script that cats [`selection_file`]. xdph runs
+/// `custom_picker_binary` and reads one selection line from its stdout; an empty read (no session
+/// has written the file) leaves xdph to its interactive picker — the graceful fallback.
+fn picker_shim_path() -> String {
+    let dir = std::env::var("XDG_RUNTIME_DIR").unwrap_or_else(|_| "/tmp".into());
+    format!("{dir}/punktfunk-xdph-picker.sh")
+}
+
+/// The picker line for output `name`. Verified against xdph 1.3.x / hyprland-share-picker on
+/// Hyprland 0.55.4: xdph reads the custom picker's stdout and requires the `[SELECTION]` marker
+/// followed by `screen:<name>` (or `window:<addr>` / `region:…`); anything else is rejected as
+/// "strange output" and falls back to the interactive picker. So a monitor selection is
+/// `[SELECTION]screen:<name>`.
+fn picker_selection_line(name: &str) -> String {
+    format!("[SELECTION]screen:{name}\n")
+}
+
+/// The managed xdph config: point the screencopy custom picker at our shim so headless output
+/// selection needs no GUI. xdph reads its config at startup, so a change restarts it (see
+/// [`ensure_xdph_config`]). The *selection* is the per-session file, not this static config.
+fn xdph_config() -> String {
+    format!(
+        "# managed by punktfunk (vdisplay/hyprland.rs) — headless per-session output selection.\n\
+screencopy {{\n\
+    custom_picker_binary = {}\n\
+}}\n",
+        picker_shim_path()
+    )
+}
+
+/// Monotonic per-process counter for headless output names (`PF-1`, `PF-2`, …). Named outputs kill
+/// the before/after diff race sway needs (D6).
+static OUTPUT_SEQ: AtomicU32 = AtomicU32::new(0);
+
+fn next_output_name() -> String {
+    format!("PF-{}", OUTPUT_SEQ.fetch_add(1, Ordering::Relaxed) + 1)
+}
+
+/// The Hyprland virtual-display driver. Stateless — each [`create`](VirtualDisplay::create) adds one
+/// named headless output and spins up a portal thread owning the cast on it.
+pub struct HyprlandDisplay;
+
+impl HyprlandDisplay {
+    pub fn new() -> Result<Self> {
+        Ok(HyprlandDisplay)
+    }
+}
+
+/// Hyprland is usable when a live Hyprland instance for our uid is reachable — signalled by
+/// `HYPRLAND_INSTANCE_SIGNATURE` (inherited from the session) **or** a discoverable instance socket
+/// under `$XDG_RUNTIME_DIR/hypr/*/.socket.sock` (so the systemd `--user` host works without env
+/// import, unlike sway's `SWAYSOCK`; the signature is then exported by `apply_session_env`). Cheap,
+/// side-effect-free — safe on the enumeration path.
+pub fn is_available() -> bool {
+    if std::env::var_os("HYPRLAND_INSTANCE_SIGNATURE").is_some() {
+        return true;
+    }
+    let dir = match std::env::var_os("XDG_RUNTIME_DIR") {
+        Some(d) => std::path::PathBuf::from(d).join("hypr"),
+        None => return false,
+    };
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return false;
+    };
+    entries
+        .flatten()
+        .any(|e| e.path().join(".socket.sock").exists())
+}
+
+/// Pre-flight for the Hyprland backend: `hyprctl` must reach the compositor (a clear error now
+/// beats a create-time failure), and if the permission system is enforcing, warn about the silent
+/// black-frame / dropped-input failure mode.
+pub fn probe() -> Result<()> {
+    hyprctl(&["-j", "version"]).context(
+        "hyprctl not reachable — is Hyprland running and HYPRLAND_INSTANCE_SIGNATURE set? (the \
+         host must run inside, or be able to reach, the Hyprland session)",
+    )?;
+    if let Some((maj, min, pat)) = hyprland_version() {
+        tracing::info!(version = %format!("{maj}.{min}.{pat}"), "Hyprland backend ready");
+    }
+    warn_if_permissions_enforced();
+    Ok(())
+}
+
+impl VirtualDisplay for HyprlandDisplay {
+    fn name(&self) -> &'static str {
+        "hyprland"
+    }
+
+    fn create(&mut self, mode: Mode) -> Result<VirtualOutput> {
+        // Log the permission-system caveat once per process (silent black frames otherwise).
+        preflight_once();
+
+        let name = next_output_name();
+        hyprctl_dispatch(&["output", "create", "headless", &name]).with_context(|| {
+            format!("hyprctl output create headless {name} (is hyprctl reachable?)")
+        })?;
+        // Own the output from here on so any later error (or drop) removes it.
+        let output = OutputGuard(name.clone());
+        wait_monitor_ready(&name, Duration::from_secs(5))
+            .with_context(|| format!("waiting for headless output {name} to appear"))?;
+
+        // The client's exact mode (also the frame clock — a headless output is timer-paced from it).
+        set_monitor_rule(&name, mode).with_context(|| format!("set monitor rule for {name}"))?;
+
+        // Steer xdph's custom picker at our new output, then run the portal handshake on its own
+        // thread (it parks to keep the cast alive, like the other backends).
+        ensure_xdph_config()?;
+        let sel = selection_file();
+        std::fs::write(&sel, picker_selection_line(&name))
+            .with_context(|| format!("write {sel}"))?;
+
+        let (setup_tx, setup_rx) = std::sync::mpsc::channel::<Result<(OwnedFd, u32), String>>();
+        let stop = Arc::new(AtomicBool::new(false));
+        let stop_thread = stop.clone();
+        thread::Builder::new()
+            .name("punktfunk-hypr-vout".into())
+            .spawn(move || portal_thread(setup_tx, stop_thread))
+            .context("spawn hyprland portal thread")?;
+
+        let (fd, node_id) = match setup_rx.recv_timeout(Duration::from_secs(20)) {
+            Ok(Ok(v)) => v,
+            Ok(Err(e)) => bail!("ScreenCast portal on {name} failed: {e}"),
+            Err(_) => bail!("timed out waiting for the ScreenCast portal on {name}"),
+        };
+        tracing::info!(
+            node_id,
+            output = %name,
+            w = mode.width,
+            h = mode.height,
+            hz = mode.refresh_hz,
+            "hyprland headless output ready"
+        );
+        Ok(VirtualOutput {
+            node_id,
+            remote_fd: Some(fd),
+            preferred_mode: Some((mode.width, mode.height, mode.refresh_hz)),
+            keepalive: Box::new(Keepalive {
+                _stop: StopGuard(stop),
+                _output: output,
+            }),
+            // Owned (the compositor output is ours to tear down), but not registry-poolable: the
+            // portal fd can't be re-opened per attach, so the registry passes it through on
+            // `remote_fd.is_some()` — same as wlroots.
+            ownership: DisplayOwnership::Owned,
+            reused_gen: None,
+        })
+    }
+}
+
+/// Drop order matters: stop the portal thread first (zbus connection drop ends the cast), then
+/// remove the output (fields drop in declaration order).
+struct Keepalive {
+    _stop: StopGuard,
+    _output: OutputGuard,
+}
+
+/// Dropping this ends the portal keepalive thread, closing its zbus connection — the portal then
+/// tears the screencast session down.
+struct StopGuard(Arc<AtomicBool>);
+
+impl Drop for StopGuard {
+    fn drop(&mut self) {
+        self.0.store(true, Ordering::Relaxed);
+    }
+}
+
+/// Owns the created headless output; dropping it removes it from Hyprland.
+struct OutputGuard(String);
+
+impl Drop for OutputGuard {
+    fn drop(&mut self) {
+        match hyprctl_dispatch(&["output", "remove", &self.0]) {
+            Ok(_) => tracing::info!(output = %self.0, "hyprland headless output removed"),
+            Err(e) => {
+                tracing::warn!(output = %self.0, error = %format!("{e:#}"), "output remove failed")
+            }
+        }
+    }
+}
+
+/// Run `hyprctl <args>`, returning stdout. `hyprctl` reads `HYPRLAND_INSTANCE_SIGNATURE` from the
+/// env (exported by `apply_session_env`) to reach the right instance socket. It exits non-zero on a
+/// hard failure, but for dispatch commands it can print an error with status 0 — see
+/// [`hyprctl_dispatch`].
+fn hyprctl(args: &[&str]) -> Result<String> {
+    let out = Command::new("hyprctl")
+        .args(args)
+        .output()
+        .context("run hyprctl (is Hyprland installed?)")?;
+    if !out.status.success() {
+        bail!(
+            "hyprctl {:?} failed: {}{}",
+            args,
+            String::from_utf8_lossy(&out.stdout).trim(),
+            String::from_utf8_lossy(&out.stderr).trim()
+        );
+    }
+    Ok(String::from_utf8_lossy(&out.stdout).into_owned())
+}
+
+/// Run a `hyprctl` **dispatch** command (`output …`, `keyword …`, `eval …`) that reports success by
+/// printing `ok`. hyprctl often exits 0 even when the command is rejected, printing the error to
+/// stdout, so treat a known error marker as failure (this is also how [`set_monitor_rule`] tells the
+/// two config eras apart).
+fn hyprctl_dispatch(args: &[&str]) -> Result<()> {
+    let out = hyprctl(args)?;
+    let t = out.trim();
+    let lc = t.to_ascii_lowercase();
+    if lc.contains("invalid")
+        || lc.contains("not found")
+        || lc.contains("couldn't")
+        || lc.contains("could not")
+        || lc.contains("unknown")
+        || lc.contains("no such")
+        || lc.contains("error")
+        // `hyprctl eval` on a hyprlang (non-Lua) config: "eval is only supported with the lua
+        // config manager" — a rejection hyprctl reports with exit 0 and no other marker.
+        || lc.contains("only supported")
+        || lc.contains("not supported")
+    {
+        bail!("hyprctl {:?} rejected: {t}", args);
+    }
+    Ok(())
+}
+
+/// Wait until the named headless output shows up in `hyprctl -j monitors` (it appears near-instantly
+/// in practice; poll briefly to be safe).
+fn wait_monitor_ready(name: &str, timeout: Duration) -> Result<()> {
+    let deadline = Instant::now() + timeout;
+    loop {
+        if monitor_exists(name)? {
+            return Ok(());
+        }
+        if Instant::now() >= deadline {
+            bail!("output create succeeded but monitor {name} never appeared");
+        }
+        thread::sleep(Duration::from_millis(50));
+    }
+}
+
+/// Is a monitor named `name` present in `hyprctl -j monitors` (JSON)?
+fn monitor_exists(name: &str) -> Result<bool> {
+    let out = hyprctl(&["-j", "monitors"])?;
+    let monitors: serde_json::Value =
+        serde_json::from_str(&out).context("parse hyprctl -j monitors")?;
+    Ok(monitors
+        .as_array()
+        .map(|a| {
+            a.iter()
+                .any(|m| m.get("name").and_then(|n| n.as_str()) == Some(name))
+        })
+        .unwrap_or(false))
+}
+
+/// Set the client's exact mode on `name`, supporting both config eras (D5). Encapsulates the whole
+/// era split (D5). `hyprctl keyword monitor NAME,WxH@Hz,auto,1` is the hyprlang path — the default
+/// config manager on **every** current release, including ≥0.55 (verified on 0.55.4: version does
+/// NOT imply the Lua era — a stock 0.55.4 rejects `eval` with "only supported with the lua config
+/// manager"). So we try `keyword` first and fall back to the Lua `hyprctl eval 'hl.monitor{…}'` only
+/// for a user who opted into the Lua config manager (where `keyword` is gone). Either way we confirm
+/// the output actually adopted the mode — some forms print `ok` for a command they ignored.
+///
+/// A headless output starts at 0×0 and only gets a framebuffer once a mode commits; if neither form
+/// makes it adopt a usable (non-zero) size the compositor couldn't back the mode (a headless GBM /
+/// dmabuf allocation failure — Sunshine#4197, seen on some NVIDIA setups), which we surface clearly
+/// rather than streaming a 0×0 corpse.
+fn set_monitor_rule(name: &str, mode: Mode) -> Result<()> {
+    let hz = mode.refresh_hz.max(1);
+    let spec = format!("{name},{}x{}@{hz},auto,1", mode.width, mode.height);
+    let lua = format!(
+        "hl.monitor{{ output = \"{name}\", mode = \"{}x{}@{hz}\", position = \"auto\", scale = 1 }}",
+        mode.width, mode.height
+    );
+    let keyword: Vec<&str> = vec!["keyword", "monitor", &spec];
+    let eval: Vec<&str> = vec!["eval", &lua];
+    for a in [&keyword, &eval] {
+        // A wrong-era command errors (`keyword` gone under Lua, or `eval` under hyprlang) — skip to
+        // the other form. A command that's accepted then has up to the timeout to take effect.
+        if hyprctl_dispatch(a).is_err() {
+            continue;
+        }
+        if wait_exact_mode(name, mode, Duration::from_millis(1500)) {
+            tracing::debug!(output = %name, cmd = ?a, w = mode.width, h = mode.height, "monitor adopted the requested mode");
+            return Ok(());
+        }
+    }
+    // Neither form produced the exact mode. Distinguish "usable but different size" (proceed with a
+    // warning — a working stream beats none) from "0×0 / gone" (the output has no framebuffer at all).
+    match monitor_size(name)? {
+        Some((w, h)) if w > 0 && h > 0 => {
+            tracing::warn!(
+                output = %name,
+                requested = %format!("{}x{}", mode.width, mode.height),
+                got = %format!("{w}x{h}"),
+                "Hyprland did not adopt the exact requested mode — streaming at the output's current size"
+            );
+            Ok(())
+        }
+        _ => bail!(
+            "headless output {name} never got a framebuffer (stayed 0x0) after the monitor rule for \
+             {}x{}@{hz} — the compositor could not back the mode, likely a headless GBM/dmabuf \
+             allocation failure (GPU driver; cf. Sunshine#4197). Check the Hyprland log.",
+            mode.width,
+            mode.height
+        ),
+    }
+}
+
+/// Poll until monitor `name` reports exactly `mode`'s width×height (the rule applies asynchronously),
+/// up to `timeout`. Returns `false` on timeout.
+fn wait_exact_mode(name: &str, mode: Mode, timeout: Duration) -> bool {
+    let deadline = Instant::now() + timeout;
+    loop {
+        if matches!(monitor_size(name), Ok(Some((w, h))) if w == mode.width as u64 && h == mode.height as u64)
+        {
+            return true;
+        }
+        if Instant::now() >= deadline {
+            return false;
+        }
+        thread::sleep(Duration::from_millis(50));
+    }
+}
+
+/// Monitor `name`'s current `(width, height)` from `hyprctl -j monitors all` (includes a disabled
+/// output), or `None` if it isn't present. A freshly-created headless output reports `0×0` until a
+/// mode commits.
+fn monitor_size(name: &str) -> Result<Option<(u64, u64)>> {
+    let out = hyprctl(&["-j", "monitors", "all"])?;
+    let monitors: serde_json::Value =
+        serde_json::from_str(&out).context("parse hyprctl -j monitors")?;
+    let Some(arr) = monitors.as_array() else {
+        return Ok(None);
+    };
+    for m in arr {
+        if m.get("name").and_then(|n| n.as_str()) == Some(name) {
+            let w = m.get("width").and_then(|v| v.as_u64()).unwrap_or(0);
+            let h = m.get("height").and_then(|v| v.as_u64()).unwrap_or(0);
+            return Ok(Some((w, h)));
+        }
+    }
+    Ok(None)
+}
+
+/// The running Hyprland `(major, minor, patch)` from `hyprctl -j version` (`tag` like `v0.55.4`),
+/// for a diagnostic log — the mode-rule path is version-independent (see [`set_monitor_rule`]).
+fn hyprland_version() -> Option<(u16, u16, u16)> {
+    let out = hyprctl(&["-j", "version"]).ok()?;
+    let json: serde_json::Value = serde_json::from_str(&out).ok()?;
+    parse_version_tag(json.get("tag").and_then(|t| t.as_str())?)
+}
+
+/// Parse a Hyprland `tag` (`v0.55.4`, or a dev `v0.41.2-13-gabcdef`) to `(major, minor, patch)`.
+fn parse_version_tag(tag: &str) -> Option<(u16, u16, u16)> {
+    let t = tag.trim().trim_start_matches(['v', 'V']);
+    let mut it = t.split(['.', '-', '_', '+']);
+    let major = it.next()?.parse().ok()?;
+    let minor = it.next().and_then(|s| s.parse().ok()).unwrap_or(0);
+    let patch = it.next().and_then(|s| s.parse().ok()).unwrap_or(0);
+    Some((major, minor, patch))
+}
+
+/// Log the permission-system caveat at most once per process: with
+/// `ecosystem.enforce_permissions = true` (0.49+, off by default), direct screencopy/virtual-input
+/// clients can be denied — and denial is **silent black frames / dropped input**, not an error.
+fn preflight_once() {
+    static WARNED: Once = Once::new();
+    WARNED.call_once(warn_if_permissions_enforced);
+}
+
+fn warn_if_permissions_enforced() {
+    let Ok(out) = hyprctl(&["-j", "getoption", "ecosystem:enforce_permissions"]) else {
+        return;
+    };
+    let on = serde_json::from_str::<serde_json::Value>(&out)
+        .ok()
+        .and_then(|j| j.get("int").and_then(|v| v.as_i64()))
+        .is_some_and(|v| v != 0);
+    if on {
+        tracing::warn!(
+            "Hyprland ecosystem.enforce_permissions is ON — screencopy/virtual-input may be denied \
+             as SILENT black frames / dropped input. Grant the host with hl.permission rules \
+             (screencopy + virtual pointer/keyboard) — see docs/hyprland."
+        );
+    }
+}
+
+/// Make sure xdph uses our custom picker: install the shim (once) and write the managed config,
+/// restarting xdph if the config changed (it reads config only at startup). Mirrors the wlroots
+/// `ensure_xdpw_config` pattern.
+fn ensure_xdph_config() -> Result<()> {
+    // 1. Install the picker shim (idempotent — content is fixed).
+    let shim = picker_shim_path();
+    let sel = selection_file();
+    let shim_body = format!("#!/bin/sh\nexec cat \"{sel}\" 2>/dev/null\n");
+    if std::fs::read_to_string(&shim).is_ok_and(|c| c == shim_body) {
+        // already installed
+    } else {
+        std::fs::write(&shim, &shim_body).with_context(|| format!("write {shim}"))?;
+        #[cfg(target_os = "linux")]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            std::fs::set_permissions(&shim, std::fs::Permissions::from_mode(0o700))
+                .with_context(|| format!("chmod {shim}"))?;
+        }
+    }
+
+    // 2. Write the managed xdph config and restart xdph on change.
+    let base = std::env::var_os("XDG_CONFIG_HOME")
+        .map(std::path::PathBuf::from)
+        .or_else(|| std::env::var_os("HOME").map(|h| std::path::PathBuf::from(h).join(".config")))
+        .ok_or_else(|| anyhow!("neither XDG_CONFIG_HOME nor HOME set"))?;
+    let dir = base.join("hypr");
+    let path = dir.join("xdph.conf");
+    let cfg = xdph_config();
+    if std::fs::read_to_string(&path).is_ok_and(|c| c == cfg) {
+        return Ok(());
+    }
+    std::fs::create_dir_all(&dir).with_context(|| format!("mkdir {}", dir.display()))?;
+    std::fs::write(&path, &cfg).with_context(|| format!("write {}", path.display()))?;
+    tracing::info!(path = %path.display(), "wrote managed xdg-desktop-portal-hyprland config");
+    let _ = Command::new("systemctl")
+        .args([
+            "--user",
+            "try-restart",
+            "xdg-desktop-portal-hyprland.service",
+        ])
+        .status();
+    Ok(())
+}
+
+/// The ScreenCast portal handshake — the xdg ScreenCast portal is backend-neutral (served here by
+/// xdph), so this mirrors the wlroots portal thread: it reports the fd + node id and parks until
+/// stopped (the zbus connection is the cast's lifetime). xdph answers source selection via our
+/// custom picker, no dialog. (Kept separate from wlroots' copy so each wlr-family backend stays
+/// self-owned per D1; unify if they ever diverge no further.)
+fn portal_thread(setup_tx: Sender<Result<(OwnedFd, u32), String>>, stop: Arc<AtomicBool>) {
+    use ashpd::desktop::screencast::{CursorMode, Screencast, SelectSourcesOptions, SourceType};
+    use ashpd::desktop::PersistMode;
+    use ashpd::enumflags2::BitFlags;
+
+    // Multi-thread runtime: the zbus background reader must be pumped across the
+    // create_session → select_sources → start handshake (see capture/linux.rs).
+    let rt = match tokio::runtime::Builder::new_multi_thread()
+        .worker_threads(2)
+        .enable_all()
+        .build()
+    {
+        Ok(rt) => rt,
+        Err(e) => {
+            let _ = setup_tx.send(Err(format!("build tokio runtime: {e}")));
+            return;
+        }
+    };
+    let err_tx = setup_tx.clone();
+
+    rt.block_on(async move {
+        let result: Result<()> = async {
+            let proxy = Screencast::new().await.context(
+                "connect ScreenCast portal (is xdg-desktop-portal running with the hyprland backend/xdph?)",
+            )?;
+            let session = proxy
+                .create_session(Default::default())
+                .await
+                .context("create_session")?;
+            proxy
+                .select_sources(
+                    &session,
+                    SelectSourcesOptions::default()
+                        .set_cursor_mode(CursorMode::Embedded)
+                        // xdph offers MONITOR; the custom picker selects our output.
+                        .set_sources(BitFlags::from_flag(SourceType::Monitor))
+                        .set_multiple(false)
+                        .set_persist_mode(PersistMode::DoNot),
+                )
+                .await
+                .context("select_sources")?
+                .response()
+                .context("select_sources rejected")?;
+            let streams = proxy
+                .start(&session, None, Default::default())
+                .await
+                .context("start cast")?
+                .response()
+                .context("start response (custom picker declined? check the xdph config/shim/selection file)")?;
+            let stream = streams
+                .streams()
+                .first()
+                .context("portal returned no streams")?
+                .clone();
+            let node_id = stream.pipe_wire_node_id();
+            let fd = proxy
+                .open_pipe_wire_remote(&session, Default::default())
+                .await
+                .context("open_pipe_wire_remote")?;
+
+            setup_tx
+                .send(Ok((fd, node_id)))
+                .map_err(|_| anyhow!("virtual-output opener went away"))?;
+
+            // Park, keeping `proxy` + `session` (the zbus connection) alive until stopped — the cast
+            // is torn down when the connection drops.
+            let _keep_alive = (&proxy, &session);
+            while !stop.load(Ordering::Relaxed) {
+                tokio::time::sleep(Duration::from_millis(200)).await;
+            }
+            Ok(())
+        }
+        .await;
+
+        if let Err(e) = result {
+            let _ = err_tx.send(Err(format!("{e:#}")));
+        }
+    });
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn version_tag_parses_release_and_dev_builds() {
+        assert_eq!(parse_version_tag("v0.55.0"), Some((0, 55, 0)));
+        assert_eq!(parse_version_tag("0.41.2"), Some((0, 41, 2)));
+        // Dev builds tack the commit distance + hash on with a dash.
+        assert_eq!(parse_version_tag("v0.41.2-13-gabcdef"), Some((0, 41, 2)));
+        // Missing patch defaults to 0; garbage is rejected.
+        assert_eq!(parse_version_tag("v1.0"), Some((1, 0, 0)));
+        assert_eq!(parse_version_tag("wat"), None);
+    }
+
+    #[test]
+    fn output_names_are_unique_and_prefixed() {
+        let a = next_output_name();
+        let b = next_output_name();
+        assert!(a.starts_with("PF-") && b.starts_with("PF-"));
+        assert_ne!(a, b);
+    }
+
+    #[test]
+    fn picker_line_carries_the_selection_marker() {
+        // xdph requires the `[SELECTION]` prefix; a bare `screen:NAME` is rejected as strange output.
+        assert_eq!(picker_selection_line("PF-1"), "[SELECTION]screen:PF-1\n");
+    }
+}
@@ -890,11 +890,16 @@ pub(crate) fn allow_public_network(args: &[String]) -> bool {
    args.iter().any(|a| a == "--allow-public-network")
 }

-/// Inbound firewall rules for the streaming ports (best-effort; logs but never fails the install).
-/// Scoped by [`firewall_profile_arg`]: Domain + Private by default, all profiles when `allow_public`.
+/// Inbound firewall rules for the streaming + mgmt ports (best-effort; logs but never fails the
+/// install). Scoped by [`firewall_profile_arg`]: Domain + Private by default, all profiles when
+/// `allow_public`. TCP 47990 is deliberate: `serve` binds the mgmt/library REST API to all interfaces
+/// so paired clients can browse the game library over mTLS, and off-loopback `mgmt::require_auth`
+/// exposes only the read-only status/library allowlist to a paired client cert — the bearer-token
+/// admin surface stays loopback-only regardless of the bind — so opening it adds no admin exposure.
 fn add_firewall_rules(allow_public: bool) {
    let profile = firewall_profile_arg(allow_public);
-    // (name suffix, protocol, ports)
+    // (name suffix, protocol, ports). 47990 = mgmt/library (LAN = read-only, paired-cert only); the
+    // rest are the GameStream (47984/47989/48010, 47998-48010) + native (9777) + mDNS (5353) ports.
    let rules = [
        ("TCP", "TCP", "47984,47989,48010,47990"),
        ("UDP", "UDP", "47998-48010,9777,5353"),
@@ -23,7 +23,7 @@ anyhow = "1"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 # Loopback HTTPS poll of GET /api/v1/local/summary. Same sync ureq + rustls(ring) stack and
-# custom-verifier pattern as the Linux client's library fetch (clients/linux/src/library.rs) —
+# custom-verifier pattern as the Linux client's library fetch (crates/pf-client-core/src/library.rs) —
 # but ring-only (no default aws-lc-rs provider: it needs a C toolchain per target and the agent
 # pins the ring provider explicitly anyway).
 ureq = { version = "2", default-features = false, features = ["tls"] }
@@ -128,8 +128,9 @@ sudo ufw allow punktfunk-web
 sudo firewall-cmd --permanent --add-service=punktfunk-web && sudo firewall-cmd --reload  # firewalld
 ```

-That opens **TCP 47992** (HTTPS, login-gated). The mgmt API (47990) stays loopback-only and is never
-opened. Full port lists (`nftables`, explicit ports) are in
+That opens **TCP 47992** (HTTPS, login-gated). The mgmt API (47990) is opened for paired clients by the
+`punktfunk-native` profile (game-library browsing over mTLS); off-loopback it serves only read-only
+status/library, and every admin action stays loopback-only. Full port lists (`nftables`, explicit ports) are in
 [`packaging/arch/README.md`](https://git.unom.io/unom/punktfunk/src/branch/main/packaging/arch/README.md#firewall).

 ## 6. Connect a client
@@ -34,10 +34,10 @@ On Linux the host **rewrites `WAYLAND_DISPLAY` / `XDG_CURRENT_DESKTOP` / `XDG_RU

 | Setting | Values | Meaning |
 |---|---|---|
-| `PUNKTFUNK_COMPOSITOR` | `kwin` · `mutter` · `gamescope` · `wlroots` (aliases: `kde`/`plasma`, `gnome`, `sway`/`hyprland`) | Which backend creates the virtual display. **Leave unset to auto-detect;** set only to force one. |
+| `PUNKTFUNK_COMPOSITOR` | `kwin` · `mutter` · `gamescope` · `wlroots` · `hyprland` (aliases: `kde`/`plasma`, `gnome`, `sway`/`wlr`) | Which backend creates the virtual display. `wlroots` is sway/River; `hyprland` is its own backend. **Leave unset to auto-detect;** set only to force one. |
 | `PUNKTFUNK_VIDEO_SOURCE` | `virtual` · `portal` | `virtual` creates a per-client display at the client's exact mode (the normal choice). `portal` captures an existing monitor instead. |
 | `PUNKTFUNK_ZEROCOPY` | `1` · `0` *(default on)* | GPU zero-copy capture→encode (dmabuf → CUDA → NVENC, or D3D11 on Windows). **On by default** — no need to set it; it falls back to a CPU path automatically. Set `0` to force the CPU path. One exception: Windows **Intel/QSV** keeps the CPU path by default until zero-copy is validated on Intel hardware — set `1` to try it there. |
-| `PUNKTFUNK_INPUT_BACKEND` | `libei` · `gamescope` · `wlr` · `uinput` | How input is injected. `libei` for GNOME/KDE, `gamescope` for Bazzite/gamescope, `wlr` for Sway/wlroots. Auto-detected with the compositor. |
+| `PUNKTFUNK_INPUT_BACKEND` | `libei` · `gamescope` · `wlr` · `uinput` | How input is injected. `libei` for GNOME/KDE, `gamescope` for Bazzite/gamescope, `wlr` for Sway/wlroots **and Hyprland**. Auto-detected with the compositor. |
 | `PUNKTFUNK_ENCODER` | `auto` · `nvenc` · `vaapi` (Linux) · `amf` · `qsv` (Windows) · `software` | Encoder backend. `auto` (default) detects the GPU vendor: NVIDIA→NVENC, AMD→VAAPI/AMF, Intel→VAAPI/QSV. `software` (aliases `sw`/`openh264`) is the GPU-less H.264 path on both platforms — on Windows `auto` falls back to it when no GPU is found; on Linux it is **explicit-only** (`auto` never picks it). |
 | `PUNKTFUNK_RENDER_NODE` | path | Linux DRM render node for zero-copy (default `/dev/dri/renderD128`). Set on multi-GPU boxes to pick the right GPU. |

@@ -32,15 +32,19 @@ punktfunk-host serve --gamestream
 | `--native` | No-op. The native `punktfunk/1` server always runs in `serve`; kept only for backward compatibility. |
 | `--native-port <PORT>` | Native QUIC port (default `9777`). |
 | `--open` | Don't require pairing — serve any device on the network. Off by default; only for trusted single-user setups. |
-| `--mgmt-bind <IP:PORT>` | Management API address (default loopback `127.0.0.1:47990`). |
+| `--mgmt-bind <IP:PORT>` | Management API address (default `0.0.0.0:47990` — all interfaces, so paired clients can browse the game library over mTLS; pass `127.0.0.1:47990` to keep it loopback-only). |
 | `--mgmt-token <TOKEN>` | Override the bearer token for the management API. |

 These are the only flags `serve` accepts.

-The management API is **always HTTPS with bearer-token auth**. If you don't pass `--mgmt-token`, a token
-is auto-generated and persisted to `~/.config/punktfunk/mgmt-token`; `--mgmt-token` only overrides it. A
-token is **required** when you bind the API off loopback with `--mgmt-bind`. Every endpoint is documented
-in the interactive [**API Reference**](/api).
+The management API is **always HTTPS**. It binds all interfaces by default so a **paired client** can
+fetch the game library over its mTLS certificate — but off loopback that certificate reaches only the
+read-only status + library endpoints. The **admin surface** (arming pairing, removing devices, session
+control, library edits) authenticates with a **bearer token** and is honored **from loopback only**, so
+it is never LAN-exposed even under the default wide bind. If you don't pass `--mgmt-token`, a token is
+auto-generated and persisted to `~/.config/punktfunk/mgmt-token` (the bundled web console reads the same
+file); `--mgmt-token` only overrides it. Pass `--mgmt-bind 127.0.0.1:47990` to keep 47990 loopback-only.
+Every endpoint is documented in the interactive [**API Reference**](/api).

 By default the host **requires pairing** — see [Pairing & Trust](/docs/pairing). On `serve` you
 **arm pairing from the web console** (or mgmt API); the host then displays a 4-digit PIN. Pass `--open` to
@@ -0,0 +1,102 @@
+---
+title: Hyprland
+description: Configure a punktfunk host on a Hyprland session — headless output via hyprctl, capture via xdg-desktop-portal-hyprland.
+---
+
+Hyprland is a **first-class backend.** The host adds a per-client headless output at the client's
+exact mode with `hyprctl`, captures it through the **xdg-desktop-portal-hyprland (xdph)** ScreenCast
+portal (zero-copy dmabuf), and injects input via the wlroots virtual pointer/keyboard protocols —
+which Hyprland still implements even after dropping wlroots in v0.42.
+
+This is a distinct backend from [Sway / wlroots](/docs/sway): Hyprland has its own IPC (`hyprctl`)
+and its own portal (xdph), so it is auto-detected and driven separately.
+
+This page assumes the package is already installed — see [Arch](/docs/arch), [Ubuntu](/docs/ubuntu),
+or [Fedora](/docs/fedora).
+
+> New here? Read [Security & Safe Use](/docs/security) first — a streaming host is remote control of
+> the machine, so keep it on a trusted LAN or VPN and require pairing.
+
+## host.env
+
+The host auto-detects a Hyprland session, so you usually need nothing here. To force the backend, set
+these in `~/.config/punktfunk/host.env`:
+
+```ini
+PUNKTFUNK_COMPOSITOR=hyprland
+PUNKTFUNK_INPUT_BACKEND=wlr
+PUNKTFUNK_VIDEO_SOURCE=virtual
+# GPU zero-copy capture→encode is ON by default; auto-falls back to CPU. Set PUNKTFUNK_ZEROCOPY=0 to force CPU.
+```
+
+See [Configuration](/docs/configuration) for the full reference.
+
+## How it works
+
+- **Video** — the host runs `hyprctl output create headless PF-1` and applies a monitor rule for the
+  client's exact mode. Outputs are **named**, so there's no before/after diffing. The rule uses
+  `hyprctl keyword monitor …` (the hyprlang config manager — the default on every release, 0.55
+  included) and falls back to the Lua `hyprctl eval 'hl.monitor{…}'` only if you've opted into the
+  Lua config manager. The host confirms the output actually adopted the mode before streaming.
+- **Capture** — it captures that output through the **xdg-desktop-portal-hyprland (xdph)** ScreenCast
+  portal. To pick the output without a GUI on a headless host, the host writes a managed
+  `~/.config/hypr/xdph.conf` pointing xdph's `custom_picker_binary` at a small shim that selects the
+  new output automatically — no interactive picker dialog to answer.
+- **Input** — mouse and keyboard are injected via the wlroots **virtual pointer** and **virtual
+  keyboard** protocols (Hyprland kept them). Gamepads and audio are compositor-independent.
+
+For how long the virtual output lives, and extend-vs-exclusive topology, see
+[Virtual displays](/docs/virtual-displays).
+
+## Requirements
+
+- A running Hyprland session (the `hyprctl`/xdph contracts are verified on **0.55.4**; older
+  releases share the same `hyprctl` surface).
+- **xdg-desktop-portal-hyprland (xdph)** installed and running — the host captures through its
+  ScreenCast portal, and steers its custom picker. Without it there is no video.
+- The ScreenCast interface routed to xdph — see `scripts/headless/portals.conf` (a `[Hyprland]`
+  section pins `org.freedesktop.impl.portal.ScreenCast=hyprland`).
+
+## Troubleshooting: black / no video (headless output at 0×0)
+
+A headless output only gets a framebuffer once the compositor can allocate one. On some GPU/driver
+combinations (notably NVIDIA, and in nested test setups) that GBM/dmabuf allocation fails and the
+output stays `0×0` — you'll see `GBM: Failed to allocate a GBM buffer: bo null` in the Hyprland log
+(cf. [Sunshine #4197](https://github.com/LizardByte/Sunshine/issues/4197)). The host detects this
+and fails the session with a clear error rather than streaming a blank surface. If you hit it,
+capture the Hyprland log (`hyprctl` instance dir → `hyprland.log`) and check your GPU's GBM support;
+running Hyprland as a real session (not nested) is the supported configuration.
+
+## Permission system
+
+Hyprland's permission system (`ecosystem.enforce_permissions`, 0.49+, **off by default**) can deny
+direct screencopy and virtual-input clients — and denial is **silent**: capture goes to *black
+frames* and input is *dropped*, with no error. If you've enabled it, grant the host explicitly in
+your Hyprland config:
+
+```ini
+ecosystem {
+    enforce_permissions = true
+}
+
+permission = /usr/bin/punktfunk-host, screencopy, allow
+permission = /usr/bin/punktfunk-host, virtual-pointer, allow
+permission = /usr/bin/punktfunk-host, virtual-keyboard, allow
+```
+
+The host logs a warning at startup when it detects enforcement is on. (Adjust the binary path to
+where your package installed `punktfunk-host`.)
+
+## Start the host
+
+With the backend selected, start the host from **inside your Hyprland session**:
+
+```sh
+systemctl --user enable --now punktfunk-host
+journalctl --user -u punktfunk-host -f
+```
+
+## Bring up the console and pair
+
+Enable the web console, read its login password, and arm PIN pairing — see
+[The Web Console](/docs/web-console). Then [connect a client](/docs/clients).
@@ -20,6 +20,7 @@
    "kde",
    "gnome",
    "gamescope",
+    "hyprland",
    "sway",
    "running-as-a-service",
    "virtual-displays",
@@ -26,11 +26,11 @@ is also available. Setup splits along two axes: you **install** the package per
 - [KDE Plasma (KWin)](/docs/kde)
 - [GNOME (Mutter)](/docs/gnome)
 - [Steam / gamescope](/docs/gamescope)
+- [Hyprland](/docs/hyprland)
 - [Sway / wlroots](/docs/sway)

-Pick your distro to install, then your desktop to configure — the two are independent. Other
-wlroots compositors (Hyprland) work but aren't a primary target; the host still needs one of these
-compositor backends to create a virtual display.
+Pick your distro to install, then your desktop to configure — the two are independent. The host
+needs one of these compositor backends to create a virtual display.

 > **Windows host:** punktfunk also runs as a native host on **Windows 11 22H2 or newer (x64)** — a
 > signed installer that registers a service and bundles a virtual-display driver (whose driver-
@@ -43,14 +43,18 @@ developer toolchain — just paste a URL into Decky:
 3. Paste the **stable** link and confirm:

   ```
-   https://git.unom.io/api/packages/unom/generic/punktfunk-decky/latest/punktfunk.zip
+   https://unom.io/pf-decky
   ```

 The **punktfunk** panel appears in the Quick Access Menu right away — no Deck restart needed.

-> **Channels.** The link above is the **stable** channel (moves on `vX.Y.Z` releases). For the latest
-> `main` build use the **canary** zip — `…/generic/punktfunk-decky/canary/punktfunk.zip` — or pin an
-> exact version with `…/punktfunk-decky/<version>/punktfunk.zip`. See [Release Channels](/docs/channels).
+> **Channels.** `https://unom.io/pf-decky` is a short link to the **stable** channel (moves on
+> `vX.Y.Z` releases), currently
+> `https://git.unom.io/api/packages/unom/generic/punktfunk-decky/latest/punktfunk.zip`. For the
+> latest `main` build use the **canary** zip —
+> `https://git.unom.io/api/packages/unom/generic/punktfunk-decky/canary/punktfunk.zip` — or pin an
+> exact version with `https://git.unom.io/api/packages/unom/generic/punktfunk-decky/<version>/punktfunk.zip`.
+> See [Release Channels](/docs/channels).

 ## Use it

@@ -1,12 +1,15 @@
 ---
 title: Sway / wlroots
-description: Configure a punktfunk host on a wlroots compositor (Sway, Hyprland).
+description: Configure a punktfunk host on a wlroots compositor (Sway, River).
 ---

-The wlroots family can host — but **Sway is the only validated path.** The host adds a per-client
-headless output at the client's exact mode and captures it through the xdg-desktop-portal-wlr (xdpw)
-ScreenCast portal, injecting input via the wlroots virtual pointer/keyboard protocols. Hyprland and
-other wlroots compositors are best-effort (see [How it works](#how-it-works) for the caveat).
+Sway (and other wlroots-proper compositors like River) can host: the host adds a per-client headless
+output at the client's exact mode with `swaymsg create_output` and captures it through the
+xdg-desktop-portal-wlr (xdpw) ScreenCast portal, injecting input via the wlroots virtual
+pointer/keyboard protocols.
+
+> On **Hyprland**? It's a separate first-class backend (its own `hyprctl` IPC and xdph portal) —
+> see [Hyprland](/docs/hyprland). This page is for sway and other wlroots-proper compositors.

 This is **not a primary target.** It works and is validated live on **sway 1.11** (zero-copy), but it
 sees far less testing than the KDE and GNOME paths — expect rougher edges. If you have a choice,
@@ -24,7 +27,7 @@ The host auto-detects a wlroots session, so you usually need nothing here. To fo
 these in `~/.config/punktfunk/host.env`:

 ```ini
-PUNKTFUNK_COMPOSITOR=wlroots      # aliases: sway, hyprland
+PUNKTFUNK_COMPOSITOR=wlroots      # aliases: sway, wlr (Hyprland has its own: PUNKTFUNK_COMPOSITOR=hyprland)
 PUNKTFUNK_INPUT_BACKEND=wlr
 PUNKTFUNK_VIDEO_SOURCE=virtual
 # GPU zero-copy capture→encode is ON by default; auto-falls back to CPU. Set PUNKTFUNK_ZEROCOPY=0 to force CPU.
@@ -35,9 +38,8 @@ See [Configuration](/docs/configuration) for the full reference.
 ## How it works

 - **Video** — the host adds a headless output at the client's exact mode with `swaymsg create_output`.
-  This uses Sway's IPC specifically; other wlroots compositors (Hyprland, …) don't expose an
-  equivalent, so virtual-output creation isn't wired up for them yet — Sway is the supported wlroots
-  path today.
+  This uses Sway's IPC specifically; other wlroots-proper compositors (River, …) are best-effort on
+  this path. (Hyprland is driven by its own [backend](/docs/hyprland), not this one.)
 - **Capture** — it captures that output through the **xdg-desktop-portal-wlr (xdpw)** ScreenCast
  portal. The host writes a managed chooser config so the output pick is automatic — no interactive
  picker dialog to answer.
@@ -49,7 +51,8 @@ For how long the virtual output lives, and extend-vs-exclusive topology, see

 ## Requirements

- A running wlroots session (Sway, Hyprland, …).
+- A running wlroots-proper session (Sway, River, …). On Hyprland, use the
+  [Hyprland backend](/docs/hyprland) instead.
 - **xdg-desktop-portal-wlr (xdpw)** installed and running — the host captures through its ScreenCast
  portal. Without it there is no video.

@@ -101,7 +101,7 @@ What punktfunk does with your monitor layout while it streams.

 Per-backend support:

-| | KWin | Mutter/GNOME | Sway/wlroots | Windows |
+| | KWin | Mutter/GNOME | Sway/wlroots · Hyprland | Windows |
 |---|---|---|---|---|
 | Extend | ✅ | ✅ | ✅ | ✅ |
 | Primary | ✅ | ✅ | ⚠️ treated as Extend | ✅ |
@@ -5,8 +5,9 @@ description: Enable the punktfunk browser console, read or change its login pass

 The web console is the browser UI for a punktfunk host — live status, paired devices, and the PIN
 pairing flow. It ships as the **`punktfunk-web`** systemd user unit on Linux and the **`PunktfunkWeb`**
-task on Windows, and serves on **`http://<host-ip>:47992`**. The host's own management API stays
-loopback-only behind it, so the console is the one surface you expose on the LAN.
+task on Windows, and serves on **`http://<host-ip>:47992`**. It's the surface you expose on the LAN to
+administer the host; the host's own management API (47990) keeps every admin action loopback-only and
+off-loopback serves only read-only status + game-library browsing to paired clients.

 > New here? Read [Security & Safe Use](/docs/security) first — a streaming host is remote control of
 > the machine, so keep it on a trusted LAN or VPN and require pairing.
@@ -76,7 +76,7 @@ only by Administrators and SYSTEM. To read or change it (with the `schtasks` res

 The host **requires PIN pairing** by default (secure on a LAN). To connect the first time, open the
 console from any browser on the LAN, log in, go to **Devices → [arm pairing](/docs/web-console#arm-pairing)**,
-and enter the PIN on your [client](/docs/clients). The host's own management API stays loopback-only behind the console.
+and enter the PIN on your [client](/docs/clients). The host's own management API keeps every admin action loopback-only; off-loopback it serves only read-only status and game-library browsing to paired clients.

 ### Configure

--- a/Show More
+++ b/Show More