fix(encode): port the RFI taint sweep to Vulkan Video, close the QSV sweep hole, bounds-check encode feedback

Three defects from the pf-encode sweep, each adjudicated against source.

- Vulkan Video never received fecbec2d's taint sweep (it was carved out one
  commit later). `pick_recovery_slot` accepts any resident slot whose wire is
  below the CURRENT loss start, but "resident and older than this loss" is not
  "the client decoded it": after an earlier loss [a,b] recovered at wire r,
  everything in [a, r-1] is undecodable at the client — the lost frames plus
  every frame that predicted through the gap — and those wires stay eligible
  until the 8-slot ring rolls them out. A later loss could therefore anchor on
  one and ship it tagged `recovery_anchor`, which is the client's definitive
  re-anchor signal (punktfunk-core/src/reanchor.rs): the host lifts the client's
  post-loss freeze onto a picture built from a reference it never had. Swept
  before anchor selection, matching AMF/QSV.
  `slot_wire` is blanked and `slot_poc` deliberately is NOT: `slot_poc` feeds
  `build_h265_rps_s0`, which must keep naming every physically-resident DPB
  picture or a conforming decoder evicts them and the anchor then references a
  picture the client already dropped.

- QSV's sweep was incomplete, and in its MODAL case. `ltr_slots` mirrors the
  hardware DPB, but nulling an entry issues no VPL call — the frame stays marked
  long-term until that LongTermIdx is re-marked or an IDR flushes it (amf.rs
  states this verbatim). The rejection loop iterates the post-sweep mirror and
  only rejects `Some` slots, so it silently skipped the single entry the sweep
  exists to distrust, leaving the recovery frame free to predict from it. With
  NUM_LTR_SLOTS=2 the "exactly one slot swept" case is the common one, and the
  two existing tests cover only the both-survive and both-swept cases. Taint is
  now recorded in `ltr_tainted` with the FrameOrder left in place, so anchor
  selection and the queued-force guard skip it while the rejection list still
  names it.

- `read_slot` built a slice from the driver-reported (offset, bytes-written)
  encode feedback with no validation against `bs_size`, so a driver reporting a
  range outside the bitstream buffer produced an out-of-bounds read shipped
  straight onto the wire. Checked in u64 (so the add cannot wrap) before
  `map_memory`, so the error path has no unmap to unwind.

Adds `taint_sweep_excludes_slots_from_an_earlier_loss` covering the two-loss
case the existing single-loss test does not reach.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitea/workflows/arch.yml

@@ -42,7 +42,7 @@ jobs:
       - name: Install build + runtime-dev deps
         run: |
           pacman -Syu --noconfirm --needed \
-            git nodejs rust clang cmake nasm pkgconf python vulkan-headers \
+            git nodejs rust clang cmake ninja nasm pkgconf python vulkan-headers \
             gtk4 libadwaita sdl3 ffmpeg pipewire wayland libxkbcommon opus libei \
             mesa libglvnd unzip libarchive
           # bun builds the punktfunk-web console + the punktfunk-scripting runner AND is vendored as

.gitea/workflows/deb.yml

@@ -1,8 +1,18 @@
-# Build the punktfunk-host and punktfunk-client .debs and publish them to Gitea's Debian
-# package registry, so Ubuntu boxes get new builds via `apt update && apt upgrade`. Runs
-# inside the same Ubuntu 26.04 rust-ci builder image as ci.yml, so dpkg-shlibdeps pins the
-# runtime lib package names (libavcodec62, libpipewire-0.3-0t64, …) to exactly what the
-# target boxes run.
+# Build the punktfunk .debs and publish them to Gitea's Debian package registry, so Ubuntu
+# boxes get new builds via `apt update && apt upgrade`. Two jobs, both publishing to the same
+# apt distribution/component:
+#
+#   build-publish       — client + web + scripting, on the Ubuntu 26.04 rust-ci image (the client
+#                         needs 24.04-absent libs: SDL3, GTK4 ≥ 4.20).
+#   build-publish-host  — the HOST, on the Ubuntu 24.04 rust-ci-noble image with a from-source
+#                         FFmpeg 8 BUNDLED into the .deb. This lowers the host's glibc floor to 2.39
+#                         and removes the hard `Depends: libavcodec62`, so the ONE host .deb installs
+#                         on Ubuntu 24.04 LTS through 26.04. (A 26.04-built host .deb is uninstallable
+#                         on 24.04 — the reason this job exists; see packaging/debian/README.md.)
+#
+# Both compute VERSION identically (scripts/ci/pf-version.sh is deterministic per commit), so the
+# host and client packages always share a version line. The release-attach helpers are race-safe
+# (ensure_release create-or-fetch; upsert_asset only conflicts on same-name), so the jobs run parallel.
 #
 # Registry (public, unom org): https://git.unom.io/unom/-/packages
 # Box setup (once):  see packaging/debian/README.md
@@ -83,22 +93,15 @@ jobs:
           key: cargo-target-v3-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
           restore-keys: cargo-target-v3-${{ env.rustc }}-
 
-      - name: Build release host + client
+      - name: Build release clients
         env:
-          PUNKTFUNK_BUILD_VERSION: ${{ env.VERSION }}   # stamped into the binary (build.rs)
+          PUNKTFUNK_BUILD_VERSION: ${{ env.VERSION }}   # stamped into the binaries (build.rs)
         run: |
           git config --global --add safe.directory "$PWD"
           # 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).
-          # --features punktfunk-host/nvenc: the direct-SDK NVENC path (real RFI + recovery anchor on
-          # Linux NVIDIA; design/linux-direct-nvenc.md). AMD/Intel-safe — NVENC/CUDA is dlopen'd at
-          # runtime (no link-time dep; identical DT_NEEDED to a plain build), and the encoder is only
-          # constructed for a CUDA capture frame + PUNKTFUNK_NVENC_DIRECT, never on VAAPI hosts.
-          # --features punktfunk-host/vulkan-encode: the AMD/Intel twin — raw VK_KHR_video_encode_h265
-          # with real RFI (design/linux-vulkan-video-encode.md). Pure Rust ash (no new lib / link dep);
-          # default on for HEVC (PUNKTFUNK_VULKAN_ENCODE=0 → libav VAAPI), failed open falls back to VAAPI.
-          cargo build --release --locked --features punktfunk-host/nvenc,punktfunk-host/vulkan-encode \
-            -p punktfunk-host -p punktfunk-client-linux -p punktfunk-client-session
+          # both client binaries must ship (build-client-deb.sh installs both). The HOST is built
+          # separately in the build-publish-host job (Ubuntu 24.04 image + bundled FFmpeg 8).
+          cargo build --release --locked -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
@@ -128,7 +131,7 @@ jobs:
       - name: Build .debs
         run: |
           export PATH="$HOME/.bun/bin:$PATH"
-          VERSION="$VERSION" bash packaging/debian/build-deb.sh
+          # host .deb is built in build-publish-host (Ubuntu 24.04 image); this job ships the rest.
           VERSION="$VERSION" bash packaging/debian/build-client-deb.sh
           # Reuse CI's bun for the vendored runtime (matches the amd64 runner) instead of downloading.
           VERSION="$VERSION" BUN_BIN="$(command -v bun || true)" bash packaging/debian/build-web-deb.sh
@@ -168,3 +171,101 @@ jobs:
           for DEB in dist/*.deb; do
             upsert_asset "$RID" "$DEB"
           done
+
+  # ---------------------------------------------------------------------------------------------
+  # The HOST .deb — built on Ubuntu 24.04 (noble) with a from-source FFmpeg 8 BUNDLED, so it installs
+  # on Ubuntu 24.04 LTS through 26.04 (see the file header + packaging/debian/README.md). Runs in
+  # parallel with build-publish and publishes to the SAME distribution/component; the version step is
+  # byte-identical so host and clients share a version line.
+  build-publish-host:
+    runs-on: ubuntu-24.04
+    container:
+      image: git.unom.io/unom/punktfunk-rust-ci-noble:latest
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Version + channel
+        run: |
+          git config --global --add safe.directory "$PWD"
+          eval "$(bash scripts/ci/pf-version.sh)"   # -> PF_BASE (one minor ahead of the latest stable tag)
+          SHORT=$(echo "$GITHUB_SHA" | cut -c1-8)
+          case "$GITHUB_REF" in
+            refs/tags/v*) V="${GITHUB_REF_NAME#v}"; DIST=stable ;;
+            *)            V="${PF_BASE}~ci${GITHUB_RUN_NUMBER}.g${SHORT}"; DIST=canary ;;
+          esac
+          echo "VERSION=$V" >> "$GITHUB_ENV"
+          echo "DISTRIBUTION=$DIST" >> "$GITHUB_ENV"
+          echo "host package version $V -> apt distribution '$DIST'"
+
+      # dpkg-shlibdeps/dpkg-deb + patchelf are baked into rust-ci-noble; python3 is for the
+      # release-attach helper. Re-install defensively so the job stays green against the PREVIOUS
+      # image on the same push (docker.yml bootstrap lag) — a no-op once the image ships them.
+      - name: dpkg-dev + patchelf + python3
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends dpkg-dev patchelf python3
+
+      - name: Cache keys
+        run: echo "rustc=$(rustc --version | cut -d' ' -f2)" >> "$GITHUB_ENV"
+      - uses: actions/cache@v4
+        with:
+          path: |
+            /usr/local/cargo/registry
+            /usr/local/cargo/git
+          key: cargo-home-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-home-
+      - uses: actions/cache@v4
+        with:
+          path: target
+          # Own key: this target dir is built against 24.04's glibc/toolchain and must NOT share
+          # ci.yml's 26.04 target cache (mixing would poison both).
+          key: cargo-target-noble-v1-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-target-noble-v1-${{ env.rustc }}-
+
+      - name: Build release host
+        env:
+          PUNKTFUNK_BUILD_VERSION: ${{ env.VERSION }}   # stamped into the binary (build.rs)
+        run: |
+          git config --global --add safe.directory "$PWD"
+          # Same features the old combined build used: --nvenc (direct-SDK NVENC, real RFI on NVIDIA;
+          # NVENC/CUDA is dlopen'd — no link dep, so this image needs no libcuda stub) + --vulkan-encode
+          # (raw VK_KHR_video_encode_h265 on AMD/Intel, pure ash). punktfunk-tray also ships in the host
+          # .deb (build-deb.sh builds+installs it). ffmpeg-sys-next links the image's bundled FFmpeg 8
+          # via PKG_CONFIG_PATH (set in rust-ci-noble).
+          cargo build --release --locked --features punktfunk-host/nvenc,punktfunk-host/vulkan-encode \
+            -p punktfunk-host -p punktfunk-tray
+
+      - name: Build host .deb (FFmpeg bundled)
+        # BUNDLE_FFMPEG=1 copies the image's /opt/ffmpeg libav* into the package and repoints the
+        # binary's rpath, so there is no `Depends: libavcodec62` to block install on 24.04. FFMPEG_PREFIX
+        # defaults to /opt/ffmpeg (the image's ENV also sets it).
+        run: |
+          VERSION="$VERSION" BUNDLE_FFMPEG=1 bash packaging/debian/build-deb.sh
+
+      - name: Publish to the Gitea apt registry
+        env:
+          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          for DEB in dist/*.deb; do
+            echo "uploading $DEB"
+            NAME=$(dpkg-deb -f "$DEB" Package)
+            VER=$(dpkg-deb -f "$DEB" Version)
+            ARCH=$(dpkg-deb -f "$DEB" Architecture)
+            curl -fsS -o /dev/null --user "enricobuehler:$TOKEN" -X DELETE \
+              "https://$REGISTRY/api/packages/$OWNER/debian/pool/$DISTRIBUTION/$COMPONENT/$NAME/$VER/$ARCH" || true
+            curl -fsS --user "enricobuehler:$TOKEN" --upload-file "$DEB" \
+              "https://$REGISTRY/api/packages/$OWNER/debian/pool/$DISTRIBUTION/$COMPONENT/upload"
+          done
+          echo "published host to $OWNER/debian $DISTRIBUTION/$COMPONENT"
+
+      - name: Attach the host .deb to the Gitea release (stable tags only)
+        if: startsWith(gitea.ref, 'refs/tags/v')
+        env:
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          . scripts/ci/gitea-release.sh
+          RID=$(ensure_release "$GITHUB_REF_NAME" "$GITHUB_REF_NAME" auto)
+          for DEB in dist/*.deb; do
+            upsert_asset "$RID" "$DEB"
+          done

.gitea/workflows/docker.yml

@@ -39,6 +39,12 @@ jobs:
           - image: punktfunk-rust-ci
             dockerfile: ci/rust-ci.Dockerfile
             context: ci
+          # Ubuntu 24.04 LTS host builder: same purpose as rust-ci but lowers the host .deb's glibc
+          # floor to 2.39 and bundles a from-source FFmpeg 8, so the package installs on 24.04 LTS
+          # (rust-ci's 26.04 build is uninstallable there). Consumed by deb.yml's build-publish-host job.
+          - image: punktfunk-rust-ci-noble
+            dockerfile: ci/rust-ci-noble.Dockerfile
+            context: ci
           - image: punktfunk-fedora-rpm
             dockerfile: ci/fedora-rpm.Dockerfile
             context: ci

.gitea/workflows/windows-host.yml

@@ -145,9 +145,18 @@ jobs:
       - name: Clippy (host + tray, Windows)
         shell: pwsh
         # First-ever Windows lint coverage for the host (Linux CI never lints the windows-cfg code).
+        # --release is REQUIRED, not just faster: a default (debug) clippy compiles the whole dep tree
+        # into a SECOND target dir (C:\t\debug), which means a second full build of openh264-sys2's
+        # vendored C++ (the software-H.264 fallback in pf-encode) on top of the release copy the Build
+        # steps above already produced. That second cc-rs `cl.exe` fan-out tips this runner over into
+        # `cabac_decoder.cpp: fatal error C1069 (cannot read compiler command line)` — an environmental
+        # disk/temp exhaustion, NOT a source error (the identical file compiles fine in the release
+        # build minutes earlier). Linting in release reuses those native build-script artifacts (no
+        # openh264 rebuild), and keeps everything in one C:\t\release tree. Same reason
+        # pf-vkhdr-layer's clippy below runs --release.
         run: |
-          cargo clippy -p punktfunk-host --features nvenc,amf-qsv,qsv -- -D warnings; if ($LASTEXITCODE) { throw "host clippy" }
-          cargo clippy -p punktfunk-tray -- -D warnings; if ($LASTEXITCODE) { throw "tray clippy" }
+          cargo clippy --release -p punktfunk-host --features nvenc,amf-qsv,qsv -- -D warnings; if ($LASTEXITCODE) { throw "host clippy" }
+          cargo clippy --release -p punktfunk-tray -- -D warnings; if ($LASTEXITCODE) { throw "tray clippy" }
 
       - name: Build + lint the HDR Vulkan layer (pf-vkhdr-layer)
         shell: pwsh

.gitea/workflows/windows-msix.yml

@@ -104,8 +104,9 @@ jobs:
           "MSIX_VERSION=$v" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
           Write-Output "MSIX version $v  arch ${{ matrix.arch }}  target ${{ matrix.target }}"
 
-      # Both client binaries — the shell spawns punktfunk-session.exe (a package sibling)
-      # for every stream. --no-default-features on ARM64 is a no-op for the shell.
+      # All three client binaries — the shell spawns punktfunk-session.exe (a package
+      # sibling) for every stream, and punktfunk-console.exe is the couch Start-menu tile's
+      # hand-off shim. --no-default-features on ARM64 is a no-op for the shell.
       - name: Build (release)
         shell: pwsh
         run: cargo build --release -p punktfunk-client-windows -p punktfunk-client-session ${{ matrix.session_flags }} --target ${{ matrix.target }}

Cargo.lock

@@ -2159,7 +2159,7 @@ dependencies = [
 
 [[package]]
 name = "latency-probe"
-version = "0.13.0"
+version = "0.15.0"
 
 [[package]]
 name = "lazy_static"
@@ -2264,7 +2264,7 @@ dependencies = [
 
 [[package]]
 name = "libvpl-sys"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "bindgen",
  "cmake",
@@ -2299,7 +2299,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
 
 [[package]]
 name = "loss-harness"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "punktfunk-core",
 ]
@@ -2788,7 +2788,7 @@ checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
 
 [[package]]
 name = "pf-capture"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -2808,7 +2808,7 @@ dependencies = [
 
 [[package]]
 name = "pf-client-core"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "anyhow",
  "ash",
@@ -2832,7 +2832,7 @@ dependencies = [
 
 [[package]]
 name = "pf-clipboard"
-version = "0.12.0"
+version = "0.15.0"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -2850,7 +2850,7 @@ dependencies = [
 
 [[package]]
 name = "pf-console-ui"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "anyhow",
  "ash",
@@ -2871,7 +2871,7 @@ dependencies = [
 
 [[package]]
 name = "pf-encode"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "anyhow",
  "ash",
@@ -2894,7 +2894,7 @@ dependencies = [
 
 [[package]]
 name = "pf-ffvk"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "ash",
  "bindgen",
@@ -2903,7 +2903,7 @@ dependencies = [
 
 [[package]]
 name = "pf-frame"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "anyhow",
  "libc",
@@ -2915,7 +2915,7 @@ dependencies = [
 
 [[package]]
 name = "pf-gpu"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "anyhow",
  "pf-host-config",
@@ -2929,11 +2929,11 @@ dependencies = [
 
 [[package]]
 name = "pf-host-config"
-version = "0.13.0"
+version = "0.15.0"
 
 [[package]]
 name = "pf-inject"
-version = "0.12.0"
+version = "0.15.0"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -2961,14 +2961,14 @@ dependencies = [
 
 [[package]]
 name = "pf-paths"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "tracing",
 ]
 
 [[package]]
 name = "pf-presenter"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "anyhow",
  "ash",
@@ -2983,7 +2983,7 @@ dependencies = [
 
 [[package]]
 name = "pf-vdisplay"
-version = "0.12.0"
+version = "0.15.0"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -3013,7 +3013,7 @@ dependencies = [
 
 [[package]]
 name = "pf-win-display"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "anyhow",
  "pf-paths",
@@ -3025,7 +3025,7 @@ dependencies = [
 
 [[package]]
 name = "pf-zerocopy"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "anyhow",
  "ash",
@@ -3221,7 +3221,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-android"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "android_logger",
  "jni",
@@ -3237,7 +3237,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-linux"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "anyhow",
  "async-channel",
@@ -3253,7 +3253,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-session"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "anyhow",
  "pf-client-core",
@@ -3268,7 +3268,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-windows"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "async-channel",
  "ffmpeg-next",
@@ -3287,7 +3287,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-core"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "aes-gcm",
  "bytes",
@@ -3318,7 +3318,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-host"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "aes",
  "aes-gcm",
@@ -3400,7 +3400,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-probe"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "anyhow",
  "mdns-sd",
@@ -3414,7 +3414,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-tray"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "anyhow",
  "ksni",
@@ -3437,7 +3437,7 @@ checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea"
 
 [[package]]
 name = "pyrowave-sys"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "bindgen",
  "cmake",

Cargo.toml

@@ -48,7 +48,7 @@ exclude = [
 ndk = { path = "clients/android/native/vendor/ndk" }
 
 [workspace.package]
-version = "0.13.0"
+version = "0.15.0"
 edition = "2021"
 rust-version = "1.82"
 license = "MIT OR Apache-2.0"

api/openapi.json

@@ -10,7 +10,7 @@
       "name": "MIT OR Apache-2.0",
       "identifier": "MIT OR Apache-2.0"
     },
-    "version": "0.13.0"
+    "version": "0.15.0"
   },
   "paths": {
     "/api/v1/clients": {
@@ -1348,6 +1348,117 @@
         }
       }
     },
+    "/api/v1/library/scanners": {
+      "get": {
+        "tags": [
+          "library"
+        ],
+        "summary": "List the library scanners",
+        "description": "The installed-store scanners this host supports — the list is platform-dependent (Steam\neverywhere; Lutris + Heroic on Linux; Epic, GOG, and Xbox/Game Pass on Windows), so the console\nrenders a toggle only for scanners that can do anything here. Scanners default to enabled;\ndisabling one hides its titles from every library surface from the next read. The user-curated\ncustom store is not a scanner and is always on.",
+        "operationId": "listLibraryScanners",
+        "responses": {
+          "200": {
+            "description": "This host's scanners with their enable state",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/ScannerInfo"
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/library/scanners/{id}": {
+      "put": {
+        "tags": [
+          "library"
+        ],
+        "summary": "Enable or disable a library scanner",
+        "description": "Persists the toggle and applies it from the next library read (no restart). Disabling a scanner\nhides its titles everywhere — the console grid, native clients, and the GameStream app list —\nand re-enabling brings them straight back (nothing is deleted; the scan just runs again). Emits\n`library.changed` with the scanner id as `source` when the state changed.",
+        "operationId": "setLibraryScanner",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "The scanner id (e.g. `steam`)",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScannerToggle"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Toggle stored; the full scanner list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/ScannerInfo"
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No such scanner on this platform",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Could not persist the settings",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/v1/local/summary": {
       "get": {
         "tags": [
@@ -1931,6 +2042,184 @@
         }
       }
     },
+    "/api/v1/plugins": {
+      "get": {
+        "tags": [
+          "plugins"
+        ],
+        "summary": "List registered plugins",
+        "description": "The live plugin directory (lease not expired), sorted by title. **Secret-free**: each entry\nreports its id, title, optional version, and — for plugins that serve one — a UI descriptor\n(loopback port + icon). The console renders these as nav entries and proxies to the port; it\nfetches the secret separately, server-side.",
+        "operationId": "listPlugins",
+        "responses": {
+          "200": {
+            "description": "Live plugin registrations",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/PluginSummary"
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/plugins/{id}": {
+      "put": {
+        "tags": [
+          "plugins"
+        ],
+        "summary": "Register or renew a plugin",
+        "description": "Upserts the plugin's directory entry and renews its lease (TTL 90 s). Idempotent: a plugin PUTs\nthis every ~30 s while it runs. The optional `ui` block declares a loopback UI surface the console\nwill proxy and add to its nav. Emits `plugins.changed` when an operator-visible field changed\n(first registration, restart, or re-scan) — a pure renewal is silent.",
+        "operationId": "registerPlugin",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "The plugin id (its `definePlugin` name: `[a-z][a-z0-9-]*`)",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PluginRegistration"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "204": {
+            "description": "Registered / renewed"
+          },
+          "400": {
+            "description": "Invalid id or registration",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "plugins"
+        ],
+        "summary": "Deregister a plugin",
+        "description": "The clean-shutdown path: removes the plugin's directory entry immediately (the SDK helper calls\nthis from its scope finalizer on `SIGTERM`). Emits `plugins.changed` when a live entry was\nremoved. Idempotent — deleting an unknown/expired id is a no-op `204`.",
+        "operationId": "deregisterPlugin",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "The plugin id",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Deregistered (or already absent)"
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/plugins/{id}/ui-credential": {
+      "get": {
+        "tags": [
+          "plugins"
+        ],
+        "summary": "Fetch a plugin UI's proxy credential",
+        "description": "Returns `{port, secret}` for a live plugin's loopback UI — the console proxy's server-side lookup.\nBearer + loopback only (like every mutation), and additionally excluded from the console's browser\npassthrough: the secret never reaches a browser.",
+        "operationId": "getPluginUiCredential",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "The plugin id",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The proxy credential",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UiCredential"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No live plugin with that id, or it serves no UI",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/v1/session": {
       "delete": {
         "tags": [
@@ -3294,6 +3583,25 @@
               }
             }
           },
+          {
+            "type": "object",
+            "required": [
+              "id",
+              "kind"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "The plugin whose registration changed (registered, restarted, deregistered, or\nlease-expired). A consumer re-reads `GET /api/v1/plugins` for the new set."
+              },
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "plugins.changed"
+                ]
+              }
+            }
+          },
           {
             "type": "object",
             "required": [
@@ -4099,6 +4407,116 @@
           "gamestream"
         ]
       },
+      "PluginRegistration": {
+        "type": "object",
+        "description": "Register/renew body for `PUT /plugins/{id}`.",
+        "required": [
+          "title"
+        ],
+        "properties": {
+          "title": {
+            "type": "string",
+            "description": "Human-readable title for the console nav entry (1–64 chars; control chars stripped)."
+          },
+          "ui": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/PluginUi",
+                "description": "Present iff the plugin serves a UI surface. A registration with no `ui` is a liveness/phone-book\nentry only (e.g. a future runner-management listing) and grows no nav entry."
+              }
+            ]
+          },
+          "version": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Optional plugin version, purely informational (≤32 chars)."
+          }
+        }
+      },
+      "PluginSummary": {
+        "type": "object",
+        "description": "One entry in `GET /plugins`. **Never carries the secret** — the browser learns a plugin exists\nand has a UI, nothing that lets it reach the plugin directly (it goes through the console proxy).",
+        "required": [
+          "id",
+          "title"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "ui": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/PluginUiPublic"
+              }
+            ]
+          },
+          "version": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        }
+      },
+      "PluginUi": {
+        "type": "object",
+        "description": "A plugin's UI surface as it registers it. Carries the secret — this shape is only ever a request\nbody, never a response ([`PluginUiPublic`] is the secret-free view).",
+        "required": [
+          "port",
+          "secret"
+        ],
+        "properties": {
+          "icon": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Optional lucide icon name for the console nav entry (`^[a-z0-9-]{1,48}$`)."
+          },
+          "port": {
+            "type": "integer",
+            "format": "int32",
+            "description": "The **loopback** port the plugin serves its UI on. The host and console only ever dial\n`127.0.0.1:<port>`; a registration can never carry a hostname.",
+            "minimum": 0
+          },
+          "secret": {
+            "type": "string",
+            "description": "Per-boot shared secret the console proxy must present (as `Authorization: Bearer`) on every\nrequest to the plugin's UI server. Rotated whenever the plugin restarts."
+          }
+        }
+      },
+      "PluginUiPublic": {
+        "type": "object",
+        "description": "The secret-free view of a plugin's UI surface — what [`list_plugins`] returns to the browser.",
+        "required": [
+          "port"
+        ],
+        "properties": {
+          "icon": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "port": {
+            "type": "integer",
+            "format": "int32",
+            "minimum": 0
+          }
+        }
+      },
       "PortMap": {
         "type": "object",
         "description": "Every port a client integration may need (Moonlight derives the stream ports from the\nHTTP base; a control pane should not have to).",
@@ -4364,6 +4782,44 @@
           }
         }
       },
+      "ScannerInfo": {
+        "type": "object",
+        "description": "One installed-store scanner this host build supports, with its enable state — the unit the\nconsole renders a toggle for. The list is platform-gated at compile time (the scanners are),\nso the console never shows a toggle that cannot do anything on this host.",
+        "required": [
+          "id",
+          "label",
+          "enabled"
+        ],
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "description": "Whether this host runs the scanner (default true)."
+          },
+          "id": {
+            "type": "string",
+            "description": "Stable scanner id — the same string the scanner's entries carry in their `store` field.",
+            "example": "steam"
+          },
+          "label": {
+            "type": "string",
+            "description": "Human-facing name for the console toggle.",
+            "example": "Steam"
+          }
+        }
+      },
+      "ScannerToggle": {
+        "type": "object",
+        "description": "Request body for `setLibraryScanner`.",
+        "required": [
+          "enabled"
+        ],
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "description": "Whether the scanner should run on this host."
+          }
+        }
+      },
       "SessionInfo": {
         "type": "object",
         "description": "Client-requested launch parameters (key material is never exposed here).",
@@ -4710,6 +5166,24 @@
           "primary",
           "exclusive"
         ]
+      },
+      "UiCredential": {
+        "type": "object",
+        "description": "`GET /plugins/{id}/ui-credential` — the console proxy's server-side lookup (bearer + loopback).\nThis is the only endpoint that returns a secret; the console BFF denylists it from the browser.",
+        "required": [
+          "port",
+          "secret"
+        ],
+        "properties": {
+          "port": {
+            "type": "integer",
+            "format": "int32",
+            "minimum": 0
+          },
+          "secret": {
+            "type": "string"
+          }
+        }
       }
     },
     "securitySchemes": {
@@ -4772,6 +5246,10 @@
     {
       "name": "hooks",
       "description": "Operator hooks: commands and webhooks fired on lifecycle events (fire-and-forget — hooks observe, never veto)"
+    },
+    {
+      "name": "plugins",
+      "description": "Plugin directory: running `punktfunk-plugin-*` processes register a lease and, optionally, a loopback UI the web console proxies and adds to its nav"
     }
   ]
 }

ci/rust-ci-noble.Dockerfile

@@ -0,0 +1,85 @@
+# LTS builder for the punktfunk HOST .deb — Ubuntu 24.04 (noble), the current Ubuntu LTS.
+#
+# WHY THIS EXISTS (see packaging/debian/README.md → "Ubuntu 24.04 LTS"):
+# The default builder (ci/rust-ci.Dockerfile) is Ubuntu 26.04, so the host .deb it produces bakes
+# in a glibc 2.41 floor and a hard `Depends: libavcodec62, …` (FFmpeg 8). Ubuntu 24.04 LTS ships
+# glibc 2.39 and FFmpeg 6.1 (libavcodec60), so that .deb is uninstallable there — apt reports the
+# deps as "too recent". Building the host on 24.04 instead lowers the glibc floor to 2.39 (the
+# binary then runs on 24.04 → 26.04), and the ONE library 24.04 is too old for — FFmpeg — is built
+# from source here and BUNDLED into the .deb (packaging/debian/build-deb.sh, BUNDLE_FFMPEG=1), so
+# the package no longer depends on the distro's libav* at all. Everything else the host links
+# (PipeWire, Wayland, xkbcommon, GL/EGL/GBM, Vulkan; opus is vendored via cmake) is soname-compatible
+# on 24.04, so this ONE universal host .deb replaces the 26.04-built one for every Ubuntu user.
+#
+# libcuda is deliberately NOT provided: the host dlopen's libcuda.so.1 at runtime (pf-zerocopy /
+# pf-encode) and never link-imports it, so — unlike the full-workspace rust-ci image, which builds
+# tests that DO link a cuda stub — this host-only build needs no NVIDIA driver package. NVENC/EGL
+# come from whatever driver the target runs, out of band.
+#
+# Rebuilt+pushed by .gitea/workflows/docker.yml (matrix: punktfunk-rust-ci-noble); consumed by the
+# `build-publish-host` job in .gitea/workflows/deb.yml. Bootstrap: like rust-ci, the first deb.yml
+# run after this image is added uses the image from a PRIOR docker.yml push — seed it once manually
+# (docker build -f ci/rust-ci-noble.Dockerfile -t … ci && docker push) before the host job can run.
+FROM ubuntu:24.04
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    # toolchain + bindgen; nodejs runs the JS actions (checkout/cache); unzip for the rustup installer's deps
+    build-essential clang libclang-dev pkg-config cmake git curl ca-certificates nodejs unzip \
+    # .deb assembly: dpkg-shlibdeps/dpkg-deb; patchelf repoints the binary's rpath at the bundled FFmpeg
+    dpkg-dev patchelf \
+    # FFmpeg 8 build deps: nasm (asm), VAAPI (libva/libdrm) so the built libav* keep the AMD/Intel
+    # encode backend the host auto-selects; zlib (libavformat). NVENC needs only headers (below), dlopen'd.
+    nasm libva-dev libdrm-dev zlib1g-dev \
+    # host link deps present on 24.04 with sonames compatible up to 26.04
+    libpipewire-0.3-dev libwayland-dev libxkbcommon-dev \
+    libgl-dev libegl-dev libgbm-dev libvulkan-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# --- FFmpeg 8 from source -> /opt/ffmpeg (shared libs + .pc files) ----------------------------------
+# libavcodec.so.62, matching the 26.04 line's soname so the host behaves identically. This is an
+# LGPL build (no --enable-gpl / --enable-nonfree) so bundling the .so's into an MIT/Apache .deb stays
+# license-clean — LGPL's relink clause is satisfied by dynamic linking, and the only encoders the host
+# calls (h264/hevc/av1 _nvenc + _vaapi, plus scale_vaapi/hwmap filters; software H.264 fallback is the
+# BSD-2 openh264 crate, NOT FFmpeg libx264) are all LGPL-compatible.
+# Sourced from the official FFmpeg GitHub mirror by release tag, NOT ffmpeg.org: the CI build network
+# can't reach ffmpeg.org (curl times out) but reaches github.com fine. The `nX.Y` tag pins the version
+# (n8.0 -> libavcodec 62); bump it to move FFmpeg. Immutable-tag clone, so no separate checksum needed.
+ARG FFMPEG_TAG=n8.0
+# nv-codec-headers must MATCH the FFmpeg version: its `master` is NVENC SDK 13, which renamed
+# NV_ENC_CLOCK_TIMESTAMP_SET.countingType -> countingTypeLSB and won't compile against FFmpeg 8.0's
+# nvenc.c. Pin the last SDK-12 tag (has the field FFmpeg 8.0 expects). Bump alongside FFMPEG_TAG.
+ARG NVHDR_TAG=n12.2.72.0
+RUN set -eux; \
+    # nv-codec-headers: the NVENC/NVDEC headers FFmpeg's --enable-nvenc needs (headers only, no lib —
+    # the driver is dlopen'd at runtime). Installs ffnvcodec.pc under /usr/local/lib/pkgconfig.
+    git clone --depth 1 --branch "$NVHDR_TAG" https://github.com/FFmpeg/nv-codec-headers.git /tmp/nvhdr; \
+    make -C /tmp/nvhdr install PREFIX=/usr/local; \
+    git clone --depth 1 --branch "$FFMPEG_TAG" https://github.com/FFmpeg/FFmpeg.git /tmp/ffmpeg; \
+    cd /tmp/ffmpeg; \
+    PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./configure \
+      --prefix=/opt/ffmpeg \
+      --enable-shared --disable-static \
+      --disable-doc --disable-programs --disable-debug \
+      --enable-nvenc --enable-vaapi \
+      --extra-cflags=-I/usr/local/include --extra-ldflags=-L/usr/local/lib; \
+    make -j"$(nproc)"; make install; \
+    cd /; rm -rf /tmp/ffmpeg /tmp/nvhdr; \
+    # sanity: the soname we expect to bundle (libavcodec.so.62 on FFmpeg 8)
+    test -e /opt/ffmpeg/lib/libavcodec.so.62
+
+# ffmpeg-sys-next discovers FFmpeg via pkg-config; point it at the bundled build. PKG_CONFIG_PATH is
+# PREPENDED to pkg-config's default dirs (not a replacement — that's PKG_CONFIG_LIBDIR), so PipeWire /
+# Wayland / libva / … still resolve from the system. FFMPEG_PREFIX is read by build-deb.sh's bundler.
+ENV PKG_CONFIG_PATH=/opt/ffmpeg/lib/pkgconfig \
+    FFMPEG_PREFIX=/opt/ffmpeg
+
+# Toolchain shared across CI users (jobs may run as different uids).
+ENV RUSTUP_HOME=/usr/local/rustup \
+    CARGO_HOME=/usr/local/cargo \
+    PATH=/usr/local/cargo/bin:$PATH
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
+    | sh -s -- -y --no-modify-path --profile minimal \
+        --component rustfmt,clippy \
+    && chmod -R a+w "$RUSTUP_HOME" "$CARGO_HOME" \
+    && rustc --version && cargo clippy --version && cargo fmt --version

clients/apple/Punktfunk.xcodeproj/project.pbxproj

@@ -13,8 +13,8 @@
 		DD0000000000000000000003 /* SwiftUINavigationTransitions in Frameworks */ = {isa = PBXBuildFile; productRef = DD0000000000000000000002 /* SwiftUINavigationTransitions */; };
 		E295569A300948B9009F939C /* WidgetKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = E2955699300948B9009F939C /* WidgetKit.framework */; };
 		E295569C300948B9009F939C /* SwiftUI.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = E295569B300948B9009F939C /* SwiftUI.framework */; };
-		E2CAFE000000000000000001 /* PunktfunkShared in Frameworks */ = {isa = PBXBuildFile; productRef = E2CAFE000000000000000002 /* PunktfunkShared */; };
 		E29556A9300948BA009F939C /* PunktfunkWidgetsExtension.appex in Embed Foundation Extensions */ = {isa = PBXBuildFile; fileRef = E2955697300948B9009F939C /* PunktfunkWidgetsExtension.appex */; settings = {ATTRIBUTES = (RemoveHeadersOnCopy, ); }; };
+		E2CAFE000000000000000001 /* PunktfunkShared in Frameworks */ = {isa = PBXBuildFile; productRef = E2CAFE000000000000000002 /* PunktfunkShared */; };
 /* End PBXBuildFile section */
 
 /* Begin PBXContainerItemProxy section */
@@ -504,6 +504,7 @@
 				MARKETING_VERSION = 0.9.1;
 				PRODUCT_BUNDLE_IDENTIFIER = io.unom.punktfunk;
 				PRODUCT_NAME = "$(TARGET_NAME)";
+				REGISTER_APP_GROUPS = YES;
 				SUPPORTED_PLATFORMS = macosx;
 				SUPPORTS_MACCATALYST = NO;
 				SWIFT_EMIT_LOC_STRINGS = YES;
@@ -540,6 +541,7 @@
 				MARKETING_VERSION = 0.9.1;
 				PRODUCT_BUNDLE_IDENTIFIER = io.unom.punktfunk;
 				PRODUCT_NAME = "$(TARGET_NAME)";
+				REGISTER_APP_GROUPS = YES;
 				SUPPORTED_PLATFORMS = macosx;
 				SUPPORTS_MACCATALYST = NO;
 				SWIFT_EMIT_LOC_STRINGS = YES;
@@ -719,7 +721,7 @@
 					"@executable_path/../../Frameworks",
 				);
 				LOCALIZATION_PREFERS_STRING_CATALOGS = YES;
-				MARKETING_VERSION = 1.0;
+				MARKETING_VERSION = 0.9.1;
 				PRODUCT_BUNDLE_IDENTIFIER = io.unom.punktfunk.widgets;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				REGISTER_APP_GROUPS = YES;
@@ -764,7 +766,7 @@
 					"@executable_path/../../Frameworks",
 				);
 				LOCALIZATION_PREFERS_STRING_CATALOGS = YES;
-				MARKETING_VERSION = 1.0;
+				MARKETING_VERSION = 0.9.1;
 				PRODUCT_BUNDLE_IDENTIFIER = io.unom.punktfunk.widgets;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				REGISTER_APP_GROUPS = YES;
@@ -861,15 +863,15 @@
 			isa = XCSwiftPackageProductDependency;
 			productName = PunktfunkKit;
 		};
-		E2CAFE000000000000000002 /* PunktfunkShared */ = {
-			isa = XCSwiftPackageProductDependency;
-			productName = PunktfunkShared;
-		};
 		DD0000000000000000000002 /* SwiftUINavigationTransitions */ = {
 			isa = XCSwiftPackageProductDependency;
 			package = DD0000000000000000000001 /* XCRemoteSwiftPackageReference "swiftui-navigation-transitions" */;
 			productName = SwiftUINavigationTransitions;
 		};
+		E2CAFE000000000000000002 /* PunktfunkShared */ = {
+			isa = XCSwiftPackageProductDependency;
+			productName = PunktfunkShared;
+		};
 /* End XCSwiftPackageProductDependency section */
 	};
 	rootObject = AA000000000000000000000D /* Project object */;

clients/apple/Punktfunk.xcodeproj/xcshareddata/xcschemes/Punktfunk-iOS.xcscheme

@@ -55,6 +55,11 @@
             value = "1"
             isEnabled = "YES">
          </EnvironmentVariable>
+         <EnvironmentVariable
+            key = "MTL_HUD_ENABLED"
+            value = "1"
+            isEnabled = "YES">
+         </EnvironmentVariable>
       </EnvironmentVariables>
    </LaunchAction>
    <ProfileAction

clients/apple/Punktfunk.xcodeproj/xcshareddata/xcschemes/Punktfunk.xcscheme

@@ -30,7 +30,7 @@
       shouldAutocreateTestPlan = "YES">
    </TestAction>
    <LaunchAction
-      buildConfiguration = "Debug"
+      buildConfiguration = "Release"
       selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
       selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
       launchStyle = "0"

clients/apple/PunktfunkWidgets/HostsWidget.swift

@@ -94,7 +94,7 @@ private struct SmallHostView: View {
             VStack(alignment: .leading, spacing: 6) {
                 Image(systemName: "play.tv.fill")
                     .font(.title2)
-                    .foregroundStyle(.tint)
+                    .foregroundStyle(Color.brand)
                 Spacer(minLength: 0)
                 Text(host.displayName)
                     .font(.headline)
@@ -122,12 +122,12 @@ private struct MediumHostsView: View {
             VStack(alignment: .leading, spacing: 8) {
                 Text("Punktfunk")
                     .font(.caption).bold()
-                    .foregroundStyle(.tint)
+                    .foregroundStyle(Color.brand)
                 ForEach(hosts.prefix(4)) { host in
                     Link(destination: connectURL(host)) {
                         HStack {
                             Image(systemName: "play.tv.fill")
-                                .foregroundStyle(.tint)
+                                .foregroundStyle(Color.brand)
                             Text(host.displayName)
                                 .font(.subheadline)
                                 .lineLimit(1)
@@ -184,3 +184,47 @@ private struct EmptyHostView: View {
         .frame(maxWidth: .infinity, maxHeight: .infinity)
     }
 }
+
+// MARK: - Previews (Xcode canvas)
+//
+// Select the PunktfunkWidgetsExtension scheme and open the canvas (⌥⌘↩). The widget
+// `#Preview(as:widget:timeline:)` form feeds sample entries directly — the App-Group store is
+// never read, so the canvas works without a paired device or saved hosts. The small preview's
+// second entry shows the empty state one timeline click away.
+
+private let previewHosts: [StoredHost] = [
+    StoredHost(
+        name: "Studio", address: "192.168.1.20",
+        lastConnected: .now.addingTimeInterval(-40 * 60)),
+    StoredHost(
+        name: "Living Room", address: "192.168.1.30",
+        lastConnected: .now.addingTimeInterval(-26 * 3600)),
+    StoredHost(
+        name: "Workstation", address: "10.0.0.5",
+        lastConnected: .now.addingTimeInterval(-6 * 86400)),
+]
+
+#Preview("Small", as: .systemSmall) {
+    HostsWidget()
+} timeline: {
+    HostsEntry(date: .now, hosts: previewHosts)
+    HostsEntry(date: .now, hosts: [])
+}
+
+#Preview("Medium", as: .systemMedium) {
+    HostsWidget()
+} timeline: {
+    HostsEntry(date: .now, hosts: previewHosts)
+}
+
+#Preview("Lock Screen circular", as: .accessoryCircular) {
+    HostsWidget()
+} timeline: {
+    HostsEntry(date: .now, hosts: previewHosts)
+}
+
+#Preview("Lock Screen rectangular", as: .accessoryRectangular) {
+    HostsWidget()
+} timeline: {
+    HostsEntry(date: .now, hosts: previewHosts)
+}

clients/apple/PunktfunkWidgets/SessionLiveActivity.swift

@@ -19,43 +19,69 @@ struct PunktfunkSessionLiveActivity: Widget {
             LockScreenView(context: context)
                 .activitySystemActionForegroundColor(.white)
         } dynamicIsland: { context in
+            // Island layout (2026-07 rebuild): the EXPANDED island leads with identity (brand
+            // glyph + host), keeps the elapsed clock at the trailing edge, and gives the bottom
+            // region one purposeful row — session status + the live numbers on the left, the
+            // End action on the right. COMPACT shows the one number worth a glance: live
+            // latency while streaming (the sparse ~30 s pushes), the disconnect countdown while
+            // backgrounded, a state glyph otherwise. Brand purple is the identity accent
+            // everywhere `.tint` used to leak system blue.
             DynamicIsland {
                 DynamicIslandExpandedRegion(.leading) {
-                    Label {
-                        Text(context.attributes.hostName).font(.caption).lineLimit(1)
-                    } icon: {
+                    HStack(spacing: 6) {
                         Image(systemName: "play.tv.fill")
+                            .font(.subheadline)
+                            .foregroundStyle(Color.brand)
+                        Text(context.attributes.hostName)
+                            .font(.subheadline.weight(.semibold))
+                            .lineLimit(1)
                     }
-                    .foregroundStyle(.tint)
+                    .padding(.leading, 4)
+                    .padding(.top, 2)
                 }
                 DynamicIslandExpandedRegion(.trailing) {
-                    Text(timerInterval: context.state.startedAt...Date.distantFuture, countsDown: false)
-                        .font(.caption).monospacedDigit()
-                        .frame(maxWidth: 56)
+                    ElapsedClock(startedAt: context.state.startedAt)
+                        .font(.subheadline)
                         .foregroundStyle(.secondary)
+                        .frame(maxWidth: 64, alignment: .trailing)
+                        .padding(.trailing, 4)
+                        .padding(.top, 2)
                 }
                 DynamicIslandExpandedRegion(.center) {
                     if let title = context.attributes.launchTitle {
-                        Text(title).font(.caption2).lineLimit(1).foregroundStyle(.secondary)
+                        Text(title)
+                            .font(.caption)
+                            .foregroundStyle(.secondary)
+                            .lineLimit(1)
                     }
                 }
                 DynamicIslandExpandedRegion(.bottom) {
-                    VStack(spacing: 6) {
-                        Text(context.state.modeLine)
-                            .font(.caption2).foregroundStyle(.secondary).lineLimit(1)
-                        StageLine(state: context.state)
-                        EndButton()
+                    // The expanded island's height is there to be used: one info row (status
+                    // leading, live numbers trailing — the mode string stays on the Lock
+                    // Screen), then the platform-conventional LARGE full-width action button.
+                    VStack(spacing: 10) {
+                        HStack {
+                            StatusLine(state: context.state)
+                            Spacer(minLength: 8)
+                            StatsLine(state: context.state, showMode: false)
+                        }
+                        Spacer(minLength: 0) // any slack height goes here — button hugs the bottom
+                        EndButton(fullWidth: true)
                     }
+                    .frame(maxHeight: .infinity)
+                    .padding(.horizontal, 4)
+                    .padding(.top, 6)
                 }
             } compactLeading: {
-                Image(systemName: "play.tv.fill").foregroundStyle(.tint)
+                Image(systemName: "play.tv.fill")
+                    .foregroundStyle(Color.brand)
             } compactTrailing: {
-                Text(timerInterval: context.state.startedAt...Date.distantFuture, countsDown: false)
-                    .monospacedDigit()
-                    .frame(maxWidth: 44)
+                CompactReadout(state: context.state)
             } minimal: {
-                Image(systemName: "play.tv.fill").foregroundStyle(.tint)
+                Image(systemName: "play.tv.fill")
+                    .foregroundStyle(Color.brand)
             }
+            .keylineTint(Color.brand)
         }
     }
 }
@@ -69,21 +95,20 @@ private struct LockScreenView: View {
         HStack(alignment: .top, spacing: 12) {
             Image(systemName: "play.tv.fill")
                 .font(.title2)
-                .foregroundStyle(.tint)
-            VStack(alignment: .leading, spacing: 3) {
+                .foregroundStyle(Color.brand)
+            VStack(alignment: .leading, spacing: 4) {
                 HStack {
                     Text(context.attributes.hostName).font(.headline).lineLimit(1)
                     Spacer()
-                    Text(timerInterval: context.state.startedAt...Date.distantFuture, countsDown: false)
-                        .font(.subheadline).monospacedDigit()
+                    ElapsedClock(startedAt: context.state.startedAt)
+                        .font(.subheadline)
                         .foregroundStyle(.secondary)
                 }
                 if let title = context.attributes.launchTitle {
                     Text(title).font(.caption).foregroundStyle(.secondary).lineLimit(1)
                 }
-                Text(context.state.modeLine)
-                    .font(.caption2).foregroundStyle(.secondary).lineLimit(1)
-                StageLine(state: context.state)
+                StatusLine(state: context.state)
+                StatsLine(state: context.state)
             }
             if context.state.stage == .background {
                 EndButton()
@@ -95,46 +120,237 @@ private struct LockScreenView: View {
 
 // MARK: - Shared pieces
 
-/// The stage badge + (while backgrounded) the auto-disconnect countdown.
-private struct StageLine: View {
+/// The ticking elapsed-session clock — client-side via `timerInterval`, no per-second push.
+private struct ElapsedClock: View {
+    let startedAt: Date
+    var body: some View {
+        Text(timerInterval: startedAt...Date.distantFuture, countsDown: false)
+            .monospacedDigit()
+            .multilineTextAlignment(.trailing)
+    }
+}
+
+/// The session's state as a colored dot + label; while backgrounded with a deadline, the label
+/// IS the countdown. One shared truth for the island bottom and the Lock Screen banner.
+private struct StatusLine: View {
+    let state: PunktfunkSessionAttributes.ContentState
+
+    var body: some View {
+        HStack(spacing: 5) {
+            Circle()
+                .fill(color)
+                .frame(width: 6, height: 6)
+            label
+                .font(.caption2.weight(.medium))
+                .foregroundStyle(.secondary)
+                .lineLimit(1)
+        }
+    }
+
+    private var color: Color {
+        switch state.stage {
+        case .streaming: return .green
+        case .background: return .orange
+        case .reconnecting: return .yellow
+        case .ending: return .secondary
+        }
+    }
+
+    @ViewBuilder private var label: some View {
+        switch state.stage {
+        case .streaming:
+            Text("Streaming")
+        case .background:
+            if let deadline = state.backgroundDeadline {
+                HStack(spacing: 3) {
+                    Text("Background · ends in")
+                    Text(timerInterval: Date()...deadline, countsDown: true)
+                        .monospacedDigit()
+                }
+            } else {
+                Text("Running in background")
+            }
+        case .reconnecting:
+            Text("Reconnecting…")
+        case .ending:
+            Text("Session ended")
+        }
+    }
+}
+
+/// The live numbers, one quiet line: latency and bitrate (the sparse ~30 s pushes) ahead of the
+/// mode (`showMode` false on the island, where the row shares space with the status line).
+/// Anything unreported simply doesn't appear.
+private struct StatsLine: View {
+    let state: PunktfunkSessionAttributes.ContentState
+    var showMode = true
+
+    var body: some View {
+        HStack(spacing: 8) {
+            if let ms = state.latencyMs {
+                stat("bolt.fill", "\(ms) ms")
+            }
+            if let mbps = state.mbps {
+                stat("arrow.down", String(format: "%.0f Mb/s", mbps))
+            }
+            if showMode {
+                Text(state.modeLine)
+                    .font(.caption2)
+                    .foregroundStyle(.tertiary)
+                    .lineLimit(1)
+            }
+        }
+    }
+
+    private func stat(_ icon: String, _ text: String) -> some View {
+        HStack(spacing: 3) {
+            Image(systemName: icon)
+                .font(.system(size: 8, weight: .semibold))
+            Text(text)
+                .font(.caption2)
+                .monospacedDigit()
+        }
+        .foregroundStyle(.secondary)
+    }
+}
+
+/// The compact trailing readout — the island's one glanceable number. Streaming: the live
+/// latency once the app has reported one, the elapsed clock until then. Backgrounded: the
+/// auto-disconnect countdown. Off-nominal stages show a state glyph instead of a number.
+private struct CompactReadout: View {
     let state: PunktfunkSessionAttributes.ContentState
 
     var body: some View {
         switch state.stage {
         case .streaming:
-            EmptyView()
+            if let ms = state.latencyMs {
+                Text("\(ms) ms")
+                    .font(.caption2.weight(.medium))
+                    .monospacedDigit()
+                    .foregroundStyle(.green)
+            } else {
+                ElapsedClock(startedAt: state.startedAt)
+                    .font(.caption2)
+                    .frame(maxWidth: 48)
+            }
         case .background:
             if let deadline = state.backgroundDeadline {
-                HStack(spacing: 3) {
-                    Text("Keeps running for")
-                    Text(timerInterval: Date()...deadline, countsDown: true)
-                        .monospacedDigit()
-                }
-                .font(.caption2)
-                .foregroundStyle(.secondary)
+                Text(timerInterval: Date()...deadline, countsDown: true)
+                    .font(.caption2)
+                    .monospacedDigit()
+                    .multilineTextAlignment(.trailing)
+                    .frame(maxWidth: 48)
+                    .foregroundStyle(.orange)
             } else {
-                badge("Running in background", .orange)
+                Image(systemName: "moon.fill").foregroundStyle(.orange)
             }
         case .reconnecting:
-            badge("Reconnecting…", .yellow)
+            Image(systemName: "wifi.exclamationmark").foregroundStyle(.yellow)
         case .ending:
-            badge("Session ended", .secondary)
+            Image(systemName: "stop.fill").foregroundStyle(.secondary)
         }
     }
-
-    private func badge(_ text: String, _ color: Color) -> some View {
-        Text(text).font(.caption2).foregroundStyle(color)
-    }
 }
 
 /// End-stream button — runs EndStreamIntent in the app process (LiveActivityIntent).
+/// `fullWidth` is the expanded island's large bottom action (the platform convention there);
+/// the compact form remains the Lock Screen banner's trailing button while backgrounded.
 private struct EndButton: View {
+    var fullWidth = false
+
     var body: some View {
-        Button(intent: EndStreamIntent()) {
-            Label("End", systemImage: "stop.fill")
-                .font(.caption).bold()
+        if fullWidth {
+            Button(intent: EndStreamIntent()) {
+                Label("End Session", systemImage: "stop.fill")
+                    .font(.subheadline.weight(.semibold))
+                    .frame(maxWidth: .infinity)
+                    .padding(.vertical, 2)
+            }
+            .tint(.red)
+            .buttonStyle(.bordered)
+        } else {
+            Button(intent: EndStreamIntent()) {
+                Label("End", systemImage: "stop.fill")
+                    .font(.caption).bold()
+            }
+            .tint(.red)
+            .buttonStyle(.bordered)
         }
-        .tint(.red)
-        .buttonStyle(.bordered)
     }
 }
+
+// MARK: - Previews (Xcode canvas)
+//
+// Select the PunktfunkWidgetsExtension scheme and open the canvas (⌥⌘↩) — the activity
+// `#Preview(as:using:)` form renders every surface WITHOUT running the app or starting a real
+// Activity: `.content` is the Lock Screen banner, `.dynamicIsland(.expanded/.compact/.minimal)`
+// the island states (canvas device must be a Dynamic Island phone for those). Each listed
+// content state becomes a frame in the canvas timeline strip, so all four session stages are one
+// click apart. Sample state lives here (fileprivate), never in PunktfunkShared.
+
+extension PunktfunkSessionAttributes {
+    fileprivate static var preview: PunktfunkSessionAttributes {
+        PunktfunkSessionAttributes(hostID: UUID(), hostName: "Studio", launchTitle: "Hades II")
+    }
+}
+
+extension PunktfunkSessionAttributes.ContentState {
+    fileprivate static var streaming: Self {
+        .init(
+            stage: .streaming, startedAt: .now.addingTimeInterval(-754),
+            modeLine: "2752×2064 @120 · HEVC · HDR", latencyMs: 8, mbps: 84.2)
+    }
+    fileprivate static var backgrounded: Self {
+        .init(
+            stage: .background, startedAt: .now.addingTimeInterval(-1975),
+            modeLine: "2752×2064 @120 · HEVC · HDR",
+            backgroundDeadline: .now.addingTimeInterval(9 * 60))
+    }
+    fileprivate static var reconnecting: Self {
+        .init(
+            stage: .reconnecting, startedAt: .now.addingTimeInterval(-754),
+            modeLine: "2752×2064 @120 · HEVC · HDR")
+    }
+    fileprivate static var ended: Self {
+        .init(
+            stage: .ending, startedAt: .now.addingTimeInterval(-3541),
+            modeLine: "2752×2064 @120 · HEVC · HDR")
+    }
+}
+
+#Preview("Lock Screen", as: .content, using: PunktfunkSessionAttributes.preview) {
+    PunktfunkSessionLiveActivity()
+} contentStates: {
+    PunktfunkSessionAttributes.ContentState.streaming
+    PunktfunkSessionAttributes.ContentState.backgrounded
+    PunktfunkSessionAttributes.ContentState.reconnecting
+    PunktfunkSessionAttributes.ContentState.ended
+}
+
+#Preview(
+    "Island expanded", as: .dynamicIsland(.expanded),
+    using: PunktfunkSessionAttributes.preview
+) {
+    PunktfunkSessionLiveActivity()
+} contentStates: {
+    PunktfunkSessionAttributes.ContentState.streaming
+    PunktfunkSessionAttributes.ContentState.backgrounded
+}
+
+#Preview(
+    "Island compact", as: .dynamicIsland(.compact),
+    using: PunktfunkSessionAttributes.preview
+) {
+    PunktfunkSessionLiveActivity()
+} contentStates: {
+    PunktfunkSessionAttributes.ContentState.streaming
+}
+
+#Preview(
+    "Island minimal", as: .dynamicIsland(.minimal),
+    using: PunktfunkSessionAttributes.preview
+) {
+    PunktfunkSessionLiveActivity()
+} contentStates: {
+    PunktfunkSessionAttributes.ContentState.streaming
+}

clients/apple/Sources/PunktfunkClient/ContentView.swift

@@ -89,6 +89,11 @@ struct ContentView: View {
     /// the remote-as-pointer controls, so it must be seen at least once per session.
     @State private var showShortcutHint = false
     #endif
+    #if os(iOS)
+    /// The stats-OFF tier's touch-exit disc window (see the overlay in `stream(captureEnabled:)`
+    /// — the disc must LEAVE the hierarchy so nothing composites over the metal layer).
+    @State private var showTouchExit = false
+    #endif
     #if !os(macOS)
     @State private var showSettings = false
     #endif
@@ -193,6 +198,9 @@ struct ContentView: View {
                 #if os(macOS) || os(tvOS)
                 showShortcutHint = true // the 6 s shortcut banner, per session start
                 #endif
+                #if os(iOS)
+                showTouchExit = true // the off-tier exit disc's 8 s window, per session start
+                #endif
                 // A session actually started — remember it on the card ("Connected … ago"
                 // plus the accent ring on the most recent host).
                 guard let host = model.activeHost else { break }
@@ -292,7 +300,7 @@ struct ContentView: View {
             Button("Cancel", role: .cancel) {}
         } message: { req in
             Text("\(req.host.displayName) requires pairing. Request access and approve this "
-                + "device in the host's web console (port 3000 → Pairing) — no PIN needed. Or "
+                + "device in the host's web console (port 47992 → Pairing) — no PIN needed. Or "
                 + "pair with the 4-digit PIN it can display.")
         }
         // One "Connection failed" surface for every home screen (touch grid, gamepad launcher) and
@@ -335,7 +343,7 @@ struct ContentView: View {
             Button("Cancel", role: .cancel) { model.disconnect() }
         } message: { req in
             Text("Approve \u{201C}\(localDeviceName)\u{201D} in \(req.host.displayName)'s web "
-                + "console (port 3000 → Pairing). This device connects automatically once you "
+                + "console (port 47992 → Pairing). This device connects automatically once you "
                 + "approve it — no need to reconnect.")
         }
         // Informational deep-link outcome (unknown host / already streaming). Not an error.
@@ -492,12 +500,19 @@ struct ContentView: View {
                 }
                 // The resize spinner rides over the (blurred) stream; suppressed under the trust
                 // prompt, which owns the screen. It never hit-tests, so window-drag resizes keep
-                // steering and the next click still reaches the stream.
+                // steering and the next click still reaches the stream. Mounted ONLY while a
+                // resize is live: resident structure above the CAMetalLayer is what the stage-4
+                // direct-to-display hunt is eliminating — composited presents reach glass a full
+                // refresh later. The enter/exit fade rides the call-site transition + the
+                // .animation(value: resizing) below (the view's internal `if active` fade can't
+                // run when the whole view unmounts).
                 .overlay {
-                    if pendingFingerprint == nil {
-                        ResizeIndicatorView(active: model.resizing)
+                    if pendingFingerprint == nil, model.resizing {
+                        ResizeIndicatorView(active: true)
+                            .transition(.opacity.combined(with: .scale(scale: 0.92)))
                     }
                 }
+                .animation(.easeInOut(duration: 0.22), value: model.resizing)
             if let fp = pendingFingerprint {
                 TrustCardView(
                     fingerprint: fp,
@@ -587,7 +602,8 @@ struct ContentView: View {
                     },
                     endToEndMeter: model.endToEnd,
                     decodeMeter: model.decodeStage,
-                    displayMeter: model.displayStage
+                    displayMeter: model.displayStage,
+                    presentFloorMeter: model.presentFloor
                 )
                 .overlay(alignment: placement.alignment) {
                     // The stats overlay MORPHS between tiers and SCALES UP on enter. With no `.id`, a
@@ -636,18 +652,27 @@ struct ContentView: View {
                 #if os(iOS)
                 // Touch users have no menu / ⌘D, so when the HUD's Disconnect button isn't on
                 // screen — the overlay off, or the compact pill (which carries no button) —
-                // keep a minimal always-reachable exit in a corner. It rides a material disc
-                // (like the HUD) so the glyph stays legible over a bright frame — this is the
-                // sole touch disconnect path in those tiers.
+                // keep a minimal touch exit in a corner. It rides a material disc (like the
+                // HUD) so the glyph stays legible over a bright frame.
+                //
+                // In the OFF tier the disc shows for the first 8 s of a session, then leaves
+                // the hierarchy ENTIRELY (the shortcut-banner pattern): any composited overlay
+                // above the stream — a glass one doubly so, its blur SAMPLES the video layer —
+                // forces the CAMetalLayer through the compositor, costing ~a refresh of display
+                // latency and blocking direct-to-display promotion. Off is the immersive/
+                // measurement tier; after the fade, touch-only exits are backgrounding the app
+                // or re-enabling the stats overlay. Compact keeps its disc permanently — that
+                // tier composites a HUD pill anyway, so hiding the exit there wins nothing.
                 .overlay(alignment: .topLeading) {
-                    if captureEnabled && (statsVerbosity == .off || statsVerbosity == .compact) {
+                    if captureEnabled,
+                       statsVerbosity == .compact || (statsVerbosity == .off && showTouchExit) {
                         Button { model.disconnect() } label: {
                             Image(systemName: "xmark")
                                 .font(.headline.weight(.semibold))
                                 .frame(width: 36, height: 36)
-                                // Sole touch exit in the off/compact tiers — a floating glass disc
-                                // over the frame (26+, material fallback). interactive: the disc
-                                // IS the tap target, so the glass reacts to press.
+                                // Floating glass disc over the frame (26+, material fallback).
+                                // interactive: the disc IS the tap target, so the glass reacts
+                                // to press.
                                 .glassBackground(Circle(), interactive: true)
                                 // Match the hit region to the visible disc so every tap also
                                 // triggers the interactive-glass press highlight.
@@ -656,6 +681,12 @@ struct ContentView: View {
                         .buttonStyle(.plain)
                         .padding(12)
                         .accessibilityLabel("Disconnect")
+                        .transition(.opacity)
+                        .task {
+                            guard statsVerbosity == .off else { return }
+                            try? await Task.sleep(for: .seconds(8))
+                            withAnimation(.easeOut(duration: 0.6)) { showTouchExit = false }
+                        }
                     }
                 }
                 #endif

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

@@ -102,6 +102,20 @@ final class SessionModel: ObservableObject {
     @Published var decodeValid = false
     @Published var displayP50Ms = 0.0
     @Published var displayValid = false
+    /// The measured OS present floor (design/apple-presentation-rebuild.md): the deadline
+    /// engine's vend→glass pipeline depth — an OS property no client can pace under (~2 refresh
+    /// intervals composited; would read ~1 under direct-to-display). The HUD subtracts it from
+    /// the shown display/e2e so the numbers describe Punktfunk's own pipeline; raw values stay
+    /// in the detailed tier + the stats log. Invalid (0) on macOS arrival (sync-off ≈ no floor)
+    /// and under stage-1.
+    @Published var osFloorP50Ms = 0.0
+    @Published var osFloorValid = false
+
+    /// The floor-shaved values every HUD tier displays (raw − floor, never below 0). Identical
+    /// to the raw values whenever no floor is measured.
+    var displayAdjP50Ms: Double { max(0, displayP50Ms - (osFloorValid ? osFloorP50Ms : 0)) }
+    var endToEndAdjP50Ms: Double { max(0, endToEndP50Ms - (osFloorValid ? osFloorP50Ms : 0)) }
+    var endToEndAdjP95Ms: Double { max(0, endToEndP95Ms - (osFloorValid ? osFloorP50Ms : 0)) }
     /// Unrecoverable network frame drops in the last window (FEC couldn't rebuild them) and their
     /// share of frames offered, `lost/(received+lost)`. The HUD hides the line while zero.
     @Published var lostFrames = 0
@@ -133,6 +147,9 @@ final class SessionModel: ObservableObject {
     let endToEnd = LatencyMeter()
     let decodeStage = LatencyMeter()
     let displayStage = LatencyMeter()
+    /// The OS present floor sampler (see `osFloorP50Ms`) — fed one sample per display-link
+    /// update by the deadline engine, drained by the same 1 s tick as the stage meters.
+    let presentFloor = LatencyMeter()
     /// Cumulative reassembler-drop counter at the last stats drain (per-window `lost` delta).
     private var lastFramesDropped: UInt64 = 0
     private var statsTimer: Timer?
@@ -210,7 +227,13 @@ final class SessionModel: ObservableObject {
         // metadata we apply (Step 2) when it IS HDR.
         let displayHDR: Bool = {
             #if os(macOS)
-                return (NSScreen.main?.maximumExtendedDynamicRangeColorComponentValue ?? 1.0) > 1.0
+                // POTENTIAL, not current, headroom: `maximumExtendedDynamicRangeColorComponentValue`
+                // is the CURRENTLY-ALLOCATED headroom, which macOS hands out on demand — on an idle
+                // SDR desktop it reads 1.0 even with HDR enabled and active (external HDR displays
+                // like the Samsung G95SC allocate EDR only when content asks). Gating on it means an
+                // HDR monitor never gets advertised at connect time. `maximumPotential…` is the
+                // mode-independent capability (the macOS analogue of the tvOS/iOS gates below).
+                return (NSScreen.main?.maximumPotentialExtendedDynamicRangeColorComponentValue ?? 1.0) > 1.0
             #elseif os(tvOS)
                 // NOT the EDR headroom here: on tvOS that reflects the CURRENT output mode, and
                 // Apple's recommended setup runs an SDR home screen with Match Content — an
@@ -264,14 +287,11 @@ final class SessionModel: ObservableObject {
             // PyroWave (wired LAN) is a pure opt-in: picking it in the codec setting both
             // advertises the bit and prefers it — the host never auto-selects it, and the
             // picker only offers it when the Metal decode probe passed (simdgroup floor ≈ A13;
-            // every M-series Mac and the ATV 4K gen 3 pass). The codec is 8-bit 4:2:0 SDR
-            // BT.709 by contract, so the opt-in also drops the HDR/10-bit/4:4:4 caps for this
-            // session — HDR sessions stay HEVC/AV1 (plan §4.7).
+            // every M-series Mac and the ATV 4K gen 3 pass). The decoder self-configures from
+            // the per-frame sequence header (4:2:0/4:4:4, SDR/PQ — design/pyrowave-444-hdr.md),
+            // so the session keeps the user's HDR/10-bit/4:4:4 caps exactly like HEVC/AV1.
             if preferredCodec == PunktfunkConnection.codecPyroWave, MetalWaveletDecoder.supported {
                 videoCodecs |= PunktfunkConnection.codecPyroWave
-                videoCaps &= ~(PunktfunkConnection.videoCap10Bit
-                    | PunktfunkConnection.videoCapHDR
-                    | PunktfunkConnection.videoCap444)
             }
             let result = Result { try PunktfunkConnection(
                 host: host.address, port: host.port,
@@ -335,7 +355,7 @@ final class SessionModel: ObservableObject {
                         // operator didn't approve it before the host's park window elapsed (or
                         // the host was unreachable).
                         self.errorMessage = "\(host.displayName) didn't let this device in. "
-                            + "Approve it in the host's web console (port 3000 → Pairing), then "
+                            + "Approve it in the host's web console (port 47992 → Pairing), then "
                             + "request access again — the request expires after a few minutes."
                     } else {
                         self.errorMessage = pin != nil
@@ -469,6 +489,7 @@ final class SessionModel: ObservableObject {
         endToEndValid = false
         decodeValid = false
         displayValid = false
+        osFloorValid = false
         lostFrames = 0
         lostPct = 0
         mouseCaptured = false
@@ -652,15 +673,25 @@ final class SessionModel: ObservableObject {
                 } else {
                     self.displayValid = false
                 }
+                if let f = self.presentFloor.drain() {
+                    self.osFloorP50Ms = f.p50Ms
+                    self.osFloorValid = true
+                } else {
+                    self.osFloorValid = false
+                }
                 // Mirror the window to the unified log (see statsLog) — one line per second,
                 // stages in ms, only while frames actually flowed. `fps` counts RECEIVED AUs;
                 // `presents` counts frames that reached glass (the display meter's sample count)
                 // — a presents≪fps gap is the presenter dropping/serializing, an fps deficit is
                 // upstream (host capture/encode or the network).
                 if frames > 0 {
+                    // The classic fields stay RAW (cross-session comparability with every log
+                    // captured before the 2026-07 floor policy); the appended trio carries the
+                    // measured OS present floor and the floor-shaved values the HUD displays.
                     let line = String(
                         format: "fps=%d presents=%d e2e_p50=%.1f e2e_p95=%.1f hostnet_p50=%.1f "
-                            + "decode_p50=%.1f display_p50=%.1f lost=%d",
+                            + "decode_p50=%.1f display_p50=%.1f lost=%d "
+                            + "floor_p50=%.1f display_adj=%.1f e2e_adj=%.1f",
                         frames,
                         displayWindow?.count ?? 0,
                         self.endToEndValid ? self.endToEndP50Ms : -1,
@@ -668,7 +699,10 @@ final class SessionModel: ObservableObject {
                         self.hostNetworkValid ? self.hostNetworkP50Ms : -1,
                         self.decodeValid ? self.decodeP50Ms : -1,
                         self.displayValid ? self.displayP50Ms : -1,
-                        lost)
+                        lost,
+                        self.osFloorValid ? self.osFloorP50Ms : -1,
+                        self.displayValid ? self.displayAdjP50Ms : -1,
+                        self.endToEndValid ? self.endToEndAdjP50Ms : -1)
                     statsLog.info("\(line, privacy: .public)")
                 }
             }

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

@@ -65,7 +65,9 @@ struct StreamHUDView: View {
     private var compactLine: String {
         var parts = ["\(model.fps) fps"]
         if model.endToEndValid {
-            parts.append(String(format: "%.1f ms", model.endToEndP50Ms))
+            // Floor-shaved (design/apple-presentation-rebuild.md): the OS present pipeline's
+            // fixed depth is excluded, so the headline describes Punktfunk's own latency.
+            parts.append(String(format: "%.1f ms", model.endToEndAdjP50Ms))
         } else if model.hostNetworkValid {
             parts.append(String(format: "%.1f ms", model.hostNetworkP50Ms))
         }
@@ -86,24 +88,36 @@ struct StreamHUDView: View {
             }
             if model.endToEndValid {
                 // Stage-2: the end-to-end headline (capture→on-glass, measured directly, skew-
-                // corrected) — "(same-host clock)" when the host didn't answer the skew handshake.
-                Text("end-to-end \(model.endToEndP50Ms, specifier: "%.1f") ms p50 · \(model.endToEndP95Ms, specifier: "%.1f") p95 · capture→on-glass\(model.endToEndSkewCorrected ? "" : " (same-host clock)")")
+                // corrected) — "(same-host clock)" when the host didn't answer the skew
+                // handshake. FLOOR-SHAVED (design/apple-presentation-rebuild.md): the OS present
+                // pipeline's fixed depth is excluded so the number describes Punktfunk's own
+                // latency; the detailed tier shows the excluded floor as its own line, and the
+                // stats log keeps the raw values.
+                Text("end-to-end \(model.endToEndAdjP50Ms, specifier: "%.1f") ms p50 · \(model.endToEndAdjP95Ms, specifier: "%.1f") p95 · capture→on-glass\(model.endToEndSkewCorrected ? "" : " (same-host clock)")")
                     .font(.system(.caption2, design: .monospaced))
                     .foregroundStyle(.secondary)
                 // The equation (detailed tier only): the stages tiling the headline interval
                 // (per-window p50s — they only approximately sum to the directly-measured
                 // total). With a host that reports per-AU timings (0xCF) the first term splits
-                // into host + network (phase 2); an old host keeps the combined term.
+                // into host + network (phase 2); an old host keeps the combined term. The
+                // display term is floor-shaved like the headline, so the equation still sums.
                 if verbosity == .detailed && model.hostNetworkValid && model.decodeValid && model.displayValid {
                     if model.splitValid {
-                        Text("= host \(model.hostP50Ms, specifier: "%.1f") + network \(model.networkP50Ms, specifier: "%.1f") + decode \(model.decodeP50Ms, specifier: "%.1f") + display \(model.displayP50Ms, specifier: "%.1f")")
+                        Text("= host \(model.hostP50Ms, specifier: "%.1f") + network \(model.networkP50Ms, specifier: "%.1f") + decode \(model.decodeP50Ms, specifier: "%.1f") + display \(model.displayAdjP50Ms, specifier: "%.1f")")
                             .font(.system(.caption2, design: .monospaced))
                             .foregroundStyle(.secondary)
                     } else {
-                        Text("= host+network \(model.hostNetworkP50Ms, specifier: "%.1f") + decode \(model.decodeP50Ms, specifier: "%.1f") + display \(model.displayP50Ms, specifier: "%.1f")")
+                        Text("= host+network \(model.hostNetworkP50Ms, specifier: "%.1f") + decode \(model.decodeP50Ms, specifier: "%.1f") + display \(model.displayAdjP50Ms, specifier: "%.1f")")
                             .font(.system(.caption2, design: .monospaced))
                             .foregroundStyle(.secondary)
                     }
+                    if model.osFloorValid {
+                        // The excluded OS term, kept visible for honesty: display-pipeline
+                        // minimum no client can pace under (~2 refresh intervals composited).
+                        Text("os present +\(model.osFloorP50Ms, specifier: "%.1f") excluded (display pipeline minimum)")
+                            .font(.system(.caption2, design: .monospaced))
+                            .foregroundStyle(.tertiary)
+                    }
                 }
             } else if model.hostNetworkValid {
                 // Stage-1 fallback presenter: the layer decodes + presents internally with no

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

@@ -40,7 +40,9 @@ struct GamepadSettingsView: View {
     @AppStorage(DefaultsKey.libraryEnabled) private var libraryEnabled = true
     @AppStorage(DefaultsKey.gamepadUIEnabled) private var gamepadUIEnabled = true
     @AppStorage(DefaultsKey.autoWake) private var autoWakeEnabled = true
-    @AppStorage(DefaultsKey.presenter) private var presenter = SettingsOptions.presenterDefault
+    @AppStorage(DefaultsKey.presentPriority) private var presentPriority =
+        SettingsOptions.presentPriorityDefault
+    @AppStorage(DefaultsKey.smoothBuffer) private var smoothBuffer = 0
     #if os(iOS)
     @AppStorage(DefaultsKey.rumbleOnDevice) private var rumbleOnDevice = false
     #endif
@@ -288,11 +290,19 @@ struct GamepadSettingsView: View {
                     + "hardware decode.",
                 value: $enable444),
             choiceRow(
-                id: "presenter", icon: "rectangle.stack", label: "Presenter",
-                detail: "Stage 3 paces presents to the display — lowest display latency. "
-                    + "Stage 2 shows each frame on arrival. Applies from the next session.",
-                options: SettingsOptions.presenters, current: presenter
-            ) { presenter = $0 },
+                id: "presentPriority", icon: "rectangle.stack", label: "Prioritize",
+                detail: "Lowest latency shows each frame the moment the display can take it; "
+                    + "Smoothness buffers a few frames to even out network hiccups. Applies "
+                    + "from the next session.",
+                options: SettingsOptions.presentPriorities, current: presentPriority
+            ) { presentPriority = $0 },
+            choiceRow(
+                id: "smoothBuffer", icon: "square.stack.3d.up", label: "Smoothness buffer",
+                detail: "How many frames Smoothness holds — each adds about a refresh of "
+                    + "display latency and absorbs about a refresh of jitter. Only applies "
+                    + "when prioritizing smoothness.",
+                options: SettingsOptions.smoothBuffers(refreshHz: hz), current: smoothBuffer
+            ) { smoothBuffer = $0 },
 
             choiceRow(
                 id: "audio", header: "Audio", icon: "speaker.wave.2", label: "Audio channels",

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

@@ -8,7 +8,10 @@ import SwiftUI
 /// drives the detail pane; on iPhone the same list collapses to pushed sub-pages. Internal (not
 /// private) so the screenshot harness can open SettingsView on a specific category.
 enum SettingsCategory: String, CaseIterable, Identifiable {
-    case general, display, audio, controllers, advanced, about
+    // The 2026-07 revamp's map: General = session/app behavior, Display = everything about the
+    // picture (resolution, quality, presentation, host output), Input = touch/keyboard/mouse.
+    // The old Advanced tab dissolved (its lone game-library toggle lives in General now).
+    case general, display, input, audio, controllers, about
 
     var id: Self { self }
 
@@ -16,9 +19,9 @@ enum SettingsCategory: String, CaseIterable, Identifiable {
         switch self {
         case .general: return "General"
         case .display: return "Display"
+        case .input: return "Input"
         case .audio: return "Audio"
         case .controllers: return "Controllers"
-        case .advanced: return "Advanced"
         case .about: return "About"
         }
     }
@@ -27,9 +30,9 @@ enum SettingsCategory: String, CaseIterable, Identifiable {
         switch self {
         case .general: return "gearshape"
         case .display: return "display"
+        case .input: return "keyboard"
         case .audio: return "speaker.wave.2"
         case .controllers: return "gamecontroller"
-        case .advanced: return "slider.horizontal.3"
         case .about: return "info.circle"
         }
     }

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

@@ -37,28 +37,31 @@ enum SettingsOptions {
     static let hudPlacements: [(label: String, tag: String)] =
         HUDPlacement.allCases.map { ($0.label, $0.rawValue) }
 
-    /// Stage-2 vs stage-3 present pacing (`DefaultsKey.presenter` — see SessionPresenter's
-    /// PresenterChoice); the freeze-prone stage-1 diagnostic only ships in DEBUG builds.
-    static var presenters: [(label: String, tag: String)] {
-        var options: [(label: String, tag: String)] = [
-            ("Stage 2", "stage2"),
-            ("Stage 3", "stage3"),
-        ]
-        #if DEBUG
-        options.append(("Stage 1 (debug)", "stage1"))
-        #endif
-        return options
-    }
+    /// Presentation intent (`DefaultsKey.presentPriority` — the 2026-07 rebuild that replaced
+    /// the visible stage picker with intent; see SessionPresenter's PresentPriority and
+    /// design/apple-presentation-rebuild.md). The stage ladder survives only as the hidden
+    /// PUNKTFUNK_PRESENTER debug env lever.
+    static let presentPriorities: [(label: String, tag: String)] = [
+        ("Lowest latency", "latency"),
+        ("Smoothness", "smooth"),
+    ]
+    static let presentPriorityDefault = "latency"
 
-    /// The platform's presenter default (mirrors SessionPresenter's platformDefault — tvOS runs
-    /// glass pacing, everything else arrival). Views seed their @AppStorage display from this so
-    /// an untouched picker shows what actually runs.
-    static var presenterDefault: String {
-        #if os(tvOS)
-        "stage3"
-        #else
-        "stage2"
-        #endif
+    /// Smoothness's jitter-buffer sizes (`DefaultsKey.smoothBuffer`; 0 = Automatic, currently 2
+    /// frames). The ms hints derive from the chosen refresh setting — each buffered frame costs
+    /// about one refresh interval of display latency and absorbs about one interval of arrival
+    /// jitter.
+    static func smoothBuffers(refreshHz: Int) -> [(label: String, tag: Int)] {
+        let periodMs = 1000.0 / Double(max(24, refreshHz))
+        func hint(_ frames: Int) -> String {
+            String(format: "+%.0f ms", Double(frames) * periodMs)
+        }
+        return [
+            ("Automatic", 0),
+            ("1 frame (\(hint(1)))", 1),
+            ("2 frames (\(hint(2)))", 2),
+            ("3 frames (\(hint(3)))", 3),
+        ]
     }
 
     /// Stats-overlay tiers (`DefaultsKey.statsVerbosity`) — the `tag` is the raw value.

clients/apple/Sources/PunktfunkClient/Settings/SettingsView+Sections.swift

@@ -1,5 +1,15 @@
 // SettingsView's shared sections — each setting's Section is defined exactly once here and
 // composed by the per-platform bodies in SettingsView.swift.
+//
+// 2026-07 settings revamp: every field carries its explanation DIRECTLY under it in the same
+// cell (the `described` helper in SettingsView+Support) — the old per-section footer paragraphs
+// collected several fields' explanations into one blob nobody could match back to its row.
+// Where a picker's meaning depends on the selection (touch mode, modifier layout, prioritize),
+// the description is DYNAMIC — it explains the current choice. The only footers left are the
+// one-line "Applies from the next session." form notes.
+//
+// Category map (SettingsCategory): General = session/app behavior, Display = everything about
+// the picture (resolution lives HERE), Input = touch/keyboard/mouse, Audio, Controllers, About.
 
 #if os(iOS)
 import CoreHaptics
@@ -8,18 +18,23 @@ import PunktfunkKit
 import SwiftUI
 
 extension SettingsView {
-    // MARK: - Sections (shared)
+    // MARK: - Display: Resolution
 
     // NOTE: the Section content is deliberately split into the small named builders below — as one
     // inline expression the iOS branch (wheel + 3-way refresh + bitrate rows) blew Swift's
     // type-checker budget ("unable to type-check this expression in reasonable time"), which
     // failed exactly one slice: the iOS archive (macOS/tvOS never compile that branch).
-    @ViewBuilder var streamModeSection: some View {
-        Section {
+    @ViewBuilder var resolutionSection: some View {
+        Section("Resolution") {
             #if os(iOS) || os(macOS)
             // Match-window (design/midstream-resolution-resize.md D1): follow the session
             // window/scene, renegotiating the host mode on a resize. Off → the explicit mode below.
-            Toggle("Match window", isOn: $matchWindow)
+            described(matchWindow
+                ? "The host resizes its output to follow this window — the picture stays "
+                    + "pixel-exact (1:1) through every resize."
+                : "Stream at the fixed mode below; a window at a different size shows it scaled.") {
+                Toggle("Match window", isOn: $matchWindow)
+            }
             #endif
             #if os(iOS)
             iosResolutionWheel
@@ -32,75 +47,19 @@ extension SettingsView {
                 TextField("", value: $height, format: .number.grouping(.never))
                     .labelsHidden()
             }
-            TextField("Refresh rate (Hz)", value: $hz, format: .number.grouping(.never))
+            described("The host drives a real virtual output at exactly this size and refresh — "
+                + "true pixels, no scaling.") {
+                TextField("Refresh rate (Hz)", value: $hz, format: .number.grouping(.never))
+            }
             LabeledContent("") {
                 Button("Use this display's mode") { fillFromMainScreen() }
             }
             #endif
-            #if !os(tvOS)
-            renderScaleRow
-            bitrateRows
-            #endif
-        } header: {
-            Text("Stream mode")
-        } footer: {
-            Text(matchWindow
-                ? "The stream follows this window — the host resizes its virtual output to match "
-                    + "as you resize, so the picture stays pixel-exact (1:1) with no scaling. "
-                    + "\(Self.bitrateFooter)"
-                : "The host creates a virtual output at exactly this mode — native resolution, but "
-                    + "a window that isn't this size is scaled to fit. \(Self.bitrateFooter)")
-                .font(.geist(12, relativeTo: .caption))
-                .foregroundStyle(.secondary)
         }
     }
 
-    #if !os(tvOS)
-    /// Render-scale picker + the resulting host resolution. > 1 supersamples (sharper, at more
-    /// bandwidth AND client decode); < 1 renders under native (lighter). The presenter resamples the
-    /// decoded frame to this display, so the multiplier is where the sharpness/cost trade-off lives.
-    @ViewBuilder var renderScaleRow: some View {
-        Picker("Render scale", selection: $renderScale) {
-            ForEach(RenderScale.presets, id: \.self) { scale in
-                Text(RenderScale.label(scale)).tag(scale)
-            }
-        }
-        // The concrete host resolution makes the cost legible. Only meaningful for the explicit mode
-        // (match-window derives the base from the live window, not these fields).
-        if renderScale != 1.0, !matchWindow {
-            let mode = RenderScale.apply(
-                baseWidth: width, baseHeight: height,
-                scale: renderScale,
-                maxDimension: RenderScale.maxDimension(codec: codec))
-            Text("Host renders \(Int(mode.width))×\(Int(mode.height)); this device downscales it to your display.")
-                .font(.geist(12, relativeTo: .caption))
-                .foregroundStyle(.secondary)
-        }
-    }
-
-    /// Keyboard & mouse forwarding — applies wherever a hardware keyboard/mouse drives the stream
-    /// (always on macOS; an attached keyboard/mouse on iPad). Absent on tvOS (no such input path).
-    @ViewBuilder var inputSection: some View {
-        Section {
-            Picker("Modifier keys", selection: $modifierLayout) {
-                ForEach(ModifierLayout.allCases, id: \.self) { layout in
-                    Text(layout.label).tag(layout.rawValue)
-                }
-            }
-            Toggle("Invert scroll direction", isOn: $invertScroll)
-        } header: {
-            Text("Keyboard & mouse")
-        } footer: {
-            Text((ModifierLayout(rawValue: modifierLayout) ?? .mac).detail
-                + " Invert scroll reverses the wheel/trackpad scroll direction sent to the host.")
-                .font(.geist(12, relativeTo: .caption))
-                .foregroundStyle(.secondary)
-        }
-    }
-    #endif
-
     #if os(iOS)
-    // MARK: - Stream mode (iOS wheel)
+    // MARK: - Display: Resolution (iOS wheel)
 
     /// Touch-first: a rotating wheel of common resolutions (this device's own mode first) — the
     /// same family as the Clock/Timer pickers. The host renders a virtual output at exactly the
@@ -119,6 +78,11 @@ extension SettingsView {
             .labelsHidden()
             .pickerStyle(.wheel)
             .frame(maxHeight: 140)
+            Text("The host drives a real output at exactly this mode — true pixels, no scaling.")
+                .font(.geist(13, relativeTo: .footnote))
+                .foregroundStyle(.secondary)
+                .fixedSize(horizontal: false, vertical: true)
+                .frame(maxWidth: 360, alignment: .leading) // match the described-row caption cap
         }
     }
 
@@ -210,10 +174,69 @@ extension SettingsView {
     }
     #endif
 
+    // MARK: - Display: Quality
+
+    @ViewBuilder var qualitySection: some View {
+        Section("Quality") {
+            #if !os(tvOS)
+            renderScaleRow
+            bitrateRows
+            #endif
+            described("A preference — the host falls back if it can't encode it.") {
+                Picker("Video codec", selection: $codec) {
+                    ForEach(SettingsOptions.codecs, id: \.tag) { option in
+                        Text(option.label).tag(option.tag)
+                    }
+                }
+            }
+            described("HDR10, when the host has HDR content and this display supports it. "
+                + "HEVC only; otherwise the stream stays SDR.") {
+                Toggle("10-bit HDR", isOn: $hdrEnabled)
+            }
+            described("Sharper text and UI for desktop work, at more bandwidth. For games the "
+                + "bits are better spent at 4:2:0. HEVC only.") {
+                Toggle("Full chroma (4:4:4)", isOn: $enable444)
+            }
+        }
+    }
+
     #if !os(tvOS)
+    /// Render-scale picker + the resulting host resolution. > 1 supersamples (sharper, at more
+    /// bandwidth AND client decode); < 1 renders under native (lighter). The presenter resamples the
+    /// decoded frame to this display, so the multiplier is where the sharpness/cost trade-off lives.
+    @ViewBuilder var renderScaleRow: some View {
+        described(renderScaleDescription) {
+            Picker("Render scale", selection: $renderScale) {
+                ForEach(RenderScale.presets, id: \.self) { scale in
+                    Text(RenderScale.label(scale)).tag(scale)
+                }
+            }
+        }
+    }
+
+    /// Render scale explained, with the CONCRETE host resolution when it applies — the cost made
+    /// legible. Only the explicit mode can show it (match-window derives the base from the live
+    /// window, not these fields).
+    private var renderScaleDescription: String {
+        var text = "Above native supersamples for sharpness; below renders lighter on the host "
+            + "and the link."
+        if renderScale != 1.0, !matchWindow {
+            let mode = RenderScale.apply(
+                baseWidth: width, baseHeight: height,
+                scale: renderScale,
+                maxDimension: RenderScale.maxDimension(codec: codec))
+            text += " Host renders \(Int(mode.width))×\(Int(mode.height)); this device scales "
+                + "it to your display."
+        }
+        return text
+    }
+
     /// The automatic-bitrate toggle + manual slider (and the >1 Gbps warning) rows.
     @ViewBuilder private var bitrateRows: some View {
-        Toggle("Automatic bitrate", isOn: automaticBitrate)
+        described("The host's default 20 Mbps, clamped to what it supports. Turn off to set a "
+            + "fixed rate — a host card's context menu has a network speed test.") {
+            Toggle("Automatic bitrate", isOn: automaticBitrate)
+        }
         if bitrateKbps != 0 {
             HStack(spacing: 12) {
                 Slider(value: bitrateSlider, in: 0...1) {
@@ -233,26 +256,228 @@ extension SettingsView {
     }
     #endif
 
-    @ViewBuilder var audioSection: some View {
-        Section {
-            Picker("Audio channels", selection: $audioChannels) {
-                ForEach(SettingsOptions.audioChannels, id: \.tag) { option in
-                    Text(option.label).tag(option.tag)
+    // MARK: - Display: Presentation
+
+    // The presentation intent (design/apple-presentation-rebuild.md — replaced the visible
+    // stage picker): latency (newest-wins, zero queue) vs smoothness (a small deliberate jitter
+    // buffer). The stage ladder survives only as the hidden PUNKTFUNK_PRESENTER debug env lever.
+    @ViewBuilder var presentationSection: some View {
+        Section("Presentation") {
+            described(presentPriority == "smooth"
+                ? "A small frame buffer evens out network hiccups, at the buffer's worth of "
+                    + "added display latency."
+                : "Every frame shows the moment the display can take it — a network hiccup is "
+                    + "an occasional repeated or skipped frame.") {
+                Picker("Prioritize", selection: $presentPriority) {
+                    ForEach(SettingsOptions.presentPriorities, id: \.tag) { option in
+                        Text(option.tag == SettingsOptions.presentPriorityDefault
+                            ? "\(option.label) (default)" : option.label)
+                            .tag(option.tag)
+                    }
                 }
             }
-            #if os(macOS)
-            Picker("Speaker", selection: $speakerUID) {
-                Text("System default").tag("")
-                ForEach(outputDevices) { device in
-                    Text(device.name).tag(device.uid)
+            if presentPriority == "smooth" {
+                described("Frames held back — each absorbs about one refresh of jitter and "
+                    + "adds one refresh of delay.") {
+                    Picker("Buffer", selection: $smoothBuffer) {
+                        ForEach(SettingsOptions.smoothBuffers(refreshHz: hz), id: \.tag) { option in
+                            Text(option.label).tag(option.tag)
+                        }
+                    }
                 }
-                if !speakerUID.isEmpty,
-                   !outputDevices.contains(where: { $0.uid == speakerUID }) {
-                    Text("Unavailable device").tag(speakerUID)
+            }
+            // Non-tvOS: the Apple TV drives a fixed HDMI mode, so there's no adaptive refresh.
+            #if !os(tvOS)
+            described("A ProMotion or adaptive-sync display follows the stream's rate — "
+                + "smoother motion. No effect on fixed-refresh displays.") {
+                Toggle("Allow VRR", isOn: $allowVRR)
+            }
+            #endif
+            // macOS-only: iOS/tvOS layers always present on the display's vsync, so the choice
+            // only exists on the Mac (the layer's own sync stays off — see MetalVideoPresenter).
+            #if os(macOS)
+            described("Flips align to the display's refresh — even pacing, up to one refresh "
+                + "of added latency. Off shows frames as soon as they're ready.") {
+                Toggle("V-Sync", isOn: $vsync)
+            }
+            #endif
+        }
+    }
+
+    // MARK: - Display: Host output
+
+    @ViewBuilder var hostOutputSection: some View {
+        Section {
+            described("The backend the host uses for its virtual output. A specific choice "
+                + "falls back to auto-detection when that backend isn't available.") {
+                Picker("Compositor", selection: $compositor) {
+                    ForEach(SettingsOptions.compositors, id: \.tag) { option in
+                        Text(option.label).tag(option.tag)
+                    }
+                }
+            }
+        } header: {
+            Text("Host output")
+        } footer: {
+            // The one form-level note (deliberately not repeated on every row above).
+            Text("Display changes apply from the next session.")
+                .font(.geist(12, relativeTo: .caption))
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    // MARK: - General: Session
+
+    @ViewBuilder var sessionSection: some View {
+        Section("Session") {
+            #if os(macOS)
+            described("Go fullscreen when a session starts; return to a window on the host "
+                + "list.") {
+                Toggle("Fullscreen while streaming", isOn: $fullscreenWhileStreaming)
+            }
+            #endif
+            described("Connecting to a saved host that's offline sends Wake-on-LAN and waits "
+                + "for it to boot. Turn off if hosts behind a VPN look offline when they "
+                + "aren't.") {
+                Toggle("Auto-wake on connect", isOn: $autoWakeEnabled)
+            }
+            #if os(iOS)
+            described("Audio and the connection stay live after you switch away; video pauses "
+                + "to save power and resumes instantly when you return. Off, backgrounding "
+                + "freezes the session.") {
+                Toggle("Keep streaming in background", isOn: $backgroundKeepAlive)
+            }
+            if backgroundKeepAlive {
+                described("Ends a backgrounded session so it can't run down the battery.") {
+                    Picker("Disconnect after", selection: $backgroundTimeoutMinutes) {
+                        Text("1 minute").tag(1)
+                        Text("5 minutes").tag(5)
+                        Text("10 minutes").tag(10)
+                        Text("30 minutes").tag(30)
+                    }
                 }
             }
             #endif
-            Toggle("Send microphone to the host", isOn: $micEnabled)
+        }
+    }
+
+    // MARK: - General: Statistics overlay
+
+    @ViewBuilder var overlaySection: some View {
+        Section("Statistics") {
+            described(Self.statisticsDescription) {
+                Picker("Statistics overlay", selection: $statsVerbosityRaw) {
+                    ForEach(StatsVerbosity.allCases, id: \.rawValue) { tier in
+                        Text(tier.label).tag(tier.rawValue)
+                    }
+                }
+            }
+            Picker("Position", selection: $hudPlacement) {
+                ForEach(HUDPlacement.allCases) { placement in
+                    Text(placement.label).tag(placement.rawValue)
+                }
+            }
+            .disabled(statsVerbosityRaw == StatsVerbosity.off.rawValue)
+        }
+    }
+
+    // MARK: - General: Library
+
+    @ViewBuilder var librarySection: some View {
+        Section("Library") {
+            described("Adds “Browse Library…” to paired hosts — list their Steam and custom "
+                + "games and launch one directly. No extra host setup.") {
+                Toggle("Show game library", isOn: $libraryEnabled)
+            }
+        }
+    }
+
+    // MARK: - Input
+
+    #if os(iOS)
+    /// Touch-input model (iPhone + iPad) plus the iPad-only pointer-capture toggle: lock the
+    /// mouse/trackpad for relative movement (games) vs forward an absolute cursor position.
+    @ViewBuilder var pointerSection: some View {
+        Section("Touch & pointer") {
+            described(touchModeDescription) {
+                Picker("Touch input", selection: $touchMode) {
+                    Text("Trackpad").tag(TouchInputMode.trackpad.rawValue)
+                    Text("Direct pointer").tag(TouchInputMode.pointer.rawValue)
+                    Text("Touch passthrough").tag(TouchInputMode.touch.rawValue)
+                }
+            }
+            if UIDevice.current.userInterfaceIdiom == .pad {
+                described("Locks a hardware mouse for relative mouse-look in games; off sends "
+                    + "absolute positions. Needs the stream fullscreen and frontmost.") {
+                    Toggle("Capture pointer for games", isOn: $pointerCapture)
+                }
+            }
+        }
+    }
+
+    /// The SELECTED touch mode explained — dynamic, so the caption always describes what the
+    /// picker currently does instead of narrating all three modes at once.
+    private var touchModeDescription: String {
+        switch TouchInputMode(rawValue: touchMode) ?? .trackpad {
+        case .trackpad:
+            return "Your finger drives the host cursor like a laptop trackpad — tap to click, "
+                + "two-finger tap right-clicks, two-finger drag scrolls, tap-and-drag holds."
+        case .pointer:
+            return "The host cursor jumps to wherever you touch — tap is a click at that spot."
+        case .touch:
+            return "Real multi-touch reaches the host — for touch-native apps and games."
+        }
+    }
+    #endif
+
+    #if !os(tvOS)
+    /// Keyboard & mouse forwarding — applies wherever a hardware keyboard/mouse drives the stream
+    /// (always on macOS; an attached keyboard/mouse on iPad). Absent on tvOS (no such input path).
+    @ViewBuilder var inputSection: some View {
+        Section("Keyboard & mouse") {
+            described((ModifierLayout(rawValue: modifierLayout) ?? .mac).detail) {
+                Picker("Modifier keys", selection: $modifierLayout) {
+                    ForEach(ModifierLayout.allCases, id: \.self) { layout in
+                        Text(layout.label).tag(layout.rawValue)
+                    }
+                }
+            }
+            described("Reverses the wheel and trackpad scroll direction sent to the host.") {
+                Toggle("Invert scroll direction", isOn: $invertScroll)
+            }
+        }
+    }
+    #endif
+
+    // MARK: - Audio
+
+    @ViewBuilder var audioSection: some View {
+        Section {
+            described("The speaker layout requested from the host.") {
+                Picker("Audio channels", selection: $audioChannels) {
+                    ForEach(SettingsOptions.audioChannels, id: \.tag) { option in
+                        Text(option.label).tag(option.tag)
+                    }
+                }
+            }
+            #if os(macOS)
+            described("Host audio plays through this device; System default follows your "
+                + "Mac's output changes.") {
+                Picker("Speaker", selection: $speakerUID) {
+                    Text("System default").tag("")
+                    ForEach(outputDevices) { device in
+                        Text(device.name).tag(device.uid)
+                    }
+                    if !speakerUID.isEmpty,
+                       !outputDevices.contains(where: { $0.uid == speakerUID }) {
+                        Text("Unavailable device").tag(speakerUID)
+                    }
+                }
+            }
+            #endif
+            described("This device's microphone feeds the host's virtual mic.") {
+                Toggle("Send microphone to the host", isOn: $micEnabled)
+            }
             #if os(macOS)
             Picker("Microphone", selection: $micUID) {
                 Text("System default").tag("")
@@ -268,264 +493,27 @@ extension SettingsView {
             // Multi-channel interfaces only: the mic sits on ONE discrete input, so let the user
             // pick it. Auto sums every channel (a lone hot mic still passes at full level).
             if micChannelCount > 1 {
-                Picker("Microphone channel", selection: $micChannel) {
-                    Text("Auto (all channels)").tag(0)
-                    ForEach(1...micChannelCount, id: \.self) { ch in
-                        Text("Channel \(ch)").tag(ch)
+                described("Pick the input your mic is on; Auto sums every channel.") {
+                    Picker("Microphone channel", selection: $micChannel) {
+                        Text("Auto (all channels)").tag(0)
+                        ForEach(1...micChannelCount, id: \.self) { ch in
+                            Text("Channel \(ch)").tag(ch)
+                        }
                     }
+                    .disabled(!micEnabled)
                 }
-                .disabled(!micEnabled)
             }
             #endif
         } header: {
             Text("Audio")
         } footer: {
-            Text(Self.audioFooter)
+            Text("Applies from the next session.")
                 .font(.geist(12, relativeTo: .caption))
                 .foregroundStyle(.secondary)
         }
     }
 
-    #if os(iOS)
-    /// Touch-input model (iPhone + iPad) plus the iPad-only pointer-capture toggle: lock the
-    /// mouse/trackpad for relative movement (games) vs forward an absolute cursor position.
-    @ViewBuilder var pointerSection: some View {
-        Section {
-            Picker("Touch input", selection: $touchMode) {
-                Text("Trackpad").tag(TouchInputMode.trackpad.rawValue)
-                Text("Direct pointer").tag(TouchInputMode.pointer.rawValue)
-                Text("Touch passthrough").tag(TouchInputMode.touch.rawValue)
-            }
-            if UIDevice.current.userInterfaceIdiom == .pad {
-                Toggle("Capture pointer for games", isOn: $pointerCapture)
-            }
-        } header: {
-            Text("Touch & pointer")
-        } footer: {
-            Text(pointerFooterText)
-                .font(.geist(12, relativeTo: .caption))
-                .foregroundStyle(.secondary)
-        }
-    }
-
-    /// Footer copy for `pointerSection`, built in plain `+=` statements. Deliberately NOT one big
-    /// `+` chain (with a ternary) inside the ViewBuilder — that single expression blew Swift's
-    /// type-checker budget and was what actually broke the iOS archive.
-    private var pointerFooterText: String {
-        var text = "Trackpad: your finger moves the host cursor like a laptop touchpad — tap "
-        text += "to click, two-finger tap to right-click, two-finger drag to scroll, "
-        text += "tap-and-drag to hold, three-finger tap for the stats overlay. Direct pointer: "
-        text += "the cursor jumps to your finger. Touch passthrough: real multi-touch reaches "
-        text += "the host. Applies from the next touch."
-        if UIDevice.current.userInterfaceIdiom == .pad {
-            text += " Pointer capture locks a hardware mouse for relative mouse-look; off sends "
-            text += "absolute positions. Needs the stream full-screen and frontmost."
-        }
-        return text
-    }
-    #endif
-
-    @ViewBuilder var compositorSection: some View {
-        Section {
-            Picker("Compositor", selection: $compositor) {
-                ForEach(SettingsOptions.compositors, id: \.tag) { option in
-                    Text(option.label).tag(option.tag)
-                }
-            }
-        } header: {
-            Text("Host compositor")
-        } footer: {
-            Text("Which compositor drives the virtual output on the host. A specific "
-                + "choice is honored only if that backend is available there — "
-                + "otherwise the host falls back to auto-detection.")
-                .font(.geist(12, relativeTo: .caption))
-                .foregroundStyle(.secondary)
-        }
-    }
-
-    /// Auto-wake on connect — fire Wake-on-LAN + wait for a sleeping saved host to come back before
-    /// giving up. Now available on every platform (the iOS/tvOS multicast entitlement is granted).
-    @ViewBuilder var wakeSection: some View {
-        Section {
-            Toggle("Auto-wake on connect", isOn: $autoWakeEnabled)
-        } header: {
-            Text("Wake-on-LAN")
-        } footer: {
-            Text("Connecting to a saved host that isn't on the network yet sends a Wake-on-LAN "
-                + "packet and waits for it to come back before streaming. Turn off if a host that's "
-                + "already on just isn't visible here (e.g. over a VPN), so connects go straight "
-                + "through instead of waiting out the wake. A host's “Wake” action still works either "
-                + "way.")
-                .font(.geist(12, relativeTo: .caption))
-                .foregroundStyle(.secondary)
-        }
-    }
-
-    @ViewBuilder var windowSection: some View {
-        #if os(macOS)
-        Section {
-            Toggle("Fullscreen while streaming", isOn: $fullscreenWhileStreaming)
-        } header: {
-            Text("Window")
-        } footer: {
-            Text("Take the window fullscreen when a session starts and restore it on the host "
-                + "list, so only the stream is fullscreen — not the picker.")
-                .font(.geist(12, relativeTo: .caption))
-                .foregroundStyle(.secondary)
-        }
-        #endif
-    }
-
-    // Non-tvOS: the Apple TV drives a fixed HDMI mode, so there's no adaptive refresh to allow.
-    @ViewBuilder var vrrSection: some View {
-        #if !os(tvOS)
-        Section {
-            Toggle("Allow VRR", isOn: $allowVRR)
-        } header: {
-            Text("Variable refresh rate")
-        } footer: {
-            Text("Let a ProMotion or adaptive-sync display vary its refresh rate to match the "
-                + "stream — smoother motion without tearing. No effect on fixed-refresh displays. "
-                + "Applies from the next session.")
-                .font(.geist(12, relativeTo: .caption))
-                .foregroundStyle(.secondary)
-        }
-        #endif
-    }
-
-    // macOS-only: iOS/tvOS layers always present on the display's vsync, so the choice only
-    // exists on the Mac (where the layer's own sync must stay off — see MetalVideoPresenter).
-    @ViewBuilder var vsyncSection: some View {
-        #if os(macOS)
-        Section {
-            Toggle("V-Sync", isOn: $vsync)
-        } header: {
-            Text("Presentation")
-        } footer: {
-            Text("Off (default): each frame is shown as soon as it's ready — lowest latency, "
-                + "but frame timing can look uneven and fullscreen may tear. On: frames flip "
-                + "in step with the display's refresh — evenly paced, up to one refresh of "
-                + "added latency. Applies from the next session.")
-                .font(.geist(12, relativeTo: .caption))
-                .foregroundStyle(.secondary)
-        }
-        #endif
-    }
-
-    // Stage-2 (Metal/VTDecompressionSession, present on frame arrival) is the proven default;
-    // stage-3 is the same pipeline with glass-gated present pacing — a user-visible A/B while the
-    // pacing work settles (see Stage2Pipeline's PresentPacing for the queue-saturation rationale).
-    // Stage-1 (compressed video straight to the system layer) stays a DEBUG-only diagnostic — it
-    // freezes hard on a lost HEVC reference.
-    @ViewBuilder var presenterSection: some View {
-        Section {
-            Picker("Presenter", selection: $presenter) {
-                Text("Stage 2 (default)").tag("stage2")
-                Text("Stage 3 (experimental)").tag("stage3")
-                #if DEBUG
-                Text("Stage 1 (debug)").tag("stage1")
-                #endif
-            }
-        } header: {
-            Text("Video presenter")
-        } footer: {
-            Text("Stage 2: each frame is shown the moment it's decoded — proven, but on displays "
-                + "running near the stream's frame rate, queued frames can add two to three "
-                + "refreshes of display latency that never drains. Stage 3: presents are paced "
-                + "to the display — at most one undisplayed frame in flight, always the freshest, "
-                + "dropping late frames instead of queueing them. Watch the statistics overlay's "
-                + "display time to compare. Applies from the next session.")
-                .font(.geist(12, relativeTo: .caption))
-                .foregroundStyle(.secondary)
-        }
-    }
-
-    @ViewBuilder var hdrSection: some View {
-        Section {
-            Picker("Video codec", selection: $codec) {
-                ForEach(SettingsOptions.codecs, id: \.tag) { option in
-                    Text(option.label).tag(option.tag)
-                }
-            }
-            Toggle("10-bit HDR", isOn: $hdrEnabled)
-            Toggle("Full chroma (4:4:4)", isOn: $enable444)
-        } header: {
-            Text("Video quality")
-        } footer: {
-            Text("Codec is a preference; the host falls back if it can't encode your choice. "
-                + "HDR (HDR10) and full chroma (4:4:4) are HEVC-only, and each engages only when "
-                + "both this device and the host support it — otherwise the stream stays 8-bit "
-                + "4:2:0 SDR. 4:4:4 (off by default) sharpens text and UI — best for desktop "
-                + "work; for games the bits are better spent at 4:2:0. Applies from the next "
-                + "session.")
-                .font(.geist(12, relativeTo: .caption))
-                .foregroundStyle(.secondary)
-        }
-    }
-
-    @ViewBuilder var statisticsSection: some View {
-        Section {
-            Picker("Statistics overlay", selection: $statsVerbosityRaw) {
-                ForEach(StatsVerbosity.allCases, id: \.rawValue) { tier in
-                    Text(tier.label).tag(tier.rawValue)
-                }
-            }
-            Picker("Position", selection: $hudPlacement) {
-                ForEach(HUDPlacement.allCases) { placement in
-                    Text(placement.label).tag(placement.rawValue)
-                }
-            }
-            .disabled(statsVerbosityRaw == StatsVerbosity.off.rawValue)
-        } header: {
-            Text("Statistics")
-        } footer: {
-            Text(Self.statisticsFooter)
-                .font(.geist(12, relativeTo: .caption))
-                .foregroundStyle(.secondary)
-        }
-    }
-
-    /// iOS/iPadOS only: keep a backgrounded session alive (audio background mode). Empty elsewhere
-    /// (tvOS backgrounding semantics differ; macOS isn't gated by the mode) so the shared `.general`
-    /// detail can reference it unconditionally.
-    @ViewBuilder var keepAliveSection: some View {
-        #if os(iOS)
-        Section {
-            Toggle("Keep streaming in background", isOn: $backgroundKeepAlive)
-            if backgroundKeepAlive {
-                Picker("Disconnect after", selection: $backgroundTimeoutMinutes) {
-                    Text("1 minute").tag(1)
-                    Text("5 minutes").tag(5)
-                    Text("10 minutes").tag(10)
-                    Text("30 minutes").tag(30)
-                }
-            }
-        } header: {
-            Text("Background")
-        } footer: {
-            Text("Off by default: backgrounding the app freezes the session. When on, audio keeps "
-                + "playing and the connection stays live (video is dropped to save power) after you "
-                + "switch away — and the session auto-disconnects after the time above so it can't "
-                + "run down your battery. Returning to the app resumes video instantly.")
-                .font(.geist(12, relativeTo: .caption))
-                .foregroundStyle(.secondary)
-        }
-        #endif
-    }
-
-    @ViewBuilder var experimentalSection: some View {
-        Section {
-            Toggle("Show game library", isOn: $libraryEnabled)
-        } header: {
-            Text("Experimental")
-        } footer: {
-            Text("Adds a “Browse Library…” action to each host that lists its games "
-                + "(Steam + custom); tap a title to launch it. Works once you've paired — no "
-                + "extra host setup.")
-                .font(.geist(12, relativeTo: .caption))
-                .foregroundStyle(.secondary)
-        }
-    }
+    // MARK: - Controllers
 
     @ViewBuilder var controllersSection: some View {
         Section {
@@ -537,24 +525,37 @@ extension SettingsView {
                     controllerRow(controller)
                 }
             }
-            Picker("Use controller", selection: $gamepads.preferredID) {
-                ForEach(controllerOptions, id: \.tag) { option in
-                    Text(option.label).tag(option.tag)
+            described("One controller is forwarded as player 1 — Automatic picks the most "
+                + "recently connected.") {
+                Picker("Use controller", selection: $gamepads.preferredID) {
+                    ForEach(controllerOptions, id: \.tag) { option in
+                        Text(option.label).tag(option.tag)
+                    }
                 }
             }
-            Picker("Controller type", selection: $gamepadType) {
-                ForEach(SettingsOptions.padTypes, id: \.tag) { option in
-                    Text(option.label).tag(option.tag)
+            described("The virtual pad created on the host. Automatic matches your controller "
+                + "— a DualSense keeps adaptive triggers, lightbar, touchpad and motion.") {
+                Picker("Controller type", selection: $gamepadType) {
+                    ForEach(SettingsOptions.padTypes, id: \.tag) { option in
+                        Text(option.label).tag(option.tag)
+                    }
                 }
             }
             #if os(iOS)
             // iPhone only in practice: hidden where the device itself can't play haptics (iPad).
             if CHHapticEngine.capabilitiesForHardware().supportsHaptics {
-                Toggle("Rumble on this iPhone", isOn: $rumbleOnDevice)
+                described("Plays player 1's rumble on the phone's own Taptic Engine — for "
+                    + "clip-on controllers without motors of their own.") {
+                    Toggle("Rumble on this iPhone", isOn: $rumbleOnDevice)
+                }
             }
             #endif
             #if !os(tvOS)
-            Toggle("Gamepad-optimized browsing", isOn: $gamepadUIEnabled)
+            described("With a controller connected, the host list and library switch to a "
+                + "controller-friendly layout — larger focus targets, a swipeable cover "
+                + "browser.") {
+                Toggle("Gamepad-optimized browsing", isOn: $gamepadUIEnabled)
+            }
             #endif
             #if DEBUG && !os(tvOS)
             Button("Test Controller…") { showControllerTest = true }
@@ -564,22 +565,9 @@ extension SettingsView {
         } header: {
             Text("Controllers")
         } footer: {
-            // The gamepad-UI blurb is appended here, not merged into the shared
-            // `controllersFooter` constant — tvOS's `tvBody` reuses that exact string (line ~348)
-            // for its own footer and has no such toggle to describe.
-            VStack(alignment: .leading, spacing: 6) {
-                Text(Self.controllersFooter)
-                #if os(iOS)
-                if CHHapticEngine.capabilitiesForHardware().supportsHaptics {
-                    Text(Self.deviceRumbleFooter)
-                }
-                #endif
-                #if !os(tvOS)
-                Text(Self.gamepadUIFooter)
-                #endif
-            }
-            .font(.geist(12, relativeTo: .caption))
-            .foregroundStyle(.secondary)
+            Text("Applies from the next session.")
+                .font(.geist(12, relativeTo: .caption))
+                .foregroundStyle(.secondary)
         }
     }
 }

clients/apple/Sources/PunktfunkClient/Settings/SettingsView+Support.swift

@@ -9,6 +9,31 @@ import PunktfunkKit
 import SwiftUI
 
 extension SettingsView {
+    // MARK: - Described rows (the 2026-07 revamp's field idiom)
+
+    /// A control with its explanation attached to the SAME cell: the field, then a tight caption
+    /// directly under it. This replaced the per-section footer paragraphs — a description the eye
+    /// can't match to its field is one nobody reads. Keep captions to one or two sentences; when
+    /// a picker's meaning depends on the selection, pass a DYNAMIC string describing the current
+    /// choice.
+    @ViewBuilder
+    func described<Content: View>(
+        _ caption: String, @ViewBuilder content: () -> Content
+    ) -> some View {
+        VStack(alignment: .leading, spacing: 5) {
+            content()
+            Text(caption)
+                .font(.geist(13, relativeTo: .footnote))
+                .foregroundStyle(.secondary)
+                .fixedSize(horizontal: false, vertical: true) // wrap, never truncate, in Form cells
+                // Cap the caption's line length well short of the cell: a full-width caption runs
+                // its text right up to the control column (toggles especially), reading as one
+                // colliding block. ~46 chars/line also just measures better.
+                .frame(maxWidth: 360, alignment: .leading)
+        }
+        .padding(.vertical, 2)
+    }
+
     // MARK: - Bitrate
 
     /// Slider domain, log-scale: the useful range spans three orders of magnitude
@@ -17,6 +42,7 @@ extension SettingsView {
     private static let minSliderKbps = 2_000.0
     private static let maxSliderKbps = 3_000_000.0
 
+    /// tvOS's cluster caption (the touch/desktop forms describe bitrate per-row instead).
     static let bitrateFooter =
         "Automatic uses the host's default bitrate (20 Mbps); the host clamps any choice "
         + "to its supported range. Run a speed test from a host card's context menu to "
@@ -53,55 +79,27 @@ extension SettingsView {
 
     // MARK: - Statistics
 
-    static var statisticsFooter: String {
-        let base = "Shows streaming statistics in the chosen corner — Compact is a one-line "
-            + "pill, Normal adds resolution and latency, Detailed adds the latency stage "
-            + "breakdown."
+    static var statisticsDescription: String {
+        let base = "Live session stats in a corner overlay — Compact is a one-line pill, "
+            + "Detailed adds the latency stage breakdown."
         #if os(macOS)
-        return base + " ⌃⌥⇧S cycles Off → Compact → Normal → Detailed any time."
+        return base + " ⌃⌥⇧S cycles the tiers any time."
         #elseif os(iOS)
-        return base + " ⌃⌥⇧S or a three-finger tap cycles Off → Compact → Normal → Detailed "
-            + "any time."
+        return base + " ⌃⌥⇧S or a three-finger tap cycles the tiers any time."
         #else
         return base
         #endif
     }
 
-    // MARK: - Audio
-
-    static var audioFooter: String {
-        #if os(macOS)
-        return "Host audio plays through the chosen speaker; your microphone feeds the host's "
-            + "virtual mic. System default follows your Mac's device changes. Applies from the "
-            + "next session."
-        #else
-        return "Host audio plays locally; your microphone feeds the host's virtual mic. "
-            + "Applies from the next session."
-        #endif
-    }
-
     // MARK: - Controllers
 
+    /// tvOS's cluster caption (the touch/desktop form describes each row inline instead).
     static let controllersFooter =
         "One controller is forwarded as player 1 — Automatic picks the most recently "
         + "connected. Type is the virtual pad the host creates; Automatic matches your "
         + "controller (a DualSense keeps adaptive triggers, lightbar, touchpad and motion). "
         + "Applies from the next session."
 
-    #if os(iOS)
-    static let deviceRumbleFooter =
-        "Rumble on this iPhone plays player 1's rumble on the phone's own Taptic Engine as "
-        + "well — for clip-on controllers that have no rumble motors of their own. Applies "
-        + "from the next session."
-    #endif
-
-    #if !os(tvOS)
-    static let gamepadUIFooter =
-        "When a controller connects, the host list and library switch to a controller-"
-        + "friendly layout — larger focus targets and a swipeable cover browser. Turn this "
-        + "off to always use the standard layout."
-    #endif
-
     /// "Use controller" choices for this view's manager (see `SettingsOptions.controllerOptions`).
     var controllerOptions: [(label: String, tag: String)] {
         SettingsOptions.controllerOptions(gamepads)

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

@@ -2,13 +2,15 @@
 // deliberate resample is the opt-in Render Scale (the host renders at size × scale and this device
 // downscales — supersampling for sharpness, or under-rendering for a lighter host/link).
 //
-// Navigation differs per platform, but all three group the same categories (General, Display,
-// Audio, Controllers, Advanced, About): macOS uses a tabbed preferences window; iOS/iPadOS uses
-// an adaptive NavigationSplitView — a category sidebar + detail pane on iPad, auto-collapsing to
+// Navigation differs per platform, but all three follow the same category map (General =
+// session/app behavior, Display = everything about the picture, Input, Audio, Controllers,
+// About — see SettingsCategory): macOS uses a tabbed preferences window; iOS/iPadOS uses an
+// adaptive NavigationSplitView — a category sidebar + detail pane on iPad, auto-collapsing to
 // a hierarchical push list on iPhone (the system Settings idiom on each); tvOS uses a
-// focus-native pushed-picker layout. The individual sections (`streamModeSection`,
-// `audioSection`, …) are shared across all three so a setting is defined exactly once — they
-// live in SettingsView+Sections.swift, with their helpers in SettingsView+Support.swift.
+// focus-native pushed-picker layout in the same order. The individual sections
+// (`resolutionSection`, `audioSection`, …) are shared across all three so a setting is defined
+// exactly once — they live in SettingsView+Sections.swift, with their helpers (including the
+// per-field `described` caption idiom) in SettingsView+Support.swift.
 
 #if os(macOS)
 import AppKit
@@ -33,7 +35,9 @@ struct SettingsView: View {
     @AppStorage(DefaultsKey.compositor) var compositor = 0
     @AppStorage(DefaultsKey.gamepadType) var gamepadType = 0
     @AppStorage(DefaultsKey.bitrateKbps) var bitrateKbps = 0
-    @AppStorage(DefaultsKey.presenter) var presenter = SettingsOptions.presenterDefault
+    @AppStorage(DefaultsKey.presentPriority) var presentPriority =
+        SettingsOptions.presentPriorityDefault
+    @AppStorage(DefaultsKey.smoothBuffer) var smoothBuffer = 0
     #if os(macOS)
     @AppStorage(DefaultsKey.vsync) var vsync = false
     #endif
@@ -120,27 +124,32 @@ struct SettingsView: View {
 
     #if os(macOS)
     private var macBody: some View {
+        // Tab map mirrors SettingsCategory: General = session/app behavior, Display = the whole
+        // picture (resolution lives here), Input = keyboard & mouse.
         TabView {
             Form {
-                streamModeSection
-                inputSection
-                compositorSection
-                wakeSection
+                sessionSection
+                overlaySection
+                librarySection
             }
             .formStyle(.grouped)
             .tabItem { Label("General", systemImage: "gearshape") }
 
             Form {
-                presenterSection
-                hdrSection
-                vrrSection
-                vsyncSection
-                windowSection
-                statisticsSection
+                resolutionSection
+                qualitySection
+                presentationSection
+                hostOutputSection
             }
             .formStyle(.grouped)
             .tabItem { Label("Display", systemImage: "display") }
 
+            Form {
+                inputSection
+            }
+            .formStyle(.grouped)
+            .tabItem { Label("Input", systemImage: "keyboard") }
+
             Form {
                 audioSection
             }
@@ -168,16 +177,10 @@ struct SettingsView: View {
             .onDisappear { gamepads.stopDiscovery() }
             .tabItem { Label("Controllers", systemImage: "gamecontroller") }
 
-            Form {
-                experimentalSection
-            }
-            .formStyle(.grouped)
-            .tabItem { Label("Advanced", systemImage: "slider.horizontal.3") }
-
             AcknowledgementsView()
                 .tabItem { Label("About", systemImage: "info.circle") }
         }
-        .frame(width: 480, height: 460)
+        .frame(width: 500, height: 520)
     }
     #endif
 
@@ -252,26 +255,31 @@ struct SettingsView: View {
         switch category {
         case .general:
             Form {
-                streamModeSection
-                pointerSection
-                inputSection
-                compositorSection
-                wakeSection
-                keepAliveSection // iOS-only content; empty on tvOS
+                sessionSection
+                overlaySection
+                librarySection
             }
             .formStyle(.grouped)
             .navigationTitle("General")
             .navigationBarTitleDisplayMode(.inline)
         case .display:
             Form {
-                presenterSection
-                hdrSection
-                vrrSection
-                statisticsSection
+                resolutionSection
+                qualitySection
+                presentationSection
+                hostOutputSection
             }
             .formStyle(.grouped)
             .navigationTitle("Display")
             .navigationBarTitleDisplayMode(.inline)
+        case .input:
+            Form {
+                pointerSection
+                inputSection
+            }
+            .formStyle(.grouped)
+            .navigationTitle("Input")
+            .navigationBarTitleDisplayMode(.inline)
         case .audio:
             Form { audioSection }
                 .formStyle(.grouped)
@@ -282,11 +290,6 @@ struct SettingsView: View {
                 .formStyle(.grouped)
                 .navigationTitle("Controllers")
                 .navigationBarTitleDisplayMode(.inline)
-        case .advanced:
-            Form { experimentalSection }
-                .formStyle(.grouped)
-                .navigationTitle("Advanced")
-                .navigationBarTitleDisplayMode(.inline)
         case .about:
             // Already a full scrollable view that sets its own "Acknowledgements" title; pin the
             // display mode inline to match the five sibling detail pages (it would otherwise inherit
@@ -332,6 +335,16 @@ struct SettingsView: View {
         Binding(get: { autoWakeEnabled ? "on" : "off" }, set: { autoWakeEnabled = $0 == "on" })
     }
 
+    /// One cluster caption, TV-legible — the 10-foot analogue of the touch/desktop per-row
+    /// `described` captions (per-row text doesn't scale to TV type sizes).
+    private func tvCaption(_ text: String) -> some View {
+        Text(text)
+            .font(.geist(20, relativeTo: .caption))
+            .foregroundStyle(.secondary)
+            .multilineTextAlignment(.center)
+            .padding(.top, 8)
+    }
+
     private var tvBody: some View {
         let currentTag = "\(width)x\(height)x\(hz)"
         let bounds = UIScreen.main.nativeBounds
@@ -344,6 +357,9 @@ struct SettingsView: View {
         if !options.contains(where: { $0.tag == currentTag }) {
             options.insert(("Custom (\(width)×\(height) @ \(hz))", currentTag), at: 0)
         }
+        // Row order mirrors the touch/desktop category map: Display (mode → quality →
+        // presentation → host output), then Audio, General, Statistics, Controllers — with one
+        // short caption per cluster (per-row captions don't scale to 10-foot type sizes).
         return ScrollView {
             VStack(spacing: 16) {
                 TVSelectionRow(title: "Stream mode", options: options, selection: modeTag)
@@ -355,37 +371,41 @@ struct SettingsView: View {
                     title: "Bitrate",
                     options: SettingsOptions.bitrateOptions(current: bitrateKbps),
                     selection: $bitrateKbps)
-                TVSelectionRow(
-                    title: "Audio channels",
-                    options: SettingsOptions.audioChannels,
-                    selection: $audioChannels)
                 if bitrateKbps > 1_000_000 {
                     Label(Self.gigabitWarning, systemImage: "exclamationmark.triangle.fill")
                         .font(.geist(20, relativeTo: .caption)) // TV-legible caption size
                         .foregroundStyle(.orange)
                         .multilineTextAlignment(.center)
                 }
-                TVSelectionRow(
-                    title: "Compositor", options: SettingsOptions.compositors,
-                    selection: $compositor)
-                TVSelectionRow(
-                    title: "Presenter",
-                    options: SettingsOptions.presenters,
-                    selection: $presenter)
                 TVSelectionRow(
                     title: "10-bit HDR",
                     options: [("On", "on"), ("Off", "off")], selection: hdrEnabledTag)
+                TVSelectionRow(
+                    title: "Prioritize",
+                    options: SettingsOptions.presentPriorities,
+                    selection: $presentPriority)
+                if presentPriority == "smooth" {
+                    TVSelectionRow(
+                        title: "Smoothness buffer",
+                        options: SettingsOptions.smoothBuffers(refreshHz: hz),
+                        selection: $smoothBuffer)
+                }
+                TVSelectionRow(
+                    title: "Compositor", options: SettingsOptions.compositors,
+                    selection: $compositor)
+                tvCaption("The host drives a real output at exactly the chosen mode. "
+                    + "\(Self.bitrateFooter) Lowest latency shows frames immediately; "
+                    + "Smoothness buffers a few to even out network hiccups. A specific "
+                    + "compositor is honored only if available on the host.")
+                TVSelectionRow(
+                    title: "Audio channels",
+                    options: SettingsOptions.audioChannels,
+                    selection: $audioChannels)
                 TVSelectionRow(
                     title: "Auto-wake on connect",
                     options: [("On", "on"), ("Off", "off")], selection: autoWakeEnabledTag)
-                Text("The host creates a virtual output at exactly this mode — native "
-                    + "resolution, no scaling. \(Self.bitrateFooter) A specific compositor "
-                    + "is honored only if available on the host. Auto-wake sends Wake-on-LAN to a "
-                    + "sleeping saved host and waits for it before streaming.")
-                    .font(.geist(20, relativeTo: .caption))
-                    .foregroundStyle(.secondary)
-                    .multilineTextAlignment(.center)
-                    .padding(.top, 8)
+                tvCaption("Auto-wake sends Wake-on-LAN to a sleeping saved host and waits for "
+                    + "it before streaming.")
                 TVSelectionRow(
                     title: "Statistics overlay",
                     options: SettingsOptions.statsVerbosities, selection: $statsVerbosityRaw)
@@ -405,11 +425,7 @@ struct SettingsView: View {
                 TVSelectionRow(
                     title: "Gamepad-optimized browsing",
                     options: [("On", "on"), ("Off", "off")], selection: gamepadUIEnabledTag)
-                Text(Self.controllersFooter)
-                    .font(.geist(20, relativeTo: .caption))
-                    .foregroundStyle(.secondary)
-                    .multilineTextAlignment(.center)
-                    .padding(.top, 8)
+                tvCaption(Self.controllersFooter)
                 NavigationLink("Acknowledgements") { AcknowledgementsView() }
                     .padding(.top, 8)
             }

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

@@ -1,4 +1,4 @@
-// PIN pairing sheet. The host shows the pairing PIN in its web console (port 3000 →
+// PIN pairing sheet. The host shows the pairing PIN in its web console (port 47992 →
 // Pairing; also printed in the host's log when armed via --allow-pairing); the user
 // types it here. The ceremony is SPAKE2, so a wrong PIN buys an
 // attacker exactly one online guess — for the user a typo just means "try again" (the
@@ -45,7 +45,7 @@ struct PairSheet: View {
         #if os(tvOS)
         VStack(spacing: 24) {
             Text("The PIN is shown in the host's web console "
-                + "(http://<host>:3000 → Pairing). "
+                + "(https://<host>:47992 → Pairing). "
                 + "Pairing verifies both sides at once — no fingerprint comparison "
                 + "needed.")
                 .font(.geist(22, relativeTo: .callout)) // TV-legible (system callout is ~25 there)
@@ -118,7 +118,7 @@ struct PairSheet: View {
                         .foregroundStyle(.tint)
                 } footer: {
                     Text("The PIN is shown in the host's web console "
-                        + "(http://<host>:3000 → Pairing). "
+                        + "(https://<host>:47992 → Pairing). "
                         + "Pairing verifies both sides at once — no fingerprint "
                         + "comparison needed.")
                         .font(.geist(12, relativeTo: .caption))
@@ -210,7 +210,7 @@ struct PairSheet: View {
                     onPaired(fingerprint)
                     dismiss()
                 case .failure(PunktfunkClientError.wrongPIN):
-                    errorText = "Wrong PIN — check the host's web console (port 3000) "
+                    errorText = "Wrong PIN — check the host's web console (port 47992) "
                         + "and try again."
                 case .failure(PunktfunkClientError.rejected(let rejection)):
                     // The host answered and said why (not armed / rate-limited / armed for

clients/apple/Sources/PunktfunkKit/Support/BrandFont.swift

@@ -57,30 +57,8 @@ public enum BrandFont {
     }
 }
 
-public extension Color {
-    /// The punktfunk brand purple (the app-icon lens / website `--brand`). Defined explicitly,
-    /// independent of the asset-catalog accent — `Color.accentColor` resolution is environment- and
-    /// timing-sensitive (it can fall back to system blue), and the brand mark must never drift.
-    /// Light: #6656F2, Dark: #8678F5 (the lighter violet reads better on dark surfaces).
-    static let brand: Color = {
-        #if canImport(UIKit)
-        return Color(UIColor { traits in
-            traits.userInterfaceStyle == .dark
-                ? UIColor(red: 0x86 / 255, green: 0x78 / 255, blue: 0xF5 / 255, alpha: 1)
-                : UIColor(red: 0x66 / 255, green: 0x56 / 255, blue: 0xF2 / 255, alpha: 1)
-        })
-        #elseif canImport(AppKit)
-        return Color(NSColor(name: nil) { appearance in
-            appearance.bestMatch(from: [.aqua, .darkAqua]) == .darkAqua
-                ? NSColor(red: 0x86 / 255, green: 0x78 / 255, blue: 0xF5 / 255, alpha: 1)
-                : NSColor(red: 0x66 / 255, green: 0x56 / 255, blue: 0xF2 / 255, alpha: 1)
-        })
-        #else
-        // Non-Apple fallback: the light brand value, so all branches agree on a canonical color.
-        return Color(red: 0x66 / 255, green: 0x56 / 255, blue: 0xF2 / 255)
-        #endif
-    }()
-}
+// Color.brand lives in PunktfunkShared/BrandColor.swift (re-exported here): the widget
+// extension links Shared alone and must render the same purple.
 
 public extension Font {
     /// Geist Sans at an explicit point size, scaling with Dynamic Type relative to `textStyle`.

clients/apple/Sources/PunktfunkKit/Video/MetalVideoPresenter.swift

@@ -14,6 +14,9 @@
 #if canImport(Metal) && canImport(QuartzCore)
 import CoreGraphics
 import CoreVideo
+#if os(macOS)
+import IOSurface
+#endif
 import Metal
 import QuartzCore
 import os
@@ -193,13 +196,11 @@ fragment float4 pf_frag_hdr(VOut in [[stage_in]],
 // display-referred SDR. (When the display IS in an HDR mode — requested per session via
 // AVDisplayManager, see StreamViewIOS — tvOS presents pf_frag_hdr's PQ passthrough instead:
 // in a genuine HDR10 output, PQ passthrough is the correct emission and the TV tone-maps.)
-fragment float4 pf_frag_hdr_tv(VOut in [[stage_in]],
-                               texture2d<float> lumaTex [[texture(0)]],
-                               texture2d<float> chromaTex [[texture(1)]],
-                               constant CscUniform& csc [[buffer(0)]]) {
-    // Y′CbCr → full-range PQ R′G′B′ via the per-frame rows (as pf_frag_hdr).
-    float3 pq = sampleRgb(lumaTex, chromaTex, in.uv, csc);
-    // ST 2084 EOTF: PQ code value → linear light, 1.0 = 10,000 nits.
+// The shared PQ→display-referred-SDR tail (see pf_frag_hdr_tv's rationale above): ST 2084
+// EOTF → 203-nit-anchored scene light → BT.2020→709 primaries → extended-Reinhard rolloff →
+// BT.709 OETF. Used by the tvOS biplanar tone-map and the planar (PyroWave) tone-map — the
+// latter also on macOS windowed sessions, whose IOSurface present path is BGRA8-only.
+static inline float3 pqToSdr(float3 pq) {
     const float m1 = 2610.0/16384.0;
     const float m2 = 78.84375;
     const float c1 = 3424.0/4096.0;
@@ -207,20 +208,49 @@ fragment float4 pf_frag_hdr_tv(VOut in [[stage_in]],
     const float c3 = 18.6875;
     float3 p = pow(pq, 1.0/m2);
     float3 lin = pow(max(p - c1, 0.0) / (c2 - c3 * p), 1.0/m1);
-    // Scene-referred with diffuse white at 1.0 (the same 203-nit anchor the EDR path uses).
     float3 t = lin * (10000.0/203.0);
-    // BT.2020 → BT.709 primaries while still linear; negatives are out-of-gamut, floor them.
     float3 t709 = float3(
         dot(t, float3( 1.6605, -0.5876, -0.0728)),
         dot(t, float3(-0.1246,  1.1329, -0.0083)),
         dot(t, float3(-0.0182, -0.1006,  1.1187)));
     t709 = max(t709, 0.0);
-    // Extended Reinhard: 1.0 stays put, the 1000-nit knee lands at display white, above rolls off.
     const float w = 1000.0/203.0;
     float3 mapped = saturate(t709 * (1.0 + t709 / (w * w)) / (1.0 + t709));
-    // BT.709 OETF — the same encoding the SDR stream arrives in, so both paths present alike.
     float3 e = select(1.099 * pow(mapped, 0.45) - 0.099, 4.5 * mapped, mapped < 0.018);
-    return float4(e, 1.0);
+    return e;
+}
+
+fragment float4 pf_frag_hdr_tv(VOut in [[stage_in]],
+                               texture2d<float> lumaTex [[texture(0)]],
+                               texture2d<float> chromaTex [[texture(1)]],
+                               constant CscUniform& csc [[buffer(0)]]) {
+    // Y′CbCr → full-range PQ R′G′B′ via the per-frame rows (as pf_frag_hdr), then the tail.
+    return float4(pqToSdr(sampleRgb(lumaTex, chromaTex, in.uv, csc)), 1.0);
+}
+
+// PyroWave planar HDR tone-map: three separate R16 planes (P010-style studio codes; the rows
+// fold in depth-10 MSB packing) → PQ R′G′B′ → the shared SDR tail. Used when a PQ pyrowave
+// stream must land on an 8-bit surface: tvOS without HDR headroom, and macOS WINDOWED sessions
+// (the IOSurface present path — the DCP-panic mitigation — is BGRA8). The passthrough planar
+// HDR pipeline reuses pf_frag_planar itself on an rgba16Float drawable (identical math — the
+// layer's itur_2100_PQ colour space + EDR metadata do the interpretation).
+fragment float4 pf_frag_planar_tm(VOut in [[stage_in]],
+                                  texture2d<float> lumaTex [[texture(0)]],
+                                  texture2d<float> cbTex [[texture(1)]],
+                                  texture2d<float> crTex [[texture(2)]],
+                                  constant CscUniform& csc [[buffer(0)]]) {
+    constexpr sampler s(filter::linear, address::clamp_to_edge);
+#ifdef PF_BILINEAR_LUMA
+    float lumaY = lumaTex.sample(s, in.uv).r;
+#else
+    float lumaY = catmullRomLuma(lumaTex, s, in.uv);
+#endif
+    float2 cuv = chromaUV(lumaTex, cbTex, in.uv);
+    float3 yuv = float3(lumaY, cbTex.sample(s, cuv).r, crTex.sample(s, cuv).r);
+    float3 pq = saturate(float3(dot(csc.r0.xyz, yuv) + csc.r0.w,
+                                dot(csc.r1.xyz, yuv) + csc.r1.w,
+                                dot(csc.r2.xyz, yuv) + csc.r2.w));
+    return float4(pqToSdr(pq), 1.0);
 }
 """
 
@@ -228,6 +258,51 @@ public final class MetalVideoPresenter {
     /// The layer the hosting view installs (as a sublayer) and sizes to its bounds.
     public let layer: CAMetalLayer
 
+    #if os(macOS)
+    /// The WINDOWED-mode PyroWave present target: a plain CALayer sized like `layer` (installed
+    /// as a sibling ABOVE it), fed IOSurfaces via `contents` inside ordinary CATransactions.
+    ///
+    /// Why this exists — the macOS DCP KERNEL PANIC ("mismatched swapID's" @UnifiedPipeline.cpp,
+    /// WindowServer dies, machine reboots): out-of-band CAMetalLayer image-queue swaps into a
+    /// COMPOSITED (windowed) session race WindowServer's own swap submissions on high-refresh
+    /// displays, and the race survives glass pacing — a fully serialized one-in-flight present
+    /// stream still panicked a 240 Hz Mac Studio (2026-07-18, twice). So in windowed mode we stop
+    /// using the image queue entirely and present the way video players do: render the planar CSC
+    /// into an IOSurface pool and swap `contents` on main — WindowServer treats it as ordinary
+    /// damage on its own composite cadence, coalescing faster-than-refresh updates instead of
+    /// latching queue swaps mid-cycle. Fullscreen keeps the CAMetalLayer path (direct-scanout
+    /// promotion, no compositing, no panic reports). Contents updates are transparent to the
+    /// layer below when nil, so flipping modes just covers/uncovers the metal layer.
+    public let surfaceLayer: CALayer = {
+        let l = CALayer()
+        l.contentsGravity = .resize // frame is already aspect-fit + pixel-snapped by layout
+        l.isOpaque = true
+        l.actions = ["contents": NSNull(), "bounds": NSNull(), "position": NSNull()]
+        return l
+    }()
+
+    /// One IOSurface-backed render target of the windowed present pool. All pool state is
+    /// RENDER-THREAD confined; only the immutable surface refs cross to main (contents swap).
+    private struct SurfaceSlot {
+        let surface: IOSurfaceRef
+        let texture: MTLTexture
+        /// Monotonic use stamp — the reuse picker takes the least-recently-rendered free slot.
+        var seq: UInt64 = 0
+    }
+
+    private var surfacePool: [SurfaceSlot] = []
+    private var surfacePoolSize: CGSize = .zero
+    private var surfaceSeq: UInt64 = 0
+    /// Index of the slot most recently handed to the layer — never rewritten next, even if its
+    /// use count already dropped (the compositor may still be scanning out the previous frame).
+    private var lastHandedOff: Int?
+    /// Staged (under `stagingLock`, like every cross-thread input): the hosting view's windowed
+    /// vs fullscreen state, pushed from main via `setSurfacePresents`. Drained in `renderPlanar`.
+    private var surfacePresentsStaged = false
+    /// Render-thread copy, so pool teardown happens exactly once on a mode flip.
+    private var surfacePresentsActive = false
+    #endif
+
     private let device: MTLDevice
     private let queue: MTLCommandQueue
     /// SDR (BT.709 8-bit → bgra8) and HDR (BT.2020 PQ 10-bit → rgba16Float) pipelines. Selected per
@@ -239,6 +314,11 @@ public final class MetalVideoPresenter {
     private let pipelineHDRToneMap: MTLRenderPipelineState?
     /// PyroWave's 3-plane SDR path (pf_frag_planar → bgra8) — see `renderPlanar`.
     private let pipelinePlanar: MTLRenderPipelineState
+    /// PyroWave planar HDR passthrough (pf_frag_planar → rgba16Float; the layer's PQ colour
+    /// space + EDR interpret the samples) and the planar PQ→SDR tone-map (pf_frag_planar_tm →
+    /// bgra8; tvOS without headroom + macOS windowed IOSurface presents).
+    private let pipelinePlanarHDR: MTLRenderPipelineState
+    private let pipelinePlanarToneMap: MTLRenderPipelineState
     private var textureCache: CVMetalTextureCache?
 
     /// The PyroWave Metal decoder records on the presenter's device + queue: one device means
@@ -289,6 +369,8 @@ public final class MetalVideoPresenter {
         let pipelineHDR: MTLRenderPipelineState
         let pipelineHDRToneMap: MTLRenderPipelineState?
         let pipelinePlanar: MTLRenderPipelineState
+        let pipelinePlanarHDR: MTLRenderPipelineState
+        let pipelinePlanarToneMap: MTLRenderPipelineState
         do {
             // DEBUG A/B lever: PUNKTFUNK_BILINEAR_LUMA=1 compiles the shader with Catmull-Rom OFF
             // (plain bilinear luma) by prepending a #define ahead of the source. Default (unset) is
@@ -326,8 +408,18 @@ public final class MetalVideoPresenter {
             let planar = MTLRenderPipelineDescriptor()
             planar.vertexFunction = vtx
             planar.fragmentFunction = library.makeFunction(name: "pf_frag_planar")
-            planar.colorAttachments[0].pixelFormat = .bgra8Unorm // PyroWave is 8-bit SDR
+            planar.colorAttachments[0].pixelFormat = .bgra8Unorm
             pipelinePlanar = try device.makeRenderPipelineState(descriptor: planar)
+            let planarHdr = MTLRenderPipelineDescriptor()
+            planarHdr.vertexFunction = vtx
+            planarHdr.fragmentFunction = library.makeFunction(name: "pf_frag_planar")
+            planarHdr.colorAttachments[0].pixelFormat = .rgba16Float // PQ passthrough
+            pipelinePlanarHDR = try device.makeRenderPipelineState(descriptor: planarHdr)
+            let planarTm = MTLRenderPipelineDescriptor()
+            planarTm.vertexFunction = vtx
+            planarTm.fragmentFunction = library.makeFunction(name: "pf_frag_planar_tm")
+            planarTm.colorAttachments[0].pixelFormat = .bgra8Unorm
+            pipelinePlanarToneMap = try device.makeRenderPipelineState(descriptor: planarTm)
         } catch {
             return nil
         }
@@ -368,6 +460,7 @@ public final class MetalVideoPresenter {
         return MetalVideoPresenter(
             device: device, queue: queue, pipelineSDR: pipelineSDR, pipelineHDR: pipelineHDR,
             pipelineHDRToneMap: pipelineHDRToneMap, pipelinePlanar: pipelinePlanar,
+            pipelinePlanarHDR: pipelinePlanarHDR, pipelinePlanarToneMap: pipelinePlanarToneMap,
             textureCache: textureCache, layer: layer)
     }
 
@@ -375,6 +468,8 @@ public final class MetalVideoPresenter {
         device: MTLDevice, queue: MTLCommandQueue, pipelineSDR: MTLRenderPipelineState,
         pipelineHDR: MTLRenderPipelineState, pipelineHDRToneMap: MTLRenderPipelineState?,
         pipelinePlanar: MTLRenderPipelineState,
+        pipelinePlanarHDR: MTLRenderPipelineState,
+        pipelinePlanarToneMap: MTLRenderPipelineState,
         textureCache: CVMetalTextureCache, layer: CAMetalLayer
     ) {
         self.device = device
@@ -383,6 +478,8 @@ public final class MetalVideoPresenter {
         self.pipelineHDR = pipelineHDR
         self.pipelineHDRToneMap = pipelineHDRToneMap
         self.pipelinePlanar = pipelinePlanar
+        self.pipelinePlanarHDR = pipelinePlanarHDR
+        self.pipelinePlanarToneMap = pipelinePlanarToneMap
         self.textureCache = textureCache
         self.layer = layer
     }
@@ -493,6 +590,48 @@ public final class MetalVideoPresenter {
         stagingLock.unlock()
     }
 
+    #if os(macOS)
+    /// Park the windowed-vs-fullscreen present routing (MAIN thread — the hosting view pushes its
+    /// window state on every layout). true = PyroWave frames present via `surfaceLayer` contents
+    /// (the DCP swapID-panic mitigation — see `surfaceLayer`); false = the CAMetalLayer path.
+    /// Applied by the render thread on the next frame, like every other staged value here.
+    public func setSurfacePresents(_ on: Bool) {
+        stagingLock.lock()
+        surfacePresentsStaged = on
+        stagingLock.unlock()
+    }
+    #endif
+
+    /// Deadline pacing only, RENDER THREAD: reconcile the layer with a decoded frame BEFORE a
+    /// drawable exists. The link vends from the layer's CURRENT config, and the layer starts
+    /// with `drawableSize` 0 (it never tracks bounds once set explicitly, and the sublayer's
+    /// frame isn't even laid out when the link spins up) — so leaving all reconciliation to the
+    /// render path (which needs a frame AND a vended drawable) deadlocks at session start:
+    /// every vend fails allocation at 0×0, the stash stays empty, no pair ever completes, and
+    /// the size is never set. The 2026-07-19 iPad black screen ("[CAMetalLayer nextDrawable]
+    /// returning nil because allocation failed" every refresh). Called on EVERY frame arrival:
+    /// drains the same staging the render path drains (both are idempotent about it) and
+    /// applies size + HDR config, so the next vend always matches the frame about to present —
+    /// this also makes a mid-session HDR flip cost at most one skipped vend instead of waiting
+    /// for a paired present to retag the layer.
+    func reconcileLayer(decodedSize: CGSize, isHDR: Bool) {
+        stagingLock.lock()
+        let targetFromLayout = drawableTarget
+        let newHdrMeta = pendingHdrMeta
+        pendingHdrMeta = nil
+        stagingLock.unlock()
+        configure(hdr: isHDR)
+        if let newHdrMeta {
+            self.lastHdrMeta = newHdrMeta
+            #if !os(tvOS)
+            if hdrActive { layer.edrMetadata = makeEDR(newHdrMeta) }
+            #endif
+        }
+        let targetSize = (targetFromLayout.width > 0 && targetFromLayout.height > 0)
+            ? targetFromLayout : decodedSize
+        if layer.drawableSize != targetSize { layer.drawableSize = targetSize }
+    }
+
     /// Draw one decoded frame to the next drawable and present it. RENDER THREAD (Stage2Pipeline's;
     /// `nextDrawable()` may block up to a frame — that wait belongs here, never on main). `isHDR`
     /// selects the 10-bit BT.2020 PQ path vs the 8-bit BT.709 path and is reconciled with the
@@ -508,10 +647,15 @@ public final class MetalVideoPresenter {
     /// glass mid-refresh whenever the layer is direct-scanout promoted (fullscreen, no HUD), which
     /// is the "frametimes are off with the stats HUD closed" report. nil presents immediately
     /// (`PUNKTFUNK_PRESENT_MODE=immediate` — the pre-fix behavior, kept as a diagnostic A/B).
+    ///
+    /// `into drawable` (deadline pacing) supplies the CAMetalDisplayLink-vended drawable to
+    /// render into instead of calling `nextDrawable()` — see `encodePresent` for the format
+    /// guard that skips a vend the layer's config outran.
     @discardableResult
     public func render(
         _ pixelBuffer: CVPixelBuffer, isHDR: Bool = false,
         presentAtMediaTime: CFTimeInterval? = nil,
+        into drawable: CAMetalDrawable? = nil,
         onPresented: ((Int64?) -> Void)? = nil
     ) -> Bool {
         // Drain the cross-thread staging (see `stagingLock`): the layout-derived drawable size and
@@ -565,7 +709,8 @@ public final class MetalVideoPresenter {
             width: CVPixelBufferGetWidth(pixelBuffer), height: CVPixelBufferGetHeight(pixelBuffer))
         return encodePresent(
             decodedSize: decodedSize, targetFromLayout: targetFromLayout, pipeline: pipeline,
-            presentAtMediaTime: presentAtMediaTime, onPresented: onPresented,
+            presentAtMediaTime: presentAtMediaTime, providedDrawable: drawable,
+            onPresented: onPresented,
             // Hold the CVMetalTextures + source pixel buffer (its IOSurface) alive until the GPU
             // finishes sampling — releasing them at scope exit could free the backing mid-read.
             keepAlive: [luma, chroma, pixelBuffer]
@@ -584,17 +729,58 @@ public final class MetalVideoPresenter {
     func renderPlanar(
         _ planes: WaveletPlanes,
         presentAtMediaTime: CFTimeInterval? = nil,
+        into drawable: CAMetalDrawable? = nil,
         onPresented: ((Int64?) -> Void)? = nil
     ) -> Bool {
         stagingLock.lock()
         let targetFromLayout = drawableTarget
+        #if os(macOS)
+        let surfaceMode = surfacePresentsStaged
+        #endif
         stagingLock.unlock()
-        configure(hdr: false)
+        // A PQ (HDR) pyrowave stream drives the same layer/EDR machinery as the biplanar path;
+        // macOS WINDOWED sessions stay on the SDR layer (the IOSurface path tone-maps in-shader).
+        #if os(macOS)
+        configure(hdr: planes.pq && !surfaceMode)
+        #else
+        configure(hdr: planes.pq)
+        #endif
         var csc = planes.csc
+        #if os(macOS)
+        if surfaceMode != surfacePresentsActive {
+            surfacePresentsActive = surfaceMode
+            presenterLog.info(
+                "stage2: windowed surface presents \(surfaceMode ? "ON" : "OFF", privacy: .public) (PyroWave DCP-panic mitigation)")
+            if !surfaceMode {
+                // Back to the metal path (fullscreen): drop the pool — at 5K it holds >100 MB,
+                // and re-entering windowed mode rebuilds it in one frame.
+                surfacePool.removeAll()
+                surfacePoolSize = .zero
+                lastHandedOff = nil
+            }
+        }
+        if surfaceMode {
+            return renderPlanarToSurface(
+                planes, targetFromLayout: targetFromLayout, csc: &csc, onPresented: onPresented)
+        }
+        #endif
+        // PQ passthrough needs the HDR drawable; a PQ frame while the drawable is (still)
+        // 8-bit — tvOS without display headroom, or a not-yet-flipped layer — tone-maps
+        // in-shader instead (the pipeline must match the drawable's pixel format).
+        #if os(tvOS)
+        let planarPassthrough = hdrActive && hdrPassthroughActive
+        #else
+        let planarPassthrough = hdrActive
+        #endif
+        let planarPipeline: MTLRenderPipelineState =
+            planes.pq
+                ? (planarPassthrough ? pipelinePlanarHDR : pipelinePlanarToneMap)
+                : pipelinePlanar
         return encodePresent(
             decodedSize: CGSize(width: planes.width, height: planes.height),
-            targetFromLayout: targetFromLayout, pipeline: pipelinePlanar,
-            presentAtMediaTime: presentAtMediaTime, onPresented: onPresented,
+            targetFromLayout: targetFromLayout, pipeline: planarPipeline,
+            presentAtMediaTime: presentAtMediaTime, providedDrawable: drawable,
+            onPresented: onPresented,
             // The ring textures stay valid by ring depth; retaining them here also pins the
             // slot's set until the sample completes (mirrors the biplanar keep-alive).
             keepAlive: [planes.y, planes.cb, planes.cr]
@@ -606,12 +792,132 @@ public final class MetalVideoPresenter {
         }
     }
 
+    #if os(macOS)
+    /// The windowed-mode present tail (see `surfaceLayer` for why this path exists): render the
+    /// planar CSC into a pooled IOSurface and hand it to `surfaceLayer.contents` on MAIN inside a
+    /// plain CATransaction — an ordinary damaged-layer update on WindowServer's own composite
+    /// cadence, no CAMetalLayer image-queue swap anywhere. `presentAtMediaTime` doesn't apply
+    /// (the compositor paces); `onPresented` fires after the contents swap is committed, stamped
+    /// with CLOCK_REALTIME then — the closest observable analogue of "reached glass" here (the
+    /// composite follows within a refresh, so the meters' display stage reads slightly optimistic).
+    private func renderPlanarToSurface(
+        _ planes: WaveletPlanes, targetFromLayout: CGSize, csc: inout CscUniform,
+        onPresented: ((Int64?) -> Void)?
+    ) -> Bool {
+        let decodedSize = CGSize(width: planes.width, height: planes.height)
+        let targetSize = (targetFromLayout.width > 0 && targetFromLayout.height > 0)
+            ? targetFromLayout : decodedSize
+        ensureSurfacePool(size: targetSize)
+        guard let slotIndex = takeSurfaceSlot(),
+              let commandBuffer = queue.makeCommandBuffer()
+        else { return false }
+        let slot = surfacePool[slotIndex]
+
+        let pass = MTLRenderPassDescriptor()
+        pass.colorAttachments[0].texture = slot.texture
+        pass.colorAttachments[0].loadAction = .clear
+        pass.colorAttachments[0].clearColor = MTLClearColor(red: 0, green: 0, blue: 0, alpha: 1)
+        pass.colorAttachments[0].storeAction = .store
+        guard let encoder = commandBuffer.makeRenderCommandEncoder(descriptor: pass) else {
+            return false
+        }
+        encoder.setRenderPipelineState(planes.pq ? pipelinePlanarToneMap : pipelinePlanar)
+        encoder.setFragmentTexture(planes.y, index: 0)
+        encoder.setFragmentTexture(planes.cb, index: 1)
+        encoder.setFragmentTexture(planes.cr, index: 2)
+        encoder.setFragmentBytes(&csc, length: MemoryLayout<CscUniform>.stride, index: 0)
+        encoder.drawPrimitives(type: .triangle, vertexStart: 0, vertexCount: 3)
+        encoder.endEncoding()
+        let surface = slot.surface
+        let surfaceLayer = surfaceLayer // captured directly — the handler must not retain self
+        let keepAlive: [Any] = [planes.y, planes.cb, planes.cr]
+        commandBuffer.addCompletedHandler { _ in
+            _ = keepAlive // ring textures pinned until the GPU finished sampling
+            DispatchQueue.main.async {
+                CATransaction.begin()
+                CATransaction.setDisableActions(true)
+                surfaceLayer.contents = surface
+                CATransaction.commit()
+                onPresented?(
+                    Stage2Pipeline.realtimeNs(forDisplayLinkTimestamp: CACurrentMediaTime()))
+            }
+        }
+        commandBuffer.commit()
+        lastHandedOff = slotIndex
+        return true
+    }
+
+    /// (Re)build the pool at `size` — 4 BGRA8 IOSurface render targets (one on glass, one queued
+    /// in CA, one rendering, one spare). RENDER THREAD. A failed allocation leaves the pool empty;
+    /// the caller returns false and the ring's putBack + display-link retry take over.
+    private func ensureSurfacePool(size: CGSize) {
+        guard size != surfacePoolSize else { return }
+        surfacePool.removeAll()
+        surfacePoolSize = size
+        lastHandedOff = nil
+        let w = Int(size.width)
+        let h = Int(size.height)
+        guard w > 0, h > 0 else { return }
+        // 256-byte row alignment satisfies both IOSurface and Metal linear-texture rules.
+        let bytesPerRow = ((w * 4) + 255) & ~255
+        let props: [String: Any] = [
+            kIOSurfaceWidth as String: w,
+            kIOSurfaceHeight as String: h,
+            kIOSurfaceBytesPerElement as String: 4,
+            kIOSurfaceBytesPerRow as String: bytesPerRow,
+            kIOSurfacePixelFormat as String: kCVPixelFormatType_32BGRA,
+        ]
+        let desc = MTLTextureDescriptor.texture2DDescriptor(
+            pixelFormat: .bgra8Unorm, width: w, height: h, mipmapped: false)
+        desc.usage = [.renderTarget]
+        desc.storageMode = .shared
+        for _ in 0..<4 {
+            guard let surface = IOSurfaceCreate(props as CFDictionary),
+                  let texture = device.makeTexture(descriptor: desc, iosurface: surface, plane: 0)
+            else {
+                surfacePool.removeAll()
+                return
+            }
+            surfacePool.append(SurfaceSlot(surface: surface, texture: texture))
+        }
+    }
+
+    /// Pick the slot to render into: never the one just handed to the layer (the compositor may
+    /// still scan it), prefer surfaces the window server isn't holding (`IOSurfaceIsInUse`), and
+    /// among those the least recently rendered. Falls back to the LRU busy slot rather than
+    /// stalling — a visible glitch at worst, never a queue-up. RENDER THREAD.
+    private func takeSurfaceSlot() -> Int? {
+        guard !surfacePool.isEmpty else { return nil }
+        var free: Int?
+        var busy: Int?
+        for i in surfacePool.indices where i != lastHandedOff {
+            if !IOSurfaceIsInUse(surfacePool[i].surface) {
+                if free == nil || surfacePool[i].seq < surfacePool[free!].seq { free = i }
+            } else {
+                if busy == nil || surfacePool[i].seq < surfacePool[busy!].seq { busy = i }
+            }
+        }
+        guard let pick = free ?? busy else { return nil }
+        surfaceSeq += 1
+        surfacePool[pick].seq = surfaceSeq
+        return pick
+    }
+    #endif
+
     /// The shared present tail of `render`/`renderPlanar`: size the drawable, encode one
     /// fullscreen triangle with `pipeline` (`bind` supplies the fragment resources), schedule
     /// the present and the on-glass callback.
+    ///
+    /// `providedDrawable` (deadline pacing) is the CAMetalDisplayLink-vended drawable to render
+    /// into instead of `nextDrawable()`. It was vended against the layer's config at vend time,
+    /// so after a mid-session reconfigure (HDR flip: `configure` above already retagged the
+    /// layer) its pixel format can lag the pipeline's attachment format — encoding would be a
+    /// Metal validation failure. The guard returns false instead: the drawable drops back to
+    /// the pool, the caller re-rings the frame, and the link's next vend carries the new format.
     private func encodePresent(
         decodedSize: CGSize, targetFromLayout: CGSize, pipeline: MTLRenderPipelineState,
-        presentAtMediaTime: CFTimeInterval?, onPresented: ((Int64?) -> Void)?,
+        presentAtMediaTime: CFTimeInterval?, providedDrawable: CAMetalDrawable? = nil,
+        onPresented: ((Int64?) -> Void)?,
         keepAlive: [Any], bind: (MTLRenderCommandEncoder) -> Void
     ) -> Bool {
         // Size the drawable to the LAYER's pixels (its laid-out frame × contentsScale, pushed here by
@@ -624,11 +930,17 @@ public final class MetalVideoPresenter {
         // (layout / Reconfigure / HDR flip — and every frame of a live resize, which is fine).
         let targetSize = (targetFromLayout.width > 0 && targetFromLayout.height > 0)
             ? targetFromLayout : decodedSize
+        // Under a provided (link-vended) drawable this sizes the NEXT vend — the one in hand
+        // keeps its size, and a live-resize transient composites via contentsGravity as ever.
         if layer.drawableSize != targetSize { layer.drawableSize = targetSize }
         #if DEBUG
         logSizeIfChanged(decoded: decodedSize, drawable: targetSize)
         #endif
-        guard let drawable = layer.nextDrawable(),
+        if let providedDrawable,
+           providedDrawable.texture.pixelFormat != layer.pixelFormat {
+            return false // config outran the vend (HDR flip) — next vend has the new format
+        }
+        guard let drawable = providedDrawable ?? layer.nextDrawable(),
               let commandBuffer = queue.makeCommandBuffer()
         else { return false }
 

clients/apple/Sources/PunktfunkKit/Video/MetalWaveletDecoder.swift

@@ -47,6 +47,9 @@ struct WaveletLayout {
 
     let width: Int
     let height: Int
+    /// Full-res chroma (4:4:4): chroma components get the full band set including level 0,
+    /// exactly like luma — upstream `init_block_meta` with `Chroma444`.
+    let chroma444: Bool
     let alignedWidth: Int
     let alignedHeight: Int
     /// blockMeta[component][level][band] = (blockOffset32x32, blockStride32x32); -1 offset =
@@ -59,9 +62,10 @@ struct WaveletLayout {
     func levelWidth(_ level: Int) -> Int { (alignedWidth / 2) >> level }
     func levelHeight(_ level: Int) -> Int { (alignedHeight / 2) >> level }
 
-    init(width: Int, height: Int) {
+    init(width: Int, height: Int, chroma444: Bool) {
         self.width = width
         self.height = height
+        self.chroma444 = chroma444
         let align = { (v: Int) in
             max((v + Self.alignment - 1) & ~(Self.alignment - 1), Self.minimumImageSize)
         }
@@ -78,7 +82,7 @@ struct WaveletLayout {
         let ah = alignedHeight
         for level in stride(from: Self.decompositionLevels - 1, through: 0, by: -1) {
             for component in 0..<3 {
-                if level == 0 && component != 0 { continue } // 4:2:0: no top-level chroma
+                if level == 0 && component != 0 && !chroma444 { continue } // 4:2:0: no top-level chroma
                 for band in (level == Self.decompositionLevels - 1 ? 0 : 1)..<4 {
                     let levelW = (aw / 2) >> level
                     let levelH = (ah / 2) >> level
@@ -108,6 +112,9 @@ struct ParsedWaveletFrame {
     var decodedBlocks: Int
     /// VUI bits from the sequence header (BitstreamSequenceHeader).
     var bt2020: Bool
+    /// PQ transfer ⇒ HDR session: 16-bit studio-code planes + EDR present (the host stamps
+    /// this bit iff the session negotiated 10-bit — the depth is coupled to the transfer).
+    var pq: Bool
     var fullRange: Bool
 
     /// The frame's Y′CbCr→RGB signal for the presenter's planar CSC. PyroWave today is always
@@ -131,6 +138,12 @@ enum WaveletBitstream {
     /// decoding — upstream's `decoded_blocks > total/2` partial rule).
     static func parse(au: Data, chunkAligned: Bool, windowSize: Int) -> ParsedWaveletFrame? {
         var state = ParseState()
+        // Reserve the coefficient buffer ONCE, up front. Every packet's payload is a slice of the
+        // AU, so `au.count / 4` words is a tight upper bound — reserving it here lets the per-packet
+        // appends stay amortized O(1). (Reserving per packet forces Swift to allocate the exact new
+        // size each time, turning the walk O(n²) — invisible on the tiny golden fixtures, but ~5 ms
+        // per 1.4 MB frame on a real 5120x1440 stream.)
+        state.payload.reserveCapacity(au.count / 4)
         let ok = au.withUnsafeBytes { (raw: UnsafeRawBufferPointer) -> Bool in
             guard let base = raw.baseAddress?.assumingMemoryBound(to: UInt8.self) else {
                 return false
@@ -203,6 +216,7 @@ enum WaveletBitstream {
         var totalBlocks = 0
         var decodedBlocks = 0
         var bt2020 = false
+        var pq = false
         var fullRange = false
         var sawSOF = false
 
@@ -220,22 +234,27 @@ enum WaveletBitstream {
                     // siting[31].
                     let code = (word1 >> 24) & 0x3
                     guard code == 0 else { return false } // only START_OF_FRAME is defined
-                    let chromaRes = (word1 >> 26) & 1
-                    guard chromaRes == 0 else { return false } // host contract: 4:2:0
+                    let chroma444 = (word1 >> 26) & 1 != 0
                     let w = Int(word0 & 0x3fff) + 1
                     let h = Int((word0 >> 14) & 0x3fff) + 1
-                    guard w >= 2, h >= 2, w % 2 == 0, h % 2 == 0 else { return false }
+                    guard w >= 2, h >= 2, chroma444 || (w % 2 == 0 && h % 2 == 0) else {
+                        return false
+                    }
                     if sawSOF {
                         // One frame, one geometry — a second SOF must agree.
-                        guard layout?.width == w, layout?.height == h else { return false }
+                        guard layout?.width == w, layout?.height == h,
+                              layout?.chroma444 == chroma444
+                        else { return false }
                     } else {
                         sawSOF = true
-                        let l = WaveletLayout(width: w, height: h)
+                        let l = WaveletLayout(width: w, height: h, chroma444: chroma444)
                         layout = l
                         offsets = [UInt32](repeating: .max, count: l.blockCount32)
-                        payload.reserveCapacity(64 * 1024 / 4)
                         totalBlocks = Int(word1 & 0xff_ffff)
                         bt2020 = (word1 >> 29) & 1 != 0
+                        // transfer_function bit: PQ ⇒ an HDR session (16-bit studio-code
+                        // planes by the negotiated coupling — design/pyrowave-444-hdr.md).
+                        pq = (word1 >> 28) & 1 != 0
                         fullRange = (word1 >> 30) & 1 == 0 // YCBCR_RANGE_FULL = 0
                     }
                     pos += 8
@@ -252,9 +271,15 @@ enum WaveletBitstream {
                     if offsets[blockIndex] == .max {
                         offsets[blockIndex] = UInt32(payload.count)
                         decodedBlocks += 1
-                        payload.reserveCapacity(payload.count + payloadWords)
-                        for w in 0..<payloadWords {
-                            payload.append(loadWord(base, pos + w * 4))
+                        // Bulk-copy the packet's coefficient words in one memcpy rather than
+                        // word-by-word. All Apple platforms are little-endian, so the wire's LE
+                        // u32s land in the [UInt32] buffer verbatim; memcpy has no alignment
+                        // requirement, so a non-word-aligned `base + pos` is fine. `reserveCapacity`
+                        // up in `parse` keeps the grow amortized O(1).
+                        let dstWord = payload.count
+                        payload.append(contentsOf: repeatElement(0, count: payloadWords))
+                        payload.withUnsafeMutableBytes { dst in
+                            _ = memcpy(dst.baseAddress! + dstWord * 4, base + pos, payloadWords * 4)
                         }
                     }
                 } else if layout != nil {
@@ -280,7 +305,7 @@ enum WaveletBitstream {
             return ParsedWaveletFrame(
                 layout: layout, offsets: offsets, payload: payload,
                 totalBlocks: totalBlocks, decodedBlocks: decodedBlocks,
-                bt2020: bt2020, fullRange: fullRange)
+                bt2020: bt2020, pq: pq, fullRange: fullRange)
         }
     }
 }
@@ -293,6 +318,8 @@ public struct WaveletPlanes: @unchecked Sendable {
     public let cb: MTLTexture
     public let cr: MTLTexture
     public let csc: CscUniform
+    /// PQ (HDR) stream: the presenter picks the HDR/tone-map planar pipeline + EDR config.
+    public let pq: Bool
     public var width: Int { y.width }
     public var height: Int { y.height }
 }
@@ -351,6 +378,8 @@ public final class MetalWaveletDecoder {
 
     private var slots: [Slot] = []
     private var nextSlot = 0
+    /// The ring's plane format facts (from the last SOF): PQ ⇒ 16-bit UNORM planes.
+    private var hdr16 = false
 
     /// The current geometry (from the last SOF that built the resources) — the pump reports
     /// decoded-size changes to the resize overlay from this. PUMP THREAD.
@@ -409,8 +438,9 @@ public final class MetalWaveletDecoder {
                 au: au, chunkAligned: chunkAligned, windowSize: windowSize)
         else { return false }
 
-        if layout?.width != frame.layout.width || layout?.height != frame.layout.height {
-            guard rebuild(layout: frame.layout) else { return false }
+        if layout?.width != frame.layout.width || layout?.height != frame.layout.height
+            || layout?.chroma444 != frame.layout.chroma444 || hdr16 != frame.pq {
+            guard rebuild(layout: frame.layout, hdr16: frame.pq) else { return false }
         }
         guard let layout, !slots.isEmpty else { return false }
 
@@ -450,7 +480,7 @@ public final class MetalWaveletDecoder {
         dequant.setBuffer(slot.payload, offset: 0, index: 1)
         for level in 0..<WaveletLayout.decompositionLevels {
             for component in 0..<3 {
-                if level == 0 && component != 0 { continue } // 4:2:0
+                if level == 0 && component != 0 && !layout.chroma444 { continue } // 4:2:0
                 for band in (level == WaveletLayout.decompositionLevels - 1 ? 0 : 1)..<4 {
                     let meta = layout.blockMeta[component][level][band]
                     let w = layout.levelWidth(level)
@@ -489,15 +519,20 @@ public final class MetalWaveletDecoder {
             let grid = MTLSize(width: (rx + 15) / 16, height: (ry + 15) / 16, depth: 1)
             let group = MTLSize(width: 64, height: 1, depth: 1)
             if inputLevel == 0 {
-                // 4:2:0: the final full-res pass is luma only (chroma finished at level 1).
+                // Final full-res pass: luma only in 4:2:0 (chroma finished at level 1); all
+                // three components in 4:4:4 (chroma runs the full pyramid like luma).
                 idwt.setComputePipelineState(idwtShiftPipeline)
-                idwt.setTexture(coefficients[0][0], index: 0)
-                idwt.setTexture(slot.y, index: 1)
-                idwt.dispatchThreadgroups(grid, threadsPerThreadgroup: group)
+                let components = layout.chroma444 ? 3 : 1
+                for component in 0..<components {
+                    idwt.setTexture(coefficients[component][0], index: 0)
+                    let out = component == 0 ? slot.y : (component == 1 ? slot.cb : slot.cr)
+                    idwt.setTexture(out, index: 1)
+                    idwt.dispatchThreadgroups(grid, threadsPerThreadgroup: group)
+                }
             } else {
                 for component in 0..<3 {
                     idwt.setTexture(coefficients[component][inputLevel], index: 0)
-                    if component != 0 && inputLevel == 1 {
+                    if component != 0 && inputLevel == 1 && !layout.chroma444 {
                         // 4:2:0 chroma emits its final half-res plane one level early.
                         idwt.setComputePipelineState(idwtShiftPipeline)
                         idwt.setTexture(component == 1 ? slot.cb : slot.cr, index: 1)
@@ -513,7 +548,9 @@ public final class MetalWaveletDecoder {
 
         let planes = WaveletPlanes(
             y: slot.y, cb: slot.cb, cr: slot.cr,
-            csc: CscRows.rows(frame.cscSignal, depth: 8, msbPacked: false))
+            csc: CscRows.rows(
+                frame.cscSignal, depth: frame.pq ? 10 : 8, msbPacked: frame.pq),
+            pq: frame.pq)
         cmd.addCompletedHandler { buffer in
             completion(buffer.error == nil ? planes : nil)
         }
@@ -524,9 +561,9 @@ public final class MetalWaveletDecoder {
 
     /// (Re)allocate every size-dependent resource for `layout`'s geometry. Also the mid-stream
     /// resize path: a Reconfigure shows up here as new SOF dims.
-    private func rebuild(layout newLayout: WaveletLayout) -> Bool {
+    private func rebuild(layout newLayout: WaveletLayout, hdr16 newHdr16: Bool) -> Bool {
         waveletLog.info(
-            "pyrowave: building decoder \(newLayout.width)x\(newLayout.height) (aligned \(newLayout.alignedWidth)x\(newLayout.alignedHeight), \(newLayout.blockCount32) blocks)")
+            "pyrowave: building decoder \(newLayout.width)x\(newLayout.height) (aligned \(newLayout.alignedWidth)x\(newLayout.alignedHeight), \(newLayout.blockCount32) blocks, \(newLayout.chroma444 ? "4:4:4" : "4:2:0", privacy: .public)\(newHdr16 ? " HDR16" : "", privacy: .public))")
         var coeff: [[MTLTexture]] = []
         var lls: [[MTLTexture]] = []
         for component in 0..<3 {
@@ -560,19 +597,22 @@ public final class MetalWaveletDecoder {
 
         var newSlots: [Slot] = []
         for i in 0..<Self.ringDepth {
+            let planeFormat: MTLPixelFormat = newHdr16 ? .r16Unorm : .r8Unorm
             let plane = { (w: Int, h: Int, name: String) -> MTLTexture? in
                 let desc = MTLTextureDescriptor.texture2DDescriptor(
-                    pixelFormat: .r8Unorm, width: w, height: h, mipmapped: false)
+                    pixelFormat: planeFormat, width: w, height: h, mipmapped: false)
                 desc.usage = [.shaderRead, .shaderWrite]
                 desc.storageMode = .private
                 let t = self.device.makeTexture(descriptor: desc)
                 t?.label = name
                 return t
             }
+            let cw = newLayout.chroma444 ? newLayout.width : newLayout.width / 2
+            let ch = newLayout.chroma444 ? newLayout.height : newLayout.height / 2
             guard
                 let y = plane(newLayout.width, newLayout.height, "pyrowave Y[\(i)]"),
-                let cb = plane(newLayout.width / 2, newLayout.height / 2, "pyrowave Cb[\(i)]"),
-                let cr = plane(newLayout.width / 2, newLayout.height / 2, "pyrowave Cr[\(i)]"),
+                let cb = plane(cw, ch, "pyrowave Cb[\(i)]"),
+                let cr = plane(cw, ch, "pyrowave Cr[\(i)]"),
                 let offsets = device.makeBuffer(
                     length: max(newLayout.blockCount32 * 4, 4), options: .storageModeShared),
                 let payload = device.makeBuffer(length: 64 * 1024, options: .storageModeShared)
@@ -585,6 +625,7 @@ public final class MetalWaveletDecoder {
         slots = newSlots
         nextSlot = 0
         layout = newLayout
+        hdr16 = newHdr16
         return true
     }
 

clients/apple/Sources/PunktfunkKit/Video/SessionPresenter.swift

@@ -1,8 +1,12 @@
-// Per-session presenter stack shared by the macOS and iOS/tvOS stream views: stage-2 (explicit
-// VTDecompressionSession decode → CAMetalLayer, driven by the hosting view's CADisplayLink) is the
-// default; stage-1 (StreamPump → AVSampleBufferDisplayLayer) is the Metal-unavailable / DEBUG
-// fallback. The views own the platform bits — capture, window/scale tracking, and constructing the
-// display link — and delegate the shared presenter lifecycle here.
+// Per-session presenter stack shared by the macOS and iOS/tvOS stream views: the Metal pipeline
+// (explicit VTDecompressionSession decode → CAMetalLayer) is the default — deadline-paced
+// stage-4 on iOS/tvOS, arrival-paced stage-2 on macOS (see PresenterChoice.platformDefault);
+// the user-facing choice is the INTENT (PresentPriority: latency vs smoothness+buffer — the
+// 2026-07 rebuild, design/apple-presentation-rebuild.md), the stage ladder is env-only debug.
+// Stage-1 (StreamPump → AVSampleBufferDisplayLayer) is the Metal-unavailable / DEBUG fallback.
+// The views own the platform bits — capture, window/scale tracking, and constructing the
+// display link (arrival/glass pacing only; deadline pacing runs its own CAMetalDisplayLink) —
+// and delegate the shared presenter lifecycle here.
 //
 // Main-thread only: start/layout/stop and the display-link tick all run on the main runloop.
 
@@ -26,15 +30,17 @@ public final class DisplayLinkProxy: NSObject {
     @objc public func tick(_ link: CADisplayLink) { onTick(link) }
 }
 
-/// Which presenter a session runs. Stage-2/stage-3 are the same Metal pipeline with arrival vs
-/// glass-gated present pacing (`PresentPacing` — see Stage2Pipeline for the tradeoff, and why
-/// stage-3 exists: stage-2's present-on-arrival saturates the layer's FIFO image queue on panels
-/// running near the stream rate). Stage-1 (compressed video straight to the system layer) is a
-/// DEBUG-only diagnostic. Internal (not private) for unit tests.
+/// Which presenter a session runs. Stage-2/3/4 are the same Metal pipeline with different present
+/// pacing (`PresentPacing` — see Stage2Pipeline for the full tradeoff): stage-2 presents on frame
+/// arrival, stage-3 gates presents on the on-glass callback, stage-4 presents into
+/// CAMetalDisplayLink-vended drawables (deadline pacing — iOS/tvOS only; see `PresentPacing`'s
+/// doc for why the vsync-latching platforms need it). Stage-1 (compressed video straight to the
+/// system layer) is a DEBUG-only diagnostic. Internal (not private) for unit tests.
 enum PresenterChoice: Equatable {
     case stage1
     case stage2
     case stage3
+    case stage4
 
     /// Resolve from the `PUNKTFUNK_PRESENTER` env override (A/B without touching settings) first,
     /// then the persisted `DefaultsKey.presenter` setting; anything unknown (or an empty env var)
@@ -42,34 +48,159 @@ enum PresenterChoice: Equatable {
     /// leftover DEBUG "stage1" value silently maps to the default rather than reviving the
     /// freeze-prone fallback.
     static func resolve(setting: String?, env: String?, allowStage1: Bool) -> PresenterChoice {
+        explicit(setting: setting, env: env, allowStage1: allowStage1) ?? platformDefault
+    }
+
+    /// The user's EXPLICIT stage selection, nil when they haven't made one (unset/unknown values,
+    /// and a release build's gated "stage1"). Split from `resolve` so a codec-conditional default
+    /// (see `SessionPresenter.pacing`) can apply only when the user hasn't picked a stage — an
+    /// explicit "stage2" must stay a faithful A/B of arrival pacing. "stage4" resolves only on
+    /// iOS/tvOS: macOS's present path is entangled with the sync-off/DCP-panic saga (see
+    /// MetalVideoPresenter's init) and stays on its proven pacings until deadline presents are
+    /// deliberately validated there — a synced "stage4" value maps back to the platform default.
+    static func explicit(setting: String?, env: String?, allowStage1: Bool) -> PresenterChoice? {
         let raw = env.flatMap { $0.isEmpty ? nil : $0 } ?? setting
         switch raw {
-        case "stage1": return allowStage1 ? .stage1 : platformDefault
+        case "stage1": return allowStage1 ? .stage1 : nil
         case "stage2": return .stage2
         case "stage3": return .stage3
-        default: return platformDefault
+        case "stage4":
+            #if os(macOS)
+            return nil
+            #else
+            return .stage4
+            #endif
+        default: return nil
         }
     }
 
-    /// tvOS defaults to GLASS pacing: an Apple TV is the sticky-FIFO worst case by construction —
-    /// a fixed 60 Hz panel fed a 60 fps stream, where arrival pacing pins the layer's image queue
-    /// at ~3 drawables and every frame rides ~50 ms of queue (the measured display stage there).
-    /// The Settings picker can still force stage-2 for an A/B. Everything else keeps stage-2 (the
-    /// proven default; ProMotion/desktop panels out-tick the stream often enough to drain).
+    /// iOS/iPadOS/tvOS default to DEADLINE pacing (stage-4), macOS to arrival (stage-2).
+    ///
+    /// The iOS/tvOS layers ALWAYS vsync-latch presents into a FIFO image queue
+    /// (`displaySyncEnabled` is macOS-only API), and at stream rate ≈ panel rate — an Apple TV's
+    /// fixed 60 Hz by construction; an iPhone/iPad with VRR (default on, preferred = stream rate)
+    /// steering the panel to the stream — that queue's depth is STICKY: one burst fills it and,
+    /// with arrivals and latches then running at the same rate, it NEVER drains. Every queued
+    /// present costs a full refresh, forever: the 2026-07 iPad Pro (2752×2064@120) field ladder
+    /// read ~30 ms display on arrival (~3 refreshes of queue), 22–28 ms glass-gated at depth 2
+    /// (a standing queue of 2 — the depth-2 experiment's post-mortem), 14 ms at depth 1. Glass
+    /// pacing (stage-3) bounds the queue but presents still serialize on the on-glass callback;
+    /// deadline pacing (stage-4) is the fix for the remainder: one CAMetalDisplayLink-vended
+    /// drawable per refresh, presented the moment a frame decodes — the queue cannot exist and
+    /// nothing waits on callbacks (see `PresentPacing.deadline`).
+    ///
+    /// tvOS joined iOS on the deadline engine in the 2026-07 presentation rebuild
+    /// (design/apple-presentation-rebuild.md — the engine is field-proven on iOS and strictly
+    /// simpler than the glass gate it replaces; `PUNKTFUNK_PRESENTER=stage3` remains the
+    /// fallback lever if a TV-specific issue surfaces). macOS keeps stage-2: with the layer's
+    /// sync off, presents are out-of-band flips that don't queue, so arrival is genuinely
+    /// lowest-latency there.
     static var platformDefault: PresenterChoice {
-        #if os(tvOS)
-        .stage3
+        #if os(iOS) || os(tvOS)
+        .stage4
         #else
         .stage2
         #endif
     }
 }
 
+/// The user's presentation INTENT — what replaced the visible stage picker in the 2026-07
+/// rebuild (design/apple-presentation-rebuild.md). Two intents, one engine per platform:
+///
+/// - `.latency` (the default): every frame shows as soon as the display can take it — the
+///   newest-wins zero-queue store; network/decode jitter appears as the occasional repeat or
+///   drop. This is the configuration the whole 2026-07 pacing saga optimized.
+/// - `.smooth(buffer:)`: a small deliberate jitter buffer (`FrameStore.fifo`) evens the present
+///   cadence at the cost of `buffer` refresh intervals of added display latency — which the HUD
+///   SHOWS (only the OS floor is shaved, never the user's chosen buffer). `buffer` ∈ 1…3;
+///   the "Automatic" setting (stored 0) currently maps to 2.
+///
+/// Mechanism stays internal: intents map onto `PresentPacing`/`FrameStore.Policy` per platform
+/// in `SessionPresenter.start`; the stage ladder survives only as the PUNKTFUNK_PRESENTER debug
+/// env lever. Internal (not private) for unit tests.
+enum PresentPriority: Equatable {
+    case latency
+    case smooth(buffer: Int)
+
+    /// Resolve from the persisted settings: `DefaultsKey.presentPriority` ("latency" default;
+    /// anything but "smooth" — unset, garbage, a synced unknown future value — falls back to
+    /// latency) and `DefaultsKey.smoothBuffer` (0/out-of-range = Automatic = 2).
+    static func resolve(setting: String?, bufferSetting: Int?) -> PresentPriority {
+        guard setting == "smooth" else { return .latency }
+        let raw = bufferSetting ?? 0
+        return .smooth(buffer: (1...3).contains(raw) ? raw : 2)
+    }
+
+    /// The frame hand-off policy this intent runs (see `FrameStore`).
+    var storePolicy: FrameStorePolicy {
+        switch self {
+        case .latency: return .newestWins
+        case .smooth(let buffer): return .fifo(capacity: buffer)
+        }
+    }
+}
+
 final class SessionPresenter {
+    /// Present pacing for this session. Stage-3 always means glass gating; under the stage-2
+    /// default, macOS PyroWave sessions ALSO get glass gating — a kernel-panic mitigation, not a
+    /// latency tweak. macOS's DCP panics ("mismatched swapID's" @UnifiedPipeline.cpp, the whole
+    /// machine dies) when WindowServer's swap submissions race, and the reliable trigger is
+    /// out-of-band CAMetalLayer presents (displaySyncEnabled=false — mandatory for us, see
+    /// MetalVideoPresenter's init) arriving faster than the compositor latches them in a
+    /// COMPOSITED (windowed) session. Arrival pacing does exactly that with PyroWave: the wavelet
+    /// decode is near-instant Metal compute, so a network clump of frames presents within the
+    /// same millisecond, and PyroWave is the codec that sustains stream rates above the panel's
+    /// refresh. The glass gate admits one presented-but-undisplayed swap at a time (serialized on
+    /// the on-glass callback, 100 ms stale backstop), which removes the racing pattern outright;
+    /// frames the panel couldn't have shown anyway coalesce in the newest-wins ring. An explicit
+    /// stage-2 pick (setting/env) still forces arrival pacing — that A/B lever must stay honest.
+    /// VideoToolbox codecs keep arrival pacing: decode latency spaces their presents, and years
+    /// of stage-2 defaults there predate any panic report.
+    static func pacing(
+        for choice: PresenterChoice, explicit: PresenterChoice?, codec: VideoCodec
+    ) -> PresentPacing {
+        if choice == .stage4 { return .deadline }
+        if choice == .stage3 { return .glass }
+        #if os(macOS)
+        if explicit == nil, codec == .pyrowave { return .glass }
+        #endif
+        return .arrival
+    }
+
+    /// The glass gate's in-flight present budget (`PresentGate` capacity): 1 everywhere.
+    ///
+    /// Depth 1 is the only depth that works. The 2026-07 depth-2 experiment (one flip scanning
+    /// out + one queued, predicted ~5–8 ms at 120 Hz) REGRESSED the iPad Pro's display stage to
+    /// 22–28 ms vs depth 1's 14: any second gate slot becomes a STANDING queue — a burst fills
+    /// it, and with presents and latches then running at the same rate the occupancy never
+    /// returns to zero, so every frame permanently rides one extra refresh per slot. A bounded
+    /// FIFO can cap the queue but nothing ever drains it; the prediction assumed an idle queue
+    /// that doesn't exist after the first Wi-Fi clump. Sub-refresh display latency needs pacing
+    /// that can't queue at all — that's stage-4 (`PresentPacing.deadline`), not a deeper gate.
+    ///
+    /// `PUNKTFUNK_GATE_DEPTH` (1…3) still overrides on iOS/tvOS so the standing-queue ladder
+    /// stays reproducible on-device; macOS is pinned to 1, env ignored — glass pacing exists
+    /// there as the DCP swapID kernel-panic mitigation (see `pacing`), and STRICT present
+    /// serialization is its point. Internal (not private) for unit tests.
+    static func gateDepth(env: String?) -> Int {
+        #if os(macOS)
+        return 1
+        #else
+        if let env, let depth = Int(env), (1...3).contains(depth) { return depth }
+        return 1
+        #endif
+    }
+
     private var pump: StreamPump?
     private var stage2: Stage2Pipeline?
     private var stage2Link: CADisplayLink?
     private var metalLayer: CAMetalLayer?
+    #if os(macOS)
+    /// The windowed-mode PyroWave present target (sibling above `metalLayer`) and the last
+    /// routing pushed to the pipeline — see `setComposited`. Main-thread only, like all of this.
+    private var surfaceLayer: CALayer?
+    private var surfacePresentsActive = false
+    #endif
     private var connection: PunktfunkConnection?
     /// The decoded frame's REAL pixel dimensions (ground truth, pushed by the view from the pump's
     /// `onDecodedSize` new-mode-IDR callback). Used for the aspect-fit in `layout` in preference to
@@ -93,6 +224,7 @@ final class SessionPresenter {
         endToEndMeter: LatencyMeter?,
         decodeMeter: LatencyMeter? = nil,
         displayMeter: LatencyMeter? = nil,
+        presentFloorMeter: LatencyMeter? = nil,
         makeDisplayLink: (AnyObject, Selector) -> CADisplayLink,
         onFrame: (@Sendable (AccessUnit) -> Void)?,
         onSessionEnd: (@Sendable () -> Void)?,
@@ -101,43 +233,79 @@ final class SessionPresenter {
         stop()
         self.connection = connection
 
-        // Presenter choice — stage-2 is the DEFAULT (explicit VTDecompressionSession decode + a
-        // CAMetalLayer/display-link present): it can detect + recover a wedged decoder where
-        // stage-1's AVSampleBufferDisplayLayer freezes hard on a lost HEVC reference. Stage-3 is
-        // the same pipeline with glass-gated present pacing (the settings picker's live A/B — see
-        // PresentPacing). Stage-1 is reachable only via the DEBUG presenter value; release maps it
-        // back to stage-2 (the stage-1 pump below stays the automatic fallback if Metal is missing).
+        // Presentation resolution (design/apple-presentation-rebuild.md). The Metal pipeline is
+        // the DEFAULT (explicit VTDecompressionSession decode + a CAMetalLayer present): it can
+        // detect + recover a wedged decoder where stage-1's AVSampleBufferDisplayLayer freezes
+        // hard on a lost HEVC reference. The MECHANISM (pacing) is per-platform via
+        // PresenterChoice.platformDefault — deadline on iOS/tvOS, arrival on macOS — overridable
+        // only by the hidden PUNKTFUNK_PRESENTER debug env (the legacy persisted stage picker
+        // value is deliberately ignored). The user-facing choice is the INTENT
+        // (PresentPriority): latency (newest-wins zero-queue store) vs smoothness (a FIFO jitter
+        // buffer; on macOS it additionally paces presents onto the vsync grid so the buffer
+        // drains on display cadence). Stage-1 is reachable only via env in DEBUG; release maps
+        // it back to the default (the stage-1 pump below stays the automatic Metal-missing
+        // fallback).
         #if DEBUG
         let allowStage1 = true
         #else
         let allowStage1 = false
         #endif
-        let choice = PresenterChoice.resolve(
-            setting: UserDefaults.standard.string(forKey: DefaultsKey.presenter),
+        let explicit = PresenterChoice.explicit(
+            setting: nil, // the legacy DefaultsKey.presenter picker value is no longer read
             env: ProcessInfo.processInfo.environment["PUNKTFUNK_PRESENTER"],
             allowStage1: allowStage1)
+        let choice = explicit ?? PresenterChoice.platformDefault
+        let pacing = Self.pacing(for: choice, explicit: explicit, codec: connection.videoCodec)
+        let priority = PresentPriority.resolve(
+            setting: UserDefaults.standard.string(forKey: DefaultsKey.presentPriority),
+            bufferSetting: UserDefaults.standard.object(forKey: DefaultsKey.smoothBuffer) as? Int)
+        // macOS smoothness rides arrival pacing + forced vsync scheduling; under a glass-paced
+        // macOS session (the PyroWave DCP mitigation) the gate already serializes on the
+        // display, so the FIFO alone provides the buffering.
+        #if os(macOS)
+        let vsyncPaced = priority != .latency && pacing == .arrival
+        #else
+        let vsyncPaced = false
+        #endif
         if choice != .stage1,
            let pipeline = Stage2Pipeline(
                endToEndMeter: endToEndMeter, decodeMeter: decodeMeter,
                displayMeter: displayMeter,
-               pacing: choice == .stage3 ? .glass : .arrival) {
+               presentFloorMeter: presentFloorMeter,
+               pacing: pacing,
+               gateDepth: Self.gateDepth(
+                   env: ProcessInfo.processInfo.environment["PUNKTFUNK_GATE_DEPTH"]),
+               storePolicy: priority.storePolicy,
+               vsyncPaced: vsyncPaced) {
             let metal = pipeline.layer
             // The opaque metal layer composites OVER the AVSampleBufferDisplayLayer base, which
             // sits idle (un-enqueued) in stage-2. contentsScale + frame are set in layout().
             baseLayer.addSublayer(metal)
             metalLayer = metal
+            #if os(macOS)
+            // The windowed-PyroWave present target sits ABOVE the metal layer: transparent (nil
+            // contents) while the metal path presents, covering it while surface presents run.
+            baseLayer.addSublayer(pipeline.surfaceLayer)
+            surfaceLayer = pipeline.surfaceLayer
+            surfacePresentsActive = false
+            #endif
             stage2 = pipeline
             // The link is the vsync CLOCK + putBack-retry nudge, not the presentation trigger
             // (frame arrival is — see Stage2Pipeline's header). timestamp→targetTimestamp is the
             // link's own report of the current refresh period (tracks VRR rate changes).
-            let proxy = DisplayLinkProxy { [weak self] link in
-                self?.stage2?.renderTick(
-                    targetMediaTime: link.targetTimestamp,
-                    period: link.targetTimestamp - link.timestamp)
+            // DEADLINE pacing needs neither: its CAMetalDisplayLink (pipeline-owned) is the vsync
+            // clock, and every one of its updates re-checks the ring, which IS the retry tick —
+            // a second link would only fight it over the frame-rate hint.
+            if pacing != .deadline {
+                let proxy = DisplayLinkProxy { [weak self] link in
+                    self?.stage2?.renderTick(
+                        targetMediaTime: link.targetTimestamp,
+                        period: link.targetTimestamp - link.timestamp)
+                }
+                let link = makeDisplayLink(proxy, #selector(DisplayLinkProxy.tick(_:)))
+                link.add(to: .main, forMode: .common)
+                stage2Link = link
             }
-            let link = makeDisplayLink(proxy, #selector(DisplayLinkProxy.tick(_:)))
-            link.add(to: .main, forMode: .common)
-            stage2Link = link
             syncFrameRate(hz: connection.currentMode().refreshHz)
             pipeline.start(
                 connection: connection, onFrame: onFrame, onSessionEnd: onSessionEnd,
@@ -165,7 +333,12 @@ final class SessionPresenter {
     /// rate (it already tracks the display and must NOT be capped to the stream rate).
     /// Re-applied from `layout` so a mid-session `Reconfigure` picks up a new refresh.
     private func syncFrameRate(hz: UInt32) {
-        guard hz > 0, let link = stage2Link else { return }
+        guard hz > 0 else { return }
+        // Deadline pacing: the hint goes to the pipeline's CAMetalDisplayLink instead (staged;
+        // applied from the link's own thread — see Stage2Pipeline.setFrameRateHint). A no-op
+        // under arrival/glass pacing, where the CADisplayLink below is the one hinted link.
+        stage2?.setFrameRateHint(hz: Float(hz))
+        guard let link = stage2Link else { return }
         let hzF = Float(hz)
         let allowVRR = UserDefaults.standard.object(forKey: DefaultsKey.allowVRR) as? Bool ?? true
         #if os(macOS)
@@ -224,6 +397,12 @@ final class SessionPresenter {
         CATransaction.setDisableActions(true)
         metalLayer.contentsScale = contentsScale
         metalLayer.frame = snapped
+        #if os(macOS)
+        // The surface present target mirrors the metal layer's geometry exactly — its IOSurfaces
+        // are sized to the same snapped pixel rect, so the contents composite is a 1:1 blit too.
+        surfaceLayer?.contentsScale = contentsScale
+        surfaceLayer?.frame = snapped
+        #endif
         CATransaction.commit()
         // Hand the resulting pixel size to the render thread (it must not read layer geometry
         // cross-thread) — this is what the presenter sizes its drawable to. Uses the SNAPPED size so
@@ -251,6 +430,31 @@ final class SessionPresenter {
         contentSize = size
     }
 
+    #if os(macOS)
+    /// Route presents for the window's composited state (MAIN thread — the view pushes it on
+    /// every layout, which fullscreen transitions always trigger). PyroWave sessions in a
+    /// COMPOSITED (windowed) session present via `surfaceLayer` contents instead of the
+    /// CAMetalLayer image queue — the DCP "mismatched swapID's" kernel-panic mitigation (see
+    /// `MetalVideoPresenter.surfaceLayer`; the metal-swap race survives glass pacing, so pacing
+    /// alone was not enough). VT codecs keep the metal path: no panic reports there, and their
+    /// HDR/EDR presentation has no surface-contents equivalent wired.
+    func setComposited(_ composited: Bool) {
+        guard let stage2, let connection else { return }
+        let wantsSurface = composited && connection.videoCodec == .pyrowave
+        guard wantsSurface != surfacePresentsActive else { return }
+        surfacePresentsActive = wantsSurface
+        stage2.setSurfacePresents(wantsSurface)
+        if !wantsSurface {
+            // Uncover the metal layer NOW (its last drawable is still attached, so fullscreen
+            // entry shows the previous frame until the next present — no black flash).
+            CATransaction.begin()
+            CATransaction.setDisableActions(true)
+            surfaceLayer?.contents = nil
+            CATransaction.commit()
+        }
+    }
+    #endif
+
     /// Stop the active pump/pipeline (≤ one poll timeout; stage-2 joins its pump) and detach the
     /// stage-2 layer + link. Does not close the connection — that stays with whoever owns it.
     /// Idempotent.
@@ -264,6 +468,11 @@ final class SessionPresenter {
         stage2 = nil
         metalLayer?.removeFromSuperlayer()
         metalLayer = nil
+        #if os(macOS)
+        surfaceLayer?.removeFromSuperlayer()
+        surfaceLayer = nil
+        surfacePresentsActive = false
+        #endif
         connection = nil
     }
 

clients/apple/Sources/PunktfunkKit/Video/Stage2Pipeline.swift

@@ -18,10 +18,14 @@
 //     – V-Sync ON: present(at: next vsync) predicted from the link's last phase/period, at most one
 //       period ahead by construction, falling back to immediate when the link data is stale — a
 //       schedule can never sit far in the future holding drawables hostage.
-// • Present PACING is the stage-2 vs stage-3 presenter split (`PresentPacing`, chosen per session
-//   by SessionPresenter from the presenter setting / PUNKTFUNK_PRESENTER): stage-2 presents on
-//   frame arrival; stage-3 additionally gates presents to ONE undisplayed drawable so the layer's
-//   FIFO image queue can never saturate — see PresentPacing's doc for the full rationale.
+// • Present PACING is the stage-2/3/4 presenter split (`PresentPacing`, chosen per session by
+//   SessionPresenter from the presenter setting / PUNKTFUNK_PRESENTER): stage-2 presents on
+//   frame arrival; stage-3 additionally gates presents on the on-glass callback (`PresentGate`)
+//   so the layer's FIFO image queue can never saturate; stage-4 (iOS/tvOS) presents into
+//   CAMetalDisplayLink-vended drawables the moment a frame decodes — deadline pacing, where the
+//   queue cannot exist at all — see PresentPacing's doc for the full rationale. Under deadline
+//   pacing the render thread below is fed by BOTH the decoder callback and the link's per-refresh
+//   updates (which vend the drawable), and the V-Sync policy/vsync clock don't apply.
 // • Rendering lives on its own thread so any `nextDrawable()` wait lands off-main (input, SwiftUI).
 //
 // The render thread also stamps the unified latency stages (end-to-end capture→on-glass + decode and
@@ -40,6 +44,7 @@ import Foundation
 import Metal
 import PunktfunkShared
 import QuartzCore
+import os
 
 /// PUNKTFUNK_PRESENT_DEBUG=1: the render thread prints a once-per-second line with the decode
 /// (ring-submit) rate, present rate, failed/empty wakes and the slowest render call — for
@@ -47,33 +52,127 @@ import QuartzCore
 /// stdout is the cheapest reliable capture channel.
 let presentDebug = ProcessInfo.processInfo.environment["PUNKTFUNK_PRESENT_DEBUG"] == "1"
 
-/// Newest-ready 1-slot ring: the decoder overwrites (drops the older undisplayed frame — lowest
-/// latency, no smoothing buffer), the display link takes-and-clears. Sendable; lock-guarded.
-private final class ReadyRing: @unchecked Sendable {
+/// The pf-present line's os_log mirror (subsystem io.unom.punktfunk, category "present") — the
+/// SessionModel "stats" mirror's sibling, so DEADLINE sessions stream their pacing decomposition
+/// to Console.app wirelessly with no env var / Xcode attach. Always on for deadline pacing (the
+/// stats are a few arrays + one log line per second); other pacings keep the env-gated print.
+private let presentLog = Logger(subsystem: "io.unom.punktfunk", category: "present")
+
+/// Decoded-frame hand-off between the decode half and the render thread. The POLICY is the
+/// user's presentation intent (design/apple-presentation-rebuild.md — the 2026-07 rebuild that
+/// replaced the visible stage picker):
+///
+/// - `.newestWins` (Prioritize lowest latency, the default): a 1-slot ring — the decoder
+///   overwrites (drops the older undisplayed frame), the render thread takes-and-clears. Zero
+///   store by construction: any deeper app-held buffer ahead of a latch-paced display becomes a
+///   STANDING queue costing one full refresh per slot, forever (the depth-2 gate post-mortem —
+///   see SessionPresenter.gateDepth).
+/// - `.fifo(capacity: K)` (Prioritize smoothness): a small deliberate jitter buffer. The
+///   decoder appends; overflow drops the OLDEST (bounded added latency — the newest keeps
+///   flowing); the render thread pops the oldest ONE per present opportunity, so the cadence is
+///   the display's. `take` withholds frames until the buffer has PREROLLED to capacity once —
+///   without preroll a steady stream drains every frame on arrival and headroom never builds —
+///   and re-arms preroll when it runs dry (an underflow: the previous frame persists on glass,
+///   a repeat by omission, while headroom rebuilds). Each buffered frame ≈ one refresh interval
+///   of jitter absorbed for one interval of added display latency, which the metrics SHOW —
+///   only the OS present floor is shaved from the HUD, never the user's chosen buffer.
+///
+/// Sendable; lock-guarded — decoder callbacks and the render thread cross here.
+public enum FrameStorePolicy: Sendable, Equatable {
+    case newestWins
+    case fifo(capacity: Int)
+}
+
+public final class FrameStore<Frame>: @unchecked Sendable {
     private let lock = NSLock()
-    private var frame: ReadyFrame?
-    /// Ring submissions since the last `drainSubmitted` — the decode rate for the
-    /// PUNKTFUNK_PRESENT_DEBUG stat line.
+    private let capacity: Int // 1 = newest-wins semantics
+    private let isFifo: Bool
+    private var frames: [Frame] = []
+    private var prerolled = false
+    /// Submissions since the last `drainSubmitted` — the decode rate for the pf-present line.
     private var submitted = 0
-    func submit(_ f: ReadyFrame) {
-        lock.lock(); frame = f; submitted += 1; lock.unlock()
+    /// Smoothness accounting for the pf-present line: frames dropped by a full buffer, and
+    /// runs-dry that re-armed preroll.
+    private var overflowDrops = 0
+    private var underflows = 0
+
+    public init(policy: FrameStorePolicy) {
+        switch policy {
+        case .newestWins:
+            capacity = 1
+            isFifo = false
+        case .fifo(let k):
+            capacity = max(1, k)
+            isFifo = true
+        }
     }
-    func drainSubmitted() -> Int {
-        lock.lock(); defer { lock.unlock() }
-        let n = submitted; submitted = 0; return n
-    }
-    func take() -> ReadyFrame? {
-        lock.lock(); defer { lock.unlock() }
-        let f = frame; frame = nil; return f
-    }
-    /// Return a frame the display link took but could not present (a transient `nextDrawable`
-    /// failure). Kept only while the slot is still empty — a newer decoded frame wins, so
-    /// newest-ready ordering is preserved. Without this, a failed render silently LOSES the
-    /// frame, and under the host's infinite GOP a static scene sends no replacement until the
-    /// next damage — the stale picture would persist.
-    func putBack(_ f: ReadyFrame) {
+
+    func submit(_ f: Frame) {
         lock.lock()
-        if frame == nil { frame = f }
+        if isFifo {
+            frames.append(f)
+            if frames.count > capacity {
+                frames.removeFirst() // oldest goes — bounded latency, the newest keeps flowing
+                overflowDrops += 1
+            }
+        } else {
+            frames = [f] // newest wins; the replaced frame is the intended drop point
+        }
+        submitted += 1
+        lock.unlock()
+    }
+
+    func drainSubmitted() -> Int {
+        lock.lock()
+        defer { lock.unlock() }
+        let n = submitted
+        submitted = 0
+        return n
+    }
+
+    /// Take-and-reset the smoothness counters (the pf-present `qDrop`/`qDry` stats).
+    func drainSmoothing() -> (overflowDrops: Int, underflows: Int) {
+        lock.lock()
+        defer { lock.unlock() }
+        let out = (overflowDrops, underflows)
+        overflowDrops = 0
+        underflows = 0
+        return out
+    }
+
+    func take() -> Frame? {
+        lock.lock()
+        defer { lock.unlock() }
+        if isFifo {
+            if !prerolled {
+                guard frames.count >= capacity else { return nil } // still building headroom
+                prerolled = true
+            }
+            guard !frames.isEmpty else {
+                underflows += 1 // ran dry — repeat by omission, rebuild headroom
+                prerolled = false
+                return nil
+            }
+            return frames.removeFirst()
+        }
+        let f = frames.first
+        frames.removeAll(keepingCapacity: true)
+        return f
+    }
+
+    /// Return a frame the render thread took but could not present (no drawable yet, or a
+    /// transient render failure). Newest-wins keeps it only while the slot is still empty — a
+    /// newer decoded frame wins; FIFO reinserts it at the FRONT (it is the oldest; a transient
+    /// capacity+1 is trimmed by the next submit). Without this, a failed present silently LOSES
+    /// the frame, and under the host's infinite GOP a static scene sends no replacement until
+    /// the next damage — the stale picture would persist.
+    func putBack(_ f: Frame) {
+        lock.lock()
+        if isFifo {
+            frames.insert(f, at: 0)
+        } else if frames.isEmpty {
+            frames = [f]
+        }
         lock.unlock()
     }
 }
@@ -107,63 +206,211 @@ private final class VsyncClock: @unchecked Sendable {
 /// When a ready frame is pushed to the layer — the stage-2 vs stage-3 presenter split. Same decode
 /// half, same newest-wins ring; only the present cadence differs.
 ///
-/// - `arrival` (stage-2, the default): present the moment a frame is decoded. Lowest latency while
-///   the layer's image queue is shallow — but that queue is FIFO and consumed at one drawable per
-///   refresh (iOS always vsync-latches; the macOS 26 compositor latch-paces our out-of-band
+/// - `arrival` (stage-2, the macOS default): present the moment a frame is decoded. Lowest latency
+///   while the layer's image queue is shallow — but that queue is FIFO and consumed at one drawable
+///   per refresh (iOS always vsync-latches; the macOS 26 compositor latch-paces our out-of-band
 ///   presents the same way when composited), so at stream rate ≈ refresh rate its depth is STICKY:
 ///   one early burst (session start, a Wi-Fi clump) fills it to `maximumDrawableCount` and — with
 ///   arrivals and latches then running at the same rate — it never drains. Every later frame rides
-///   ~2–3 refreshes of queue (the measured 29–30 ms display stage on 120 Hz ProMotion panels), and
+///   ~2–3 refreshes of queue (the measured 23–30 ms display stage on 120 Hz ProMotion panels), and
 ///   the full-queue regime is where host↔panel clock drift turns into periodic repeats/drops (the
 ///   "fixed-interval" jitter reports).
-/// - `glass` (stage-3, experimental): at most ONE presented-but-undisplayed drawable in flight
-///   (`PresentGate`). The render thread presents only when the previous flip reached glass (the
-///   drawable's presented handler reopens the gate and re-signals); frames decoded meanwhile
+/// - `glass` (stage-3, the tvOS default): at most a small BOUNDED number of presented-but-
+///   undisplayed drawables in flight (`PresentGate`; depth 1 — see `SessionPresenter.gateDepth`
+///   for why deeper is a regression). The render thread presents only while a gate slot is free
+///   (a drawable's presented handler reopens its slot and re-signals); frames decoded meanwhile
 ///   coalesce in the newest-wins ring. Freshness is preserved by DROPPING stale frames before
 ///   present instead of queueing them behind the display — the hidden queue latency becomes
-///   explicit, correct frame drops.
+///   explicit, correct frame drops. The residual cost: presents serialize on the on-glass
+///   callback, whose own delivery latency pushes each present ~a refresh past the frame's decode
+///   (the field-measured 14 ms display stage at 120 Hz vs the ~half-refresh floor).
+/// - `deadline` (stage-4, the iOS/iPadOS default; iOS/tvOS only — see
+///   `PresenterChoice.explicit`): a CAMetalDisplayLink vends ONE drawable per refresh
+///   (`preferredFrameLatency` 1) into a newest-wins hand-off slot, and the render thread pairs
+///   it with the newest decoded frame THE MOMENT either half arrives — usually the frame, into
+///   an already-vended drawable. The image queue cannot exist (one vended drawable in flight,
+///   ever), nothing serializes on the on-glass callback (the link's next vend is the pace), and
+///   the present is deadline-timed by the system to latch the upcoming refresh. This is the only
+///   pacing whose steady state can reach the sub-refresh display floor on the always-vsync-latch
+///   platforms; `arrival`/`glass` remain the on-device A/B rungs.
+///
+/// macOS PyroWave sessions default to `glass` even though the platform default is stage-2: burst
+/// presents into a composited (windowed) layer are the trigger pattern for the macOS DCP
+/// "mismatched swapID's" KERNEL PANIC, and the one-in-flight gate removes that pattern — see
+/// `SessionPresenter.pacing` for the full rationale.
 public enum PresentPacing: Sendable {
     case arrival
     case glass
+    case deadline
 }
 
-/// Stage-3's present gate: admits one in-flight (presented, not yet on glass) drawable. The render
-/// thread `tryAcquire`s before taking a frame; the drawable's presented handler `release`s and
-/// re-signals the render thread. `staleAfter` is insurance against a present whose handler never
-/// fires (the macOS "out-of-band presents aren't damage" hazard class — see MetalVideoPresenter's
-/// init post-mortem): rather than freezing the stream, a stuck gate force-opens after 100 ms, a
-/// visible ~10 fps degradation that PUNKTFUNK_PRESENT_DEBUG's `forced` counter exposes (it reads 0
-/// on healthy systems). Internal (not private) for unit tests. Sendable; lock-guarded — the
-/// releaser runs on a Metal callback thread.
+/// Newest-wins 1-slot hand-off box (the generic sibling of `ReadyRing`): deadline pacing's
+/// drawable stash — the link thread `put`s each update's vended drawable (replacing an
+/// unpresented older one, which just returns to the layer's pool), the render thread `take`s.
+/// `putBack` returns a taken value only while the slot is still empty, so a fresher `put` from
+/// the other thread is never clobbered by a stale return. Internal (not private) for unit tests.
+/// Sendable; lock-guarded.
+final class LatestBox<T>: @unchecked Sendable {
+    private let lock = NSLock()
+    private var value: T?
+    func put(_ v: T) { lock.lock(); value = v; lock.unlock() }
+    func putBack(_ v: T) {
+        lock.lock()
+        if value == nil { value = v }
+        lock.unlock()
+    }
+    func take() -> T? {
+        lock.lock()
+        defer { lock.unlock() }
+        let v = value
+        value = nil
+        return v
+    }
+}
+
+/// Deadline pacing's staged frame-rate hint. SessionPresenter pushes the stream rate from the
+/// MAIN thread (session start + every layout/Reconfigure); the link's own thread drains and
+/// applies it, so the CAMetalDisplayLink is only ever touched from the thread that runs it. The
+/// floor is PINNED at the stream rate — no idle ramp-down: with a low floor the link idles toward
+/// it on a static scene (infinite GOP ⇒ no frames), and the first damage frame after idle would
+/// wait out a slow tick before it could present. Empty wakes at stream rate are near-free; the
+/// PANEL still idles via VRR because no presents happen. Sendable; lock-guarded.
+private final class FrameRateHint: @unchecked Sendable {
+    private let lock = NSLock()
+    private var pending: CAFrameRateRange?
+    func stage(hz: Float) {
+        guard hz > 0 else { return }
+        lock.lock()
+        pending = CAFrameRateRange(minimum: hz, maximum: max(hz, 120), preferred: hz)
+        lock.unlock()
+    }
+    func drain() -> CAFrameRateRange? {
+        lock.lock()
+        defer { lock.unlock() }
+        let p = pending
+        pending = nil
+        return p
+    }
+}
+
+/// The CAMetalDisplayLink delegate for deadline pacing: each per-refresh update stashes its
+/// vended drawable (newest wins) and nudges the render thread — which also wakes on decoder
+/// arrivals, so whichever half completes the (frame, drawable) pair triggers the present. Also
+/// applies the staged frame-rate hint from the link's own thread. Retained by the link thread's
+/// closure (the link holds it weak); captures only the shared boxes, never the pipeline — the
+/// same no-self-capture rule as the pump/render threads.
+private final class DeadlineLinkDelegate: NSObject, CAMetalDisplayLinkDelegate {
+    private let stash: LatestBox<CAMetalDrawable>
+    private let renderSignal: DispatchSemaphore
+    private let hint: FrameRateHint
+    private let stats: PresentDebugStats?
+    /// The OS-floor sampler (design/apple-presentation-rebuild.md): every update's vend→glass
+    /// lead is recorded so its p50 becomes the "OS present floor" the HUD subtracts from the
+    /// shown display/e2e numbers. Self-adapting — reads ~2 refresh periods composited today,
+    /// would read ~1 under direct-to-display, tracks VRR rate changes.
+    private let floorMeter: LatencyMeter?
+    /// One-shot: log the link's EFFECTIVE preferredFrameLatency after the first re-assert —
+    /// reads 1 while vendLeadMs sits at ~2 periods ⇒ the scheduler ignores the request while
+    /// the layer is composited (the promotion hunt); reads 2 ⇒ the system clamped it outright.
+    private var loggedEffective = false
+
+    init(
+        stash: LatestBox<CAMetalDrawable>, renderSignal: DispatchSemaphore,
+        hint: FrameRateHint, stats: PresentDebugStats?, floorMeter: LatencyMeter?
+    ) {
+        self.stash = stash
+        self.renderSignal = renderSignal
+        self.hint = hint
+        self.stats = stats
+        self.floorMeter = floorMeter
+    }
+
+    func metalDisplayLink(_ link: CAMetalDisplayLink, needsUpdate update: CAMetalDisplayLink.Update) {
+        if let range = hint.drain(), link.preferredFrameRateRange != range {
+            link.preferredFrameRateRange = range
+        }
+        // Re-assert the minimum-latency request every update (cheap compare): it was set once
+        // before add(to:), and whether a pre-add set survives scheduling is exactly the kind of
+        // thing the vendLeadMs stat exists to catch — belt and braces.
+        if link.preferredFrameLatency != 1 { link.preferredFrameLatency = 1 }
+        if !loggedEffective {
+            loggedEffective = true
+            let range = link.preferredFrameRateRange
+            let msg = String(
+                format: "deadline link up: effective preferredFrameLatency=%.2f "
+                    + "range=%.0f-%.0f preferred=%.0f",
+                link.preferredFrameLatency, range.minimum, range.maximum, range.preferred ?? 0)
+            presentLog.info("\(msg, privacy: .public)")
+        }
+        // The link's own pipeline depth, measured: how far ahead of glass this vend runs.
+        let leadS = update.targetPresentationTimestamp - CACurrentMediaTime()
+        stats?.vendLead(ms: leadS * 1000)
+        // Same measurement into the floor meter (as a LatencyMeter sample: end = now, start =
+        // now − lead) — its 1 s p50 is the OS present floor SessionModel shaves off.
+        if leadS > 0, let floorMeter {
+            var ts = timespec()
+            clock_gettime(CLOCK_REALTIME, &ts)
+            let nowNs = Int64(ts.tv_sec) * 1_000_000_000 + Int64(ts.tv_nsec)
+            floorMeter.record(
+                ptsNs: UInt64(nowNs - Int64(leadS * 1_000_000_000)), atNs: nowNs, offsetNs: 0)
+        }
+        stash.put(update.drawable)
+        renderSignal.signal()
+    }
+}
+
+/// Stage-3's present gate: admits `capacity` in-flight (presented, not yet on glass) drawables.
+/// The render thread `tryAcquire`s before taking a frame; the drawable's presented handler
+/// `release`s and re-signals the render thread. Depth 1 fully serializes presents on the on-glass
+/// callback — which costs a refresh whenever the callback's own latency pushes the next present
+/// past a vsync; depth 2 keeps one flip queued behind the one scanning out, so a decoded frame
+/// presents immediately and latches the very next vsync while the queue still can't build (see
+/// `SessionPresenter.gateDepth` for the per-platform choice). `staleAfter` is insurance against a
+/// present whose handler never fires (the macOS "out-of-band presents aren't damage" hazard class
+/// — see MetalVideoPresenter's init post-mortem): rather than freezing the stream, a full gate
+/// force-opens a slot 100 ms after its oldest present, a visible ~10 fps degradation that
+/// PUNKTFUNK_PRESENT_DEBUG's `forced` counter exposes (it reads 0 on healthy systems). Internal
+/// (not private) for unit tests. Sendable; lock-guarded — the releaser runs on a Metal callback
+/// thread.
 final class PresentGate: @unchecked Sendable {
-    /// How long one pending present may hold the gate before it's presumed lost.
+    /// How long one pending present may hold its slot before it's presumed lost.
     static let staleAfter: CFTimeInterval = 0.1
 
     private let lock = NSLock()
-    private var pending = false
-    private var armedAt: CFTimeInterval = 0
+    private let capacity: Int
+    /// Arm instants of the in-flight presents, oldest first (≤ `capacity` entries).
+    private var armed: [CFTimeInterval] = []
     private var forced = 0
 
-    /// Arm the gate for one present. False = a present is already in flight (and not stale) —
-    /// leave the frame in the ring; the presented handler's release/re-signal (or the next
+    /// `capacity` = the in-flight present budget (clamped to ≥ 1) — see the type doc.
+    init(capacity: Int = 1) {
+        self.capacity = max(1, capacity)
+    }
+
+    /// Arm the gate for one present. False = the gate is full of live presents (none stale) —
+    /// leave the frame in the ring; a presented handler's release/re-signal (or the next
     /// display-link tick) retries with the freshest frame then.
     func tryAcquire(now: CFTimeInterval) -> Bool {
         lock.lock()
         defer { lock.unlock() }
-        if pending {
-            guard now - armedAt > Self.staleAfter else { return false }
-            forced += 1 // presumed-lost present — reopen rather than stall the stream
+        if armed.count >= capacity {
+            // Full: reopen only by presuming the OLDEST in-flight present lost (its handler
+            // never fired) rather than stalling the stream.
+            guard let oldest = armed.first, now - oldest > Self.staleAfter else { return false }
+            armed.removeFirst()
+            forced += 1
         }
-        pending = true
-        armedAt = now
+        armed.append(now)
         return true
     }
 
-    /// The in-flight present reached glass (or was dropped, or its render failed before a present
-    /// was registered) — reopen. Idempotent: a late stale-path double-release is harmless.
+    /// One in-flight present reached glass (or was dropped, or its render failed before a present
+    /// was registered) — free the oldest slot. A release with nothing in flight is a no-op; a
+    /// lost present's handler firing late after its stale force-open can transiently over-admit
+    /// one flip, which the next glass callback corrects.
     func release() {
         lock.lock()
-        pending = false
+        if !armed.isEmpty { armed.removeFirst() }
         lock.unlock()
     }
 
@@ -184,13 +431,23 @@ final class PresentGate: @unchecked Sendable {
 private final class PresentDebugStats: @unchecked Sendable {
     private let lock = NSLock()
     private var last = CACurrentMediaTime()
-    private var ok = 0, failed = 0, empty = 0, dropped = 0, gated = 0
+    private var ok = 0, failed = 0, empty = 0, dropped = 0, gated = 0, noDrawable = 0
     private var maxRenderMs = 0.0
     private var lastGlassNs: Int64 = 0
     private var glassDeltasMs: [Double] = []
+    /// Present-issue → on-glass delay per frame (system presentedTime minus the render call's
+    /// start) — the DIRECT decomposition of the display stage: ring/pairing wait lives upstream
+    /// of it, queue + present-pipeline cost inside it. Standing queue reads as ~n×period here;
+    /// a healthy latch reads under one period.
+    private var latchMs: [Double] = []
+    /// Deadline pacing: the link's own pipeline depth — `targetPresentationTimestamp - now` at
+    /// each update. ~1 period means preferredFrameLatency=1 is honored (a vended drawable can
+    /// reach glass at the NEXT refresh); ~2 periods means the system is running a frame ahead
+    /// and one whole refresh of the display stage lives INSIDE the link, not in our pairing.
+    private var vendLeadMs: [Double] = []
     /// Presented-but-not-yet-on-glass drawables right now / the window's peak — the direct
     /// measurement of the layer image-queue depth the stage-3 gate exists to bound (stage-2 on a
-    /// 120 Hz panel saturates this at ~maximumDrawableCount; stage-3 should peg it at 1).
+    /// 120 Hz panel saturates this at ~maximumDrawableCount; stage-3 pegs it at the gate depth).
     private var inFlight = 0
     private var maxInFlight = 0
 
@@ -201,6 +458,14 @@ private final class PresentDebugStats: @unchecked Sendable {
     /// is normal, it just shows the gate working.
     func gatedWake() { lock.lock(); gated += 1; lock.unlock() }
 
+    /// Deadline pacing: a decoded frame is waiting but the link hasn't vended this interval's
+    /// drawable yet — the frame presents on the link's next update. A high count just means
+    /// decode outruns the link's phase; the wait is bounded by one refresh.
+    func noDrawableWake() { lock.lock(); noDrawable += 1; lock.unlock() }
+
+    /// Deadline pacing, LINK thread: one update's vend-to-target distance (see `vendLeadMs`).
+    func vendLead(ms: Double) { lock.lock(); vendLeadMs.append(ms); lock.unlock() }
+
     func renderReturned(ok rendered: Bool, tookMs: Double) {
         lock.lock()
         if rendered {
@@ -214,40 +479,59 @@ private final class PresentDebugStats: @unchecked Sendable {
         lock.unlock()
     }
 
-    func presented(atNs: Int64?) {
+    func presented(atNs: Int64?, issuedNs: Int64) {
         lock.lock()
         inFlight = max(0, inFlight - 1) // clamp: the handler can beat renderReturned's increment
         if let atNs {
             if lastGlassNs > 0 { glassDeltasMs.append(Double(atNs - lastGlassNs) / 1e6) }
             lastGlassNs = atNs
+            latchMs.append(Double(atNs - issuedNs) / 1e6)
         } else {
             dropped += 1
         }
         lock.unlock()
     }
 
-    func flushIfDue(ring: ReadyRing, gate: PresentGate?) {
+    func flushIfDue(ring: FrameStore<ReadyFrame>, gate: PresentGate?) {
         lock.lock()
         let now = CACurrentMediaTime()
         guard now - last >= 1 else { lock.unlock(); return }
         last = now
         let decoded = ring.drainSubmitted()
+        let smoothing = ring.drainSmoothing()
         let deltas = glassDeltasMs.sorted()
         let p50 = deltas.isEmpty ? 0 : deltas[deltas.count / 2]
         let dMax = deltas.last ?? 0
+        let latches = latchMs.sorted()
+        let latchP50 = latches.isEmpty ? 0 : latches[latches.count / 2]
+        let latchMax = latches.last ?? 0
+        let vends = vendLeadMs.sorted()
+        let vendP50 = vends.isEmpty ? 0 : vends[vends.count / 2]
+        let vendMax = vends.last ?? 0
         let inflightMax = maxInFlight
         let line = String(
-            format: "pf-present decoded=%d ok=%d fail=%d empty=%d gated=%d dropped=%d "
-                + "maxRenderMs=%.1f inflightMax=%d forced=%d glassDeltaMs p50=%.2f max=%.2f n=%d",
-            decoded, ok, failed, empty, gated, dropped, maxRenderMs, inflightMax,
-            gate?.drainForced() ?? 0, p50, dMax, deltas.count)
-        ok = 0; failed = 0; empty = 0; dropped = 0; gated = 0
+            format: "pf-present decoded=%d ok=%d fail=%d empty=%d gated=%d noDrawable=%d "
+                + "dropped=%d qDrop=%d qDry=%d maxRenderMs=%.1f inflightMax=%d forced=%d "
+                + "glassDeltaMs p50=%.2f max=%.2f n=%d latchMs p50=%.2f max=%.2f "
+                + "vendLeadMs p50=%.2f max=%.2f",
+            decoded, ok, failed, empty, gated, noDrawable, dropped,
+            smoothing.overflowDrops, smoothing.underflows, maxRenderMs, inflightMax,
+            gate?.drainForced() ?? 0, p50, dMax, deltas.count, latchP50, latchMax,
+            vendP50, vendMax)
+        ok = 0; failed = 0; empty = 0; dropped = 0; gated = 0; noDrawable = 0
         maxRenderMs = 0
         maxInFlight = inFlight // the window peak restarts from the live depth
         glassDeltasMs.removeAll(keepingCapacity: true)
+        latchMs.removeAll(keepingCapacity: true)
+        vendLeadMs.removeAll(keepingCapacity: true)
         lock.unlock()
-        print(line)
-        fflush(stdout) // stdout is a pipe when captured — flush per line or nothing shows
+        // Console.app first (the on-device readout — see presentLog); stdout only under the env
+        // lever (the CLI client's capture channel).
+        presentLog.info("\(line, privacy: .public)")
+        if presentDebug {
+            print(line)
+            fflush(stdout) // stdout is a pipe when captured — flush per line or nothing shows
+        }
     }
 }
 
@@ -274,15 +558,27 @@ private final class DecodeReport: @unchecked Sendable {
 }
 
 public final class Stage2Pipeline {
-    private let ring = ReadyRing()
+    private let ring: FrameStore<ReadyFrame>
     private let presenter: MetalVideoPresenter
     private let decoder: VideoDecoder
-    /// Present cadence — `.arrival` (stage-2) or `.glass` (stage-3, the present gate). Fixed for
-    /// the pipeline's lifetime; SessionPresenter resolves it per session (see PresentPacing).
+    /// Present cadence — `.arrival` (stage-2), `.glass` (stage-3, the present gate) or
+    /// `.deadline` (stage-4, the CAMetalDisplayLink engine). Fixed for the pipeline's lifetime;
+    /// SessionPresenter resolves it per session (see PresentPacing).
     private let pacing: PresentPacing
+    /// The glass gate's in-flight present budget (`PresentGate` capacity) — meaningful only under
+    /// `.glass`; SessionPresenter resolves it per platform (see `SessionPresenter.gateDepth`).
+    private let gateDepth: Int
+    /// macOS smoothness: pace presents onto the vsync grid (`present(at:)` via the VsyncClock),
+    /// at most one per vsync, so the FIFO store drains on the display's cadence rather than on
+    /// arrival. Ignored under `.deadline` (the link IS the cadence there).
+    private let vsyncPaced: Bool
     private let endToEndMeter: LatencyMeter?
     private let decodeMeter: LatencyMeter?
     private let displayMeter: LatencyMeter?
+    /// The measured OS present floor (deadline pacing only): each link update's vend→glass lead
+    /// is recorded here, and its p50 is what SessionModel subtracts from the shown display/e2e
+    /// numbers — the pipeline-depth cost no client controls (design/apple-presentation-rebuild.md).
+    private let presentFloorMeter: LatencyMeter?
     private let recovery = KeyframeRecovery()
     /// Feeds the core Automatic-bitrate controller's decode signal from the decode callback; `start`
     /// binds the live connection + arming flag (see DecodeReport).
@@ -313,6 +609,9 @@ public final class Stage2Pipeline {
     private let vsyncClock = VsyncClock()
     private let renderStopped = DispatchSemaphore(value: 0)
     private var renderJoinable = false
+    /// Deadline pacing's staged CAMetalDisplayLink frame-rate hint (see `FrameRateHint`).
+    /// Created unconditionally (cheap); only the deadline link thread drains it.
+    private let frameRateHint = FrameRateHint()
 
     /// The Metal layer the hosting view installs + sizes.
     public var layer: CAMetalLayer { presenter.layer }
@@ -323,19 +622,28 @@ public final class Stage2Pipeline {
     /// render + vsync — the tail stage-2 exists to shorten). All optional: metering never gates
     /// the presenter choice. Returns nil if Metal can't be set up (headless / no GPU) — caller
     /// falls back to the stage-1 presenter. `pacing` selects the stage-2 (arrival) vs stage-3
-    /// (glass-gated) present cadence — see PresentPacing.
+    /// (glass-gated) present cadence — see PresentPacing; `gateDepth` is the glass gate's
+    /// in-flight present budget (see `SessionPresenter.gateDepth`).
     public init?(
         endToEndMeter: LatencyMeter?,
         decodeMeter: LatencyMeter? = nil,
         displayMeter: LatencyMeter? = nil,
-        pacing: PresentPacing = .arrival
+        presentFloorMeter: LatencyMeter? = nil,
+        pacing: PresentPacing = .arrival,
+        gateDepth: Int = 1,
+        storePolicy: FrameStorePolicy = .newestWins,
+        vsyncPaced: Bool = false
     ) {
         guard let presenter = MetalVideoPresenter.make() else { return nil }
         self.presenter = presenter
         self.pacing = pacing
+        self.gateDepth = gateDepth
+        self.vsyncPaced = vsyncPaced
+        self.ring = FrameStore(policy: storePolicy)
         self.endToEndMeter = endToEndMeter
         self.decodeMeter = decodeMeter
         self.displayMeter = displayMeter
+        self.presentFloorMeter = presentFloorMeter
         let ring = ring
         let recovery = recovery
         let renderSignal = renderSignal
@@ -510,6 +818,17 @@ public final class Stage2Pipeline {
         pumpJoinable = true
         thread.start()
 
+        // The present half. Deadline pacing (stage-4) swaps it wholesale: a CAMetalDisplayLink
+        // vends the drawables and its per-refresh updates co-drive the render thread — see
+        // startDeadlinePresenter. The V-Sync policy below doesn't apply there (the link deadline-
+        // times every present). Deadline sessions ALWAYS carry the stats (their pf-present line
+        // streams to Console.app via presentLog — the on-device pacing decomposition).
+        let debugStats = (presentDebug || pacing == .deadline) ? PresentDebugStats() : nil
+        if pacing == .deadline {
+            startDeadlinePresenter(debugStats: debugStats)
+            return
+        }
+
         // The render thread: one present per display-link signal. It owns every layer format/colour/
         // drawable interaction (see MetalVideoPresenter's threading notes); with displaySyncEnabled on,
         // nextDrawable's up-to-a-frame wait lands here instead of on main. The 100 ms timed wait is
@@ -524,16 +843,21 @@ public final class Stage2Pipeline {
         // lowest-latency behavior); PUNKTFUNK_PRESENT_MODE=immediate|vsync overrides it for A/B.
         // Resolved once per session.
         let presentMode = ProcessInfo.processInfo.environment["PUNKTFUNK_PRESENT_MODE"]
-        let vsyncEnabled = presentMode == "vsync"
+        // `vsyncPaced` (macOS smoothness) FORCES vsync scheduling — the FIFO store must drain
+        // on the display cadence, one frame per vsync, or the buffer degenerates to arrival.
+        let vsyncPaced = vsyncPaced
+        let vsyncEnabled = vsyncPaced || presentMode == "vsync"
             || (presentMode != "immediate"
                 && UserDefaults.standard.bool(forKey: DefaultsKey.vsync))
-        let debugStats = presentDebug ? PresentDebugStats() : nil
         let vsyncClock = vsyncClock
-        // Stage-3's one-in-flight present gate; nil = stage-2's present-on-arrival. A local (like
-        // the ring) so neither the render thread nor the presented handlers capture `self`.
-        let gate: PresentGate? = pacing == .glass ? PresentGate() : nil
+        // Stage-3's bounded in-flight present gate; nil = stage-2's present-on-arrival. A local
+        // (like the ring) so neither the render thread nor the presented handlers capture `self`.
+        let gate: PresentGate? = pacing == .glass ? PresentGate(capacity: gateDepth) : nil
         let renderThread = Thread {
             defer { renderStopped.signal() }
+            // macOS smoothness: the vsync this thread last presented onto — at most ONE present
+            // per vsync so the FIFO drains on the display's cadence. Thread-confined.
+            var lastPresentTarget: CFTimeInterval = 0
             // Every iteration drains its own autorelease pool (`return` = the old `continue`):
             // this thread has no runloop, and `nextDrawable()` AUTORELEASES each CAMetalDrawable —
             // without a per-iteration pool every presented frame's drawable object (plus its
@@ -543,6 +867,15 @@ public final class Stage2Pipeline {
                     debugStats?.flushIfDue(ring: ring, gate: gate)
                     return
                 }
+                // Smoothness pacing: this vsync's present slot already taken — the frame stays
+                // in the store, and the next display-link tick re-signals. (Tolerance well under
+                // any refresh period; a stale clock ⇒ nil target ⇒ no dedup, present flows.)
+                if vsyncPaced, let t = vsyncClock.nextVsync(after: CACurrentMediaTime()),
+                   abs(t - lastPresentTarget) < 0.002 {
+                    debugStats?.gatedWake()
+                    debugStats?.flushIfDue(ring: ring, gate: gate)
+                    return
+                }
                 // Stage-3: while a present is in flight, don't take from the ring at all — frames
                 // keep coalescing there (newest wins, the intended drop point) and the presented
                 // handler re-signals the moment the slot frees. Checked BEFORE the take so a gated
@@ -563,6 +896,7 @@ public final class Stage2Pipeline {
                 let presentAt = vsyncEnabled
                     ? vsyncClock.nextVsync(after: CACurrentMediaTime()) : nil
                 let renderStarted = CACurrentMediaTime()
+                let issuedNs = Stage2Pipeline.realtimeNs(forDisplayLinkTimestamp: renderStarted)
                 let onGlass: (Int64?) -> Void = { presentedNs in
                     // Stage-3: the flip reached glass (or was dropped) — free the present slot,
                     // then re-signal so the freshest waiting ring frame goes out immediately.
@@ -580,7 +914,7 @@ public final class Stage2Pipeline {
                     // Display stage = decoded → on-glass. Both instants are client CLOCK_REALTIME,
                     // so no skew offset applies.
                     displayMeter?.record(ptsNs: UInt64(frame.decodedNs), atNs: atNs, offsetNs: 0)
-                    debugStats?.presented(atNs: presentedNs)
+                    debugStats?.presented(atNs: presentedNs, issuedNs: issuedNs)
                 }
                 // One present tail, two decode sources: the VideoToolbox biplanar buffer or the
                 // PyroWave Metal planes — the ring, pacing and meters are agnostic to which.
@@ -599,6 +933,8 @@ public final class Stage2Pipeline {
                 if !rendered {
                     gate?.release() // no present registered — its handler will never fire
                     ring.putBack(frame)
+                } else if vsyncPaced, let presentAt {
+                    lastPresentTarget = presentAt // this vsync's slot is now taken
                 }
                 debugStats?.flushIfDue(ring: ring, gate: gate)
             } }
@@ -609,22 +945,186 @@ public final class Stage2Pipeline {
         renderThread.start()
     }
 
+    /// Deadline pacing's present half (stage-4 — see `PresentPacing.deadline`): a
+    /// CAMetalDisplayLink on its own runloop thread vends ONE drawable per refresh into the
+    /// newest-wins stash, and the render thread pairs it with the newest decoded frame the
+    /// moment either half completes the pair — the common case is a decoded frame presenting
+    /// instantly into an already-vended drawable, which the system then latches at the upcoming
+    /// refresh (`preferredFrameLatency` 1). No image queue can form (one vended drawable in
+    /// flight, ever) and nothing serializes on the on-glass callback. An unpresented stashed
+    /// drawable is simply replaced by the next update (back to the layer's pool), so the stash
+    /// is never stale by more than a refresh while the link runs.
+    ///
+    /// Threading mirrors the arrival/glass half: neither thread captures `self`; the link is
+    /// created, driven and invalidated entirely on its own thread (CAMetalDisplayLink is only
+    /// ever touched there — the frame-rate hint crosses via `FrameRateHint`); the link thread's
+    /// runloop iterations each drain an autorelease pool (a vended CAMetalDrawable is
+    /// autoreleased like a `nextDrawable()` one — see the render loop's identical rule); the
+    /// 100 ms runloop horizon is the stop-flag poll, so teardown is bounded without a join.
+    private func startDeadlinePresenter(debugStats: PresentDebugStats?) {
+        let token = token
+        let ring = ring
+        let renderSignal = renderSignal
+        let renderStopped = renderStopped
+        let presenter = presenter
+        let endToEndMeter = endToEndMeter
+        let displayMeter = displayMeter
+        let offsetNs = offsetNs
+        let hint = frameRateHint
+        let layer = presenter.layer
+        let stash = LatestBox<CAMetalDrawable>()
+
+        let floorMeter = presentFloorMeter
+        // The link starts LAZILY — the render thread triggers this after the FIRST decoded
+        // frame's reconcileLayer. Started eagerly it vends into the layer's initial 0×0
+        // drawableSize for the whole connect window: every vend fails allocation and the system
+        // logs "[CAMetalLayer nextDrawable] returning nil because allocation failed" once per
+        // refresh until the first frame arrives. Before that frame there is nothing to present
+        // anyway, and the first frame waits at most one refresh for the first vend.
+        let startLink: () -> Void = {
+            let linkThread = Thread {
+                let delegate = DeadlineLinkDelegate(
+                    stash: stash, renderSignal: renderSignal, hint: hint, stats: debugStats,
+                    floorMeter: floorMeter)
+                let link = CAMetalDisplayLink(metalLayer: layer)
+                link.preferredFrameLatency = 1 // wake as late as fits: latch the NEXT refresh
+                if let range = hint.drain() { link.preferredFrameRateRange = range }
+                link.delegate = delegate // weak — this closure is the strong ref
+                link.add(to: RunLoop.current, forMode: .default)
+                while !token.isStopped {
+                    autoreleasepool {
+                        _ = RunLoop.current.run(
+                            mode: .default, before: Date(timeIntervalSinceNow: 0.1))
+                    }
+                }
+                link.invalidate()
+            }
+            linkThread.name = "punktfunk-stage4-link"
+            linkThread.qualityOfService = .userInteractive
+            linkThread.start()
+        }
+
+        let renderThread = Thread {
+            defer { renderStopped.signal() }
+            // Whether startLink ran — render-thread confined (only this thread triggers it).
+            var linkLive = false
+            // Per-iteration autorelease pool — same contract as the arrival/glass loop (the
+            // vended drawable and its retinue are autoreleased objects on a runloop-less thread).
+            while !token.isStopped { autoreleasepool {
+                if renderSignal.wait(timeout: .now() + .milliseconds(100)) == .timedOut {
+                    debugStats?.flushIfDue(ring: ring, gate: nil)
+                    return
+                }
+                // Present needs the PAIR — frame first. The frame drives the layer reconcile,
+                // which must run even when NO drawable is vended yet: the link vends from the
+                // layer's CURRENT config, so drawableSize/format have to be right before a vend
+                // can succeed at all (see reconcileLayer — the session-start bootstrap, where
+                // the layer still has its initial 0×0 size and every vend fails allocation).
+                guard !token.isStopped, let frame = ring.take() else {
+                    debugStats?.emptyWake()
+                    debugStats?.flushIfDue(ring: ring, gate: nil)
+                    return
+                }
+                switch frame.image {
+                case .video(let pixelBuffer, let isHDR):
+                    presenter.reconcileLayer(
+                        decodedSize: CGSize(
+                            width: CVPixelBufferGetWidth(pixelBuffer),
+                            height: CVPixelBufferGetHeight(pixelBuffer)),
+                        isHDR: isHDR)
+                case .planar(let planes):
+                    presenter.reconcileLayer(
+                        decodedSize: CGSize(width: planes.width, height: planes.height),
+                        isHDR: planes.pq)
+                }
+                // First frame: the layer now has a real config — start vending (see startLink).
+                if !linkLive {
+                    linkLive = true
+                    startLink()
+                }
+                guard let drawable = stash.take() else {
+                    // No vend yet (session start: the reconcile above just unblocked the
+                    // allocator, the link's next update delivers; steady state: decode beat the
+                    // link's phase). putBack keeps newest-wins — a fresher decode replaces this
+                    // frame while it waits, and the update's signal retries the pairing.
+                    ring.putBack(frame)
+                    debugStats?.noDrawableWake()
+                    debugStats?.flushIfDue(ring: ring, gate: nil)
+                    return
+                }
+                let renderStarted = CACurrentMediaTime()
+                let issuedNs = Stage2Pipeline.realtimeNs(forDisplayLinkTimestamp: renderStarted)
+                let onGlass: (Int64?) -> Void = { presentedNs in
+                    let atNs = presentedNs
+                        ?? Stage2Pipeline.realtimeNs(forDisplayLinkTimestamp: CACurrentMediaTime())
+                    endToEndMeter?.record(ptsNs: frame.ptsNs, atNs: atNs, offsetNs: offsetNs)
+                    displayMeter?.record(ptsNs: UInt64(frame.decodedNs), atNs: atNs, offsetNs: 0)
+                    debugStats?.presented(atNs: presentedNs, issuedNs: issuedNs)
+                }
+                let rendered: Bool
+                switch frame.image {
+                case .video(let pixelBuffer, let isHDR):
+                    rendered = presenter.render(
+                        pixelBuffer, isHDR: isHDR, into: drawable, onPresented: onGlass)
+                case .planar(let planes):
+                    rendered = presenter.renderPlanar(
+                        planes, into: drawable, onPresented: onGlass)
+                }
+                debugStats?.renderReturned(
+                    ok: rendered, tookMs: (CACurrentMediaTime() - renderStarted) * 1000)
+                if !rendered {
+                    // The vended drawable is spent either way (an unused/mismatched one drops
+                    // back to the pool); the frame retries on the link's next vend. A format
+                    // mismatch (mid-session HDR flip caught between the layer reconfigure and
+                    // the next vend) self-heals the same way — see encodePresent's guard.
+                    ring.putBack(frame)
+                }
+                debugStats?.flushIfDue(ring: ring, gate: nil)
+            } }
+        }
+        renderThread.name = "punktfunk-stage2-render"
+        renderThread.qualityOfService = .userInteractive
+        renderJoinable = true
+        renderThread.start()
+    }
+
     /// MAIN thread, once per display-link tick: refresh the vsync clock (V-Sync-mode scheduling)
     /// and nudge the render thread. The nudge is NOT the presentation trigger — frame arrival is
     /// (see the header) — it only retries a frame a transient `nextDrawable` failure put back into
     /// the ring, which matters under the host's infinite GOP where a static scene sends no
-    /// replacement frame.
+    /// replacement frame. Arrival/glass pacing only — deadline sessions have no CADisplayLink
+    /// (their CAMetalDisplayLink's updates are both clock and retry).
     public func renderTick(targetMediaTime: CFTimeInterval, period: CFTimeInterval) {
         vsyncClock.set(target: targetMediaTime, period: period)
         renderSignal.signal()
     }
 
+    /// MAIN thread (SessionPresenter — session start + every layout/Reconfigure): hint the
+    /// deadline link with the stream cadence. Staged; the link's own thread applies it (see
+    /// `FrameRateHint`). No-op under arrival/glass pacing, where the hosting view's CADisplayLink
+    /// is the hinted link.
+    public func setFrameRateHint(hz: Float) {
+        frameRateHint.stage(hz: hz)
+    }
+
     /// Forward the layout-derived drawable pixel size to the presenter (MAIN thread — see
     /// `MetalVideoPresenter.setDrawableTarget`).
     public func setDrawableTarget(_ size: CGSize) {
         presenter.setDrawableTarget(size)
     }
 
+    #if os(macOS)
+    /// The windowed-mode PyroWave present target (see `MetalVideoPresenter.surfaceLayer` — the
+    /// DCP swapID-panic mitigation). The hosting view installs it as a sibling above `layer`.
+    public var surfaceLayer: CALayer { presenter.surfaceLayer }
+
+    /// Forward the windowed-vs-fullscreen present routing (MAIN thread — see
+    /// `MetalVideoPresenter.setSurfacePresents`).
+    public func setSurfacePresents(_ on: Bool) {
+        presenter.setSurfacePresents(on)
+    }
+    #endif
+
     /// Forward the display's current EDR headroom to the presenter (MAIN thread — a `UIScreen`
     /// read). tvOS flips HDR presentation between PQ passthrough and the in-shader tone-map on
     /// it; see `MetalVideoPresenter.setDisplayHeadroom`.
@@ -669,7 +1169,7 @@ public final class Stage2Pipeline {
     /// reason the VT pump avoids capturing `self` (a missed stop must not leak a live pipeline).
     private static func makePyroWavePump(
         connection: PunktfunkConnection, token: StopFlag, pumpStopped: DispatchSemaphore,
-        ring: ReadyRing, renderSignal: DispatchSemaphore,
+        ring: FrameStore<ReadyFrame>, renderSignal: DispatchSemaphore,
         device: MTLDevice, queue: MTLCommandQueue,
         decodeMeter: LatencyMeter?,
         onFrame: (@Sendable (AccessUnit) -> Void)?,

clients/apple/Sources/PunktfunkKit/Video/Stage444Probe.swift

@@ -65,19 +65,21 @@ public enum Stage444Probe {
         guard let sample = AnnexB.sampleBuffer(au: au, format: format, codec: .hevc) else { return false }
 
         var produced: OSType = 0
-        let done = DispatchSemaphore(value: 0)
+        // SYNCHRONOUS decode — no `._EnableAsynchronousDecompression`, so the output callback
+        // runs on THIS thread before DecodeFrame returns. The async flag + semaphore wait it
+        // replaced tripped the Thread Performance Checker on every first connect: VideoToolbox's
+        // callback thread carries no QoS class, and the userInteractive connect Task blocked on
+        // it through the semaphore (a priority inversion). A one-shot 256×256 probe gains
+        // nothing from decode parallelism; the lazy statics still cache the result.
         let status = VTDecompressionSessionDecodeFrame(
             session, sampleBuffer: sample,
-            flags: [._EnableAsynchronousDecompression], infoFlagsOut: nil
+            flags: [], infoFlagsOut: nil
         ) { status, _, imageBuffer, _, _ in
             if status == noErr, let imageBuffer {
                 produced = CVPixelBufferGetPixelFormatType(imageBuffer)
             }
-            done.signal()
         }
         guard status == noErr else { return false }
-        VTDecompressionSessionWaitForAsynchronousFrames(session)
-        _ = done.wait(timeout: .now() + 1.0)
         return produced == want || produced == fullRangeSibling
     }
 }

clients/apple/Sources/PunktfunkKit/Views/StreamView.swift

@@ -93,6 +93,7 @@ public struct StreamView: NSViewRepresentable {
     private let endToEndMeter: LatencyMeter?
     private let decodeMeter: LatencyMeter?
     private let displayMeter: LatencyMeter?
+    private let presentFloorMeter: LatencyMeter?
 
     /// `onFrame`/`onSessionEnd` fire on the pump thread — hop to the main actor for UI.
     /// `captureEnabled: false` disables input capture entirely while UI (e.g. a trust
@@ -115,7 +116,8 @@ public struct StreamView: NSViewRepresentable {
         onDecodedSize: (@Sendable (Int, Int) -> Void)? = nil,
         endToEndMeter: LatencyMeter? = nil,
         decodeMeter: LatencyMeter? = nil,
-        displayMeter: LatencyMeter? = nil
+        displayMeter: LatencyMeter? = nil,
+        presentFloorMeter: LatencyMeter? = nil
     ) {
         self.connection = connection
         self.captureEnabled = captureEnabled
@@ -128,6 +130,7 @@ public struct StreamView: NSViewRepresentable {
         self.endToEndMeter = endToEndMeter
         self.decodeMeter = decodeMeter
         self.displayMeter = displayMeter
+        self.presentFloorMeter = presentFloorMeter
     }
 
     public func makeNSView(context: Context) -> StreamLayerView {
@@ -138,6 +141,7 @@ public struct StreamView: NSViewRepresentable {
         view.endToEndMeter = endToEndMeter
         view.decodeMeter = decodeMeter
         view.displayMeter = displayMeter
+        view.presentFloorMeter = presentFloorMeter
         view.onResizeTarget = onResizeTarget
         view.onDecodedSize = onDecodedSize
         view.start(connection: connection, onFrame: onFrame, onSessionEnd: onSessionEnd)
@@ -151,6 +155,7 @@ public struct StreamView: NSViewRepresentable {
         view.endToEndMeter = endToEndMeter
         view.decodeMeter = decodeMeter
         view.displayMeter = displayMeter
+        view.presentFloorMeter = presentFloorMeter
         view.onResizeTarget = onResizeTarget
         view.onDecodedSize = onDecodedSize
         // SwiftUI reuses the NSView across state changes — repoint the pump only when the
@@ -172,6 +177,7 @@ public final class StreamLayerView: NSView {
     var endToEndMeter: LatencyMeter?
     var decodeMeter: LatencyMeter?
     var displayMeter: LatencyMeter?
+    var presentFloorMeter: LatencyMeter?
     /// The shared presenter stack: stage-2 (CAMetalLayer sublayer + display link) with the
     /// stage-1 StreamPump → displayLayer path as the Metal-unavailable / DEBUG fallback.
     private let presenter = SessionPresenter()
@@ -661,6 +667,7 @@ public final class StreamLayerView: NSView {
             endToEndMeter: endToEndMeter,
             decodeMeter: decodeMeter,
             displayMeter: displayMeter,
+            presentFloorMeter: presentFloorMeter,
             makeDisplayLink: { displayLink(target: $0, selector: $1) },
             onFrame: onFrame,
             onSessionEnd: onSessionEnd,
@@ -692,6 +699,11 @@ public final class StreamLayerView: NSView {
     /// the view's physical-pixel size (bounds → backing), so a window resize / retina move follows.
     private func layoutPresenter() {
         presenter.layout(in: bounds, contentsScale: window?.backingScaleFactor ?? 1)
+        // Present routing tracks the window's composited state (fullscreen transitions always
+        // re-layout, so this stays current): windowed PyroWave presents via surface contents —
+        // the DCP swapID kernel-panic mitigation (see SessionPresenter.setComposited). A view
+        // not yet in a window counts as composited (the safe default).
+        presenter.setComposited(!(window?.styleMask.contains(.fullScreen) ?? false))
         // Feed the follower only once in a window (backing scale is real then) and with real
         // bounds — a pre-window layout would report point-sized dimensions.
         if window != nil, bounds.width > 0, bounds.height > 0 {

clients/apple/Sources/PunktfunkKit/Views/StreamViewIOS.swift

@@ -61,6 +61,7 @@ public struct StreamView: UIViewControllerRepresentable {
     private let endToEndMeter: LatencyMeter?
     private let decodeMeter: LatencyMeter?
     private let displayMeter: LatencyMeter?
+    private let presentFloorMeter: LatencyMeter?
 
     /// `onDisconnectRequest` exists for call-site parity with the macOS StreamView (the
     /// captured-state ⌃⌥⇧D combo is detected by the macOS NSEvent monitor only); on iOS a
@@ -77,7 +78,8 @@ public struct StreamView: UIViewControllerRepresentable {
         onDecodedSize: (@Sendable (Int, Int) -> Void)? = nil,
         endToEndMeter: LatencyMeter? = nil,
         decodeMeter: LatencyMeter? = nil,
-        displayMeter: LatencyMeter? = nil
+        displayMeter: LatencyMeter? = nil,
+        presentFloorMeter: LatencyMeter? = nil
     ) {
         self.connection = connection
         self.captureEnabled = captureEnabled
@@ -89,6 +91,7 @@ public struct StreamView: UIViewControllerRepresentable {
         self.endToEndMeter = endToEndMeter
         self.decodeMeter = decodeMeter
         self.displayMeter = displayMeter
+        self.presentFloorMeter = presentFloorMeter
     }
 
     public func makeUIViewController(context: Context) -> StreamViewController {
@@ -98,6 +101,7 @@ public struct StreamView: UIViewControllerRepresentable {
         controller.endToEndMeter = endToEndMeter
         controller.decodeMeter = decodeMeter
         controller.displayMeter = displayMeter
+        controller.presentFloorMeter = presentFloorMeter
         controller.onResizeTarget = onResizeTarget
         controller.onDecodedSize = onDecodedSize
         controller.start(connection: connection, onFrame: onFrame, onSessionEnd: onSessionEnd)
@@ -110,6 +114,7 @@ public struct StreamView: UIViewControllerRepresentable {
         controller.endToEndMeter = endToEndMeter
         controller.decodeMeter = decodeMeter
         controller.displayMeter = displayMeter
+        controller.presentFloorMeter = presentFloorMeter
         controller.onResizeTarget = onResizeTarget
         controller.onDecodedSize = onDecodedSize
         if controller.connection !== connection {
@@ -145,6 +150,7 @@ public final class StreamViewController: StreamViewControllerBase {
     var endToEndMeter: LatencyMeter?
     var decodeMeter: LatencyMeter?
     var displayMeter: LatencyMeter?
+    var presentFloorMeter: LatencyMeter?
     /// The shared presenter stack: stage-2 (CAMetalLayer sublayer + display link) with the
     /// stage-1 StreamPump → displayLayer path as the Metal-unavailable / DEBUG fallback.
     private let presenter = SessionPresenter()
@@ -406,6 +412,7 @@ public final class StreamViewController: StreamViewControllerBase {
             endToEndMeter: endToEndMeter,
             decodeMeter: decodeMeter,
             displayMeter: displayMeter,
+            presentFloorMeter: presentFloorMeter,
             makeDisplayLink: { CADisplayLink(target: $0, selector: $1) },
             onFrame: onFrame,
             onSessionEnd: onSessionEnd,

clients/apple/Sources/PunktfunkShared/BrandColor.swift

@@ -0,0 +1,30 @@
+// The brand color, in the dependency-free foundation so EVERY process can use it — the widget
+// extension links PunktfunkShared alone (never PunktfunkKit's Rust staticlib), and before this
+// moved here the Live Activity / widgets fell back to `.tint` = system blue.
+
+import SwiftUI
+
+public extension Color {
+    /// The punktfunk brand purple (the app-icon lens / website `--brand`). Defined explicitly,
+    /// independent of the asset-catalog accent — `Color.accentColor` resolution is environment- and
+    /// timing-sensitive (it can fall back to system blue), and the brand mark must never drift.
+    /// Light: #6656F2, Dark: #8678F5 (the lighter violet reads better on dark surfaces).
+    static let brand: Color = {
+        #if canImport(UIKit)
+        return Color(UIColor { traits in
+            traits.userInterfaceStyle == .dark
+                ? UIColor(red: 0x86 / 255, green: 0x78 / 255, blue: 0xF5 / 255, alpha: 1)
+                : UIColor(red: 0x66 / 255, green: 0x56 / 255, blue: 0xF2 / 255, alpha: 1)
+        })
+        #elseif canImport(AppKit)
+        return Color(NSColor(name: nil) { appearance in
+            appearance.bestMatch(from: [.aqua, .darkAqua]) == .darkAqua
+                ? NSColor(red: 0x86 / 255, green: 0x78 / 255, blue: 0xF5 / 255, alpha: 1)
+                : NSColor(red: 0x66 / 255, green: 0x56 / 255, blue: 0xF2 / 255, alpha: 1)
+        })
+        #else
+        // Non-Apple fallback: the light brand value, so all branches agree on a canonical color.
+        return Color(red: 0x66 / 255, green: 0x56 / 255, blue: 0xF2 / 255)
+        #endif
+    }()
+}

clients/apple/Sources/PunktfunkShared/DefaultsKeys.swift

@@ -50,12 +50,21 @@ public enum DefaultsKey {
     /// discrete channel, and the default N→stereo downmix grabs channels 0/1 (silence when the mic
     /// is higher up), so we fold to mono ourselves. Only meaningful for multi-channel devices.
     public static let micChannel = "punktfunk.micChannel"
-    /// Which presenter runs a session: "stage2" (default — explicit decode + Metal present on
-    /// frame arrival), "stage3" (same pipeline, glass-gated present pacing — the experimental
-    /// low-display-latency A/B; see Stage2Pipeline's PresentPacing), or "stage1" (DEBUG-only
-    /// system-layer fallback). Resolved once per session by SessionPresenter;
-    /// PUNKTFUNK_PRESENTER=stage1|stage2|stage3 overrides it for A/B.
+    /// LEGACY (2026-07 presentation rebuild — design/apple-presentation-rebuild.md): the old
+    /// user-visible stage picker's key. No longer read — the presenter is resolved from
+    /// `presentPriority` below; the stage ladder survives only as the
+    /// PUNKTFUNK_PRESENTER=stage1|stage2|stage3|stage4 debug env lever. Kept so a synced old
+    /// value is documented, not mysterious.
     public static let presenter = "punktfunk.presenter"
+    /// The user's presentation intent: "latency" (default — every frame shows as soon as the
+    /// display can; jitter appears as the occasional repeat/drop) or "smooth" (a small client
+    /// jitter buffer evens the cadence at the cost of added, visible display latency).
+    /// Resolved once per session by SessionPresenter — see PresentPriority.
+    public static let presentPriority = "punktfunk.presentPriority"
+    /// Smoothness's jitter-buffer capacity in frames: 0 = Automatic (currently 2), or 1…3.
+    /// Each buffered frame adds ~one refresh interval of display latency and absorbs ~one
+    /// interval of arrival jitter. Only meaningful when `presentPriority` is "smooth".
+    public static let smoothBuffer = "punktfunk.smoothBuffer"
     /// macOS: V-Sync the stream's presents — each decoded frame flips on the next display vsync
     /// (evenly paced, no tearing under direct scanout) instead of as soon as the GPU finishes
     /// (lowest latency — the default, OFF). Resolved once per session;

clients/apple/Tests/PunktfunkKitTests/PresentPacingTests.swift

@@ -4,13 +4,15 @@ import XCTest
 import QuartzCore
 @testable import PunktfunkKit
 
-/// Stage-3 present pacing: the one-in-flight `PresentGate` and the stage-1/2/3 `PresenterChoice`
-/// resolution (setting + PUNKTFUNK_PRESENTER env override + the release-build stage-1 gate).
+/// Present pacing: the stage-3 bounded in-flight `PresentGate`, the stage-4 `LatestBox`
+/// drawable hand-off, the stage-1/2/3/4 `PresenterChoice` resolution (setting +
+/// PUNKTFUNK_PRESENTER env override + the release-build stage-1 gate + the iOS/tvOS-only
+/// stage-4 gate), and the per-platform glass-gate depth.
 final class PresentPacingTests: XCTestCase {
     // MARK: - PresentGate
 
-    /// The core invariant: one present in flight. A second acquire while pending must fail (the
-    /// frame stays in the ring for the presented handler's re-signal); release reopens.
+    /// The depth-1 invariant: one present in flight. A second acquire while pending must fail
+    /// (the frame stays in the ring for the presented handler's re-signal); release reopens.
     func testGateAdmitsOneInFlightPresent() {
         let gate = PresentGate()
         XCTAssertTrue(gate.tryAcquire(now: 0), "an idle gate must admit the first present")
@@ -20,6 +22,34 @@ final class PresentPacingTests: XCTestCase {
         XCTAssertEqual(gate.drainForced(), 0, "no stale present was force-cleared")
     }
 
+    /// Depth 2 (the PUNKTFUNK_GATE_DEPTH ladder rung — no longer a default; see
+    /// `SessionPresenter.gateDepth`'s standing-queue post-mortem): a second present may queue
+    /// behind the flip scanning out — the bound only bites at the THIRD. One release (a glass
+    /// callback) reopens exactly one slot.
+    func testGateDepthTwoAdmitsTwoInFlightPresents() {
+        let gate = PresentGate(capacity: 2)
+        XCTAssertTrue(gate.tryAcquire(now: 0))
+        XCTAssertTrue(gate.tryAcquire(now: 0.001), "depth 2 must admit a queued second flip")
+        XCTAssertFalse(gate.tryAcquire(now: 0.002), "the third present must wait for glass")
+        gate.release()
+        XCTAssertTrue(gate.tryAcquire(now: 0.003), "one glass callback frees one slot")
+        XCTAssertFalse(gate.tryAcquire(now: 0.004))
+        XCTAssertEqual(gate.drainForced(), 0)
+    }
+
+    /// Depth 2 staleness anchors to the OLDEST in-flight present: a full gate stays closed while
+    /// the oldest is live, force-opens once it ages out, and the younger present keeps its slot.
+    func testGateDepthTwoForceOpensOnTheOldestStalePresent() {
+        let gate = PresentGate(capacity: 2)
+        XCTAssertTrue(gate.tryAcquire(now: 10))
+        XCTAssertTrue(gate.tryAcquire(now: 10.05))
+        XCTAssertFalse(gate.tryAcquire(now: 10 + PresentGate.staleAfter - 0.01))
+        XCTAssertTrue(gate.tryAcquire(now: 10 + PresentGate.staleAfter + 0.01))
+        XCTAssertEqual(gate.drainForced(), 1)
+        // The 10.05 present is still live, so the gate is full again right after the force-open.
+        XCTAssertFalse(gate.tryAcquire(now: 10 + PresentGate.staleAfter + 0.02))
+    }
+
     /// The lost-handler insurance: a present whose handler never fires (the macOS "presents
     /// aren't damage" hazard class) must not freeze the stream — past `staleAfter` the gate
     /// force-opens and counts the event for the PUNKTFUNK_PRESENT_DEBUG `forced` stat.
@@ -45,13 +75,150 @@ final class PresentPacingTests: XCTestCase {
         XCTAssertEqual(gate.drainForced(), 0)
     }
 
+    // MARK: - PresentPriority (the user-facing latency/smoothness intent)
+
+    /// Resolution from the persisted settings: anything but an explicit "smooth" is latency
+    /// (the default), and the buffer setting maps 0/out-of-range/garbage to Automatic (2).
+    func testPresentPriorityResolution() {
+        XCTAssertEqual(PresentPriority.resolve(setting: nil, bufferSetting: nil), .latency)
+        XCTAssertEqual(PresentPriority.resolve(setting: "latency", bufferSetting: 3), .latency)
+        XCTAssertEqual(PresentPriority.resolve(setting: "garbage", bufferSetting: nil), .latency)
+        XCTAssertEqual(
+            PresentPriority.resolve(setting: "smooth", bufferSetting: nil),
+            .smooth(buffer: 2), "unset buffer = Automatic = 2")
+        XCTAssertEqual(
+            PresentPriority.resolve(setting: "smooth", bufferSetting: 0), .smooth(buffer: 2))
+        XCTAssertEqual(
+            PresentPriority.resolve(setting: "smooth", bufferSetting: 1), .smooth(buffer: 1))
+        XCTAssertEqual(
+            PresentPriority.resolve(setting: "smooth", bufferSetting: 3), .smooth(buffer: 3))
+        XCTAssertEqual(
+            PresentPriority.resolve(setting: "smooth", bufferSetting: 9),
+            .smooth(buffer: 2), "out-of-range buffer = Automatic")
+    }
+
+    /// The intent→store mapping: latency runs the zero-queue newest-wins slot, smoothness the
+    /// FIFO jitter buffer at the resolved capacity.
+    func testPresentPriorityStorePolicy() {
+        XCTAssertEqual(PresentPriority.latency.storePolicy, .newestWins)
+        XCTAssertEqual(
+            PresentPriority.smooth(buffer: 3).storePolicy, .fifo(capacity: 3))
+    }
+
+    // MARK: - FrameStore (the decoded-frame hand-off, both intents)
+
+    /// Newest-wins (latency): submit replaces the undisplayed frame, take clears, putBack
+    /// restores only into an empty slot — the exact pre-rebuild ReadyRing semantics.
+    func testFrameStoreNewestWins() {
+        let store = FrameStore<Int>(policy: .newestWins)
+        XCTAssertNil(store.take())
+        store.submit(1)
+        store.submit(2)
+        XCTAssertEqual(store.take(), 2, "the newer decode replaces the undisplayed frame")
+        XCTAssertNil(store.take())
+        store.putBack(7)
+        store.submit(8) // a fresh decode beats the putBack
+        store.putBack(7)
+        XCTAssertEqual(store.take(), 8)
+        XCTAssertEqual(store.drainSubmitted(), 3)
+        let smoothing = store.drainSmoothing()
+        XCTAssertEqual(smoothing.overflowDrops, 0)
+        XCTAssertEqual(smoothing.underflows, 0)
+    }
+
+    /// FIFO (smoothness): take withholds frames until the buffer has PREROLLED to capacity —
+    /// without preroll a steady stream drains on arrival and headroom never builds — then pops
+    /// oldest-first.
+    func testFrameStoreFifoPrerollsToCapacity() {
+        let store = FrameStore<Int>(policy: .fifo(capacity: 2))
+        store.submit(1)
+        XCTAssertNil(store.take(), "one frame buffered — still building headroom")
+        store.submit(2)
+        XCTAssertEqual(store.take(), 1, "prerolled — pops the OLDEST")
+        store.submit(3)
+        XCTAssertEqual(store.take(), 2, "steady state: one in, oldest out")
+        XCTAssertEqual(store.take(), 3)
+    }
+
+    /// FIFO overflow drops the OLDEST (bounded added latency, the newest keeps flowing) and
+    /// counts it; running dry counts an underflow and re-arms preroll so headroom rebuilds.
+    func testFrameStoreFifoOverflowAndUnderflow() {
+        let store = FrameStore<Int>(policy: .fifo(capacity: 2))
+        store.submit(1)
+        store.submit(2)
+        store.submit(3) // full — 1 (the oldest) goes
+        XCTAssertEqual(store.take(), 2)
+        XCTAssertEqual(store.take(), 3)
+        XCTAssertNil(store.take(), "ran dry — an underflow, preroll re-arms")
+        store.submit(4)
+        XCTAssertNil(store.take(), "rebuilding headroom after the underflow")
+        store.submit(5)
+        XCTAssertEqual(store.take(), 4)
+        let smoothing = store.drainSmoothing()
+        XCTAssertEqual(smoothing.overflowDrops, 1)
+        XCTAssertEqual(smoothing.underflows, 1)
+    }
+
+    /// FIFO putBack reinserts at the FRONT — a frame the render thread couldn't present is
+    /// still the oldest, so present order is preserved.
+    func testFrameStoreFifoPutBackPreservesOrder() {
+        let store = FrameStore<Int>(policy: .fifo(capacity: 2))
+        store.submit(1)
+        store.submit(2)
+        let f = store.take()
+        XCTAssertEqual(f, 1)
+        store.putBack(f!)
+        XCTAssertEqual(store.take(), 1, "the returned frame stays first out")
+        XCTAssertEqual(store.take(), 2)
+    }
+
+    // MARK: - LatestBox (stage-4's drawable hand-off)
+
+    /// Newest-wins hand-off: `put` replaces (an unpresented older drawable returns to the
+    /// layer's pool by release), `take` empties the slot.
+    func testLatestBoxNewestWins() {
+        let box = LatestBox<Int>()
+        XCTAssertNil(box.take())
+        box.put(1)
+        box.put(2)
+        XCTAssertEqual(box.take(), 2, "a fresher put replaces the unpresented value")
+        XCTAssertNil(box.take(), "take empties the slot")
+    }
+
+    /// `putBack` fills only an EMPTY slot: the render thread returning a drawable it took but
+    /// didn't present must never clobber a fresher one the link vended in between.
+    func testLatestBoxPutBackNeverClobbersAFresherPut() {
+        let box = LatestBox<Int>()
+        box.put(1)
+        let stale = box.take()
+        XCTAssertEqual(stale, 1)
+        box.putBack(stale!)
+        XCTAssertEqual(box.take(), 1, "putBack into a still-empty slot restores the value")
+        box.put(2)
+        let taken = box.take()
+        box.put(3) // the link vends a fresher drawable while the render thread holds `taken`
+        box.putBack(taken!)
+        XCTAssertEqual(box.take(), 3, "the fresher vend wins over the stale return")
+    }
+
     // MARK: - PresenterChoice
 
-    func testPresenterChoiceDefaultsToStage2() {
+    /// The platform default: deadline-paced stage-4 on iOS/iPadOS AND tvOS (the vsync-latching
+    /// platforms where any bounded-FIFO pacing keeps a standing queue — tvOS joined in the
+    /// 2026-07 presentation rebuild), arrival stage-2 on macOS (sync-off presents don't queue).
+    /// No selection / garbage falls back to it.
+    func testPresenterChoiceFallsBackToPlatformDefault() {
+        #if os(iOS) || os(tvOS)
+        XCTAssertEqual(PresenterChoice.platformDefault, .stage4)
+        #else
+        XCTAssertEqual(PresenterChoice.platformDefault, .stage2)
+        #endif
         XCTAssertEqual(
-            PresenterChoice.resolve(setting: nil, env: nil, allowStage1: true), .stage2)
+            PresenterChoice.resolve(setting: nil, env: nil, allowStage1: true),
+            PresenterChoice.platformDefault)
         XCTAssertEqual(
-            PresenterChoice.resolve(setting: "garbage", env: nil, allowStage1: true), .stage2)
+            PresenterChoice.resolve(setting: "garbage", env: nil, allowStage1: true),
+            PresenterChoice.platformDefault)
         XCTAssertEqual(
             PresenterChoice.resolve(setting: "stage2", env: nil, allowStage1: true), .stage2)
     }
@@ -69,15 +236,109 @@ final class PresentPacingTests: XCTestCase {
             PresenterChoice.resolve(setting: "stage3", env: "", allowStage1: true), .stage3)
     }
 
+    /// "stage4" (deadline pacing) resolves only on iOS/tvOS. On macOS — whose present path is
+    /// entangled with the sync-off/DCP-panic saga — a synced-over "stage4" value maps back to
+    /// the platform default instead of engaging an unvalidated pacing.
+    func testPresenterChoiceGatesStage4ToVsyncLatchPlatforms() {
+        #if os(macOS)
+        XCTAssertNil(PresenterChoice.explicit(setting: "stage4", env: nil, allowStage1: true))
+        XCTAssertEqual(
+            PresenterChoice.resolve(setting: "stage4", env: nil, allowStage1: true), .stage2)
+        XCTAssertEqual(
+            PresenterChoice.resolve(setting: nil, env: "stage4", allowStage1: true), .stage2)
+        #else
+        XCTAssertEqual(
+            PresenterChoice.explicit(setting: "stage4", env: nil, allowStage1: true), .stage4)
+        XCTAssertEqual(
+            PresenterChoice.resolve(setting: nil, env: "stage4", allowStage1: true), .stage4)
+        // The env override wins over the persisted setting, both directions.
+        XCTAssertEqual(
+            PresenterChoice.resolve(setting: "stage4", env: "stage3", allowStage1: true), .stage3)
+        XCTAssertEqual(
+            PresenterChoice.resolve(setting: "stage2", env: "stage4", allowStage1: true), .stage4)
+        #endif
+    }
+
     /// Stage-1 (the freeze-prone system-layer diagnostic) resolves only where allowed (DEBUG
-    /// builds); a leftover "stage1" value in a release build maps back to stage-2.
+    /// builds); a leftover "stage1" value in a release build maps back to the platform default.
     func testPresenterChoiceGatesStage1() {
         XCTAssertEqual(
             PresenterChoice.resolve(setting: "stage1", env: nil, allowStage1: true), .stage1)
         XCTAssertEqual(
-            PresenterChoice.resolve(setting: "stage1", env: nil, allowStage1: false), .stage2)
+            PresenterChoice.resolve(setting: "stage1", env: nil, allowStage1: false),
+            PresenterChoice.platformDefault)
         XCTAssertEqual(
-            PresenterChoice.resolve(setting: nil, env: "stage1", allowStage1: false), .stage2)
+            PresenterChoice.resolve(setting: nil, env: "stage1", allowStage1: false),
+            PresenterChoice.platformDefault)
+    }
+
+    /// `explicit` is nil exactly when `resolve` would fall back to the platform default — the
+    /// distinction the codec-conditional pacing default rides on.
+    func testPresenterChoiceExplicitIsNilWithoutASelection() {
+        XCTAssertNil(PresenterChoice.explicit(setting: nil, env: nil, allowStage1: true))
+        XCTAssertNil(PresenterChoice.explicit(setting: "garbage", env: nil, allowStage1: true))
+        XCTAssertNil(PresenterChoice.explicit(setting: "stage1", env: nil, allowStage1: false))
+        XCTAssertEqual(
+            PresenterChoice.explicit(setting: "stage2", env: nil, allowStage1: true), .stage2)
+        XCTAssertEqual(
+            PresenterChoice.explicit(setting: nil, env: "stage3", allowStage1: true), .stage3)
+    }
+
+    // MARK: - Session pacing (the macOS PyroWave swapID-panic mitigation)
+
+    /// macOS PyroWave sessions under the DEFAULT stage-2 choice must get glass pacing (the
+    /// one-in-flight gate is the "mismatched swapID's" kernel-panic mitigation); an EXPLICIT
+    /// stage-2 pick must stay a faithful arrival-pacing A/B. Elsewhere the default is unchanged.
+    func testPacingDefaultsPyroWaveToGlassOnMacOS() {
+        #if os(macOS)
+        XCTAssertEqual(
+            SessionPresenter.pacing(for: .stage2, explicit: nil, codec: .pyrowave), .glass,
+            "defaulted macOS PyroWave must serialize presents (swapID-panic mitigation)")
+        XCTAssertEqual(
+            SessionPresenter.pacing(for: .stage2, explicit: .stage2, codec: .pyrowave), .arrival,
+            "an explicit stage-2 pick must keep arrival pacing (honest A/B)")
+        #else
+        XCTAssertEqual(
+            SessionPresenter.pacing(for: .stage2, explicit: nil, codec: .pyrowave), .arrival)
+        #endif
+        // Non-PyroWave defaults keep arrival pacing under stage-2 everywhere.
+        XCTAssertEqual(
+            SessionPresenter.pacing(for: .stage2, explicit: nil, codec: .hevc), .arrival)
+        // Stage-3 means glass regardless of codec or how it was chosen.
+        XCTAssertEqual(
+            SessionPresenter.pacing(for: .stage3, explicit: .stage3, codec: .hevc), .glass)
+        XCTAssertEqual(
+            SessionPresenter.pacing(for: .stage3, explicit: nil, codec: .pyrowave), .glass)
+        // Stage-4 means deadline regardless of codec or how it was chosen.
+        XCTAssertEqual(
+            SessionPresenter.pacing(for: .stage4, explicit: nil, codec: .hevc), .deadline)
+        XCTAssertEqual(
+            SessionPresenter.pacing(for: .stage4, explicit: .stage4, codec: .pyrowave), .deadline)
+    }
+
+    // MARK: - Glass-gate depth
+
+    /// The in-flight present budget is 1 EVERYWHERE: any deeper gate keeps a standing queue —
+    /// the 2026-07 iPad depth-2 experiment regressed display latency 14→22–28 ms (see
+    /// `SessionPresenter.gateDepth`'s post-mortem). macOS additionally pins the env lever (glass
+    /// there is the swapID-panic mitigation — strict serialization is its point);
+    /// PUNKTFUNK_GATE_DEPTH still reproduces the standing-queue ladder on iOS/tvOS.
+    /// Out-of-range/garbage values are ignored.
+    func testGateDepthPlatformDefaultsAndEnvOverride() {
+        #if os(macOS)
+        XCTAssertEqual(SessionPresenter.gateDepth(env: nil), 1)
+        XCTAssertEqual(SessionPresenter.gateDepth(env: "2"), 1, "macOS is pinned to 1")
+        #else
+        XCTAssertEqual(
+            SessionPresenter.gateDepth(env: nil), 1,
+            "any depth >1 is a standing queue — one refresh of display latency per slot")
+        XCTAssertEqual(SessionPresenter.gateDepth(env: "2"), 2, "the on-device ladder lever")
+        #endif
+        XCTAssertEqual(
+            SessionPresenter.gateDepth(env: "0"), SessionPresenter.gateDepth(env: nil),
+            "out-of-range env values fall back to the platform depth")
+        XCTAssertEqual(
+            SessionPresenter.gateDepth(env: "garbage"), SessionPresenter.gateDepth(env: nil))
     }
 }
 #endif

clients/apple/Tests/PunktfunkKitTests/PyroWaveDecoderTests.swift

@@ -57,7 +57,7 @@ final class PyroWaveParserTests: XCTestCase {
     func testLayoutMatchesUpstreamBlockSpace() {
         // init_block_meta's walk for 256x144 (aligned 256x160): level extents halve from
         // 128x80; per (comp,level,band) count32 = ceil(ceil(w/8)/4) * ceil(ceil(h/8)/4).
-        let layout = WaveletLayout(width: width, height: height)
+        let layout = WaveletLayout(width: width, height: height, chroma444: false)
         XCTAssertEqual(layout.alignedWidth, 256)
         XCTAssertEqual(layout.alignedHeight, 160)
         XCTAssertEqual(layout.levelWidth(0), 128)
@@ -85,7 +85,7 @@ final class PyroWaveParserTests: XCTestCase {
     }
 
     func testDenseParseFillsOffsetsAndCountsBlocks() throws {
-        let layout = WaveletLayout(width: width, height: height)
+        let layout = WaveletLayout(width: width, height: height, chroma444: false)
         var au = sof(totalBlocks: 4)
         au += packet(blockIndex: 0)
         au += packet(blockIndex: 3)
@@ -273,6 +273,17 @@ final class PyroWaveGoldenTests: XCTestCase {
         try assertMatchesReference(decoded, prefix: "ref-chunked")
     }
 
+    /// 4:4:4: the chroma components run the full pyramid like luma (no level-0 skip, no
+    /// early half-res emit) — the layout + dispatch structure Phase 4 added
+    /// (design/pyrowave-444-hdr.md). The fixture comes from the 4:4:4 host encoder; the
+    /// reference is upstream's own 4:4:4 decode (full-res chroma planes).
+    func testDense444GoldenFrame() throws {
+        try XCTSkipIf(!MetalWaveletDecoder.supported, "no capable Metal device")
+        let au = try fixture("au-dense444")
+        let decoded = try decode(au: au, chunkAligned: false, windowSize: 0)
+        try assertMatchesReference(decoded, prefix: "ref-dense444")
+    }
+
     /// Phase-4 partial delivery: zero a mid-AU window (a lost shard) — the frame must still
     /// decode (blocks > half) and stay recognizably the same picture (holes reconstruct as
     /// localized blur, not garbage).

clients/linux/src/app.rs

@@ -55,6 +55,11 @@ pub struct AppModel {
     /// App-lifetime SDL gamepad service (Settings' controller list + pinning). Streams
     /// run in the session binary, which has its own.
     pub gamepad: crate::gamepad::GamepadService,
+    /// Device lists for the settings pickers (GPUs via `punktfunk-session
+    /// --list-adapters` — the shell deliberately links no Vulkan itself — and audio
+    /// endpoints via the PipeWire registry), probed once at startup on a worker thread.
+    /// Empty until the probe lands — empty lists simply hide their pickers.
+    pub probes: Rc<RefCell<crate::ui_settings::DeviceProbes>>,
     hosts: Controller<HostsPage>,
     /// One session child at a time — connects while one runs are ignored.
     busy: bool,
@@ -160,6 +165,42 @@ impl SimpleComponent for AppModel {
         }
 
         let settings = Rc::new(RefCell::new(Settings::load()));
+        // Device lists for the settings pickers: probe in the background, ready long
+        // before the dialog opens. A missing session binary or absent PipeWire just
+        // leaves the corresponding list empty (and its picker hidden).
+        let probes: Rc<RefCell<crate::ui_settings::DeviceProbes>> = Rc::default();
+        {
+            let (tx, rx) = async_channel::bounded::<crate::ui_settings::DeviceProbes>(1);
+            std::thread::spawn(move || {
+                let adapters: Vec<String> =
+                    std::process::Command::new(crate::spawn::session_binary())
+                        .arg("--list-adapters")
+                        .output()
+                        .ok()
+                        .filter(|o| o.status.success())
+                        .map(|o| {
+                            String::from_utf8_lossy(&o.stdout)
+                                .lines()
+                                .map(str::trim)
+                                .filter(|l| !l.is_empty())
+                                .map(str::to_string)
+                                .collect()
+                        })
+                        .unwrap_or_default();
+                let (speakers, mics) = pf_client_core::audio::devices().unwrap_or_default();
+                let _ = tx.send_blocking(crate::ui_settings::DeviceProbes {
+                    adapters,
+                    speakers,
+                    mics,
+                });
+            });
+            let probes = probes.clone();
+            glib::spawn_future_local(async move {
+                if let Ok(found) = rx.recv().await {
+                    *probes.borrow_mut() = found;
+                }
+            });
+        }
         // Re-apply the persisted forwarded-controller pin (stable key; the service
         // matches it whenever such a pad connects).
         {
@@ -197,6 +238,7 @@ impl SimpleComponent for AppModel {
             settings,
             identity,
             gamepad: init.gamepad,
+            probes,
             hosts,
             busy: false,
             wake_fallback: None,
@@ -307,8 +349,15 @@ impl SimpleComponent for AppModel {
                     // packet now (fire-and-forget — harmless if it's awake) so a genuinely-asleep
                     // box is already booting while the dial times out, arm the wake-wait fallback
                     // for THIS request, and connect immediately.
-                    crate::wol::wake(&req.mac, req.addr.parse().ok());
-                    self.wake_fallback = Some(req.clone());
+                    //
+                    // Auto-wake OFF (the Settings toggle, for VPN hosts that look offline when
+                    // they aren't): no packet and no wake-and-wait fallback — the dial either
+                    // succeeds or fails with the normal error. The host-card menu's explicit
+                    // "Wake host" is deliberately not gated.
+                    if self.settings.borrow().auto_wake {
+                        crate::wol::wake(&req.mac, req.addr.parse().ok());
+                        self.wake_fallback = Some(req.clone());
+                    }
                     sender.input(AppMsg::Connect(req));
                 }
             }
@@ -435,6 +484,7 @@ impl SimpleComponent for AppModel {
                     &self.window,
                     self.settings.clone(),
                     &self.gamepad,
+                    &self.probes.borrow(),
                     move || {
                         // The library toggle changes the saved cards' menu — re-render.
                         let _ = hosts.send(HostsMsg::Refresh);

clients/linux/src/cli.rs

@@ -352,6 +352,7 @@ pub fn headless_add_host(target: &str) -> glib::ExitCode {
             paired: false,
             last_used: None,
             mac: Vec::new(),
+            clipboard_sync: false,
         });
     }
     match known.save() {
@@ -534,7 +535,34 @@ pub fn run_shot(ctx: &ShotCtx, scene: &str) {
             )));
         }
         "settings" | "03-settings" => {
-            crate::ui_settings::show(&ctx.window, ctx.settings.clone(), &ctx.gamepad, || {});
+            // Mock devices so the shot shows the probe-dependent pickers populated.
+            let dev = |name: &str, description: &str| pf_client_core::audio::AudioDevice {
+                name: name.to_string(),
+                description: description.to_string(),
+            };
+            let probes = crate::ui_settings::DeviceProbes {
+                adapters: vec![
+                    "NVIDIA GeForce RTX 4070".to_string(),
+                    "AMD Radeon 780M".to_string(),
+                ],
+                speakers: vec![dev("alsa_output.mock-hdmi", "HDMI / DisplayPort Audio")],
+                mics: vec![dev("alsa_input.mock-usb", "USB Microphone Analog Stereo")],
+            };
+            let dialog = crate::ui_settings::show(
+                &ctx.window,
+                ctx.settings.clone(),
+                &ctx.gamepad,
+                &probes,
+                || {},
+            );
+            // Optional page for the capture (general/display/input/audio/controllers);
+            // the dialog opens on General otherwise.
+            if let Ok(page) = std::env::var("PUNKTFUNK_SHOT_SETTINGS_PAGE") {
+                if !page.is_empty() {
+                    use adw::prelude::PreferencesDialogExt as _;
+                    dialog.set_visible_page_name(&page);
+                }
+            }
         }
         "trust" | "04-trust" => crate::ui_trust::tofu_dialog(&ctx.window, sender, mock_req()),
         "pair" | "05-pair" => {

clients/linux/src/ui_settings.rs

@@ -1,5 +1,9 @@
-//! Preferences dialog: stream mode, bitrate, host compositor, gamepad type, microphone,
-//! capture behavior. Written back to disk when the dialog closes.
+//! Preferences dialog on the cross-client category map (the Apple 2026-07 settings
+//! revamp): General / Display / Input / Audio / Controllers pages — Display owns
+//! everything about the picture — with per-field captions in each row's subtitle,
+//! dynamic where the meaning depends on the selection (touch mode). Written back to
+//! disk when the dialog closes. About stays in the primary menu (GNOME convention)
+//! rather than as a page.
 
 use crate::trust::Settings;
 use adw::prelude::*;
@@ -40,14 +44,31 @@ const GAMEPADS: &[&str] = &[
     "steamdeck",
 ];
 const COMPOSITORS: &[&str] = &["auto", "kwin", "wlroots", "mutter", "gamescope"];
-/// Codec setting values (persisted) paired with their display labels below.
-const CODECS: &[&str] = &["auto", "hevc", "h264", "av1"];
-const CODEC_LABELS: &[&str] = &["Automatic", "HEVC (H.265)", "H.264 (AVC)", "AV1"];
+/// Codec setting values (persisted) paired with their display labels below. PyroWave is
+/// preference-only by design (`Settings::preferred_codec`) — the ladder falls back to
+/// HEVC when either side can't do it.
+const CODECS: &[&str] = &["auto", "hevc", "h264", "av1", "pyrowave"];
+const CODEC_LABELS: &[&str] = &[
+    "Automatic",
+    "HEVC (H.265)",
+    "H.264 (AVC)",
+    "AV1",
+    "PyroWave (wired LAN)",
+];
 const DECODERS: &[&str] = &["auto", "vulkan", "vaapi", "software"];
 /// Touch-input model values (persisted) paired with their display labels below — the
 /// cross-client set (Android/Apple). Only meaningful on a touchscreen (Deck/tablet).
 const TOUCH_MODES: &[&str] = &["trackpad", "pointer", "touch"];
 const TOUCH_MODE_LABELS: &[&str] = &["Trackpad", "Direct pointer", "Touch passthrough"];
+/// The SELECTED touch mode explained — the caption swaps with the choice (the Apple
+/// revamp's dynamic-caption idiom) instead of narrating all three modes at once.
+/// Combo-row captions must stay ONE line (~66 chars at the default dialog width): a
+/// wrapped subtitle's natural width crushes the selected-value label into an ellipsis.
+const TOUCH_MODE_CAPTIONS: &[&str] = &[
+    "Drives the cursor like a laptop trackpad — tap to click",
+    "The cursor jumps to your finger — a tap clicks there",
+    "Real multi-touch reaches the host — for touch-native apps",
+];
 
 /// punktfunk's own license (MIT OR Apache-2.0), shown on the About dialog's Legal page.
 const APP_LICENSE: &str = concat!(
@@ -266,22 +287,92 @@ impl ChoiceRow {
     }
 }
 
+/// Update a row's caption after construction — the dynamic-caption hook (touch mode,
+/// resolution, codec). Both ChoiceRow shapes carry their subtitle on [`adw::ActionRow`]
+/// ([`adw::ComboRow`] derives from it), so one downcast covers desktop and gamescope mode.
+fn set_row_subtitle(row: &adw::PreferencesRow, text: &str) {
+    if let Some(r) = row.downcast_ref::<adw::ActionRow>() {
+        r.set_subtitle(text);
+    }
+}
+
+/// The SELECTED resolution choice explained (row index: 0 = Native, 1 = Match window,
+/// 2.. = explicit sizes) — one line each, see the caption-width note on
+/// [`TOUCH_MODE_CAPTIONS`].
+fn resolution_caption(i: u32) -> &'static str {
+    match i {
+        0 => "The native mode of this monitor, resolved at connect",
+        1 => "Follows the stream window — resizes renegotiate the host output",
+        _ => "The host drives a virtual output at exactly this size",
+    }
+}
+
+/// The SELECTED codec explained: the PyroWave entry is the one that needs its trade-off
+/// spelled out; everything else shares the soft-preference line.
+fn codec_caption(i: u32) -> &'static str {
+    if CODECS.get(i as usize) == Some(&"pyrowave") {
+        "Wavelet codec for wired LAN — minimal latency, lots of bandwidth"
+    } else {
+        "A preference — the host falls back if it can't encode it"
+    }
+}
+
+/// A settings category page for the dialog's view switcher.
+fn page(title: &str, icon: &str) -> adw::PreferencesPage {
+    adw::PreferencesPage::builder()
+        // The name addresses the page programmatically (`set_visible_page_name` — the
+        // screenshot harness's page knob); the title is what the view switcher shows.
+        .name(title.to_lowercase())
+        .title(title)
+        .icon_name(icon)
+        .build()
+}
+
+/// Startup device probes for the pickers — filled by the app shell in the background
+/// (GPUs via `punktfunk-session --list-adapters`, audio endpoints via the PipeWire
+/// registry); any list may still be empty when the dialog opens, which simply hides
+/// that picker.
+#[derive(Default)]
+pub struct DeviceProbes {
+    pub adapters: Vec<String>,
+    pub speakers: Vec<pf_client_core::audio::AudioDevice>,
+    pub mics: Vec<pf_client_core::audio::AudioDevice>,
+}
+
+/// A titled group of rows; `description` (may be empty) is the one form-level note —
+/// per-field explanations belong in row subtitles, not here.
+fn group(title: &str, description: &str) -> adw::PreferencesGroup {
+    let g = adw::PreferencesGroup::builder().title(title).build();
+    if !description.is_empty() {
+        g.set_description(Some(description));
+    }
+    g
+}
+
 /// `on_closed` runs after the settings are saved (the app shell refreshes the hosts grid
-/// there so the experimental library toggle takes effect without a nav round-trip).
+/// there so the library toggle takes effect without a nav round-trip). `probes` is the
+/// shell's startup device probe (`AppModel::probes`) — may still be empty. Returns the
+/// presented dialog so the screenshot harness can select a page; callers ignore it.
 pub fn show(
     parent: &impl IsA<gtk::Widget>,
     settings: Rc<RefCell<Settings>>,
     gamepads: &crate::gamepad::GamepadService,
+    probes: &DeviceProbes,
     on_closed: impl Fn() + 'static,
-) {
+) -> adw::PreferencesDialog {
     // The dialog exists before the rows: ChoiceRow's gamescope mode pushes its selection
     // subpage onto it.
     let dialog = adw::PreferencesDialog::new();
     dialog.set_title("Preferences");
+    dialog.set_search_enabled(true);
+    // Wide enough that the category switcher sits in the HEADER BAR (the tabbed look the
+    // Apple/Windows clients have): AdwPreferencesDialog moves it to a bottom bar below a
+    // breakpoint of 110pt × page count (≈ 733 px for our five pages). In a window that
+    // can't give the dialog this width it still collapses to the bottom bar on its own.
+    dialog.set_content_width(830);
     let inline = gamescope_session();
-    let page = adw::PreferencesPage::new();
 
-    let stream = adw::PreferencesGroup::builder().title("Stream").build();
+    // ---- Display: Resolution ----
     // The D1 tri-state: Native, Match window (a virtual index 1, stored as the
     // `match_window` flag), then the explicit sizes.
     let res_names: Vec<String> = std::iter::once("Native display".to_string())
@@ -297,10 +388,13 @@ pub fn show(
         &dialog,
         inline,
         "Resolution",
-        "The host creates a virtual output at exactly this size — Match window follows \
-         the stream window, including mid-stream resizes",
+        resolution_caption(0),
         &res_names.iter().map(String::as_str).collect::<Vec<_>>(),
     );
+    {
+        let w = res_row.widget().clone();
+        res_row.connect_changed(move |i| set_row_subtitle(&w, resolution_caption(i)));
+    }
     let hz_names: Vec<String> = REFRESH
         .iter()
         .map(|&r| {
@@ -315,9 +409,11 @@ pub fn show(
         &dialog,
         inline,
         "Refresh rate",
-        "",
+        "Native follows the monitor the window is on",
         &hz_names.iter().map(String::as_str).collect::<Vec<_>>(),
     );
+
+    // ---- Display: Quality ----
     let scale_names: Vec<String> = RENDER_SCALES
         .iter()
         .map(|&s| render_scale_label(s))
@@ -326,13 +422,69 @@ pub fn show(
         &dialog,
         inline,
         "Render scale",
-        "Supersample for sharpness (> 1×, more bandwidth and decode) or render below native \
-         (< 1×) for a lighter host — this device resamples to the window",
+        "Above 1× supersamples for sharpness; below is lighter on the host",
         &scale_names.iter().map(String::as_str).collect::<Vec<_>>(),
     );
     let bitrate_row = adw::SpinRow::with_range(0.0, 3000.0, 5.0);
     bitrate_row.set_title("Bitrate");
-    bitrate_row.set_subtitle("Mbit/s · 0 = host default · run a speed test before going high");
+    bitrate_row
+        .set_subtitle("Mbit/s · 0 = host default · a host card's menu has a network speed test");
+    let codec_row = ChoiceRow::new(
+        &dialog,
+        inline,
+        "Video codec",
+        codec_caption(0),
+        CODEC_LABELS,
+    );
+    {
+        let w = codec_row.widget().clone();
+        codec_row.connect_changed(move |i| set_row_subtitle(&w, codec_caption(i)));
+    }
+    let hdr_row = adw::SwitchRow::builder()
+        .title("10-bit HDR")
+        .subtitle(
+            "Advertise 10-bit HDR10 so the host upgrades HDR content — shown in HDR where \
+             the display supports it, tone-mapped otherwise",
+        )
+        .build();
+    let decoder_row = ChoiceRow::new(
+        &dialog,
+        inline,
+        "Video decoder",
+        "Automatic picks the best hardware decode, then software",
+        &["Automatic", "Vulkan Video", "VAAPI", "Software"],
+    );
+    // GPU picker (multi-GPU boxes): the adapter name feeds the session's device pick
+    // via `Settings::adapter` → PUNKTFUNK_VK_ADAPTER. Hidden when there's nothing to
+    // pick; a saved adapter that's gone (eGPU unplugged) keeps a revertable entry.
+    let saved_adapter = settings.borrow().adapter.clone();
+    let mut gpu_names = vec!["Automatic".to_string()];
+    let mut gpu_keys: Vec<String> = vec![String::new()];
+    for a in &probes.adapters {
+        gpu_names.push(a.clone());
+        gpu_keys.push(a.clone());
+    }
+    if !saved_adapter.is_empty() && !gpu_keys.contains(&saved_adapter) {
+        gpu_names.push(format!("{saved_adapter} (not detected)"));
+        gpu_keys.push(saved_adapter.clone());
+    }
+    let gpu_row = (gpu_keys.len() > 1).then(|| {
+        let row = ChoiceRow::new(
+            &dialog,
+            inline,
+            "GPU",
+            "Decodes and presents the stream",
+            &gpu_names.iter().map(String::as_str).collect::<Vec<_>>(),
+        );
+        let i = gpu_keys
+            .iter()
+            .position(|k| k == &saved_adapter)
+            .unwrap_or(0);
+        row.set_selected(i as u32);
+        row
+    });
+
+    // ---- Display: Host output ----
     let compositor_row = ChoiceRow::new(
         &dialog,
         inline,
@@ -346,19 +498,19 @@ pub fn show(
             "gamescope",
         ],
     );
-    let decoder_row = ChoiceRow::new(
-        &dialog,
-        inline,
-        "Video decoder",
-        "Automatic picks the best hardware decode for this GPU (VAAPI on AMD/Intel, \
-         Vulkan Video on NVIDIA), falling back to software",
-        &[
-            "Automatic (hardware → software)",
-            "Vulkan Video",
-            "VAAPI",
-            "Software",
-        ],
-    );
+
+    // ---- General ----
+    let fullscreen_row = adw::SwitchRow::builder()
+        .title("Start streams in fullscreen")
+        .subtitle("F11, the mouse at the top edge, or L1+R1+Start+Select lead back out")
+        .build();
+    let wake_row = adw::SwitchRow::builder()
+        .title("Auto-wake on connect")
+        .subtitle(
+            "Sends Wake-on-LAN to an offline saved host and waits for it to boot — turn \
+             off if hosts behind a VPN look offline when they aren't",
+        )
+        .build();
     let stats_row = ChoiceRow::new(
         &dialog,
         inline,
@@ -366,20 +518,101 @@ pub fn show(
         "Compact = fps · latency · bitrate in one line — Ctrl+Alt+Shift+S cycles the tiers live",
         &["Off", "Compact", "Normal", "Detailed"],
     );
-    let fullscreen_row = adw::SwitchRow::builder()
-        .title("Start streams in fullscreen")
-        .subtitle("F11, the mouse at the top edge, or L1+R1+Start+Select lead back out")
+    let library_row = adw::SwitchRow::builder()
+        .title("Show game library")
+        .subtitle(
+            "Adds “Browse library…” to paired hosts — list their Steam and custom games \
+             and launch one directly. No extra host setup",
+        )
         .build();
-    stream.add(res_row.widget());
-    stream.add(hz_row.widget());
-    stream.add(scale_row.widget());
-    stream.add(&bitrate_row);
-    stream.add(compositor_row.widget());
-    stream.add(decoder_row.widget());
-    stream.add(&fullscreen_row);
-    stream.add(stats_row.widget());
 
-    let input = adw::PreferencesGroup::builder().title("Input").build();
+    // ---- Input ----
+    let touch_row = ChoiceRow::new(
+        &dialog,
+        inline,
+        "Touch input",
+        TOUCH_MODE_CAPTIONS[0],
+        TOUCH_MODE_LABELS,
+    );
+    // Dynamic caption: describe the SELECTED mode, not all three at once.
+    {
+        let w = touch_row.widget().clone();
+        touch_row.connect_changed(move |i| {
+            let i = (i as usize).min(TOUCH_MODE_CAPTIONS.len() - 1);
+            set_row_subtitle(&w, TOUCH_MODE_CAPTIONS[i]);
+        });
+    }
+    let inhibit_row = adw::SwitchRow::builder()
+        .title("Capture system shortcuts")
+        .subtitle("Forward Alt+Tab, Super, … to the host while input is captured")
+        .build();
+    let invert_row = adw::SwitchRow::builder()
+        .title("Invert scroll direction")
+        .subtitle("Reverses the wheel and trackpad scroll direction sent to the host")
+        .build();
+
+    // ---- Audio ----
+    let surround_row = ChoiceRow::new(
+        &dialog,
+        inline,
+        "Audio channels",
+        "Stereo or surround — the host downmixes if its output has fewer",
+        &["Stereo", "5.1 Surround", "7.1 Surround"],
+    );
+    let mic_row = adw::SwitchRow::builder()
+        .title("Stream microphone")
+        .subtitle("Sends your microphone to the host's virtual mic")
+        .build();
+    // Endpoint pickers (from the PipeWire probe): visible labels are descriptions, the
+    // stored value is the node name. Hidden when the probe found nothing; a saved
+    // device that's gone keeps a revertable "(not detected)" entry, like the GPU row.
+    let dev_row = |saved: String,
+                   devs: &[pf_client_core::audio::AudioDevice],
+                   title: &str,
+                   subtitle: &str| {
+        let mut names = vec!["System default".to_string()];
+        let mut keys = vec![String::new()];
+        for d in devs {
+            names.push(d.description.clone());
+            keys.push(d.name.clone());
+        }
+        if !saved.is_empty() && !keys.contains(&saved) {
+            names.push(format!("{saved} (not detected)"));
+            keys.push(saved.clone());
+        }
+        let row = (keys.len() > 1).then(|| {
+            let row = ChoiceRow::new(
+                &dialog,
+                inline,
+                title,
+                subtitle,
+                &names.iter().map(String::as_str).collect::<Vec<_>>(),
+            );
+            row.set_selected(keys.iter().position(|k| k == &saved).unwrap_or(0) as u32);
+            row
+        });
+        (row, keys)
+    };
+    let (speaker_row, speaker_keys) = dev_row(
+        settings.borrow().speaker_device.clone(),
+        &probes.speakers,
+        "Speaker",
+        "Host audio plays here — System default follows the desktop",
+    );
+    let (micdev_row, micdev_keys) = dev_row(
+        settings.borrow().mic_device.clone(),
+        &probes.mics,
+        "Microphone",
+        "The input that feeds the host's virtual mic",
+    );
+    // The device pick only matters while the mic streams at all.
+    if let Some(r) = &micdev_row {
+        let w = r.widget().clone();
+        w.set_sensitive(mic_row.is_active());
+        mic_row.connect_active_notify(move |m| w.set_sensitive(m.is_active()));
+    }
+
+    // ---- Controllers ----
     // Controller forwarding: Automatic forwards EVERY real controller, each as its own pad
     // (Steam's virtual pad skipped); pinning one restricts the session to that single
     // controller (single-player). The pin is persisted by stable key (`Settings::forward_pad`),
@@ -413,7 +646,7 @@ pub fn show(
         if pads.is_empty() {
             "No controllers detected"
         } else {
-            "All controllers are forwarded, each as its own player; pick one to force single-player"
+            "Every pad is its own player — pick one to force single-player"
         },
         &pad_names.iter().map(String::as_str).collect::<Vec<_>>(),
     );
@@ -443,7 +676,7 @@ pub fn show(
         &dialog,
         inline,
         "Gamepad type",
-        "The virtual pad the host creates — Automatic matches the physical pad",
+        "The virtual pad on the host — Automatic matches your controller",
         &[
             "Automatic",
             "Xbox 360",
@@ -453,66 +686,8 @@ pub fn show(
             "Steam Deck",
         ],
     );
-    let touch_row = ChoiceRow::new(
-        &dialog,
-        inline,
-        "Touch input",
-        "How the touchscreen drives the host — Trackpad nudges a cursor (tap to click); \
-         Direct pointer jumps to your finger; Touch passthrough sends real touches",
-        TOUCH_MODE_LABELS,
-    );
-    let inhibit_row = adw::SwitchRow::builder()
-        .title("Capture system shortcuts")
-        .subtitle("Forward Alt+Tab, Super, … to the host while input is captured")
-        .build();
-    input.add(forward_row.widget());
-    input.add(pad_row.widget());
-    input.add(touch_row.widget());
-    input.add(&inhibit_row);
 
-    let audio = adw::PreferencesGroup::builder().title("Audio").build();
-    let surround_row = ChoiceRow::new(
-        &dialog,
-        inline,
-        "Audio channels",
-        "Request stereo or surround (the host downmixes if its output has fewer)",
-        &["Stereo", "5.1 Surround", "7.1 Surround"],
-    );
-    audio.add(surround_row.widget());
-    let codec_row = ChoiceRow::new(
-        &dialog,
-        inline,
-        "Video codec",
-        "Preferred codec — the host falls back if it can't encode this one",
-        CODEC_LABELS,
-    );
-    stream.add(codec_row.widget());
-    let mic_row = adw::SwitchRow::builder()
-        .title("Stream microphone")
-        .subtitle("Send the default input device to the host's virtual microphone")
-        .build();
-    audio.add(&mic_row);
-
-    // Experimental — mirrors the Apple client's Experimental section (wording included).
-    let experimental = adw::PreferencesGroup::builder()
-        .title("Experimental")
-        .build();
-    let library_row = adw::SwitchRow::builder()
-        .title("Show game library")
-        .subtitle(
-            "Adds a “Browse library…” action to each saved host that lists its games \
-             (Steam + custom) via the host's management API — works once you've paired",
-        )
-        .build();
-    experimental.add(&library_row);
-
-    // About (with the license/third-party Legal pages) lives in the primary menu now.
-    page.add(&stream);
-    page.add(&input);
-    page.add(&audio);
-    page.add(&experimental);
-
-    // Seed from the current settings.
+    // ---- Seed from the current settings ----
     {
         let s = settings.borrow();
         let res_i = if s.match_window {
@@ -525,6 +700,7 @@ pub fn show(
                 .unwrap_or(0)
         };
         res_row.set_selected(res_i as u32);
+        set_row_subtitle(res_row.widget(), resolution_caption(res_i as u32));
         let hz_i = REFRESH.iter().position(|&r| r == s.refresh_hz).unwrap_or(0);
         hz_row.set_selected(hz_i as u32);
         let scale_i = RENDER_SCALES
@@ -540,6 +716,8 @@ pub fn show(
             .position(|&t| t == s.touch_mode)
             .unwrap_or(0);
         touch_row.set_selected(touch_i as u32);
+        // set_selected never fires the changed hook, so seed the dynamic caption directly.
+        set_row_subtitle(touch_row.widget(), TOUCH_MODE_CAPTIONS[touch_i]);
         let comp_i = COMPOSITORS
             .iter()
             .position(|&c| c == s.compositor)
@@ -553,8 +731,11 @@ pub fn show(
             .unwrap_or(0);
         stats_row.set_selected(stats_i as u32);
         fullscreen_row.set_active(s.fullscreen_on_stream);
+        wake_row.set_active(s.auto_wake);
         inhibit_row.set_active(s.inhibit_shortcuts);
+        invert_row.set_active(s.invert_scroll);
         mic_row.set_active(s.mic_enabled);
+        hdr_row.set_active(s.hdr_enabled);
         library_row.set_active(s.library_enabled);
         surround_row.set_selected(match s.audio_channels {
             6 => 1,
@@ -563,9 +744,104 @@ pub fn show(
         });
         let codec_i = CODECS.iter().position(|&c| c == s.codec).unwrap_or(0);
         codec_row.set_selected(codec_i as u32);
+        set_row_subtitle(codec_row.widget(), codec_caption(codec_i as u32));
     }
 
-    dialog.add(&page);
+    // ---- Assemble the category pages (the Apple revamp's map) ----
+    let general = page("General", "preferences-system-symbolic");
+    let session_group = group("Session", "");
+    session_group.add(&fullscreen_row);
+    session_group.add(&wake_row);
+    let stats_group = group("Statistics", "");
+    stats_group.add(stats_row.widget());
+    let library_group = group("Library", "");
+    library_group.add(&library_row);
+    general.add(&session_group);
+    general.add(&stats_group);
+    general.add(&library_group);
+
+    let display = page("Display", "video-display-symbolic");
+    let resolution_group = group("Resolution", "");
+    resolution_group.add(res_row.widget());
+    resolution_group.add(hz_row.widget());
+    let quality_group = group("Quality", "");
+    quality_group.add(scale_row.widget());
+    quality_group.add(&bitrate_row);
+    quality_group.add(codec_row.widget());
+    quality_group.add(&hdr_row);
+    quality_group.add(decoder_row.widget());
+    if let Some(r) = &gpu_row {
+        quality_group.add(r.widget());
+    }
+    // The one form-level note (deliberately not repeated on every row).
+    let output_group = group(
+        "Host output",
+        "Display changes apply from the next session.",
+    );
+    output_group.add(compositor_row.widget());
+    display.add(&resolution_group);
+    display.add(&quality_group);
+    display.add(&output_group);
+
+    let input = page("Input", "input-keyboard-symbolic");
+    let touch_group = group("Touch", "");
+    touch_group.add(touch_row.widget());
+    // Group titles are Pango markup — the ampersand must be an entity.
+    let kbm_group = group("Keyboard &amp; mouse", "");
+    kbm_group.add(&inhibit_row);
+    kbm_group.add(&invert_row);
+    input.add(&touch_group);
+    input.add(&kbm_group);
+
+    let audio = page("Audio", "audio-volume-high-symbolic");
+    let audio_group = group("", "Applies from the next session.");
+    audio_group.add(surround_row.widget());
+    if let Some(r) = &speaker_row {
+        audio_group.add(r.widget());
+    }
+    audio_group.add(&mic_row);
+    if let Some(r) = &micdev_row {
+        audio_group.add(r.widget());
+    }
+    audio.add(&audio_group);
+
+    let controllers = page("Controllers", "input-gaming-symbolic");
+    let controllers_group = group("", "");
+    // The detected-pad list (mirrors the Apple Controllers section): informational rows
+    // above the pickers, from the same snapshot that feeds the forwarding picker.
+    if pads.is_empty() {
+        let none = adw::ActionRow::builder()
+            .title("No controllers detected")
+            .css_classes(["dim-label"])
+            .build();
+        controllers_group.add(&none);
+    } else {
+        for p in &pads {
+            let row = adw::ActionRow::builder()
+                .title(&p.name)
+                .use_markup(false)
+                .build();
+            if p.steam_virtual {
+                row.set_subtitle(
+                    "Steam Input's virtual pad — Automatic skips it while a real pad is connected",
+                );
+            } else {
+                row.set_subtitle(p.kind_label());
+            }
+            row.add_prefix(&gtk::Image::from_icon_name("input-gaming-symbolic"));
+            controllers_group.add(&row);
+        }
+    }
+    controllers_group.add(forward_row.widget());
+    controllers_group.add(pad_row.widget());
+    controllers.add(&controllers_group);
+
+    dialog.add(&general);
+    dialog.add(&display);
+    dialog.add(&input);
+    dialog.add(&audio);
+    dialog.add(&controllers);
+
     dialog.connect_closed(move |_| {
         let mut s = settings.borrow_mut();
         // Index 1 is the virtual "Match window" option; 0 = Native, 2.. = explicit.
@@ -587,12 +863,25 @@ pub fn show(
         s.compositor = COMPOSITORS[(compositor_row.selected() as usize).min(COMPOSITORS.len() - 1)]
             .to_string();
         s.decoder = DECODERS[(decoder_row.selected() as usize).min(DECODERS.len() - 1)].to_string();
+        if let Some(r) = &gpu_row {
+            s.adapter = gpu_keys[(r.selected() as usize).min(gpu_keys.len() - 1)].clone();
+        }
+        if let Some(r) = &speaker_row {
+            s.speaker_device =
+                speaker_keys[(r.selected() as usize).min(speaker_keys.len() - 1)].clone();
+        }
+        if let Some(r) = &micdev_row {
+            s.mic_device = micdev_keys[(r.selected() as usize).min(micdev_keys.len() - 1)].clone();
+        }
         s.set_stats_verbosity(
             StatsVerbosity::ALL[(stats_row.selected() as usize).min(StatsVerbosity::ALL.len() - 1)],
         );
         s.fullscreen_on_stream = fullscreen_row.is_active();
+        s.auto_wake = wake_row.is_active();
         s.inhibit_shortcuts = inhibit_row.is_active();
+        s.invert_scroll = invert_row.is_active();
         s.mic_enabled = mic_row.is_active();
+        s.hdr_enabled = hdr_row.is_active();
         s.audio_channels = match surround_row.selected() {
             1 => 6,
             2 => 8,
@@ -605,6 +894,7 @@ pub fn show(
         on_closed();
     });
     dialog.present(Some(parent));
+    dialog
 }
 
 #[cfg(test)]
@@ -678,6 +968,17 @@ mod tests {
         assert_eq!(fired.get(), 1);
         assert_eq!(row.value_label.as_ref().unwrap().text(), "B");
 
+        // The dynamic-caption hook drives the same subtitle both row shapes expose.
+        set_row_subtitle(row.widget(), "swapped");
+        assert_eq!(
+            row.widget()
+                .downcast_ref::<adw::ActionRow>()
+                .unwrap()
+                .subtitle()
+                .as_deref(),
+            Some("swapped")
+        );
+
         // Re-activating shows the check on the new selection (fresh subpage each time).
         row.widget()
             .downcast_ref::<adw::ActionRow>()
@@ -698,5 +999,16 @@ mod tests {
         combo.set_selected(0);
         assert_eq!(combo.selected(), 0);
         assert_eq!(combo_fired.get(), 0);
+        // ComboRow derives from ActionRow, so the caption hook reaches it too.
+        set_row_subtitle(combo.widget(), "combo caption");
+        assert_eq!(
+            combo
+                .widget()
+                .downcast_ref::<adw::ActionRow>()
+                .unwrap()
+                .subtitle()
+                .as_deref(),
+            Some("combo caption")
+        );
     }
 }

clients/session/src/console.rs

@@ -158,6 +158,7 @@ pub fn run(target: Option<&str>) -> u8 {
             v => v,
         },
         touch_mode: settings_at_start.touch_mode(),
+        invert_scroll: settings_at_start.invert_scroll,
         json_status,
         on_connected: Some(Box::new(move |fingerprint: [u8; 32]| {
             let fp_hex = trust::hex(&fingerprint);
@@ -452,6 +453,7 @@ impl ServiceState {
                         paired: false,
                         last_used: None,
                         mac: Vec::new(),
+                        clipboard_sync: false,
                     });
                 }
                 if let Err(e) = known.save() {

clients/session/src/main.rs

@@ -103,6 +103,14 @@ mod session_main {
         force_software: Arc<AtomicBool>,
         vulkan: Option<pf_client_core::video::VulkanDecodeDevice>,
     ) -> SessionParams {
+        // Per-host clipboard opt-in (design/clipboard-and-file-transfer.md §5.3), resolved
+        // here rather than passed in so every caller — a direct connect and the console's
+        // own launches — honors the same stored decision. `addr` is moved into the struct
+        // below, so read it first.
+        let clipboard = trust::KnownHosts::load()
+            .hosts
+            .iter()
+            .any(|h| h.addr == addr && h.port == port && h.clipboard_sync);
         // Re-apply the shell-persisted forwarded-controller pin (stable `vid:pid:name`
         // key) to OUR gamepad service — the shells' in-process services can't reach this
         // process. Applied per params-build (idempotent; browse re-launches included) so
@@ -165,6 +173,7 @@ mod session_main {
             // pump) pins one manually.
             display_hdr: None,
             mic_enabled: settings.mic_enabled,
+            clipboard,
             // 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.
@@ -259,19 +268,66 @@ mod session_main {
             )
             .init();
 
+        // `--list-adapters`: print the Vulkan physical devices' marketing names (one per
+        // line, discrete first) for the desktop shells' GPU picker, then exit.
+        if arg_flag("--list-adapters") {
+            return match pf_presenter::vk::list_adapters() {
+                Ok(names) => {
+                    for n in names {
+                        println!("{n}");
+                    }
+                    0
+                }
+                Err(e) => {
+                    eprintln!("list-adapters: {e:#}");
+                    EXIT_PRESENTER_FAILED
+                }
+            };
+        }
+
+        // `--list-audio`: the PipeWire endpoints the settings pickers offer, as
+        // `sink|source<TAB>node.name<TAB>description` lines — a debug window into the
+        // same enumeration the GTK shell probes.
+        #[cfg(target_os = "linux")]
+        if arg_flag("--list-audio") {
+            return match pf_client_core::audio::devices() {
+                Ok((sinks, sources)) => {
+                    for d in sinks {
+                        println!("sink\t{}\t{}", d.name, d.description);
+                    }
+                    for d in sources {
+                        println!("source\t{}\t{}", d.name, d.description);
+                    }
+                    0
+                }
+                Err(e) => {
+                    eprintln!("list-audio: {e:#}");
+                    EXIT_PRESENTER_FAILED
+                }
+            };
+        }
+
         // Before any Vulkan call: make RADV expose its video-decode queue + extensions so the
         // decoder's `auto` path prefers Vulkan Video over VAAPI (Steam Deck, and any gated RADV).
         // Windows drivers (NVIDIA/AMD Adrenalin) expose theirs unconditionally.
         #[cfg(target_os = "linux")]
         enable_radv_video_decode();
 
-        // The Settings GPU pick (the WinUI shell's picker stores the adapter's marketing
-        // name) → the presenter's device selection, unless the user already forced one.
-        // Before any Vulkan call, like the RADV knob (covers --connect and --browse).
-        if std::env::var_os("PUNKTFUNK_VK_ADAPTER").is_none() {
-            let adapter = trust::Settings::load().adapter;
-            if !adapter.is_empty() {
-                std::env::set_var("PUNKTFUNK_VK_ADAPTER", adapter);
+        // The Settings device picks → env, unless the user already forced one by hand:
+        // the GPU (the shells' pickers store the adapter's marketing name) for the
+        // presenter's device selection, and the audio endpoints (PipeWire node names)
+        // for the playback/mic streams' `target.object`. Before any Vulkan call, like
+        // the RADV knob (covers --connect and --browse).
+        {
+            let s = trust::Settings::load();
+            for (var, value) in [
+                ("PUNKTFUNK_VK_ADAPTER", &s.adapter),
+                ("PUNKTFUNK_AUDIO_SINK", &s.speaker_device),
+                ("PUNKTFUNK_AUDIO_SOURCE", &s.mic_device),
+            ] {
+                if std::env::var_os(var).is_none() && !value.is_empty() {
+                    std::env::set_var(var, value);
+                }
             }
         }
 
@@ -373,6 +429,7 @@ mod session_main {
                 v => v,
             },
             touch_mode: settings.touch_mode(),
+            invert_scroll: settings.invert_scroll,
             json_status: true,
             on_connected: Some(Box::new(|fingerprint: [u8; 32]| {
                 // This host's card carries the accent bar in the desktop client now.

clients/windows/Cargo.toml

@@ -12,6 +12,12 @@ repository.workspace = true
 name = "punktfunk-client"
 path = "src/main.rs"
 
+# The couch/HTPC Start-menu entry. Its own executable because an MSIX <Application> cannot
+# pass arguments to a full-trust exe — see the binary's own docs.
+[[bin]]
+name = "punktfunk-console"
+path = "src/bin/punktfunk-console.rs"
+
 # Everything is Windows-gated so `cargo build --workspace` stays green on Linux/macOS (the
 # other native clients live in clients/linux and clients/apple); on other
 # platforms this builds as a stub binary. Mirrors the Linux client's cfg(target_os="linux")

clients/windows/packaging/AppxManifest.xml

@@ -57,6 +57,23 @@
         <uap:DefaultTile Square71x71Logo="Assets\Square71x71Logo.png" />
       </uap:VisualElements>
     </Application>
+    <!--
+      Second entry point: the couch/console UI, for an HTPC or a TV-attached box where the
+      desktop shell is the wrong first screen. Same full-trust executable, launched with
+      `--console`, which hands straight off to the session binary's controller-driven
+      browse mode (host list, pairing, settings, library) fullscreen.
+    -->
+    <Application Id="PunktfunkConsole" Executable="punktfunk-console.exe"
+                 EntryPoint="Windows.FullTrustApplication">
+      <uap:VisualElements
+        DisplayName="Punktfunk Console"
+        Description="Controller-driven couch interface for TVs and HTPCs"
+        BackgroundColor="transparent"
+        Square150x150Logo="Assets\Square150x150Logo.png"
+        Square44x44Logo="Assets\Square44x44Logo.png">
+        <uap:DefaultTile Square71x71Logo="Assets\Square71x71Logo.png" />
+      </uap:VisualElements>
+    </Application>
   </Applications>
 
   <Capabilities>

clients/windows/packaging/pack-msix.ps1

@@ -72,7 +72,7 @@ New-Item -ItemType Directory -Force -Path (Join-Path $layout 'Assets') | Out-Nul
 # session client the shell spawns for every stream (sibling resolution — see clients/windows/
 # src/spawn.rs); Skia links statically and vulkan-1.dll is a GPU-driver component, so the session
 # adds no DLLs of its own.
-$required = @('punktfunk-client.exe', 'punktfunk-session.exe', 'Microsoft.WindowsAppRuntime.Bootstrap.dll', 'SDL3.dll', 'resources.pri')
+$required = @('punktfunk-client.exe', 'punktfunk-session.exe', 'punktfunk-console.exe', 'Microsoft.WindowsAppRuntime.Bootstrap.dll', 'SDL3.dll', 'resources.pri')
 foreach ($f in $required) {
     $src = Join-Path $TargetDir $f
     if (-not (Test-Path $src)) { throw "missing build artifact '$f' in $TargetDir (did 'cargo build --release' run?)" }

clients/windows/src/app/connect.rs

@@ -36,7 +36,9 @@ pub(crate) fn initiate_waking(
     set_screen: &AsyncSetState<Screen>,
     set_status: &AsyncSetState<String>,
 ) {
-    crate::wol::wake(&target.mac, target.addr.parse().ok());
+    if ctx.settings.lock().unwrap().auto_wake {
+        crate::wol::wake(&target.mac, target.addr.parse().ok());
+    }
     initiate_opts(ctx, target, set_screen, set_status, true)
 }
 
@@ -272,6 +274,7 @@ fn connect_spawn(
                             paired: persist_paired,
                             last_used: None,
                             mac: target.mac.clone(),
+                            clipboard_sync: false,
                         });
                         let _ = k.save();
                     }
@@ -291,9 +294,13 @@ fn connect_spawn(
                             *shared.target.lock().unwrap() = target.clone();
                             ss.call(Screen::Pair);
                         }
-                        Some((_, false)) if wake_on_fail => {
+                        Some((_, false))
+                            if wake_on_fail && ctx2.settings.lock().unwrap().auto_wake =>
+                        {
                             // The dial-first attempt to a non-advertising host failed — it
-                            // may genuinely be asleep. NOW wake and wait.
+                            // may genuinely be asleep. NOW wake and wait. Skipped entirely
+                            // when auto-wake is off: the wait is only worth showing if we
+                            // are actually sending magic packets to end it.
                             wake_and_connect(&ctx2, target.clone(), &ss, &st);
                         }
                         Some((msg, false)) => {
@@ -321,9 +328,12 @@ fn connect_spawn(
 /// PAIRED host in the session window. The shell yields exactly like a stream — hidden on
 /// the library window's `ready`, restored when the child exits (launched titles stream
 /// in that same window, so the whole couch round-trip happens without the shell).
+/// `target = None` opens the console's own host view (discovery, pairing, settings) — the
+/// couch entry point that isn't tied to one host; `Some` opens straight into that host's
+/// library.
 pub(crate) fn open_console(
     ctx: &Arc<AppCtx>,
-    target: Target,
+    target: Option<Target>,
     set_screen: &AsyncSetState<Screen>,
     set_status: &AsyncSetState<String>,
 ) {
@@ -331,15 +341,21 @@ pub(crate) fn open_console(
     *ctx.shared.session.lock().unwrap() = child.clone();
     ctx.shared.stats_line.lock().unwrap().clear();
     ctx.shared.browse.store(true, Ordering::SeqCst);
-    *ctx.shared.target.lock().unwrap() = target.clone();
+    if let Some(t) = target.clone() {
+        *ctx.shared.target.lock().unwrap() = t;
+    }
     let fullscreen = ctx.settings.lock().unwrap().fullscreen_on_stream;
     set_status.call(String::new());
     set_screen.call(Screen::Connecting);
 
     let shared = ctx.shared.clone();
     let (ss, st) = (set_screen.clone(), set_status.clone());
-    let spawned =
-        crate::spawn::spawn_browse(&target.addr, target.port, fullscreen, child, move |event| {
+    let addr_port = target.as_ref().map(|t| (t.addr.clone(), t.port));
+    let spawned = crate::spawn::spawn_browse(
+        addr_port.as_ref().map(|(a, p)| (a.as_str(), *p)),
+        fullscreen,
+        child,
+        move |event| {
             use crate::spawn::SpawnEvent;
             match event {
                 SpawnEvent::Ready => {
@@ -357,7 +373,8 @@ pub(crate) fn open_console(
                     ss.call(Screen::Hosts);
                 }
             }
-        });
+        },
+    );
     if let Err(e) = spawned {
         set_status.call(e);
         set_screen.call(Screen::Hosts);
@@ -467,6 +484,7 @@ fn wake_and_connect(
                             paired: false,
                             last_used: None,
                             mac: target.mac.clone(),
+                            clipboard_sync: false,
                         });
                         let _ = k.save();
                     }

clients/windows/src/app/hosts.rs

@@ -1,5 +1,5 @@
 //! The hosts page: saved (trusted/paired) hosts and live mDNS discovery as tap-to-connect
-//! tiles in a responsive grid, with a per-host "…" menu (connect / speed test / rename /
+//! tiles in a responsive grid, with a per-host "…" menu (connect / speed test / edit /
 //! forget) and a manual connect entry — the same card layout as the Linux and Apple clients.
 
 use super::connect::{initiate, initiate_waking, open_console};
@@ -14,10 +14,12 @@ use windows_reactor::*;
 /// Overflow-menu item labels — `on_item_clicked` reports the clicked item by its text.
 const MENU_CONNECT: &str = "Connect";
 const MENU_LIBRARY: &str = "Browse library\u{2026}";
-const MENU_CONSOLE: &str = "Open console UI";
 const MENU_SPEED: &str = "Test network speed\u{2026}";
 const MENU_WAKE: &str = "Wake host";
-const MENU_RENAME: &str = "Rename\u{2026}";
+/// One entry for every per-host property (name, address, MAC, clipboard sharing) — the
+/// Apple client's add/edit sheet. A menu item per field read as clutter and buried the ones
+/// that matter.
+const MENU_EDIT: &str = "Edit\u{2026}";
 const MENU_FORGET: &str = "Forget\u{2026}";
 
 /// Whether the console (gamepad) UI is available in this build: the session binary ships
@@ -187,43 +189,114 @@ fn status_row(online: Option<bool>, badge: &str, kind: Pill) -> Element {
         .into()
 }
 
-/// The in-tile rename editor (ContentDialog can't hold a text field): name box + save/cancel.
-/// No tap-to-connect while editing — a click into the box would bubble `Tapped` to the region.
-/// `initial` seeds the text box's displayed value and is CONSTANT for the life of the edit — the
-/// field is uncontrolled, its live value kept in `live` (read at Save). Driving a *controlled* box
-/// from an always-deferred `AsyncSetState` round-trip fights the caret on fast typing and can drop
-/// the last char if Save is clicked before the write lands; an uncontrolled box + a ref sidesteps
-/// both (and skips a full-page re-render per keystroke). See the seed block in `hosts_page`.
-fn rename_editor(
-    initial: &str,
-    fp: String,
-    live: HookRef<String>,
-    set_rename: AsyncSetState<Option<(String, String)>>,
+/// The in-tile host editor (a ContentDialog can't hold text fields): every per-host
+/// property in one place, mirroring the Apple client's add/edit sheet — name, address,
+/// port, Wake-on-LAN MAC, and whether this machine shares its clipboard with the host.
+/// Replaced a menu-item-per-property, which buried the useful entries in noise.
+///
+/// Drafts live in refs owned by the page and are read at Save time; the root `edit` state
+/// carries only the target's fingerprint + initial name, so typing doesn't round-trip
+/// through a re-render.
+#[allow(clippy::too_many_arguments)]
+fn edit_editor(
+    fp: &str,
+    initial_name: &str,
+    name_draft: HookRef<String>,
+    addr_draft: HookRef<String>,
+    port_draft: HookRef<String>,
+    mac_draft: HookRef<String>,
+    clip_draft: HookRef<bool>,
+    set_edit: AsyncSetState<Option<(String, String)>>,
 ) -> Element {
     let commit = {
-        let (fp, live, sr) = (fp.clone(), live.clone(), set_rename.clone());
+        let (fp, se) = (fp.to_string(), set_edit.clone());
+        let (name_draft, addr_draft, port_draft, mac_draft, clip_draft) = (
+            name_draft.clone(),
+            addr_draft.clone(),
+            port_draft.clone(),
+            mac_draft.clone(),
+            clip_draft.clone(),
+        );
         move || {
-            let draft = live.borrow();
-            let name = draft.trim();
-            if !name.is_empty() {
-                let mut known = KnownHosts::load();
-                if let Some(h) = known.hosts.iter_mut().find(|h| h.fp_hex == fp) {
-                    h.name = name.to_string();
+            let mut known = KnownHosts::load();
+            if let Some(h) = known.hosts.iter_mut().find(|h| h.fp_hex == fp) {
+                // Each field falls back to what was stored: a cleared box means "leave it",
+                // never "erase it" — except the MAC, which is legitimately clearable.
+                let name = name_draft.borrow().trim().to_string();
+                if !name.is_empty() {
+                    h.name = name;
                 }
-                let _ = known.save();
+                let addr = addr_draft.borrow().trim().to_string();
+                if !addr.is_empty() {
+                    h.addr = addr;
+                }
+                if let Ok(p) = port_draft.borrow().trim().parse::<u16>() {
+                    if p != 0 {
+                        h.port = p;
+                    }
+                }
+                let mac = mac_draft.borrow().trim().to_string();
+                h.mac = if mac.is_empty() {
+                    Vec::new()
+                } else {
+                    mac.split(&[',', ' '][..])
+                        .filter(|m| !m.trim().is_empty())
+                        .map(|m| m.trim().to_string())
+                        .collect()
+                };
+                h.clipboard_sync = *clip_draft.borrow();
             }
-            sr.call(None);
+            let _ = known.save();
+            se.call(None);
         }
     };
-    let on_changed = {
-        let live = live.clone();
-        move |s: String| live.set(s)
+    let field = |label: &str, value: String, placeholder: &str, draft: HookRef<String>| {
+        vstack((
+            text_block(label)
+                .font_size(12.0)
+                .foreground(ThemeRef::SecondaryText)
+                .horizontal_alignment(HorizontalAlignment::Left),
+            text_box(&value)
+                .placeholder_text(placeholder)
+                .on_text_changed(move |t: String| draft.set(t)),
+        ))
+        .spacing(2.0)
     };
+    let (name0, addr0, port0, mac0, clip0) = (
+        name_draft.borrow().clone(),
+        addr_draft.borrow().clone(),
+        port_draft.borrow().clone(),
+        mac_draft.borrow().clone(),
+        *clip_draft.borrow(),
+    );
+    let _ = initial_name;
     card(
         vstack((
-            text_box(initial)
-                .placeholder_text("Host name")
-                .on_text_changed(on_changed),
+            field("Name", name0, "e.g. Living Room", name_draft),
+            field("Address", addr0, "IP or hostname", addr_draft),
+            field("Port", port0, "9777", port_draft),
+            field(
+                "MAC (Wake-on-LAN)",
+                mac0,
+                "auto-filled when known",
+                mac_draft,
+            ),
+            vstack((
+                ToggleSwitch::new(clip0)
+                    .header("Share clipboard with this host")
+                    .on_content("On")
+                    .off_content("Off")
+                    .on_toggled(move |v: bool| clip_draft.set(v)),
+                text_block(
+                    "Copy on one machine, paste on the other. Off for every host until you \
+                     turn it on here; the host must allow it too.",
+                )
+                .font_size(12.0)
+                .foreground(ThemeRef::SecondaryText)
+                .wrap()
+                .horizontal_alignment(HorizontalAlignment::Left),
+            ))
+            .spacing(4.0),
             hstack((
                 button("Save")
                     .accent()
@@ -231,7 +304,7 @@ fn rename_editor(
                     .on_click(commit),
                 button("Cancel")
                     .subtle()
-                    .on_click(move || set_rename.call(None)),
+                    .on_click(move || set_edit.call(None)),
             ))
             .spacing(4.0),
         ))
@@ -264,16 +337,41 @@ pub(crate) fn hosts_page(props: &HostsProps, cx: &mut RenderCx) -> Element {
     let rename = props.rename.clone();
     let set_forget = &props.set_forget;
     let set_rename = &props.set_rename;
-    // The live rename draft, read at Save time (see `rename_editor`). Root `rename` carries only the
-    // INITIAL name, so it no longer round-trips per keystroke. Seed the draft each time the rename
-    // TARGET changes (start, cancel, or a switch to another host).
-    let rename_draft = cx.use_ref(String::new());
-    let rename_seed = cx.use_ref(Option::<String>::None);
+    // The live edit drafts, read at Save time (see `edit_editor`). Root `rename` carries only
+    // the target's fingerprint + initial name, so typing never round-trips through a
+    // re-render. Every draft is re-seeded from the STORED host whenever the edit target
+    // changes (open, cancel, or switching to another host).
+    let name_draft = cx.use_ref(String::new());
+    let addr_draft = cx.use_ref(String::new());
+    let port_draft = cx.use_ref(String::new());
+    let mac_draft = cx.use_ref(String::new());
+    let clip_draft = cx.use_ref(false);
+    let edit_seed = cx.use_ref(Option::<String>::None);
     {
         let active = rename.as_ref().map(|(fp, _)| fp.clone());
-        if *rename_seed.borrow() != active {
-            rename_draft.set(rename.as_ref().map(|(_, n)| n.clone()).unwrap_or_default());
-            rename_seed.set(active);
+        if *edit_seed.borrow() != active {
+            let stored = active.as_ref().and_then(|fp| {
+                KnownHosts::load()
+                    .hosts
+                    .into_iter()
+                    .find(|h| &h.fp_hex == fp)
+            });
+            name_draft.set(stored.as_ref().map(|h| h.name.clone()).unwrap_or_default());
+            addr_draft.set(stored.as_ref().map(|h| h.addr.clone()).unwrap_or_default());
+            port_draft.set(
+                stored
+                    .as_ref()
+                    .map(|h| h.port.to_string())
+                    .unwrap_or_default(),
+            );
+            mac_draft.set(
+                stored
+                    .as_ref()
+                    .map(|h| h.mac.join(", "))
+                    .unwrap_or_default(),
+            );
+            clip_draft.set(stored.as_ref().is_some_and(|h| h.clipboard_sync));
+            edit_seed.set(active);
         }
     }
     let hover = Hover {
@@ -314,20 +412,51 @@ pub(crate) fn hosts_page(props: &HostsProps, cx: &mut RenderCx) -> Element {
             .spacing(2.0)
             .grid_column(0)
             .vertical_alignment(VerticalAlignment::Center),
-            hstack((
-                header_btn("Add host", Symbol::Add).accent().on_click({
-                    let sa = set_show_add.clone();
-                    move || sa.call(true)
-                }),
-                header_btn("Shortcuts", Symbol::Keyboard).on_click({
-                    let ss = set_screen.clone();
-                    move || ss.call(Screen::Help)
-                }),
-                header_btn("Settings", Symbol::Setting).on_click({
-                    let ss = set_screen.clone();
-                    move || ss.call(Screen::Settings)
-                }),
-            ))
+            hstack({
+                let mut actions: Vec<Element> = vec![header_btn("Add host", Symbol::Add)
+                    .accent()
+                    .on_click({
+                        let sa = set_show_add.clone();
+                        move || sa.call(true)
+                    })
+                    .into()];
+                // The couch UI's front door, beside the other page actions. Absent on ARM64,
+                // where the session binary ships without its Skia console.
+                if CONSOLE_UI_AVAILABLE {
+                    actions.push(
+                        header_btn("Console UI", Symbol::Play)
+                            .tooltip(
+                                "The controller-driven couch interface \u{2014} host list, \
+                                 pairing and libraries, launching streams in the same window.",
+                            )
+                            .on_click({
+                                let (c, ss, st) =
+                                    (ctx.clone(), set_screen.clone(), set_status.clone());
+                                // No target: the console opens its OWN host view rather than
+                                // one host's library — the couch counterpart of this page.
+                                move || open_console(&c, None, &ss, &st)
+                            })
+                            .into(),
+                    );
+                }
+                actions.push(
+                    header_btn("Shortcuts", Symbol::Keyboard)
+                        .on_click({
+                            let ss = set_screen.clone();
+                            move || ss.call(Screen::Help)
+                        })
+                        .into(),
+                );
+                actions.push(
+                    header_btn("Settings", Symbol::Setting)
+                        .on_click({
+                            let ss = set_screen.clone();
+                            move || ss.call(Screen::Settings)
+                        })
+                        .into(),
+                );
+                actions
+            })
             .spacing(8.0)
             .grid_column(1)
             .vertical_alignment(VerticalAlignment::Center),
@@ -347,84 +476,23 @@ pub(crate) fn hosts_page(props: &HostsProps, cx: &mut RenderCx) -> Element {
         );
     }
 
-    // A controller is connected and a paired host is REACHABLE (advertising or probed —
-    // an offline host would just open the console onto an error scene): offer the couch
-    // experience — the console (gamepad) UI on the most recently used such host.
-    if CONSOLE_UI_AVAILABLE && props.pads > 0 {
-        let reachable = |k: &&crate::trust::KnownHost| {
-            hosts
-                .iter()
-                .any(|h| h.fp_hex == k.fp_hex || (h.addr == k.addr && h.port == k.port))
-                || props.probed.get(&k.fp_hex).copied().unwrap_or(false)
-        };
-        if let Some(k) = known
-            .hosts
-            .iter()
-            .filter(|h| h.paired)
-            .filter(reachable)
-            .max_by_key(|h| h.last_used.unwrap_or(0))
-        {
-            let target = Target {
-                name: k.name.clone(),
-                addr: k.addr.clone(),
-                port: k.port,
-                fp_hex: Some(k.fp_hex.clone()),
-                pair_optional: false,
-                mac: k.mac.clone(),
-            };
-            let svc = props.svc.clone();
-            body.push(
-                card(
-                    grid((
-                        vstack((
-                            text_block("Controller detected").font_size(14.0).semibold(),
-                            text_block(format!(
-                                "Browse {}\u{2019}s game library with the gamepad \u{2014} \
-                                 launches stream in the same window.",
-                                k.name
-                            ))
-                            .font_size(12.0)
-                            .wrap()
-                            .foreground(ThemeRef::SecondaryText),
-                        ))
-                        .spacing(2.0)
-                        .grid_column(0)
-                        .vertical_alignment(VerticalAlignment::Center),
-                        button("Open console UI")
-                            .accent()
-                            .icon(Symbol::Play)
-                            .on_click(move || {
-                                open_console(
-                                    &svc.ctx,
-                                    target.clone(),
-                                    &svc.set_screen,
-                                    &svc.set_status,
-                                )
-                            })
-                            .grid_column(1)
-                            .vertical_alignment(VerticalAlignment::Center)
-                            .margin(edges(12.0, 0.0, 0.0, 0.0)),
-                    ))
-                    .columns([GridLength::Star(1.0), GridLength::Auto]),
-                )
-                .into(),
-            );
-        }
-    }
-
     // Saved (trusted/paired) hosts — reachable even when mDNS isn't. A saved host that's also
     // being advertised right now shows as Online (and is deduped out of the discovery section).
     if !known.hosts.is_empty() {
         body.push(section("SAVED HOSTS"));
         let mut tiles: Vec<Element> = Vec::new();
         for k in &known.hosts {
-            // Rust 2021 (no let-chains): match the "this tile is being renamed" case explicitly.
+            // Rust 2021 (no let-chains): match the "this tile is being edited" case explicitly.
             if matches!(&rename, Some((fp, _)) if fp == &k.fp_hex) {
                 let (fp, initial) = rename.clone().unwrap();
-                tiles.push(rename_editor(
+                tiles.push(edit_editor(
+                    &fp,
                     &initial,
-                    fp,
-                    rename_draft.clone(),
+                    name_draft.clone(),
+                    addr_draft.clone(),
+                    port_draft.clone(),
+                    mac_draft.clone(),
+                    clip_draft.clone(),
                     set_rename.clone(),
                 ));
                 continue;
@@ -471,15 +539,12 @@ pub(crate) fn hosts_page(props: &HostsProps, cx: &mut RenderCx) -> Element {
                         if library_enabled && k.paired {
                             items.push(menu_item(MENU_LIBRARY));
                         }
-                        if CONSOLE_UI_AVAILABLE && k.paired {
-                            items.push(menu_item(MENU_CONSOLE));
-                        }
                         items.push(menu_item(MENU_SPEED));
                         // Offer an explicit wake only when the host is offline and we have a MAC.
                         if can_wake {
                             items.push(menu_item(MENU_WAKE));
                         }
-                        items.push(menu_item(MENU_RENAME));
+                        items.push(menu_item(MENU_EDIT));
                         items.push(menu_separator());
                         items.push(menu_item(MENU_FORGET));
                         items
@@ -493,9 +558,6 @@ pub(crate) fn hosts_page(props: &HostsProps, cx: &mut RenderCx) -> Element {
                             super::library::start_fetch(&svc.ctx, &svc.set_library);
                             svc.set_screen.call(Screen::Library);
                         }
-                        MENU_CONSOLE => {
-                            open_console(&svc.ctx, target.clone(), &svc.set_screen, &svc.set_status)
-                        }
                         MENU_WAKE => crate::wol::wake(&target.mac, target.addr.parse().ok()),
                         MENU_SPEED => {
                             *svc.ctx.shared.target.lock().unwrap() = target.clone();
@@ -507,7 +569,7 @@ pub(crate) fn hosts_page(props: &HostsProps, cx: &mut RenderCx) -> Element {
                             svc.set_speed.call(SpeedState::Running);
                             svc.set_screen.call(Screen::SpeedTest);
                         }
-                        MENU_RENAME => sr.call(Some((fp.clone(), name.clone()))),
+                        MENU_EDIT => sr.call(Some((fp.clone(), name.clone()))),
                         MENU_FORGET => sf.call(Some((fp.clone(), name.clone()))),
                         _ => {}
                     })

clients/windows/src/app/mod.rs

@@ -241,7 +241,8 @@ fn root(cx: &mut RenderCx, ctx: &Arc<AppCtx>) -> Element {
     // reactor backend, so only a root `AsyncSetState` reliably re-renders the page.
     let (hover, set_hover) = cx.use_async_state(Option::<String>::None);
     // Which Settings section the NavigationView shows (persists across visits this run).
-    let (settings_nav, set_settings_nav) = cx.use_async_state("display".to_string());
+    // Opens on General — the first sidebar item, matching the Apple client's landing category.
+    let (settings_nav, set_settings_nav) = cx.use_async_state("general".to_string());
     // Connected-controller count, mirrored from the gamepad service by a poll thread
     // (thread-driven state must be root state — see the module docs). Drives the hosts
     // page's "Open console UI" hint; the compare in `call` makes the steady state free.

clients/windows/src/app/pair.rs

@@ -59,6 +59,7 @@ pub(crate) fn pair_page(props: &Svc, cx: &mut RenderCx) -> Element {
                                 paired: true,
                                 last_used: None,
                                 mac: target3.mac.clone(),
+                                clipboard_sync: false,
                             });
                             let _ = k.save();
                             connect(&ctx3, &target3, Some(fp), &ss, &st);

clients/windows/src/app/settings.rs

@@ -1,5 +1,15 @@
 //! The settings screen. Every control writes straight back to the persisted [`Settings`]
 //! (there is no Apply step), via the small [`setting_combo`]/[`setting_toggle`] builders.
+//!
+//! **Structure mirrors the Apple client's 2026-07 settings revamp** (its
+//! `SettingsCategory` + `SettingsView+Sections.swift`), so the two desktop clients read the
+//! same way: General = session/app behavior, Display = everything about the picture,
+//! Input = touch/keyboard/mouse, Audio, Controllers, About. Each field carries its
+//! explanation DIRECTLY under it ([`described`]) rather than only on hover — the same move
+//! Apple made, for the same reason (guidance nobody hovers for is guidance nobody reads).
+//! Wording is shared verbatim wherever the setting means the same thing on both platforms;
+//! where the BEHAVIOR differs the text is deliberately Windows-specific (the forwarded-
+//! controller picker especially: Apple forwards one pad, this client forwards them all).
 
 use super::style::*;
 use super::{AppCtx, Screen};
@@ -38,7 +48,8 @@ fn render_scale_label(scale: f64) -> String {
 // Automatic — which is exactly how the session's decoder chain reads that value.
 const DECODERS: &[(&str, &str)] = &[
     ("auto", "Automatic (GPU, fall back to CPU)"),
-    ("vulkan", "Hardware (GPU / Vulkan Video)"),
+    ("vulkan", "Hardware (Vulkan Video)"),
+    ("d3d11va", "Hardware (Direct3D 11 / DXVA)"),
     ("software", "Software (CPU)"),
 ];
 /// Audio channel presets: `(channel count, display label)`. The host clamps to what it can
@@ -51,6 +62,9 @@ const CODECS: &[(&str, &str)] = &[
     ("hevc", "HEVC (H.265)"),
     ("h264", "H.264 (AVC)"),
     ("av1", "AV1"),
+    // Preference-only by design: `resolve_codec` never auto-picks PyroWave, and asking for
+    // it on a host or device that can't do it simply falls back down the ladder to HEVC.
+    ("pyrowave", "PyroWave (wired LAN)"),
 ];
 /// Virtual-pad presets: `(stored value, display label)` — the pad the HOST creates. Same set the
 /// GTK client offers; "Automatic" resolves from the physical controller at connect.
@@ -134,11 +148,63 @@ fn setting_toggle(
         })
 }
 
-/// A settings card: just the controls. No heading (the section title is the NavigationView
-/// header) and no description paragraph — per-control guidance is a `.tooltip(...)` on the
-/// control itself (a paragraph in the card reads as the first control's label).
-fn settings_card(controls: Vec<Element>) -> Element {
-    card(vstack(controls).spacing(10.0)).into()
+/// One field: the control with its explanation directly underneath (Apple's `described`).
+///
+/// The caption goes BELOW the control on purpose. An earlier revision put guidance only in
+/// hover tooltips because a paragraph *above* a control reads as that control's label — true,
+/// but a caption under it reads as a caption, which is how every Windows Settings page and
+/// the Apple client both do it. Width-capped for the same reason Apple caps at 360pt: a
+/// full-width caption runs into the control column and the whole cell reads as one block.
+fn described(control: impl Into<Element>, caption: &str) -> Element {
+    vstack((
+        control.into(),
+        text_block(caption)
+            .font_size(12.0)
+            .foreground(ThemeRef::SecondaryText)
+            .wrap()
+            .max_width(420.0)
+            // Stretch (the TextBlock default) CENTRES a MaxWidth-capped block in the leftover
+            // width — the caption must be pinned left or it drifts away from its control.
+            .horizontal_alignment(HorizontalAlignment::Left),
+    ))
+    .spacing(5.0)
+    .into()
+}
+
+/// A settings sub-section heading. Deliberately NOT the shared [`section`] helper: that one
+/// carries a 2px left inset (fine over the hosts/licenses lists it was written for), which
+/// here left every heading hanging one nudge right of the card edge below it. Flush left, so
+/// heading and card share one line.
+fn group_heading(label: &str) -> Element {
+    text_block(label)
+        .font_size(12.0)
+        .semibold()
+        .foreground(ThemeRef::SecondaryText)
+        .horizontal_alignment(HorizontalAlignment::Left)
+        .margin(edges(0.0, 14.0, 0.0, 2.0))
+        .into()
+}
+
+/// One settings group: an optional sub-section label, a card of fields, and an optional
+/// form-level note under it (Apple's Section header/footer). Groups stack down the page.
+fn group(header: Option<&str>, fields: Vec<Element>, footer: Option<&str>) -> Vec<Element> {
+    let mut out = Vec::with_capacity(3);
+    if let Some(h) = header {
+        out.push(group_heading(h));
+    }
+    out.push(card(vstack(fields).spacing(14.0)).into());
+    if let Some(f) = footer {
+        out.push(
+            text_block(f)
+                .font_size(12.0)
+                .foreground(ThemeRef::SecondaryText)
+                .wrap()
+                .horizontal_alignment(HorizontalAlignment::Left)
+                .margin(edges(0.0, 6.0, 0.0, 0.0))
+                .into(),
+        );
+    }
+    out
 }
 
 /// The settings screen: a stock WinUI `NavigationView` (the Windows-Settings sidebar pattern) —
@@ -183,12 +249,7 @@ pub(crate) fn settings_page(
     let res_combo = setting_combo(ctx, "Resolution", res_names, res_i, |s, i| {
         s.match_window = i == 1;
         (s.width, s.height) = if i <= 1 { (0, 0) } else { RESOLUTIONS[i - 1] };
-    })
-    .tooltip(
-        "The host creates a virtual display at exactly this size. \u{201C}Native display\u{201D} \
-         resolves to the monitor this window is on at connect; \u{201C}Match window\u{201D} \
-         follows the stream window, including mid-stream resizes.",
-    );
+    });
     let (hz_names, hz_i) = {
         let names: Vec<String> = REFRESH
             .iter()
@@ -205,8 +266,7 @@ pub(crate) fn settings_page(
     };
     let hz_combo = setting_combo(ctx, "Refresh rate", hz_names, hz_i, |s, i| {
         s.refresh_hz = REFRESH[i];
-    })
-    .tooltip("\u{201C}Native\u{201D} resolves to this display's refresh rate at connect.");
+    });
     let (scale_names, scale_i) = {
         let names: Vec<String> = RENDER_SCALES
             .iter()
@@ -220,36 +280,26 @@ pub(crate) fn settings_page(
     };
     let scale_combo = setting_combo(ctx, "Render scale", scale_names, scale_i, |s, i| {
         s.render_scale = RENDER_SCALES[i];
-    })
-    .tooltip(
-        "Supersample for sharpness (above 1\u{00D7}, more bandwidth and decode) or render below \
-         native (below 1\u{00D7}) for a lighter host \u{2014} this device resamples to the window.",
-    );
+    });
     let (comp_names, comp_i) = presets(COMPOSITORS, |v| *v == s.compositor);
     let comp_combo = setting_combo(ctx, "Host compositor", comp_names, comp_i, |s, i| {
         s.compositor = COMPOSITORS[i].0.to_string();
-    })
-    .tooltip(
-        "Linux hosts only, and advisory \u{2014} the host falls back to auto-detect when the \
-         choice is unavailable.",
-    );
+    });
+    let auto_wake_toggle = setting_toggle(ctx, "Auto-wake on connect", s.auto_wake, |s, on| {
+        s.auto_wake = on
+    });
     let fullscreen_toggle = setting_toggle(
         ctx,
         "Start streams fullscreen",
         s.fullscreen_on_stream,
         |s, on| s.fullscreen_on_stream = on,
-    )
-    .tooltip("The stream window opens fullscreen; F11 or Alt+Enter switches back live.");
+    );
 
     // --- Video -----------------------------------------------------------------------------
     let (dec_names, dec_i) = presets(DECODERS, |v| *v == s.decoder);
     let decoder_combo = setting_combo(ctx, "Video decoder", dec_names, dec_i, |s, i| {
         s.decoder = DECODERS[i].0.to_string();
-    })
-    .tooltip(
-        "Hardware decode (Vulkan Video) is far lighter than software \u{2014} keep it on \
-         Automatic unless debugging.",
-    );
+    });
     // GPU picker, only on a multi-GPU box (hybrid laptop, eGPU): which adapter decodes + presents.
     // Stored as the adapter description; empty = automatic (the window's monitor's adapter).
     let gpus = crate::gpu::adapter_names();
@@ -268,18 +318,11 @@ pub(crate) fn settings_page(
                 gpus[i - 1].clone()
             };
         })
-        .tooltip(
-            "Which adapter decodes and presents the stream. Applies to the next stream; \
-             Automatic uses the GPU driving this window's display.",
-        )
     });
     let (codec_names, codec_i) = presets(CODECS, |v| *v == s.codec);
     let codec_combo = setting_combo(ctx, "Video codec", codec_names, codec_i, |s, i| {
         s.codec = CODECS[i].0.to_string();
-    })
-    .tooltip(
-        "A soft preference \u{2014} the host falls back to the best codec both sides support.",
-    );
+    });
     // Free-form Mb/s (0 = host default) instead of presets, so a speed-test recommendation
     // round-trips exactly.
     let bitrate_box = {
@@ -292,18 +335,10 @@ pub(crate) fn settings_page(
                 s.bitrate_kbps = (v.clamp(0.0, 3000.0) * 1000.0) as u32;
                 s.save();
             })
-            .tooltip(
-                "0 lets the host decide. Run a per-host speed test from the host list for a \
-                 recommendation.",
-            )
     };
     let hdr_toggle = setting_toggle(ctx, "HDR (10-bit, BT.2020 PQ)", s.hdr_enabled, |s, on| {
         s.hdr_enabled = on
-    })
-    .tooltip(
-        "Advertise 10-bit HDR10 so the host upgrades HDR content. Needs a display in HDR mode; \
-         SDR content is unaffected.",
-    );
+    });
 
     // --- Input -----------------------------------------------------------------------------
     // Controller forwarding: Automatic forwards EVERY real controller, each as its own pad;
@@ -348,60 +383,44 @@ pub(crate) fn settings_page(
                 s.forward_pad = key.unwrap_or_default();
                 s.save();
             })
-            .tooltip(
-                "Every connected controller is forwarded, each as its own player. Pick one \
-                 to force single-player \u{2014} only it reaches the host.",
-            )
     };
     let (pad_names, pad_i) = presets(GAMEPADS, |v| {
         GamepadPref::from_name(v) == GamepadPref::from_name(&s.gamepad)
     });
     let pad_combo = setting_combo(ctx, "Gamepad type", pad_names, pad_i, |s, i| {
         s.gamepad = GAMEPADS[i].0.to_string();
-    })
-    .tooltip(
-        "The virtual pad the host creates. \u{201C}Automatic\u{201D} matches your physical \
-         controller.",
-    );
+    });
     let (touch_names, touch_i) = presets(TOUCH_MODES, |v| *v == s.touch_mode);
     let touch_combo = setting_combo(ctx, "Touch input", touch_names, touch_i, |s, i| {
         s.touch_mode = TOUCH_MODES[i].0.to_string();
-    })
-    .tooltip(
-        "How a touchscreen drives the host: Trackpad nudges a cursor (tap to click), Direct \
-         pointer jumps to your finger, Touch passthrough sends real touches.",
-    );
+    });
+    let invert_scroll_toggle =
+        setting_toggle(ctx, "Invert scroll direction", s.invert_scroll, |s, on| {
+            s.invert_scroll = on
+        });
     let shortcuts_toggle = setting_toggle(
         ctx,
         "Capture system shortcuts (Alt+Tab, Win, \u{2026})",
         s.inhibit_shortcuts,
         |s, on| s.inhibit_shortcuts = on,
-    )
-    .tooltip("Off: Alt+Tab, Win & co. act on this machine while the stream input is captured.");
+    );
 
     // --- Audio -----------------------------------------------------------------------------
     let (ac_names, ac_i) = presets(AUDIO_CHANNELS, |v| *v == s.audio_channels);
     let channels_combo = setting_combo(ctx, "Audio channels", ac_names, ac_i, |s, i| {
         s.audio_channels = AUDIO_CHANNELS[i].0;
-    })
-    .tooltip("The host downmixes if its output has fewer channels.");
+    });
     let mic_toggle = setting_toggle(
         ctx,
         "Stream microphone to the host",
         s.mic_enabled,
         |s, on| s.mic_enabled = on,
-    )
-    .tooltip("Sends the default microphone to the host's virtual mic source.");
+    );
 
     let (hud_names, hud_i) = presets(STATS_TIERS, |v| *v == s.stats_verbosity());
     let hud_combo = setting_combo(ctx, "Stats overlay (HUD)", hud_names, hud_i, |s, i| {
         s.set_stats_verbosity(STATS_TIERS[i].0);
-    })
-    .tooltip(
-        "How much the in-stream overlay shows: Compact (fps \u{00B7} latency \u{00B7} bitrate \
-         in one line) \u{2192} Normal \u{2192} Detailed (decode path and per-stage latency). \
-         Ctrl+Alt+Shift+S cycles the tiers live while streaming.",
-    );
+    });
 
     let licenses_button = {
         let ss = set_screen.clone();
@@ -412,10 +431,6 @@ pub(crate) fn settings_page(
         "Show game library (experimental)",
         s.library_enabled,
         |s, on| s.library_enabled = on,
-    )
-    .tooltip(
-        "Adds \u{201C}Browse library\u{2026}\u{201D} to paired hosts \u{2014} pick a game and it \
-         launches in the stream. Mirrors the Apple client's toggle.",
     );
     // App identity + version at the top of the About card (the WinUI Settings convention; the About
     // screen previously showed no version at all). CARGO_PKG_VERSION is the workspace version, baked
@@ -428,70 +443,227 @@ pub(crate) fn settings_page(
     ))
     .spacing(2.0);
 
-    // The selected section's content — per-control guidance lives on hover tooltips, so the
-    // card is just the controls.
-    let (title, card): (&str, Element) = match section {
-        "video" => (
-            "Video",
-            settings_card({
-                let mut controls: Vec<Element> = vec![decoder_combo.into()];
-                if let Some(c) = gpu_combo {
-                    controls.push(c.into());
-                }
-                controls.extend([
-                    codec_combo.into(),
-                    bitrate_box.into(),
-                    hdr_toggle.into(),
-                    hud_combo.into(),
-                ]);
-                controls
-            }),
-        ),
-        "input" => (
-            "Input",
-            settings_card(vec![
-                forward_combo.into(),
-                pad_combo.into(),
-                touch_combo.into(),
-                shortcuts_toggle.into(),
-            ]),
+    // The selected section's content, grouped exactly like the Apple client's categories
+    // (SettingsCategory + SettingsView+Sections.swift). Each field's explanation sits under
+    // it; the only form-level notes are the "applies from the next session" footers, matching
+    // Apple's decision to keep exactly one of those per affected category.
+    let (title, groups): (&str, Vec<Element>) = match section {
+        "display" => {
+            let mut out = group(
+                Some("Resolution"),
+                vec![
+                    described(
+                        res_combo,
+                        "The host drives a real virtual output at exactly this size \u{2014} true \
+                         pixels, no scaling. \u{201C}Native display\u{201D} follows the monitor this \
+                         window is on; \u{201C}Match window\u{201D} keeps the picture pixel-exact \
+                         (1:1) through every resize.",
+                    ),
+                    described(
+                        hz_combo,
+                        "\u{201C}Native\u{201D} resolves to this display\u{2019}s refresh rate at \
+                         connect.",
+                    ),
+                ],
+                None,
+            );
+            out.extend(group(
+                Some("Quality"),
+                vec![
+                    described(
+                        scale_combo,
+                        "Above native supersamples for sharpness; below renders lighter on the \
+                         host and the link. This device resamples the result to the window.",
+                    ),
+                    described(
+                        bitrate_box,
+                        "0 lets the host decide (its default, clamped to what it supports). A \
+                         host card\u{2019}s context menu has a network speed test.",
+                    ),
+                    described(
+                        codec_combo,
+                        "A preference \u{2014} the host falls back if it can\u{2019}t encode it. \
+                         PyroWave is the low-latency wavelet codec for a WIRED link: it trades \
+                         bitrate (hundreds of Mb/s) for near-zero decode time, so it wants \
+                         gigabit Ethernet.",
+                    ),
+                    described(
+                        hdr_toggle,
+                        "HDR10, when the host has HDR content and this display supports it. \
+                         HEVC only; otherwise the stream stays SDR.",
+                    ),
+                ],
+                None,
+            ));
+            out.extend(group(
+                Some("Decoding"),
+                {
+                    let mut fields = vec![described(
+                        decoder_combo,
+                        "Automatic picks the hardware path this GPU does best \u{2014} Direct3D \
+                         11 on Intel, Vulkan Video on NVIDIA and AMD \u{2014} and falls back to \
+                         the CPU. Change it only when debugging.",
+                    )];
+                    if let Some(c) = gpu_combo {
+                        fields.push(described(
+                            c,
+                            "Which adapter decodes and presents the stream. Automatic uses the \
+                             GPU driving this window\u{2019}s display.",
+                        ));
+                    }
+                    fields
+                },
+                None,
+            ));
+            out.extend(group(
+                Some("Host output"),
+                vec![described(
+                    comp_combo,
+                    "The backend the host uses for its virtual output (Linux hosts only). A \
+                     specific choice falls back to auto-detection when that backend \
+                     isn\u{2019}t available.",
+                )],
+                // The one form-level note, exactly as on Apple.
+                Some("Display changes apply from the next session."),
+            ));
+            ("Display", out)
+        }
+        "input" => {
+            let mut out = group(
+                Some("Touch & pointer"),
+                vec![described(
+                    touch_combo,
+                    "How a touchscreen drives the host: Trackpad moves the host cursor like a \
+                     laptop trackpad (tap to click), Direct pointer jumps the cursor to wherever \
+                     you touch, Touch passthrough sends real multi-touch through.",
+                )],
+                None,
+            );
+            out.extend(group(
+                Some("Keyboard & mouse"),
+                vec![
+                    described(
+                        shortcuts_toggle,
+                        "Alt+Tab, the Windows key and friends reach the host while the stream \
+                         has input captured. Off, they act on this machine instead.",
+                    ),
+                    described(
+                        invert_scroll_toggle,
+                        "Reverses the wheel and trackpad scroll direction sent to the host.",
+                    ),
+                ],
+                None,
+            ));
+            ("Input", out)
+        }
+        "controllers" => (
+            "Controllers",
+            group(
+                None,
+                vec![
+                    // NOT Apple's wording: Apple forwards ONE pad as player 1, this client
+                    // forwards every controller as its own player. Same picker, different rule.
+                    described(
+                        forward_combo,
+                        "Every connected controller is forwarded, each as its own player. Pick \
+                         one to force single-player \u{2014} only it reaches the host.",
+                    ),
+                    described(
+                        pad_combo,
+                        "The virtual pad created on the host. Automatic matches your controller \
+                         \u{2014} a DualSense keeps adaptive triggers, lightbar, touchpad and \
+                         motion.",
+                    ),
+                ],
+                Some("Applies from the next session."),
+            ),
         ),
         "audio" => (
             "Audio",
-            settings_card(vec![channels_combo.into(), mic_toggle.into()]),
+            group(
+                None,
+                vec![
+                    described(
+                        channels_combo,
+                        "The speaker layout requested from the host. It downmixes if its own \
+                         output has fewer channels.",
+                    ),
+                    described(
+                        mic_toggle,
+                        "This device\u{2019}s microphone feeds the host\u{2019}s virtual mic.",
+                    ),
+                ],
+                Some("Applies from the next session."),
+            ),
         ),
         "about" => (
             "About",
-            settings_card(vec![
-                about_identity.into(),
-                library_toggle.into(),
-                licenses_button.into(),
-            ]),
-        ),
-        _ => (
-            "Display",
-            settings_card(vec![
-                res_combo.into(),
-                hz_combo.into(),
-                scale_combo.into(),
-                fullscreen_toggle.into(),
-                comp_combo.into(),
-            ]),
+            group(
+                None,
+                vec![about_identity.into(), licenses_button.into()],
+                None,
+            ),
         ),
+        // "general" and anything unrecognized.
+        _ => {
+            let mut out = group(
+                Some("Session"),
+                vec![
+                    described(
+                        fullscreen_toggle,
+                        "Go fullscreen when a session starts; F11 or Alt+Enter switches back \
+                         live.",
+                    ),
+                    described(
+                        auto_wake_toggle,
+                        "Connecting to a saved host that\u{2019}s offline sends Wake-on-LAN and \
+                         waits for it to boot. Turn off if hosts behind a VPN look offline when \
+                         they aren\u{2019}t.",
+                    ),
+                ],
+                None,
+            );
+            out.extend(group(
+                Some("Statistics"),
+                vec![described(
+                    hud_combo,
+                    "Live session stats in a corner overlay \u{2014} Compact is a one-line pill, \
+                     Detailed adds the latency stage breakdown. Ctrl+Alt+Shift+S cycles the \
+                     tiers any time.",
+                )],
+                None,
+            ));
+            out.extend(group(
+                Some("Library"),
+                vec![described(
+                    library_toggle,
+                    "Adds \u{201C}Browse library\u{2026}\u{201D} to paired hosts \u{2014} list \
+                     their Steam and custom games and launch one directly. No extra host setup.",
+                )],
+                None,
+            ));
+            ("General", out)
+        }
     };
 
     // The stock WinUI sidebar (Windows-Settings pattern): pane on the left, the section's card
     // as content, the NavigationView's own back arrow returning to the host list. Auto display
     // mode collapses the pane on a narrow window, exactly like Windows Settings.
+    // Category order mirrors the Apple client's sidebar exactly.
     let items = vec![
+        NavViewItem::new("General")
+            .tag("general")
+            .icon(Symbol::Setting),
         NavViewItem::new("Display")
             .tag("display")
             .icon(Symbol::FullScreen),
-        NavViewItem::new("Video").tag("video").icon(Symbol::Video),
         NavViewItem::new("Input")
             .tag("input")
             .icon(Symbol::Keyboard),
         NavViewItem::new("Audio").tag("audio").icon(Symbol::Volume),
+        NavViewItem::new("Controllers")
+            .tag("controllers")
+            .icon(Symbol::Play),
         NavViewItem::new("About").tag("about").icon(Symbol::Help),
     ];
     // The card is KEYED by section so switching panes REMOUNTS it instead of diffing one
@@ -502,12 +674,38 @@ pub(crate) fn settings_page(
     //
     // The content column (not the NavigationView — the sidebar must stay put) carries the
     // section-switch entrance: fade + slide-up from the root-driven tween.
-    let content = page_wide(vec![card.with_key(section)])
-        .opacity(progress)
-        .margin(edges(0.0, (1.0 - progress) * 22.0, 0.0, 0.0));
+    // No max-width cap here (unlike the other pages): the NavigationView already spends the
+    // left third on its pane, so a 640-wide column left the cards as a narrow ribbon.
+    // The category title is rendered HERE, not via NavigationView's Header: that header's
+    // left inset belongs to WinUI's own template (a string prop is all we can set), so it
+    // sat noticeably right of the cards under it. In the content column it shares the cards'
+    // left edge by construction.
+    let titled: Vec<Element> = std::iter::once(
+        text_block(title)
+            .font_size(28.0)
+            .semibold()
+            .horizontal_alignment(HorizontalAlignment::Left)
+            .margin(edges(0.0, 0.0, 0.0, 6.0))
+            .into(),
+    )
+    .chain(groups)
+    .collect();
+    // The keyed column MUST sit inside a panel's child list, not directly under the
+    // scroll_view: `ScrollView::children()` is `Children::PositionalSingle`, which
+    // reconciles its one child POSITIONALLY and ignores keys outright. Keyed straight onto
+    // the scroll_view's child, the section switch silently diffs one section's controls into
+    // another's — which re-sets each reused ComboBox's items (clearing WinUI's selection)
+    // but skips `selected_index` whenever the two sections' values compare equal, so the
+    // combos render blank until touched. A panel (vstack) takes the keyed path, so the key
+    // remounts the whole column and every prop is applied fresh.
+    let content = scroll_view(
+        vstack(vec![vstack(titled).spacing(10.0).with_key(section).into()])
+            .margin(edges(24.0, 20.0, 28.0, 40.0)),
+    )
+    .opacity(progress)
+    .margin(edges(0.0, (1.0 - progress) * 22.0, 0.0, 0.0));
     NavigationView::new(items, content)
         .pane_title("Settings")
-        .header(title)
         .selected_tag(section)
         .on_selection_changed({
             let ss = set_section.clone();

clients/windows/src/bin/punktfunk-console.rs

@@ -0,0 +1,38 @@
+//! `punktfunk-console.exe` — the couch/HTPC entry point.
+//!
+//! Exists because an MSIX `<Application>` cannot pass ARGUMENTS to a full-trust executable:
+//! a second Start-menu tile therefore cannot simply be "punktfunk-client.exe --console", it
+//! needs its own executable. This is that executable, and it is deliberately nothing but a
+//! hand-off — it starts the session binary's `--browse` mode (the complete controller-driven
+//! client: host list, discovery, PIN pairing, settings, Wake-on-LAN, library) fullscreen and
+//! mirrors its exit code, so whatever supervises this process sees the real result.
+//!
+//! `--windowed` keeps it in a window; everything else is the session binary's own business.
+
+// No console window: this is launched from a Start-menu tile / shortcut, and a flashing
+// console behind the couch UI looks like a crash.
+#![cfg_attr(windows, windows_subsystem = "windows")]
+
+#[cfg(windows)]
+fn main() {
+    // The session binary ships beside us in the package; fall back to PATH for a dev run.
+    let session = std::env::current_exe()
+        .ok()
+        .map(|e| e.with_file_name("punktfunk-session.exe"))
+        .filter(|p| p.exists())
+        .unwrap_or_else(|| "punktfunk-session".into());
+
+    let mut cmd = std::process::Command::new(session);
+    cmd.arg("--browse");
+    if !std::env::args().any(|a| a == "--windowed") {
+        cmd.arg("--fullscreen");
+    }
+    match cmd.status() {
+        Ok(st) => std::process::exit(st.code().unwrap_or(0)),
+        Err(_) => std::process::exit(1),
+    }
+}
+
+/// The workspace builds on Linux/macOS too; there is nothing to launch there.
+#[cfg(not(windows))]
+fn main() {}

clients/windows/src/gpu.rs

@@ -41,16 +41,41 @@ fn all_adapters() -> Vec<IDXGIAdapter> {
 
 /// Descriptions of the real (hardware, non-WARP) GPUs — the Settings GPU picker's option list.
 /// The picker only shows when this has more than one entry.
+///
+/// **Deduplicated by description**, because the description IS the identity everywhere
+/// downstream: the pick is persisted as that string (`Settings::adapter`) and matched by
+/// name in the session binary (`PUNKTFUNK_VK_ADAPTER`). So two entries with the same name
+/// are one selectable choice however many times DXGI enumerates them — listing it twice
+/// only offers the user a meaningless coin flip. Seen live on an Intel Arc laptop
+/// (2026-07-19), whose Vulkan ICD likewise enumerates the one physical iGPU twice.
 pub fn adapter_names() -> Vec<String> {
     const DXGI_ADAPTER_FLAG_SOFTWARE: u32 = 2; // dxgi.h; not in this windows-rs feature set
-    all_adapters()
-        .iter()
-        .filter(|a| {
-            a.cast::<windows::Win32::Graphics::Dxgi::IDXGIAdapter1>()
-                .and_then(|a1| unsafe { a1.GetDesc1() })
-                .map(|d| d.Flags & DXGI_ADAPTER_FLAG_SOFTWARE == 0)
-                .unwrap_or(true)
-        })
-        .map(adapter_name)
-        .collect()
+    let mut names: Vec<String> = Vec::new();
+    for a in all_adapters() {
+        let desc1 = a
+            .cast::<windows::Win32::Graphics::Dxgi::IDXGIAdapter1>()
+            .and_then(|a1| unsafe { a1.GetDesc1() })
+            .ok();
+        let name = adapter_name(&a);
+        // Forensics for the next duplicate/oddity report — which adapters DXGI actually
+        // returned, and whether the repeats share a LUID (one adapter enumerated twice)
+        // or are distinct devices that merely present the same description.
+        if let Some(d) = &desc1 {
+            tracing::debug!(
+                name = %name,
+                luid = format!("{:08x}-{:08x}", d.AdapterLuid.HighPart, d.AdapterLuid.LowPart),
+                vendor = format_args!("{:#06x}", d.VendorId),
+                device = format_args!("{:#06x}", d.DeviceId),
+                flags = d.Flags,
+                "DXGI adapter"
+            );
+        }
+        if desc1.is_some_and(|d| d.Flags & DXGI_ADAPTER_FLAG_SOFTWARE != 0) {
+            continue; // WARP / software renderer — never a streaming target
+        }
+        if !names.contains(&name) {
+            names.push(name);
+        }
+    }
+    names
 }

clients/windows/src/main.rs

@@ -76,6 +76,27 @@ fn main() {
         return;
     }
 
+    // `--console`: go straight to the gamepad/couch UI, skipping the WinUI shell entirely —
+    // the HTPC entry point (a Start-menu tile, a Steam shortcut, a startup item). The session
+    // binary's bare `--browse` IS a complete standalone client: host list, discovery, PIN
+    // pairing, settings and Wake-on-LAN, all controller-driven. We just exec it and mirror
+    // its exit code, so anything supervising this process sees the real result.
+    if flag("--console") {
+        let mut cmd = std::process::Command::new(spawn::session_binary());
+        cmd.arg("--browse");
+        // A couch UI is fullscreen unless explicitly told otherwise.
+        if !flag("--windowed") {
+            cmd.arg("--fullscreen");
+        }
+        match cmd.status() {
+            Ok(st) => std::process::exit(st.code().unwrap_or(0)),
+            Err(e) => {
+                eprintln!("could not start the console UI: {e}");
+                std::process::exit(1);
+            }
+        }
+    }
+
     // Windowed (default): the WinUI 3 app owns host selection, settings, and pairing.
     // Framework-dependent deployment: initialize the Windows App SDK runtime before any WinUI
     // call (build.rs stages the bootstrap DLL via windows-reactor-setup).

clients/windows/src/spawn.rs

@@ -126,21 +126,26 @@ pub(crate) fn spawn_session(
 /// The same stdout contract as a connect (`--json-status`): `ready` when the library
 /// window presents, `error` on a failed start, EOF on quit.
 pub(crate) fn spawn_browse(
-    addr: &str,
-    port: u16,
+    target: Option<(&str, u16)>,
     fullscreen: bool,
     slot: SessionChild,
     on_event: impl FnMut(SpawnEvent) + Send + 'static,
 ) -> Result<(), String> {
     let mut cmd = Command::new(session_binary());
-    cmd.arg("--browse")
-        .arg(format!("{addr}:{port}"))
-        .arg("--json-status");
+    cmd.arg("--browse");
+    // A target opens straight into that host's library; bare `--browse` opens the console's
+    // OWN host view (discovery, pairing, settings, Wake-on-LAN) — the couch equivalent of
+    // the shell's hosts page.
+    if let Some((addr, port)) = target {
+        cmd.arg(format!("{addr}:{port}"));
+    }
+    cmd.arg("--json-status");
     if fullscreen {
         cmd.arg("--fullscreen");
     }
     add_window_pos(&mut cmd);
-    spawn_with(cmd, &format!("{addr}:{port}"), slot, on_event)
+    let label = target.map_or_else(|| "console".to_string(), |(a, p)| format!("{a}:{p}"));
+    spawn_with(cmd, &label, slot, on_event)
 }
 
 /// Hand the shell window's position to the child (`--window-pos`) so the session window

crates/pf-capture/src/lib.rs

@@ -244,8 +244,13 @@ pub struct ZeroCopyPolicy {
     /// The resolved backend produces GPU-resident frames (everything but the software encoder) —
     /// used only to phrase the CPU-fallback warning (the host `encode::resolved_backend_is_gpu`).
     pub backend_is_gpu: bool,
+    /// THIS session encodes PyroWave: the frames' consumer is the wavelet encoder's own Vulkan
+    /// device, which imports raw dmabufs on ANY vendor — so the capturer takes the raw-dmabuf
+    /// passthrough (like the VAAPI backend) instead of the EGL→CUDA import whose payloads only
+    /// NVENC can consume. Per-session (the codec is negotiated), unlike `backend_is_vaapi`.
+    pub pyrowave_session: bool,
     /// The PyroWave encoder's Vulkan-importable dmabuf modifiers for the capture's packed-RGB fourcc,
-    /// resolved when the encoder pref is `pyrowave` (the passthrough advertises them so Mutter+NVIDIA,
+    /// resolved when the session encodes PyroWave (the passthrough advertises them so Mutter+NVIDIA,
     /// which allocates tiled-only, still negotiates zero-copy). Empty otherwise.
     pub pyrowave_modifiers: Vec<u64>,
 }
@@ -254,6 +259,55 @@ pub struct ZeroCopyPolicy {
 pub fn capturer_supports_444(_encoder_ingests_rgb_444: bool) -> bool {
     true
 }
+
+/// Whether the **native-plane** capturer (a compositor virtual output) can deliver an HDR (10-bit
+/// PQ/BT.2020) source on this platform — the capture-side gate the punktfunk/1 handshake consults
+/// before negotiating 10-bit (mirroring [`capturer_supports_444`]).
+///
+/// Linux: `false`. GNOME 50 added HDR **screen sharing** for *monitor* streams only — Mutter's
+/// `RecordVirtual` virtual-monitor streams advertise 8-bit BGRx/BGRA exclusively (still true on
+/// the GNOME 51 dev branch), and virtual outputs report no BT2020/PQ colour capabilities, so they
+/// can't be flipped into HDR mode via DisplayConfig either. The Linux HDR path that DOES exist —
+/// the GNOME 50+ portal **monitor mirror** (`open_portal_monitor` with `want_hdr`) — is gated
+/// separately by the GameStream plane (`host_hdr_capable` + the live monitor colour-mode probe).
+#[cfg(target_os = "linux")]
+pub fn capturer_supports_hdr() -> bool {
+    false
+}
+/// Windows: the IDD-push capturer proactively enables advanced colour and delivers P010/Rgb10a2.
+#[cfg(target_os = "windows")]
+pub fn capturer_supports_hdr() -> bool {
+    true
+}
+#[cfg(not(any(target_os = "linux", target_os = "windows")))]
+pub fn capturer_supports_hdr() -> bool {
+    false
+}
+
+/// Process-wide latch: a `want_hdr` portal capture failed to negotiate the HDR (10-bit PQ) offer —
+/// the compositor never accepted it (monitor left HDR mode between the probe and the negotiation,
+/// NVIDIA EGL not listing LINEAR for XR30, a pre-50 Mutter…). Later sessions consult
+/// [`hdr_capture_failed`] and fall back to the SDR offer instead of re-running the same doomed
+/// 10-second negotiation timeout on every reconnect. Sticky until host restart (matching the
+/// zero-copy downgrade latches); the log line at latch time says so.
+#[cfg(target_os = "linux")]
+static HDR_CAPTURE_FAILED: std::sync::atomic::AtomicBool =
+    std::sync::atomic::AtomicBool::new(false);
+
+#[cfg(target_os = "linux")]
+pub fn hdr_capture_failed() -> bool {
+    HDR_CAPTURE_FAILED.load(std::sync::atomic::Ordering::Relaxed)
+}
+
+#[cfg(target_os = "linux")]
+pub(crate) fn note_hdr_capture_failed() {
+    if !HDR_CAPTURE_FAILED.swap(true, std::sync::atomic::Ordering::Relaxed) {
+        tracing::warn!(
+            "HDR capture negotiation failed — this host will offer SDR capture for the rest of \
+             the process lifetime (restart the host after fixing the monitor's HDR mode to retry)"
+        );
+    }
+}
 #[cfg(target_os = "windows")]
 pub fn capturer_supports_444(encoder_ingests_rgb_444: bool) -> bool {
     // IDD-push delivers full-chroma BGRA for an SDR 4:4:4 session (skipping the NV12 VideoConverter),
@@ -316,16 +370,28 @@ pub use idd_push::verify_is_wudfhost;
 #[cfg(target_os = "linux")]
 #[path = "linux/mod.rs"]
 mod linux;
+// The GNOME BT.2100 colour-mode probe — the host's capture-side gate for offering HDR on the
+// portal monitor path (see `open_portal_monitor`'s `want_hdr`).
+#[cfg(target_os = "linux")]
+pub use linux::gnome_hdr_monitor_active;
 #[cfg(target_os = "windows")]
 #[path = "windows/synthetic_nv12.rs"]
 pub mod synthetic_nv12;
 
 /// Open the Linux xdg-ScreenCast portal capturer for a client-sized monitor. `anchored` drives
-/// ScreenCast off a RemoteDesktop session (KWin/GNOME) so it inherits that grant headlessly. The
-/// [`ZeroCopyPolicy`] carries the pre-resolved encode-backend facts (the one-way edge).
+/// ScreenCast off a RemoteDesktop session (KWin/GNOME) so it inherits that grant headlessly.
+/// `want_hdr` offers the GNOME 50+ HDR formats (10-bit PQ/BT.2020 dmabufs) instead of the SDR
+/// set — pass it only when the mirrored monitor is actually in HDR mode (the host probes
+/// DisplayConfig) or the negotiation runs into its 10 s timeout and latches the SDR downgrade.
+/// The [`ZeroCopyPolicy`] carries the pre-resolved encode-backend facts (the one-way edge).
 #[cfg(target_os = "linux")]
-pub fn open_portal_monitor(anchored: bool, policy: ZeroCopyPolicy) -> Result<Box<dyn Capturer>> {
-    linux::PortalCapturer::open(anchored, policy).map(|c| Box::new(c) as Box<dyn Capturer>)
+pub fn open_portal_monitor(
+    anchored: bool,
+    want_hdr: bool,
+    policy: ZeroCopyPolicy,
+) -> Result<Box<dyn Capturer>> {
+    linux::PortalCapturer::open(anchored, want_hdr && !hdr_capture_failed(), policy)
+        .map(|c| Box::new(c) as Box<dyn Capturer>)
 }
 
 /// Open the Linux portal capturer bound to an already-created virtual output's PipeWire node. The
@@ -365,9 +431,18 @@ pub fn open_idd_push(
     preferred: Option<(u32, u32, u32)>,
     client_10bit: bool,
     want_444: bool,
+    pyrowave: bool,
     keepalive: Box<dyn Send>,
     sender: FrameChannelSender,
 ) -> std::result::Result<Box<dyn Capturer>, (anyhow::Error, Box<dyn Send>)> {
-    idd_push::IddPushCapturer::open(target, preferred, client_10bit, want_444, keepalive, sender)
-        .map(|c| Box::new(c) as Box<dyn Capturer>)
+    idd_push::IddPushCapturer::open(
+        target,
+        preferred,
+        client_10bit,
+        want_444,
+        pyrowave,
+        keepalive,
+        sender,
+    )
+    .map(|c| Box::new(c) as Box<dyn Capturer>)
 }

crates/pf-capture/src/linux/mod.rs

@@ -62,6 +62,13 @@ pub struct PortalCapturer {
     /// the process-wide downgrade ([`pf_zerocopy::note_vaapi_dmabuf_failed`]) so the pipeline
     /// rebuild retries on the CPU offer instead of failing identically forever.
     vaapi_dmabuf: bool,
+    /// This capture ran the HDR (10-bit PQ/BT.2020 dmabuf) offer — see [`Self::open`]'s
+    /// `want_hdr`. Read by the negotiation-timeout diagnosis (a failed HDR offer latches the
+    /// process-wide SDR downgrade) and by [`hdr_meta`](Capturer::hdr_meta).
+    hdr_offer: bool,
+    /// Set once the stream negotiated one of the 10-bit PQ formats (`param_changed`), i.e. frames
+    /// really are PQ/BT.2020 — drives [`hdr_meta`](Capturer::hdr_meta).
+    hdr_negotiated: Arc<AtomicBool>,
     /// The PipeWire node this capturer consumes — surfaced in error messages for diagnosis.
     node_id: u32,
     /// Stops the PipeWire loop on teardown (sent in `Drop`). Without it a dropped or failed
@@ -80,8 +87,9 @@ pub struct PortalCapturer {
 impl PortalCapturer {
     /// `anchored` drives ScreenCast off a RemoteDesktop session (KWin/GNOME) so it inherits the
     /// RemoteDesktop grant and never raises a separate ScreenCast dialog; `false` uses a plain
-    /// ScreenCast session (wlroots, which has no RemoteDesktop portal).
-    pub fn open(anchored: bool, policy: ZeroCopyPolicy) -> Result<PortalCapturer> {
+    /// ScreenCast session (wlroots, which has no RemoteDesktop portal). `want_hdr` offers the
+    /// GNOME 50+ HDR formats (10-bit PQ/BT.2020, dmabuf-only) instead of the SDR set.
+    pub fn open(anchored: bool, want_hdr: bool, policy: ZeroCopyPolicy) -> Result<PortalCapturer> {
         // Portal handshake (async) on its own thread; hands back the PW fd + node id.
         let (setup_tx, setup_rx) = std::sync::mpsc::channel::<Result<(OwnedFd, u32), String>>();
         thread::Builder::new()
@@ -102,11 +110,12 @@ impl PortalCapturer {
         };
         tracing::info!(
             node_id,
+            want_hdr,
             "ScreenCast portal session started; connecting PipeWire"
         );
         // This portal path (GameStream / monitor capture) is always 4:2:0, so allow zero-copy as before.
         Ok(
-            spawn_pipewire(Some(fd), node_id, None, true, false, policy)?
+            spawn_pipewire(Some(fd), node_id, None, true, false, want_hdr, policy)?
                 .into_capturer(node_id, None),
         )
     }
@@ -135,12 +144,15 @@ impl PortalCapturer {
             want_444,
             "connecting PipeWire to virtual output"
         );
+        // Virtual outputs are SDR-only upstream (Mutter's RecordVirtual streams advertise 8-bit
+        // BGRx/BGRA exclusively, GNOME 50 and 51-dev alike) — never run the HDR offer here.
         Ok(spawn_pipewire(
             remote_fd,
             node_id,
             preferred_mode,
             allow_zerocopy,
             want_444,
+            false,
             policy,
         )?
         .into_capturer(node_id, Some(keepalive)))
@@ -160,6 +172,10 @@ struct PwHandles {
     /// This capture will offer LINEAR-dmabuf-only for the VAAPI passthrough (see
     /// [`PortalCapturer::vaapi_dmabuf`]).
     vaapi_dmabuf: bool,
+    /// This capture ran the HDR offer (see [`PortalCapturer::hdr_offer`]).
+    hdr_offer: bool,
+    /// See [`PortalCapturer::hdr_negotiated`].
+    hdr_negotiated: Arc<AtomicBool>,
     quit: ::pipewire::channel::Sender<()>,
     join: thread::JoinHandle<()>,
 }
@@ -177,6 +193,8 @@ impl PwHandles {
             broken: self.broken,
             stall_since: None,
             vaapi_dmabuf: self.vaapi_dmabuf,
+            hdr_offer: self.hdr_offer,
+            hdr_negotiated: self.hdr_negotiated,
             node_id,
             quit: Some(self.quit),
             join: Some(self.join),
@@ -199,6 +217,10 @@ fn spawn_pipewire(
     // 4:4:4 session: tiled dmabufs convert to planar YUV444 on the GPU (`ImportKind::Tiled444`)
     // instead of NV12/RGB, so the session stays zero-copy at full chroma.
     want_444: bool,
+    // HDR session (GNOME 50+ monitor mirror): offer ONLY the 10-bit PQ/BT.2020 formats as
+    // LINEAR dmabufs (SHM can't carry them — Mutter's SHM record path paints 8-bit ARGB32
+    // regardless of the negotiated format, and the tiled EGL de-tile blit is 8-bit).
+    want_hdr: bool,
     // Encode-backend facts resolved by the facade (never re-derived here) — the one-way
     // capture→encode edge (plan §W6).
     policy: ZeroCopyPolicy,
@@ -213,17 +235,31 @@ fn spawn_pipewire(
     let streaming_cb = streaming.clone();
     let broken = Arc::new(AtomicBool::new(false));
     let broken_cb = broken.clone();
+    let hdr_negotiated = Arc::new(AtomicBool::new(false));
+    let hdr_negotiated_cb = hdr_negotiated.clone();
     // pipewire's own cross-thread channel: the receiver attaches to the loop and quits it; the
     // sender lives on the capturer and fires in its `Drop`. Absolute `::pipewire` path — the
     // inner `mod pipewire` shadows the crate name at this scope.
     let (quit_tx, quit_rx) = ::pipewire::channel::channel::<()>();
     let zerocopy = allow_zerocopy && pf_zerocopy::enabled();
+    // HDR cannot ride the SHM path (see `want_hdr` above): under PUNKTFUNK_FORCE_SHM the HDR
+    // offer is dropped — SDR capture, loudly.
+    let force_shm = std::env::var("PUNKTFUNK_FORCE_SHM").as_deref() == Ok("1");
+    let want_hdr = if want_hdr && force_shm {
+        tracing::warn!(
+            "HDR capture requested but PUNKTFUNK_FORCE_SHM=1 — the SHM path is 8-bit only; \
+             offering SDR"
+        );
+        false
+    } else {
+        want_hdr
+    };
     // Mirror of the thread's `vaapi_passthrough` decision (deterministic from here: on a VAAPI
-    // backend the EGL→CUDA importer is never built) — kept on the capturer so `next_frame`'s
-    // negotiation-timeout branch knows a failed negotiation was the LINEAR-dmabuf offer.
-    let vaapi_dmabuf = zerocopy
-        && std::env::var("PUNKTFUNK_FORCE_SHM").as_deref() != Ok("1")
-        && policy.backend_is_vaapi;
+    // backend or a PyroWave session the EGL→CUDA importer is never built) — kept on the capturer
+    // so `next_frame`'s negotiation-timeout branch knows a failed negotiation was the raw-dmabuf
+    // passthrough offer.
+    let vaapi_dmabuf =
+        zerocopy && !force_shm && (policy.backend_is_vaapi || policy.pyrowave_session);
     let join = thread::Builder::new()
         .name("punktfunk-pipewire".into())
         .spawn(move || {
@@ -235,8 +271,10 @@ fn spawn_pipewire(
                 negotiated_cb,
                 streaming_cb,
                 broken_cb,
+                hdr_negotiated_cb,
                 zerocopy,
                 want_444,
+                want_hdr,
                 preferred,
                 quit_rx,
                 policy,
@@ -252,6 +290,8 @@ fn spawn_pipewire(
         streaming,
         broken,
         vaapi_dmabuf,
+        hdr_offer: want_hdr,
+        hdr_negotiated,
         quit: quit_tx,
         join,
     })
@@ -354,6 +394,26 @@ impl Capturer for PortalCapturer {
     fn set_active(&self, active: bool) {
         self.active.store(active, Ordering::Relaxed);
     }
+
+    /// Generic HDR10 mastering metadata once the stream negotiated a 10-bit PQ format. Mutter
+    /// exposes no per-monitor mastering volume through the screencast, so this is the standard
+    /// HDR10 default block (BT.2020 primaries, D65 white, 1000 / 0.005 cd/m², CLL unknown) — the
+    /// same fallback Windows uses when a display reports nothing. The native stream loop prefers
+    /// the client display's own volume when the client sent one (`Hello::display_hdr`).
+    fn hdr_meta(&self) -> Option<punktfunk_core::quic::HdrMeta> {
+        if !self.hdr_negotiated.load(Ordering::Relaxed) {
+            return None;
+        }
+        Some(punktfunk_core::quic::HdrMeta {
+            // ST.2086 order G, B, R; (x, y) chromaticity in 1/50000 units.
+            display_primaries: [[8500, 39850], [6550, 2300], [35400, 14600]],
+            white_point: [15635, 16450],                 // D65
+            max_display_mastering_luminance: 10_000_000, // 1000 cd/m² (0.0001 units)
+            min_display_mastering_luminance: 50,         // 0.005 cd/m²
+            max_cll: 0,
+            max_fall: 0,
+        })
+    }
 }
 
 impl PortalCapturer {
@@ -372,6 +432,20 @@ impl PortalCapturer {
                          or capture never started)",
                         self.node_id
                     ))
+                } else if self.hdr_offer {
+                    // The HDR (10-bit PQ dmabuf) offer was never accepted — the monitor left HDR
+                    // mode between the probe and the negotiation, the compositor pre-dates the
+                    // GNOME 50 HDR formats, or its allocator can't do LINEAR for XR30/XB30.
+                    // Latch the process-wide SDR downgrade so the next session (Moonlight
+                    // auto-reconnects) negotiates SDR instead of re-running this same timeout.
+                    super::note_hdr_capture_failed();
+                    Err(anyhow!(
+                        "no PipeWire frame within 10s (node {}): the compositor never accepted \
+                         the HDR (10-bit PQ/BT.2020 dmabuf) offer — is the mirrored monitor in \
+                         HDR mode on GNOME 50+? Downgrading this host to SDR capture; reconnect \
+                         to stream SDR",
+                        self.node_id
+                    ))
                 } else if self.vaapi_dmabuf && !pf_zerocopy::vaapi_dmabuf_forced() {
                     // The LINEAR-dmabuf-only offer (VAAPI passthrough default) was never accepted.
                     // Latch the process-wide downgrade so the encode loop's pipeline rebuild
@@ -416,6 +490,87 @@ impl Drop for PortalCapturer {
     }
 }
 
+/// Whether any monitor of the live GNOME session is currently in BT.2100 (HDR) colour mode — the
+/// precondition for Mutter's monitor screencast advertising the 10-bit PQ formats (GNOME 50+;
+/// Mutter only appends the HDR formats while the mirrored monitor's colour state is BT.2020+PQ).
+/// Queried over the session bus: `DisplayConfig.GetCurrentState`, monitor property
+/// `"color-mode" == 1` (`META_COLOR_MODE_BT2100`). `false` on any error — not GNOME, a pre-48
+/// Mutter without colour modes, no monitors — so callers fall back to the honest SDR offer.
+/// Blocking (one D-Bus round-trip on a fresh connection); call from control-plane threads only.
+pub fn gnome_hdr_monitor_active() -> bool {
+    use ashpd::zbus;
+    // GetCurrentState reply: (serial, monitors, logical_monitors, properties); each monitor is
+    // (spec(ssss), modes a(siiddada{sv}), properties a{sv}) — "color-mode" lives in the monitor
+    // properties.
+    type Mode = (
+        String,
+        i32,
+        i32,
+        f64,
+        f64,
+        Vec<f64>,
+        std::collections::HashMap<String, zbus::zvariant::OwnedValue>,
+    );
+    type Monitor = (
+        (String, String, String, String),
+        Vec<Mode>,
+        std::collections::HashMap<String, zbus::zvariant::OwnedValue>,
+    );
+    type LogicalMonitor = (
+        i32,
+        i32,
+        f64,
+        u32,
+        bool,
+        Vec<(String, String, String, String)>,
+        std::collections::HashMap<String, zbus::zvariant::OwnedValue>,
+    );
+    type State = (
+        u32,
+        Vec<Monitor>,
+        Vec<LogicalMonitor>,
+        std::collections::HashMap<String, zbus::zvariant::OwnedValue>,
+    );
+    let probe = || -> Result<bool> {
+        // zbus is built async-only here (ashpd's tokio integration) — run the one round-trip on
+        // a throwaway current-thread runtime; this is a control-plane call, never per-frame.
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .context("build tokio runtime")?;
+        rt.block_on(async {
+            let conn = zbus::Connection::session().await.context("session bus")?;
+            let reply = conn
+                .call_method(
+                    Some("org.gnome.Mutter.DisplayConfig"),
+                    "/org/gnome/Mutter/DisplayConfig",
+                    Some("org.gnome.Mutter.DisplayConfig"),
+                    "GetCurrentState",
+                    &(),
+                )
+                .await
+                .context("DisplayConfig.GetCurrentState")?;
+            let (_serial, monitors, _logical, _props): State = reply
+                .body()
+                .deserialize()
+                .context("parse GetCurrentState")?;
+            Ok(monitors.iter().any(|(_spec, _modes, props)| {
+                props
+                    .get("color-mode")
+                    .and_then(|v| u32::try_from(v).ok())
+                    .is_some_and(|mode| mode == 1) // META_COLOR_MODE_BT2100
+            }))
+        })
+    };
+    match probe() {
+        Ok(hdr) => hdr,
+        Err(e) => {
+            tracing::debug!(error = %format!("{e:#}"), "GNOME HDR colour-mode probe failed — SDR");
+            false
+        }
+    }
+}
+
 /// Pick the ScreenCast cursor mode from what the backend advertises (`AvailableCursorModes`),
 /// preferring **cursor-as-metadata**: the compositor keeps its cheap hardware cursor plane and
 /// ships the pointer as PipeWire `SPA_META_Cursor` metadata (position + an occasional bitmap),
@@ -669,6 +824,10 @@ mod pipewire {
             VideoFormat::RGBA => PixelFormat::Rgba,
             VideoFormat::RGB => PixelFormat::Rgb,
             VideoFormat::BGR => PixelFormat::Bgr,
+            // The GNOME 50+ HDR screencast formats (packed 2:10:10:10; only ever negotiated by
+            // the `want_hdr` offer, whose MANDATORY colorimetry props pin them to PQ/BT.2020).
+            VideoFormat::xRGB_210LE => PixelFormat::X2Rgb10,
+            VideoFormat::xBGR_210LE => PixelFormat::X2Bgr10,
             _ => return None,
         })
     }
@@ -732,6 +891,9 @@ mod pipewire {
         /// irrecoverably gone for this stream — the import worker died, or tiled imports failed
         /// [`IMPORT_FAIL_POISON`] times in a row.
         broken: Arc<AtomicBool>,
+        /// Set when the negotiated format is one of the 10-bit PQ formats (`param_changed`) —
+        /// read by [`PortalCapturer::hdr_meta`](super::PortalCapturer).
+        hdr_negotiated: Arc<AtomicBool>,
         /// Consecutive tiled-import failures (reset on success); see [`IMPORT_FAIL_POISON`].
         import_fail_streak: u32,
         /// Present when zero-copy is enabled on NVIDIA: imports a dmabuf → CUDA device buffer,
@@ -886,6 +1048,91 @@ mod pipewire {
         serialize_pod(obj)
     }
 
+    /// Build one GNOME 50+ HDR format pod: `format` (xRGB_210LE / xBGR_210LE) as a LINEAR-only
+    /// dmabuf with **MANDATORY** BT.2020 primaries + SMPTE ST.2084 (PQ) transfer-function props —
+    /// the exact colorimetry Mutter's monitor stream advertises while the mirrored monitor is in
+    /// HDR mode (its HDR pods carry the same props MANDATORY, so both sides must speak them for
+    /// the intersection to exist; an SDR or pre-50 producer can never match this pod).
+    ///
+    /// LINEAR-only because every 10-bit consumer we have reads the buffer without a de-tile pass:
+    /// the CPU path mmaps it, and the VAAPI passthrough imports it into a VA surface. The tiled
+    /// EGL de-tile blit renders into an 8-bit `GL_RGBA8` texture — it would silently crush the
+    /// depth — so tiled modifiers are deliberately NOT advertised (a zero-copy 10-bit de-tile is
+    /// the follow-up). SHM is excluded entirely: Mutter's SHM record path paints 8-bit ARGB32
+    /// regardless of the negotiated format.
+    /// `SPA_VIDEO_TRANSFER_SMPTE2084` (PQ) — spelled out rather than taken from `pw::spa::sys`
+    /// because libspa only grew the constant with the BT2020_10/SMPTE2084/ARIB_STD_B67 block, and
+    /// the distro builders (Ubuntu 24.04 noble for the .deb) ship headers predating it — bindgen
+    /// then emits no such constant and the host fails to compile there, even though the code never
+    /// runs on those systems (the HDR path needs GNOME 50+).
+    ///
+    /// 14 is the enum's position in `spa/param/video/color.h` and is wire ABI, not a private
+    /// detail: SPA mirrors GStreamer's `GstVideoTransferFunction`, where that block was added
+    /// together, so the value is identical on every libspa that has the symbol at all. On one that
+    /// doesn't, PipeWire simply fails to intersect this format offer and the session negotiates
+    /// SDR — the same outcome as not offering HDR.
+    const SPA_VIDEO_TRANSFER_SMPTE2084: u32 = 14;
+
+    fn build_hdr_dmabuf_format(
+        format: VideoFormat,
+        preferred: Option<(u32, u32, u32)>,
+    ) -> Result<Vec<u8>> {
+        let (dw, dh, dhz) = preferred.unwrap_or((1920, 1080, 60));
+        use pw::spa::param::format::{FormatProperties, MediaSubtype, MediaType};
+        let mut obj = pw::spa::pod::object!(
+            pw::spa::utils::SpaTypes::ObjectParamFormat,
+            pw::spa::param::ParamType::EnumFormat,
+            pw::spa::pod::property!(FormatProperties::MediaType, Id, MediaType::Video),
+            pw::spa::pod::property!(FormatProperties::MediaSubtype, Id, MediaSubtype::Raw),
+            pw::spa::pod::property!(FormatProperties::VideoFormat, Id, format),
+            pw::spa::pod::property!(
+                FormatProperties::VideoSize,
+                Choice,
+                Range,
+                Rectangle,
+                pw::spa::utils::Rectangle {
+                    width: dw,
+                    height: dh
+                },
+                pw::spa::utils::Rectangle {
+                    width: 1,
+                    height: 1
+                },
+                pw::spa::utils::Rectangle {
+                    width: 8192,
+                    height: 8192
+                }
+            ),
+            pw::spa::pod::property!(
+                FormatProperties::VideoFramerate,
+                Choice,
+                Range,
+                Fraction,
+                pw::spa::utils::Fraction { num: dhz, denom: 1 },
+                pw::spa::utils::Fraction { num: 0, denom: 1 },
+                pw::spa::utils::Fraction { num: 240, denom: 1 }
+            ),
+        );
+        obj.properties.push(pw::spa::pod::Property {
+            key: pw::spa::sys::SPA_FORMAT_VIDEO_modifier,
+            flags: pw::spa::pod::PropertyFlags::MANDATORY,
+            value: pw::spa::pod::Value::Long(0), // DRM_FORMAT_MOD_LINEAR
+        });
+        obj.properties.push(pw::spa::pod::Property {
+            key: pw::spa::sys::SPA_FORMAT_VIDEO_transferFunction,
+            flags: pw::spa::pod::PropertyFlags::MANDATORY,
+            value: pw::spa::pod::Value::Id(pw::spa::utils::Id(SPA_VIDEO_TRANSFER_SMPTE2084)),
+        });
+        obj.properties.push(pw::spa::pod::Property {
+            key: pw::spa::sys::SPA_FORMAT_VIDEO_colorPrimaries,
+            flags: pw::spa::pod::PropertyFlags::MANDATORY,
+            value: pw::spa::pod::Value::Id(pw::spa::utils::Id(
+                pw::spa::sys::SPA_VIDEO_COLOR_PRIMARIES_BT2020,
+            )),
+        });
+        serialize_pod(obj)
+    }
+
     /// The default (shm/CPU-path) format offer: raw video in any encoder-mappable layout, any
     /// size, any framerate (0/1 = variable allowed — gamescope fixates exactly that).
     fn build_default_format_obj(preferred: Option<(u32, u32, u32)>) -> pw::spa::pod::Object {
@@ -1157,6 +1404,54 @@ mod pipewire {
         })
     }
 
+    /// Alpha-blend the cached cursor bitmap into a packed 10-bit (`X2Rgb10`/`X2Bgr10`) CPU frame:
+    /// unpack each u32, blend the 8-bit cursor channels scaled to 10 bits (`v<<2 | v>>6`), repack.
+    /// The frame samples are PQ-encoded, so like the 8-bit gamma-space blend this is a display-
+    /// referred approximation — fine for a cursor. `r_shift` is the R channel's bit offset (20 for
+    /// x:R:G:B, 0 for x:B:G:R); G is always at 10 and B mirrors R.
+    fn composite_cursor_rgb10(
+        tight: &mut [u8],
+        w: usize,
+        h: usize,
+        r_shift: u32,
+        cursor: &CursorState,
+    ) {
+        let b_shift = 20 - r_shift; // 0 or 20 — the opposite end from R
+        let (bw, bh) = (cursor.bw as i32, cursor.bh as i32);
+        for cy in 0..bh {
+            let dy = cursor.y + cy;
+            if dy < 0 || dy as usize >= h {
+                continue;
+            }
+            for cx in 0..bw {
+                let dx = cursor.x + cx;
+                if dx < 0 || dx as usize >= w {
+                    continue;
+                }
+                let s = ((cy * bw + cx) as usize) * 4;
+                let a = cursor.rgba[s + 3] as u32;
+                if a == 0 {
+                    continue;
+                }
+                // 8-bit cursor channel → 10-bit (replicate the top bits into the bottom).
+                let up10 = |v: u8| ((v as u32) << 2) | ((v as u32) >> 6);
+                let (sr, sg, sb) = (
+                    up10(cursor.rgba[s]),
+                    up10(cursor.rgba[s + 1]),
+                    up10(cursor.rgba[s + 2]),
+                );
+                let di = (dy as usize * w + dx as usize) * 4;
+                let px = u32::from_le_bytes(tight[di..di + 4].try_into().unwrap());
+                let blend = |dst: u32, src: u32| (src * a + dst * (255 - a)) / 255;
+                let dr = blend((px >> r_shift) & 0x3ff, sr);
+                let dg = blend((px >> 10) & 0x3ff, sg);
+                let db = blend((px >> b_shift) & 0x3ff, sb);
+                let out = (px & 0xc000_0000) | (dr << r_shift) | (dg << 10) | (db << b_shift);
+                tight[di..di + 4].copy_from_slice(&out.to_le_bytes());
+            }
+        }
+    }
+
     /// Alpha-blend the cached cursor bitmap into the tightly-packed CPU frame at its latched
     /// position. Cheap: a straight-alpha blit over at most ~256×256 pixels, clipped to the frame —
     /// the whole point of cursor-as-metadata (no forced full-frame composite on the producer).
@@ -1170,6 +1465,12 @@ mod pipewire {
         if !cursor.visible || cursor.rgba.is_empty() {
             return;
         }
+        // The packed 10-bit HDR layouts blend via bit unpack/repack, not byte offsets.
+        match fmt {
+            PixelFormat::X2Rgb10 => return composite_cursor_rgb10(tight, w, h, 20, cursor),
+            PixelFormat::X2Bgr10 => return composite_cursor_rgb10(tight, w, h, 0, cursor),
+            _ => {}
+        }
         let Some((ri, gi, bi, bpp)) = dst_offsets(fmt) else {
             return;
         };
@@ -1344,7 +1645,10 @@ mod pipewire {
         // through to the shm de-pad copy below.
         let mut gpu_import_broken = false;
         if let (Some(importer), Some(fmt)) = (ud.importer.as_mut(), ud.format) {
-            if datas[0].type_() == pw::spa::buffer::DataType::DmaBuf {
+            // Defense-in-depth: the 10-bit PQ formats must never enter the EGL→CUDA import (its
+            // de-tile blit is 8-bit RGBA8 — silent depth loss). An HDR offer never builds the
+            // importer, so this gate only matters if those invariants ever drift apart.
+            if datas[0].type_() == pw::spa::buffer::DataType::DmaBuf && !fmt.is_hdr_rgb10() {
                 let plane = pf_zerocopy::DmabufPlane {
                     fd: datas[0].fd(),
                     offset: datas[0].chunk().offset(),
@@ -1604,9 +1908,13 @@ mod pipewire {
         negotiated: Arc<AtomicBool>,
         streaming: Arc<AtomicBool>,
         broken: Arc<AtomicBool>,
+        hdr_negotiated: Arc<AtomicBool>,
         zerocopy: bool,
         // 4:4:4 session: tiled dmabufs take the worker's planar-YUV444 GPU convert.
         want_444: bool,
+        // HDR session: offer ONLY the 10-bit PQ/BT.2020 formats as LINEAR dmabufs (see
+        // `build_hdr_dmabuf_format`); the SDR offers are not built at all.
+        want_hdr: bool,
         preferred: Option<(u32, u32, u32)>,
         quit_rx: pw::channel::Receiver<()>,
         // Encode-backend facts resolved by the facade (never re-derived here) — the one-way
@@ -1639,13 +1947,18 @@ mod pipewire {
         // Build the GPU importer up front — normally the ISOLATED worker process
         // (design/zerocopy-worker-isolation.md), so a driver fault on a dying compositor's
         // dmabuf kills the worker, not this host. If it fails, log and fall back to the CPU path
-        // (we simply won't request dmabuf below). Skipped entirely when the encode backend is
-        // VAAPI: those frames go to the raw-dmabuf passthrough, and building the importer there
-        // would waste a CUDA probe — or worse, on an NVIDIA box forced to PUNKTFUNK_ENCODER=vaapi,
-        // succeed and produce CUDA payloads the VAAPI encoder must reject. Also skipped once
-        // repeated worker deaths latched the import off (a wedged GPU stack must not crash-loop).
+        // (we simply won't request dmabuf below). Skipped entirely when the frames go to the
+        // raw-dmabuf passthrough — the encode backend is VAAPI, or the SESSION encodes PyroWave
+        // (its Vulkan device imports raw dmabufs on any vendor): building the importer there
+        // would waste a CUDA probe — or worse, succeed and produce CUDA payloads only NVENC can
+        // consume. Also skipped once repeated worker deaths latched the import off (a wedged GPU
+        // stack must not crash-loop).
         let backend_is_vaapi = policy.backend_is_vaapi;
-        let mut importer = if zerocopy && !backend_is_vaapi {
+        let raw_passthrough = backend_is_vaapi || policy.pyrowave_session;
+        // HDR never builds the EGL→CUDA importer: its de-tile blit renders into 8-bit RGBA8,
+        // which would silently crush the 10-bit depth. The HDR consumers are the CPU mmap path
+        // (LINEAR de-pad → X2Rgb10 CPU frames) and the VAAPI raw-dmabuf passthrough.
+        let mut importer = if zerocopy && !raw_passthrough && !want_hdr {
             if pf_zerocopy::gpu_import_disabled() {
                 tracing::warn!(
                     "zero-copy GPU import disabled after repeated import-worker deaths — using CPU path"
@@ -1671,9 +1984,11 @@ mod pipewire {
         // host. KWin/gamescope don't need it (they blit into the buffer, so no read-before-render
         // race).
         let force_shm = std::env::var("PUNKTFUNK_FORCE_SHM").as_deref() == Ok("1");
-        // VAAPI zero-copy passthrough: zero-copy on, no EGL→CUDA importer (any non-NVIDIA host), and
-        // the encoder backend is VAAPI → hand the raw dmabuf to the encoder (it imports + GPU-CSCs).
-        let vaapi_passthrough = zerocopy && !force_shm && importer.is_none() && backend_is_vaapi;
+        // Raw-dmabuf zero-copy passthrough: zero-copy on, no EGL→CUDA importer, and the frames'
+        // consumer imports raw dmabufs itself — the VAAPI backend (libva import + GPU CSC) or a
+        // PyroWave session (the wavelet encoder's own Vulkan device, any vendor) → hand the raw
+        // dmabuf straight to the encoder.
+        let vaapi_passthrough = zerocopy && !force_shm && importer.is_none() && raw_passthrough;
         // Modifiers our import stack handles for BGRx: the EGL-importable (tiled) set, plus LINEAR
         // (0) — NVIDIA's EGL won't list it, but LINEAR dmabufs (gamescope's only offer) import via
         // CUDA external memory instead. For the VAAPI passthrough path we advertise LINEAR only:
@@ -1689,8 +2004,9 @@ mod pipewire {
         // advertisement with every modifier its device samples from, so compositors that
         // never allocate LINEAR (Mutter+NVIDIA) still negotiate zero-copy dmabufs. The modifiers
         // were resolved by the facade (`ZeroCopyPolicy::pyrowave_modifiers`) — non-empty only when
-        // the host's `pyrowave` feature is on AND the encoder pref is `pyrowave` — so capture never
-        // calls back into `encode` and needs no feature gate of its own (the emptiness check gates it).
+        // the host's `pyrowave` feature is on AND the session (or the global encoder pref) is
+        // PyroWave — so capture never calls back into `encode` and needs no feature gate of its
+        // own (the emptiness check gates it).
         if vaapi_passthrough && !policy.pyrowave_modifiers.is_empty() {
             for &m in &policy.pyrowave_modifiers {
                 if !modifiers.contains(&m) {
@@ -1710,11 +2026,11 @@ mod pipewire {
             );
         } else if zerocopy && !want_dmabuf {
             tracing::warn!("zero-copy: no importable dmabuf modifiers — using CPU path");
-        } else if vaapi_passthrough {
+        } else if vaapi_passthrough && policy.pyrowave_modifiers.is_empty() {
             tracing::info!(
                 "zero-copy: advertising LINEAR dmabuf for direct VAAPI import (GPU CSC)"
             );
-        } else if want_dmabuf {
+        } else if want_dmabuf && !vaapi_passthrough {
             tracing::info!(
                 count = modifiers.len(),
                 sample = ?&modifiers[..modifiers.len().min(6)],
@@ -1755,6 +2071,7 @@ mod pipewire {
             negotiated,
             streaming,
             broken,
+            hdr_negotiated,
             import_fail_streak: 0,
             importer,
             vaapi_passthrough,
@@ -1822,12 +2139,20 @@ mod pipewire {
                     let sz = ud.info.size();
                     ud.format = map_format(ud.info.format());
                     ud.modifier = ud.info.modifier();
+                    // HDR: the 10-bit PQ formats are only ever offered with MANDATORY BT.2020/PQ
+                    // colorimetry props, so a 10-bit negotiation IS an HDR negotiation — but log
+                    // what the producer actually fixated for diagnosis.
+                    let hdr = ud.format.is_some_and(|f| f.is_hdr_rgb10());
+                    ud.hdr_negotiated.store(hdr, Ordering::Relaxed);
                     tracing::info!(
                         width = sz.width,
                         height = sz.height,
                         spa_format = ?ud.info.format(),
                         mapped = ?ud.format,
                         modifier = ud.modifier,
+                        hdr,
+                        transfer_function = ud.info.transfer_function(),
+                        color_primaries = ud.info.color_primaries(),
                         "pipewire format negotiated"
                     );
                     if ud.format.is_none() {
@@ -2029,20 +2354,36 @@ mod pipewire {
         // (offering shm too makes the compositor pick shm). The modifier list is advertised with
         // DONT_FIXATE so the compositor's allocator chooses one; we re-emit the fixated format in
         // `param_changed` (the two-step DMA-BUF handshake). Otherwise offer the multi-format shm
-        // pod and let MAP_BUFFERS map it.
-        let shm_values = serialize_pod(obj)?;
-        let (dmabuf_values, buffers_values) = if want_dmabuf {
-            (
-                Some(build_dmabuf_format(&modifiers, preferred)?),
-                Some(build_dmabuf_buffers()?),
-            )
+        // pod and let MAP_BUFFERS map it. An HDR session replaces ALL of this with the two 10-bit
+        // PQ pods (LINEAR dmabuf, MANDATORY colorimetry — see `build_hdr_dmabuf_format`): offering
+        // SDR alongside would make the producer pick its earlier-listed SDR format, and the
+        // negotiation-timeout path latches the process-wide SDR downgrade if nothing matches.
+        let format_pods: Vec<Vec<u8>> = if want_hdr {
+            tracing::info!(
+                "HDR capture: offering xRGB_210LE/xBGR_210LE LINEAR dmabufs with MANDATORY \
+                 BT.2020 + SMPTE-2084 (PQ) colorimetry (GNOME 50+ monitor stream)"
+            );
+            vec![
+                build_hdr_dmabuf_format(VideoFormat::xRGB_210LE, preferred)?,
+                build_hdr_dmabuf_format(VideoFormat::xBGR_210LE, preferred)?,
+            ]
+        } else if want_dmabuf {
+            vec![build_dmabuf_format(&modifiers, preferred)?]
+        } else {
+            vec![serialize_pod(obj)?]
+        };
+        let buffers_values = if want_hdr || want_dmabuf {
+            // Dmabuf-only. For HDR this is load-bearing beyond zero-copy: Mutter's SHM record
+            // path paints 8-bit ARGB32 regardless of the negotiated format, so a MemFd buffer
+            // under a 10-bit format would carry mislabeled bytes.
+            Some(build_dmabuf_buffers()?)
         } else if force_shm {
             // True SHM: exclude DmaBuf so Mutter MUST download (glReadPixels orders against render).
-            (None, Some(build_shm_only_buffers()?))
+            Some(build_shm_only_buffers()?)
         } else {
             // CPU path still accepts mappable dmabufs (gamescope offers only those once its
             // modifier-bearing format pod wins the intersection).
-            (None, Some(build_mappable_buffers()?))
+            Some(build_mappable_buffers()?)
         };
 
         // Ask for cursor-as-metadata on every path (harmless if the producer can't supply it): the
@@ -2050,9 +2391,8 @@ mod pipewire {
         // compositor keeps its cheap hardware cursor plane (see `choose_cursor_mode`).
         let cursor_meta = build_cursor_meta_param()?;
         let mut byte_slices: Vec<&[u8]> = Vec::new();
-        match &dmabuf_values {
-            Some(d) => byte_slices.push(d),
-            None => byte_slices.push(&shm_values),
+        for pod in &format_pods {
+            byte_slices.push(pod);
         }
         if let Some(b) = &buffers_values {
             byte_slices.push(b);
@@ -2076,4 +2416,24 @@ mod pipewire {
         mainloop.run();
         Ok(())
     }
+
+    #[cfg(test)]
+    mod tests {
+        /// Pin our hand-written PQ transfer id against the real libspa binding. We can't take the
+        /// constant from `pw::spa::sys` directly (older distro headers don't export it — see
+        /// [`super::SPA_VIDEO_TRANSFER_SMPTE2084`]), so assert the two agree wherever the symbol
+        /// DOES exist. Any libspa that renumbers the enum fails this instead of silently tagging
+        /// the HDR offer with the wrong transfer function.
+        ///
+        /// Only builds where tests are compiled — the .deb/.rpm builders run plain `cargo build`,
+        /// so this never reintroduces the compile failure it exists to prevent.
+        #[test]
+        fn pq_transfer_id_matches_libspa() {
+            assert_eq!(
+                super::SPA_VIDEO_TRANSFER_SMPTE2084,
+                super::pw::spa::sys::SPA_VIDEO_TRANSFER_SMPTE2084,
+                "libspa renumbered spa_video_transfer_function — update the hardcoded PQ id"
+            );
+        }
+    }
 }

crates/pf-capture/src/windows/dxgi.rs

@@ -12,7 +12,7 @@
 // Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
 #![deny(clippy::undocumented_unsafe_blocks)]
 
-pub use pf_frame::dxgi::{make_device, pack_luid, D3d11Frame, WinCaptureTarget};
+pub use pf_frame::dxgi::{make_device, pack_luid, D3d11Frame, PyroFrameShare, WinCaptureTarget};
 
 use anyhow::{bail, Context, Result};
 use std::ffi::c_void;
@@ -466,6 +466,229 @@ impl HdrP010Converter {
     }
 }
 
+/// PyroWave LUMA pass PS — full-res, writes Y′ to a separate `R8_UNORM` texture. BT.709 limited from
+/// the 8-bit sRGB (gamma) BGRA slot, BYTE-IDENTICAL to the Linux `rgb2yuv.comp` `lumaY` (so the
+/// wavelet client — whose golden fixtures come from that shader — decodes the same colours). `Load`
+/// (texelFetch) reads the exact source texel: RTV pixel (x,y) → source texel (x,y).
+const PYRO_Y_PS: &str = r"
+Texture2D<float4> tx : register(t0);
+float main(float4 pos : SV_POSITION) : SV_TARGET {
+    float3 c = tx.Load(int3(int2(pos.xy), 0)).rgb;
+    return 16.0/255.0 + 0.1826*c.r + 0.6142*c.g + 0.0620*c.b;
+}
+";
+
+/// PyroWave CHROMA pass PS — half-res, writes interleaved (Cb,Cr) to a separate `R8G8_UNORM` texture.
+/// **2×2 box average** (centre-sited) of the four luma-block RGB texels, then BT.709 limited Cb/Cr —
+/// BYTE-IDENTICAL to `rgb2yuv.comp` (which averages `(c00+c10+c01+c11)*0.25` then U/V), so the chroma
+/// siting matches the client's decoder. Even dimensions guarantee the 2×2 block is in-bounds.
+const PYRO_UV_PS: &str = r"
+Texture2D<float4> tx : register(t0);
+float2 main(float4 pos : SV_POSITION) : SV_TARGET {
+    int2 p = int2(pos.xy) * 2;
+    float3 c00 = tx.Load(int3(p,             0)).rgb;
+    float3 c10 = tx.Load(int3(p + int2(1,0), 0)).rgb;
+    float3 c01 = tx.Load(int3(p + int2(0,1), 0)).rgb;
+    float3 c11 = tx.Load(int3(p + int2(1,1), 0)).rgb;
+    float3 a = (c00 + c10 + c01 + c11) * 0.25;
+    float u = 128.0/255.0 - 0.1006*a.r - 0.3386*a.g + 0.4392*a.b;
+    float v = 128.0/255.0 + 0.4392*a.r - 0.3989*a.g - 0.0403*a.b;
+    return float2(u, v);
+}
+";
+
+/// PyroWave 4:4:4 CHROMA pass PS — FULL-res, per-pixel (no box filter, no siting), the Windows twin
+/// of the Linux `rgb2yuv444.comp` chroma math.
+const PYRO_UV444_PS: &str = r"
+Texture2D<float4> tx : register(t0);
+float2 main(float4 pos : SV_POSITION) : SV_TARGET {
+    float3 c = tx.Load(int3(int2(pos.xy), 0)).rgb;
+    float u = 128.0/255.0 - 0.1006*c.r - 0.3386*c.g + 0.4392*c.b;
+    float v = 128.0/255.0 + 0.4392*c.r - 0.3989*c.g - 0.0403*c.b;
+    return float2(u, v);
+}
+";
+
+/// Shared HLSL for the PyroWave **HDR** passes: scRGB FP16 → PQ-encoded BT.2020 → 10-bit studio
+/// codes MSB-packed into 16-bit UNORM — the SAME colour math as [`HDR_P010_COMMON`] (verified by
+/// `hdr_p010_selftest`), restated over `Load`ed texels so the pyrowave passes stay texel-exact like
+/// their SDR twins. The wavelet client decodes these planes with the same CSC rows as the P010 path.
+const PYRO_HDR_COMMON: &str = r"
+Texture2D<float4> tx : register(t0);
+static const float3x3 BT709_TO_BT2020 = {
+    0.627403914, 0.329283038, 0.043313048,
+    0.069097292, 0.919540405, 0.011362303,
+    0.016391439, 0.088013308, 0.895595253
+};
+float3 pq_oetf(float3 L) {
+    const float m1 = 0.1593017578125;
+    const float m2 = 78.84375;
+    const float c1 = 0.8359375;
+    const float c2 = 18.8515625;
+    const float c3 = 18.6875;
+    float3 Lp = pow(saturate(L), m1);
+    return pow((c1 + c2 * Lp) / (1.0 + c3 * Lp), m2);
+}
+float3 scrgb_to_pq2020_rgb(float3 scrgb) {
+    float3 nits = max(scrgb, 0.0) * 80.0;
+    return pq_oetf(mul(BT709_TO_BT2020, nits) / 10000.0);
+}
+static const float KR = 0.2627;
+static const float KG = 0.6780;
+static const float KB = 0.0593;
+float y_unorm(float3 pq) {
+    float y = KR * pq.r + KG * pq.g + KB * pq.b;
+    float code = clamp(64.0 + 876.0 * y, 64.0, 940.0);
+    return (code * 64.0) / 65535.0;
+}
+float2 cbcr_unorm(float3 pq) {
+    float y = KR * pq.r + KG * pq.g + KB * pq.b;
+    float cbc = clamp(512.0 + 896.0 * (pq.b - y) / 1.8814, 64.0, 960.0);
+    float crc = clamp(512.0 + 896.0 * (pq.r - y) / 1.4746, 64.0, 960.0);
+    return float2((cbc * 64.0) / 65535.0, (crc * 64.0) / 65535.0);
+}
+";
+
+/// PyroWave HDR LUMA pass PS — full-res, writes PQ Y′ studio codes to an `R16_UNORM` texture.
+const PYRO_HDR_Y_PS: &str = r"
+#include_common
+float main(float4 pos : SV_POSITION) : SV_TARGET {
+    float3 pq = scrgb_to_pq2020_rgb(tx.Load(int3(int2(pos.xy), 0)).rgb);
+    return y_unorm(pq);
+}
+";
+
+/// PyroWave HDR 4:2:0 CHROMA pass PS — half-res, centre-sited 2×2 box in scRGB-LINEAR space (the
+/// pyrowave family's siting, matching the SDR pass + `rgb2yuv.comp`, NOT the P010 path's
+/// left-cositing), then PQ + studio Cb/Cr into an `R16G16_UNORM` texture.
+const PYRO_HDR_UV_PS: &str = r"
+#include_common
+float2 main(float4 pos : SV_POSITION) : SV_TARGET {
+    int2 p = int2(pos.xy) * 2;
+    float3 a = max(tx.Load(int3(p,             0)).rgb, 0.0);
+    float3 b = max(tx.Load(int3(p + int2(1,0), 0)).rgb, 0.0);
+    float3 c = max(tx.Load(int3(p + int2(0,1), 0)).rgb, 0.0);
+    float3 d = max(tx.Load(int3(p + int2(1,1), 0)).rgb, 0.0);
+    float3 pq = scrgb_to_pq2020_rgb((a + b + c + d) * 0.25);
+    return cbcr_unorm(pq);
+}
+";
+
+/// PyroWave HDR 4:4:4 CHROMA pass PS — full-res, per-pixel.
+const PYRO_HDR_UV444_PS: &str = r"
+#include_common
+float2 main(float4 pos : SV_POSITION) : SV_TARGET {
+    float3 pq = scrgb_to_pq2020_rgb(tx.Load(int3(int2(pos.xy), 0)).rgb);
+    return cbcr_unorm(pq);
+}
+";
+
+/// scRGB/BGRA → **separate** YUV planes for the PyroWave wavelet encoder: a full-res Y texture + a
+/// (half- or full-res) interleaved CbCr texture (design/pyrowave-windows-host-zerocopy.md +
+/// design/pyrowave-444-hdr.md). SDR mode reads the BGRA slot and writes BT.709-limited 8-bit planes
+/// (`R8_UNORM`/`R8G8_UNORM`), byte-identical to the Linux `rgb2yuv(444).comp`; HDR mode reads the
+/// scRGB FP16 slot and writes P010-style 10-bit studio codes MSB-packed into 16-bit planes
+/// (`R16_UNORM`/`R16G16_UNORM`), colour math identical to [`HdrP010Converter`]. The wavelet encoder
+/// imports the two SEPARATE textures into its own Vulkan device — the NVIDIA D3D11→Vulkan import of
+/// a single *planar* NV12 texture is unreliable at arbitrary sizes, whereas simple single/
+/// two-component textures import reliably. The caller owns the two textures + their RTVs (shareable,
+/// per out-ring slot); this only records the passes.
+pub(crate) struct BgraToYuvPlanes {
+    vs: ID3D11VertexShader,
+    ps_y: ID3D11PixelShader,
+    ps_uv: ID3D11PixelShader,
+    /// Full-res chroma pass (4:4:4) — the chroma viewport skips the /2.
+    chroma444: bool,
+}
+
+impl BgraToYuvPlanes {
+    pub(crate) unsafe fn new(device: &ID3D11Device, hdr: bool, chroma444: bool) -> Result<Self> {
+        let (y_src, uv_src) = match (hdr, chroma444) {
+            (false, false) => (PYRO_Y_PS.to_string(), PYRO_UV_PS.to_string()),
+            (false, true) => (PYRO_Y_PS.to_string(), PYRO_UV444_PS.to_string()),
+            (true, false) => (
+                PYRO_HDR_Y_PS.replace("#include_common", PYRO_HDR_COMMON),
+                PYRO_HDR_UV_PS.replace("#include_common", PYRO_HDR_COMMON),
+            ),
+            (true, true) => (
+                PYRO_HDR_Y_PS.replace("#include_common", PYRO_HDR_COMMON),
+                PYRO_HDR_UV444_PS.replace("#include_common", PYRO_HDR_COMMON),
+            ),
+        };
+        let vsb = compile_shader(HDR_VS, s!("main"), s!("vs_5_0"))?;
+        let yb = compile_shader(&y_src, s!("main"), s!("ps_5_0"))?;
+        let uvb = compile_shader(&uv_src, s!("main"), s!("ps_5_0"))?;
+        let mut vs = None;
+        device.CreateVertexShader(&vsb, None, Some(&mut vs))?;
+        let mut ps_y = None;
+        device.CreatePixelShader(&yb, None, Some(&mut ps_y))?;
+        let mut ps_uv = None;
+        device.CreatePixelShader(&uvb, None, Some(&mut ps_uv))?;
+        Ok(Self {
+            vs: vs.context("pyro vs")?,
+            ps_y: ps_y.context("pyro y ps")?,
+            ps_uv: ps_uv.context("pyro uv ps")?,
+            chroma444,
+        })
+    }
+
+    /// Convert `src_srv` (BGRA slot for SDR / scRGB FP16 slot for HDR, WxH) → `y_rtv` (full-res Y
+    /// texture) + `cbcr_rtv` (half- or full-res CbCr texture per the constructed mode). Two opaque
+    /// passes; `w`/`h` are the full luma dims (even for 4:2:0).
+    #[allow(clippy::too_many_arguments)]
+    pub(crate) unsafe fn convert(
+        &self,
+        ctx: &ID3D11DeviceContext,
+        src_srv: &ID3D11ShaderResourceView,
+        y_rtv: &ID3D11RenderTargetView,
+        cbcr_rtv: &ID3D11RenderTargetView,
+        w: u32,
+        h: u32,
+    ) -> Result<()> {
+        ctx.OMSetBlendState(None, None, 0xffff_ffff); // opaque overwrite
+        ctx.VSSetShader(&self.vs, None);
+        ctx.PSSetShaderResources(0, Some(&[Some(src_srv.clone())]));
+        ctx.IASetInputLayout(None);
+        ctx.IASetPrimitiveTopology(D3D_PRIMITIVE_TOPOLOGY_TRIANGLELIST);
+
+        // LUMA pass: full-res → the R8 Y texture.
+        ctx.RSSetViewports(Some(&[D3D11_VIEWPORT {
+            TopLeftX: 0.0,
+            TopLeftY: 0.0,
+            Width: w as f32,
+            Height: h as f32,
+            MinDepth: 0.0,
+            MaxDepth: 1.0,
+        }]));
+        ctx.OMSetRenderTargets(Some(&[Some(y_rtv.clone())]), None);
+        ctx.PSSetShader(&self.ps_y, None);
+        ctx.Draw(3, 0);
+        ctx.OMSetRenderTargets(Some(&[None]), None);
+
+        // CHROMA pass: half-res (4:2:0) or full-res (4:4:4) → the CbCr texture.
+        let (cw, ch) = if self.chroma444 {
+            (w, h)
+        } else {
+            (w / 2, h / 2)
+        };
+        ctx.RSSetViewports(Some(&[D3D11_VIEWPORT {
+            TopLeftX: 0.0,
+            TopLeftY: 0.0,
+            Width: cw as f32,
+            Height: ch as f32,
+            MinDepth: 0.0,
+            MaxDepth: 1.0,
+        }]));
+        ctx.OMSetRenderTargets(Some(&[Some(cbcr_rtv.clone())]), None);
+        ctx.PSSetShader(&self.ps_uv, None);
+        ctx.Draw(3, 0);
+
+        ctx.OMSetRenderTargets(Some(&[None]), None);
+        ctx.PSSetShaderResources(0, Some(&[None]));
+        Ok(())
+    }
+}
+
 /// f64 reference for the P010 colour math — the EXACT analogue of the HLSL in [`HDR_P010_COMMON`].
 /// Input is one scRGB pixel (linear, Rec.709 primaries, 1.0 = 80 nits, may be >1 for HDR). Output is
 /// the 10-bit studio-range (Y, Cb, Cr) codes the shader should produce for a flat (constant) block.
@@ -829,8 +1052,7 @@ use windows::Win32::Graphics::Direct3D11::{
 };
 use windows::Win32::Graphics::Dxgi::Common::{
     DXGI_COLOR_SPACE_RGB_FULL_G10_NONE_P709, DXGI_COLOR_SPACE_RGB_FULL_G22_NONE_P709,
-    DXGI_COLOR_SPACE_YCBCR_STUDIO_G2084_LEFT_P2020, DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P709,
-    DXGI_RATIONAL,
+    DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P709, DXGI_RATIONAL,
 };
 
 /// D3D11 **Video Processor** colour/format converter — runs on the GPU's dedicated VIDEO engine, NOT
@@ -846,12 +1068,17 @@ pub(crate) struct VideoConverter {
 }
 
 impl VideoConverter {
+    /// A BGRA/FP16-RGB → **NV12 (BT.709 limited SDR)** video-engine converter. `scrgb_input` picks
+    /// the input colour space: `false` = 8-bit sRGB `BGRA` (the SDR ring); `true` = FP16 scRGB
+    /// linear (the HDR ring, used by a PyroWave session that tone-maps the HDR desktop down to the
+    /// 8-bit wavelet stream). The output is always studio-range BT.709 NV12 — the P010/BT.2020 HDR
+    /// path is [`HdrP010Converter`]'s job, never this one.
     pub(crate) unsafe fn new(
         device: &ID3D11Device,
         context: &ID3D11DeviceContext,
         width: u32,
         height: u32,
-        hdr: bool,
+        scrgb_input: bool,
     ) -> Result<Self> {
         let vdev: ID3D11VideoDevice = device.cast().context("device -> ID3D11VideoDevice")?;
         let vctx: ID3D11VideoContext1 = context.cast().context("context -> ID3D11VideoContext1")?;
@@ -876,19 +1103,15 @@ impl VideoConverter {
             .CreateVideoProcessor(&enumr, 0)
             .context("CreateVideoProcessor")?;
 
-        // Full-range RGB in → studio-range YUV out. HDR: scRGB linear (G10) → BT.2020 PQ (G2084).
-        // SDR: sRGB (G22) → BT.709 (G22).
-        let (in_cs, out_cs) = if hdr {
-            (
-                DXGI_COLOR_SPACE_RGB_FULL_G10_NONE_P709,
-                DXGI_COLOR_SPACE_YCBCR_STUDIO_G2084_LEFT_P2020,
-            )
+        // Full-range RGB in → studio-range BT.709 NV12 out. Input gamma follows the ring format:
+        // scRGB linear (G10) for the FP16 HDR ring, sRGB (G22) for the 8-bit BGRA SDR ring. The
+        // output is always BT.709 SDR (the video processor tone-maps the scRGB case).
+        let in_cs = if scrgb_input {
+            DXGI_COLOR_SPACE_RGB_FULL_G10_NONE_P709
         } else {
-            (
-                DXGI_COLOR_SPACE_RGB_FULL_G22_NONE_P709,
-                DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P709,
-            )
+            DXGI_COLOR_SPACE_RGB_FULL_G22_NONE_P709
         };
+        let out_cs = DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P709;
         vctx.VideoProcessorSetStreamColorSpace1(&vp, 0, in_cs);
         vctx.VideoProcessorSetOutputColorSpace1(&vp, out_cs);
         // One frame in, one frame out — no interpolation/auto-processing.

crates/pf-capture/src/windows/idd_push.rs

@@ -19,7 +19,10 @@
 // Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
 #![deny(clippy::undocumented_unsafe_blocks)]
 
-use super::dxgi::{make_device, D3d11Frame, HdrP010Converter, VideoConverter, WinCaptureTarget};
+use super::dxgi::{
+    make_device, BgraToYuvPlanes, D3d11Frame, HdrP010Converter, PyroFrameShare, VideoConverter,
+    WinCaptureTarget,
+};
 use super::{CapturedFrame, Capturer, FramePayload, PixelFormat};
 use anyhow::{bail, Context, Result};
 use pf_driver_proto::{control, frame};
@@ -33,13 +36,16 @@ use windows::Win32::Foundation::{
     HANDLE, INVALID_HANDLE_VALUE, LUID, POINT, WAIT_OBJECT_0,
 };
 use windows::Win32::Graphics::Direct3D11::{
-    ID3D11Device, ID3D11DeviceContext, ID3D11ShaderResourceView, ID3D11Texture2D,
-    D3D11_BIND_RENDER_TARGET, D3D11_BIND_SHADER_RESOURCE, D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX,
-    D3D11_RESOURCE_MISC_SHARED_NTHANDLE, D3D11_TEXTURE2D_DESC, D3D11_USAGE_DEFAULT,
+    ID3D11Device, ID3D11Device5, ID3D11DeviceContext, ID3D11DeviceContext4, ID3D11Fence,
+    ID3D11RenderTargetView, ID3D11ShaderResourceView, ID3D11Texture2D, D3D11_BIND_RENDER_TARGET,
+    D3D11_BIND_SHADER_RESOURCE, D3D11_FENCE_FLAG_SHARED, D3D11_RESOURCE_MISC_SHARED,
+    D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX, D3D11_RESOURCE_MISC_SHARED_NTHANDLE,
+    D3D11_TEXTURE2D_DESC, D3D11_USAGE_DEFAULT,
 };
 use windows::Win32::Graphics::Dxgi::Common::{
     DXGI_FORMAT, DXGI_FORMAT_B8G8R8A8_UNORM, DXGI_FORMAT_NV12, DXGI_FORMAT_P010,
-    DXGI_FORMAT_R16G16B16A16_FLOAT, DXGI_SAMPLE_DESC,
+    DXGI_FORMAT_R16G16B16A16_FLOAT, DXGI_FORMAT_R16G16_UNORM, DXGI_FORMAT_R16_UNORM,
+    DXGI_FORMAT_R8G8_UNORM, DXGI_FORMAT_R8_UNORM, DXGI_SAMPLE_DESC,
 };
 use windows::Win32::Graphics::Dxgi::{
     CreateDXGIFactory1, IDXGIAdapter1, IDXGIFactory4, IDXGIKeyedMutex, IDXGIResource1,
@@ -142,6 +148,18 @@ struct HostSlot {
     srv: ID3D11ShaderResourceView,
 }
 
+/// One PyroWave output-ring slot: the two SEPARATE shareable plane textures the wavelet encoder
+/// imports (design/pyrowave-windows-host-zerocopy.md) plus their RTVs (the [`BgraToYuvPlanes`] CSC
+/// renders into them). Y is full-res `R8_UNORM`, CbCr is half-res `R8G8_UNORM`; both are
+/// `SHARED | SHARED_NTHANDLE`. Rotated per frame like `out_ring` so encode N and convert N+1 touch
+/// different textures.
+struct PyroOutSlot {
+    y: ID3D11Texture2D,
+    y_rtv: ID3D11RenderTargetView,
+    cbcr: ID3D11Texture2D,
+    cbcr_rtv: ID3D11RenderTargetView,
+}
+
 /// RAII guard over an [`IDXGIKeyedMutex`]: [`acquire`](Self::acquire) does `AcquireSync(key, timeout)`,
 /// `Drop` does `ReleaseSync(key)`. So the lock is released even if the work between acquire and the end
 /// of the guard's scope `?`-returns or panics — the "leak the keyed-mutex lock → stall the driver on
@@ -375,10 +393,12 @@ pub struct IddPushCapturer {
     /// display's HDR mode flipped). Stamped into the header + each delivery so the driver re-attaches
     /// (and so stale-ring publishes are rejected).
     generation: u32,
-    /// The CLIENT's advertised 10-bit capability (= negotiated `bit_depth >= 10`). Only used at `open`
-    /// to PROACTIVELY enable advanced color (so a 10-bit client gets HDR without a manual toggle); it
-    /// does NOT gate the per-frame conversion — that follows the display, like the WGC path (clients
-    /// under-report 10-bit yet all decode Main10 + auto-detect PQ from the VUI).
+    /// The CLIENT's advertised 10-bit capability (= negotiated `bit_depth >= 10`). Gates the
+    /// composition depth: a 10-bit client PROACTIVELY enables advanced color at `open` (HDR without a
+    /// manual toggle); an SDR-only client forces it OFF and the descriptor poller PINS it there, so a
+    /// client that advertised SDR ("HDR off") is never handed the in-band PQ upgrade the pixel-format-
+    /// driven encoder would otherwise stamp from an HDR composition. (An HDR-negotiated H.26x session
+    /// still follows a host-side "Use HDR" flip; all clients decode Main10 + auto-detect PQ from the VUI.)
     client_10bit: bool,
     /// The DISPLAY's CURRENT HDR state (from `advanced_color_enabled`) — the user can flip "Use HDR" in
     /// Windows mid-session. Drives the ring format (HDR → FP16 surfaces, SDR → BGRA) and the conversion.
@@ -391,6 +411,32 @@ pub struct IddPushCapturer {
     /// While the display is HDR this is overridden to the P010 path (no 10-bit 4:4:4 source):
     /// the stream honestly downgrades to 4:2:0 — the encoder's caps cross-check reports it.
     want_444: bool,
+    /// A PyroWave (wavelet) session (design/pyrowave-windows-host-zerocopy.md +
+    /// design/pyrowave-444-hdr.md). When set, frames come from the separate-plane `pyro_ring`
+    /// (shareable Y + CbCr textures the mode-aware [`BgraToYuvPlanes`] CSC writes) and a **shared
+    /// fence** is signalled after each convert, so the pyrowave encoder zero-copy-imports the two
+    /// textures into its own Vulkan device ordered after the D3D11 convert. The composition is
+    /// PINNED to the negotiated depth: SDR sessions force advanced color OFF (8-bit BGRA → R8
+    /// planes), 10-bit sessions enable it like H.26x (scRGB FP16 → R16 studio-code planes);
+    /// `want_444` sizes the chroma plane full-res.
+    pyrowave: bool,
+    /// PyroWave: the shared D3D11 timeline fence (created lazily on the first frame, `SHARED` flag).
+    /// The capturer `Signal`s it after each frame's GPU convert; the encoder's Vulkan side waits it.
+    pyro_fence: Option<ID3D11Fence>,
+    /// PyroWave: the fence's persistent shared NT handle (raw), passed on EVERY frame. The encoder
+    /// DUPLICATEs + imports it as a Vulkan timeline semaphore whenever it has none (first frame or
+    /// after an encoder rebuild), so this original stays valid across rebuilds.
+    pyro_fence_handle: Option<isize>,
+    /// PyroWave: the monotonically increasing fence value (one `Signal` per emitted frame).
+    pyro_fence_value: u64,
+    /// PyroWave: the separate-plane output ring (Y R8 + CbCr R8G8 shareable textures + RTVs), used
+    /// INSTEAD of `out_ring` for a pyrowave session. Built lazily; rebuilt on a mode change.
+    pyro_ring: Vec<PyroOutSlot>,
+    /// PyroWave: the BGRA→YUV-planes CSC (BT.709 limited, matching `rgb2yuv.comp`). Built lazily.
+    pyro_conv: Option<BgraToYuvPlanes>,
+    /// PyroWave: the last presented (Y, CbCr) textures — the repeat source (analogue of
+    /// `last_present` for the two-plane path).
+    pyro_last: Option<(ID3D11Texture2D, ID3D11Texture2D)>,
     /// Off-thread display-descriptor sampler (see [`DescriptorPoller`]) — the capture loop reads
     /// its snapshot instead of running CCD queries inline on the frame path.
     desc_poller: DescriptorPoller,
@@ -556,18 +602,20 @@ impl IddPushCapturer {
     /// virtual display); on FAILURE the keepalive is handed BACK so the caller can fall back to DDA
     /// instead of tearing the display down (audit §5.1 — no more 20 s black bail). "Failure" includes the
     /// driver not attaching to the ring within a few seconds (e.g. a hybrid-GPU render mismatch).
+    #[allow(clippy::too_many_arguments)]
     pub fn open(
         target: WinCaptureTarget,
         preferred: Option<(u32, u32, u32)>,
         client_10bit: bool,
         want_444: bool,
+        pyrowave: bool,
         keepalive: Box<dyn Send>,
         sender: crate::FrameChannelSender,
     ) -> std::result::Result<Self, (anyhow::Error, Box<dyn Send>)> {
         // The stall-attribution listener (idempotent): started with the first IDD-push capturer so
         // the stall log can correlate DWM holes with OS display events for the session's lifetime.
         pf_win_display::display_events::spawn_once();
-        match Self::open_inner(target, preferred, client_10bit, want_444, sender) {
+        match Self::open_inner(target, preferred, client_10bit, want_444, pyrowave, sender) {
             Ok(mut me) => {
                 me._keepalive = keepalive;
                 Ok(me)
@@ -576,11 +624,13 @@ impl IddPushCapturer {
         }
     }
 
+    #[allow(clippy::too_many_arguments)]
     fn open_inner(
         target: WinCaptureTarget,
         preferred: Option<(u32, u32, u32)>,
         client_10bit: bool,
         want_444: bool,
+        pyrowave: bool,
         sender: crate::FrameChannelSender,
     ) -> Result<Self> {
         // The ring MUST live on the adapter the driver's swap-chain renders on. Primary: the
@@ -601,6 +651,7 @@ impl IddPushCapturer {
             preferred,
             client_10bit,
             want_444,
+            pyrowave,
             luid,
             sender.clone(),
         ) {
@@ -628,17 +679,27 @@ impl IddPushCapturer {
                     "IDD push: ring/driver render-adapter mismatch — rebinding the ring to the \
                      driver's reported adapter"
                 );
-                Self::open_on(target, preferred, client_10bit, want_444, drv, sender)
-                    .context("IDD-push rebind to the driver's reported render adapter")
+                Self::open_on(
+                    target,
+                    preferred,
+                    client_10bit,
+                    want_444,
+                    pyrowave,
+                    drv,
+                    sender,
+                )
+                .context("IDD-push rebind to the driver's reported render adapter")
             }
         }
     }
 
+    #[allow(clippy::too_many_arguments)]
     fn open_on(
         target: WinCaptureTarget,
         preferred: Option<(u32, u32, u32)>,
         client_10bit: bool,
         want_444: bool,
+        pyrowave: bool,
         luid: LUID,
         sender: crate::FrameChannelSender,
     ) -> Result<Self> {
@@ -663,12 +724,12 @@ impl IddPushCapturer {
         }
         // The driver composes the virtual display in FP16 (R16G16B16A16_FLOAT scRGB) when the display is
         // in advanced-color (HDR) mode, and 8-bit BGRA otherwise (per swap_chain_processor.rs + the
-        // COMMIT_MODES2 colorspace/rgb_bpc log). The user can flip "Use HDR" in Windows at any time, so
-        // the ring format must TRACK the display's ACTUAL mode (the driver's format-guard drops a
-        // mismatch). We poll the live state here and on every recreate. For a 10-bit-capable client we
-        // PROACTIVELY enable advanced color so HDR streams without the user toggling anything; an
-        // SDR-only client leaves the display alone (and still gets a tone-mapped picture, never a freeze,
-        // if the user does enable HDR).
+        // COMMIT_MODES2 colorspace/rgb_bpc log). For a 10-bit-capable client we PROACTIVELY enable
+        // advanced color so HDR streams without the user toggling anything, then TRACK the display's
+        // actual mode (a mid-session "Use HDR" flip; the driver's format-guard drops a mismatch), polling
+        // the live state here and on every recreate. An SDR-only client instead forces advanced color OFF
+        // and is PINNED there (below + the descriptor poller), so the SDR negotiation is honored and the
+        // encoder never emits the in-band PQ upgrade to a client that asked for SDR.
         // SAFETY: one block over the whole ring setup; every operation in it is sound:
         // - `set_advanced_color`/`advanced_color_enabled` are `unsafe fn`s taking only a copy of the plain
         //   `u32` target id; they read/flip CCD display config and return owned values, borrowing nothing.
@@ -691,6 +752,49 @@ impl IddPushCapturer {
         // - `header` points into the OS mapping, NOT into the `MappedSection` struct, so moving `section`
         //   into `me` leaves it valid (see the `MappedSection` doc comment).
         unsafe {
+            // An SDR-NEGOTIATED session (either codec) must run on an SDR (BGRA) composition, so
+            // actively turn advanced color OFF — undoing any leftover HDR state from a prior 10-bit
+            // session on a reused/lingering monitor, the driver's default, or the host's global
+            // "Use HDR" — and settle before sizing the ring. Non-optional for two reasons:
+            //   - PyroWave: its CSC reads 8-bit BGRA and the NVIDIA D3D11 VideoProcessor can't ingest
+            //     the FP16 ring at all.
+            //   - H.26x: off an HDR composition the capturer emits P010 and the encoder stamps
+            //     Main10 + BT.2020 PQ from the pixel format alone (the in-band HDR upgrade), sending a
+            //     10-bit PQ stream to a client that advertised SDR-only ("HDR off = never send me
+            //     10-bit"). On a client whose monitor is HDR-capable but has "Use HDR" off, that PQ
+            //     lands on an SDR desktop and blows out — the composition must honor the negotiation.
+            // An HDR-negotiated (10-bit) session instead enables HDR below and rides the FP16 scRGB
+            // ring (design/pyrowave-444-hdr.md Phase 3 for PyroWave; the H.26x P010 path otherwise).
+            if !client_10bit {
+                let _ = pf_win_display::win_display::set_advanced_color(target.target_id, false);
+                let settle = Instant::now();
+                while settle.elapsed() < Duration::from_millis(250) {
+                    if pf_win_display::win_display::advanced_color_enabled(target.target_id)
+                        == Some(false)
+                    {
+                        break;
+                    }
+                    std::thread::sleep(Duration::from_millis(25));
+                }
+                if pf_win_display::win_display::advanced_color_enabled(target.target_id)
+                    == Some(true)
+                {
+                    tracing::error!(
+                        target = target.target_id,
+                        pyrowave,
+                        "IDD push: SDR session but advanced color (HDR) could NOT be turned off on the \
+                         virtual display (a physical display forcing HDR?) — PyroWave will likely fail \
+                         its first frame; H.26x would emit PQ the SDR-only client never asked for"
+                    );
+                } else {
+                    tracing::info!(
+                        target = target.target_id,
+                        pyrowave,
+                        settle_ms = settle.elapsed().as_millis() as u64,
+                        "IDD push: SDR-negotiated session — advanced color forced OFF (SDR/BGRA composition)"
+                    );
+                }
+            }
             // If we ENABLE advanced color for a 10-bit client, trust it (the driver will compose FP16) and
             // size the ring FP16 directly — don't race the advanced_color_enabled poll, which may not have
             // settled within 250 ms and would size the ring SDR while the driver composes FP16 → a format
@@ -721,9 +825,14 @@ impl IddPushCapturer {
             }
             // A failed open-time read defaults to SDR (unless the 10-bit path enabled HDR above) —
             // there is no "last known" yet; the descriptor poller corrects a wrong guess mid-session.
-            let display_hdr = enabled_hdr
-                || pf_win_display::win_display::advanced_color_enabled(target.target_id)
-                    .unwrap_or(false);
+            // An SDR-negotiated session (either codec) forced advanced color OFF above and composes
+            // SDR unconditionally: `client_10bit` gates HDR so a client that advertised SDR-only is
+            // never handed a PQ stream, even if a physical display forces HDR on (the descriptor
+            // poller re-asserts OFF; PyroWave's format guard/stash absorbs any lingering FP16 compose).
+            let display_hdr = client_10bit
+                && (enabled_hdr
+                    || pf_win_display::win_display::advanced_color_enabled(target.target_id)
+                        .unwrap_or(false));
             // Downgrade point D (design/hdr-10bit-default-and-av1.md item 2d): the session was
             // NEGOTIATED 10-bit (the client was told HDR in the Welcome), but the virtual display
             // could not enable advanced color — the ring sizes SDR and the encoder will emit 8-bit
@@ -853,6 +962,13 @@ impl IddPushCapturer {
                 client_10bit,
                 display_hdr,
                 want_444,
+                pyrowave,
+                pyro_fence: None,
+                pyro_fence_handle: None,
+                pyro_fence_value: 0,
+                pyro_ring: Vec::new(),
+                pyro_conv: None,
+                pyro_last: None,
                 desc_poller: DescriptorPoller::spawn(
                     target.target_id,
                     DisplayDescriptor {
@@ -1128,6 +1244,16 @@ impl IddPushCapturer {
     /// auto-switch, exactly as on the WGC path. HDR wins over 4:4:4 (there is no 10-bit
     /// full-chroma source): the stream downgrades to 4:2:0 with a warning.
     fn out_format(&self) -> (DXGI_FORMAT, PixelFormat) {
+        // PyroWave never uses this out-ring (it has its own separate-plane `pyro_ring`); the
+        // format here only labels the frame. SDR sessions label NV12 (BT.709 limited), HDR
+        // (negotiated 10-bit) sessions P010 — matching the studio-code planes the pyro CSC writes.
+        if self.pyrowave {
+            return if self.display_hdr {
+                (DXGI_FORMAT_P010, PixelFormat::P010)
+            } else {
+                (DXGI_FORMAT_NV12, PixelFormat::Nv12)
+            };
+        }
         if self.display_hdr {
             if self.want_444 {
                 warn_444_hdr_downgrade_once();
@@ -1215,6 +1341,8 @@ impl IddPushCapturer {
         self.out_ring.clear(); // the output format changed → rebuild lazily at the new format
         self.video_conv = None; // converters are sized + HDR-specific → rebuild at the new mode
         self.hdr_p010_conv = None;
+        self.pyro_ring.clear(); // PyroWave two-plane ring is sized → rebuild at the new mode
+        self.pyro_last = None;
         self.out_idx = 0;
         self.last_present = None;
         Ok(())
@@ -1228,11 +1356,31 @@ impl IddPushCapturer {
     /// only when TWO consecutive samples agree on the same new descriptor (~½ s), so a
     /// single-sample transient during a topology re-probe never costs a ring recreate.
     fn poll_display_hdr(&mut self) {
-        let (now, seq) = self.desc_poller.snapshot();
+        let (mut now, seq) = self.desc_poller.snapshot();
         if seq == self.desc_seq {
             return; // no new sample since last consume
         }
         self.desc_seq = seq;
+        // Two cases re-assert the NEGOTIATED depth instead of following a mid-session "Use HDR"
+        // flip — flip the display back and treat the descriptor as the negotiated state (so the ring
+        // is never recreated at the wrong format):
+        //   - a PyroWave session: its encoder was opened for fixed plane formats (R8 SDR / R16 HDR),
+        //     so it can't follow a flip the way H.26x re-inits do;
+        //   - ANY SDR-negotiated session (`!client_10bit`, either codec): a host-side flip to HDR
+        //     must not promote the stream to P010 PQ behind a client that advertised SDR-only.
+        // An HDR-negotiated H.26x session is NOT pinned — it still follows a host "Use HDR" flip in
+        // either direction (its encoder re-inits on the depth change).
+        if (self.pyrowave || !self.client_10bit) && now.hdr != self.client_10bit {
+            // SAFETY: `set_advanced_color` is `unsafe` (CCD DisplayConfig calls); it takes a plain
+            // `u32` target id + bool, forms no lasting borrow, and returns a bool.
+            unsafe {
+                let _ = pf_win_display::win_display::set_advanced_color(
+                    self.target_id,
+                    self.client_10bit,
+                );
+            }
+            now.hdr = self.client_10bit;
+        }
         let current = DisplayDescriptor {
             hdr: self.display_hdr,
             width: self.width,
@@ -1281,7 +1429,8 @@ impl IddPushCapturer {
             },
             Usage: D3D11_USAGE_DEFAULT,
             // RENDER_TARGET: the VIDEO processor (NV12) and the P010 shader passes both write here, and
-            // NVENC registers it as encode input — matching the WGC YUV ring.
+            // NVENC registers it as encode input — matching the WGC YUV ring. (PyroWave uses its own
+            // shareable two-plane `pyro_ring` instead, so this NVENC/AMF/QSV ring stays unshared.)
             BindFlags: D3D11_BIND_RENDER_TARGET.0 as u32,
             CPUAccessFlags: 0,
             MiscFlags: 0,
@@ -1302,6 +1451,91 @@ impl IddPushCapturer {
         Ok(())
     }
 
+    /// PyroWave: build the separate-plane output ring (`OUT_RING` × {full-res R8 Y, half-res R8G8
+    /// CbCr}, both `SHARED | SHARED_NTHANDLE` + RTV) if not yet built. The wavelet encoder imports the
+    /// two SEPARATE textures (a single planar NV12 import is unreliable on NVIDIA); the
+    /// [`BgraToYuvPlanes`] CSC renders into their RTVs.
+    fn ensure_pyro_ring(&mut self) -> Result<()> {
+        if !self.pyro_ring.is_empty() {
+            return Ok(());
+        }
+        let (w, h) = (self.width, self.height);
+        // SAFETY: all D3D11 calls target `self.device`; every `&desc` is a fully-initialized stack
+        // struct and every `Some(&mut _)` a live out-param; `?` rejects a failed HRESULT before use.
+        // The created textures/RTVs belong to `self.device`.
+        unsafe {
+            let make = |dev: &ID3D11Device,
+                        fmt: DXGI_FORMAT,
+                        w: u32,
+                        h: u32|
+             -> Result<(ID3D11Texture2D, ID3D11RenderTargetView)> {
+                let desc = D3D11_TEXTURE2D_DESC {
+                    Width: w,
+                    Height: h,
+                    MipLevels: 1,
+                    ArraySize: 1,
+                    Format: fmt,
+                    SampleDesc: DXGI_SAMPLE_DESC {
+                        Count: 1,
+                        Quality: 0,
+                    },
+                    Usage: D3D11_USAGE_DEFAULT,
+                    BindFlags: D3D11_BIND_RENDER_TARGET.0 as u32,
+                    CPUAccessFlags: 0,
+                    MiscFlags: (D3D11_RESOURCE_MISC_SHARED_NTHANDLE.0
+                        | D3D11_RESOURCE_MISC_SHARED.0) as u32,
+                };
+                let mut tex: Option<ID3D11Texture2D> = None;
+                dev.CreateTexture2D(&desc, None, Some(&mut tex))
+                    .context("CreateTexture2D(pyro plane)")?;
+                let tex = tex.context("null pyro plane texture")?;
+                let mut rtv: Option<ID3D11RenderTargetView> = None;
+                dev.CreateRenderTargetView(&tex, None, Some(&mut rtv))
+                    .context("CreateRenderTargetView(pyro plane)")?;
+                Ok((tex, rtv.context("null pyro plane rtv")?))
+            };
+            // Plane formats/geometry follow the negotiated session: 16-bit UNORM planes for an
+            // HDR (10-bit) session (P010-style studio codes from the pyro HDR CSC), full-res
+            // chroma for 4:4:4 (design/pyrowave-444-hdr.md Phase 3).
+            let (yf, cf) = if self.display_hdr {
+                (DXGI_FORMAT_R16_UNORM, DXGI_FORMAT_R16G16_UNORM)
+            } else {
+                (DXGI_FORMAT_R8_UNORM, DXGI_FORMAT_R8G8_UNORM)
+            };
+            let (cw, ch) = if self.want_444 {
+                (w, h)
+            } else {
+                (w / 2, h / 2)
+            };
+            for _ in 0..OUT_RING {
+                let (y, y_rtv) = make(&self.device, yf, w, h)?;
+                let (cbcr, cbcr_rtv) = make(&self.device, cf, cw, ch)?;
+                self.pyro_ring.push(PyroOutSlot {
+                    y,
+                    y_rtv,
+                    cbcr,
+                    cbcr_rtv,
+                });
+            }
+        }
+        Ok(())
+    }
+
+    /// PyroWave: build the (mode-aware) RGB→YUV-planes CSC if not yet built. The mode is
+    /// session-fixed: SDR/BGRA vs HDR/scRGB input, half- vs full-res chroma — the composition
+    /// is pinned to the negotiated depth (`poll_display_hdr`), so the converter never needs a
+    /// mid-session mode swap.
+    fn ensure_pyro_conv(&mut self) -> Result<()> {
+        if self.pyro_conv.is_none() {
+            // SAFETY: `BgraToYuvPlanes::new` compiles D3D11 shaders on `self.device`; `?` propagates
+            // failure before it is stored.
+            self.pyro_conv = Some(unsafe {
+                BgraToYuvPlanes::new(&self.device, self.display_hdr, self.want_444)?
+            });
+        }
+        Ok(())
+    }
+
     /// Build the per-mode YUV converter if not already built: a VIDEO-engine BGRA→NV12 processor on an
     /// SDR display, or the FP16→P010 shader on an HDR display. Both keep NVENC's RGB→YUV CSC off the SM.
     /// An SDR 4:4:4 session needs NO converter — the BGRA slot passes through (see `out_format`).
@@ -1327,6 +1561,61 @@ impl IddPushCapturer {
         Ok(())
     }
 
+    /// PyroWave: after this frame's GPU convert, `Signal` the shared fence and return the fence
+    /// `(handle, value)` for the encoder — the persistent shared handle EVERY frame (the encoder
+    /// imports it whenever it has no timeline yet, e.g. after a mode-switch rebuild) + the
+    /// incrementing value. `None` for a non-PyroWave session. The fence + its shared handle are
+    /// created lazily on the first call. `Flush` submits the queued convert + signal so the encoder's
+    /// cross-API Vulkan timeline wait resolves promptly instead of blocking on a still-unsubmitted
+    /// signal. The caller pairs the returned fence with the frame's CbCr texture into a
+    /// [`PyroFrameShare`].
+    ///
+    /// # Safety
+    /// Runs on the owning capture/encode thread that holds the immediate context; forms no lasting
+    /// borrow of `self`'s COM objects.
+    unsafe fn pyro_fence_signal(&mut self) -> Result<Option<(Option<isize>, u64)>> {
+        if !self.pyrowave {
+            return Ok(None);
+        }
+        if self.pyro_fence.is_none() {
+            let dev5: ID3D11Device5 = self
+                .device
+                .cast()
+                .context("ID3D11Device -> ID3D11Device5 (shared fence)")?;
+            // windows-rs returns COM interfaces via an out-param (unlike the HANDLE-returning
+            // CreateSharedHandle below).
+            let mut fence_out: Option<ID3D11Fence> = None;
+            dev5.CreateFence(0, D3D11_FENCE_FLAG_SHARED, &mut fence_out)
+                .context("CreateFence(D3D11_FENCE_FLAG_SHARED)")?;
+            let fence = fence_out.context("null D3D11 fence")?;
+            // GENERIC_ALL (0x1000_0000) — the access the pyrowave interop test hands the handle.
+            let handle: HANDLE = fence
+                .CreateSharedHandle(None, 0x1000_0000, PCWSTR::null())
+                .context("ID3D11Fence::CreateSharedHandle")?;
+            self.pyro_fence = Some(fence);
+            self.pyro_fence_handle = Some(handle.0 as isize);
+            self.pyro_fence_value = 0;
+        }
+        self.pyro_fence_value += 1;
+        let value = self.pyro_fence_value;
+        let ctx4: ID3D11DeviceContext4 = self
+            .context
+            .cast()
+            .context("ID3D11DeviceContext -> ID3D11DeviceContext4 (fence signal)")?;
+        {
+            let fence = self.pyro_fence.as_ref().expect("fence just created");
+            ctx4.Signal(fence, value)
+                .context("ID3D11 fence Signal after convert")?;
+        }
+        // Submit the queued convert + signal so the encoder's Vulkan timeline wait can resolve.
+        self.context.Flush();
+        // Pass the persistent shared handle EVERY frame (not once): the encoder can be rebuilt on a
+        // client mode-switch, and a rebuilt encoder needs to re-import the fence into its fresh Vulkan
+        // device. The encoder imports only when it has no timeline yet (and DUPLICATES the handle so
+        // this original stays valid for the next rebuild).
+        Ok(Some((self.pyro_fence_handle, value)))
+    }
+
     fn try_consume(&mut self) -> Result<Option<CapturedFrame>> {
         self.log_driver_status_once();
         // Follow the display: a "Use HDR" flip recreates the ring at the matching format.
@@ -1391,13 +1680,34 @@ impl IddPushCapturer {
         if seq == self.last_seq || slot >= self.slots.len() {
             return Ok(None);
         }
-        self.ensure_out_ring()?;
-        // Build the converter BEFORE acquiring the slot so nothing between Acquire and Release can
-        // `?`-return and leak the keyed-mutex lock (which would stall the driver on that slot).
-        self.ensure_converter()?;
+        // Build the ring + converter BEFORE acquiring the slot so nothing between Acquire and Release
+        // can `?`-return and leak the keyed-mutex lock (which would stall the driver on that slot).
+        // PyroWave uses its OWN two-plane ring (`pyro_ring`); everything else the single NV12/BGRA ring.
         let i = self.out_idx;
-        let out = self.out_ring[i].clone();
+        let (out, pyro_slot) = if self.pyrowave {
+            self.ensure_pyro_ring()?;
+            self.ensure_pyro_conv()?;
+            let s = &self.pyro_ring[i];
+            (
+                None,
+                Some((
+                    s.y.clone(),
+                    s.y_rtv.clone(),
+                    s.cbcr.clone(),
+                    s.cbcr_rtv.clone(),
+                )),
+            )
+        } else {
+            self.ensure_out_ring()?;
+            self.ensure_converter()?;
+            (Some(self.out_ring[i].clone()), None)
+        };
         let (_, pf) = self.out_format();
+        let ring_len = if self.pyrowave {
+            self.pyro_ring.len()
+        } else {
+            self.out_ring.len()
+        };
 
         // Hold the slot's keyed mutex only across the convert/copy into the host out-ring (NOT across the
         // ~3 ms encode — NVENC reads the host out-ring slot, not the keyed-mutex slot), so the driver gets
@@ -1414,14 +1724,30 @@ impl IddPushCapturer {
             // A `?` here is leak-safe: `_lock` (the KeyedMutexGuard) drops on the early return, releasing
             // the slot back to the driver.
             unsafe {
-                if self.display_hdr {
+                if self.pyrowave {
+                    // PyroWave: ring slot SRV (BGRA for SDR, scRGB FP16 for HDR) → the two separate
+                    // plane textures via the mode-aware CSC; the shared fence signalled just after
+                    // (`pyro_fence_signal`) orders the encoder's cross-device Vulkan read after this
+                    // convert. The composition format is pinned to the negotiated depth.
+                    let (_, y_rtv, _, cbcr_rtv) = pyro_slot.as_ref().expect("pyro slot");
+                    if let Some(conv) = self.pyro_conv.as_ref() {
+                        conv.convert(
+                            &self.context,
+                            &s.srv,
+                            y_rtv,
+                            cbcr_rtv,
+                            self.width,
+                            self.height,
+                        )?;
+                    }
+                } else if self.display_hdr {
                     // HDR: FP16 slot SRV → P010 (BT.2020 PQ) via the shader; NVENC takes native P010.
                     if let Some(conv) = self.hdr_p010_conv.as_ref() {
                         conv.convert(
                             &self.device,
                             &self.context,
                             &s.srv,
-                            &out,
+                            out.as_ref().expect("out ring"),
                             self.width,
                             self.height,
                         )?;
@@ -1430,19 +1756,24 @@ impl IddPushCapturer {
                     // SDR 4:4:4: pass the BGRA slot through untouched — NVENC ingests full-chroma
                     // RGB and CSCs to YUV 4:4:4 itself (per the always-written BT.709 VUI). Plain
                     // copy-engine move; the slot releases back to the driver immediately.
-                    self.context.CopyResource(&out, &s.tex);
+                    self.context
+                        .CopyResource(out.as_ref().expect("out ring"), &s.tex);
                 } else {
                     // SDR: BGRA slot → NV12 on the VIDEO engine; NVENC takes native NV12, no SM-side CSC.
                     if let Some(conv) = self.video_conv.as_ref() {
-                        conv.convert(&s.tex, &out)?;
+                        conv.convert(&s.tex, out.as_ref().expect("out ring"))?;
                     }
                 }
             }
             // `_lock` drops here → `ReleaseSync(0)`.
         }
-        self.out_idx = (i + 1) % self.out_ring.len();
+        self.out_idx = (i + 1) % ring_len;
         self.last_seq = seq;
-        self.last_present = Some((out.clone(), pf));
+        if let Some((y, _, cbcr, _)) = pyro_slot.as_ref() {
+            self.pyro_last = Some((y.clone(), cbcr.clone()));
+        } else {
+            self.last_present = Some((out.as_ref().expect("out ring").clone(), pf));
+        }
         let now = Instant::now();
         if self.recovering_since.take().is_some() {
             // A fresh frame resumed → recovered. The recovery gap is self-inflicted (ring
@@ -1517,14 +1848,33 @@ impl IddPushCapturer {
             }
         }
         self.last_fresh = now; // feeds the driver-death watch
+                               // Build the frame. For PyroWave the encode input is the Y plane
+                               // (`texture`) + the CbCr plane & fence in `pyro`; signal the shared fence
+                               // after the convert above. SAFETY: on the owning capture/encode thread.
+        let (texture, pyro) = if let Some((y, _, cbcr, _)) = pyro_slot {
+            // SAFETY: on the owning capture/encode thread holding the immediate context.
+            let (fence_handle, fence_value) =
+                unsafe { self.pyro_fence_signal() }?.expect("pyrowave session signals its fence");
+            (
+                y,
+                Some(PyroFrameShare {
+                    cbcr,
+                    fence_handle,
+                    fence_value,
+                }),
+            )
+        } else {
+            (out.expect("out ring texture"), None)
+        };
         Ok(Some(CapturedFrame {
             width: self.width,
             height: self.height,
             pts_ns: now_ns(),
             format: pf,
             payload: FramePayload::D3d11(D3d11Frame {
-                texture: out,
+                texture,
                 device: self.device.clone(),
+                pyro,
             }),
             cursor: None,
         }))
@@ -1535,8 +1885,46 @@ impl IddPushCapturer {
         // new driver frame) never re-hands a slot that may still be encoding under pipeline_depth>1 — the
         // out-ring rotation IS the texture-ownership contract, and repeats must honor it too (audit §5.3).
         // OUT_RING(3) > the max pipeline_depth(2) guarantees the rotated slot is not in flight.
-        let (src, pf) = self.last_present.clone()?;
         let i = self.out_idx;
+        // PyroWave: copy the last Y+CbCr into a fresh two-plane slot; texture = Y, CbCr + fence in `pyro`.
+        if self.pyrowave {
+            let (src_y, src_cbcr) = self.pyro_last.clone()?;
+            let slot = self.pyro_ring.get(i)?;
+            let (dst_y, dst_cbcr) = (slot.y.clone(), slot.cbcr.clone());
+            // SAFETY: GPU copies on the owning thread's immediate context; src/dst are our own pyro-ring
+            // plane textures of identical format/size.
+            unsafe {
+                self.context.CopyResource(&dst_y, &src_y);
+                self.context.CopyResource(&dst_cbcr, &src_cbcr);
+            }
+            self.out_idx = (i + 1) % self.pyro_ring.len();
+            self.pyro_last = Some((dst_y.clone(), dst_cbcr.clone()));
+            // Fence the copies above so the encoder reads completed textures. SAFETY: owning thread.
+            let (fence_handle, fence_value) = match unsafe { self.pyro_fence_signal() } {
+                Ok(Some(f)) => f,
+                _ => {
+                    tracing::warn!("pyrowave: fence signal failed on a repeat frame — dropping it");
+                    return None;
+                }
+            };
+            return Some(CapturedFrame {
+                width: self.width,
+                height: self.height,
+                pts_ns: now_ns(),
+                format: self.out_format().1,
+                payload: FramePayload::D3d11(D3d11Frame {
+                    texture: dst_y,
+                    device: self.device.clone(),
+                    pyro: Some(PyroFrameShare {
+                        cbcr: dst_cbcr,
+                        fence_handle,
+                        fence_value,
+                    }),
+                }),
+                cursor: None,
+            });
+        }
+        let (src, pf) = self.last_present.clone()?;
         let dst = self.out_ring.get(i)?.clone();
         // SAFETY: GPU copy on the owning thread's immediate context; src/dst are our out-ring textures of
         // identical format/size (src is a previous out-ring slot; dst the next).
@@ -1553,6 +1941,7 @@ impl IddPushCapturer {
             payload: FramePayload::D3d11(D3d11Frame {
                 texture: dst,
                 device: self.device.clone(),
+                pyro: None,
             }),
             cursor: None,
         })

crates/pf-capture/src/windows/synthetic_nv12.rs

@@ -127,6 +127,7 @@ impl Capturer for SyntheticNv12Capturer {
             payload: FramePayload::D3d11(D3d11Frame {
                 texture: self.default_tex.clone(),
                 device: self.device.clone(),
+                pyro: None,
             }),
             cursor: None,
         })

crates/pf-client-core/Cargo.toml

@@ -24,6 +24,14 @@ ffmpeg-next = "8"
 opus = "0.3"
 
 mdns-sd = "0.20"
+
+# PyroWave decode (the opt-in wired-LAN wavelet codec, design/pyrowave-codec-plan.md
+# §4.5) — pure Vulkan compute on the presenter's shared device, so it builds wherever the
+# spawned Vulkan session presenter runs: Linux AND Windows (pyrowave-sys covers both; it
+# is an empty stub elsewhere). `ash` only wraps the presenter's existing raw handles
+# (same pinned version as pf-presenter).
+pyrowave-sys = { path = "../pyrowave-sys", optional = true }
+ash = { version = "0.38", optional = true }
 # 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`.
@@ -40,11 +48,6 @@ tracing = "0.1"
 [target.'cfg(target_os = "linux")'.dependencies]
 pipewire = "0.9"
 sdl3 = { version = "0.18", features = ["hidapi"] }
-# PyroWave decode (the opt-in wired-LAN wavelet codec, design/pyrowave-codec-plan.md
-# §4.5) — pure Vulkan compute on the presenter's shared device. `ash` only wraps the
-# presenter's existing raw handles (same pinned version as pf-presenter).
-pyrowave-sys = { path = "../pyrowave-sys", optional = true }
-ash = { version = "0.38", optional = true }
 
 [target.'cfg(windows)'.dependencies]
 wasapi = "0.23"
@@ -61,6 +64,10 @@ windows = { git = "https://github.com/microsoft/windows-rs", rev = "a4f7b2cb7c63
     # IDXGIResource1::CreateSharedHandle takes an optional SECURITY_ATTRIBUTES — the
     # method itself is feature-gated behind this.
     "Win32_Security",
+    # The OS-clipboard bridge (clipboard.rs): Open/Get/SetClipboardData + the sequence
+    # number, and the GlobalAlloc block the clipboard takes ownership of.
+    "Win32_System_DataExchange",
+    "Win32_System_Memory",
 ] }
 
 [features]

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

@@ -20,6 +20,83 @@ const MIC_FRAME: usize = 960;
 
 struct Terminate;
 
+/// A selectable PipeWire endpoint for the settings pickers.
+#[derive(Clone, Debug)]
+pub struct AudioDevice {
+    /// `node.name` — the stable key the streams target via `target.object`.
+    pub name: String,
+    /// `node.description` — the human label the picker shows.
+    pub description: String,
+}
+
+/// Enumerate audio endpoints: `(sinks, sources)`. One registry roundtrip on a private
+/// mainloop (a few ms against a live PipeWire); no daemon errors out and the caller
+/// simply shows no pickers.
+pub fn devices() -> Result<(Vec<AudioDevice>, Vec<AudioDevice>)> {
+    use pipewire as pw;
+    use std::cell::RefCell;
+    use std::rc::Rc;
+
+    static PW_INIT: std::sync::Once = std::sync::Once::new();
+    PW_INIT.call_once(pw::init);
+
+    let mainloop = pw::main_loop::MainLoopRc::new(None).context("pw MainLoop")?;
+    let context = pw::context::ContextRc::new(&mainloop, None).context("pw Context")?;
+    let core = context
+        .connect_rc(None)
+        .context("pw connect (is PipeWire running in this session?)")?;
+    let registry = core.get_registry_rc().context("pw registry")?;
+
+    let found: Rc<RefCell<(Vec<AudioDevice>, Vec<AudioDevice>)>> = Rc::default();
+    let _reg_listener = registry
+        .add_listener_local()
+        .global({
+            let found = found.clone();
+            move |g| {
+                let Some(props) = g.props else { return };
+                let sink = match props.get("media.class") {
+                    Some("Audio/Sink") => true,
+                    Some("Audio/Source") => false,
+                    _ => return,
+                };
+                let Some(name) = props.get("node.name") else {
+                    return;
+                };
+                let description = props
+                    .get("node.description")
+                    .or_else(|| props.get("node.nick"))
+                    .unwrap_or(name)
+                    .to_string();
+                let dev = AudioDevice {
+                    name: name.to_string(),
+                    description,
+                };
+                let mut f = found.borrow_mut();
+                if sink { &mut f.0 } else { &mut f.1 }.push(dev);
+            }
+        })
+        .register();
+
+    // The registry replays existing globals asynchronously; one core sync marks the
+    // point they've all been delivered — quit the loop there.
+    let pending = core.sync(0).context("pw sync")?;
+    let _core_listener = core
+        .add_listener_local()
+        .done({
+            let mainloop = mainloop.clone();
+            move |_, seq| {
+                if seq == pending {
+                    mainloop.quit();
+                }
+            }
+        })
+        .register();
+    mainloop.run();
+
+    let result = found.borrow().clone();
+    Ok(result)
+}
+
 pub struct AudioPlayer {
     pcm_tx: SyncSender<Vec<f32>>,
     /// Drained chunk Vecs coming back from the PipeWire consumer for reuse (the pool half
@@ -118,20 +195,26 @@ fn pw_thread(
         move |_| mainloop.quit()
     });
 
-    let stream = pw::stream::StreamBox::new(
-        &core,
-        "punktfunk-client",
-        properties! {
-            *pw::keys::MEDIA_TYPE       => "Audio",
-            *pw::keys::MEDIA_CATEGORY   => "Playback",
-            *pw::keys::MEDIA_ROLE       => "Game",
-            *pw::keys::NODE_NAME        => "punktfunk-client",
-            *pw::keys::NODE_DESCRIPTION => "Punktfunk Stream",
-            // ~5 ms quantum (one Opus frame) keeps the ring — and so the latency — small.
-            *pw::keys::NODE_LATENCY     => "240/48000",
-        },
-    )
-    .context("pw Stream")?;
+    let mut props = properties! {
+        *pw::keys::MEDIA_TYPE       => "Audio",
+        *pw::keys::MEDIA_CATEGORY   => "Playback",
+        *pw::keys::MEDIA_ROLE       => "Game",
+        *pw::keys::NODE_NAME        => "punktfunk-client",
+        *pw::keys::NODE_DESCRIPTION => "Punktfunk Stream",
+        // ~5 ms quantum (one Opus frame) keeps the ring — and so the latency — small.
+        *pw::keys::NODE_LATENCY     => "240/48000",
+    };
+    // The Settings speaker pick (session main maps `Settings::speaker_device` here);
+    // unset/empty = PipeWire's default routing.
+    if let Ok(target) = std::env::var("PUNKTFUNK_AUDIO_SINK") {
+        if !target.is_empty() {
+            // Raw key: the `keys::TARGET_OBJECT` constant is feature-gated on a newer
+            // libpipewire than we require; the wire name is stable.
+            props.insert("target.object", target);
+        }
+    }
+    let stream =
+        pw::stream::StreamBox::new(&core, "punktfunk-client", props).context("pw Stream")?;
 
     let ud = PlayerData {
         rx: pcm_rx,
@@ -316,18 +399,23 @@ fn mic_thread(
         move |_| mainloop.quit()
     });
 
-    let stream = pw::stream::StreamBox::new(
-        &core,
-        "punktfunk-mic-capture",
-        properties! {
-            *pw::keys::MEDIA_TYPE       => "Audio",
-            *pw::keys::MEDIA_CATEGORY   => "Capture",
-            *pw::keys::MEDIA_ROLE       => "Communication",
-            *pw::keys::NODE_NAME        => "punktfunk-mic-capture",
-            *pw::keys::NODE_DESCRIPTION => "Punktfunk Microphone",
-        },
-    )
-    .context("pw mic Stream")?;
+    let mut props = properties! {
+        *pw::keys::MEDIA_TYPE       => "Audio",
+        *pw::keys::MEDIA_CATEGORY   => "Capture",
+        *pw::keys::MEDIA_ROLE       => "Communication",
+        *pw::keys::NODE_NAME        => "punktfunk-mic-capture",
+        *pw::keys::NODE_DESCRIPTION => "Punktfunk Microphone",
+    };
+    // The Settings microphone pick (`Settings::mic_device` via session main).
+    if let Ok(target) = std::env::var("PUNKTFUNK_AUDIO_SOURCE") {
+        if !target.is_empty() {
+            // Raw key: the `keys::TARGET_OBJECT` constant is feature-gated on a newer
+            // libpipewire than we require; the wire name is stable.
+            props.insert("target.object", target);
+        }
+    }
+    let stream = pw::stream::StreamBox::new(&core, "punktfunk-mic-capture", props)
+        .context("pw mic Stream")?;
 
     let ud = MicData {
         connector: connector.clone(),

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

@@ -0,0 +1,421 @@
+//! OS-clipboard bridge for the spawned session client (`design/clipboard-and-file-transfer.md`
+//! §5). The protocol half already exists in `punktfunk_core::clipboard` — the per-session task
+//! that runs fetch streams — and `NativeClient` exposes it as `clip_control` / `clip_offer` /
+//! `clip_fetch` / `clip_serve` / `next_clip`. What was missing on Windows is exactly what §5.2
+//! writes in Swift for macOS: the code that talks to the actual pasteboard. This is that half.
+//!
+//! Shape (one thread, owned by the session pump):
+//!
+//! * **Local → remote** stays lazy by construction. A poll of `GetClipboardSequenceNumber`
+//!   spots a local copy, we announce the FORMAT LIST (`clip_offer`) and nothing else; the
+//!   bytes are read only if the host actually pastes and sends a `FetchRequest`.
+//! * **Remote → local** is EAGER in this first cut, and that is a deliberate deviation from
+//!   §5.2's promise-based apply. macOS gets laziness free from `NSPasteboardItemDataProvider`;
+//!   the Windows equivalent is delayed rendering (`SetClipboardData(fmt, NULL)` answered on
+//!   `WM_RENDERFORMAT`), which needs a clipboard-owning window running its own message pump —
+//!   a bigger piece than this. So we fetch on the offer and place real bytes, under
+//!   [`EAGER_FETCH_CAP`] so a huge host-side copy can't pull megabytes nobody pastes. Text is
+//!   tiny and always crosses; a large image simply isn't mirrored until delayed rendering lands.
+//! * **Echo suppression** is §3.4's Windows rule verbatim: record the clipboard sequence
+//!   number right after our own `SetClipboardData` and ignore exactly that change, or every
+//!   copy ping-pongs between the two machines forever.
+//!
+//! Secrets are respected: a clipboard carrying `ExcludeClipboardContentFromMonitorProcessing`
+//! (what password managers set) is never announced and never served — the Windows counterpart
+//! of §5.2's `org.nspasteboard.ConcealedType` skip.
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use punktfunk_core::client::NativeClient;
+use punktfunk_core::clipboard::ClipEventCore;
+use punktfunk_core::quic::{ClipKind, CLIP_FILE_INDEX_NONE, HOST_CAP_CLIPBOARD};
+
+/// Wire mime for UTF-8 text — the one format every peer must handle (§3.5).
+const MIME_TEXT: &str = "text/plain;charset=utf-8";
+/// Wire mime for the image floor (§3.5). Read/written through the "PNG" registered clipboard
+/// format; apps that only publish `CF_DIB` are a follow-up (the conversion the host already
+/// has in `image_to_dib`).
+const MIME_PNG: &str = "image/png";
+
+/// Ceiling on an EAGERLY fetched remote payload (see the module docs). Text never approaches
+/// it; it exists so a host-side copy of something enormous doesn't cross for a paste that may
+/// never happen. Lifted once delayed rendering makes the fetch lazy.
+const EAGER_FETCH_CAP: u64 = 4 << 20;
+
+/// How often the local clipboard is polled for changes. §3.2 asks for ≥ 100 ms between offers;
+/// 400 ms keeps a copy→focus→paste round trip comfortably ahead of the user.
+const POLL: Duration = Duration::from_millis(400);
+
+/// Drain-and-poll cadence: how long `next_clip` blocks before we re-check the clipboard and
+/// the stop flag.
+const EVENT_WAIT: Duration = Duration::from_millis(120);
+
+/// Run the clipboard bridge until `stop` is set or the session closes. Returns immediately
+/// (doing nothing) when the host didn't advertise `HOST_CAP_CLIPBOARD` — an older host, or one
+/// whose backend can't do it — so this is safe to spawn unconditionally.
+pub fn run(client: Arc<NativeClient>, stop: Arc<AtomicBool>) {
+    if client.host_caps() & HOST_CAP_CLIPBOARD == 0 {
+        tracing::info!("host has no clipboard capability — shared clipboard off");
+        return;
+    }
+    // Opt-in per §3.1: nothing is announced or served until this crosses enabled.
+    if let Err(e) = client.clip_control(true, 0) {
+        tracing::warn!(error = %e, "clipboard: enable failed");
+        return;
+    }
+    tracing::info!("shared clipboard enabled");
+
+    let mut state = State {
+        // Adopt the CURRENT sequence number without announcing: whatever is on the clipboard
+        // from before the session started is the user's, not a copy they made for this stream.
+        last_seq: os::sequence_number(),
+        ..Default::default()
+    };
+    let mut next_poll = Instant::now() + POLL;
+
+    while !stop.load(Ordering::SeqCst) {
+        // Inbound first — a pending FetchRequest is the host waiting on us. `NoFrame` is the
+        // ordinary poll timeout (nothing pending); anything else means the connection is gone
+        // and the session teardown is already on its way.
+        match client.next_clip(EVENT_WAIT) {
+            Ok(ev) => handle_event(&client, &mut state, ev),
+            Err(punktfunk_core::error::PunktfunkError::NoFrame) => {}
+            Err(_) => break,
+        }
+        // The local clipboard is polled on its OWN cadence, not once per inbound wait: the
+        // event wait is short (it bounds teardown latency), and hammering the Win32 clipboard
+        // eight times a second would contend with whatever app the user is actually copying in.
+        let now = Instant::now();
+        if now >= next_poll {
+            poll_local(&client, &mut state);
+            next_poll = now + POLL;
+        }
+    }
+    // Best-effort: tell the host to stop announcing into a session that's ending.
+    let _ = client.clip_control(false, 0);
+}
+
+#[derive(Default)]
+struct State {
+    /// Clipboard sequence number as of our last look — a change means someone copied.
+    last_seq: u32,
+    /// The sequence number our OWN `SetClipboardData` produced (§3.4 echo suppression).
+    self_written_seq: Option<u32>,
+    /// Monotonic offer counter (§3.2 — newest wins).
+    offer_seq: u32,
+    /// Rate-limit guard for offers (§3.2 asks ≥ 100 ms).
+    last_offer: Option<Instant>,
+    /// The host's current offer, so a fetch can name its `seq`.
+    remote_offer: Option<u32>,
+    /// In-flight eager fetch → the mime it will deliver, so `Data` knows how to place it.
+    pending_fetch: Option<(u32, String)>,
+    /// The last payload we placed locally, kept only to answer a host fetch of our own echo
+    /// without re-reading the OS clipboard.
+    last_applied: Option<(String, Vec<u8>)>,
+}
+
+/// A local clipboard change → announce the format list (never the bytes).
+fn poll_local(client: &NativeClient, state: &mut State) {
+    let seq = os::sequence_number();
+    if seq == state.last_seq {
+        return;
+    }
+    state.last_seq = seq;
+    // Our own apply — swallow it, or the two clipboards chase each other forever.
+    if state.self_written_seq == Some(seq) {
+        state.self_written_seq = None;
+        return;
+    }
+    if let Some(t) = state.last_offer {
+        if t.elapsed() < Duration::from_millis(100) {
+            return;
+        }
+    }
+    if os::is_concealed() {
+        tracing::debug!("clipboard: concealed content — not announced");
+        return;
+    }
+    let mut kinds: Vec<ClipKind> = Vec::new();
+    for (mime, size) in os::available_kinds() {
+        kinds.push(ClipKind {
+            mime: mime.to_string(),
+            size_hint: size,
+        });
+    }
+    if kinds.is_empty() {
+        return;
+    }
+    state.offer_seq = state.offer_seq.wrapping_add(1);
+    state.last_offer = Some(Instant::now());
+    let seq_id = state.offer_seq;
+    tracing::debug!(
+        seq = seq_id,
+        kinds = kinds.len(),
+        "clipboard: offering local copy"
+    );
+    if let Err(e) = client.clip_offer(seq_id, kinds) {
+        tracing::warn!(error = %e, "clipboard: offer failed");
+    }
+}
+
+fn handle_event(client: &NativeClient, state: &mut State, ev: ClipEventCore) {
+    match ev {
+        ClipEventCore::State {
+            enabled,
+            policy,
+            reason,
+        } => {
+            tracing::info!(enabled, policy, reason, "clipboard: host state");
+        }
+        // The host copied. Pull the best format we can place (see the module docs on why this
+        // is eager for now) — text preferred, then PNG.
+        ClipEventCore::RemoteOffer { seq, kinds } => {
+            state.remote_offer = Some(seq);
+            let pick = kinds
+                .iter()
+                .find(|k| k.mime == MIME_TEXT)
+                .or_else(|| kinds.iter().find(|k| k.mime == MIME_PNG));
+            let Some(kind) = pick else {
+                tracing::debug!("clipboard: remote offer has no format we can place");
+                return;
+            };
+            if kind.size_hint > EAGER_FETCH_CAP {
+                tracing::info!(
+                    mime = %kind.mime,
+                    size = kind.size_hint,
+                    "clipboard: remote payload over the eager-fetch cap — not mirrored"
+                );
+                return;
+            }
+            match client.clip_fetch(seq, kind.mime.clone(), CLIP_FILE_INDEX_NONE) {
+                Ok(xfer) => state.pending_fetch = Some((xfer, kind.mime.clone())),
+                Err(e) => tracing::warn!(error = %e, "clipboard: fetch failed to start"),
+            }
+        }
+        // Bytes for the fetch above — place them, then record the sequence number they cause.
+        ClipEventCore::Data {
+            xfer_id,
+            bytes,
+            last,
+        } => {
+            let Some((pending, mime)) = state.pending_fetch.clone() else {
+                return;
+            };
+            if pending != xfer_id {
+                return;
+            }
+            if last {
+                state.pending_fetch = None;
+            }
+            match os::set(&mime, &bytes) {
+                Ok(()) => {
+                    // §3.4: this is the change WE caused; ignore exactly it.
+                    state.self_written_seq = Some(os::sequence_number());
+                    state.last_applied = Some((mime.clone(), bytes));
+                    tracing::debug!(mime = %mime, "clipboard: applied remote content");
+                }
+                Err(e) => tracing::warn!(error = %e, mime = %mime, "clipboard: apply failed"),
+            }
+        }
+        // The host is pasting what we offered: read the bytes NOW (this is the lazy half) and
+        // answer. A read failure still answers — with a cancel — so the host isn't left waiting.
+        ClipEventCore::FetchRequest {
+            req_id,
+            seq: _,
+            file_index: _,
+            mime,
+        } => {
+            if os::is_concealed() {
+                let _ = client.clip_cancel(req_id);
+                return;
+            }
+            // Serve our own last-applied payload verbatim when it still matches — avoids a
+            // lossy OS round trip for content that originated on the host anyway.
+            let bytes = match &state.last_applied {
+                Some((m, b)) if *m == mime && state.self_written_seq.is_some() => Ok(b.clone()),
+                _ => os::get(&mime),
+            };
+            match bytes {
+                Ok(b) => {
+                    tracing::debug!(mime = %mime, len = b.len(), "clipboard: serving to host");
+                    if let Err(e) = client.clip_serve(req_id, b, true) {
+                        tracing::warn!(error = %e, "clipboard: serve failed");
+                    }
+                }
+                Err(e) => {
+                    tracing::debug!(error = %e, mime = %mime, "clipboard: nothing to serve");
+                    let _ = client.clip_cancel(req_id);
+                }
+            }
+        }
+        ClipEventCore::Cancelled { id } => tracing::debug!(id, "clipboard: transfer cancelled"),
+        ClipEventCore::Error { id, code } => {
+            tracing::debug!(id, code, "clipboard: transfer error");
+            if state.pending_fetch.as_ref().is_some_and(|(x, _)| *x == id) {
+                state.pending_fetch = None;
+            }
+        }
+    }
+}
+
+#[cfg(windows)]
+mod os {
+    //! The Win32 clipboard seam. Every entry point opens the clipboard, does one thing and
+    //! closes it — holding it across a network fetch would block every other app on the box.
+
+    use super::{MIME_PNG, MIME_TEXT};
+    use anyhow::{anyhow, bail, Result};
+    use windows::core::PCWSTR;
+    use windows::Win32::Foundation::{HANDLE, HGLOBAL};
+    use windows::Win32::System::DataExchange::{
+        CloseClipboard, EmptyClipboard, GetClipboardData, GetClipboardSequenceNumber,
+        IsClipboardFormatAvailable, OpenClipboard, RegisterClipboardFormatW, SetClipboardData,
+    };
+    use windows::Win32::System::Memory::{
+        GlobalAlloc, GlobalLock, GlobalSize, GlobalUnlock, GMEM_MOVEABLE,
+    };
+
+    const CF_UNICODETEXT: u32 = 13;
+
+    /// A registered clipboard format id, by name (`PNG`, the concealed marker, …).
+    fn registered(name: &str) -> u32 {
+        let wide: Vec<u16> = name.encode_utf16().chain(std::iter::once(0)).collect();
+        unsafe { RegisterClipboardFormatW(PCWSTR(wide.as_ptr())) }
+    }
+
+    fn png_format() -> u32 {
+        registered("PNG")
+    }
+
+    /// RAII clipboard open — `CloseClipboard` must run even on the error paths.
+    struct Clip;
+    impl Clip {
+        fn open() -> Result<Clip> {
+            // A retry loop: another app can hold the clipboard for a moment.
+            for _ in 0..10 {
+                if unsafe { OpenClipboard(None) }.is_ok() {
+                    return Ok(Clip);
+                }
+                std::thread::sleep(std::time::Duration::from_millis(10));
+            }
+            bail!("clipboard busy")
+        }
+    }
+    impl Drop for Clip {
+        fn drop(&mut self) {
+            let _ = unsafe { CloseClipboard() };
+        }
+    }
+
+    pub fn sequence_number() -> u32 {
+        unsafe { GetClipboardSequenceNumber() }
+    }
+
+    /// Password managers mark secrets with this format; §5.2's concealed-type rule.
+    pub fn is_concealed() -> bool {
+        let fmt = registered("ExcludeClipboardContentFromMonitorProcessing");
+        unsafe { IsClipboardFormatAvailable(fmt) }.is_ok()
+    }
+
+    /// The wire kinds the current clipboard can supply, with size hints where they're free.
+    pub fn available_kinds() -> Vec<(&'static str, u64)> {
+        let mut out = Vec::new();
+        if unsafe { IsClipboardFormatAvailable(CF_UNICODETEXT) }.is_ok() {
+            out.push((MIME_TEXT, 0));
+        }
+        if unsafe { IsClipboardFormatAvailable(png_format()) }.is_ok() {
+            out.push((MIME_PNG, 0));
+        }
+        out
+    }
+
+    /// Read one wire format off the clipboard.
+    pub fn get(mime: &str) -> Result<Vec<u8>> {
+        let _clip = Clip::open()?;
+        match mime {
+            MIME_TEXT => {
+                let h = unsafe { GetClipboardData(CF_UNICODETEXT) }?;
+                let g = HGLOBAL(h.0);
+                let p = unsafe { GlobalLock(g) } as *const u16;
+                if p.is_null() {
+                    bail!("clipboard text lock failed");
+                }
+                // GlobalSize is a byte count of a NUL-terminated UTF-16 buffer.
+                let bytes = unsafe { GlobalSize(g) };
+                let mut len = bytes / 2;
+                let slice = unsafe { std::slice::from_raw_parts(p, len) };
+                if let Some(nul) = slice.iter().position(|&c| c == 0) {
+                    len = nul;
+                }
+                let text = String::from_utf16_lossy(unsafe { std::slice::from_raw_parts(p, len) });
+                let _ = unsafe { GlobalUnlock(g) };
+                Ok(text.into_bytes())
+            }
+            MIME_PNG => {
+                let h = unsafe { GetClipboardData(png_format()) }?;
+                let g = HGLOBAL(h.0);
+                let p = unsafe { GlobalLock(g) } as *const u8;
+                if p.is_null() {
+                    bail!("clipboard png lock failed");
+                }
+                let len = unsafe { GlobalSize(g) };
+                let out = unsafe { std::slice::from_raw_parts(p, len) }.to_vec();
+                let _ = unsafe { GlobalUnlock(g) };
+                Ok(out)
+            }
+            other => Err(anyhow!("unsupported clipboard format {other}")),
+        }
+    }
+
+    /// Place one wire format on the clipboard, replacing its contents.
+    pub fn set(mime: &str, bytes: &[u8]) -> Result<()> {
+        let (fmt, payload) = match mime {
+            MIME_TEXT => {
+                let text = String::from_utf8_lossy(bytes);
+                let wide: Vec<u16> = text.encode_utf16().chain(std::iter::once(0)).collect();
+                let raw: Vec<u8> = wide.iter().flat_map(|c| c.to_le_bytes()).collect();
+                (CF_UNICODETEXT, raw)
+            }
+            MIME_PNG => (png_format(), bytes.to_vec()),
+            other => bail!("unsupported clipboard format {other}"),
+        };
+        let _clip = Clip::open()?;
+        unsafe { EmptyClipboard() }?;
+        // The clipboard OWNS this block once SetClipboardData succeeds — do not free it.
+        let g = unsafe { GlobalAlloc(GMEM_MOVEABLE, payload.len()) }?;
+        let p = unsafe { GlobalLock(g) } as *mut u8;
+        if p.is_null() {
+            bail!("clipboard alloc lock failed");
+        }
+        unsafe { std::ptr::copy_nonoverlapping(payload.as_ptr(), p, payload.len()) };
+        let _ = unsafe { GlobalUnlock(g) };
+        unsafe { SetClipboardData(fmt, Some(HANDLE(g.0))) }?;
+        Ok(())
+    }
+}
+
+#[cfg(not(windows))]
+mod os {
+    //! Non-Windows stub. Linux needs the Wayland `data-control` seam (the same protocol the
+    //! host side already speaks) — the bridge above is platform-neutral and will drive it
+    //! unchanged once this module grows a real implementation.
+    use anyhow::{bail, Result};
+
+    pub fn sequence_number() -> u32 {
+        0
+    }
+    pub fn is_concealed() -> bool {
+        false
+    }
+    pub fn available_kinds() -> Vec<(&'static str, u64)> {
+        Vec::new()
+    }
+    pub fn get(_mime: &str) -> Result<Vec<u8>> {
+        bail!("clipboard unsupported on this platform")
+    }
+    pub fn set(_mime: &str, _bytes: &[u8]) -> Result<()> {
+        bail!("clipboard unsupported on this platform")
+    }
+}

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

@@ -41,11 +41,19 @@ mod video_software;
 mod video_vaapi;
 #[cfg(any(target_os = "linux", windows))]
 mod video_vulkan;
-// PyroWave decode — Linux + `pyrowave` feature only (plan §4.5; the Windows client's
-// present-path decision and the Apple Metal port are their own phases).
+// The OS-clipboard bridge for the shared clipboard (design/clipboard-and-file-transfer.md §5).
+// Built everywhere the session client is; the platform seam inside is Windows-real,
+// stub elsewhere.
+#[cfg(any(target_os = "linux", windows))]
+pub mod clipboard;
+// PyroWave decode — Linux + Windows (plan §4.5; the Apple Metal port is its own phase).
+// Windows joined once its client moved to the SAME spawned Vulkan session presenter as
+// Linux's: the decoder is plain Vulkan compute on the presenter's device (no fds, no
+// dmabuf, no D3D11 interop), so the old "Windows present-path decision" that gated it
+// resolved itself — the present path is now literally the same code.
 #[cfg(windows)]
 pub mod video_d3d11;
-#[cfg(all(target_os = "linux", feature = "pyrowave"))]
+#[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
 pub mod video_pyrowave;
 
 pub mod wol;

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

@@ -41,6 +41,9 @@ pub struct SessionParams {
     pub display_hdr: Option<punktfunk_core::quic::HdrMeta>,
     /// Stream the default microphone to the host's virtual mic source.
     pub mic_enabled: bool,
+    /// Share the clipboard with this host (the per-host `KnownHost::clipboard_sync`). The
+    /// bridge additionally needs the host to advertise `HOST_CAP_CLIPBOARD`.
+    pub clipboard: bool,
     /// Video decoder preference (Settings; `PUNKTFUNK_DECODER` overrides — see
     /// `video::Decoder::new`).
     pub decoder: String,
@@ -227,7 +230,7 @@ fn pump(
     // the plan-§3 contract: the host only ever picks PyroWave when the client names it.
     #[allow(unused_mut)]
     let mut preferred = params.preferred_codec;
-    #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+    #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
     if std::env::var("PUNKTFUNK_PREFER_PYROWAVE").as_deref() == Ok("1") {
         if params.vulkan.as_ref().is_some_and(|v| v.pyrowave_decode) {
             preferred = punktfunk_core::quic::CODEC_PYROWAVE;
@@ -296,15 +299,27 @@ fn pump(
     // A negotiated PyroWave session decodes on the presenter's device, no FFmpeg —
     // reachable only through the explicit preference above (resolve_codec never
     // auto-picks the bit), so failing loudly here is failing an opted-in experiment.
-    #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+    #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
     let built = if connector.codec == punktfunk_core::quic::CODEC_PYROWAVE {
         let mode = connector.mode();
+        // The wavelet bitstream has no VUI: the negotiated Welcome colour signalling IS
+        // the session's colour contract (BT.709 limited SDR today, BT.2020 PQ once the
+        // HDR leg lands), and the chroma the host resolved sizes the plane ring.
+        let color = crate::video::ColorDesc {
+            primaries: connector.color.primaries,
+            transfer: connector.color.transfer,
+            matrix: connector.color.matrix,
+            full_range: connector.color.full_range != 0,
+        };
         match params.vulkan.as_ref() {
             Some(vk) => Decoder::new_pyrowave(
                 vk,
                 mode.width,
                 mode.height,
                 connector.shard_payload as usize,
+                connector.chroma_format == punktfunk_core::quic::CHROMA_IDC_444,
+                color,
+                connector.bit_depth >= 10,
             ),
             None => Err(anyhow::anyhow!(
                 "pyrowave session without a presenter device"
@@ -313,7 +328,7 @@ fn pump(
     } else {
         Decoder::new(codec_id, &params.decoder, params.vulkan.as_ref())
     };
-    #[cfg(not(all(target_os = "linux", feature = "pyrowave")))]
+    #[cfg(not(all(any(target_os = "linux", windows), feature = "pyrowave")))]
     let built = Decoder::new(codec_id, &params.decoder, params.vulkan.as_ref());
     let mut decoder = match built {
         Ok(d) => d,
@@ -327,6 +342,20 @@ fn pump(
     // app-lifetime service's job (the UI attaches it on Connected). Audio runs on its own
     // thread (one puller per plane), blocking on the audio queue like the Apple client.
     let audio_thread = spawn_audio(connector.clone(), stop.clone());
+    // The shared clipboard (design/clipboard-and-file-transfer.md §5): its own thread, since
+    // `next_clip` blocks and the OS clipboard calls can wait on other apps. Returns straight
+    // away when the host has no clipboard capability, so spawning is unconditional.
+    let clipboard_thread = params
+        .clipboard
+        .then(|| {
+            let c = connector.clone();
+            let s = stop.clone();
+            std::thread::Builder::new()
+                .name("pf-clipboard".into())
+                .spawn(move || crate::clipboard::run(c, s))
+                .ok()
+        })
+        .flatten();
     let _mic = params
         .mic_enabled
         .then(|| {
@@ -516,7 +545,7 @@ fn pump(
                             DecodedImage::VkFrame(_) => "vulkan",
                             #[cfg(windows)]
                             DecodedImage::D3d11(_) => "d3d11va",
-                            #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+                            #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
                             DecodedImage::PyroWave(_) => "pyrowave",
                         };
                         if total_frames == 1 {
@@ -527,7 +556,10 @@ fn pump(
                                 DecodedImage::VkFrame(v) => (v.width, v.height, "vulkan-video"),
                                 #[cfg(windows)]
                                 DecodedImage::D3d11(d) => (d.width, d.height, "d3d11va"),
-                                #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+                                #[cfg(all(
+                                    any(target_os = "linux", windows),
+                                    feature = "pyrowave"
+                                ))]
                                 DecodedImage::PyroWave(f) => (f.width, f.height, "pyrowave"),
                             };
                             tracing::info!(width = w, height = h, path, "first frame decoded");
@@ -784,6 +816,9 @@ fn pump(
     if let Some(t) = audio_thread {
         let _ = t.join(); // exits within its 100 ms pull timeout once `stop` is set
     }
+    if let Some(t) = clipboard_thread {
+        let _ = t.join(); // exits within its next_clip wait once `stop` is set
+    }
     let _ = ev_tx.send_blocking(SessionEvent::Ended(end));
 }
 

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

@@ -124,6 +124,12 @@ pub struct KnownHost {
     /// pre-existing stores load; empty until first learned.
     #[serde(default)]
     pub mac: Vec<String>,
+    /// Share this machine's clipboard with THIS host (design/clipboard-and-file-transfer.md
+    /// §5.3 — the Apple client's `StoredHost.clipboardSync`). Per-host, not global: handing a
+    /// host your clipboard is a trust decision about that host. Default off; the host must
+    /// also advertise `HOST_CAP_CLIPBOARD` and have its own policy enabled.
+    #[serde(default)]
+    pub clipboard_sync: bool,
 }
 
 #[derive(Default, Serialize, Deserialize)]
@@ -201,6 +207,7 @@ pub fn persist_host(name: &str, addr: &str, port: u16, fp_hex: &str, paired: boo
         paired,
         last_used: None,
         mac: Vec::new(),
+        clipboard_sync: false,
     });
     let _ = known.save();
 }
@@ -526,6 +533,27 @@ pub struct Settings {
     /// Experimental: the game-library browser ("Browse library…" on saved cards) —
     /// mirrors the Apple client's "Show game library" toggle, default off.
     pub library_enabled: bool,
+    /// Send Wake-on-LAN before connecting to a saved host and wait for it to boot (the
+    /// Apple client's "Auto-wake on connect"). Default ON — that was the unconditional
+    /// behavior before this became a setting. Off is for hosts reached over a VPN, where
+    /// an offline-looking host is really just unreachable by broadcast and the wake +
+    /// wait only adds a delay.
+    #[serde(default = "default_true")]
+    pub auto_wake: bool,
+    /// Reverse the wheel/trackpad scroll direction sent to the host (the Apple client's
+    /// "Invert scroll direction"). Default off = the host scrolls the way this machine does.
+    #[serde(default)]
+    pub invert_scroll: bool,
+    /// Playback endpoint for stream audio — on Linux the PipeWire `node.name` the
+    /// playback stream targets (`target.object`); empty = the session default (the
+    /// Apple client's Speaker picker). The session maps it onto `PUNKTFUNK_AUDIO_SINK`.
+    /// Ignored on Windows until the WASAPI endpoint leg exists.
+    #[serde(default)]
+    pub speaker_device: String,
+    /// Capture endpoint for the mic uplink (same semantics as `speaker_device`;
+    /// `PUNKTFUNK_AUDIO_SOURCE`).
+    #[serde(default)]
+    pub mic_device: String,
     /// Match-window resolution policy (design/midstream-resolution-resize.md D1): the
     /// stream mode follows the session window — the connect asks for the window's pixel
     /// size and a mid-session resize renegotiates the host's virtual display + encoder
@@ -614,6 +642,10 @@ impl Default for Settings {
             stats_verbosity: None,
             fullscreen_on_stream: true,
             library_enabled: false,
+            auto_wake: true,
+            invert_scroll: false,
+            speaker_device: String::new(),
+            mic_device: String::new(),
             match_window: false,
             last_window_w: 0,
             last_window_h: 0,

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

@@ -1,9 +1,10 @@
 //! Video decode: reassembled HEVC access units → frames for the presenter.
 //!
-//! Three backends, picked at session start (auto on Linux: vaapi → vulkan → software on
-//! desktop Mesa, vulkan first on NVIDIA/VanGogh — see
-//! [`VulkanDecodeDevice::prefer_vulkan_over_vaapi`];
-//! override: `PUNKTFUNK_DECODER=vulkan|vaapi|software`):
+//! Three backends, picked at session start (auto is vendor-ordered on BOTH desktop OSes —
+//! see [`VulkanDecodeDevice::prefer_vulkan_first`]. Linux: vaapi → vulkan → software on
+//! desktop Mesa, vulkan first on NVIDIA/VanGogh. Windows: d3d11va → vulkan → software on
+//! Intel/unknown, vulkan first on NVIDIA/AMD.
+//! Override: `PUNKTFUNK_DECODER=vulkan|vaapi|d3d11va|software`):
 //!
 //! * **Vulkan Video**: FFmpeg's Vulkan decoder running on the PRESENTER's own VkDevice
 //!   (its handles arrive via [`VulkanDecodeDevice`]) — the decoded VkImage feeds the
@@ -22,9 +23,12 @@
 //! B-frames, in-band parameter sets on every IDR), so decode is strictly one-in/one-out.
 //!
 //! On Windows the VAAPI/dmabuf backend does not exist (DRM-PRIME is a Linux concept); the
-//! chain there is Vulkan → **D3D11VA** (`crate::video_d3d11` — the vendor-agnostic DXVA
-//! path, which is how Intel's Windows driver gets hardware decode without Vulkan Video)
-//! → software. Everything dmabuf-shaped is `cfg(target_os = "linux")`-gated inline.
+//! hardware pair there is Vulkan Video and **D3D11VA** (`crate::video_d3d11` — the
+//! vendor-agnostic DXVA path every Windows video player exercises), ordered per vendor:
+//! Intel's driver DOES advertise Vulkan Video (Arc drivers since 2023), but FFmpeg-Vulkan
+//! on it strobes and burns the frame budget (B580 field report, 2026-07) where D3D11VA
+//! streams clean — so Intel/unknown take D3D11VA first and NVIDIA/AMD keep Vulkan first.
+//! Everything dmabuf-shaped is `cfg(target_os = "linux")`-gated inline.
 
 // bindgen's C-enum repr is target-dependent (u32 on Linux/clang, i32 on MSVC), so the
 // pf-ffvk Vulkan flag/enum casts below are required on one platform and no-ops on the
@@ -73,7 +77,7 @@ pub enum DecodedImage {
     /// PyroWave planar output: three R8 plane views on the presenter's own device,
     /// decode already fence-complete, GENERAL layout — the presenter's planar CSC
     /// samples them directly (BT.709 limited, the codec's fixed colour contract).
-    #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+    #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
     PyroWave(crate::video_pyrowave::PyroWavePlanarFrame),
 }
 
@@ -151,7 +155,7 @@ impl DecodedImage {
             DecodedImage::VkFrame(f) => f.keyframe,
             #[cfg(windows)]
             DecodedImage::D3d11(f) => f.keyframe,
-            #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+            #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
             DecodedImage::PyroWave(f) => f.keyframe,
         }
     }
@@ -167,7 +171,7 @@ impl DecodedImage {
             DecodedImage::VkFrame(f) => (f.width, f.height),
             #[cfg(windows)]
             DecodedImage::D3d11(f) => (f.width, f.height),
-            #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+            #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
             DecodedImage::PyroWave(f) => (f.width, f.height),
         }
     }
@@ -234,9 +238,10 @@ enum Backend {
     #[cfg(windows)]
     D3d11va(crate::video_d3d11::D3d11vaDecoder),
     /// PyroWave (wired-LAN wavelet codec): pyrowave compute on the presenter's device,
-    /// no FFmpeg involvement. No demotion rung — there is no other decoder for it.
+    /// no FFmpeg involvement (Linux + Windows — same Vulkan presenter on both). No demotion
+    /// rung — there is no other decoder for it.
     /// Boxed: the decoder (pinned create-info hold + plane ring) dwarfs the other variants.
-    #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+    #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
     PyroWave(Box<crate::video_pyrowave::PyroWaveDecoder>),
     Software(SoftwareDecoder),
 }
@@ -250,16 +255,42 @@ pub struct Decoder {
     /// (e.g. a reference-missing frame after packet loss) shouldn't cost the whole
     /// session its hardware decoder.
     vaapi_fails: u32,
+    /// When the current error streak started. Demotion needs the streak to be OLD as well
+    /// as long: one startup loss burst produces 3+ consecutive failing AUs within
+    /// milliseconds — demoting on count alone (live-hit: Intel iGPU, 2026-07-19, three
+    /// errors in 20 ms → software forever) never gives the IDR requested on the FIRST
+    /// error (~100–300 ms round trip) a chance to rescue the hardware decoder.
+    first_fail: Option<std::time::Instant>,
     /// 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
     /// keyframe, so a rebuilt/erroring decoder would otherwise stay gray/frozen forever.
     want_keyframe: bool,
+    /// The presenter has the win32 external-memory import path, so D3D11VA frames can reach
+    /// the screen — kept for the mid-session Vulkan→D3D11VA demotion rung (the Windows
+    /// analog of Linux's Vulkan→VAAPI rung).
+    #[cfg(windows)]
+    d3d11_import: bool,
+    /// The presenter adapter's LUID (see [`VulkanDecodeDevice::adapter_luid`]) so a demotion
+    /// rebuild lands on the SAME GPU.
+    #[cfg(windows)]
+    adapter_luid: Option<[u8; 8]>,
+    /// [`VulkanDecodeDevice::d3d11_hdr10`], for the same demotion rebuild.
+    #[cfg(windows)]
+    d3d11_hdr10: bool,
 }
 
-/// Demote VAAPI→software only after this many consecutive hardware decode errors; a lone
-/// transient error just re-requests an IDR and keeps the hardware decoder.
+/// Demote a hardware backend (Vulkan→VAAPI/D3D11VA, VAAPI/D3D11VA→software) only after
+/// this many consecutive decode errors; a lone transient error just re-requests an IDR
+/// and keeps the hardware decoder.
 const VAAPI_DEMOTE_AFTER: u32 = 3;
 
+/// ...AND only when the streak has lasted this long. Every error re-requests an IDR, and
+/// one arriving + decoding resets the streak — so a genuinely broken driver (errors keep
+/// flowing through multiple IDR cycles) still demotes ~a second in, while a burst of
+/// consecutive bad AUs from a single loss event no longer strands the session on
+/// software before the first requested IDR could even arrive.
+const HW_DEMOTE_MIN_STREAK: std::time::Duration = std::time::Duration::from_millis(1000);
+
 /// Map a negotiated `quic` codec bit to the FFmpeg decoder id the client opens.
 pub fn ffmpeg_codec_id(wire: u8) -> ffmpeg::codec::Id {
     match wire {
@@ -292,11 +323,11 @@ pub fn decodable_codecs() -> u8 {
 /// under its explicit opt-in.
 pub fn decodable_codecs_for(vk: Option<&VulkanDecodeDevice>) -> u8 {
     let bits = decodable_codecs();
-    #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+    #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
     if vk.map(|v| v.pyrowave_decode).unwrap_or(false) {
         return bits | punktfunk_core::quic::CODEC_PYROWAVE;
     }
-    #[cfg(not(all(target_os = "linux", feature = "pyrowave")))]
+    #[cfg(not(all(any(target_os = "linux", windows), feature = "pyrowave")))]
     let _ = vk;
     bits
 }
@@ -328,10 +359,12 @@ impl Decoder {
     /// 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.
-    /// Auto's hardware order on Linux depends on the device
-    /// ([`VulkanDecodeDevice::prefer_vulkan_over_vaapi`]): VAAPI → Vulkan → software on
+    /// Auto's hardware order depends on the device on BOTH desktop OSes
+    /// ([`VulkanDecodeDevice::prefer_vulkan_first`]). Linux: VAAPI → Vulkan → software on
     /// desktop Mesa (AMD/Intel), Vulkan → VAAPI → software on NVIDIA and the Deck's
-    /// VanGogh. Windows is Vulkan → D3D11VA → software (no VAAPI there).
+    /// VanGogh. Windows (no VAAPI there): Vulkan → D3D11VA → software on NVIDIA/AMD,
+    /// D3D11VA → Vulkan → software on Intel/unknown (Intel's driver advertises Vulkan
+    /// Video, but FFmpeg-Vulkan on it strobes/overruns the budget — B580 field report).
     pub fn new(
         codec_id: ffmpeg::codec::Id,
         pref: &str,
@@ -343,12 +376,25 @@ impl Decoder {
             .ok()
             .filter(|v| !v.is_empty())
             .unwrap_or_else(|| pref.to_string());
+        #[cfg(windows)]
+        let (d3d11_import, adapter_luid, d3d11_hdr10) = (
+            vk.is_some_and(|v| v.d3d11_import),
+            vk.and_then(|v| v.adapter_luid),
+            vk.is_some_and(|v| v.d3d11_hdr10),
+        );
         let done = |backend| {
             Ok(Decoder {
                 backend,
                 codec_id,
                 vaapi_fails: 0,
+                first_fail: None,
                 want_keyframe: false,
+                #[cfg(windows)]
+                d3d11_import,
+                #[cfg(windows)]
+                adapter_luid,
+                #[cfg(windows)]
+                d3d11_hdr10,
             })
         };
         // Linux `auto`: try VAAPI FIRST unless this device is one where Vulkan Video is
@@ -363,7 +409,7 @@ impl Decoder {
         if matches!(choice.as_str(), "auto" | "" | "hardware")
             && !vk
                 .filter(|v| v.video_decode)
-                .is_some_and(|v| v.prefer_vulkan_over_vaapi())
+                .is_some_and(|v| v.prefer_vulkan_first())
         {
             vaapi_tried = true;
             match VaapiDecoder::new(codec_id) {
@@ -376,6 +422,44 @@ impl Decoder {
                 }
             }
         }
+        // Windows `auto`: D3D11VA FIRST unless this device is one where Vulkan Video is
+        // the established right answer (NVIDIA/AMD). Intel's Windows driver advertises
+        // Vulkan Video (Arc drivers since 2023) so the capability gate alone no longer
+        // keeps Intel off FFmpeg-Vulkan — and that combination is field-broken (B580,
+        // 2026-07: strobing between clean anchors and corrupt inter frames that never
+        // trips the error-streak demotion, 7 ms p50 decodes blowing the 120 Hz budget)
+        // where D3D11VA — the DXVA path every Windows video player exercises, and what
+        // this backend was built for — streams clean. Vulkan stays reachable below by
+        // explicit preference and as auto's fallback when D3D11VA can't be built.
+        #[cfg(windows)]
+        let mut d3d11_tried = false;
+        #[cfg(windows)]
+        if matches!(choice.as_str(), "auto" | "" | "hardware")
+            && !vk
+                .filter(|v| v.video_decode)
+                .is_some_and(|v| v.prefer_vulkan_first())
+        {
+            if let Some(v) = vk.filter(|v| v.d3d11_import) {
+                d3d11_tried = true;
+                match crate::video_d3d11::D3d11vaDecoder::new(
+                    codec_id,
+                    v.adapter_luid,
+                    v.d3d11_hdr10,
+                ) {
+                    Ok(d) => {
+                        tracing::info!(
+                            ?codec_id,
+                            "D3D11VA hardware decode active (shared-texture hand-off)"
+                        );
+                        return done(Backend::D3d11va(d));
+                    }
+                    Err(e) => {
+                        tracing::info!(reason = %format!("{e:#}"),
+                            "D3D11VA unavailable — trying Vulkan Video");
+                    }
+                }
+            }
+        }
         if matches!(choice.as_str(), "auto" | "" | "vulkan" | "hardware") {
             // `video_decode` gates the Vulkan Video attempt: the presenter now exports its
             // handle bundle even when the device has no decode queue (Windows D3D11 interop
@@ -426,14 +510,20 @@ impl Decoder {
                 }
             }
         }
-        // Windows: D3D11VA is the vendor-agnostic DXVA fallback when Vulkan Video isn't
-        // available (Intel's Windows driver foremost) — gated on the presenter having the
-        // win32 external-memory import path, else its frames could never reach the screen.
+        // Windows: D3D11VA as the fallback rung for NVIDIA/AMD auto (Vulkan Video missing
+        // or failed to open) and the explicit `d3d11va` preference — gated on the presenter
+        // having the win32 external-memory import path, else its frames could never reach
+        // the screen. (On Intel/unknown auto it was already tried above — `d3d11_tried`
+        // skips the repeat.)
         #[cfg(windows)]
-        if choice != "software" && choice != "vulkan" {
+        if choice != "software" && choice != "vulkan" && !d3d11_tried {
             match vk.filter(|v| v.d3d11_import) {
                 Some(v) => {
-                    match crate::video_d3d11::D3d11vaDecoder::new(codec_id, v.adapter_luid) {
+                    match crate::video_d3d11::D3d11vaDecoder::new(
+                        codec_id,
+                        v.adapter_luid,
+                        v.d3d11_hdr10,
+                    ) {
                         Ok(d) => {
                             tracing::info!(
                                 ?codec_id,
@@ -483,12 +573,15 @@ impl Decoder {
     /// Open a PyroWave decoder for a `CODEC_PYROWAVE` session (plan §4.5): pyrowave
     /// compute on the presenter's device, no FFmpeg. `codec_id` is irrelevant (kept as
     /// HEVC so an — impossible — demotion path stays well-formed).
-    #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+    #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
     pub fn new_pyrowave(
         vk: &VulkanDecodeDevice,
         width: u32,
         height: u32,
         shard_payload: usize,
+        chroma444: bool,
+        color: ColorDesc,
+        hdr16: bool,
     ) -> Result<Decoder> {
         Ok(Decoder {
             backend: Backend::PyroWave(Box::new(crate::video_pyrowave::PyroWaveDecoder::new(
@@ -496,10 +589,23 @@ impl Decoder {
                 width,
                 height,
                 shard_payload,
+                chroma444,
+                color,
+                hdr16,
             )?)),
             codec_id: ffmpeg::codec::Id::HEVC,
             vaapi_fails: 0,
+            first_fail: None,
             want_keyframe: false,
+            // A PyroWave session never demotes (nothing else decodes it — a failure
+            // renegotiates the codec instead), so the D3D11VA rebuild facts are unused
+            // here; keep them well-formed rather than plumbing them in for nothing.
+            #[cfg(windows)]
+            d3d11_import: false,
+            #[cfg(windows)]
+            adapter_luid: None,
+            #[cfg(windows)]
+            d3d11_hdr10: false,
         })
     }
 
@@ -518,6 +624,7 @@ impl Decoder {
         tracing::warn!("presenter can't display hardware frames — demoting to software decode");
         self.backend = Backend::Software(SoftwareDecoder::new(self.codec_id)?);
         self.vaapi_fails = 0;
+        self.first_fail = None;
         self.want_keyframe = true;
         Ok(())
     }
@@ -542,7 +649,7 @@ impl Decoder {
         au: &[u8],
         // Only the PyroWave backend reads the flags; without that feature the param is unused.
         #[cfg_attr(
-            not(all(target_os = "linux", feature = "pyrowave")),
+            not(all(any(target_os = "linux", windows), feature = "pyrowave")),
             allow(unused_variables)
         )]
         user_flags: u32,
@@ -560,7 +667,7 @@ impl Decoder {
             // No demote ladder below PyroWave (nothing else decodes it): propagate the
             // error; the pump surfaces it and the session falls back to HEVC by
             // renegotiation (plan §4.6), not by decoder swap.
-            #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+            #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
             Backend::PyroWave(p) => {
                 let aligned = user_flags & punktfunk_core::packet::USER_FLAG_CHUNK_ALIGNED != 0;
                 return Ok(p
@@ -572,6 +679,7 @@ impl Decoder {
         match result {
             Ok(f) => {
                 self.vaapi_fails = 0;
+                self.first_fail = None;
                 Ok(f)
             }
             Err(e) => {
@@ -583,7 +691,9 @@ impl Decoder {
                 };
                 self.vaapi_fails += 1;
                 self.want_keyframe = true;
-                if self.vaapi_fails >= VAAPI_DEMOTE_AFTER {
+                let first = *self.first_fail.get_or_insert_with(std::time::Instant::now);
+                if self.vaapi_fails >= VAAPI_DEMOTE_AFTER && first.elapsed() >= HW_DEMOTE_MIN_STREAK
+                {
                     // A failing Vulkan backend still has a hardware rung below it on
                     // Linux — demote to VAAPI first (user-reported: FFmpeg-Vulkan-on-Mesa
                     // error-streaking where VAAPI streams perfectly); only when that
@@ -596,16 +706,39 @@ impl Decoder {
                                     "Vulkan Video decode failing repeatedly — demoting to VAAPI");
                                 self.backend = Backend::Vaapi(v);
                                 self.vaapi_fails = 0;
+                                self.first_fail = None;
                                 return Ok(None);
                             }
                             Err(va) => tracing::info!(reason = %va,
                                 "VAAPI unavailable for demotion — software decode"),
                         }
                     }
+                    // Windows' hardware rung below Vulkan is D3D11VA (a 4K120 stream is
+                    // not survivable on software) — same-GPU rebuild via the stashed LUID.
+                    #[cfg(windows)]
+                    if matches!(self.backend, Backend::Vulkan(_)) && self.d3d11_import {
+                        match crate::video_d3d11::D3d11vaDecoder::new(
+                            self.codec_id,
+                            self.adapter_luid,
+                            self.d3d11_hdr10,
+                        ) {
+                            Ok(d) => {
+                                tracing::warn!(error = %e, fails = self.vaapi_fails,
+                                    "Vulkan Video decode failing repeatedly — demoting to D3D11VA");
+                                self.backend = Backend::D3d11va(d);
+                                self.vaapi_fails = 0;
+                                self.first_fail = None;
+                                return Ok(None);
+                            }
+                            Err(dx) => tracing::info!(reason = %dx,
+                                "D3D11VA unavailable for demotion — software decode"),
+                        }
+                    }
                     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;
+                    self.first_fail = None;
                 } else {
                     tracing::debug!(backend = which, error = %e,
                         "decode error — requesting keyframe, keeping hardware decode");
@@ -712,10 +845,10 @@ pub struct VulkanDecodeDevice {
     pub physical_device: usize,
     pub device: usize,
     /// PCI vendor of the presenter's physical device (0x10DE NVIDIA, 0x1002 AMD,
-    /// 0x8086 Intel) — drives [`Self::prefer_vulkan_over_vaapi`].
+    /// 0x8086 Intel) — drives [`Self::prefer_vulkan_first`].
     pub vendor_id: u32,
     /// The driver's device-name string (e.g. "AMD RADV VANGOGH") — the VanGogh/Deck
-    /// detection for [`Self::prefer_vulkan_over_vaapi`].
+    /// detection for [`Self::prefer_vulkan_first`].
     pub device_name: String,
     /// The presenter's graphics+present family (FFmpeg's "required" tx/comp family too).
     pub graphics_qf: u32,
@@ -758,6 +891,10 @@ pub struct VulkanDecodeDevice {
     /// The presenter enabled `VK_KHR_external_memory_win32` + `VK_KHR_win32_keyed_mutex`:
     /// D3D11 shared-texture frames can reach the screen. Always `false` off Windows.
     pub d3d11_import: bool,
+    /// The presenter can also import the RGB10A2 hand-off texture AND offers an HDR10
+    /// swapchain — the D3D11VA backend emits its HDR (RGB10 PQ pass-through) ring flavor
+    /// for PQ streams instead of tone-mapping to sRGB. Always `false` off Windows.
+    pub d3d11_hdr10: bool,
     /// `VkPhysicalDeviceIDProperties::deviceLUID` when the driver reports one — the D3D11VA
     /// backend creates its decode device on the SAME adapter so shared textures never cross
     /// GPUs. `None` when not reported (or off Windows, where it's unused).
@@ -769,9 +906,11 @@ pub struct VulkanDecodeDevice {
 }
 
 impl VulkanDecodeDevice {
-    /// Should `auto` try Vulkan Video BEFORE VAAPI on this device?
-    ///  * **NVIDIA** — Vulkan is its only hardware path (no usable VAAPI; the
-    ///    nvidia-vaapi-driver is broken for this, Moonlight blacklists it).
+    /// Should `auto` try Vulkan Video BEFORE the platform's other hardware path (VAAPI on
+    /// Linux, D3D11VA on Windows) on this device?
+    ///  * **NVIDIA** — Vulkan Video is the proven path (on Linux the only one: no usable
+    ///    VAAPI — the nvidia-vaapi-driver is broken for this, Moonlight blacklists it;
+    ///    on Windows it's the validated zero-copy default, 4K@144 with 0.1 ms decode).
     ///  * **AMD (RADV, VanGogh included)** — Vulkan decode outperforms VAAPI on RADV
     ///    (on-glass verdict), and on VanGogh VAAPI's separate-plane dmabuf import
     ///    additionally shows chroma fringing; the session binary opts RADV into
@@ -779,10 +918,11 @@ impl VulkanDecodeDevice {
     ///    because a mid-session Vulkan failure streak demotes to VAAPI (not software),
     ///    so a broken Mesa Vulkan path still lands on the working driver.
     ///
-    /// Intel (ANV) and unknown vendors keep the battle-tested zero-copy VAAPI first —
-    /// ANV's Vulkan Video is the least-proven Mesa path and VAAPI is what every other
-    /// Linux client uses there.
-    pub fn prefer_vulkan_over_vaapi(&self) -> bool {
+    /// Intel and unknown vendors take the battle-tested path first: VAAPI on Linux (ANV's
+    /// Vulkan Video is the least-proven Mesa path), D3D11VA on Windows — Intel's Windows
+    /// driver advertises Vulkan Video (Arc drivers since 2023), but FFmpeg-Vulkan on it is
+    /// field-broken (B580, 2026-07: strobing + ~7 ms decodes) where DXVA streams clean.
+    pub fn prefer_vulkan_first(&self) -> bool {
         const VENDOR_NVIDIA: u32 = 0x10DE;
         const VENDOR_AMD: u32 = 0x1002;
         self.vendor_id == VENDOR_NVIDIA || self.vendor_id == VENDOR_AMD
@@ -839,30 +979,33 @@ mod tests {
             pyrowave_decode: false,
             video_decode: true,
             d3d11_import: false,
+            d3d11_hdr10: false,
             adapter_luid: None,
             queue_lock: std::sync::Arc::new(QueueLock::new()),
         }
     }
 
-    /// Auto's Linux hardware order: Vulkan-first on NVIDIA (no usable VAAPI) and ALL AMD
-    /// (Vulkan decode outperforms VAAPI on RADV — on-glass verdict; VanGogh additionally
-    /// chroma-fringes over VAAPI); Intel/unknown keep VAAPI first (ANV's Vulkan Video is
-    /// the least-proven Mesa path). A Vulkan failure streak still demotes to VAAPI, so
-    /// Vulkan-first can never strand a box on software decode.
+    /// Auto's hardware order (both OSes): Vulkan-first on NVIDIA (on Linux: no usable
+    /// VAAPI) and ALL AMD (Vulkan decode outperforms VAAPI on RADV — on-glass verdict;
+    /// VanGogh additionally chroma-fringes over VAAPI); Intel/unknown take the proven
+    /// path first — VAAPI on Linux (ANV's Vulkan Video is the least-proven Mesa path),
+    /// D3D11VA on Windows (Intel's driver advertises Vulkan Video since 2023, but
+    /// FFmpeg-Vulkan on it strobes — B580 field report). A Vulkan failure streak still
+    /// demotes to hardware (VAAPI/D3D11VA), so Vulkan-first can never strand a box on
+    /// software decode.
     #[test]
-    fn vulkan_over_vaapi_on_nvidia_and_amd() {
-        assert!(decode_device(0x10DE, "NVIDIA GeForce RTX 5070 Ti").prefer_vulkan_over_vaapi());
-        assert!(decode_device(0x1002, "AMD RADV VANGOGH").prefer_vulkan_over_vaapi());
+    fn vulkan_first_on_nvidia_and_amd_only() {
+        assert!(decode_device(0x10DE, "NVIDIA GeForce RTX 5070 Ti").prefer_vulkan_first());
+        assert!(decode_device(0x1002, "AMD RADV VANGOGH").prefer_vulkan_first());
+        assert!(decode_device(0x1002, "AMD Custom GPU 0405 (RADV VANGOGH)").prefer_vulkan_first());
+        assert!(decode_device(0x1002, "AMD Radeon RX 7800 XT (RADV NAVI32)").prefer_vulkan_first());
         assert!(
-            decode_device(0x1002, "AMD Custom GPU 0405 (RADV VANGOGH)").prefer_vulkan_over_vaapi()
-        );
-        assert!(
-            decode_device(0x1002, "AMD Radeon RX 7800 XT (RADV NAVI32)").prefer_vulkan_over_vaapi()
-        );
-        assert!(
-            !decode_device(0x8086, "Intel(R) Arc(tm) A770 Graphics (DG2)")
-                .prefer_vulkan_over_vaapi()
+            !decode_device(0x8086, "Intel(R) Arc(tm) A770 Graphics (DG2)").prefer_vulkan_first()
         );
+        // The Windows-side motivation: discrete Arc advertises Vulkan Video and must
+        // still land on D3D11VA in auto.
+        assert!(!decode_device(0x8086, "Intel(R) Arc(TM) B580 Graphics").prefer_vulkan_first());
+        assert!(!decode_device(0x8086, "Intel(R) Arc(TM) Pro Graphics").prefer_vulkan_first());
     }
 
     /// Lock the DRM FourCC magic numbers against typos — these are the exact values

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

@@ -1,6 +1,9 @@
 //! D3D11VA hardware decode (Windows) for the Vulkan presenter — the vendor-agnostic DXVA
-//! path that covers what Vulkan Video can't (Intel's Windows driver foremost, which has no
-//! video-decode queue and previously landed on CPU decode).
+//! path, and auto's FIRST choice on Intel/unknown vendors. Intel's Windows driver DOES
+//! advertise Vulkan Video (Arc drivers since 2023 — don't trust the capability gate to
+//! keep Intel off it), but FFmpeg-Vulkan on it is field-broken (B580, 2026-07: strobing +
+//! ~7 ms decodes) where this path streams clean; on NVIDIA/AMD it is the fallback rung
+//! below Vulkan Video, in `auto` and via mid-session demotion.
 //!
 //! Ported from the retired in-process WinUI presenter's decoder (`clients/windows/src/video.rs`)
 //! with one structural change: that presenter sampled D3D11 textures directly, while ours draws
@@ -24,9 +27,11 @@
 //!   (`VK_KHR_win32_keyed_mutex`); both sides take and release it with **key 0**: a frame the
 //!   presenter drops (arrival-paced, newest wins) is simply never acquired, which a
 //!   key-ping-pong protocol would deadlock on.
-//! * An HDR (PQ/BT.2020) stream is tone-mapped to SDR by the video processor (input colour
-//!   space `G2084_P2020`, output sRGB): correct picture, no HDR presentation on this backend —
-//!   its targets (Intel iGPU laptops) are SDR panels; HDR-first boxes take Vulkan Video.
+//! * An HDR (PQ/BT.2020) stream passes through when the presenter can take it (RGB10A2
+//!   import + an HDR10 swapchain — [`crate::video::VulkanDecodeDevice::d3d11_hdr10`]): the
+//!   video processor converts YCbCr G2084 → RGB G2084 into an RGB10A2 ring, colorspace
+//!   only, no tone mapping. On an SDR-only path it tone-maps to sRGB instead (input
+//!   `G2084_P2020`, output sRGB) — correct picture, no HDR presentation.
 //!
 //! The decode device is created on the **presenter's adapter** (matched by the Vulkan device's
 //! LUID) so the shared textures never cross GPUs on a multi-adapter box.
@@ -37,7 +42,7 @@ use ffmpeg_next as ffmpeg;
 use std::ffi::c_void;
 use std::ptr;
 use windows::core::{Interface, GUID};
-use windows::Win32::Foundation::HANDLE;
+use windows::Win32::Foundation::{HANDLE, RECT};
 use windows::Win32::Graphics::Direct3D::{D3D_FEATURE_LEVEL_11_0, D3D_FEATURE_LEVEL_11_1};
 use windows::Win32::Graphics::Direct3D11::{
     D3D11CreateDevice, ID3D11Device, ID3D11DeviceContext, ID3D11Multithread, ID3D11Texture2D,
@@ -52,11 +57,12 @@ use windows::Win32::Graphics::Direct3D11::{
     D3D11_VPOV_DIMENSION_TEXTURE2D,
 };
 use windows::Win32::Graphics::Dxgi::Common::{
-    DXGI_COLOR_SPACE_RGB_FULL_G22_NONE_P709, DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020,
-    DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P601, DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P709,
-    DXGI_COLOR_SPACE_YCBCR_STUDIO_G2084_LEFT_P2020, DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P2020,
-    DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P601, DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P709,
-    DXGI_FORMAT, DXGI_FORMAT_B8G8R8A8_UNORM, DXGI_FORMAT_NV12, DXGI_FORMAT_P010, DXGI_RATIONAL,
+    DXGI_COLOR_SPACE_RGB_FULL_G2084_NONE_P2020, DXGI_COLOR_SPACE_RGB_FULL_G22_NONE_P709,
+    DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020, DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P601,
+    DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P709, DXGI_COLOR_SPACE_YCBCR_STUDIO_G2084_LEFT_P2020,
+    DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P2020, DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P601,
+    DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P709, DXGI_FORMAT, DXGI_FORMAT_B8G8R8A8_UNORM,
+    DXGI_FORMAT_NV12, DXGI_FORMAT_P010, DXGI_FORMAT_R10G10B10A2_UNORM, DXGI_RATIONAL,
     DXGI_SAMPLE_DESC,
 };
 use windows::Win32::Graphics::Dxgi::{
@@ -95,10 +101,14 @@ const PROFILE_AV1_VLD_PROFILE0: GUID = GUID::from_u128(0xb8be4ccb_cf53_46ba_8d59
 pub struct D3d11Frame {
     pub width: u32,
     pub height: u32,
-    /// What the ring slot actually CONTAINS after the video processor's conversion: sRGB
-    /// BT.709 full-range RGB — regardless of the stream's own CICP (a PQ stream was
-    /// tone-mapped). The presenter keys SDR/HDR handling off this, so it always reads SDR.
+    /// What the ring slot actually CONTAINS after the video processor's conversion:
+    /// sRGB BT.709 full-range RGB normally (a PQ stream was tone-mapped), or PQ BT.2020
+    /// full-range RGB when the HDR pass-through ring is active (`rgb10`) — the presenter
+    /// keys its SDR/HDR handling off this.
     pub color: ColorDesc,
+    /// The ring slot's texture format: `false` = BGRA8, `true` = RGB10A2 (the HDR PQ
+    /// pass-through flavor) — the presenter's Vulkan import must match it exactly.
+    pub rgb10: bool,
     /// Intra keyframe (IDR/I) — the pump's post-loss re-anchor signal. See
     /// `crate::video::VkVideoFrame`.
     pub keyframe: bool,
@@ -331,6 +341,9 @@ struct SharedRing {
     height: u32,
     next: usize,
     generation: u32,
+    /// HDR flavor: RGB10A2 slots the processor fills with PQ BT.2020 RGB (colorspace
+    /// conversion only — both sides G2084, no tone mapping). `false` = BGRA8 sRGB.
+    pq_out: bool,
 }
 
 impl SharedRing {
@@ -340,6 +353,7 @@ impl SharedRing {
         width: u32,
         height: u32,
         generation: u32,
+        pq_out: bool,
     ) -> Result<SharedRing> {
         // The video processor: NV12/P010 in, BGRA8 out, 1:1 (no scaling — the Vulkan side
         // scales at composite time like every other path). Frame rates are advisory.
@@ -369,10 +383,15 @@ impl SharedRing {
             Height: height,
             MipLevels: 1,
             ArraySize: 1,
-            // Single-plane BGRA8: the ONLY hand-off format whose Vulkan import is a
+            // Single-plane RGB: the ONLY hand-off family whose Vulkan import is a
             // universally exercised driver path (see the module docs — NV12 import TDRs
-            // on NVIDIA despite being advertised).
-            Format: DXGI_FORMAT_B8G8R8A8_UNORM,
+            // on NVIDIA despite being advertised). RGB10A2 for the HDR pass-through
+            // flavor (gated on the presenter's probe), BGRA8 otherwise.
+            Format: if pq_out {
+                DXGI_FORMAT_R10G10B10A2_UNORM
+            } else {
+                DXGI_FORMAT_B8G8R8A8_UNORM
+            },
             SampleDesc: DXGI_SAMPLE_DESC {
                 Count: 1,
                 Quality: 0,
@@ -430,7 +449,8 @@ impl SharedRing {
             height,
             slots = RING_SLOTS,
             generation,
-            "D3D11 shared hand-off ring built (VideoProcessor → BGRA8)"
+            hdr = pq_out,
+            "D3D11 shared hand-off ring built (VideoProcessor → RGB)"
         );
         Ok(SharedRing {
             slots,
@@ -440,6 +460,7 @@ impl SharedRing {
             height,
             next: 0,
             generation,
+            pq_out,
         })
     }
 }
@@ -457,6 +478,10 @@ pub(crate) struct D3d11vaDecoder {
     /// setters (Win10 1703+, universally present — init fails to software without it).
     video_context1: ID3D11VideoContext1,
     ring: Option<SharedRing>,
+    /// The presenter can import RGB10A2 AND offers an HDR10 swapchain
+    /// ([`crate::video::VulkanDecodeDevice::d3d11_hdr10`]) — PQ streams get the HDR
+    /// pass-through ring; without it they keep the tonemap-to-sRGB ring.
+    hdr10_out: bool,
 }
 
 // Single-owner pointers + COM interfaces, only touched from the session pump thread (the
@@ -467,6 +492,7 @@ impl D3d11vaDecoder {
     pub(crate) fn new(
         codec_id: ffmpeg::codec::Id,
         luid: Option<[u8; 8]>,
+        hdr10_out: bool,
     ) -> Result<D3d11vaDecoder> {
         use ffmpeg::ffi;
         let (device, context) = create_device(luid)?;
@@ -537,6 +563,7 @@ impl D3d11vaDecoder {
                 video_device,
                 video_context1,
                 ring: None,
+                hdr10_out,
             })
         }
     }
@@ -591,12 +618,15 @@ impl D3d11vaDecoder {
             let video_device = self.video_device.clone();
             let video_context1 = self.video_context1.clone();
             let context = self.context.clone();
-            // (Re)build the ring + video processor on first use or a stream size change (the
-            // hand-off is BGRA8 regardless of the stream's bit depth, so depth never rebuilds).
+            // (Re)build the ring + video processor on first use, a stream size change, or a
+            // flavor change (the host flips PQ in-band; SDR↔HDR swaps the slot format, so
+            // it rebuilds like a resize — bit DEPTH alone still never rebuilds: an SDR
+            // 10-bit stream and an 8-bit one share the same output flavor).
+            let pq_out = self.hdr10_out && color.is_pq();
             let rebuild = self
                 .ring
                 .as_ref()
-                .is_none_or(|r| r.width != width || r.height != height);
+                .is_none_or(|r| r.width != width || r.height != height || r.pq_out != pq_out);
             if rebuild {
                 let generation = self.ring.as_ref().map_or(0, |r| r.generation + 1);
                 self.ring = Some(SharedRing::build(
@@ -605,6 +635,7 @@ impl D3d11vaDecoder {
                     width,
                     height,
                     generation,
+                    pq_out,
                 )?);
             }
             let ring = self.ring.as_mut().expect("ring built above");
@@ -647,10 +678,36 @@ impl D3d11vaDecoder {
                 (_, _, true) => DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P709,
                 _ => DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P709,
             };
+            // The DECODE surface is DXVA-aligned (height rounded up to the profile's
+            // macroblock/tile alignment — 128 for HEVC/AV1), so it is TALLER than the
+            // frame: a 2400-line stream decodes into a 2432-line texture. Without an
+            // explicit source rect the processor blits the WHOLE surface — the padding
+            // rows (uninitialized NV12: Y=0,U=V=0, which converts to vivid green) land at
+            // the bottom of the output and the picture is squashed to fit. Clamp the
+            // source to the real frame; the dest stays the whole (frame-sized) slot.
+            // Live-hit on Intel 3840x2400 as a ~32 px green bar (2026-07-19).
+            video_context1.VideoProcessorSetStreamSourceRect(
+                &ring.vp,
+                0,
+                true,
+                Some(&RECT {
+                    left: 0,
+                    top: 0,
+                    right: width as i32,
+                    bottom: height as i32,
+                }),
+            );
             video_context1.VideoProcessorSetStreamColorSpace1(&ring.vp, 0, in_cs);
             video_context1.VideoProcessorSetOutputColorSpace1(
                 &ring.vp,
-                DXGI_COLOR_SPACE_RGB_FULL_G22_NONE_P709,
+                // HDR ring: PQ in, PQ out — a pure colorspace conversion (YCbCr→RGB),
+                // no tone mapping; the presenter passes the values through to its HDR10
+                // swapchain. SDR ring: sRGB out (a PQ stream is tone-mapped here).
+                if ring.pq_out {
+                    DXGI_COLOR_SPACE_RGB_FULL_G2084_NONE_P2020
+                } else {
+                    DXGI_COLOR_SPACE_RGB_FULL_G22_NONE_P709
+                },
             );
 
             let stream = D3D11_VIDEO_PROCESSOR_STREAM {
@@ -684,17 +741,38 @@ impl D3d11vaDecoder {
             // completion, and an unflushed deferred batch would add a driver-decided delay.
             context.Flush();
 
-            log_layout_once(width, height, index, color.is_pq());
+            let mut src_desc = D3D11_TEXTURE2D_DESC::default();
+            src.GetDesc(&mut src_desc);
+            log_layout_once(
+                width,
+                height,
+                src_desc.Width,
+                src_desc.Height,
+                index,
+                color.is_pq(),
+            );
             Ok(D3d11Frame {
                 width,
                 height,
-                // What the slot now CONTAINS: sRGB BT.709 full-range RGB (PQ was tone-mapped).
-                color: ColorDesc {
-                    primaries: 1,
-                    transfer: 13, // sRGB (H.273)
-                    matrix: 0,    // identity — RGB
-                    full_range: true,
+                // What the slot now CONTAINS. HDR ring: PQ BT.2020 full-range RGB (the
+                // presenter reads is_pq() and flips its HDR10 swapchain). SDR ring: sRGB
+                // BT.709 full-range RGB (PQ was tone-mapped above).
+                color: if ring.pq_out {
+                    ColorDesc {
+                        primaries: 9,
+                        transfer: 16, // PQ / SMPTE ST.2084
+                        matrix: 0,    // identity — RGB
+                        full_range: true,
+                    }
+                } else {
+                    ColorDesc {
+                        primaries: 1,
+                        transfer: 13, // sRGB (H.273)
+                        matrix: 0,    // identity — RGB
+                        full_range: true,
+                    }
                 },
+                rgb10: ring.pq_out,
                 // SAFETY: `self.frame` is the live decoded AVFrame for this call.
                 keyframe: crate::video::frame_is_keyframe(self.frame),
                 handle,
@@ -720,10 +798,20 @@ impl Drop for D3d11vaDecoder {
 }
 
 /// One-time dump of the first decoded surface's layout — the forensics for a new GPU/driver.
-fn log_layout_once(width: u32, height: u32, index: u32, pq: bool) {
+/// `tex_*` is the DXVA-aligned decode surface (>= the frame); the gap is the padding the
+/// stream source rect excludes.
+fn log_layout_once(width: u32, height: u32, tex_w: u32, tex_h: u32, index: u32, pq: bool) {
     use std::sync::atomic::{AtomicBool, Ordering};
     static ONCE: AtomicBool = AtomicBool::new(true);
     if ONCE.swap(false, Ordering::Relaxed) {
-        tracing::info!(width, height, slice = index, pq, "D3D11VA first frame");
+        tracing::info!(
+            width,
+            height,
+            tex_w,
+            tex_h,
+            slice = index,
+            pq,
+            "D3D11VA first frame"
+        );
     }
 }

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

@@ -258,11 +258,12 @@ unsafe fn make_plane(
     mem_props: &vk::PhysicalDeviceMemoryProperties,
     w: u32,
     h: u32,
+    fmt: vk::Format,
 ) -> Result<(vk::Image, vk::DeviceMemory, vk::ImageView)> {
     let img = device.create_image(
         &vk::ImageCreateInfo::default()
             .image_type(vk::ImageType::TYPE_2D)
-            .format(vk::Format::R8_UNORM)
+            .format(fmt)
             .extent(vk::Extent3D {
                 width: w,
                 height: h,
@@ -306,7 +307,7 @@ unsafe fn make_plane(
         &vk::ImageViewCreateInfo::default()
             .image(img)
             .view_type(vk::ImageViewType::TYPE_2D)
-            .format(vk::Format::R8_UNORM)
+            .format(fmt)
             .subresource_range(vk::ImageSubresourceRange {
                 aspect_mask: vk::ImageAspectFlags::COLOR,
                 base_mip_level: 0,
@@ -347,12 +348,21 @@ unsafe fn build_ring(
     mem_props: &vk::PhysicalDeviceMemoryProperties,
     width: u32,
     height: u32,
+    chroma444: bool,
+    fmt: vk::Format,
 ) -> Result<Vec<PlaneSet>> {
+    // 4:2:0 = half-res chroma; 4:4:4 = full-res. The presenter's planar CSC samples with
+    // normalized UVs, so the chroma plane resolution is transparent to it.
+    let (cw, ch) = if chroma444 {
+        (width, height)
+    } else {
+        (width / 2, height / 2)
+    };
     let mut ring: Vec<PlaneSet> = Vec::with_capacity(RING);
     for _ in 0..RING {
         let built = (|| -> Result<PlaneSet> {
-            let (y, ym, yv) = make_plane(device, mem_props, width, height)?;
-            let (cb, cbm, cbv) = match make_plane(device, mem_props, width / 2, height / 2) {
+            let (y, ym, yv) = make_plane(device, mem_props, width, height, fmt)?;
+            let (cb, cbm, cbv) = match make_plane(device, mem_props, cw, ch, fmt) {
                 Ok(p) => p,
                 Err(e) => {
                     device.destroy_image_view(yv, None);
@@ -361,7 +371,7 @@ unsafe fn build_ring(
                     return Err(e);
                 }
             };
-            let (cr, crm, crv) = match make_plane(device, mem_props, width / 2, height / 2) {
+            let (cr, crm, crv) = match make_plane(device, mem_props, cw, ch, fmt) {
                 Ok(p) => p,
                 Err(e) => {
                     for (v, i, m) in [(yv, y, ym), (cbv, cb, cbm)] {
@@ -409,6 +419,16 @@ pub struct PyroWaveDecoder {
     mem_props: vk::PhysicalDeviceMemoryProperties,
     width: u32,
     height: u32,
+    /// Session-fixed negotiated chroma ([`Welcome::chroma_format`]): 4:4:4 = full-res
+    /// chroma planes + `Chroma444` pyrowave decoders (the seq-header bit is
+    /// decoder-enforced upstream, so a mismatch fails loudly, never silently).
+    chroma444: bool,
+    /// Session colour signalling ([`Welcome::color`]): the wavelet bitstream has no VUI,
+    /// so the negotiated `ColorInfo` is the contract the presenter CSC configures from.
+    color: ColorDesc,
+    /// Session-fixed negotiated depth ≥10: the planes are `R16_UNORM` carrying the host's
+    /// P010-style studio codes (the presenter samples them with depth-10 MSB-packed rows).
+    hdr16: bool,
     /// The wire shard payload — the parse-window size for chunk-aligned AUs (§4.4): each
     /// window holds whole self-delimiting codec packets, zero-padded to the window.
     wire_window: usize,
@@ -424,17 +444,20 @@ impl PyroWaveDecoder {
         width: u32,
         height: u32,
         shard_payload: usize,
+        chroma444: bool,
+        color: ColorDesc,
+        hdr16: bool,
     ) -> Result<PyroWaveDecoder> {
         if !vkd.pyrowave_decode {
             bail!("presenter device lacks the PyroWave compute feature set");
         }
-        if width % 2 != 0 || height % 2 != 0 {
+        if !chroma444 && (width % 2 != 0 || height % 2 != 0) {
             bail!("pyrowave 4:2:0 needs even dimensions (got {width}x{height})");
         }
         // SAFETY: the handles in `vkd` are the presenter's live instance/device (it
         // outlives the decoder — same contract the FFmpeg Vulkan backend relies on);
         // `Hold` pins the reconstructed create-infos for the pyrowave device's lifetime.
-        unsafe { Self::new_inner(vkd, width, height, shard_payload) }
+        unsafe { Self::new_inner(vkd, width, height, shard_payload, chroma444, color, hdr16) }
     }
 
     unsafe fn new_inner(
@@ -442,6 +465,9 @@ impl PyroWaveDecoder {
         width: u32,
         height: u32,
         shard_payload: usize,
+        chroma444: bool,
+        color: ColorDesc,
+        hdr16: bool,
     ) -> Result<PyroWaveDecoder> {
         let static_fn = ash::StaticFn {
             get_instance_proc_addr: std::mem::transmute::<usize, vk::PFN_vkGetInstanceProcAddr>(
@@ -496,7 +522,11 @@ impl PyroWaveDecoder {
             device: pw_dev,
             width: width as i32,
             height: height as i32,
-            chroma: pw::pyrowave_chroma_subsampling_PYROWAVE_CHROMA_SUBSAMPLING_420,
+            chroma: if chroma444 {
+                pw::pyrowave_chroma_subsampling_PYROWAVE_CHROMA_SUBSAMPLING_444
+            } else {
+                pw::pyrowave_chroma_subsampling_PYROWAVE_CHROMA_SUBSAMPLING_420
+            },
             // The fragment-iDWT path is for Mali/Adreno-class mobile GPUs only.
             fragment_path: false,
         };
@@ -513,7 +543,27 @@ impl PyroWaveDecoder {
         let mem_props = instance.get_physical_device_memory_properties(
             vk::PhysicalDevice::from_raw(vkd.physical_device as u64),
         );
-        let ring = match build_ring(&device, &mem_props, width, height) {
+        // 16-bit sessions decode into R16_UNORM storage planes; STORAGE_IMAGE support for
+        // R16_UNORM is optional in Vulkan (universal on desktop) — probe it so an exotic
+        // device fails with a clear message instead of a validation error.
+        let plane_fmt = if hdr16 {
+            let props = instance.get_physical_device_format_properties(
+                vk::PhysicalDevice::from_raw(vkd.physical_device as u64),
+                vk::Format::R16_UNORM,
+            );
+            if !props
+                .optimal_tiling_features
+                .contains(vk::FormatFeatureFlags::STORAGE_IMAGE)
+            {
+                pw::pyrowave_decoder_destroy(pw_dec);
+                pw::pyrowave_device_destroy(pw_dev);
+                bail!("this GPU lacks R16_UNORM STORAGE_IMAGE — cannot decode a 10-bit PyroWave session");
+            }
+            vk::Format::R16_UNORM
+        } else {
+            vk::Format::R8_UNORM
+        };
+        let ring = match build_ring(&device, &mem_props, width, height, chroma444, plane_fmt) {
             Ok(r) => r,
             Err(e) => {
                 pw::pyrowave_decoder_destroy(pw_dec);
@@ -557,6 +607,9 @@ impl PyroWaveDecoder {
             mem_props,
             width,
             height,
+            chroma444,
+            color,
+            hdr16,
             wire_window: shard_payload.max(64),
         })
     }
@@ -569,14 +622,19 @@ impl PyroWaveDecoder {
     /// The old ring is RETIRED, not destroyed: the presenter / frame channel may still
     /// reference its views (see [`RETIRE_HANDOVERS`]).
     unsafe fn reconfigure(&mut self, width: u32, height: u32) -> Result<()> {
-        if width % 2 != 0 || height % 2 != 0 {
+        if !self.chroma444 && (width % 2 != 0 || height % 2 != 0) {
             bail!("pyrowave 4:2:0 needs even dimensions (resize to {width}x{height})");
         }
         let dinfo = pw::pyrowave_decoder_create_info {
             device: self.pw_dev,
             width: width as i32,
             height: height as i32,
-            chroma: pw::pyrowave_chroma_subsampling_PYROWAVE_CHROMA_SUBSAMPLING_420,
+            // Chroma is session-fixed (negotiated); a resize never changes it.
+            chroma: if self.chroma444 {
+                pw::pyrowave_chroma_subsampling_PYROWAVE_CHROMA_SUBSAMPLING_444
+            } else {
+                pw::pyrowave_chroma_subsampling_PYROWAVE_CHROMA_SUBSAMPLING_420
+            },
             fragment_path: false,
         };
         let mut new_dec: pw::pyrowave_decoder = std::ptr::null_mut();
@@ -584,7 +642,18 @@ impl PyroWaveDecoder {
             pw::pyrowave_decoder_create(&dinfo, &mut new_dec),
             "decoder_create (mid-stream resize)",
         )?;
-        let new_ring = match build_ring(&self.device, &self.mem_props, width, height) {
+        let new_ring = match build_ring(
+            &self.device,
+            &self.mem_props,
+            width,
+            height,
+            self.chroma444,
+            if self.hdr16 {
+                vk::Format::R16_UNORM
+            } else {
+                vk::Format::R8_UNORM
+            },
+        ) {
             Ok(r) => r,
             Err(e) => {
                 pw::pyrowave_decoder_destroy(new_dec);
@@ -886,15 +955,10 @@ impl PyroWaveDecoder {
             ],
             width: w,
             height: h,
-            // No VUI in the bitstream: BT.709 limited is the fixed contract with the
-            // host's CSC (plan §4.7 CscRows note; sequence-header signaling is a
-            // follow-up once the C API exposes it).
-            color: ColorDesc {
-                primaries: 1,
-                transfer: 1,
-                matrix: 1,
-                full_range: false,
-            },
+            // No VUI in the bitstream: the negotiated Welcome `ColorInfo` is the contract
+            // with the host's CSC (BT.709 limited for SDR sessions; BT.2020 PQ once the
+            // HDR leg lands — design/pyrowave-444-hdr.md).
+            color: self.color,
             keyframe: true,
         }))
     }

crates/pf-clipboard/Cargo.toml

@@ -7,7 +7,7 @@
 # `start`), so it stays free of platform cfg.
 [package]
 name = "pf-clipboard"
-version = "0.12.0"
+version.workspace = true
 edition = "2021"
 rust-version.workspace = true
 license = "MIT OR Apache-2.0"

crates/pf-encode/Cargo.toml

@@ -53,15 +53,23 @@ ffmpeg-next = { version = "8", optional = true }
 libloading = "0.8"
 # Native Intel QSV (VPL): vendored static MIT dispatcher + bindgen'd C API, only under `qsv`.
 libvpl-sys = { path = "../libvpl-sys", optional = true }
+# PyroWave (opt-in wired-LAN wavelet codec) — vendored codec + bindgen'd C API, only under
+# `pyrowave`. The Windows backend is the NV12 zero-copy D3D11→Vulkan encoder; same crate as Linux.
+pyrowave-sys = { path = "../pyrowave-sys", optional = true }
 windows = { version = "0.62", features = [
     "Win32_Foundation",
     "Win32_Graphics_Direct3D",
     "Win32_Graphics_Direct3D11",
     "Win32_Graphics_Dxgi",
     "Win32_Graphics_Dxgi_Common",
+    # SECURITY_ATTRIBUTES — the PyroWave backend's IDXGIResource1::CreateSharedHandle signature.
+    "Win32_Security",
     "Win32_Storage_FileSystem",
     "Win32_System_LibraryLoader",
     "Win32_System_Threading",
+    # D3DKMTSetProcessSchedulingPriorityClass — raise the host's WDDM GPU scheduling priority
+    # above a running game so PyroWave's compute-shader encode isn't starved (enc/windows/pyrowave.rs).
+    "Wdk_Graphics_Direct3D",
 ] }
 
 [features]

crates/pf-encode/src/enc/codec.rs

@@ -104,13 +104,14 @@ impl Codec {
         }
     }
 
-    /// Whether this codec has a negotiable **10-bit** encode path (HEVC Main10 / AV1 10-bit).
-    /// H.264 is always 8-bit (High10 is neither an NVENC nor a VCN encode mode — negotiation
-    /// never asks), and PyroWave's wavelet path ingests 8-bit. `true` here is only the
+    /// Whether this codec has a negotiable **10-bit** encode path (HEVC Main10 / AV1 10-bit;
+    /// PyroWave rides 16-bit UNORM planes carrying P010-style studio codes — the wavelet is
+    /// depth-agnostic, design/pyrowave-444-hdr.md). H.264 is always 8-bit (High10 is neither an
+    /// NVENC nor a VCN encode mode — negotiation never asks). `true` here is only the
     /// *codec-level* gate: the active GPU/backend must still pass
     /// [`can_encode_10bit`](crate::can_encode_10bit) before the host negotiates 10-bit.
     pub fn supports_10bit(self) -> bool {
-        matches!(self, Codec::H265 | Codec::Av1)
+        matches!(self, Codec::H265 | Codec::Av1 | Codec::PyroWave)
     }
 
     /// The FFmpeg NVENC encoder name (selected by name, not codec id — the latter would

crates/pf-encode/src/enc/linux/mod.rs

@@ -27,8 +27,8 @@ use super::libav::{
 use ffmpeg::ffi; // = ffmpeg_sys_next
 
 /// The swscale *source* pixel format for a captured packed RGB/BGR layout (the real byte order, not
-/// the NVENC-padded `*0` form). Used by the 4:4:4 RGB→YUV444P conversion path. Mirrors the VAAPI
-/// CPU-input mapping; YUV/10-bit inputs can't feed this path (the 4:4:4 session forces packed RGB).
+/// the NVENC-padded `*0` form). Used by the CPU conversion paths: 4:4:4 RGB→YUV444P, and HDR
+/// X2RGB10/X2BGR10→P010. Mirrors the VAAPI CPU-input mapping; YUV inputs can't feed this path.
 fn sws_src_pixel(format: PixelFormat) -> Result<Pixel> {
     Ok(match format {
         PixelFormat::Bgrx => Pixel::BGRZ, // bgr0
@@ -37,8 +37,12 @@ fn sws_src_pixel(format: PixelFormat) -> Result<Pixel> {
         PixelFormat::Rgba => Pixel::RGBA,
         PixelFormat::Rgb => Pixel::RGB24,
         PixelFormat::Bgr => Pixel::BGR24,
+        // The GNOME 50+ HDR capture formats (PQ/BT.2020 packed 2:10:10:10) — the HDR CPU path's
+        // swscale source for the X2RGB10→P010 conversion.
+        PixelFormat::X2Rgb10 => Pixel::X2RGB10LE,
+        PixelFormat::X2Bgr10 => Pixel::X2BGR10LE,
         PixelFormat::Nv12 | PixelFormat::P010 | PixelFormat::Rgb10a2 | PixelFormat::Yuv444 => {
-            bail!("NVENC 4:4:4 CPU-input path supports packed RGB/BGR only; got {format:?}")
+            bail!("NVENC CPU-input conversion supports packed RGB/BGR only; got {format:?}")
         }
     })
 }
@@ -136,6 +140,9 @@ fn nvenc_input(format: PixelFormat) -> (Pixel, bool) {
         // the Windows paths; the Linux capturer never emits them. Map to BGRA so the match is
         // exhaustive — unreachable here.
         PixelFormat::Rgb10a2 | PixelFormat::P010 => (Pixel::BGRA, false),
+        // The Linux HDR capture formats never take the RGB-passthrough input: `open` intercepts
+        // them onto the X2RGB10→P010 swscale path before consulting this mapping (like 4:4:4).
+        PixelFormat::X2Rgb10 | PixelFormat::X2Bgr10 => (Pixel::BGRA, false),
     }
 }
 
@@ -164,11 +171,12 @@ pub struct NvencEncoder {
     frame: Option<VideoFrame>,
     /// Zero-copy path: CUDA hwdevice/hwframes contexts (the encoder takes `AV_PIX_FMT_CUDA`).
     cuda: Option<CudaHw>,
-    /// 4:4:4 CPU path only: swscale context converting the captured packed RGB/BGR → planar
-    /// YUV444P into [`Self::frame`], because `hevc_nvenc` only emits 4:4:4 from a YUV444 *input*
-    /// (RGB-in is always 4:2:0). `None` on the 4:2:0 paths AND on the zero-copy 4:4:4 path (the
-    /// worker's GPU convert delivers YUV444 CUDA frames). Freed in `Drop`.
-    sws_444: Option<*mut ffi::SwsContext>,
+    /// CPU CSC paths only: swscale context converting the captured packed source into
+    /// [`Self::frame`] — RGB/BGR → planar YUV444P for a 4:4:4 session (`hevc_nvenc` only emits
+    /// 4:4:4 from a YUV444 *input*; RGB-in is always 4:2:0), or X2RGB10/X2BGR10 → P010 (BT.2020
+    /// limited) for an HDR session. `None` on the plain RGB paths AND on the zero-copy paths (the
+    /// worker's GPU convert delivers ready CUDA frames). Freed in `Drop`.
+    sws_csc: Option<*mut ffi::SwsContext>,
     /// This session opened as full-chroma 4:4:4 (FREXT) — via either input path.
     want_444: bool,
     src_format: PixelFormat,
@@ -191,7 +199,7 @@ pub struct NvencEncoder {
     args: OpenArgs,
 }
 
-// `CudaHw` holds raw `AVBufferRef`s and `sws_444` a raw `SwsContext`; the encoder lives on a single
+// `CudaHw` holds raw `AVBufferRef`s and `sws_csc` a raw `SwsContext`; the encoder lives on a single
 // thread. The CPU encoder is already `Send` via ffmpeg-next; assert it for the raw fields too.
 // SAFETY: `NvencEncoder` owns an ffmpeg-next `Encoder`/`VideoFrame` (already `Send`) plus a `CudaHw`
 // holding raw `AVBufferRef`s and an optional raw `SwsContext`, none of which are `Send` by default.
@@ -247,14 +255,27 @@ impl NvencEncoder {
         bit_depth: u8,
         chroma: ChromaFormat,
     ) -> Result<Self> {
-        // TODO(hdr): Linux 10-bit parity. Unlike the Windows raw-SDK path (which upconverts 8-bit
-        // ARGB → Main10 via pixelBitDepthMinus8), libavcodec hevc_nvenc needs a 10-bit input pixel
-        // format (p010) for Main10, so it's a bigger change; deferred until a Linux GPU box is
-        // available to validate. The Linux host stays 8-bit for now.
-        if bit_depth != 8 {
+        // HDR / 10-bit (GNOME 50+ HDR screencast): a 10-bit session whose capture negotiated a
+        // packed 2:10:10:10 PQ/BT.2020 format (`X2Rgb10`/`X2Bgr10`) encodes HEVC Main10 / 10-bit
+        // AV1 from a P010 input frame we produce by swscale (BT.2020 limited; the PQ transfer
+        // rides through per-channel — BT.2020 NCL Y'CbCr *is* derived from the PQ-encoded R'G'B').
+        // A 10-bit request whose capture stayed SDR (HDR offer downgraded) honestly encodes 8-bit.
+        let want_hdr10 = bit_depth == 10 && format.is_hdr_rgb10() && codec.supports_10bit();
+        if bit_depth == 10 && !want_hdr10 {
             tracing::warn!(
                 bit_depth,
-                "Linux NVENC 10-bit not yet wired — encoding 8-bit"
+                ?format,
+                codec = codec.nvenc_name(),
+                "10-bit requested but the capture format/codec has no 10-bit path — encoding 8-bit"
+            );
+        }
+        if format.is_hdr_rgb10() && !want_hdr10 {
+            // A 10-bit PQ capture on an 8-bit session would be encoded with a BT.709 VUI and
+            // garbage bit-packing — never silently; the session must renegotiate.
+            bail!(
+                "captured 10-bit HDR frames ({format:?}) on an 8-bit/{} session — refusing to \
+                 mislabel PQ content",
+                codec.nvenc_name()
             );
         }
         // Full-chroma 4:4:4 (HEVC Range Extensions). `hevc_nvenc` only emits 4:4:4 from a YUV444
@@ -263,6 +284,11 @@ impl NvencEncoder {
         // (planar-YUV444 CUDA frames — `cuda` true), or the CPU path's swscale RGB→YUV444P. Both
         // feed `profile=rext`; the range follows `PUNKTFUNK_444_FULLRANGE` in both.
         let want_444 = chroma.is_444() && codec == Codec::H265;
+        if want_444 && want_hdr10 {
+            // The handshake resolves 4:4:4∧10-bit down to 8-bit on Linux, so this can't happen —
+            // fail loudly if it ever does rather than picking one silently.
+            bail!("4:4:4 + 10-bit HDR is not a supported Linux NVENC combination");
+        }
         ffmpeg::init().context("ffmpeg init")?;
         if std::env::var_os("PUNKTFUNK_FFMPEG_DEBUG").is_some() {
             // SAFETY: `av_log_set_level` sets libav's global integer log level; `48` (= AV_LOG_DEBUG)
@@ -274,10 +300,13 @@ impl NvencEncoder {
         let av_codec = encoder::find_by_name(name)
             .ok_or_else(|| anyhow!("{name} not built into libavcodec"))?;
         let (rgb_pixel, rgb_expand) = nvenc_input(format);
-        // 4:4:4 feeds NVENC a planar YUV444P frame we produce by swscale; the ordinary path feeds the
-        // captured RGB straight in and lets NVENC's internal CSC subsample to 4:2:0.
+        // 4:4:4 feeds NVENC a planar YUV444P frame we produce by swscale; HDR feeds it a P010
+        // frame likewise; the ordinary path feeds the captured RGB straight in and lets NVENC's
+        // internal CSC subsample to 4:2:0.
         let (nvenc_pixel, expand) = if want_444 {
             (Pixel::YUV444P, false)
+        } else if want_hdr10 {
+            (Pixel::P010LE, false)
         } else {
             (rgb_pixel, rgb_expand)
         };
@@ -325,7 +354,21 @@ impl NvencEncoder {
         // visible win. Linux-only: the Windows path's NVENC-internal CSC range is unmeasured.
         let full_range_444 =
             want_444 && std::env::var("PUNKTFUNK_444_FULLRANGE").is_ok_and(|v| v.trim() == "1");
-        if matches!(format, PixelFormat::Nv12) || want_444 {
+        if want_hdr10 {
+            // HDR10: BT.2020 primaries + SMPTE-2084 (PQ) transfer, limited range — matches the
+            // swscale BT.2020 CSC below and the Windows paths' signalling. The client decoder
+            // auto-detects PQ from the VUI; static mastering metadata rides out-of-band.
+            // SAFETY: `raw = video.as_mut_ptr()` is the non-null, properly-aligned, sole-owned,
+            // not-yet-opened `AVCodecContext`; we set its four VUI colour enum fields to valid
+            // variants before `open_with`. Sole owner → no aliasing; synchronous writes.
+            unsafe {
+                let raw = video.as_mut_ptr();
+                (*raw).colorspace = ffi::AVColorSpace::AVCOL_SPC_BT2020_NCL;
+                (*raw).color_range = ffi::AVColorRange::AVCOL_RANGE_MPEG;
+                (*raw).color_primaries = ffi::AVColorPrimaries::AVCOL_PRI_BT2020;
+                (*raw).color_trc = ffi::AVColorTransferCharacteristic::AVCOL_TRC_SMPTE2084;
+            }
+        } else if matches!(format, PixelFormat::Nv12) || want_444 {
             // SAFETY: same `video` builder — `raw = video.as_mut_ptr()` is the non-null, properly-
             // aligned, sole-owned, not-yet-opened `AVCodecContext`. We set its four VUI colour enum
             // fields to valid `AVColorSpace`/`AVColorRange`/`AVColorPrimaries`/`AVColorTransfer-
@@ -370,17 +413,20 @@ impl NvencEncoder {
             None
         };
 
-        // 4:4:4 CPU path: build the RGB→YUV444P swscale (BT.709, range per the flag; no rescale).
-        // Mirrors the VAAPI CPU path's RGB→NV12 scaler, but the dst is full-chroma planar 4:4:4.
-        // Skipped on the zero-copy path (`cuda`): the worker's GPU convert already delivers
-        // planar YUV444 CUDA frames — no CPU pixels exist to scale.
-        let sws_444 = if want_444 && !cuda {
+        // CPU CSC paths: build the packed-RGB → planar swscale (no rescale) into the encoder's
+        // input frame. Two users: 4:4:4 (RGB→YUV444P, BT.709, range per the flag) and HDR
+        // (X2RGB10/X2BGR10→P010, BT.2020 limited — the PQ transfer is per-channel and rides
+        // through the matrix untouched). Skipped on the zero-copy path (`cuda`): the worker's GPU
+        // convert already delivers ready CUDA frames — no CPU pixels exist to scale.
+        let sws_csc = if (want_444 || want_hdr10) && !cuda {
             let src_av = pixel_to_av(sws_src_pixel(format)?);
+            let dst_av = pixel_to_av(nvenc_pixel);
             // SAFETY: `sws_getContext` allocates a swscale context for the given src/dst dims + pixel
             // formats. Both dims are the encoder's positive `width`/`height` as `c_int`; `src_av` is a
-            // valid `AVPixelFormat` (from the `sws_src_pixel`-validated, packed-RGB-only source), the
-            // dst is YUV444P. The trailing filter/param pointers are null = "use defaults" (documented
-            // as accepted). No Rust memory is borrowed; the returned pointer is null-checked below.
+            // valid `AVPixelFormat` (from the `sws_src_pixel`-validated packed-RGB source), the dst is
+            // YUV444P (4:4:4) or P010LE (HDR). The trailing filter/param pointers are null = "use
+            // defaults" (documented as accepted). No Rust memory is borrowed; the returned pointer is
+            // null-checked below.
             let sws = unsafe {
                 ffi::sws_getContext(
                     width as c_int,
@@ -388,7 +434,7 @@ impl NvencEncoder {
                     src_av,
                     width as c_int,
                     height as c_int,
-                    ffi::AVPixelFormat::AV_PIX_FMT_YUV444P,
+                    dst_av,
                     SWS_POINT,
                     ptr::null_mut(),
                     ptr::null_mut(),
@@ -396,17 +442,22 @@ impl NvencEncoder {
                 )
             };
             if sws.is_null() {
-                bail!("sws_getContext(RGB→YUV444P) failed");
+                bail!("sws_getContext(RGB→{nvenc_pixel:?}) failed");
             }
-            // SAFETY: `sws` is the non-null context from the call above (null-checked). The ITU-709
-            // coefficient table from `sws_getCoefficients` is a process-lifetime libswscale static,
-            // reused for src+dst matrices; `sws_setColorspaceDetails` only reads it and writes scalar
-            // CSC settings into `sws` (dstRange matches the VUI: 0 = limited, 1 = the
-            // PUNKTFUNK_444_FULLRANGE experiment). No Rust memory is passed.
+            // SAFETY: `sws` is the non-null context from the call above (null-checked). The
+            // coefficient tables from `sws_getCoefficients` (ITU-709 for 4:4:4, BT.2020 NCL for HDR
+            // — matching the VUI written above) are process-lifetime libswscale statics, reused for
+            // src+dst matrices; `sws_setColorspaceDetails` only reads them and writes scalar CSC
+            // settings into `sws` (dstRange matches the VUI: 0 = limited, 1 = the
+            // PUNKTFUNK_444_FULLRANGE experiment; HDR is always limited). No Rust memory is passed.
             unsafe {
-                let cs709 = ffi::sws_getCoefficients(SWS_CS_ITU709);
+                let cs = ffi::sws_getCoefficients(if want_hdr10 {
+                    super::libav::SWS_CS_BT2020
+                } else {
+                    SWS_CS_ITU709
+                });
                 let dst_range = i32::from(full_range_444);
-                ffi::sws_setColorspaceDetails(sws, cs709, 1, cs709, dst_range, 0, 1 << 16, 1 << 16);
+                ffi::sws_setColorspaceDetails(sws, cs, 1, cs, dst_range, 0, 1 << 16, 1 << 16);
             }
             Some(sws)
         } else {
@@ -432,6 +483,12 @@ impl NvencEncoder {
             // dropped on a future libavcodec.
             opts.set("profile", "rext");
         }
+        if want_hdr10 && codec == Codec::H265 {
+            // HEVC Main10. `hevc_nvenc` auto-selects it from the P010 input, but pin it explicitly
+            // so the depth is never silently dropped on a future libavcodec. (10-bit AV1 needs no
+            // profile — AV1 Main carries 10-bit, driven by the input format.)
+            opts.set("profile", "main10");
+        }
 
         // Split-frame encode across both NVENC engines (GB203 has 2) when the pixel rate exceeds
         // a single engine's HEVC capacity (~1 Gpix/s); e.g. 5120x1440@240 = 1.77 Gpix/s needs it,
@@ -501,7 +558,7 @@ impl NvencEncoder {
             enc,
             frame,
             cuda: cuda_hw,
-            sws_444,
+            sws_csc,
             want_444,
             src_format: format,
             expand,
@@ -640,7 +697,7 @@ impl NvencEncoder {
         );
         // 4:4:4: swscale the packed RGB straight into the planar YUV444P input frame (BT.709 limited),
         // then send it — no byte-expand. The 4:2:0 RGB path (below) feeds NVENC packed RGB directly.
-        if let Some(sws) = self.sws_444 {
+        if let Some(sws) = self.sws_csc {
             let frame = self
                 .frame
                 .as_mut()
@@ -810,7 +867,7 @@ impl NvencEncoder {
 
 impl Drop for NvencEncoder {
     fn drop(&mut self) {
-        if let Some(sws) = self.sws_444.take() {
+        if let Some(sws) = self.sws_csc.take() {
             // SAFETY: `sws` is the non-null `SwsContext` allocated by `sws_getContext` in `open` and
             // owned exclusively by this encoder (taken out of the field so it can't be freed twice).
             // `sws_freeContext` frees it; nothing else references it after this single-threaded drop.
@@ -855,3 +912,105 @@ pub fn probe_can_encode_444(codec: Codec) -> bool {
     unsafe { ffi::av_log_set_level(prev) };
     ok
 }
+
+/// Probe whether this NVIDIA GPU + driver + libavcodec can actually encode 10-bit (HEVC Main10 /
+/// 10-bit AV1) from a P010 input — the exact path [`NvencEncoder::open`] takes for a live HDR
+/// stream (a tiny X2RGB10-sourced, P010-input open). The result is cached by the caller
+/// ([`crate::can_encode_10bit`]); a GPU/driver/ffmpeg without the 10-bit encode fails the open
+/// here, so the host resolves the session to 8-bit SDR before the Welcome (honest downgrade).
+pub fn probe_can_encode_10bit(codec: Codec) -> bool {
+    if !codec.supports_10bit() {
+        return false;
+    }
+    if ffmpeg::init().is_err() {
+        return false;
+    }
+    // Quiet ffmpeg's open error on a GPU that lacks 10-bit — the probe failing is an expected outcome.
+    // SAFETY: libav initialized above; `av_log_{get,set}_level` only read/write the global int level
+    // (no pointer args) and are always sound post-init.
+    let prev = unsafe {
+        let p = ffi::av_log_get_level();
+        ffi::av_log_set_level(ffi::AV_LOG_FATAL);
+        p
+    };
+    let ok = NvencEncoder::open(
+        codec,
+        PixelFormat::X2Rgb10,
+        640,
+        480,
+        30,
+        2_000_000,
+        false, // CPU input (the HDR swscale path)
+        10,
+        ChromaFormat::Yuv420,
+    )
+    .is_ok();
+    // SAFETY: restore the saved global log level (scalar arg, no pointers).
+    unsafe { ffi::av_log_set_level(prev) };
+    ok
+}
+
+#[cfg(test)]
+mod hdr_tests {
+    use super::*;
+
+    /// The Linux HDR (GNOME 50 portal) encode path end-to-end on a real NVIDIA GPU: a synthetic
+    /// PQ-ish X2RGB10 CPU frame → swscale BT.2020 → P010 → `hevc_nvenc` Main10, drained to a real
+    /// AU. `#[ignore]`d (needs NVENC):
+    /// `cargo test -p pf-encode nvenc_hdr10_smoke -- --ignored --nocapture`
+    #[test]
+    #[ignore]
+    fn nvenc_hdr10_smoke() {
+        let (w, h) = (640u32, 480u32);
+        let mut enc = NvencEncoder::open(
+            Codec::H265,
+            PixelFormat::X2Rgb10,
+            w,
+            h,
+            30,
+            2_000_000,
+            false,
+            10,
+            ChromaFormat::Yuv420,
+        )
+        .expect("open hevc_nvenc Main10 (P010 input)");
+        // Packed x:R:G:B 2:10:10:10 gradient (values are treated as PQ-encoded — fine for a smoke).
+        let mut bytes = vec![0u8; (w * h * 4) as usize];
+        for y in 0..h {
+            for x in 0..w {
+                let r = (x * 1023 / w.max(1)) & 0x3ff;
+                let g = (y * 1023 / h.max(1)) & 0x3ff;
+                let b = ((x + y) * 1023 / (w + h)) & 0x3ff;
+                let px: u32 = (r << 20) | (g << 10) | b;
+                let i = ((y * w + x) * 4) as usize;
+                bytes[i..i + 4].copy_from_slice(&px.to_le_bytes());
+            }
+        }
+        let frame = CapturedFrame {
+            width: w,
+            height: h,
+            pts_ns: 0,
+            format: PixelFormat::X2Rgb10,
+            payload: FramePayload::Cpu(bytes),
+            cursor: None,
+        };
+        let mut au = None;
+        for _ in 0..30 {
+            enc.submit(&frame).expect("submit X2Rgb10 frame");
+            if let Some(a) = enc.poll().expect("poll") {
+                au = Some(a);
+                break;
+            }
+        }
+        let au = au.expect("no AU produced within 30 frames");
+        assert!(!au.data.is_empty(), "empty AU");
+        assert!(au.keyframe, "first AU should be the IDR");
+        println!("HDR10 smoke: first AU {} bytes (IDR)", au.data.len());
+        // PF_HDR_SMOKE_DUMP=/path.h265: write the Annex-B AU for external inspection —
+        // `ffprobe -show_streams` should report Main 10, bt2020nc/smpte2084/bt2020 colours.
+        if let Ok(path) = std::env::var("PF_HDR_SMOKE_DUMP") {
+            std::fs::write(&path, &au.data).expect("dump AU");
+            println!("HDR10 smoke: AU written to {path}");
+        }
+    }
+}

crates/pf-encode/src/enc/linux/nvenc_cuda.rs

@@ -474,9 +474,13 @@ impl NvencCudaEncoder {
         // clear reason instead of an opaque session error on the first frame.
         try_api().map_err(|e| anyhow!("NVENC (Linux direct) unavailable: {e}"))?;
         if bit_depth >= 10 {
+            // An HDR (GNOME 50 portal) session never reaches this backend: its X2RGB10 frames ride
+            // the CPU/dmabuf paths (no CUDA import for the 10-bit formats yet), so the dispatcher
+            // opens the libav P010 path instead. Reaching here 10-bit means a CUDA capture payload
+            // on a 10-bit session — not wired; encode 8-bit rather than mislabel.
             tracing::warn!(
-                "Linux direct-NVENC: 10-bit requested but no P010 capture path exists yet \
-                 (Phase 5.1) — encoding 8-bit SDR"
+                "Linux direct-NVENC: 10-bit requested but the CUDA capture path has no 10-bit \
+                 import yet (HDR rides the libav P010 path) — encoding 8-bit SDR"
             );
         }
         Ok(Self {
@@ -1074,7 +1078,18 @@ impl Encoder for NvencCudaEncoder {
             // 4:4:4 honesty: engage FREXT only on a genuine YUV444 input; a subsampled NV12/RGB input
             // can't reconstruct full chroma, so clear the flag so `caps().chroma_444` is truthful.
             self.chroma_444 = self.chroma_444 && buf.yuv444;
-            self.init_session()?;
+            // `init_session` publishes `self.encoder` before its remaining fallible steps (bitstream
+            // buffers, input-surface alloc, `register_resource`), so a failure there leaves a live
+            // session with `inited == false`. Every guard on the re-init path keys off `inited`, so
+            // without this the next submit would skip teardown and overwrite `self.encoder`, leaking
+            // the session and its registered input surfaces permanently. `teardown` keys off
+            // `encoder.is_null()`, not `inited`, so it cleans up exactly this half-built state.
+            if let Err(e) = self.init_session() {
+                // SAFETY: the encode thread owns the session and a failed init leaves nothing
+                // mid-encode to race with.
+                unsafe { self.teardown() };
+                return Err(e);
+            }
         } else {
             // Steady state: the copy helpers need the shared context current on this thread.
             cuda::make_current().context("cuCtxSetCurrent (encode thread)")?;

crates/pf-encode/src/enc/linux/pyrowave.rs

@@ -38,6 +38,9 @@ use std::os::raw::c_char;
 /// uses. PyroWave carries no VUI, so the colour contract is fixed by this shader: the Phase-2
 /// client CSC must assume BT.709 limited range.
 const CSC_SPV: &[u8] = include_bytes!("rgb2yuv.spv");
+/// The 4:4:4 twin (`rgb2yuv444.comp`): one invocation per pixel, full-res interleaved CbCr,
+/// same BT.709-limited coefficients byte-for-byte.
+const CSC444_SPV: &[u8] = include_bytes!("rgb2yuv444.spv");
 /// Fixed cursor-overlay texture size (px) — mirrors `vulkan_video.rs`; the shared CSC shader bounds
 /// sampling by its push constant, so one allocation fits every pointer bitmap.
 const CURSOR_MAX: u32 = 256;
@@ -46,13 +49,6 @@ const IMPORT_CACHE_CAP: usize = 16;
 /// Headroom over the per-frame rate budget for the packetized bitstream (block headers + meta;
 /// the rate controller itself never exceeds the budget).
 const BS_SLACK: usize = 256 * 1024;
-/// Chunked-mode window framing (§4.4): 4-byte prefix per shard-sized window.
-const WINDOW_PREFIX: usize = 4;
-/// Window kinds: whole packets / an oversized packet's fragments.
-const WIN_PACKED: u16 = 0;
-const WIN_FRAG_FIRST: u16 = 1;
-const WIN_FRAG_CONT: u16 = 2;
-const WIN_FRAG_LAST: u16 = 3;
 
 /// The DRM modifiers the PyroWave device can import as a SAMPLED image of the capture's
 /// packed-RGB format. The capture advertises these for the pyrowave passthrough instead of
@@ -197,6 +193,9 @@ pub struct PyroWaveEncoder {
     width: u32,
     height: u32,
     fps: u32,
+    /// Session-fixed negotiated chroma: 4:4:4 = full-res RG8 chroma plane + per-pixel CSC
+    /// (`rgb2yuv444.comp`) + `Chroma444` pyrowave objects.
+    chroma444: bool,
     /// Per-frame bitstream budget (hard CBR): `bitrate / (8 * fps)`.
     frame_budget: usize,
     /// Datagram-aligned mode (plan §4.4): packetize at this boundary and pad every codec
@@ -218,17 +217,39 @@ fn budget_for(bitrate_bps: u64, fps: u32) -> usize {
 }
 
 impl PyroWaveEncoder {
-    pub fn open(width: u32, height: u32, fps: u32, bitrate_bps: u64) -> Result<Self> {
-        if width % 2 != 0 || height % 2 != 0 {
+    pub fn open(
+        width: u32,
+        height: u32,
+        fps: u32,
+        bitrate_bps: u64,
+        chroma: crate::ChromaFormat,
+    ) -> Result<Self> {
+        if !chroma.is_444() && (width % 2 != 0 || height % 2 != 0) {
             bail!("pyrowave 4:2:0 needs even dimensions (got {width}x{height})");
         }
+        if chroma.is_444() && !crate::pyrowave_mode_fits_rdo(width, height, true) {
+            // The negotiator downgrades these modes to 4:2:0 pre-Welcome; refuse if one
+            // slips through (e.g. the lab override) rather than wrap the RDO block index.
+            bail!(
+                "pyrowave 4:4:4 at {width}x{height} exceeds the rate controller's 16-bit \
+                 block index (see pyrowave-sys patches/0002 note) — use 4:2:0 at this size"
+            );
+        }
         // SAFETY: `open_inner` only issues Vulkan/pyrowave calls whose preconditions it
         // establishes itself (valid instance/device, correctly-chained create-infos that
         // `DeviceHold` keeps alive); all handles are freshly created and owned by the result.
-        unsafe { Self::open_inner(width, height, fps.max(1), bitrate_bps.max(1_000_000)) }
+        unsafe {
+            Self::open_inner(
+                width,
+                height,
+                fps.max(1),
+                bitrate_bps.max(1_000_000),
+                chroma.is_444(),
+            )
+        }
     }
 
-    unsafe fn open_inner(w: u32, h: u32, fps: u32, bitrate: u64) -> Result<Self> {
+    unsafe fn open_inner(w: u32, h: u32, fps: u32, bitrate: u64, chroma444: bool) -> Result<Self> {
         let entry = ash::Entry::load().context("load vulkan loader")?;
 
         let mut hold = DeviceHold {
@@ -381,7 +402,11 @@ impl PyroWaveEncoder {
             device: pw_dev,
             width: w as i32,
             height: h as i32,
-            chroma: pw::pyrowave_chroma_subsampling_PYROWAVE_CHROMA_SUBSAMPLING_420,
+            chroma: if chroma444 {
+                pw::pyrowave_chroma_subsampling_PYROWAVE_CHROMA_SUBSAMPLING_444
+            } else {
+                pw::pyrowave_chroma_subsampling_PYROWAVE_CHROMA_SUBSAMPLING_420
+            },
         };
         let mut pw_enc: pw::pyrowave_encoder = std::ptr::null_mut();
         if let Err(e) = pw_check(
@@ -392,8 +417,10 @@ impl PyroWaveEncoder {
             return Err(e);
         }
 
-        // ---- CSC planes: full-res R8 luma + half-res RG8 chroma, storage-written by the CSC
-        //      and sampled directly by pyrowave (R/G view swizzles synthesize Cb/Cr) ----
+        // ---- CSC planes: full-res R8 luma + RG8 chroma (half-res for 4:2:0, full-res for
+        //      4:4:4), storage-written by the CSC and sampled directly by pyrowave (R/G view
+        //      swizzles synthesize Cb/Cr) ----
+        let (cw, ch) = if chroma444 { (w, h) } else { (w / 2, h / 2) };
         let (y_img, y_mem, y_view) = make_plain_image(
             &device,
             &mem_props,
@@ -406,8 +433,8 @@ impl PyroWaveEncoder {
             &device,
             &mem_props,
             vk::Format::R8G8_UNORM,
-            w / 2,
-            h / 2,
+            cw,
+            ch,
             vk::ImageUsageFlags::STORAGE | vk::ImageUsageFlags::SAMPLED,
         )?;
 
@@ -420,7 +447,11 @@ impl PyroWaveEncoder {
                 .address_mode_v(vk::SamplerAddressMode::CLAMP_TO_EDGE),
             None,
         )?;
-        let spv = ash::util::read_spv(&mut std::io::Cursor::new(CSC_SPV))?;
+        let spv = ash::util::read_spv(&mut std::io::Cursor::new(if chroma444 {
+            CSC444_SPV
+        } else {
+            CSC_SPV
+        }))?;
         let shader =
             device.create_shader_module(&vk::ShaderModuleCreateInfo::default().code(&spv), None)?;
         let sb = |b: u32, t: vk::DescriptorType| {
@@ -566,7 +597,8 @@ impl PyroWaveEncoder {
             gpu = %props.device_name_as_c_str().unwrap_or(c"?").to_string_lossy(),
             mode = %format!("{w}x{h}@{fps}"),
             budget_kib = frame_budget / 1024,
-            "PyroWave encoder open (intra-only wavelet, BT.709 limited 4:2:0)"
+            chroma = if chroma444 { "4:4:4" } else { "4:2:0" },
+            "PyroWave encoder open (intra-only wavelet, BT.709 limited)"
         );
 
         Ok(Self {
@@ -608,6 +640,7 @@ impl PyroWaveEncoder {
             width: w,
             height: h,
             fps,
+            chroma444,
             frame_budget,
             wire_chunk: None,
             bitstream: Vec::new(),
@@ -832,6 +865,13 @@ impl PyroWaveEncoder {
     /// One frame, synchronously: ingest → CSC → pyrowave encode (recorded into our command
     /// buffer) → submit + fence wait (sub-ms) → packetize into an `EncodedFrame`.
     unsafe fn encode_frame(&mut self, frame: &CapturedFrame) -> Result<()> {
+        // A failed `reset()` leaves the encoder destroyed and null. Callers today turn that into
+        // a session error and never resubmit, but a null here would be a use-after-free inside
+        // pyrowave rather than a clean error — so fail loudly instead of relying on that.
+        anyhow::ensure!(
+            !self.pw_enc.is_null(),
+            "pyrowave: encode after a failed reset (encoder was destroyed and not rebuilt)"
+        );
         let dev = self.device.clone();
         let (w, h) = (self.width, self.height);
         dev.begin_command_buffer(
@@ -971,7 +1011,12 @@ impl PyroWaveEncoder {
             0,
             &pc_bytes,
         );
-        dev.cmd_dispatch(self.cmd, (w / 2).div_ceil(8), (h / 2).div_ceil(8), 1);
+        // 4:2:0: one invocation per 2x2 luma block (per chroma sample); 4:4:4: per pixel.
+        if self.chroma444 {
+            dev.cmd_dispatch(self.cmd, w.div_ceil(8), h.div_ceil(8), 1);
+        } else {
+            dev.cmd_dispatch(self.cmd, (w / 2).div_ceil(8), (h / 2).div_ceil(8), 1);
+        }
 
         // CSC storage writes -> pyrowave's sampled reads (images stay GENERAL — the layout
         // pyrowave's GPU-buffer contract accepts without transitions).
@@ -1024,17 +1069,19 @@ impl PyroWaveEncoder {
                 ),
                 // Two-component chroma image: view swizzles R/G synthesize the Cb/Cr planes
                 // (the documented NV12-style hand-off, pyrowave.h `pyrowave_gpu_buffers`).
+                // The view extent is the chroma IMAGE's own mip0 extent (it's a separate
+                // image, not a planar aspect): half-res for 4:2:0, full-res for 4:4:4.
                 plane(
                     self.uv_img,
-                    w / 2,
-                    h / 2,
+                    if self.chroma444 { w } else { w / 2 },
+                    if self.chroma444 { h } else { h / 2 },
                     rg8,
                     pw::VkComponentSwizzle_VK_COMPONENT_SWIZZLE_R,
                 ),
                 plane(
                     self.uv_img,
-                    w / 2,
-                    h / 2,
+                    if self.chroma444 { w } else { w / 2 },
+                    if self.chroma444 { h } else { h / 2 },
                     rg8,
                     pw::VkComponentSwizzle_VK_COMPONENT_SWIZZLE_G,
                 ),
@@ -1077,8 +1124,8 @@ impl PyroWaveEncoder {
         // boundary by design.
         let cap = self.frame_budget + BS_SLACK;
         self.bitstream.resize(cap, 0);
-        // Chunked mode reserves 4 bytes per window for the framing prefix.
-        let boundary = self.wire_chunk.map(|c| c - WINDOW_PREFIX).unwrap_or(cap);
+        // Chunked mode reserves the 4-byte window prefix from the packetize boundary (shared helper).
+        let boundary = crate::pyrowave_wire::packet_boundary(self.wire_chunk, cap);
         let mut n: usize = 0;
         pw_check(
             pw::pyrowave_encoder_compute_num_packets(self.pw_enc, boundary, &mut n),
@@ -1101,67 +1148,16 @@ impl PyroWaveEncoder {
             "packetize",
         )?;
         packets.truncate(out_n.max(1));
-        let au = if let Some(chunk) = self.wire_chunk {
-            // Window framing (§4.4): each `chunk`-sized window opens with a 4-byte prefix
-            // (u16 used-length + u16 kind) and carries either WHOLE self-delimiting codec
-            // packets (PACKED — several small ones share a window) or one fragment of an
-            // oversized packet (FRAG chain — pyrowave 32×32 blocks are atomic and may
-            // exceed a shard). A lost shard zeroes its window (used = 0) — the receiver
-            // skips it and drops any fragment chain it interrupts.
-            let payload_max = chunk - WINDOW_PREFIX;
-            let mut au: Vec<u8> = Vec::with_capacity((packets.len() + 1) * chunk);
-            // The currently-open PACKED window: (start offset of its prefix, bytes used).
-            let mut open: Option<(usize, usize)> = None;
-            let close = |au: &mut Vec<u8>, open: &mut Option<(usize, usize)>, chunk: usize| {
-                if let Some((start, used)) = open.take() {
-                    au[start..start + 2].copy_from_slice(&(used as u16).to_le_bytes());
-                    au[start + 2..start + 4].copy_from_slice(&WIN_PACKED.to_le_bytes());
-                    au.resize(start + chunk, 0);
-                }
-            };
-            for p in &packets {
-                let bytes = &self.bitstream[p.offset..p.offset + p.size];
-                if p.size <= payload_max {
-                    let fits = open.is_some_and(|(_, used)| used + p.size <= payload_max);
-                    if !fits {
-                        close(&mut au, &mut open, chunk);
-                        let start = au.len();
-                        au.resize(start + WINDOW_PREFIX, 0);
-                        open = Some((start, 0));
-                    }
-                    au.extend_from_slice(bytes);
-                    if let Some((_, used)) = open.as_mut() {
-                        *used += p.size;
-                    }
-                } else {
-                    // Oversized packet: its own FRAG chain of full windows.
-                    close(&mut au, &mut open, chunk);
-                    let mut off = 0usize;
-                    while off < p.size {
-                        let take = (p.size - off).min(payload_max);
-                        let kind = if off == 0 {
-                            WIN_FRAG_FIRST
-                        } else if off + take == p.size {
-                            WIN_FRAG_LAST
-                        } else {
-                            WIN_FRAG_CONT
-                        };
-                        let start = au.len();
-                        au.resize(start + WINDOW_PREFIX, 0);
-                        au[start..start + 2].copy_from_slice(&(take as u16).to_le_bytes());
-                        au[start + 2..start + 4].copy_from_slice(&kind.to_le_bytes());
-                        au.extend_from_slice(&bytes[off..off + take]);
-                        au.resize(start + chunk, 0);
-                        off += take;
-                    }
-                }
-            }
-            close(&mut au, &mut open, chunk);
-            au
-        } else {
-            let p = &packets[0];
-            self.bitstream[p.offset..p.offset + p.size].to_vec()
-        };
+        // Correct pyrowave's zeroed sequence-header VUI: it signals ycbcr_range=FULL, but our CSC
+        // emits BT.709 LIMITED — patch the bits HONEST so VUI-honoring clients don't wash out
+        // blacks. (Linux capture has no HDR path, so this side never stamps BT.2020/PQ.)
+        if let Some(p) = packets.first() {
+            crate::pyrowave_wire::stamp_color_bits(&mut self.bitstream, p.offset, false);
+        }
+        // Frame into the wire AU via the shared helper (byte-identical on Linux + Windows): the dense
+        // single packet, or the datagram-aligned windowed AU (§4.4).
+        let pkts: Vec<(usize, usize)> = packets.iter().map(|p| (p.offset, p.size)).collect();
+        let au = crate::pyrowave_wire::build_au(&pkts, &self.bitstream, self.wire_chunk);
         self.frame_count += 1;
         self.pending.push_back(EncodedFrame {
             data: au,
@@ -1184,9 +1180,14 @@ impl Encoder for PyroWaveEncoder {
     }
 
     fn caps(&self) -> EncoderCaps {
-        // All defaults: no RFI (meaningless — every frame is intra), no HDR (8-bit SDR codec),
-        // no intra-refresh wave (ditto). 4:2:0 only until the 4:4:4 ride-along (plan §6).
-        EncoderCaps::default()
+        // No RFI / no intra-refresh wave (every frame is intra). Report the real opened chroma so
+        // the session glue's post-open cross-check stays quiet on a genuine 4:4:4 session — a
+        // hardcoded `default()` here mis-reports a 4:4:4 open as 4:2:0 and fires a spurious
+        // "chroma disagrees with the negotiated Welcome" warn.
+        EncoderCaps {
+            chroma_444: self.chroma444,
+            ..EncoderCaps::default()
+        }
     }
 
     fn poll(&mut self) -> Result<Option<EncodedFrame>> {
@@ -1201,16 +1202,30 @@ impl Encoder for PyroWaveEncoder {
         unsafe {
             self.device.device_wait_idle().ok();
             pw::pyrowave_encoder_destroy(self.pw_enc);
+            // Publish the null IMMEDIATELY: the create below is fallible, and its failure path
+            // must not leave a freed pointer in the field. `pyrowave_encoder_destroy` is a plain
+            // `delete` (pyrowave_c.cpp) with no null check, so `Drop` running on a stale handle
+            // is a double free — the exact shape this reset hits when the rebuild fails because
+            // the device is already lost, which is the state that made the watchdog fire.
+            self.pw_enc = std::ptr::null_mut();
             let einfo = pw::pyrowave_encoder_create_info {
                 device: self.pw_dev,
                 width: self.width as i32,
                 height: self.height as i32,
-                chroma: pw::pyrowave_chroma_subsampling_PYROWAVE_CHROMA_SUBSAMPLING_420,
+                chroma: if self.chroma444 {
+                    pw::pyrowave_chroma_subsampling_PYROWAVE_CHROMA_SUBSAMPLING_444
+                } else {
+                    pw::pyrowave_chroma_subsampling_PYROWAVE_CHROMA_SUBSAMPLING_420
+                },
             };
             let mut enc: pw::pyrowave_encoder = std::ptr::null_mut();
             let r = pw::pyrowave_encoder_create(&einfo, &mut enc);
             if r != pw::pyrowave_result_PYROWAVE_SUCCESS {
                 tracing::error!(result = ?r, "pyrowave: encoder rebuild failed");
+                // `pw_enc` stays null — `Drop` and `encode_frame` both guard on it. The queued
+                // AUs are forfeit either way (the caller turns a false reset into a session
+                // error), so drop them rather than shipping output from a dead encoder.
+                self.pending.clear();
                 return false;
             }
             self.pw_enc = enc;
@@ -1256,7 +1271,11 @@ impl Drop for PyroWaveEncoder {
         // before the VkDevice they borrow (encoder before device, per pyrowave.h).
         unsafe {
             self.device.device_wait_idle().ok();
-            pw::pyrowave_encoder_destroy(self.pw_enc);
+            // Null when a failed `reset()` already destroyed it — `pyrowave_encoder_destroy`
+            // is not null-safe.
+            if !self.pw_enc.is_null() {
+                pw::pyrowave_encoder_destroy(self.pw_enc);
+            }
             pw::pyrowave_device_destroy(self.pw_dev);
             for (_, _, i, m, v) in self.import_cache.drain(..) {
                 self.device.destroy_image_view(v, None);
@@ -1327,10 +1346,16 @@ mod tests {
         )
     }
 
-    /// Decode an AU with a standalone pyrowave decoder and return the full YUV420P planes.
-    /// This is the golden oracle for both the Phase-1 smoke check (plane means) and the Apple
-    /// Metal port's committed PSNR fixtures (`pyrowave_dump_golden`).
-    unsafe fn decode_planes(w: u32, h: u32, au: &[u8]) -> (Vec<u8>, Vec<u8>, Vec<u8>) {
+    /// Decode an AU with a standalone pyrowave decoder and return the full planar YUV
+    /// (half-res chroma for 4:2:0, full-res for 4:4:4). This is the golden oracle for the
+    /// smoke checks (plane means) and the Apple Metal port's committed PSNR fixtures
+    /// (`pyrowave_dump_golden`).
+    unsafe fn decode_planes_chroma(
+        w: u32,
+        h: u32,
+        au: &[u8],
+        chroma444: bool,
+    ) -> (Vec<u8>, Vec<u8>, Vec<u8>) {
         let mut dev: pw::pyrowave_device = std::ptr::null_mut();
         assert_eq!(
             pw::pyrowave_create_default_device(&mut dev),
@@ -1340,7 +1365,11 @@ mod tests {
             device: dev,
             width: w as i32,
             height: h as i32,
-            chroma: pw::pyrowave_chroma_subsampling_PYROWAVE_CHROMA_SUBSAMPLING_420,
+            chroma: if chroma444 {
+                pw::pyrowave_chroma_subsampling_PYROWAVE_CHROMA_SUBSAMPLING_444
+            } else {
+                pw::pyrowave_chroma_subsampling_PYROWAVE_CHROMA_SUBSAMPLING_420
+            },
             fragment_path: false,
         };
         let mut dec: pw::pyrowave_decoder = std::ptr::null_mut();
@@ -1354,11 +1383,16 @@ mod tests {
         );
         assert!(pw::pyrowave_decoder_decode_is_ready(dec, false));
 
+        let (cw, ch) = if chroma444 { (w, h) } else { (w / 2, h / 2) };
         let mut y = vec![0u8; (w * h) as usize];
-        let mut cb = vec![0u8; (w * h / 4) as usize];
-        let mut cr = vec![0u8; (w * h / 4) as usize];
+        let mut cb = vec![0u8; (cw * ch) as usize];
+        let mut cr = vec![0u8; (cw * ch) as usize];
         let mut buf: pw::pyrowave_cpu_buffer = std::mem::zeroed();
-        buf.format = pw::pyrowave_cpu_buffer_format_PYROWAVE_CPU_BUFFER_FORMAT_YUV420P;
+        buf.format = if chroma444 {
+            pw::pyrowave_cpu_buffer_format_PYROWAVE_CPU_BUFFER_FORMAT_YUV444P
+        } else {
+            pw::pyrowave_cpu_buffer_format_PYROWAVE_CPU_BUFFER_FORMAT_YUV420P
+        };
         buf.width = w as i32;
         buf.height = h as i32;
         buf.data = [
@@ -1366,7 +1400,7 @@ mod tests {
             cb.as_mut_ptr() as *mut _,
             cr.as_mut_ptr() as *mut _,
         ];
-        buf.row_stride_in_bytes = [w as usize, (w / 2) as usize, (w / 2) as usize];
+        buf.row_stride_in_bytes = [w as usize, cw as usize, cw as usize];
         buf.plane_size_in_bytes = [y.len(), cb.len(), cr.len()];
         assert_eq!(
             pw::pyrowave_decoder_decode_cpu_buffer_synchronous(dec, &buf),
@@ -1377,10 +1411,15 @@ mod tests {
         (y, cb, cr)
     }
 
-    /// Plane means of an upstream-decoded AU — the Phase-1 smoke assertion.
-    unsafe fn decode_plane_means(w: u32, h: u32, au: &[u8]) -> (f64, f64, f64) {
+    unsafe fn decode_planes(w: u32, h: u32, au: &[u8]) -> (Vec<u8>, Vec<u8>, Vec<u8>) {
         // SAFETY: forwarded — same contract as the caller.
-        let (y, cb, cr) = unsafe { decode_planes(w, h, au) };
+        unsafe { decode_planes_chroma(w, h, au, false) }
+    }
+
+    /// Plane means of an upstream-decoded AU — the smoke assertion.
+    unsafe fn decode_plane_means(w: u32, h: u32, au: &[u8], chroma444: bool) -> (f64, f64, f64) {
+        // SAFETY: forwarded — same contract as the caller.
+        let (y, cb, cr) = unsafe { decode_planes_chroma(w, h, au, chroma444) };
         let mean = |v: &[u8]| v.iter().map(|&x| x as f64).sum::<f64>() / v.len() as f64;
         (mean(&y), mean(&cb), mean(&cr))
     }
@@ -1394,7 +1433,8 @@ mod tests {
     #[ignore = "needs a real Vulkan 1.3 compute device (run on a GPU host, not the build box)"]
     fn pyrowave_smoke() {
         let (w, h) = (256u32, 256u32);
-        let mut enc = PyroWaveEncoder::open(w, h, 60, 40_000_000).expect("open");
+        let mut enc =
+            PyroWaveEncoder::open(w, h, 60, 40_000_000, crate::ChromaFormat::Yuv420).expect("open");
         assert!(!enc.caps().supports_rfi);
 
         let colors = [
@@ -1414,7 +1454,7 @@ mod tests {
                 "AU exceeds rate budget"
             );
             // SAFETY: test-only FFI into the vendored decoder with locally-owned buffers.
-            let (ym, cbm, crm) = unsafe { decode_plane_means(w, h, &au.data) };
+            let (ym, cbm, crm) = unsafe { decode_plane_means(w, h, &au.data, false) };
             let (ye, cbe, cre) = bt709(*c);
             assert!(
                 (ym - ye).abs() < 3.0 && (cbm - cbe).abs() < 3.0 && (crm - cre).abs() < 3.0,
@@ -1508,6 +1548,68 @@ mod tests {
         assert!(enc.poll().expect("poll").is_some());
     }
 
+    /// The 4:4:4 twin of `pyrowave_smoke`: per-pixel CSC into full-res RG8 chroma +
+    /// `Chroma444` pyrowave objects, verified by upstream's own 4:4:4 CPU decode. The
+    /// busy-card leg then drives the rate controller at the ~2.6 bpp operating point —
+    /// exactly the regime that overran upstream's 4:2:0-sized payload staging before
+    /// `patches/0001-payload-data-444-sizing.patch` (the Phase-0 finding): it must stay
+    /// within budget, decode, and be run-to-run deterministic (the overrun was not).
+    #[test]
+    #[ignore = "needs a real Vulkan 1.3 compute device (run on a GPU host, not the build box)"]
+    fn pyrowave_smoke_444() {
+        let (w, h) = (256u32, 256u32);
+        let mut enc =
+            PyroWaveEncoder::open(w, h, 60, 40_000_000, crate::ChromaFormat::Yuv444).expect("open");
+        let colors = [
+            [40u8, 40, 200, 255],
+            [40, 200, 40, 255],
+            [200, 40, 40, 255],
+            [128, 128, 128, 255],
+        ];
+        for (i, c) in colors.iter().enumerate() {
+            enc.submit(&cpu_frame(w, h, i as u64 * 16_666_667, *c))
+                .expect("submit");
+            let au = enc.poll().expect("poll").expect("one AU per frame");
+            assert!(au.keyframe);
+            assert!(
+                au.data.len() <= enc.frame_budget + BS_SLACK,
+                "AU exceeds rate budget"
+            );
+            // SAFETY: test-only FFI into the vendored decoder with locally-owned buffers.
+            let (ym, cbm, crm) = unsafe { decode_plane_means(w, h, &au.data, true) };
+            let (ye, cbe, cre) = bt709(*c);
+            assert!(
+                (ym - ye).abs() < 3.0 && (cbm - cbe).abs() < 3.0 && (crm - cre).abs() < 3.0,
+                "frame {i}: decoded plane means (Y {ym:.1}, Cb {cbm:.1}, Cr {crm:.1}) vs \
+                 expected (Y {ye:.1}, Cb {cbe:.1}, Cr {cre:.1})"
+            );
+        }
+
+        // Busy content at the 4:4:4 operating point (~2.6 bpp).
+        let budget_bps = w as u64 * h as u64 * 60 * 26 / 10;
+        let mut enc =
+            PyroWaveEncoder::open(w, h, 60, budget_bps, crate::ChromaFormat::Yuv444).expect("open");
+        let mut sizes = Vec::new();
+        for _ in 0..3 {
+            enc.submit(&test_card(w, h, 7)).expect("busy submit");
+            let au = enc.poll().expect("poll").expect("busy AU");
+            assert!(
+                au.data.len() <= enc.frame_budget + BS_SLACK,
+                "busy 4:4:4 AU exceeds rate budget ({} > {})",
+                au.data.len(),
+                enc.frame_budget + BS_SLACK
+            );
+            // Upstream's own decoder accepts it (a corrupt stream errors or garbles).
+            // SAFETY: test-only FFI with locally-owned buffers.
+            let _ = unsafe { decode_planes_chroma(w, h, &au.data, true) };
+            sizes.push(au.data.len());
+        }
+        assert!(
+            sizes.windows(2).all(|s| s[0] == s[1]),
+            "identical input produced varying AU sizes (the Phase-0 overrun signature): {sizes:?}"
+        );
+    }
+
     /// A deterministic busy BGRA test card (gradients + checker + LCG noise) — flat fills
     /// exercise almost none of the entropy decoder, this hits every subband.
     fn test_card(w: u32, h: u32, seed: u32) -> CapturedFrame {
@@ -1558,7 +1660,8 @@ mod tests {
         // Odd-block geometry on purpose: 256 aligns clean, 144 → aligned 160 exercises the
         // block-grid overhang. ~1.6 bpp at 60 fps.
         let (w, h) = (256u32, 144u32);
-        let mut enc = PyroWaveEncoder::open(w, h, 60, 4_000_000).expect("open");
+        let mut enc =
+            PyroWaveEncoder::open(w, h, 60, 4_000_000, crate::ChromaFormat::Yuv420).expect("open");
 
         let dump = |name: &str, bytes: &[u8]| {
             std::fs::write(dir.join(name), bytes).expect("write fixture");
@@ -1610,5 +1713,19 @@ mod tests {
         dump("ref-chunked-y.bin", &y);
         dump("ref-chunked-cb.bin", &cb);
         dump("ref-chunked-cr.bin", &cr);
+
+        // 4:4:4 dense AU + its reference (full-res chroma planes) — the Apple 4:4:4 layout's
+        // golden (design/pyrowave-444-hdr.md Phase 4). Same odd-block geometry.
+        let mut enc =
+            PyroWaveEncoder::open(w, h, 60, 6_500_000, crate::ChromaFormat::Yuv444).expect("open");
+        enc.submit(&test_card(w, h, 13)).expect("444 submit");
+        let au = enc.poll().expect("poll").expect("444 AU");
+        assert!(!au.chunk_aligned);
+        dump("au-dense444.bin", &au.data);
+        // SAFETY: test-only FFI with locally-owned buffers.
+        let (y, cb, cr) = unsafe { decode_planes_chroma(w, h, &au.data, true) };
+        dump("ref-dense444-y.bin", &y);
+        dump("ref-dense444-cb.bin", &cb);
+        dump("ref-dense444-cr.bin", &cr);
     }
 }

crates/pf-encode/src/enc/linux/rgb2yuv444.comp

@@ -0,0 +1,37 @@
+#version 450
+// RGB(A) -> full-res Y + FULL-res interleaved CbCr (BT.709 limited range): the 4:4:4 twin of
+// rgb2yuv.comp — one invocation per pixel, no chroma box filter, no siting. Same coefficients
+// byte-for-byte (the wavelet clients' planar CSC decodes both layouts identically), same
+// cursor-as-metadata blend, same source-edge clamp for the 32-aligned coded extent.
+layout(local_size_x = 8, local_size_y = 8) in;
+layout(binding = 0) uniform sampler2D rgb;                  // packed RGB input (sampled; BGRA import ok)
+layout(binding = 1, r8)  uniform writeonly image2D yImg;    // full-res Y
+layout(binding = 2, rg8) uniform writeonly image2D uvImg;   // full-res UV (interleaved)
+layout(binding = 3) uniform sampler2D cursorTex;            // straight-alpha RGBA cursor (top-left)
+
+layout(push_constant) uniform Push {
+    ivec2 curOrigin;   // top-left of the cursor in frame pixels (position - hotspot)
+    ivec2 curSize;     // cursor w,h in pixels; x <= 0 => disabled
+} pc;
+
+float lumaY(vec3 c) { return 16.0/255.0 + 0.1826*c.r + 0.6142*c.g + 0.0620*c.b; }
+
+vec3 withCursor(ivec2 p, vec3 col) {
+    if (pc.curSize.x <= 0) return col;
+    ivec2 cp = p - pc.curOrigin;
+    if (cp.x < 0 || cp.y < 0 || cp.x >= pc.curSize.x || cp.y >= pc.curSize.y) return col;
+    vec4 c = texelFetch(cursorTex, cp, 0);
+    return mix(col, c.rgb, c.a);
+}
+
+void main() {
+    ivec2 sz = imageSize(yImg);
+    ivec2 rmax = textureSize(rgb, 0) - 1;
+    ivec2 p = ivec2(gl_GlobalInvocationID.xy);
+    if (p.x >= sz.x || p.y >= sz.y) return;
+    vec3 c = withCursor(p, texelFetch(rgb, min(p, rmax), 0).rgb);
+    imageStore(yImg, p, vec4(lumaY(c), 0, 0, 1));
+    float U = 128.0/255.0 - 0.1006*c.r - 0.3386*c.g + 0.4392*c.b;
+    float V = 128.0/255.0 + 0.4392*c.r - 0.3989*c.g - 0.0403*c.b;
+    imageStore(uvImg, p, vec4(U, V, 0, 1));
+}

crates/pf-encode/src/enc/linux/vaapi.rs

@@ -61,6 +61,10 @@ fn vaapi_sws_src(format: PixelFormat) -> Result<Pixel> {
         PixelFormat::Rgba => Pixel::RGBA,
         PixelFormat::Rgb => Pixel::RGB24,
         PixelFormat::Bgr => Pixel::BGR24,
+        // The GNOME 50+ HDR capture formats (PQ/BT.2020 packed 2:10:10:10) — the HDR CPU path's
+        // swscale source for the X2RGB10→P010 conversion.
+        PixelFormat::X2Rgb10 => Pixel::X2RGB10LE,
+        PixelFormat::X2Bgr10 => Pixel::X2BGR10LE,
         PixelFormat::Nv12 | PixelFormat::P010 | PixelFormat::Rgb10a2 | PixelFormat::Yuv444 => {
             bail!("VAAPI CPU-input path supports packed RGB/BGR only; got {format:?}")
         }
@@ -101,6 +105,7 @@ fn low_power_override() -> Option<bool> {
 /// default on those kernels). AMD keeps its first-try full-feature open byte-for-byte unchanged.
 /// The resolved mode is cached per codec; `PUNKTFUNK_VAAPI_LOW_POWER` pins it.
 /// Safety contract is [`open_vaapi_encoder_mode`]'s (borrowed `device_ref`/`frames_ref`).
+#[allow(clippy::too_many_arguments)]
 unsafe fn open_vaapi_encoder(
     codec: Codec,
     width: u32,
@@ -109,6 +114,7 @@ unsafe fn open_vaapi_encoder(
     bitrate_bps: u64,
     device_ref: *mut ffi::AVBufferRef,
     frames_ref: *mut ffi::AVBufferRef,
+    ten_bit: bool,
 ) -> Result<encoder::video::Encoder> {
     let idx = lp_idx(codec);
     let modes: &[bool] = match low_power_override() {
@@ -130,6 +136,7 @@ unsafe fn open_vaapi_encoder(
             bitrate_bps,
             device_ref,
             frames_ref,
+            ten_bit,
             lp,
         ) {
             Ok(enc) => {
@@ -158,8 +165,9 @@ unsafe fn open_vaapi_encoder(
 }
 
 /// Build the FFmpeg encoder context (shared by both inner paths): name, mode, low-latency RC,
-/// infinite GOP, BT.709-limited VUI, `pix_fmt=VAAPI`, and the given hw device + frames contexts.
-/// Returns the opened encoder. `device_ref`/`frames_ref` are borrowed (ref'd into the context).
+/// infinite GOP, the VUI (BT.709 limited SDR, or BT.2020 PQ limited for `ten_bit` HDR),
+/// `pix_fmt=VAAPI`, and the given hw device + frames contexts. Returns the opened encoder.
+/// `device_ref`/`frames_ref` are borrowed (ref'd into the context).
 #[allow(clippy::too_many_arguments)]
 unsafe fn open_vaapi_encoder_mode(
     codec: Codec,
@@ -169,6 +177,7 @@ unsafe fn open_vaapi_encoder_mode(
     bitrate_bps: u64,
     device_ref: *mut ffi::AVBufferRef,
     frames_ref: *mut ffi::AVBufferRef,
+    ten_bit: bool,
     low_power: bool,
 ) -> Result<encoder::video::Encoder> {
     let name = codec.vaapi_name();
@@ -181,23 +190,39 @@ unsafe fn open_vaapi_encoder_mode(
         .context("alloc video encoder")?;
     video.set_width(width);
     video.set_height(height);
-    video.set_format(Pixel::NV12); // sw view; pix_fmt overridden to VAAPI below
-                                   // Fixed rate, CBR, no B-frames, ~1-frame VBV — the shared low-latency RC contract.
+    // sw view (pix_fmt overridden to VAAPI below): NV12, or P010 for the 10-bit HDR session.
+    video.set_format(if ten_bit { Pixel::P010LE } else { Pixel::NV12 });
+    // Fixed rate, CBR, no B-frames, ~1-frame VBV — the shared low-latency RC contract.
     apply_low_latency_rc(&mut video, fps, bitrate_bps);
     let raw = video.as_mut_ptr();
     (*raw).gop_size = i32::MAX; // no periodic IDR (forced-IDR via pict_type=I on RFI)
-                                // We hand the encoder BT.709 *limited* NV12 (swscale CSC on the CPU path; scale_vaapi pinned
-                                // to `out_color_matrix=bt709:out_range=limited` on the zero-copy path, with the full-range
-                                // RGB input tagged), so signal that VUI — else the client decoder washes the picture out.
-    (*raw).colorspace = ffi::AVColorSpace::AVCOL_SPC_BT709;
-    (*raw).color_range = ffi::AVColorRange::AVCOL_RANGE_MPEG;
-    (*raw).color_primaries = ffi::AVColorPrimaries::AVCOL_PRI_BT709;
-    (*raw).color_trc = ffi::AVColorTransferCharacteristic::AVCOL_TRC_BT709;
+    if ten_bit {
+        // HDR10: BT.2020 primaries + SMPTE-2084 (PQ) transfer, limited range — matches the P010
+        // the CSC produces (swscale BT.2020 on the CPU path; scale_vaapi pinned to bt2020 on the
+        // zero-copy path). The client decoder auto-detects PQ from the VUI.
+        (*raw).colorspace = ffi::AVColorSpace::AVCOL_SPC_BT2020_NCL;
+        (*raw).color_range = ffi::AVColorRange::AVCOL_RANGE_MPEG;
+        (*raw).color_primaries = ffi::AVColorPrimaries::AVCOL_PRI_BT2020;
+        (*raw).color_trc = ffi::AVColorTransferCharacteristic::AVCOL_TRC_SMPTE2084;
+    } else {
+        // We hand the encoder BT.709 *limited* NV12 (swscale CSC on the CPU path; scale_vaapi pinned
+        // to `out_color_matrix=bt709:out_range=limited` on the zero-copy path, with the full-range
+        // RGB input tagged), so signal that VUI — else the client decoder washes the picture out.
+        (*raw).colorspace = ffi::AVColorSpace::AVCOL_SPC_BT709;
+        (*raw).color_range = ffi::AVColorRange::AVCOL_RANGE_MPEG;
+        (*raw).color_primaries = ffi::AVColorPrimaries::AVCOL_PRI_BT709;
+        (*raw).color_trc = ffi::AVColorTransferCharacteristic::AVCOL_TRC_BT709;
+    }
     (*raw).pix_fmt = ffi::AVPixelFormat::AV_PIX_FMT_VAAPI;
     (*raw).hw_device_ctx = ffi::av_buffer_ref(device_ref);
     (*raw).hw_frames_ctx = ffi::av_buffer_ref(frames_ref);
 
     let mut opts = Dictionary::new();
+    if ten_bit && codec == Codec::H265 {
+        // HEVC Main10. `hevc_vaapi` derives it from the P010 surfaces, but pin it explicitly so
+        // the depth is never silently dropped. (10-bit AV1 is input-driven — no profile knob.)
+        opts.set("profile", "main10");
+    }
     // async_depth=1: `send_frame` blocks until THIS frame's ASIC encode completes — the lowest
     // latency structure libavcodec's vaapi_encode offers. Measured on the 780M at 1440p60: depth 1
     // = 8.3 ms end-to-end p50 vs depth 2 = 18 ms, because with depth ≥ 2 frame N's packet only
@@ -242,10 +267,59 @@ pub fn probe_can_encode(codec: Codec) -> bool {
         let prev = ffi::av_log_get_level();
         ffi::av_log_set_level(ffi::AV_LOG_FATAL);
         let ok = match VaapiHw::new(ffi::AVPixelFormat::AV_PIX_FMT_NV12, 640, 480, 2) {
-            Ok(hw) => {
-                open_vaapi_encoder(codec, 640, 480, 30, 2_000_000, hw.device_ref, hw.frames_ref)
-                    .is_ok()
-            }
+            Ok(hw) => open_vaapi_encoder(
+                codec,
+                640,
+                480,
+                30,
+                2_000_000,
+                hw.device_ref,
+                hw.frames_ref,
+                false,
+            )
+            .is_ok(),
+            Err(_) => false,
+        };
+        ffi::av_log_set_level(prev);
+        ok
+    }
+}
+
+/// Probe whether the active VAAPI GPU can encode **10-bit** (HEVC Main10 / 10-bit AV1) from P010
+/// surfaces — the exact shape a live HDR session opens (P010 pool + Main10 profile + PQ VUI). The
+/// driver rejects what the video engine can't do; the result is cached by the caller
+/// ([`crate::can_encode_10bit`]), so a non-Main10 GPU resolves every session to 8-bit SDR before
+/// the Welcome (honest downgrade).
+pub fn probe_can_encode_10bit(codec: Codec) -> bool {
+    if !codec.supports_10bit() || codec == Codec::PyroWave {
+        return false;
+    }
+    if ffmpeg::init().is_err() {
+        return false;
+    }
+    // SAFETY: `ffmpeg::init()` returned Ok above, so libav is initialized. `av_log_{get,set}_level`
+    // only read/write libav's global integer log level (no pointer args). `VaapiHw::new` (an
+    // `unsafe fn`) builds a VAAPI device + P010 frames pool from the literal args and hands back a
+    // RAII handle; `open_vaapi_encoder` (an `unsafe fn`) borrows `hw.device_ref`/`hw.frames_ref` —
+    // the two non-null refs `VaapiHw::new` just created, live locals for the whole match arm — and
+    // `av_buffer_ref`s them into the probe encoder. Both `hw` and the encoder drop (RAII) at arm end.
+    unsafe {
+        // A missing VA device / no Main10 entrypoint is an expected probe outcome — quiet ffmpeg's
+        // error for the probe, then restore the level.
+        let prev = ffi::av_log_get_level();
+        ffi::av_log_set_level(ffi::AV_LOG_FATAL);
+        let ok = match VaapiHw::new(ffi::AVPixelFormat::AV_PIX_FMT_P010LE, 640, 480, 2) {
+            Ok(hw) => open_vaapi_encoder(
+                codec,
+                640,
+                480,
+                30,
+                2_000_000,
+                hw.device_ref,
+                hw.frames_ref,
+                true,
+            )
+            .is_ok(),
             Err(_) => false,
         };
         ffi::av_log_set_level(prev);
@@ -348,12 +422,21 @@ impl CpuInner {
         bitrate_bps: u64,
     ) -> Result<Self> {
         let src_pixel = vaapi_sws_src(format)?;
+        // A 10-bit HDR capture (X2RGB10/X2BGR10, PQ/BT.2020) uploads P010 and encodes Main10; the
+        // 8-bit paths keep NV12/BT.709 byte-for-byte unchanged.
+        let ten_bit = format.is_hdr_rgb10();
+        let staging_av = if ten_bit {
+            ffi::AVPixelFormat::AV_PIX_FMT_P010LE
+        } else {
+            ffi::AVPixelFormat::AV_PIX_FMT_NV12
+        };
         const POOL: c_int = 16;
         // SAFETY: `VaapiHw::new` (an `unsafe fn`) requires libav initialized — guaranteed because the
         // only path here is `VaapiEncoder::open` → `ensure_inner` → `CpuInner::open`, and `open` ran
-        // `ffmpeg::init()`. The args are valid: NV12 sw_format, the validated positive `width`/`height`,
-        // pool=16. It returns a RAII `VaapiHw` that unrefs its two `AVBufferRef`s on drop.
-        let hw = unsafe { VaapiHw::new(ffi::AVPixelFormat::AV_PIX_FMT_NV12, width, height, POOL)? };
+        // `ffmpeg::init()`. The args are valid: an NV12/P010 sw_format, the validated positive
+        // `width`/`height`, pool=16. It returns a RAII `VaapiHw` that unrefs its two `AVBufferRef`s
+        // on drop.
+        let hw = unsafe { VaapiHw::new(staging_av, width, height, POOL)? };
         // SAFETY: `open_vaapi_encoder` (an `unsafe fn`) borrows `hw.device_ref`/`hw.frames_ref` — both
         // non-null (`VaapiHw::new` guarantees it) and from the `hw` just built above, which is a live
         // local that outlives this synchronous call. The fn `av_buffer_ref`s them into the encoder, so
@@ -368,16 +451,19 @@ impl CpuInner {
                 bitrate_bps,
                 hw.device_ref,
                 hw.frames_ref,
+                ten_bit,
             )?
         };
-        // swscale RGB→NV12, BT.709 limited (matches the VUI), no rescale.
+        // swscale RGB→NV12 (BT.709 limited) or X2RGB10→P010 (BT.2020 limited, HDR) — matches the
+        // VUI; no rescale.
         let src_av = pixel_to_av(src_pixel);
         // SAFETY: `sws_getContext` allocates a swscale context for the given src/dst dimensions and
         // pixel formats. All four dims are the encoder's positive `width`/`height` cast to `c_int`;
         // `src_av` is a valid `AVPixelFormat` (from `pixel_to_av` of the `vaapi_sws_src`-validated
-        // `src_pixel`), the dst is NV12. The three trailing pointers (srcFilter, dstFilter, param) are
-        // explicitly null = "use defaults", which the API documents as accepted. No Rust memory is
-        // borrowed — only by-value ints/enums — and the returned pointer is null-checked just below.
+        // `src_pixel`), the dst is NV12/P010. The three trailing pointers (srcFilter, dstFilter,
+        // param) are explicitly null = "use defaults", which the API documents as accepted. No Rust
+        // memory is borrowed — only by-value ints/enums — and the returned pointer is null-checked
+        // just below.
         let sws = unsafe {
             ffi::sws_getContext(
                 width as c_int,
@@ -385,7 +471,7 @@ impl CpuInner {
                 src_av,
                 width as c_int,
                 height as c_int,
-                ffi::AVPixelFormat::AV_PIX_FMT_NV12,
+                staging_av,
                 SWS_POINT,
                 ptr::null_mut(),
                 ptr::null_mut(),
@@ -393,45 +479,54 @@ impl CpuInner {
             )
         };
         if sws.is_null() {
-            bail!("sws_getContext(RGB→NV12) failed");
+            bail!(
+                "sws_getContext(RGB→{})",
+                if ten_bit { "P010" } else { "NV12" }
+            );
         }
         // SAFETY: `sws` is the non-null `SwsContext` from `sws_getContext` above (the `is_null()`
-        // check immediately preceding returned false). `sws_getCoefficients(SWS_CS_ITU709)` returns a
-        // pointer into a libswscale static const coefficient table valid for the whole process, reused
-        // here for both the inverse (src) and forward (dst) matrices. `sws_setColorspaceDetails` only
-        // reads those tables and writes scalar CSC settings into `sws`; the table pointer outlives the
-        // synchronous call and no Rust memory is passed.
+        // check immediately preceding returned false). The coefficient table from
+        // `sws_getCoefficients` (ITU-709, or BT.2020 NCL for the HDR path — matching the VUI) is a
+        // libswscale static const valid for the whole process, reused here for both the inverse
+        // (src) and forward (dst) matrices. `sws_setColorspaceDetails` only reads those tables and
+        // writes scalar CSC settings into `sws`; the table pointer outlives the synchronous call and
+        // no Rust memory is passed.
         unsafe {
-            let cs709 = ffi::sws_getCoefficients(SWS_CS_ITU709);
-            ffi::sws_setColorspaceDetails(sws, cs709, 1, cs709, 0, 0, 1 << 16, 1 << 16);
+            let cs = ffi::sws_getCoefficients(if ten_bit {
+                super::libav::SWS_CS_BT2020
+            } else {
+                SWS_CS_ITU709
+            });
+            ffi::sws_setColorspaceDetails(sws, cs, 1, cs, 0, 0, 1 << 16, 1 << 16);
         }
         // SAFETY: `av_frame_alloc` returns a fresh, uniquely-owned heap `AVFrame` (null-checked — on
         // null we free the already-built `sws` and bail). We then write the plain `format`/`width`/
         // `height` fields through the non-null, properly-aligned `f` (sole owner, not yet shared).
         // `av_frame_get_buffer(f, 0)` allocates backing storage for those dims/format; on failure we
         // free `f` and `sws` (unwinding the half-built state) and bail. On success `f` is a fully-owned
-        // NV12 frame stored in `CpuInner.nv12` and freed once in `CpuInner::drop`. `f` is a unique
-        // fresh pointer, so none of these writes alias anything.
+        // NV12/P010 frame stored in `CpuInner.nv12` and freed once in `CpuInner::drop`. `f` is a
+        // unique fresh pointer, so none of these writes alias anything.
         let nv12 = unsafe {
             let f = ffi::av_frame_alloc();
             if f.is_null() {
                 ffi::sws_freeContext(sws);
-                bail!("av_frame_alloc(NV12) failed");
+                bail!("av_frame_alloc(staging) failed");
             }
-            (*f).format = ffi::AVPixelFormat::AV_PIX_FMT_NV12 as c_int;
+            (*f).format = staging_av as c_int;
             (*f).width = width as c_int;
             (*f).height = height as c_int;
             if ffi::av_frame_get_buffer(f, 0) < 0 {
                 let mut f = f;
                 ffi::av_frame_free(&mut f);
                 ffi::sws_freeContext(sws);
-                bail!("av_frame_get_buffer(NV12) failed");
+                bail!("av_frame_get_buffer(staging) failed");
             }
             f
         };
         tracing::info!(
             encoder = codec.vaapi_name(),
-            "VAAPI encode active ({width}x{height}@{fps}, CPU→NV12 upload path)"
+            "VAAPI encode active ({width}x{height}@{fps}, CPU→{} upload path)",
+            if ten_bit { "P010 (HDR10)" } else { "NV12" }
         );
         Ok(CpuInner {
             enc,
@@ -563,6 +658,15 @@ impl DmabufInner {
     ) -> Result<Self> {
         let drm_fourcc = pf_frame::drm_fourcc(format)
             .ok_or_else(|| anyhow!("no DRM fourcc for {format:?} (VAAPI zero-copy)"))?;
+        // A 10-bit HDR capture (X2RGB10/X2BGR10 dmabufs, PQ/BT.2020) maps + CSCs to P010 and
+        // encodes Main10; the 8-bit paths keep the NV12/BT.709 graph byte-for-byte unchanged.
+        let ten_bit = format.is_hdr_rgb10();
+        let sw_format = match format {
+            PixelFormat::X2Rgb10 => ffi::AVPixelFormat::AV_PIX_FMT_X2RGB10LE,
+            PixelFormat::X2Bgr10 => ffi::AVPixelFormat::AV_PIX_FMT_X2BGR10LE,
+            // The 8-bit capture formats are all XR24-shaped packed RGB (the historical BGR0 view).
+            _ => ffi::AVPixelFormat::AV_PIX_FMT_BGR0,
+        };
         let node = render_node();
         // SAFETY: libav is initialized (`VaapiEncoder::open` ran `ffmpeg::init()` before
         // `ensure_inner` → `DmabufInner::open`). Every raw pointer dereferenced below is either freshly
@@ -628,7 +732,7 @@ impl DmabufInner {
             }
             let fc = (*drm_frames).data as *mut ffi::AVHWFramesContext;
             (*fc).format = ffi::AVPixelFormat::AV_PIX_FMT_DRM_PRIME;
-            (*fc).sw_format = ffi::AVPixelFormat::AV_PIX_FMT_BGR0; // packed XR24 RGB plane
+            (*fc).sw_format = sw_format; // packed XR24 RGB plane, or XR30/XB30 for HDR
             (*fc).width = width as c_int;
             (*fc).height = height as c_int;
             if ffi::av_hwframe_ctx_init(drm_frames) < 0 {
@@ -715,14 +819,24 @@ impl DmabufInner {
             }
             init!(src, ptr::null(), "buffer");
             init!(hwmap, c"mode=read".as_ptr(), "hwmap");
-            // Pin the VPP's output colour to what the encoder's VUI signals (BT.709 limited).
-            // Without the explicit options the conversion matrix is whatever the driver defaults
-            // to for an unspecified output (Mesa: BT.601) — a hue shift against the signaled VUI.
-            init!(
-                scale,
-                c"format=nv12:out_color_matrix=bt709:out_range=limited".as_ptr(),
-                "scale_vaapi"
-            );
+            // Pin the VPP's output colour to what the encoder's VUI signals (BT.709 limited SDR,
+            // or BT.2020 limited P010 for HDR — the PQ transfer is per-channel and rides through
+            // the matrix untouched). Without the explicit options the conversion matrix is
+            // whatever the driver defaults to for an unspecified output (Mesa: BT.601) — a hue
+            // shift against the signaled VUI.
+            if ten_bit {
+                init!(
+                    scale,
+                    c"format=p010:out_color_matrix=bt2020:out_range=limited".as_ptr(),
+                    "scale_vaapi"
+                );
+            } else {
+                init!(
+                    scale,
+                    c"format=nv12:out_color_matrix=bt709:out_range=limited".as_ptr(),
+                    "scale_vaapi"
+                );
+            }
             init!(sink, ptr::null(), "buffersink");
 
             let link = |a: *mut ffi::AVFilterContext, b: *mut ffi::AVFilterContext| -> c_int {
@@ -766,6 +880,7 @@ impl DmabufInner {
                 bitrate_bps,
                 vaapi_device,
                 nv12_ctx,
+                ten_bit,
             ) {
                 Ok(enc) => enc,
                 Err(e) => {
@@ -779,7 +894,8 @@ impl DmabufInner {
 
             tracing::info!(
                 encoder = codec.vaapi_name(),
-                "VAAPI encode active ({width}x{height}@{fps}, zero-copy dmabuf → GPU NV12)"
+                "VAAPI encode active ({width}x{height}@{fps}, zero-copy dmabuf → GPU {})",
+                if ten_bit { "P010 (HDR10)" } else { "NV12" }
             );
             Ok(DmabufInner {
                 enc,
@@ -987,8 +1103,22 @@ impl VaapiEncoder {
         bit_depth: u8,
         chroma: super::ChromaFormat,
     ) -> Result<Self> {
-        if bit_depth != 8 {
-            tracing::warn!(bit_depth, "VAAPI 10-bit not yet wired — encoding 8-bit");
+        // 10-bit rides on the captured format: an HDR capture (X2RGB10/X2BGR10) opens the P010 /
+        // Main10 / PQ-VUI variant of whichever inner path the first frame selects. A 10-bit
+        // request whose capture stayed SDR honestly encodes 8-bit; the reverse (PQ frames on an
+        // 8-bit session) is refused so PQ content is never mislabeled BT.709.
+        if format.is_hdr_rgb10() && bit_depth != 10 {
+            bail!(
+                "captured 10-bit HDR frames ({format:?}) on an {bit_depth}-bit VAAPI session — \
+                 refusing to mislabel PQ content"
+            );
+        }
+        if bit_depth == 10 && !format.is_hdr_rgb10() {
+            tracing::warn!(
+                bit_depth,
+                ?format,
+                "10-bit requested but the capture stayed SDR — encoding 8-bit"
+            );
         }
         // VAAPI 4:4:4 is deferred (see `probe_can_encode_444`): no validated AMD/Intel hardware in the
         // lab exposes a HEVC 4:4:4 encode entrypoint, and the probe returns false so the host never

crates/pf-encode/src/enc/linux/vulkan_video.rs

@@ -1851,7 +1851,20 @@ impl VulkanVideoEncoder {
         let f = &self.frames[slot];
         let mut fb = [[0u32; 2]; 1];
         dev.get_query_pool_results(f.query_pool, 0, &mut fb, vk::QueryResultFlags::WAIT)?;
-        let (off, len) = (fb[0][0] as usize, fb[0][1] as usize);
+        // The (offset, bytes-written) pair is driver-reported: validate it against the bitstream
+        // allocation BEFORE mapping, or the `from_raw_parts` below reads outside the buffer and
+        // ships whatever it finds straight onto the wire. Checked in u64 so the add cannot wrap,
+        // and before `map_memory` so there is no unmap to unwind on the error path.
+        let (off64, len64) = (fb[0][0] as u64, fb[0][1] as u64);
+        if off64.saturating_add(len64) > self.bs_size {
+            anyhow::bail!(
+                "vulkan-encode: driver reported bitstream feedback offset={off64} \
+                 bytes_written={len64}, outside the {} byte bitstream buffer — the encode likely \
+                 overflowed its destination range",
+                self.bs_size
+            );
+        }
+        let (off, len) = (off64 as usize, len64 as usize);
         let p =
             dev.map_memory(f.bs_mem, 0, vk::WHOLE_SIZE, vk::MemoryMapFlags::empty())? as *const u8;
         let prefix: &[u8] = if f.keyframe {
@@ -1923,7 +1936,28 @@ impl Encoder for VulkanVideoEncoder {
         if first_frame < 0 || first_frame > last_frame {
             return false;
         }
+        // Taint sweep BEFORE picking the anchor (the fecbec2d fix AMF and QSV got; this backend was
+        // carved out one commit later and never received it). "Resident and older than THIS loss" is
+        // not the same as "the client decoded it": after an earlier loss [a,b] was recovered at wire
+        // r, everything in [a, r-1] is undecodable at the client — the lost frames plus every frame
+        // that predicted through the gap. Those wires stay valid anchor candidates here until the
+        // 8-slot ring rolls them out, so a LATER loss can anchor on one and ship corruption tagged
+        // `recovery_anchor` — which is the client's definitive re-anchor signal (reanchor.rs), so it
+        // lifts the post-loss freeze onto a picture built from a reference it never had.
+        //
+        // Blank `slot_wire` ONLY. `slot_poc` must keep naming every physically-resident DPB picture
+        // for `build_h265_rps_s0`, or a conforming decoder evicts them and the anchor references a
+        // picture the client already dropped. `slot_wire` is the RFI/loss domain; `slot_poc` is the
+        // reference-delta domain. `prev_slot` and the normal P-frame path are indices, not wires, so
+        // ordinary prediction is unaffected.
+        for w in self.slot_wire.iter_mut() {
+            if *w >= first_frame {
+                *w = -1;
+            }
+        }
         // Can we anchor a clean P-frame to a resident slot strictly older than the loss?
+        // (A sweep that empties every candidate yields `None` here and declines the RFI, matching
+        // `qsv_live_ltr_rfi_taint_sweep_declines`.)
         match pick_recovery_slot(&self.slot_wire, first_frame) {
             Some(_) => {
                 self.pending_loss = Some(first_frame);
@@ -2697,6 +2731,62 @@ mod tests {
         assert_eq!(pick_recovery_slot(&[-1; 8], 5), None);
     }
 
+    /// The taint sweep (fecbec2d's fix, ported here): a slot encoded inside an EARLIER, still
+    /// unrepaired loss window must not become the "known-good" anchor of a LATER loss. Without the
+    /// sweep, `pick_recovery_slot` accepts it — it is resident and its wire is below the second
+    /// loss start — and the frame ships tagged `recovery_anchor`, lifting the client's freeze onto
+    /// a reference it never decoded.
+    #[test]
+    fn taint_sweep_excludes_slots_from_an_earlier_loss() {
+        // Apply the sweep exactly as `invalidate_ref_frames` does.
+        fn sweep(wires: &mut [i64], loss_first: i64) {
+            for w in wires.iter_mut() {
+                if *w >= loss_first {
+                    *w = -1;
+                }
+            }
+        }
+
+        // Slots hold wires 0..7. Loss 1 starts at wire 4, so wires 4..7 are undecodable at the
+        // client. A second loss report arrives at wire 6 while they are all still resident.
+        let tainted = [4i64, 5, 6, 7];
+
+        // WITHOUT the sweep this is the bug: the newest wire below 6 is wire 5 — squarely inside
+        // loss 1's unrepaired window — and it would be served as the "known-good" anchor.
+        let unswept = [0i64, 1, 2, 3, 4, 5, 6, 7];
+        let picked = pick_recovery_slot(&unswept, 6).expect("unswept picks something");
+        assert!(
+            tainted.contains(&unswept[picked]),
+            "precondition: without the sweep the anchor comes from the earlier loss window"
+        );
+
+        // WITH the sweep, loss 1 blanks 4..7, so loss 2 can only reach genuinely clean wires.
+        let mut wires = unswept;
+        sweep(&mut wires, 4);
+        assert_eq!(wires, [0, 1, 2, 3, -1, -1, -1, -1]);
+        let picked = pick_recovery_slot(&wires, 6).expect("clean wires remain");
+        assert_eq!(picked, 3, "newest clean survivor is wire 3");
+        assert!(!tainted.contains(&wires[picked]));
+
+        // Encoding resumes after recovery; wires 8..11 refill the swept slots and are clean. A
+        // later loss at wire 10 legitimately anchors on wire 9 — the sweep must not over-reject.
+        wires[4] = 8;
+        wires[5] = 9;
+        wires[6] = 10;
+        wires[7] = 11;
+        sweep(&mut wires, 10);
+        assert_eq!(
+            pick_recovery_slot(&wires, 10),
+            Some(5),
+            "wire 9 is post-recovery, clean"
+        );
+
+        // A loss covering every live wire leaves nothing clean → decline, caller serves an IDR.
+        let mut all = [5i64, 6, 7, 8, 9, 10, 11, 12];
+        sweep(&mut all, 5);
+        assert_eq!(pick_recovery_slot(&all, 5), None);
+    }
+
     /// The full-retention RPS: every resident picture is listed (so the decoder keeps it), the
     /// setup slot's dying occupant is not, and `used_by_curr_pic` marks exactly the real reference.
     #[test]

crates/pf-encode/src/enc/pyrowave_wire.rs

@@ -0,0 +1,268 @@
+//! Shared PyroWave AU wire-framing (design/pyrowave-codec-plan.md §4.4) — the single source of
+//! truth for the on-wire access-unit shape, used by BOTH the Linux (dmabuf/CSC) and Windows (NV12
+//! zero-copy) host encoders. It turns pyrowave's packetized bitstream into either the **dense**
+//! single-packet AU or the **datagram-aligned** windowed AU. Pure (no GPU/FFI) so it is unit-tested
+//! on any platform and both encoders emit byte-identical framing — the clients parse this exact
+//! layout, so it must stay in ONE place.
+//!
+//! Datagram-aligned AU: each `chunk`-sized window opens with a 4-byte prefix (`u16` used-length +
+//! `u16` kind) and carries either WHOLE self-delimiting codec packets (`WIN_PACKED` — several small
+//! ones share a window) or one fragment of an oversized ATOMIC packet (a `FRAG` chain — pyrowave's
+//! 32×32 blocks are atomic and can exceed a shard). A lost shard zeroes its window (`used = 0`) so
+//! the receiver skips it and drops any fragment chain it interrupts. Padding after `used` is zeroed.
+
+/// The 4-byte per-window framing prefix (`u16` used-length + `u16` kind).
+pub(crate) const WINDOW_PREFIX: usize = 4;
+/// Window kinds: whole packets / an oversized packet's fragments.
+const WIN_PACKED: u16 = 0;
+const WIN_FRAG_FIRST: u16 = 1;
+const WIN_FRAG_CONT: u16 = 2;
+const WIN_FRAG_LAST: u16 = 3;
+
+/// The packetize boundary to request from pyrowave: for a `wire_chunk` shard it is the shard payload
+/// minus the 4-byte window prefix (so a whole codec packet + its prefix fits one shard); for the
+/// dense case it is the whole-bitstream cap (one packet per AU).
+pub(crate) fn packet_boundary(wire_chunk: Option<usize>, dense_cap: usize) -> usize {
+    wire_chunk.map(|c| c - WINDOW_PREFIX).unwrap_or(dense_cap)
+}
+
+/// Patch the frame's `BitstreamSequenceHeader` to signal `ycbcr_range = LIMITED`. pyrowave's C API
+/// fills the header with `= {}` (all VUI fields zeroed) and offers NO way to set colour/range, so it
+/// signals `ycbcr_range = 0 = YCBCR_RANGE_FULL` — but BOTH host CSCs (`rgb2yuv.comp` on Linux, the
+/// D3D11 `BgraToYuvPlanes` on Windows) always emit BT.709 **LIMITED** Y′CbCr (black = Y′16). A client
+/// that honours the VUI (the Apple wavelet decoder reads `(word1 >> 30) & 1`) then skips the
+/// limited→full expansion and shows washed-out, raised blacks. Patching the bit makes the bitstream
+/// HONEST for every client — clients that hardcode limited (the Vulkan `video_pyrowave` path) are
+/// unaffected, and pyrowave's own decode ignores the flag (it reconstructs raw Y′CbCr). The other
+/// zeroed VUI fields (BT.709 primaries / transform / transfer) are already correct.
+///
+/// `seq_offset` is the byte offset of the frame's 8-byte `BitstreamSequenceHeader` in `bitstream` —
+/// the SOF packet's offset. The colour bits live in the little-endian second word's top byte
+/// (`seq_offset + 7`): `color_primaries` bit 27 (`0x08`), `transfer_function` bit 28 (`0x10`),
+/// `ycbcr_transform` bit 29 (`0x20`), `ycbcr_range` bit 30 (`0x40`); `chroma_siting` bit 31 stays 0
+/// (CENTER — the pyrowave CSCs use the centre-sited 2×2 box, unlike the left-cosited P010 path).
+/// Range is ALWAYS stamped LIMITED (both CSCs emit studio range); `bt2020_pq` additionally stamps
+/// BT.2020 primaries + PQ transfer + BT.2020 matrix — upstream's own enum semantics
+/// (`pyrowave_common.hpp`), matching the session's negotiated `ColorInfo`.
+pub(crate) fn stamp_color_bits(bitstream: &mut [u8], seq_offset: usize, bt2020_pq: bool) {
+    if let Some(b) = bitstream.get_mut(seq_offset + 7) {
+        *b |= 0x40;
+        if bt2020_pq {
+            *b |= 0x08 | 0x10 | 0x20;
+        }
+    }
+}
+
+/// The wavelet block space's total 32x32-block count for a mode — the exact counting walk of
+/// upstream `WaveletBuffers::init_block_meta` (also ported to the Apple `WaveletLayout`, whose
+/// golden tests pin it against real host AUs). Needed because the vendored RDO pass packs the
+/// block index into 16 bits (`RDOperation.block_offset_saving` — see
+/// `patches/0002-rdo-saving-clamp.patch`): a mode whose count exceeds `u16::MAX` would wrap
+/// inside the rate controller, so the host guards such modes out (≈8K 4:4:4 territory).
+pub(crate) fn block_count_32x32(width: u32, height: u32, chroma444: bool) -> u32 {
+    const LEVELS: u32 = 5;
+    let align = |v: u32| ((v + 31) & !31).max(128);
+    let (aw, ah) = (align(width), align(height));
+    let mut count = 0u32;
+    for level in (0..LEVELS).rev() {
+        let lw = (aw / 2) >> level;
+        let lh = (ah / 2) >> level;
+        let blocks_x8 = lw.div_ceil(8);
+        let blocks_y8 = lh.div_ceil(8);
+        let per_band = blocks_x8.div_ceil(4) * blocks_y8.div_ceil(4);
+        let bands = if level == LEVELS - 1 { 4 } else { 3 };
+        for component in 0..3u32 {
+            if level == 0 && component != 0 && !chroma444 {
+                continue;
+            }
+            count += per_band * bands;
+        }
+    }
+    count
+}
+
+/// Frame pyrowave's `packets` (each an `(offset, size)` into `bitstream`) into the wire AU.
+/// `wire_chunk = None` copies the single dense packet; `Some(chunk)` produces the windowed
+/// datagram-aligned AU (a whole number of `chunk`-sized windows).
+pub(crate) fn build_au(
+    packets: &[(usize, usize)],
+    bitstream: &[u8],
+    wire_chunk: Option<usize>,
+) -> Vec<u8> {
+    let Some(chunk) = wire_chunk else {
+        // Dense (default): boundary == whole buffer → the AU is exactly one pyrowave packet.
+        let (off, size) = packets[0];
+        return bitstream[off..off + size].to_vec();
+    };
+    let payload_max = chunk - WINDOW_PREFIX;
+    let mut au: Vec<u8> = Vec::with_capacity((packets.len() + 1) * chunk);
+    // The currently-open PACKED window: (start offset of its prefix, bytes used).
+    let mut open: Option<(usize, usize)> = None;
+    let close = |au: &mut Vec<u8>, open: &mut Option<(usize, usize)>, chunk: usize| {
+        if let Some((start, used)) = open.take() {
+            au[start..start + 2].copy_from_slice(&(used as u16).to_le_bytes());
+            au[start + 2..start + 4].copy_from_slice(&WIN_PACKED.to_le_bytes());
+            au.resize(start + chunk, 0);
+        }
+    };
+    for &(off, size) in packets {
+        let bytes = &bitstream[off..off + size];
+        if size <= payload_max {
+            let fits = open.is_some_and(|(_, used)| used + size <= payload_max);
+            if !fits {
+                close(&mut au, &mut open, chunk);
+                let start = au.len();
+                au.resize(start + WINDOW_PREFIX, 0);
+                open = Some((start, 0));
+            }
+            au.extend_from_slice(bytes);
+            if let Some((_, used)) = open.as_mut() {
+                *used += size;
+            }
+        } else {
+            // Oversized packet: its own FRAG chain of full windows.
+            close(&mut au, &mut open, chunk);
+            let mut o = 0usize;
+            while o < size {
+                let take = (size - o).min(payload_max);
+                let kind = if o == 0 {
+                    WIN_FRAG_FIRST
+                } else if o + take == size {
+                    WIN_FRAG_LAST
+                } else {
+                    WIN_FRAG_CONT
+                };
+                let start = au.len();
+                au.resize(start + WINDOW_PREFIX, 0);
+                au[start..start + 2].copy_from_slice(&(take as u16).to_le_bytes());
+                au[start + 2..start + 4].copy_from_slice(&kind.to_le_bytes());
+                au.extend_from_slice(&bytes[o..o + take]);
+                au.resize(start + chunk, 0);
+                o += take;
+            }
+        }
+    }
+    close(&mut au, &mut open, chunk);
+    au
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Walk a windowed AU back into the flat codec-packet stream (the client's parse), asserting the
+    /// framing invariants the encoder promises: whole windows, in-bounds `used`, zeroed padding.
+    fn walk(au: &[u8], chunk: usize) -> Vec<u8> {
+        assert_eq!(au.len() % chunk, 0, "AU is a whole number of windows");
+        let mut out = Vec::new();
+        let mut frag: Vec<u8> = Vec::new();
+        for win in au.chunks(chunk) {
+            let used = u16::from_le_bytes([win[0], win[1]]) as usize;
+            let kind = u16::from_le_bytes([win[2], win[3]]);
+            assert!(WINDOW_PREFIX + used <= win.len(), "window overrun");
+            assert!(
+                win[WINDOW_PREFIX + used..].iter().all(|&b| b == 0),
+                "non-zero padding after used"
+            );
+            let body = &win[WINDOW_PREFIX..WINDOW_PREFIX + used];
+            match kind {
+                0 => out.extend_from_slice(body),
+                1 => frag = body.to_vec(),
+                2 => frag.extend_from_slice(body),
+                3 => {
+                    frag.extend_from_slice(body);
+                    out.extend_from_slice(&frag);
+                    frag.clear();
+                }
+                k => panic!("unknown window kind {k}"),
+            }
+        }
+        out
+    }
+
+    #[test]
+    fn dense_is_the_single_packet() {
+        let bs = (0u8..=200).collect::<Vec<u8>>();
+        let au = build_au(&[(10, 50)], &bs, None);
+        assert_eq!(au, bs[10..60]);
+    }
+
+    #[test]
+    fn packed_windows_pack_small_packets_and_reconstruct() {
+        // Three small packets that share windows; walking must reproduce them concatenated in order.
+        let bs: Vec<u8> = (0..255u32).map(|i| i as u8).collect();
+        let packets = [(0, 20), (20, 20), (40, 100)];
+        let chunk = 64; // payload_max = 60
+        let au = build_au(&packets, &bs, Some(chunk));
+        let flat = walk(&au, chunk);
+        let mut expect = Vec::new();
+        for &(o, s) in &packets {
+            expect.extend_from_slice(&bs[o..o + s]);
+        }
+        assert_eq!(flat, expect);
+    }
+
+    #[test]
+    fn oversized_packet_fragments_and_reassembles() {
+        // One atomic packet larger than a window → a FRAG chain the walk reassembles exactly.
+        let bs: Vec<u8> = (0..1000u32).map(|i| i as u8).collect();
+        let chunk = 64; // payload_max = 60
+        let au = build_au(&[(0, 500)], &bs, Some(chunk));
+        assert_eq!(walk(&au, chunk), bs[0..500]);
+    }
+
+    #[test]
+    fn boundary_reserves_the_window_prefix() {
+        assert_eq!(packet_boundary(Some(1408), 999_999), 1404);
+        assert_eq!(packet_boundary(None, 777), 777);
+    }
+
+    #[test]
+    fn block_count_matches_the_apple_layout_invariant() {
+        // 256x144 (the golden-fixture geometry, aligned 256x160): recompute via the same walk
+        // the validated Apple WaveletLayout uses and pin a few mode-level facts.
+        let manual = |w: u32, h: u32, c444: bool| {
+            let align = |v: u32| ((v + 31) & !31).max(128);
+            let (aw, ah) = (align(w), align(h));
+            let mut n = 0u32;
+            for level in (0..5u32).rev() {
+                let per = (((aw / 2) >> level).div_ceil(8).div_ceil(4))
+                    * (((ah / 2) >> level).div_ceil(8).div_ceil(4));
+                let bands = if level == 4 { 4 } else { 3 };
+                for c in 0..3 {
+                    if level == 0 && c != 0 && !c444 {
+                        continue;
+                    }
+                    n += per * bands;
+                }
+            }
+            n
+        };
+        for (w, h) in [(256, 144), (1920, 1080), (3840, 2160), (7680, 4320)] {
+            assert_eq!(block_count_32x32(w, h, false), manual(w, h, false));
+            assert_eq!(block_count_32x32(w, h, true), manual(w, h, true));
+        }
+        // 4:4:4 fits comfortably at 4K; the 16-bit RDO block index wraps around 8K 4:4:4.
+        assert!(block_count_32x32(3840, 2160, true) <= u16::MAX as u32);
+        assert!(block_count_32x32(7680, 4320, true) > u16::MAX as u32);
+        assert!(block_count_32x32(7680, 4320, false) <= u16::MAX as u32);
+    }
+
+    #[test]
+    fn stamp_color_bits_sets_range_and_hdr_bits() {
+        let mut bs = vec![0u8; 16];
+        stamp_color_bits(&mut bs, 0, false);
+        // ycbcr_range = bit 30 of the LE second word = bit 6 of byte 7 (0x40); nothing else touched.
+        assert_eq!(bs[7], 0x40);
+        assert!(bs[..7].iter().all(|&b| b == 0));
+        assert!(bs[8..].iter().all(|&b| b == 0));
+        // Idempotent; an out-of-range offset is a silent no-op (never panics).
+        stamp_color_bits(&mut bs, 0, false);
+        assert_eq!(bs[7], 0x40);
+        stamp_color_bits(&mut bs, 100, false);
+        // HDR adds BT.2020 primaries (0x08) + PQ transfer (0x10) + BT.2020 matrix (0x20);
+        // chroma_siting (0x80) stays CENTER.
+        stamp_color_bits(&mut bs, 0, true);
+        assert_eq!(bs[7], 0x78);
+    }
+}

crates/pf-encode/src/enc/sw.rs

@@ -181,10 +181,13 @@ impl Encoder for OpenH264Encoder {
             PixelFormat::Bgr => (3, 2, 1, 0),
             PixelFormat::Rgba | PixelFormat::Rgbx => (4, 0, 1, 2),
             PixelFormat::Bgra | PixelFormat::Bgrx => (4, 2, 1, 0),
-            // 10-bit HDR comes only from the GPU NVENC path; the software 8-bit H.264 encoder
-            // can't represent it (and never receives it — the capturer pairs Rgb10a2 with NVENC).
-            PixelFormat::Rgb10a2 => {
-                anyhow::bail!("software H.264 encoder cannot encode 10-bit HDR (Rgb10a2)")
+            // 10-bit HDR comes only from the GPU paths; the software 8-bit H.264 encoder can't
+            // represent it (and never receives it — HDR is never negotiated on a software host).
+            PixelFormat::Rgb10a2 | PixelFormat::X2Rgb10 | PixelFormat::X2Bgr10 => {
+                anyhow::bail!(
+                    "software H.264 encoder cannot encode 10-bit HDR ({:?})",
+                    self.src_format
+                )
             }
             // NV12/P010 are GPU-resident video-processor outputs for the NVENC path; the software
             // encoder never receives them (it only gets CPU RGB frames).

crates/pf-encode/src/enc/windows/amf.rs

@@ -2077,9 +2077,15 @@ impl Encoder for AmfEncoder {
             }
             // Apply a queued force (from invalidate_ref_frames / the test hook) to THIS frame: it
             // becomes the clean re-anchor P-frame the client lifts its post-loss freeze on.
+            // Guard against a slot the taint sweep emptied since the force was queued: the
+            // HARDWARE slot still holds the tainted mark, so forcing it would re-reference the
+            // very corruption being recovered from — and the frame must not ship tagged
+            // `recovery_anchor` either (the client lifts its post-loss freeze on that tag).
             if let Some(slot) = self.pending_force.take() {
-                force_slot = Some(slot);
-                recovery_anchor = true;
+                if self.ltr_slots[slot].is_some() {
+                    force_slot = Some(slot);
+                    recovery_anchor = true;
+                }
             }
             // Mark cadence: refresh a long-term reference on every IDR and every `ltr_mark_interval`
             // frames — but never on the recovery frame itself (marking rotates `next_ltr_slot` and
@@ -2363,6 +2369,16 @@ impl Encoder for AmfEncoder {
         if !self.ltr_active || first < 0 || first > last {
             return false;
         }
+        // Taint sweep BEFORE picking the anchor: an LTR marked at-or-after the loss start was
+        // encoded inside the client's corrupt window — the client either never received it or
+        // decoded it against a broken reference chain. Serving it as "known-good" on a LATER
+        // loss ships corruption as the recovery anchor (and every subsequent mark re-samples
+        // it). Dropped slots stay dropped; the cadence re-marks a clean frame within ~1/4 s.
+        for marked in self.ltr_slots.iter_mut() {
+            if marked.is_some_and(|idx| idx >= first) {
+                *marked = None;
+            }
+        }
         // Pick the newest LTR strictly OLDER than the loss: the most recent known-good reference the
         // client still holds, so re-referencing it costs the least (smallest recovery-frame residual).
         // `ltr_slots` store the WIRE frame index of the marked frame (`submit_indexed` pins
@@ -2391,6 +2407,9 @@ impl Encoder for AmfEncoder {
                 true
             }
             None => {
+                // The sweep may have emptied the slot an earlier (un-consumed) force pointed
+                // at — clear it so the next submit can't force-reference a tainted hardware slot.
+                self.pending_force = None;
                 tracing::info!(
                     first,
                     last,
@@ -2788,6 +2807,7 @@ mod tests {
                 payload: FramePayload::D3d11(pf_frame::dxgi::D3d11Frame {
                     texture: tex.clone(),
                     device: device.clone(),
+                    pyro: None,
                 }),
                 cursor: None,
             };
@@ -2973,6 +2993,7 @@ mod tests {
                         payload: FramePayload::D3d11(pf_frame::dxgi::D3d11Frame {
                             texture: tex.clone(),
                             device: device.clone(),
+                            pyro: None,
                         }),
                         cursor: None,
                     };
@@ -3114,6 +3135,7 @@ mod tests {
                 payload: FramePayload::D3d11(pf_frame::dxgi::D3d11Frame {
                     texture: tex.clone(),
                     device: device.clone(),
+                    pyro: None,
                 }),
                 cursor: None,
             };
@@ -3261,6 +3283,7 @@ mod tests {
                 payload: FramePayload::D3d11(pf_frame::dxgi::D3d11Frame {
                     texture: tex.clone(),
                     device: device.clone(),
+                    pyro: None,
                 }),
                 cursor: None,
             };

crates/pf-encode/src/enc/windows/ffmpeg_win.rs

@@ -136,7 +136,15 @@ fn sws_src(format: PixelFormat) -> Result<Pixel> {
         PixelFormat::Rgba => Pixel::RGBA,
         PixelFormat::Rgb => Pixel::RGB24,
         PixelFormat::Bgr => Pixel::BGR24,
-        PixelFormat::Nv12 | PixelFormat::P010 | PixelFormat::Rgb10a2 | PixelFormat::Yuv444 => {
+        // X2Rgb10/X2Bgr10 are the Linux GNOME 50 HDR screencast formats — the Windows HDR path
+        // stays Rgb10a2/P010, so they can't reach this capture-side conversion. Listed explicitly
+        // (not via `_`) so the next PixelFormat addition breaks this match again on purpose.
+        PixelFormat::Nv12
+        | PixelFormat::P010
+        | PixelFormat::Rgb10a2
+        | PixelFormat::Yuv444
+        | PixelFormat::X2Rgb10
+        | PixelFormat::X2Bgr10 => {
             bail!("ffmpeg_win swscale path supports packed RGB/BGR only; got {format:?}")
         }
     })

crates/pf-encode/src/enc/windows/nvenc.rs

@@ -1135,7 +1135,19 @@ impl Encoder for NvencD3d11Encoder {
                 self.chroma_444 = false;
             }
             let device = frame.device.clone();
-            self.init_session(&device)?;
+            // `init_session` publishes `self.encoder` (and charges LIVE_SESSION_UNITS) BEFORE its
+            // last fallible steps, so a failure there leaves a live session with `inited == false`.
+            // Every guard on the re-init path keys off `inited`, so without this the next submit
+            // would skip teardown and overwrite `self.encoder` — leaking the session permanently
+            // (toward the driver's per-process cap) along with its session-budget units.
+            // `teardown` keys off `encoder.is_null()`, not `inited`, so it cleans up exactly this
+            // half-built state and is a no-op when nothing was opened.
+            if let Err(e) = self.init_session(&device) {
+                // SAFETY: same contract as the teardown above — the encode thread owns the session,
+                // and a failed init leaves nothing mid-encode to race with.
+                unsafe { self.teardown() };
+                return Err(e);
+            }
             self.init_device = dev_raw;
         }
         // The session's opening frame — NVENC emits it as an IDR regardless of pic flags, so the
@@ -1811,6 +1823,7 @@ mod tests {
                     payload: FramePayload::D3d11(D3d11Frame {
                         texture: tex.clone(),
                         device: device.clone(),
+                        pyro: None,
                     }),
                     cursor: None,
                 };
@@ -1913,6 +1926,7 @@ mod tests {
                         payload: FramePayload::D3d11(D3d11Frame {
                             texture: tex.clone(),
                             device: device.clone(),
+                            pyro: None,
                         }),
                         cursor: None,
                     };

crates/pf-encode/src/enc/windows/qsv.rs

@@ -146,7 +146,12 @@ const NUM_LTR_SLOTS: usize = 2;
 /// `PUNKTFUNK_NO_QSV_LTR` — defeat switch for the LTR-RFI path (parity with
 /// `PUNKTFUNK_NO_AMF_LTR`); loss recovery then always falls back to IDR.
 fn ltr_disabled() -> bool {
-    std::env::var("PUNKTFUNK_NO_QSV_LTR").is_ok_and(|v| v == "1" || v.eq_ignore_ascii_case("true"))
+    // Same accepted spellings as AMF's `ltr_disabled` — this had dropped the `trim()` and the
+    // `yes`/`on` forms, so a value with stray whitespace (easy to produce with `set VAR=1 `)
+    // silently left LTR enabled on Intel while the identical value worked on AMD.
+    std::env::var("PUNKTFUNK_NO_QSV_LTR")
+        .map(|v| matches!(v.trim(), "1" | "true" | "yes" | "on"))
+        .unwrap_or(false)
 }
 
 /// Frames between LTR marks (`PUNKTFUNK_LTR_INTERVAL_FRAMES`, shared with AMF); default ~1/4 s
@@ -171,13 +176,22 @@ fn ltr_test_force_at() -> Option<i64> {
 /// Mirrors [`super::amf`]'s `PUNKTFUNK_INTRA_REFRESH` opt-in: request the intra-refresh wave
 /// instead of LTR (mutually exclusive — the wave sweeps the whole picture, LTR pins references).
 fn intra_refresh_requested() -> bool {
+    // Spelling parity with AMF (see `ltr_disabled` above).
     std::env::var("PUNKTFUNK_INTRA_REFRESH")
-        .is_ok_and(|v| v == "1" || v.eq_ignore_ascii_case("true"))
+        .map(|v| matches!(v.trim(), "1" | "true" | "yes" | "on"))
+        .unwrap_or(false)
 }
 
-/// The wave period in frames (~0.5 s), the same shape as Linux NVENC / AMF.
+/// The wave period in frames (~0.5 s), `PUNKTFUNK_IR_PERIOD_FRAMES` overrides — the same knob and
+/// default as AMF / Linux NVENC. (This claimed parity while ignoring the env var entirely, so the
+/// knob silently did nothing on Intel; the clamp is kept because `mfxU16` bounds the field.)
 fn intra_refresh_period(fps: u32) -> u16 {
-    (fps / 2).clamp(8, 240) as u16
+    std::env::var("PUNKTFUNK_IR_PERIOD_FRAMES")
+        .ok()
+        .and_then(|s| s.trim().parse::<u32>().ok())
+        .filter(|v| *v >= 2)
+        .unwrap_or(fps / 2)
+        .clamp(8, 240) as u16
 }
 
 // ---------------------------------------------------------------------------------------------
@@ -700,7 +714,16 @@ pub struct QsvEncoder {
     /// `EncoderCaps::supports_rfi` and all per-frame marking/forcing below.
     ltr_active: bool,
     /// The wire frame index stored in each LTR slot (`None` = never marked).
+    ///
+    /// This mirrors the HARDWARE DPB, so an entry must not be cleared merely because we distrust
+    /// it: nulling issues no VPL call, and the encoder keeps the frame marked long-term until that
+    /// `LongTermIdx` is re-marked or an IDR flushes it. Distrust is recorded in `ltr_tainted`
+    /// instead, so the rejection list can still NAME the entry the hardware is holding.
     ltr_slots: [Option<i64>; NUM_LTR_SLOTS],
+    /// Per-slot taint from `invalidate_ref_frames`' sweep: the mark is still live in the hardware
+    /// DPB but was encoded inside the client's corrupt window, so it may not anchor a recovery —
+    /// it must be REJECTED instead. Cleared wherever the slot is re-marked or the DPB is flushed.
+    ltr_tainted: [bool; NUM_LTR_SLOTS],
     next_ltr_slot: usize,
     ltr_mark_interval: i64,
     /// Set by `invalidate_ref_frames`: the slot the next submitted frame force-references.
@@ -775,6 +798,7 @@ impl QsvEncoder {
             ir_active: false,
             ltr_active: false,
             ltr_slots: [None; NUM_LTR_SLOTS],
+            ltr_tainted: [false; NUM_LTR_SLOTS],
             next_ltr_slot: 0,
             ltr_mark_interval: ltr_mark_interval(fps),
             pending_force: None,
@@ -899,6 +923,7 @@ impl QsvEncoder {
         self.ltr_active = ltr_active;
         self.ir_active = ir_active;
         self.ltr_slots = [None; NUM_LTR_SLOTS];
+        self.ltr_tainted = [false; NUM_LTR_SLOTS];
         self.next_ltr_slot = 0;
         self.pending_force = None;
         self.hdr_applied = self.hdr_meta;
@@ -1017,13 +1042,14 @@ impl Encoder for QsvEncoder {
         self.frame_idx += 1;
         // --- LTR-RFI per-frame decisions (the AMF policy verbatim; see that module's doc) ---
         let mut mark_slot: Option<usize> = None;
-        let mut force_slot: Option<usize> = None;
+        let mut force_ltr: Option<(usize, i64)> = None;
         let mut recovery_anchor = false;
         if self.ltr_active {
             if forced {
                 // An IDR voids the decoder's reference buffers — drop stale slots and any
                 // queued force; the mark cadence below re-anchors on the IDR itself.
                 self.ltr_slots = [None; NUM_LTR_SLOTS];
+                self.ltr_tainted = [false; NUM_LTR_SLOTS]; // the IDR flushed the DPB with them
                 self.next_ltr_slot = 0;
                 self.pending_force = None;
             } else if self.ltr_test_force_at == Some(cur_idx) {
@@ -1035,17 +1061,29 @@ impl Encoder for QsvEncoder {
                 );
             }
             if let Some(slot) = self.pending_force.take() {
-                force_slot = Some(slot);
-                recovery_anchor = true;
+                // Resolve the anchor NOW: a taint sweep in `invalidate_ref_frames` may have
+                // emptied the slot since the force was queued. An empty slot means there is
+                // nothing clean to re-reference — the frame must ship as a plain P WITHOUT the
+                // `recovery_anchor` tag (the client lifts its post-loss freeze on that tag).
+                // The slot is no longer emptied by the sweep, so test the taint flag too — a
+                // tainted slot is exactly the "nothing clean to re-reference" case.
+                if let Some(idx) = self.ltr_slots[slot].filter(|_| !self.ltr_tainted[slot]) {
+                    force_ltr = Some((slot, idx));
+                    recovery_anchor = true;
+                }
             }
-            if force_slot.is_none() && (forced || cur_idx % self.ltr_mark_interval == 0) {
+            if force_ltr.is_none() && (forced || cur_idx % self.ltr_mark_interval == 0) {
                 let slot = self.next_ltr_slot;
                 self.ltr_slots[slot] = Some(cur_idx);
+                // Re-marking replaces the hardware's LongTermIdx: the tainted frame is gone from
+                // the DPB and this slot is clean again.
+                self.ltr_tainted[slot] = false;
                 self.next_ltr_slot = (self.next_ltr_slot + 1) % NUM_LTR_SLOTS;
                 mark_slot = Some(slot);
             }
         }
         let ltr_slots = self.ltr_slots;
+        let reject_ok = self.codec != Codec::Av1;
         let inner = self.inner.as_mut().expect("ensure_inner succeeded");
         // Bound the in-flight window BEFORE submitting: drain finished AUs (buffered for
         // `poll`) instead of letting the queue grow under overload.
@@ -1130,7 +1168,7 @@ impl Encoder for QsvEncoder {
                 (*surf).Data.TimeStamp = captured.pts_ns.wrapping_mul(9) / 100_000; // 90 kHz
                                                                                     // Per-frame control: forced IDR and/or the LTR reflist.
                 let mut ctrl: Option<Box<FrameCtrl>> = None;
-                if forced || mark_slot.is_some() || force_slot.is_some() {
+                if forced || mark_slot.is_some() || force_ltr.is_some() {
                     let mut c = FrameCtrl::new();
                     if forced {
                         c.ctrl.FrameType = (vpl::MFX_FRAMETYPE_IDR
@@ -1148,24 +1186,55 @@ impl Encoder for QsvEncoder {
                         c.reflist.ApplyLongTermIdx = 1;
                         use_reflist = true;
                     }
-                    if let Some(slot) = force_slot {
-                        if let Some(ltr_frame) = ltr_slots[slot] {
-                            // Force THIS frame to predict only from the known-good LTR — the
-                            // clean re-anchor. LongTermIdx stays 0 inside PreferredRefList
-                            // (the AV1 runtime rejects nonzero there; AVC/HEVC key on
-                            // FrameOrder).
-                            c.reflist.PreferredRefList[0].FrameOrder = ltr_frame as u32;
-                            c.reflist.PreferredRefList[0].PicStruct =
-                                vpl::MFX_PICSTRUCT_PROGRESSIVE as u16;
-                            use_reflist = true;
-                            tracing::info!(
-                                slot,
-                                ltr_frame,
-                                frame = cur_idx,
-                                "QSV LTR-RFI: re-referencing known-good LTR (clean recovery, \
-                                 no IDR)"
-                            );
+                    if let Some((slot, ltr_frame)) = force_ltr {
+                        // Force THIS frame to predict only from the known-good LTR — the
+                        // clean re-anchor. LongTermIdx stays 0 inside PreferredRefList
+                        // (the AV1 runtime rejects nonzero there; AVC/HEVC key on
+                        // FrameOrder).
+                        c.reflist.PreferredRefList[0].FrameOrder = ltr_frame as u32;
+                        c.reflist.PreferredRefList[0].PicStruct =
+                            vpl::MFX_PICSTRUCT_PROGRESSIVE as u16;
+                        // A preference alone is a reorder HINT (VPL spec) — the encoder may
+                        // still predict from the tainted short-term refs alongside it. AMF's
+                        // ForceLTRReferenceBitfield and NVENC's invalidation are hard
+                        // exclusions; emulate that here by rejecting every other DPB
+                        // candidate — the short-term sliding window (the 2 most recent
+                        // frames) and the other LTR slot — and capping L0 at one active
+                        // entry. Without this the "clean recovery" frame can carry the
+                        // corruption forward, which the client cannot detect (the field
+                        // failure: permanent macroblock soup under sustained loss).
+                        // AVC/HEVC only: the AV1 runtime's universal-reflist rejection path
+                        // is unvalidated, and an unhonored hint there still converges via
+                        // the host's IDR escalation.
+                        if reject_ok {
+                            let mut rej = 0;
+                            let mut reject = |idx: i64| {
+                                if idx >= 0 && idx != ltr_frame {
+                                    c.reflist.RejectedRefList[rej].FrameOrder = idx as u32;
+                                    c.reflist.RejectedRefList[rej].PicStruct =
+                                        vpl::MFX_PICSTRUCT_PROGRESSIVE as u16;
+                                    rej += 1;
+                                }
+                            };
+                            reject(cur_idx - 1);
+                            reject(cur_idx - 2);
+                            for (s, marked) in ltr_slots.iter().enumerate() {
+                                if s != slot {
+                                    if let Some(idx) = *marked {
+                                        reject(idx);
+                                    }
+                                }
+                            }
+                            c.reflist.NumRefIdxL0Active = 1;
                         }
+                        use_reflist = true;
+                        tracing::info!(
+                            slot,
+                            ltr_frame,
+                            frame = cur_idx,
+                            "QSV LTR-RFI: re-referencing known-good LTR (clean recovery, \
+                             no IDR)"
+                        );
                     }
                     if use_reflist {
                         c.attach_reflist();
@@ -1265,8 +1334,29 @@ impl Encoder for QsvEncoder {
         if !self.ltr_active || first < 0 || first > last {
             return false;
         }
+        // Taint sweep BEFORE picking the anchor: an LTR marked at-or-after the loss start was
+        // encoded inside the client's corrupt window — the client either never received it or
+        // decoded it against a broken reference chain. Serving it as "known-good" on a LATER
+        // loss ships corruption as the recovery anchor, and every subsequent mark re-samples
+        // the soup — the sustained-loss field failure where the picture never healed. Dropped
+        // slots stay dropped; the cadence re-marks a clean frame within ~1/4 s.
+        //
+        // Mark tainted rather than clearing: `ltr_slots` mirrors the HARDWARE DPB, and nulling an
+        // entry issues no VPL call — the frame stays marked long-term in the encoder. Clearing it
+        // made the rejection list below (which iterates the post-sweep mirror and only names `Some`
+        // slots) silently SKIP the one entry the sweep exists to distrust, so the recovery frame
+        // could still predict from it. With two slots the "exactly one swept" case is the modal
+        // one, and it was the broken one.
+        for (slot, marked) in self.ltr_slots.iter().enumerate() {
+            if marked.is_some_and(|idx| idx >= first) {
+                self.ltr_tainted[slot] = true;
+            }
+        }
         let mut best: Option<(usize, i64)> = None;
         for (slot, marked) in self.ltr_slots.iter().enumerate() {
+            if self.ltr_tainted[slot] {
+                continue; // still in the DPB, but encoded inside the corrupt window
+            }
             if let Some(idx) = *marked {
                 if idx < first && best.is_none_or(|(_, b)| idx > b) {
                     best = Some((slot, idx));
@@ -1287,6 +1377,9 @@ impl Encoder for QsvEncoder {
                 true
             }
             None => {
+                // The sweep may have emptied the slot an earlier (un-consumed) force pointed
+                // at — clear it so the next submit can't half-apply a stale recovery.
+                self.pending_force = None;
                 tracing::info!(
                     first,
                     last,
@@ -1366,15 +1459,21 @@ impl Encoder for QsvEncoder {
             let inner = self.inner.as_mut().expect("checked above");
             // Best-effort settle of in-flight operations (Close aborts them anyway).
             while sync_one(inner, 5).ok().flatten().is_some() {}
-            inner.pending.clear();
-            inner.ready.clear();
-            inner.frames_submitted = 0;
-            inner.first_au_logged = false;
+            // Close BEFORE dropping `pending`. Each `Pending` owns the `Box<BsBuf>` the runtime
+            // is writing into asynchronously (and a `Box<FrameCtrl>` it reads), so clearing first
+            // frees that heap while the operation is still live — a use-after-free by the VPL
+            // runtime. The drain above is best-effort and bails on the first `Err`, which is
+            // exactly the wedged-encoder case that triggers this reset, so it cannot be relied on
+            // to have retired everything. Close aborts the operations; only then is the drop safe.
             // SAFETY: the session is live on this thread; Close on a wedged encoder is legal
             // (result deliberately ignored) and re-Init happens through `init_encode`.
             unsafe {
                 let _ = vpl::MFXVideoENCODE_Close(inner.session.0);
             }
+            inner.pending.clear();
+            inner.ready.clear();
+            inner.frames_submitted = 0;
+            inner.first_au_logged = false;
             inner.session.0
         };
         match self.init_encode(rebuilt) {
@@ -1382,6 +1481,7 @@ impl Encoder for QsvEncoder {
                 self.ltr_active = ltr;
                 self.ir_active = ir;
                 self.ltr_slots = [None; NUM_LTR_SLOTS];
+                self.ltr_tainted = [false; NUM_LTR_SLOTS];
                 self.next_ltr_slot = 0;
                 self.pending_force = None;
                 if let Some(inner) = self.inner.as_mut() {
@@ -1746,6 +1846,7 @@ mod tests {
                 payload: FramePayload::D3d11(pf_frame::dxgi::D3d11Frame {
                     texture: tex.clone(),
                     device: device.clone(),
+                    pyro: None,
                 }),
                 cursor: None,
             };
@@ -1844,6 +1945,36 @@ mod tests {
         );
     }
 
+    /// Taint sweep: a loss that predates every live LTR mark leaves NO clean anchor — every
+    /// slot was marked inside the client's corrupt window. The invalidate must decline (the
+    /// caller then serves the IDR) and no recovery_anchor AU may ship; before the sweep this
+    /// force-referenced a tainted mark and shipped corruption tagged as a clean recovery.
+    #[test]
+    fn qsv_live_ltr_rfi_taint_sweep_declines() {
+        let mut rfi_answered = None;
+        let Some(aus) = drive_live(Codec::H264, false, 60, |enc, i| {
+            if i == 30 && enc.caps().supports_rfi {
+                // Frame 0 lost: the IDR itself — every mark (0, 15, ...) is at-or-after it.
+                rfi_answered = Some(enc.invalidate_ref_frames(0, 2));
+            }
+        }) else {
+            return;
+        };
+        assert_stream_shape(&aus, 60, true);
+        let Some(answered) = rfi_answered else {
+            eprintln!("note: driver declined LTR (supports_rfi=false) — sweep not exercised");
+            return;
+        };
+        assert!(
+            !answered,
+            "a loss covering every live LTR mark must fall back to IDR recovery"
+        );
+        assert!(
+            !aus.iter().any(|a| a.recovery_anchor),
+            "no recovery_anchor AU may ship when the sweep left no clean LTR"
+        );
+    }
+
     /// No-IDR bitrate retarget — Phase 3 on-glass: `reconfigure_bitrate` mid-stream must be
     /// accepted (HRD off + StartNewSequence=OFF) and must not emit a keyframe.
     #[test]

crates/pf-encode/src/lib.rs

@@ -48,7 +48,19 @@ impl Codec {
         } else {
             0u8
         };
-        #[cfg(not(all(target_os = "linux", feature = "pyrowave")))]
+        // Windows: the wavelet encoder rides on top of whatever GPU backend the box has (NVENC/AMF/
+        // QSV) — it opens its OWN Vulkan device by the render GPU's vendor/device-id and
+        // zero-copy-imports the capturer's NV12 D3D11 texture, so the H.26x backend is irrelevant to
+        // it. Only a software/GPU-less host keeps the bit off (no Vulkan GPU to open). Whether the
+        // Session-0 external-memory import actually works is confirmed at encoder open
+        // (`pyrowave_device_confirm_interop_support`); a failed open renegotiates to HEVC.
+        #[cfg(all(target_os = "windows", feature = "pyrowave"))]
+        let pyro = if windows_resolved_backend() != WindowsBackend::Software {
+            punktfunk_core::quic::CODEC_PYROWAVE
+        } else {
+            0u8
+        };
+        #[cfg(not(all(any(target_os = "linux", target_os = "windows"), feature = "pyrowave")))]
         let pyro = 0u8;
         let base = (|| {
             /// The static GPU superset (H.264 | HEVC | AV1) — mirrors the GameStream
@@ -211,6 +223,13 @@ impl Encoder for TrackedEncoder {
     }
 }
 
+/// Ceiling applied to the negotiated bitrate before it reaches openh264: software H.264 realistically
+/// caps far below the rates a hardware session negotiates, and handing it the full figure just
+/// misconfigures its rate control. Module-scope so BOTH software arms share one value — the Linux
+/// arm was missing the clamp the Windows arm applied.
+#[cfg(any(target_os = "linux", target_os = "windows"))]
+const SW_BITRATE_CEIL: u64 = 100_000_000;
+
 /// Open the platform encoder backend. Returns the encoder together with the display label of the
 /// branch that ACTUALLY opened (`nvenc`/`vaapi`/`vulkan`/`amf`/`qsv`/`software`) — the label feeds
 /// the mgmt API's live-session record, and only the open site knows which internal fallback won
@@ -236,10 +255,11 @@ fn open_video_backend(
     if fps == 0 || fps > 1000 {
         anyhow::bail!("invalid refresh/fps {fps}: must be 1..=1000 Hz");
     }
-    // 4:4:4 is HEVC-only. The negotiator should never pass `Yuv444` for another codec (it gates on
-    // `codec == H265`), but defend the contract here so a future caller can't silently emit a stream
-    // no decoder expects: a non-HEVC 4:4:4 request degrades to 4:2:0 with a warning.
-    let chroma = if chroma.is_444() && codec != Codec::H265 {
+    // 4:4:4 is HEVC- and PyroWave-only. The negotiator should never pass `Yuv444` for another
+    // codec (it gates on the codec + `can_encode_444`), but defend the contract here so a future
+    // caller can't silently emit a stream no decoder expects: an unsupported 4:4:4 request
+    // degrades to 4:2:0 with a warning.
+    let chroma = if chroma.is_444() && codec != Codec::H265 && codec != Codec::PyroWave {
         tracing::warn!(
             ?codec,
             "4:4:4 requested for a non-HEVC codec — encoding 4:2:0"
@@ -255,7 +275,7 @@ fn open_video_backend(
         if codec == Codec::PyroWave {
             #[cfg(feature = "pyrowave")]
             {
-                return pyrowave::PyroWaveEncoder::open(width, height, fps, bitrate_bps)
+                return pyrowave::PyroWaveEncoder::open(width, height, fps, bitrate_bps, chroma)
                     .map(|e| (Box::new(e) as Box<dyn Encoder>, "pyrowave"));
             }
             #[cfg(not(feature = "pyrowave"))]
@@ -275,8 +295,14 @@ fn open_video_backend(
         // stream never dies over the new path. `format`/`bit_depth`/`chroma` only matter to VAAPI —
         // the Vulkan backend imports the dmabuf and does its own 8-bit 4:2:0 CSC.
         let open_amd_intel = || -> Result<(Box<dyn Encoder>, &'static str)> {
+            // An HDR session (10-bit + a PQ/BT.2020 capture format) must skip the Vulkan Video
+            // backend — it hardcodes an 8-bit 4:2:0 BT.709 CSC — and take the libav VAAPI path,
+            // which has the P010/Main10/PQ wiring. SDR sessions keep the Vulkan default.
             #[cfg(feature = "vulkan-encode")]
-            if matches!(codec, Codec::H265 | Codec::Av1) && vulkan_encode_enabled() {
+            if matches!(codec, Codec::H265 | Codec::Av1)
+                && vulkan_encode_enabled()
+                && !(bit_depth == 10 && format.is_hdr_rgb10())
+            {
                 match vulkan_video::VulkanVideoEncoder::open(codec, width, height, fps, bitrate_bps)
                 {
                     Ok(e) => {
@@ -357,8 +383,17 @@ fn open_video_backend(
                          that ALSO preferred CODEC_PYROWAVE can display it (lab override; \
                          normal sessions negotiate it instead)"
                     );
-                    pyrowave::PyroWaveEncoder::open(width, height, fps, bitrate_bps)
-                        .map(|e| (Box::new(e) as Box<dyn Encoder>, "pyrowave"))
+                    // The lab override forces the wavelet stream onto a session negotiated for
+                    // another codec — that session's chroma may be HEVC-4:4:4, which the
+                    // pyrowave encoder doesn't do yet, so pin the override to 4:2:0.
+                    pyrowave::PyroWaveEncoder::open(
+                        width,
+                        height,
+                        fps,
+                        bitrate_bps,
+                        ChromaFormat::Yuv420,
+                    )
+                    .map(|e| (Box::new(e) as Box<dyn Encoder>, "pyrowave"))
                 }
                 #[cfg(not(feature = "pyrowave"))]
                 {
@@ -379,8 +414,14 @@ fn open_video_backend(
                     );
                 }
                 let _ = (cuda, bit_depth); // software path is CPU + 8-bit only
-                sw::OpenH264Encoder::open(format, width, height, fps, bitrate_bps)
-                    .map(|e| (Box::new(e) as Box<dyn Encoder>, "software"))
+                sw::OpenH264Encoder::open(
+                    format,
+                    width,
+                    height,
+                    fps,
+                    bitrate_bps.min(SW_BITRATE_CEIL),
+                )
+                .map(|e| (Box::new(e) as Box<dyn Encoder>, "software"))
             }
             "auto" | "" => {
                 // A CUDA frame can ONLY be consumed by NVENC. Otherwise the shared auto decision
@@ -399,10 +440,29 @@ fn open_video_backend(
     }
     #[cfg(target_os = "windows")]
     {
-        // The Windows host leg is blocked on the .173 D3D11-interop debt (plan Phase 0 §3);
-        // host_wire_caps never advertises the bit here, so this only guards a forged preference.
+        // A NEGOTIATED PyroWave session (client advertised + preferred it) routes straight to the
+        // NV12 zero-copy wavelet backend (design/pyrowave-windows-host-zerocopy.md) — placed FIRST,
+        // like the Linux branch. It opens its own Vulkan device by the render GPU's vendor/device-id
+        // and imports the capturer's shared NV12 texture; the H.26x backend selection below is moot.
         if codec == Codec::PyroWave {
-            anyhow::bail!("PyroWave host encode is not available on Windows yet");
+            #[cfg(feature = "pyrowave")]
+            {
+                let _ = (format, cuda);
+                return pyrowave::PyroWaveEncoder::open(
+                    width,
+                    height,
+                    fps,
+                    bitrate_bps,
+                    chroma,
+                    bit_depth,
+                )
+                .map(|e| (Box::new(e) as Box<dyn Encoder>, "pyrowave"));
+            }
+            #[cfg(not(feature = "pyrowave"))]
+            anyhow::bail!(
+                "session negotiated PyroWave but this host was built without --features \
+                 punktfunk-host/pyrowave (the advertisement bit should not have been set)"
+            );
         }
         let _ = cuda; // always false on Windows (no Cuda payload)
                       // NVIDIA → NVENC (direct SDK), AMD → AMF, Intel → QSV (both libavcodec), else → software
@@ -563,8 +623,6 @@ fn open_video_backend(
                      (build a GPU backend: --features nvenc or amf-qsv, or request H264)"
                 );
                 let _ = (bit_depth, chroma); // the software H.264 path is 8-bit 4:2:0 only
-                                             // Software H.264 realistically caps far below the negotiated hardware rates.
-                const SW_BITRATE_CEIL: u64 = 100_000_000;
                 sw::OpenH264Encoder::open(
                     format,
                     width,
@@ -737,6 +795,12 @@ fn nvidia_present() -> bool {
 /// picks its vendor's backend — AMD/Intel → VAAPI on that GPU's render node, NVIDIA → NVENC (still
 /// requiring the proprietary driver's device nodes; a nouveau NVIDIA GPU can't NVENC) — otherwise
 /// today's NVIDIA-presence probe, unchanged.
+///
+/// ⚠ This resolves the **`auto` case only** — it deliberately ignores `encoder_pref`. It is NOT a
+/// mirror of [`open_video`]'s dispatch and must not be used to decide which backend a capability
+/// probe should ask: use [`linux_zero_copy_is_vaapi`], which layers `encoder_pref` on top of this.
+/// (`can_encode_10bit` used this directly and answered for the wrong backend whenever a host
+/// forced one.)
 #[cfg(target_os = "linux")]
 fn linux_auto_is_vaapi() -> bool {
     if let Some(g) = pf_gpu::manual_selection() {
@@ -835,6 +899,13 @@ pub fn vaapi_codec_support() -> CodecSupport {
 pub fn can_encode_444(codec: Codec) -> bool {
     use std::collections::HashMap;
     use std::sync::{Mutex, OnceLock};
+    if codec == Codec::PyroWave {
+        // PyroWave does its own RGB→YCbCr CSC (capture always hands it a full-chroma source),
+        // so 4:4:4 needs no GPU encode probe — only the full-res-chroma CSC variant:
+        // `rgb2yuv444.comp` on Linux (Phase 2) and the mode-aware `BgraToYuvPlanes` on
+        // Windows (Phase 3) — both landed (design/pyrowave-444-hdr.md).
+        return true;
+    }
     if codec != Codec::H265 {
         return false;
     }
@@ -908,11 +979,10 @@ pub fn can_encode_444(_codec: Codec) -> bool {
 /// Backend truth: Windows **NVENC** queries the per-codec `NV_ENC_CAPS_SUPPORT_10BIT_ENCODE` cap;
 /// native **AMF** `Init`s a tiny P010 encoder with the 10-bit profile props (the driver rejects
 /// what the VCN can't do). **QSV** stays `false` until validated on Intel glass — the libavcodec
-/// Main10 incantation can silently encode 8-bit, the same stance as its 4:4:4 probe. Every
-/// **Linux** backend is `false` today: direct-NVENC/CUDA pins 8-bit until a P010 capture path
-/// exists (Phase 5.1), libav `hevc_nvenc` needs a 10-bit input format the capturer never feeds,
-/// VAAPI 10-bit isn't wired, and Vulkan-video hardcodes 8-bit — so Linux hosts honestly negotiate
-/// 8-bit SDR.
+/// Main10 incantation can silently encode 8-bit, the same stance as its 4:4:4 probe. **Linux**
+/// probes a tiny real Main10 open on the auto-resolved backend — libav NVENC (the HDR X2RGB10→
+/// P010 swscale path) or VAAPI (P010 pool + Main10) — for the GNOME 50+ HDR portal capture;
+/// the direct-SDK CUDA path and Vulkan-video stay 8-bit and a 10-bit session routes around them.
 #[cfg(any(target_os = "linux", target_os = "windows"))]
 pub fn can_encode_10bit(codec: Codec) -> bool {
     use std::collections::HashMap;
@@ -920,6 +990,12 @@ pub fn can_encode_10bit(codec: Codec) -> bool {
     if !codec.supports_10bit() {
         return false;
     }
+    if codec == Codec::PyroWave {
+        // PyroWave needs no GPU encode probe (the wavelet is depth-agnostic) — only the HDR
+        // capture CSC (scRGB FP16 → 16-bit studio-code planes), which exists on the Windows
+        // IDD-push path only (design/pyrowave-444-hdr.md Phase 3; Linux capture has no HDR).
+        return cfg!(target_os = "windows");
+    }
     // Cached per (selected GPU, codec) — a web-console preference change re-probes on the newly
     // selected adapter before the next Welcome, mirroring `can_encode_444`.
     static CACHE: OnceLock<Mutex<HashMap<(String, &'static str), bool>>> = OnceLock::new();
@@ -931,8 +1007,24 @@ pub fn can_encode_10bit(codec: Codec) -> bool {
     let supported = {
         #[cfg(target_os = "linux")]
         {
-            // No Linux backend encodes 10-bit yet (see the fn doc) — never negotiate it.
-            false
+            // NVENC (libav, the HDR P010 swscale path) or VAAPI (P010 upload / dmabuf graph),
+            // probed by opening a tiny real Main10 encoder — the same honesty contract as
+            // `can_encode_444`. Vulkan-video and the direct-SDK CUDA path stay 8-bit; a 10-bit
+            // session routes around them (see `open_video_backend`). NOTE: encode capability is
+            // only half the Linux gate — the capture side (GNOME 50+ portal monitor in HDR mode)
+            // is resolved separately by the host (`capturer_supports_hdr` / the GameStream RTSP
+            // honor), since this probe can't know what the compositor will negotiate.
+            // Resolve through the SAME helper `can_encode_444` uses (and which mirrors
+            // `open_video`'s dispatch): `linux_auto_is_vaapi` ignores `encoder_pref`, so on a box
+            // that forces a backend — e.g. `encoder_pref = "vaapi"` on an NVIDIA host — this probe
+            // would answer for NVENC while the session actually opens VAAPI, and the negotiated bit
+            // depth (plus the HDR/SDR colour label derived from it) would describe a backend that
+            // never runs. That is exactly the dishonesty this probe exists to prevent.
+            if linux_zero_copy_is_vaapi() {
+                vaapi::probe_can_encode_10bit(codec)
+            } else {
+                linux::probe_can_encode_10bit(codec)
+            }
         }
         #[cfg(target_os = "windows")]
         {
@@ -1260,6 +1352,29 @@ mod vk_util;
 #[cfg(all(target_os = "linux", feature = "pyrowave"))]
 #[path = "enc/linux/pyrowave.rs"]
 mod pyrowave;
+// The Windows PyroWave encoder — NV12 zero-copy D3D11→Vulkan via pyrowave's own compat device
+// (design/pyrowave-windows-host-zerocopy.md). Same module name as the Linux one (per-platform
+// `#[path]`, mutually-exclusive cfg) so `crate::pyrowave::*` is flat on both.
+#[cfg(all(target_os = "windows", feature = "pyrowave"))]
+#[path = "enc/windows/pyrowave.rs"]
+mod pyrowave;
+// Shared PyroWave AU wire-framing (§4.4) — the single source of truth both platform backends emit,
+// so the on-wire access-unit layout the clients parse can never drift between Linux and Windows.
+#[cfg(all(any(target_os = "linux", target_os = "windows"), feature = "pyrowave"))]
+#[path = "enc/pyrowave_wire.rs"]
+mod pyrowave_wire;
+
+/// Whether a PyroWave mode fits the vendored rate controller's packed 16-bit block index
+/// (`patches/0002-rdo-saving-clamp.patch` note): false ≈ 8K-class 4:4:4. The negotiator
+/// downgrades such a session to 4:2:0 before the Welcome; the encoders also refuse outright.
+#[cfg(all(any(target_os = "linux", target_os = "windows"), feature = "pyrowave"))]
+pub fn pyrowave_mode_fits_rdo(width: u32, height: u32, chroma444: bool) -> bool {
+    pyrowave_wire::block_count_32x32(width, height, chroma444) <= u16::MAX as u32
+}
+#[cfg(not(all(any(target_os = "linux", target_os = "windows"), feature = "pyrowave")))]
+pub fn pyrowave_mode_fits_rdo(_width: u32, _height: u32, _chroma444: bool) -> bool {
+    false
+}
 
 #[cfg(test)]
 mod tests {

crates/pf-frame/src/dxgi.rs

@@ -34,10 +34,35 @@ pub struct WinCaptureTarget {
     pub wudf_pid: u32,
 }
 
-/// A GPU-resident captured texture (future NVENC-D3D11 zero-copy path).
+/// The PyroWave (Windows) zero-copy sharing payload attached to a captured frame: the SECOND plane
+/// texture + the cross-device fence the wavelet encoder needs (design/pyrowave-windows-host-
+/// zerocopy.md). The wavelet encoder ingests **two SEPARATE** shareable plane textures — the full-res
+/// `R8_UNORM` **Y** rides [`D3d11Frame::texture`], and the half-res `R8G8_UNORM` **CbCr** rides
+/// [`cbcr`](Self::cbcr) — because importing a single *planar* NV12 texture into Vulkan is unreliable
+/// on NVIDIA at arbitrary sizes; separate single/two-component textures import reliably. `None` on
+/// every non-PyroWave frame (NVENC/AMF/QSV encode the in-place NV12/BGRA and need no cross-device
+/// fence). The encoder makes each texture's shared handle on demand.
+pub struct PyroFrameShare {
+    /// The half-res `R8G8_UNORM` interleaved CbCr plane (created `SHARED | SHARED_NTHANDLE`). The
+    /// full-res Y plane is [`D3d11Frame::texture`].
+    pub cbcr: ID3D11Texture2D,
+    /// The shared D3D11/D3D12 **fence** NT handle (raw), passed on EVERY frame; the encoder imports
+    /// it (duplicating) whenever it has no timeline yet (first frame or after an encoder rebuild).
+    pub fence_handle: Option<isize>,
+    /// The fence value the capturer signalled after THIS frame's convert. The encoder's Vulkan
+    /// acquire waits on it, so the wavelet read is ordered after the D3D11 CSC.
+    pub fence_value: u64,
+}
+
+/// A GPU-resident captured texture (the Windows zero-copy path: NVENC/AMF/QSV encode it in place;
+/// the PyroWave backend imports it — plus the second plane in [`pyro`](Self::pyro) — into its own
+/// Vulkan device). For a PyroWave frame, `texture` is the full-res `R8_UNORM` Y plane.
 pub struct D3d11Frame {
     pub texture: ID3D11Texture2D,
     pub device: ID3D11Device,
+    /// PyroWave zero-copy sharing info (the CbCr plane + fence); `None` unless this is a PyroWave
+    /// session. See [`PyroFrameShare`].
+    pub pyro: Option<PyroFrameShare>,
 }
 // SAFETY: `D3d11Frame` owns an `ID3D11Texture2D` + `ID3D11Device`, which are COM interface pointers.
 // D3D11 devices/resources use thread-safe (interlocked) COM reference counting, and the device is

crates/pf-frame/src/lib.rs

@@ -56,6 +56,19 @@ pub enum PixelFormat {
     /// `DeviceBuffer::yuv444` — three full-res planes stacked in one allocation); NVENC encodes
     /// it natively under the Range-Extensions profile. Never a CPU payload.
     Yuv444,
+    /// 10-bit RGB packed `x:R:G:B 2:10:10:10` little-endian (SPA `xRGB_210LE`, DRM `XRGB2101010` /
+    /// `XR30`, ffmpeg `x2rgb10le`, NVENC `ARGB10`) — as an LE u32: B in bits 0-9, G 10-19, R 20-29.
+    /// The Linux GNOME 50+ HDR screencast source format: Mutter advertises it (with BT.2020
+    /// primaries + SMPTE ST.2084 PQ transfer) for a monitor in HDR mode, so the samples are
+    /// PQ-encoded BT.2020 RGB. Linux-only; the Windows HDR path stays `Rgb10a2`/`P010`.
+    X2Rgb10,
+    /// 10-bit RGB packed `x:B:G:R 2:10:10:10` little-endian (SPA `xBGR_210LE`, DRM `XBGR2101010` /
+    /// `XB30`, ffmpeg `x2bgr10le`, NVENC `ABGR10`) — as an LE u32: R in bits 0-9, G 10-19, B 20-29;
+    /// the same memory layout as the Windows [`Rgb10a2`](Self::Rgb10a2) (DXGI `R10G10B10A2`). The
+    /// second GNOME 50+ HDR screencast format (same PQ/BT.2020 colorimetry as
+    /// [`X2Rgb10`](Self::X2Rgb10)); kept separate from `Rgb10a2` so the Linux and Windows HDR
+    /// paths stay independently greppable.
+    X2Bgr10,
 }
 
 impl PixelFormat {
@@ -67,6 +80,12 @@ impl PixelFormat {
             _ => 4,
         }
     }
+
+    /// True for the packed 10-bit RGB layouts a Linux HDR (BT.2020 PQ) capture negotiates —
+    /// the formats that make a session's encode bit depth 10 (HEVC Main10 / 10-bit AV1).
+    pub fn is_hdr_rgb10(self) -> bool {
+        matches!(self, PixelFormat::X2Rgb10 | PixelFormat::X2Bgr10)
+    }
 }
 
 /// DRM FourCC for a packed 32-bit format name (little-endian, e.g. `b"XR24"`).
@@ -86,6 +105,9 @@ pub fn drm_fourcc(format: PixelFormat) -> Option<u32> {
         Bgra => drm_fourcc_code(b"AR24"), // DRM_FORMAT_ARGB8888
         Rgbx => drm_fourcc_code(b"XB24"), // DRM_FORMAT_XBGR8888
         Rgba => drm_fourcc_code(b"AB24"), // DRM_FORMAT_ABGR8888
+        // The GNOME 50+ HDR screencast formats (packed 2:10:10:10, PQ/BT.2020).
+        X2Rgb10 => drm_fourcc_code(b"XR30"), // DRM_FORMAT_XRGB2101010
+        X2Bgr10 => drm_fourcc_code(b"XB30"), // DRM_FORMAT_XBGR2101010
         // 24-bit packed RGB/BGR have no straightforward dmabuf import here; use the CPU path.
         // Rgb10a2/Nv12/P010 are the Windows HDR / video-processor formats — never produced on
         // Linux; Yuv444 is OUR convert's OUTPUT, never a capture source format.
@@ -115,6 +137,13 @@ pub struct OutputFormat {
     /// Linux it forces the CPU RGB path the encoder swscales to `YUV444P`. `false` on every
     /// 4:2:0 session.
     pub chroma_444: bool,
+    /// A PyroWave (wavelet) session on Windows: the IDD-push capturer must make its NV12 out-ring
+    /// **shareable** (`SHARED | SHARED_NTHANDLE`) and signal a **shared fence** after each convert,
+    /// so the pyrowave encoder can zero-copy-import the texture into its own Vulkan device
+    /// (design/pyrowave-windows-host-zerocopy.md). Also forces the NV12 4:2:0 SDR convert branch
+    /// (never BGRA-passthrough / P010). `false` on every non-PyroWave session and on Linux (the
+    /// wavelet encoder ingests dmabufs / CPU RGB there, not a D3D11 texture).
+    pub pyrowave: bool,
 }
 
 impl OutputFormat {
@@ -130,6 +159,8 @@ impl OutputFormat {
             hdr,
             // The GameStream + spike paths are always 4:2:0 (4:4:4 is punktfunk/1-native only).
             chroma_444: false,
+            // GameStream never negotiates PyroWave (native punktfunk/1 only).
+            pyrowave: false,
         }
     }
 }

crates/pf-host-config/src/lib.rs

@@ -76,10 +76,16 @@ pub struct HostConfig {
     /// backend (the legacy SudoVDA backend was removed), so this is currently informational — kept for the
     /// shipped `host.env` and as a forward seam if a second backend is ever added.
     pub vdisplay: Option<String>,
-    /// `PUNKTFUNK_GAMESCOPE_STEAM` — opt the bare headless gamescope spawn into its Steam
-    /// integration mode (`--steam`). Managed gamescope-session-plus/SteamOS sessions own their
-    /// own flags and do not consult this.
+    /// `PUNKTFUNK_GAMESCOPE_STEAM` — force the bare headless gamescope spawn into its Steam
+    /// integration mode (`--steam`) for EVERY launch. A Steam title auto-enables `--steam` on its
+    /// own regardless of this knob; it exists to force it on for non-Steam launches too. Managed
+    /// gamescope-session-plus/SteamOS sessions own their own flags and do not consult this.
     pub gamescope_steam: bool,
+    /// `PUNKTFUNK_GAMESCOPE_GRAB_CURSOR` — add `--force-grab-cursor` to the bare headless gamescope
+    /// spawn for an actual game launch, forcing relative-mouse capture so FPS mouselook works over the
+    /// injected pointer. Default OFF: it forces relative mode, which breaks absolute-pointer titles
+    /// and menus, so it's opt-in per host until validated on-glass.
+    pub gamescope_grab_cursor: bool,
     /// `PUNKTFUNK_RECOVER_SESSION_CMD` — operator hook fired (debounced) when a client connects while NO
     /// graphical session is live for this uid: the state a compositor crash leaves behind (gnome-shell
     /// SIGSEGV → GDM greeter, whose auto-login is once-per-boot, so the box would otherwise need a walk-up
@@ -152,6 +158,12 @@ impl HostConfig {
                     "1" | "true" | "yes" | "on"
                 )
             }),
+            gamescope_grab_cursor: val("PUNKTFUNK_GAMESCOPE_GRAB_CURSOR").is_some_and(|s| {
+                matches!(
+                    s.trim().to_ascii_lowercase().as_str(),
+                    "1" | "true" | "yes" | "on"
+                )
+            }),
             recover_session_cmd: val("PUNKTFUNK_RECOVER_SESSION_CMD")
                 .filter(|s| !s.trim().is_empty()),
             on_connect_cmd: val("PUNKTFUNK_ON_CONNECT_CMD").filter(|s| !s.trim().is_empty()),

crates/pf-inject/Cargo.toml

@@ -6,7 +6,7 @@
 # gamescope-EI socket path is the shared pf-paths contract, not a vdisplay reach-in).
 [package]
 name = "pf-inject"
-version = "0.12.0"
+version.workspace = true
 edition = "2021"
 rust-version.workspace = true
 license = "MIT OR Apache-2.0"

crates/pf-presenter/src/d3d11.rs

@@ -1,6 +1,7 @@
 //! D3D11 shared-texture → Vulkan import (Windows): the presenter half of the D3D11VA
 //! decode path (`pf_client_core::video_d3d11`). Each decoded frame arrives as the NT
-//! handle of a shareable **BGRA8** texture (the decoder's VideoProcessor already did
+//! handle of a shareable single-plane RGB texture — **BGRA8** sRGB normally, **RGB10A2**
+//! PQ for the HDR pass-through flavor (the decoder's VideoProcessor already did
 //! YUV→RGB); we import it as a single-plane VkImage (`VK_KHR_external_memory_win32`,
 //! dedicated allocation) and the presenter blits it straight into its video image — no
 //! CSC pass. Single-plane RGBA is deliberate: importing the earlier multiplanar NV12
@@ -28,31 +29,41 @@ pub const DEVICE_EXTENSIONS: [&std::ffi::CStr; 2] = [
     ash::khr::win32_keyed_mutex::NAME,
 ];
 
-/// Can this device import a D3D11 BGRA8 texture as a blit source? The spec-required
+/// Can this device import a D3D11 texture of `format` as a blit source? The spec-required
 /// capability probe for the exact image the import path creates — creating an external
 /// image the driver doesn't support is undefined behavior (observed as
 /// `VK_ERROR_DEVICE_LOST` at the first submits with the old NV12 hand-off).
-pub fn import_supported(instance: &ash::Instance, pdev: vk::PhysicalDevice) -> bool {
+fn format_importable(
+    instance: &ash::Instance,
+    pdev: vk::PhysicalDevice,
+    format: vk::Format,
+) -> bool {
     let mut ext_info = vk::PhysicalDeviceExternalImageFormatInfo::default()
         .handle_type(vk::ExternalMemoryHandleTypeFlags::D3D11_TEXTURE);
     let fmt_info = vk::PhysicalDeviceImageFormatInfo2::default()
-        .format(vk::Format::B8G8R8A8_UNORM)
+        .format(format)
         .ty(vk::ImageType::TYPE_2D)
         .tiling(vk::ImageTiling::OPTIMAL)
         .usage(vk::ImageUsageFlags::TRANSFER_SRC)
         .push_next(&mut ext_info);
     let mut ext_props = vk::ExternalImageFormatProperties::default();
     let mut props = vk::ImageFormatProperties2::default().push_next(&mut ext_props);
-    let ok = unsafe {
-        instance.get_physical_device_image_format_properties2(pdev, &fmt_info, &mut props)
-    }
-    .is_ok()
+    unsafe { instance.get_physical_device_image_format_properties2(pdev, &fmt_info, &mut props) }
+        .is_ok()
         && ext_props
             .external_memory_properties
             .external_memory_features
-            .contains(vk::ExternalMemoryFeatureFlags::IMPORTABLE);
-    tracing::info!(bgra8 = ok, "D3D11 texture → Vulkan import support");
-    ok
+            .contains(vk::ExternalMemoryFeatureFlags::IMPORTABLE)
+}
+
+/// The two hand-off flavors' import support: `.0` = BGRA8 (the SDR ring — gates the whole
+/// D3D11VA path), `.1` = RGB10A2 (the HDR PQ ring — gates only the pass-through flavor;
+/// without it a PQ stream keeps the decoder-side tonemap to BGRA8).
+pub fn import_supported(instance: &ash::Instance, pdev: vk::PhysicalDevice) -> (bool, bool) {
+    let bgra8 = format_importable(instance, pdev, vk::Format::B8G8R8A8_UNORM);
+    let rgb10 = format_importable(instance, pdev, vk::Format::A2B10G10R10_UNORM_PACK32);
+    tracing::info!(bgra8, rgb10, "D3D11 texture → Vulkan import support");
+    (bgra8, rgb10)
 }
 
 /// One imported frame: the BGRA8 image over the shared texture and its imported
@@ -98,7 +109,13 @@ pub fn import(
     if std::env::var_os("PUNKTFUNK_HW_FAULT").is_some_and(|v| v == "import") {
         bail!("injected import failure (PUNKTFUNK_HW_FAULT=import)");
     }
-    let mp_format = vk::Format::B8G8R8A8_UNORM;
+    // DXGI R10G10B10A2 and Vulkan A2B10G10R10_PACK32 are the same bit layout (R in the
+    // low bits) — the standard interop pairing, same as BGRA8 ↔ B8G8R8A8.
+    let mp_format = if frame.rgb10 {
+        vk::Format::A2B10G10R10_UNORM_PACK32
+    } else {
+        vk::Format::B8G8R8A8_UNORM
+    };
     let handle_type = vk::ExternalMemoryHandleTypeFlags::D3D11_TEXTURE;
 
     // One single-plane image over the whole texture, transfer-source only — the blit is

crates/pf-presenter/src/input.rs

@@ -53,6 +53,8 @@ pub struct Capture {
     /// The touchscreen input model for this session, and — for trackpad/pointer — the
     /// gesture state machine finger events feed.
     touch_mode: TouchMode,
+    /// Reverse the scroll direction sent to the host ([`Settings::invert_scroll`]).
+    invert_scroll: bool,
     gestures: Gestures,
 }
 
@@ -68,7 +70,11 @@ fn send(connector: &NativeClient, kind: InputKind, code: u32, x: i32, y: i32, fl
 }
 
 impl Capture {
-    pub fn new(connector: Arc<NativeClient>, touch_mode: TouchMode) -> Capture {
+    pub fn new(
+        connector: Arc<NativeClient>,
+        touch_mode: TouchMode,
+        invert_scroll: bool,
+    ) -> Capture {
         Capture {
             connector,
             captured: false,
@@ -79,6 +85,7 @@ impl Capture {
             scroll_acc: (0.0, 0.0),
             touch_slots: HashMap::new(),
             touch_mode,
+            invert_scroll,
             gestures: Gestures::new(touch_mode == TouchMode::Trackpad),
         }
     }
@@ -194,9 +201,10 @@ impl Capture {
             return;
         }
         self.flush_motion(); // scroll happens at the latest cursor position
+        let sign = if self.invert_scroll { -1.0 } else { 1.0 };
         let (mut ax, mut ay) = self.scroll_acc;
-        ay += f64::from(dy) * 120.0;
-        ax += f64::from(dx) * 120.0;
+        ay += f64::from(dy) * 120.0 * sign;
+        ax += f64::from(dx) * 120.0 * sign;
         let vy = ay.trunc() as i32;
         if vy != 0 {
             ay -= f64::from(vy);

crates/pf-presenter/src/run.rs

@@ -48,6 +48,8 @@ pub struct SessionOpts {
     /// `Pointer` (absolute cursor), or `Touch` (real multi-touch passthrough). Latched per
     /// session — a mouse-only client leaves this at the default and never sees a finger.
     pub touch_mode: TouchMode,
+    /// Reverse the scroll direction sent to the host ([`Settings::invert_scroll`]).
+    pub invert_scroll: 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
@@ -194,7 +196,7 @@ struct StreamState {
     /// PyroWave present has no demote rung (nothing else decodes the codec), so a
     /// persistent non-device-lost present failure would warn on every frame. Latch it:
     /// warn on the first failure of a streak, then stay quiet until a present succeeds.
-    #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+    #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
     pyro_present_warned: bool,
     hw_fails: u32,
     /// The OSD's text (multi-line; rebuilt each Stats window and on a live tier cycle).
@@ -267,7 +269,7 @@ impl StreamState {
             win_start: Instant::now(),
             presented: PresentedWindow::default(),
             dmabuf_demoted: false,
-            #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+            #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
             pyro_present_warned: false,
             hw_fails: 0,
             osd_text: String::new(),
@@ -811,7 +813,7 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                         .ok();
                     gamepad.attach(c.clone());
                     st.clock_offset = Some(c.clock_offset_shared());
-                    let mut cap = Capture::new(c.clone(), opts.touch_mode);
+                    let mut cap = Capture::new(c.clone(), opts.touch_mode, opts.invert_scroll);
                     cap.engage(); // capture engages when the stream starts (ui_stream parity)
                     apply_capture(&mut window, &mouse, true);
                     st.capture = Some(cap);
@@ -1007,9 +1009,12 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                     // PyroWave planar frames: already on the presenter's device and
                     // fence-complete — a present failure has no demote rung (nothing
                     // else decodes the codec); only device loss ends the session.
-                    #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+                    #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
                     DecodedImage::PyroWave(f) => {
-                        st.hdr = false; // 8-bit SDR codec
+                        // The wavelet stream carries the negotiated ColorInfo (no VUI): an
+                        // HDR (PQ) pyrowave session presents through the HDR10 path exactly
+                        // like the H.26x codecs (design/pyrowave-444-hdr.md Phase 3).
+                        st.hdr = f.color.is_pq();
                         match presenter.present(
                             &window,
                             FrameInput::PyroWave(f),

crates/pf-presenter/src/vk/mod.rs

@@ -33,6 +33,8 @@ mod reconfig;
 mod resources;
 mod setup;
 
+pub use setup::list_adapters;
+
 /// One presenter iteration's video input.
 pub enum FrameInput<'a> {
     /// No new frame — re-composite the retained video image (expose/resize).
@@ -47,7 +49,7 @@ pub enum FrameInput<'a> {
     D3d11(pf_client_core::video::D3d11Frame),
     /// PyroWave planar output — three R8 plane views already on THIS device, decode
     /// fence-complete, GENERAL layout (`pf_client_core::video_pyrowave`).
-    #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+    #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
     PyroWave(pf_client_core::video_pyrowave::PyroWavePlanarFrame),
 }
 
@@ -136,7 +138,7 @@ pub struct Presenter {
     csc: CscPass,
     /// The planar (3-plane) CSC variant for PyroWave frames; built only when the device
     /// passed the pyrowave probe.
-    #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+    #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
     csc_planar: Option<CscPass>,
     /// FFmpeg Vulkan Video decode handles — `None` when the stack can't do it.
     video_export: Option<pf_client_core::video::VulkanDecodeDevice>,
@@ -304,7 +306,7 @@ impl Drop for Presenter {
             #[cfg(target_os = "linux")]
             self.hw.take();
             self.csc.destroy(&self.device);
-            #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+            #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
             if let Some(p) = &self.csc_planar {
                 p.destroy(&self.device);
             }

crates/pf-presenter/src/vk/present.rs

@@ -38,8 +38,8 @@ impl Presenter {
             FrameInput::VkFrame(v) => Some(v.color.is_pq()),
             #[cfg(windows)]
             FrameInput::D3d11(d) => Some(d.color.is_pq()),
-            #[cfg(all(target_os = "linux", feature = "pyrowave"))]
-            FrameInput::PyroWave(f) => Some(f.color.is_pq()), // always SDR today
+            #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
+            FrameInput::PyroWave(f) => Some(f.color.is_pq()),
         };
         if let Some(pq) = frame_pq {
             // A PQ stream we can only tone-map (no HDR10 surface) is the silent failure behind
@@ -68,7 +68,7 @@ impl Presenter {
         #[cfg(windows)]
         let mut win_frame: Option<crate::d3d11::HwFrame> = None;
         let mut vk_frame: Option<(VkVideoFrame, [vk::ImageView; 2])> = None;
-        #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+        #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
         let mut pyro_frame: Option<pf_client_core::video_pyrowave::PyroWavePlanarFrame> = None;
         let cpu_frame = match input {
             FrameInput::Redraw => None,
@@ -96,7 +96,7 @@ impl Presenter {
                 vk_frame = Some((v, views));
                 None
             }
-            #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+            #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
             FrameInput::PyroWave(f) => {
                 pyro_frame = Some(f);
                 None
@@ -155,7 +155,7 @@ impl Presenter {
             }
             self.csc.bind_planes(&self.device, views[0], views[1]);
         }
-        #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+        #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
         if let Some(f) = &pyro_frame {
             if self
                 .video
@@ -239,11 +239,12 @@ impl Presenter {
                 );
             }
 
-            // D3D11 frame: acquire the imported BGRA texture from the external "queue
+            // D3D11 frame: acquire the imported RGB texture from the external "queue
             // family" (the keyed mutex on the submit is the actual cross-API sync) and
-            // blit it into the video image — the frame arrives as ready sRGB from the
-            // decoder's VideoProcessor, so there is no CSC pass; the blit converts the
-            // BGRA→RGBA component order. Same layout dance as the CPU staging path.
+            // blit it into the video image — the frame arrives as ready RGB from the
+            // decoder's VideoProcessor (sRGB BGRA8, or PQ RGB10A2 on the HDR ring —
+            // matching the HDR-mode video image), so there is no CSC pass; the blit
+            // converts component order. Same layout dance as the CPU staging path.
             #[cfg(windows)]
             if let (Some(f), Some(v)) = (&win_frame, &self.video) {
                 external_acquire_barrier(&self.device, self.cmd_buf, f.image(), self.qfi);
@@ -316,7 +317,7 @@ impl Presenter {
             // PyroWave frame: the planes are already on THIS device, decode
             // fence-complete and barriered to fragment sampling (GENERAL) by the
             // decoder — no acquire needed, just the planar CSC pass.
-            #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+            #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
             if let (Some(f), Some(v)) = (&pyro_frame, &self.video) {
                 let extent = vk::Extent2D {
                     width: v.width,
@@ -694,7 +695,7 @@ impl Presenter {
     }
 
     /// [`record_csc`] over the planar (PyroWave) pass — always 8-bit, no MSB packing.
-    #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+    #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
     unsafe fn record_csc_planar(
         &self,
         framebuffer: vk::Framebuffer,
@@ -750,11 +751,31 @@ impl Presenter {
                 &[planar.desc_set],
                 &[],
             );
-            let rows = csc_rows(color, 8, false);
+            // An HDR (PQ) pyrowave session carries P010-style 10-bit studio codes MSB-packed
+            // into 16-bit planes (design/pyrowave-444-hdr.md §2.2) — same sampling scale as
+            // the P010 path; SDR sessions are plain 8-bit BT.709 limited. Depth follows the
+            // colour contract (negotiation couples 10-bit ⟺ PQ for this codec).
+            let (depth, msb_packed) = if color.is_pq() {
+                (10, true)
+            } else {
+                (8, false)
+            };
+            let rows = csc_rows(color, depth, msb_packed);
+            // Mode 1 = PQ→SDR tonemap (PQ stream without an HDR10 surface); mode 0 passes
+            // the transfer through — identical to the NV12 arm above.
+            let mode = if color.is_pq() && !self.hdr_active {
+                1.0f32
+            } else {
+                0.0
+            };
+            let peak = std::env::var("PUNKTFUNK_TONEMAP_PEAK")
+                .ok()
+                .and_then(|v| v.parse::<f32>().ok())
+                .unwrap_or(4.9); // ≈1000 nits over the 203-nit reference
             let mut pc = [0f32; 16];
             pc[..12].copy_from_slice(bytemuck_rows(&rows));
-            pc[12] = 0.0; // SDR passthrough — PyroWave has no PQ path
-            pc[13] = 0.0;
+            pc[12] = mode;
+            pc[13] = peak;
             let bytes = std::slice::from_raw_parts(pc.as_ptr().cast::<u8>(), 64);
             self.device.cmd_push_constants(
                 self.cmd_buf,

crates/pf-presenter/src/vk/reconfig.rs

@@ -203,11 +203,15 @@ impl Presenter {
             vk::Format::R8G8B8A8_UNORM
         };
         self.csc.destroy(&self.device); // fence-safe: only our cmd bufs reference it
-        #[cfg(all(target_os = "linux", feature = "pyrowave"))]
-        if let Some(p) = &self.csc_planar {
-            p.destroy(&self.device);
-        }
         self.csc = CscPass::new(&self.device, self.video_format)?;
+        // The planar (PyroWave) pass renders to the same intermediate — rebuild it at the
+        // new format too (an HDR pyrowave session needs the 10-bit intermediate exactly
+        // like the H.26x path; 8-bit PQ bands visibly).
+        #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
+        if let Some(p) = self.csc_planar.take() {
+            p.destroy(&self.device);
+            self.csc_planar = Some(CscPass::new_planar(&self.device, self.video_format)?);
+        }
         if let Some(v) = self.video.take() {
             unsafe {
                 self.device.destroy_framebuffer(v.framebuffer, None);

crates/pf-presenter/src/vk/setup.rs

@@ -94,8 +94,9 @@ impl Presenter {
         // (vkGetPhysicalDeviceImageFormatProperties2 — creating an unsupported external
         // image is UB, observed as VK_ERROR_DEVICE_LOST at the first submits on NVIDIA).
         #[cfg(windows)]
-        let win_capable = crate::d3d11::DEVICE_EXTENSIONS.iter().all(|n| has(n))
-            && crate::d3d11::import_supported(&instance, pdev);
+        let (import_bgra8, import_rgb10) = crate::d3d11::import_supported(&instance, pdev);
+        #[cfg(windows)]
+        let win_capable = crate::d3d11::DEVICE_EXTENSIONS.iter().all(|n| has(n)) && import_bgra8;
         #[cfg(windows)]
         if win_capable {
             dev_exts.extend(crate::d3d11::DEVICE_EXTENSIONS.iter().map(|n| n.as_ptr()));
@@ -315,8 +316,9 @@ impl Presenter {
             ext_mem_win32: ash::khr::external_memory_win32::Device::new(&instance, &device),
         });
         let csc = CscPass::new(&device, vk::Format::R8G8B8A8_UNORM)?;
-        // PyroWave is 8-bit SDR only, so the planar pass never needs the HDR10 rebuild.
-        #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+        // Starts SDR like `csc`; an HDR (PQ) pyrowave session rebuilds it at the 10-bit
+        // intermediate via `set_hdr_mode`, exactly like the H.26x pass.
+        #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
         let csc_planar = if pyrowave_ok {
             Some(CscPass::new_planar(&device, vk::Format::R8G8B8A8_UNORM)?)
         } else {
@@ -391,14 +393,25 @@ impl Presenter {
                 d3d11_import: win_capable,
                 #[cfg(not(windows))]
                 d3d11_import: false,
+                // Filled in below — the HDR10 surface facts arrive with pick_formats.
+                d3d11_hdr10: false,
                 adapter_luid,
                 queue_lock: queue_lock.clone(),
             })
         } else {
             None
         };
+        #[cfg(windows)]
+        let mut video_export = video_export;
 
         let (format, hdr10_format) = pick_formats(&surface_i, pdev, surface, has_colorspace_ext)?;
+        // The D3D11VA backend may emit its HDR (RGB10 PQ) ring only when this device can
+        // import the 10-bit texture AND the surface offers an HDR10 swapchain to pass it
+        // through to; otherwise a PQ stream keeps the decoder-side tonemap to sRGB.
+        #[cfg(windows)]
+        if let Some(v) = video_export.as_mut() {
+            v.d3d11_hdr10 = win_capable && import_rgb10 && hdr10_format.is_some();
+        }
         let present_mode = pick_present_mode(&surface_i, pdev, surface)?;
         tracing::info!(
             ?format,
@@ -450,7 +463,7 @@ impl Presenter {
             #[cfg(windows)]
             hw_win,
             csc,
-            #[cfg(all(target_os = "linux", feature = "pyrowave"))]
+            #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
             csc_planar,
             video_export,
             overlay_pipe,
@@ -484,6 +497,52 @@ impl Presenter {
     }
 }
 
+/// The physical devices' marketing names — the shells' GPU-picker source
+/// (`punktfunk-session --list-adapters`). No surface and no logical device; discrete
+/// GPUs first (mirroring `pick_device`'s tie-break), duplicates collapsed (the name is
+/// the whole `PUNKTFUNK_VK_ADAPTER` match key, so a second identical card adds nothing).
+/// Same 1.3 instance the presenter creates, so the list matches what streaming sees.
+pub fn list_adapters() -> Result<Vec<String>> {
+    let entry = unsafe { ash::Entry::load() }.context("libvulkan not loadable")?;
+    let app_name = CString::new("punktfunk-session").unwrap();
+    let app_info = vk::ApplicationInfo::default()
+        .application_name(&app_name)
+        .api_version(vk::API_VERSION_1_3);
+    let instance = unsafe {
+        entry.create_instance(
+            &vk::InstanceCreateInfo::default().application_info(&app_info),
+            None,
+        )
+    }
+    .context("vkCreateInstance")?;
+    let mut ranked: Vec<(u8, String)> = unsafe { instance.enumerate_physical_devices() }?
+        .into_iter()
+        .map(|d| {
+            let props = unsafe { instance.get_physical_device_properties(d) };
+            let rank = match props.device_type {
+                vk::PhysicalDeviceType::DISCRETE_GPU => 0u8,
+                vk::PhysicalDeviceType::INTEGRATED_GPU => 1,
+                _ => 2,
+            };
+            let name = props
+                .device_name_as_c_str()
+                .map(|c| c.to_string_lossy().into_owned())
+                .unwrap_or_default();
+            (rank, name)
+        })
+        .filter(|(_, n)| !n.is_empty())
+        .collect();
+    unsafe { instance.destroy_instance(None) };
+    ranked.sort_by_key(|(r, _)| *r); // stable: enumeration order within each tier
+    let mut names: Vec<String> = Vec::new();
+    for (_, n) in ranked {
+        if !names.contains(&n) {
+            names.push(n);
+        }
+    }
+    Ok(names)
+}
+
 /// First physical device with a queue family that does graphics + present here;
 /// `PUNKTFUNK_VK_DEVICE=<index>` overrides on multi-GPU boxes.
 fn pick_device(