style(windows): rustfmt install.rs to unbreak cargo fmt --all --check

The pnputil /add-driver call in windows/install.rs was committed unwrapped;
`cargo fmt --all --check` (which checks cfg(windows) files too) flagged it and
failed the `rust` CI job at the Format step, skipping clippy/build/test. Apply
rustfmt — no behavior change. Clears the way to cut the v0.2.0 release from
green main.

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

.cargo/audit.toml

@@ -0,0 +1,20 @@
+# cargo-audit configuration — consumed by `.gitea/workflows/audit.yml` (`cargo audit`).
+#
+# Silence only advisories that are KNOWN-UNFIXABLE and either not applicable to how we use the crate
+# or an accepted, documented risk. Keep this list TIGHT and justify every entry — an ignore here
+# means the audit job stops flagging it, so the reasoning must hold up.
+#
+# NOTE: `cargo audit` (no `--deny warnings`) fails only on *vulnerabilities*, not on the
+# `unmaintained` warnings (audiopus_sys / paste / rustls-pemfile). Those are left visible on purpose
+# so we keep getting the maintenance signal — they do not fail CI.
+
+[advisories]
+ignore = [
+    # rsa "Marvin Attack" — a timing sidechannel in RSA *decryption* (PKCS#1 v1.5 padding oracle).
+    # There is NO fixed rsa release (the constant-time rewrite is still unreleased upstream), and rsa
+    # is required for GameStream/Moonlight pairing. Crucially, the host uses rsa ONLY for PKCS#1 v1.5
+    # SIGNING / VERIFYING (gamestream/cert.rs + gamestream/pairing.rs: SigningKey / VerifyingKey /
+    # Signer / Verifier) — it never performs RSA decryption, which is the operation Marvin targets.
+    # So the vulnerable code path is not exercised. Revisit if a fixed rsa ships or we add RSA decrypt.
+    "RUSTSEC-2023-0071",
+]

.dockerignore

@@ -1,9 +1,9 @@
 # Root build context is used only by web/Dockerfile, which needs web/ and
-# docs/api/openapi.json. Allowlist those; keep everything else (target/, .git, crates)
+# api/openapi.json. Allowlist those; keep everything else (target/, .git, crates)
 # out of the context upload.
 *
 !web
-!docs/api/openapi.json
+!api/openapi.json
 web/node_modules
 web/.output
 web/dist

.gitea/workflows/apple.yml

@@ -2,6 +2,11 @@
 # see scripts/ci/setup-macos-runner.sh). Builds the Rust core into
 # PunktfunkCore.xcframework, then builds + tests the Swift package. Network-dependent
 # tests (RemoteFirstLightTests) self-skip without PUNKTFUNK_REMOTE_HOST.
+#
+# A second job (`screenshots`) captures the App Store Connect screenshots of the REAL UI
+# (mac window + iOS/iPad/tvOS Simulators, see clients/apple/tools/screenshots.sh) and attaches
+# them to the run as a single zip artifact (`punktfunk-appstore-screenshots`). It is isolated
+# from the build/test job and best-effort, so a capture gap never reds the core signal.
 name: apple
 
 on:
@@ -37,3 +42,55 @@ jobs:
       - name: Test (unit + real-codec round trip; remote tests self-skip)
         working-directory: clients/apple
         run: swift test
+
+  # App Store screenshots of the real UI, zipped and attached to the run as a build artifact.
+  # Skipped on PRs (cost); runs on main pushes + manual dispatch. Needs the build/test job green
+  # first, and is a separate job so a capture hiccup can never red the core signal.
+  #
+  # Scope = the two REQUIRED iOS sizes (iPhone 6.9" + iPad 13"), captured on the Simulator
+  # (`simctl io screenshot`, no Screen Recording grant needed). macOS and tvOS are deliberately
+  # NOT in CI: the self-hosted runner is headless (no window-server session), so the mac window
+  # capture can't run there; tvOS needs the Tier-3 build-std slice. Generate those two locally on
+  # a GUI Mac with `clients/apple/tools/screenshots.sh macos tvos`.
+  screenshots:
+    needs: swift
+    if: gitea.event_name != 'pull_request'
+    runs-on: macos-arm64
+    timeout-minutes: 75
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Rust toolchain + iOS Simulator targets
+        run: |
+          if ! command -v rustup >/dev/null && [ ! -x "$HOME/.cargo/bin/rustup" ]; then
+            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
+              | sh -s -- -y --no-modify-path --profile minimal
+          fi
+          RUSTUP="$(command -v rustup || echo "$HOME/.cargo/bin/rustup")"
+          dirname "$RUSTUP" >> "$GITHUB_PATH"
+          "$RUSTUP" target add aarch64-apple-darwin x86_64-apple-darwin \
+            aarch64-apple-ios aarch64-apple-ios-sim x86_64-apple-ios
+
+      - name: Build PunktfunkCore.xcframework (mac + iOS slices)
+        run: BUILD_IOS=1 bash scripts/build-xcframework.sh
+
+      - name: Capture screenshots (iPhone 6.9" + iPad 13"; auto-creates the Simulators)
+        working-directory: clients/apple
+        env:
+          SETTLE: "8" # Simulators settle slower than a local run
+        run: |
+          # Independent invocations: one platform failing skips it, not the other.
+          bash tools/screenshots.sh ios  || echo "::warning::iOS (iPhone 6.9\") screenshots skipped"
+          bash tools/screenshots.sh ipad || echo "::warning::iPad 13\" screenshots skipped"
+          echo "Produced:"; ls -la screenshots || true
+
+      - name: Upload screenshots (zip artifact)
+        if: always()
+        # v3, not v4: Gitea's artifact backend identifies as GHES, which @actions/artifact v2+
+        # (upload-artifact@v4) refuses. v3 uses the older API Gitea supports; download is still a zip.
+        uses: actions/upload-artifact@v3
+        with:
+          name: punktfunk-appstore-screenshots
+          path: clients/apple/screenshots
+          if-no-files-found: warn
+          retention-days: 30

.gitea/workflows/flatpak.yml

@@ -24,7 +24,7 @@ on:
   push:
     branches: [main]
     # The flatpak is the CLIENT — only rebuild when the client/core/manifest change, not on every
-    # docs/host push (this is a heavy flatpak-builder run). Tags (v*, the client release) build too.
+    # design/host push (this is a heavy flatpak-builder run). Tags (v*, the client release) build too.
     paths:
       - 'clients/linux/**'
       - 'crates/punktfunk-core/**'

.gitea/workflows/release.yml

@@ -46,8 +46,8 @@ name: release
 
 on:
   push:
-    # Canary: a relevant main push uploads the iOS + macOS builds to TestFlight (Apple's own
-    # canary channel) — no notarized DMG, no tvOS (those are stable-only; see the per-step gates).
+    # Canary: a relevant main push uploads the iOS + macOS + tvOS builds to TestFlight (Apple's
+    # own canary channel) — no notarized DMG (that's stable-only; see the per-step gates).
     # Heavy on the shared mac-mini runner, so paths-filtered; the TestFlight steps are
     # continue-on-error until the App Store Connect record exists, so this no-ops until then.
     branches: [main]
@@ -118,16 +118,11 @@ jobs:
           "$RUSTUP" toolchain install nightly --profile minimal
           "$RUSTUP" component add rust-src --toolchain nightly
 
-      - name: Build PunktfunkCore.xcframework (mac + iOS; + tvOS on stable tags)
-        # tvOS uses nightly -Zbuild-std (slow) — build it only for a real release, not on every
-        # canary main push.
-        run: |
-          TV=""
-          case "$GITHUB_REF" in refs/tags/v*) TV="BUILD_TVOS=1" ;; esac
-          # `env` (not a bare prefix): a $TV-expanded `NAME=val` word is NOT re-promoted to a shell
-          # assignment, so `BUILD_IOS=1 $TV bash …` would try to RUN `BUILD_TVOS=1` (exit 127). env
-          # treats its leading NAME=val args as assignments post-expansion; empty $TV is a no-op.
-          env BUILD_IOS=1 $TV bash scripts/build-xcframework.sh
+      - name: Build PunktfunkCore.xcframework (mac + iOS + tvOS)
+        # tvOS is a tier-3 target (nightly -Zbuild-std): slow on the first build, then cached on
+        # the self-hosted runner. Built on canary too so the tvOS archive/upload below runs on the
+        # same track as iOS/macOS (the nightly toolchain is installed unconditionally above).
+        run: BUILD_IOS=1 BUILD_TVOS=1 bash scripts/build-xcframework.sh
 
       - name: Stage App Store Connect API key
         env:
@@ -293,9 +288,9 @@ jobs:
             -authenticationKeyIssuerID "${{ secrets.ASC_API_ISSUER_ID }}"
 
       - name: tvOS — archive + upload to TestFlight
-        # Stable only — the tvOS xcframework slice is built just for releases (above), and the
-        # App Store Connect record + runner platform are tvOS prerequisites.
-        if: startsWith(gitea.ref, 'refs/tags/v') && (gitea.event_name != 'workflow_dispatch' || inputs.testflight == 'true')
+        # Canary + stable, the same track as iOS/macOS — the tvOS xcframework slice is now built
+        # on every apple push (above), so this matches the iOS step's gate exactly.
+        if: gitea.event_name != 'workflow_dispatch' || inputs.testflight == 'true'
         # Needs tvOS added to the App Store Connect app record + the tvOS platform installed
         # on the runner (xcodebuild -downloadPlatform tvOS).
         continue-on-error: true

.gitea/workflows/windows-drivers-provision.yml

@@ -0,0 +1,27 @@
+# One-shot provisioning of the WDK + cargo-wdk onto the persistent self-hosted windows-amd64 runner, so
+# the all-Rust UMDF drivers can build there (design/windows-host-rewrite.md, M0). The runner has the base
+# Windows SDK + MSVC + LLVM + Rust but NOT the WDK (no km/wdf/iddcx headers) or cargo-wdk.
+#
+# Dispatch manually (workflow_dispatch). Idempotent: re-running is a near no-op once provisioned. The
+# install persists on the runner (real box, not an ephemeral container), so this runs once, not per build.
+name: windows-drivers-provision
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'scripts/ci/provision-windows-wdk.ps1'
+      - '.gitea/workflows/windows-drivers-provision.yml'
+
+jobs:
+  provision:
+    runs-on: windows-amd64
+    timeout-minutes: 60
+    defaults:
+      run:
+        shell: pwsh
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install WDK + cargo-wdk on the runner
+        run: ./scripts/ci/provision-windows-wdk.ps1

.gitea/workflows/windows-drivers.yml

@@ -0,0 +1,150 @@
+# Windows driver workspace CI — runs on the self-hosted Windows runner (home-windows-1, host mode;
+# label windows-amd64). Part of the Windows-host rewrite (design/windows-host-rewrite.md, M0).
+#
+# Stage 1 (this file): PROBE the runner's driver toolchain (WDK / EWDK / cargo-make / LLVM / the
+# inf2cat/stampinf/devgen/signtool tools) so we know what's provisioned BEFORE writing driver code,
+# and build+test the owned ABI crate (pf-driver-proto) on MSVC to prove it compiles cross-OS and the
+# CI wiring works. The runner has no RTX GPU — that's fine: builds, the IddCx bindgen/link, the
+# /INTEGRITYCHECK self-sign-load, and (later) IDD-push frame flow on the basic display do not need one;
+# only live NVENC encode does, which defers to the RTX box.
+#
+# shell: pwsh deliberately (PowerShell 5.1's Out-File -Encoding utf8 prepends a BOM that corrupts the
+# first GITHUB_ENV line — see windows.yml).
+name: windows-drivers
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - '.gitea/workflows/windows-drivers.yml'
+      - 'crates/pf-driver-proto/**'
+      - 'packaging/windows/drivers/**'
+  pull_request:
+    paths:
+      - '.gitea/workflows/windows-drivers.yml'
+      - 'crates/pf-driver-proto/**'
+      - 'packaging/windows/drivers/**'
+
+# Driver builds need the WDK on the runner (provision once via windows-drivers-provision.yml).
+
+jobs:
+  probe-and-proto:
+    runs-on: windows-amd64
+    timeout-minutes: 30
+    defaults:
+      run:
+        shell: pwsh
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Probe driver toolchain (informational — never fails the job)
+        continue-on-error: true
+        run: |
+          $ErrorActionPreference = 'Continue'
+          function head($t) { Write-Host ""; Write-Host "===== $t =====" }
+
+          head "Windows Kits roots"
+          $kits = @('C:\Program Files (x86)\Windows Kits\10', 'C:\Program Files\Windows Kits\10')
+          foreach ($k in $kits) { if (Test-Path $k) { Write-Host "found: $k" } }
+
+          head "SDK Include versions (um vs km — km => WDK present)"
+          foreach ($k in $kits) {
+            $inc = Join-Path $k 'Include'
+            if (Test-Path $inc) {
+              Get-ChildItem $inc -Directory | ForEach-Object {
+                $hasUm = Test-Path (Join-Path $_.FullName 'um')
+                $hasKm = Test-Path (Join-Path $_.FullName 'km')
+                $wdf   = Test-Path (Join-Path $_.FullName 'km\wdf\umdf\2.31')
+                $iddcx = (Get-ChildItem (Join-Path $_.FullName 'um\iddcx') -Directory -ErrorAction SilentlyContinue | ForEach-Object { $_.Name }) -join ','
+                Write-Host ("{0,-16} um={1,-5} km={2,-5} wdf2.31={3,-5} iddcx=[{4}]" -f $_.Name, $hasUm, $hasKm, $wdf, $iddcx)
+              }
+            }
+          }
+
+          head "Driver tooling (inf2cat / stampinf / signtool / devgen / InfVerif)"
+          foreach ($tool in 'inf2cat.exe','stampinf.exe','signtool.exe','devgen.exe','InfVerif.exe','makecat.exe') {
+            $hits = @()
+            foreach ($k in $kits) {
+              $hits += Get-ChildItem -Path $k -Filter $tool -Recurse -ErrorAction SilentlyContinue |
+                       Where-Object { $_.FullName -match '\\x64\\' } | Select-Object -First 1 -ExpandProperty FullName
+            }
+            $hits = $hits | Where-Object { $_ } | Select-Object -First 1
+            Write-Host ("{0,-14} -> {1}" -f $tool, ($(if ($hits) { $hits } else { 'NOT FOUND' })))
+          }
+
+          head "EWDK"
+          Write-Host ("EWDKROOT = " + ($env:EWDKROOT ?? '<unset>'))
+
+          head "LLVM / clang (bindgen 0.72 builds on the runner default clang)"
+          Write-Host ("LIBCLANG_PATH = " + ($env:LIBCLANG_PATH ?? '<unset>'))
+          $clang = Get-Command clang -ErrorAction SilentlyContinue
+          if ($clang) { & clang --version } else { Write-Host "clang: NOT on PATH" }
+
+          head "cargo-make (the gamepad drivers' build driver)"
+          $cm = & cargo make --version 2>&1; Write-Host $cm
+
+          head "Rust + targets"
+          & rustc -V; & cargo -V
+          Write-Host "installed targets:"; & rustup target list --installed
+
+          head "Env knobs the WDK build cares about"
+          Write-Host ("Version_Number = " + ($env:Version_Number ?? '<unset>'))
+          Write-Host ("CARGO_HOME     = " + ($env:CARGO_HOME ?? '<unset>'))
+          Write-Host ("CARGO_TARGET_DIR (daemon) = " + ($env:CARGO_TARGET_DIR ?? '<unset>'))
+
+      - name: Build + test pf-driver-proto (MSVC)
+        run: |
+          # Short target dir to dodge MAX_PATH inside the deep act host workdir (see windows.yml).
+          $env:CARGO_TARGET_DIR = "C:\t\drv"
+          cargo build -p pf-driver-proto
+          cargo test  -p pf-driver-proto
+          cargo clippy -p pf-driver-proto --all-targets -- -D warnings
+          cargo fmt -p pf-driver-proto -- --check
+
+  # Build the UMDF driver workspace (wdk-probe) on windows-drivers-rs: proves wdk-sys bindgen/link works
+  # on the runner's WDK + LLVM, that pf-driver-proto path-deps into a driver, and exposes the produced
+  # DLL's FORCE_INTEGRITY (/INTEGRITYCHECK) bit — the M0 self-signed-load question.
+  driver-build:
+    runs-on: windows-amd64
+    timeout-minutes: 45
+    defaults:
+      run:
+        shell: pwsh
+        # In-tree target dir on purpose: wdk-build's find_top_level_cargo_manifest() walks UP from OUT_DIR
+        # to the first ancestor with a Cargo.lock, so a relocated CARGO_TARGET_DIR (C:\t\…) hides the
+        # workspace lock and it panics. The driver deps have no deep CMake-from-source crates, so the
+        # default in-tree target stays well under MAX_PATH (unlike the SDL3/audiopus client build).
+        working-directory: packaging/windows/drivers
+    env:
+      # wdk-build otherwise picks 10.0.28000.0 (no km/crt) and bindgen fails — pin the WDK SDK version.
+      Version_Number: '10.0.26100.0'
+      # No LIBCLANG_PATH pin: the vendored bindgen 0.72 builds clean on the runner's default clang 22
+      # (the shipping pack proves it). A 0.71-era layout-test overflow once needed LLVM 21; the 0.72 bump
+      # retired that — see design/windows-build-and-packaging.md.
+    steps:
+      - uses: actions/checkout@v4
+      - name: Ensure WDK + cargo-wdk (idempotent self-provision)
+        # Run the provisioning script here too so driver-build is self-sufficient and never races a
+        # separate provision run on the single runner. Path is relative to the job working-directory
+        # (packaging/windows/drivers). Near-noop once the toolchain is present.
+        run: ../../../scripts/ci/provision-windows-wdk.ps1
+      - name: cargo build the driver workspace (wdk-probe + wdk-iddcx + pf-vdisplay)
+        # Whole workspace: wdk-probe (toolchain/surface-assert probe) + wdk-iddcx (DDI wrappers) +
+        # pf-vdisplay (the real IddCx driver). pf-vdisplay linking proves the IddCx call sites resolve
+        # against IddCxStub end-to-end (M1 step 2 gate).
+        run: cargo build -v
+      - name: Inspect /INTEGRITYCHECK (before) — expect FORCE_INTEGRITY set by wdk-build
+        run: |
+          # explicit --target (.cargo/config.toml) -> output under the triple subdir.
+          $dll = "target\x86_64-pc-windows-msvc\debug\pf_vdisplay.dll"
+          if (-not (Test-Path $dll)) { throw "pf_vdisplay.dll not produced at $dll" }
+          $b = [IO.File]::ReadAllBytes($dll)
+          $pe = [BitConverter]::ToInt32($b, 0x3c)
+          $dllchar = [BitConverter]::ToUInt16($b, $pe + 0x5e)   # OptionalHeader.DllCharacteristics
+          Write-Host ("pf_vdisplay.dll built OK ({0:N0} bytes)" -f (Get-Item $dll).Length)
+          Write-Host ("BEFORE: DllCharacteristics = 0x{0:X4}; FORCE_INTEGRITY = {1}" -f $dllchar, (($dllchar -band 0x0080) -ne 0))
+      - name: Clear FORCE_INTEGRITY (self-signed-load fix) + verify
+        # wdk-build sets /INTEGRITYCHECK unconditionally -> a self-signed driver won't load. Clear the PE
+        # bit deterministically (the reusable packaging step; signing/.cat happen later for real drivers).
+        run: ../clear-force-integrity.ps1 -Path target\x86_64-pc-windows-msvc\debug\pf_vdisplay.dll

.gitea/workflows/windows-host.yml

@@ -1,6 +1,7 @@
 # Build the punktfunk Windows HOST as a signed Inno Setup installer and publish it to Gitea's generic
 # package registry, so a Windows GPU box can install the streaming host (SYSTEM service + bundled
-# SudoVDA virtual-display driver) from one signed setup.exe. Runs on the self-hosted Windows runner
+# pf-vdisplay virtual-display driver + the web management console, run by a scheduled task on a bundled
+# bun) from one signed setup.exe. Runs on the self-hosted Windows runner
 # (host mode; scripts/ci/setup-windows-runner.ps1) — same MSVC/Windows-SDK/LLVM env as windows.yml.
 #
 # Why an installer and not MSIX (like the client): the host installs a LocalSystem SCM service that
@@ -20,9 +21,12 @@
 # an ephemeral self-signed cert is generated and its public .cer published next to the installer
 # (import once to LocalMachine\TrustedPublisher). See packaging/windows/pack-host-installer.ps1.
 #
-# NVENC: the host builds with --features nvenc; the only link need is nvencodeapi.lib, synthesised
-# from a 2-export .def with llvm-dlltool (no GPU/SDK at build time). The resulting exe is NVIDIA-only
-# by design — CI never launches it, so no GPU is needed here.
+# GPU backends: the host builds with --features nvenc,amf-qsv = all three vendors in one installer.
+#  - NVENC (NVIDIA, direct SDK): the only link need is nvencodeapi.lib, synthesised from a 2-export
+#    .def with llvm-dlltool (no GPU/SDK at build time).
+#  - AMF/QSV (AMD/Intel, libavcodec): link-imports the FFmpeg libs from FFMPEG_DIR (the BtbN gpl-shared
+#    tree the client uses; includes the *_amf/*_qsv encoders) and bundles its DLLs into the installer.
+# CI never launches the exe, so no GPU is needed here — this is build + Windows clippy coverage only.
 name: windows-host
 
 on:
@@ -32,7 +36,8 @@ on:
       - 'crates/punktfunk-host/**'
       - 'crates/punktfunk-core/**'
       - 'packaging/windows/**'
-      - 'scripts/windows/host.env.example'
+      - 'scripts/windows/**'
+      - 'web/**'
       - 'Cargo.lock'
       - 'Cargo.toml'
       - '.gitea/workflows/windows-host.yml'
@@ -51,6 +56,22 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Locale-safety gate (installer-run scripts must be ASCII)
+        shell: pwsh
+        # The installer runs these via powershell.exe (Windows PowerShell 5.1) and cmd.exe on the END
+        # USER's box. PS 5.1 reads a BOM-less script in the active ANSI codepage, so on a non-UTF-8 locale
+        # (e.g. German Windows-1252) a stray em-dash mis-decodes into a curly quote and the script aborts
+        # with "unterminated string" - exactly how the pf-vdisplay driver install silently failed in the
+        # field. Keep every installer-run script pure ASCII (matches install-gamepad-drivers.ps1).
+        run: |
+          $bad = Get-ChildItem packaging/windows/*.ps1, scripts/windows/*.ps1, scripts/windows/*.cmd -ErrorAction SilentlyContinue |
+            Where-Object { [IO.File]::ReadAllText($_.FullName) -match '[^\x00-\x7F]' }
+          if ($bad) {
+            $bad.FullName | ForEach-Object { Write-Output "::error::non-ASCII in installer-run script: $_" }
+            throw "installer-run scripts must be pure ASCII (PS 5.1 mis-parses them on non-UTF-8 locales)"
+          }
+          Write-Output "installer-run scripts are ASCII-clean"
+
       - name: Configure + version
         shell: pwsh
         run: |
@@ -59,6 +80,13 @@ jobs:
           # (pwsh Out-File utf8 = no BOM, unlike Windows PowerShell 5.1 — keeps the first line clean).
           "CARGO_TARGET_DIR=C:\t" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
           "CARGO_WORKSPACE_DIR=$env:GITHUB_WORKSPACE" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          # FFMPEG_DIR: the same BtbN gpl-shared x64 tree the Windows CLIENT links against (provisioned
+          # by scripts/ci/setup-windows-runner.ps1). The host's AMD/Intel AMF/QSV encode backend
+          # (--features amf-qsv) link-imports avcodec/avutil/swscale from it; pack-host-installer.ps1
+          # then bundles its bin\*.dll into the installer. LIBCLANG_PATH is in the runner daemon env.
+          if (-not $env:FFMPEG_DIR) {
+            "FFMPEG_DIR=C:\Users\Public\ffmpeg" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          }
           $v = if ($env:GITHUB_REF -like 'refs/tags/v*') {
             $env:GITHUB_REF_NAME -replace '^v', ''
           } else {
@@ -74,14 +102,27 @@ jobs:
           & packaging/windows/nvenc/gen-nvenc-importlib.ps1 -OutDir C:\t\nvenc
           "PUNKTFUNK_NVENC_LIB_DIR=C:\t\nvenc" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
 
-      - name: Build (release, nvenc)
+      - name: Build (release, nvenc + amf-qsv)
         shell: pwsh
-        run: cargo build --release -p punktfunk-host --features nvenc
+        # All-vendor host: NVENC (NVIDIA, direct SDK) + AMF/QSV (AMD/Intel, libavcodec via FFMPEG_DIR).
+        run: cargo build --release -p punktfunk-host --features nvenc,amf-qsv
 
       - name: Clippy (host, Windows)
         shell: pwsh
         # First-ever Windows lint coverage for the host (Linux CI never lints the windows-cfg code).
-        run: cargo clippy -p punktfunk-host --features nvenc -- -D warnings
+        run: cargo clippy -p punktfunk-host --features nvenc,amf-qsv -- -D warnings
+
+      - name: Build + lint the HDR Vulkan layer (pf-vkhdr-layer)
+        shell: pwsh
+        # Standalone cdylib (own [workspace]) the installer bundles + registers (it lets Vulkan games
+        # like Doom use HDR on the virtual display). Lint here so a regression fails CI instead of
+        # silently shipping the host without the layer (pack-host-installer.ps1 builds it non-fatally).
+        # Windows-only FFI (user32 + the vk_layer loader glue) → can't be linted on the Linux CI.
+        run: |
+          Push-Location packaging/windows/pf-vkhdr-layer
+          cargo fmt --check; if ($LASTEXITCODE) { throw "pf-vkhdr-layer rustfmt" }
+          cargo clippy --release -- -D warnings; if ($LASTEXITCODE) { throw "pf-vkhdr-layer clippy" }
+          Pop-Location
 
       - name: Ensure Inno Setup
         shell: pwsh
@@ -91,6 +132,59 @@ jobs:
             choco install innosetup -y --no-progress
           }
 
+      - name: Fetch portable bun runtime (build tool + bundled to run the console)
+        shell: pwsh
+        run: |
+          # ONE pinned bun, used both to BUILD the console and shipped in the installer to RUN it. The
+          # .output is self-contained (Nitro noExternals — deps bundled + tree-shaken, no node_modules),
+          # so the installer ships just bun + a ~75-file .output instead of node + a node_modules forest.
+          $ver = 'bun-v1.3.14'
+          $url = "https://github.com/oven-sh/bun/releases/download/$ver/bun-windows-x64.zip"
+          New-Item -ItemType Directory -Force -Path C:\t | Out-Null
+          $zip = 'C:\t\bun.zip'; $dst = 'C:\t\bundist'
+          Invoke-WebRequest -Uri $url -OutFile $zip
+          if (Test-Path $dst) { Remove-Item $dst -Recurse -Force }
+          Expand-Archive -Path $zip -DestinationPath $dst -Force
+          $bun = (Get-ChildItem -Path $dst -Recurse -Filter bun.exe | Select-Object -First 1).FullName
+          if (-not $bun) { throw "bun.exe not found in $url" }
+          "BUN_EXE=$bun" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          & $bun --version
+
+      - name: Build + smoke-boot web console (bun)
+        shell: pwsh
+        env:
+          # PAT with read access to the unom org packages — the @unom npm registry needs auth to BUILD.
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        # The bun fetched above builds the Nitro server AND runs it. noExternals (vite.config) makes the
+        # output self-contained, so there's no .output/server install — the installer ships bun + the
+        # ~75-file .output. The runner is SYSTEM with no ~/.npmrc, so supply the private @unom token in
+        # the SYSTEM home .npmrc to BUILD (kept OUT of the shipped bundle — web\.npmrc has only the
+        # registry mapping, and nothing copies it into .output).
+        run: |
+          $bun = $env:BUN_EXE
+          if ($env:REGISTRY_TOKEN) {
+            $rc = Join-Path $env:USERPROFILE '.npmrc'
+            Add-Content -Path $rc -Value '@unom:registry=https://git.unom.io/api/packages/unom/npm/'
+            Add-Content -Path $rc -Value "//git.unom.io/api/packages/unom/npm/:_authToken=$env:REGISTRY_TOKEN"
+          }
+          Push-Location web
+          & $bun install --frozen-lockfile; if ($LASTEXITCODE) { throw "bun install failed ($LASTEXITCODE)" }
+          & $bun run build; if ($LASTEXITCODE) { throw "web build failed ($LASTEXITCODE)" }
+          if (Select-String -Path .output\server\index.mjs -Pattern 'Bun\.serve' -Quiet) {
+            throw "web build is a bun bundle (Bun.serve) - need the node-server preset"
+          }
+          Pop-Location
+          # Gate the installer on a real boot under the BUNDLED bun (the runtime it ships), serving /login.
+          $env:PORT = '3009'; $env:HOST = '127.0.0.1'; $env:PUNKTFUNK_UI_PASSWORD = 'ci'
+          $server = (Resolve-Path 'web\.output\server\index.mjs').Path
+          $p = Start-Process -FilePath $bun -ArgumentList $server -PassThru -WindowStyle Hidden
+          Start-Sleep -Seconds 4
+          try { $code = (Invoke-WebRequest -Uri 'http://127.0.0.1:3009/login' -UseBasicParsing -TimeoutSec 10).StatusCode } catch { $code = 0 }
+          Stop-Process -Id $p.Id -Force -ErrorAction SilentlyContinue
+          Write-Output "web console smoke (bun): /login -> $code"
+          if ($code -ne 200) { throw "web console failed to boot under bun" }
+          "WEB_OUTPUT_DIR=$((Resolve-Path 'web\.output').Path)" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+
       - name: Pack + sign installer
         shell: pwsh
         env:

.gitignore

@@ -11,6 +11,8 @@ dist/
 clients/apple/.build/
 clients/apple/PunktfunkCore.xcframework/
 clients/apple/.swiftpm/
+# Generated App Store screenshots (tools/screenshots.sh output; uploaded as a CI artifact)
+clients/apple/screenshots/
 # Xcode per-user state
 xcuserdata/
 

CLAUDE.md

@@ -2,7 +2,7 @@
 
 Low-latency desktop/game streaming stack, Linux-first, with a shared Rust protocol core
 (`punktfunk-core`) exposed over a C ABI and native clients per platform. Full design:
-[`docs/implementation-plan.md`](docs/implementation-plan.md). Status table: `README.md`.
+[`design/implementation-plan.md`](design/implementation-plan.md). Status table: `README.md`.
 
 ## Where the work stands
 
@@ -27,7 +27,15 @@ Low-latency desktop/game streaming stack, Linux-first, with a shared Rust protoc
   Input: mouse/keyboard (libei via RemoteDesktop portal on KWin/GNOME, gamescope's own EIS
   socket, wlr protocols on Sway) and **gamepads** (uinput X-Box-360 pads + rumble
   back-channel; validated live — pad created/destroyed with the session). Management REST API +
-  checked-in OpenAPI doc (`mgmt.rs`).
+  checked-in OpenAPI doc (`mgmt.rs`). **Web-console performance capture** (`stats_recorder.rs`,
+  design: [`design/stats-capture-plan.md`](design/stats-capture-plan.md)): the operator arms stats
+  recording from the web console, plays, stops, and reviews the run as graphs (per-stage latency
+  breakdown · fps new/repeat · goodput · loss/FEC). A shared `Arc<StatsRecorder>` ring (the hot-path
+  gate is a runtime `AtomicBool`, replacing the startup-only `PUNKTFUNK_PERF`) is fed by **both** the
+  native `virtual_stream` and the GameStream encode loop at their existing ~2 s/~1 s aggregation
+  boundary, and finished captures are saved as on-disk recordings
+  (`~/.config/punktfunk/captures/*.json`) browsable/exportable from the console's **Performance** page
+  (recharts). Endpoints `/api/v1/stats/*` (bearer-only). *Implemented; not yet on-glass validated.*
 - **Native protocol (`punktfunk/1`): full session planes, validated live.** QUIC
   control plane (`punktfunk-core` `quic` feature: Hello{mode}/Welcome{full Config}/Start), data
   plane = the hardened core `Session` over raw UDP with **GF(2¹⁶) Leopard FEC + AES-GCM**
@@ -70,21 +78,50 @@ Low-latency desktop/game streaming stack, Linux-first, with a shared Rust protoc
   capability; impulse-trigger rumble is unreachable through a virtual pad), and the UHID
   `hid-playstation` pads — **DualSense** (adaptive triggers, lightbar, touchpad, motion) and
   **DualShock 4** (lightbar, touchpad, motion, rumble; DualSense minus adaptive triggers / player
-  LEDs / mute). The UHID pads need a Linux host; off Linux they (and One/Series) fold into Xbox 360.
-  Clients auto-resolve the type from the physical controller (DS5→DualSense, DS4→DualShock 4,
-  Xbox One→Xbox One). Windows-host DualShock 4 (ViGEm) is not yet wired — Windows clients asking for
-  DS4 get Xbox 360 for now.
-- **Windows host: implemented and shipping (NVIDIA-only, x64-only).** `#[cfg(windows)]` backends
+  LEDs / mute). DualSense and DualShock 4 each have a Linux (UHID `hid-playstation`) **and a Windows
+  (UMDF minidriver)** backend — `inject/dualsense_windows.rs` + `inject/dualshock4_windows.rs`, one
+  driver serving either identity per a `device_type` byte the host stamps into shared memory (the DS4
+  reuses the same SwDeviceCreate game-detection identity fix as the DualSense). One/Series stays
+  Linux-only and folds into Xbox 360 off it. Clients auto-resolve the type from the physical controller
+  (DS5→DualSense, DS4→DualShock 4, Xbox One→Xbox One). **Windows uses ZERO external gamepad
+  dependencies — ViGEmBus is gone.** Xbox 360 (XInput) runs on a UMDF2 **XUSB companion** driver
+  (`packaging/windows/xusb-driver/`, `inject/gamepad_windows.rs`) that registers `GUID_DEVINTERFACE_XUSB`
+  and answers the buffered XInput IOCTLs from a shared section, so classic `XInputGetState`/`SetState`
+  work with no kernel bus driver (validated live: slot connected, state + rumble round-trip; Xbox One
+  folds to this 360 path). All three UMDF drivers (DualSense/DS4 + XUSB) are bundled + pnputil-installed
+  by the Inno Setup installer (`packaging/windows/gamepad-drivers/` + `install-gamepad-drivers.ps1`).
+  **Multi-pad ready**: the host stamps each pad's index into the device Location (`pszDeviceLocation`),
+  the driver reads it (`WdfDeviceAllocAndQueryProperty`) to map its own `*-shm-<index>`, and
+  `UmdfHostProcessSharing=ProcessSharingDisabled` gives each pad its own host (per-pad statics) —
+  validated live with 2 distinct XInput slots + 2 DualSense pads. (Client-side multi-pad forwarding is
+  the remaining piece.)
+- **Windows host: implemented and shipping (all-vendor, x64-only).** `#[cfg(windows)]` backends
   behind the same traits as Linux — DXGI Desktop Duplication capture (`capture/dxgi.rs`), **SudoVDA**
-  virtual display per session (`vdisplay/sudovda.rs`), NVENC encode (`--features nvenc`), SendInput +
-  **ViGEm** gamepads (`inject/gamepad_windows.rs`), WASAPI loopback + virtual mic (`audio/wasapi_*`).
-  Ships as a **signed Inno Setup installer** that registers a `LocalSystem` SCM service launching into
-  the interactive session for secure-desktop (UAC/lock-screen) capture (`service.rs`), bundles the
-  SudoVDA driver, and is published by `windows-host.yml`. **HDR (10-bit)**: WGC captures the HDR
-  desktop as FP16/Rgb10a2 (DDA FP16 for the secure desktop), NVENC forces HEVC Main10 + BT.2020 PQ,
-  the client auto-detects PQ from the HEVC VUI — gated by `PUNKTFUNK_10BIT` + client `VIDEO_CAP_10BIT`;
-  **Windows host only** (the Linux host stays 8-bit, blocked upstream). Newer/less battle-tested than
-  the Linux host; no AMD/Intel/software encode path. Packaging: `packaging/windows/`.
+  virtual display per session (`vdisplay/sudovda.rs`), GPU encode (NVENC `--features nvenc`; AMD/Intel
+  `--features amf-qsv`), SendInput + **ViGEm** gamepads (`inject/gamepad_windows.rs`), WASAPI loopback
+  + virtual mic (`audio/wasapi_*`). Ships as a **signed Inno Setup installer** that registers a
+  `LocalSystem` SCM service launching into the interactive session for secure-desktop (UAC/lock-screen)
+  capture (`service.rs`), bundles the SudoVDA driver + the FFmpeg DLLs, and is published by
+  `windows-host.yml`. **Encoder is GPU-aware** (`encode.rs` `open_video` + `windows_resolved_backend`):
+  `PUNKTFUNK_ENCODER=auto` (the host.env default) detects the DXGI adapter vendor → **NVENC** (NVIDIA,
+  direct SDK, `encode/nvenc.rs`), **AMF** (AMD) / **QSV** (Intel) via libavcodec
+  (`encode/ffmpeg_win.rs`, the Windows analogue of the Linux VAAPI backend — `WinVendor{Amf,Qsv}`,
+  system-memory NV12/P010 readback default + opt-in zero-copy D3D11 behind `PUNKTFUNK_ZEROCOPY` with a
+  system fallback), or software H.264 (`encode/sw.rs`, GPU-less). GameStream codec advertisement is
+  probed per-GPU on AMF/QSV (`windows_codec_support` → `serverinfo`, AV1 gated). **HDR (10-bit)**: WGC
+  captures the HDR desktop as FP16/Rgb10a2 (DDA FP16 for the secure desktop), the encoder forces HEVC
+  Main10 + BT.2020 PQ (NVENC ABGR10/P010; AMF/QSV P010 + a swscale Rgb10a2→P010 fallback), the client
+  auto-detects PQ from the HEVC VUI — gated by `PUNKTFUNK_10BIT` + client `VIDEO_CAP_10BIT`; **Windows
+  host only** (the Linux host stays 8-bit, blocked upstream). **Vulkan-game HDR over the virtual
+  display**: NVIDIA/AMD Vulkan ICDs refuse to *advertise* an HDR color space for a surface on an IddCx
+  indirect display (so Vulkan games — Doom: The Dark Ages, id Tech, etc. — say "device does not support
+  HDR"), even though the ICD happily *accepts + presents* a forced HDR swapchain there. A tiny always-on
+  Vulkan **implicit layer** (`packaging/windows/pf-vkhdr-layer/`, `VK_LAYER_PUNKTFUNK_hdr_inject`)
+  injects the `HDR10_ST2084`/scRGB surface formats into `vkGetPhysicalDeviceSurfaceFormats[2]KHR`,
+  self-gated on the display's actual advanced-color state (no-op on SDR / real monitors); bundled +
+  HKLM-registered by the installer. **Live-validated: Doom: The Dark Ages enables HDR over the virtual
+  display.** **AMF/QSV is CI-green but not yet on-glass validated** (no AMD/Intel Windows box in the
+  lab); NVENC is live-validated. Newer/less battle-tested than the Linux host. Packaging: `packaging/windows/`.
 
 ## What's left
 
@@ -177,7 +214,9 @@ Low-latency desktop/game streaming stack, Linux-first, with a shared Rust protoc
    `punktfunk-core`; phone + Android TV): NDK `AMediaCodec` hardware HEVC decode → `SurfaceView` incl.
    **HDR10** (Main10/BT.2020 PQ) with low-latency tuning + a live stats HUD (`decode.rs`/`stats.rs`),
    Opus/Oboe audio + mic uplink (`audio.rs`/`mic.rs`), gamepad input with rumble/HID feedback
-   (`feedback.rs`), `NsdManager` mDNS discovery, SPAKE2 PIN pairing + TOFU (Keystore identity +
+   (`feedback.rs`), **native `mdns-sd` mDNS discovery** (`discovery.rs`, polled over JNI — the same
+   browse the Linux/Windows clients use, replacing the flaky per-OEM `NsdManager`; Kotlin keeps only
+   the `MulticastLock` + permission UX), SPAKE2 PIN pairing + TOFU (Keystore identity +
    known-host store), Compose UI (Connect/Settings/Stream) with D-pad/controller focus nav. Built for
    `arm64-v8a` + `x86_64`; published to Google Play (Internal Testing) via `android.yml`
    (`ci/play-upload.py`). Next: real-device gamepad/HDR live-verify, presenter/latency polish.
@@ -221,8 +260,8 @@ bash crates/punktfunk-core/tests/c/run.sh   # standalone C-ABI link + round-trip
 ```
 
 Generated artifacts are **checked in** and CI fails on drift: `include/punktfunk_core.h`
-(cbindgen from `punktfunk-core/src/abi.rs`) and `docs/api/openapi.json` (regenerate with
-`cargo run -p punktfunk-host -- openapi > docs/api/openapi.json`; spec lives in `mgmt.rs`).
+(cbindgen from `punktfunk-core/src/abi.rs`) and `api/openapi.json` (regenerate with
+`cargo run -p punktfunk-host -- openapi > api/openapi.json`; spec lives in `mgmt.rs`).
 
 CI is Gitea Actions (`.gitea/workflows/`, guide: docs-site `ci.md`): `ci.yml` runs the
 workspace checks inside the `git.unom.io/unom/punktfunk-rust-ci` image plus web/docs-site
@@ -243,15 +282,16 @@ crates/punktfunk-host/
   vdisplay/{kwin,gamescope,mutter,wlroots}.rs   per-compositor client-sized virtual outputs
   zerocopy/{egl,cuda,vulkan}.rs         dmabuf → CUDA → NVENC (tiled via EGL/GL, LINEAR via Vulkan)
   inject/{libei,wlr,gamepad,dualsense}.rs   input backends (uinput xpad + UHID DualSense)
-  capture.rs · encode.rs · audio.rs · spike.rs · punktfunk1.rs · mgmt.rs · native_pairing.rs
+  encode/{nvenc,linux,vaapi,ffmpeg_win,sw}.rs   per-GPU encoders (NVENC · Linux NVENC/CUDA · VAAPI · AMF/QSV · openh264)
+  capture.rs · encode.rs · audio.rs · spike.rs · punktfunk1.rs · mgmt.rs · native_pairing.rs · stats_recorder.rs
 clients/probe/    punktfunk/1 reference/probe client (headless test/measurement tool)
 clients/linux/    native Linux client (GTK4/libadwaita · FFmpeg · PipeWire · SDL3)
 clients/windows/  native Windows client (WinUI 3 via windows-reactor · D3D11 · WASAPI · SDL3)
 clients/apple/    native macOS/iOS/tvOS client (Swift · VideoToolbox · GameController)
 clients/android/  native Android client (Kotlin app + native/ Rust JNI core over punktfunk-core)
 clients/decky/    Steam Deck Decky plugin
-crates/punktfunk-host/src/{capture/dxgi,vdisplay/sudovda,inject/gamepad_windows,audio/wasapi_*,service}.rs   Windows host backends
-web/                          TanStack web console over the mgmt API (status · devices · pairing)
+crates/punktfunk-host/src/{capture/dxgi,vdisplay/sudovda,encode/ffmpeg_win,inject/gamepad_windows,audio/wasapi_*,service}.rs   Windows host backends
+web/                          TanStack web console over the mgmt API (status · devices · pairing · performance graphs)
 packaging/                    apt(deb) · RPM/COPR · Arch/sysext · Flatpak · Bazzite bootc · Windows host installer (per-dir READMEs)
 tools/{loss-harness,latency-probe}/     measurement (plan §10)
 scripts/                  60-punktfunk.rules · punktfunk-host.service · host.env.example · headless/

Cargo.lock

@@ -2,6 +2,12 @@
 # It is not intended for manual editing.
 version = 3
 
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
 [[package]]
 name = "aead"
 version = "0.5.2"
@@ -453,6 +459,20 @@ name = "bytemuck"
 version = "1.25.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c8efb64bd706a16a1bdde310ae86b351e4d21550d98d056f22f8a7f7a2183fec"
+dependencies = [
+ "bytemuck_derive",
+]
+
+[[package]]
+name = "bytemuck_derive"
+version = "1.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f9abbd1bc6865053c427f7198e6af43bfdedc55ab791faed4fbd361d789575ff"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
 
 [[package]]
 name = "bytes"
@@ -721,6 +741,15 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "crc32fast"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9481c1c90cbf2ac953f07c8d4a58aa3945c425b7185c9154d67a65e4230da511"
+dependencies = [
+ "cfg-if",
+]
+
 [[package]]
 name = "criterion"
 version = "0.5.1"
@@ -996,6 +1025,18 @@ dependencies = [
  "pin-project-lite",
 ]
 
+[[package]]
+name = "fallible-iterator"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2acce4a10f12dc2fb14a218589d4f1f62ef011b2d0cc4b3cb1bba8e94da14649"
+
+[[package]]
+name = "fallible-streaming-iterator"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7360491ce676a36bf9bb3c56c1aa791658183a54d2744120f27285738d90465a"
+
 [[package]]
 name = "fastbloom"
 version = "0.14.1"
@@ -1074,6 +1115,16 @@ version = "0.5.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1d674e81391d1e1ab681a28d99df07927c6d4aa5b027d7da16ba32d1d21ecd99"
 
+[[package]]
+name = "flate2"
+version = "1.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"
+dependencies = [
+ "crc32fast",
+ "miniz_oxide",
+]
+
 [[package]]
 name = "flume"
 version = "0.11.1"
@@ -1097,6 +1148,12 @@ version = "0.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
 
+[[package]]
+name = "foldhash"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
+
 [[package]]
 name = "form_urlencoded"
 version = "1.2.2"
@@ -1572,7 +1629,16 @@ version = "0.15.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
 dependencies = [
- "foldhash",
+ "foldhash 0.1.5",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
+dependencies = [
+ "foldhash 0.2.0",
 ]
 
 [[package]]
@@ -1580,6 +1646,18 @@ name = "hashbrown"
 version = "0.17.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+dependencies = [
+ "foldhash 0.2.0",
+]
+
+[[package]]
+name = "hashlink"
+version = "0.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a5081f264ed7adee96ea4b4778b6bb9da0a7228b084587aa3bd3ff05da7c5a3b"
+dependencies = [
+ "hashbrown 0.17.1",
+]
 
 [[package]]
 name = "heck"
@@ -1698,12 +1776,115 @@ dependencies = [
  "tower-service",
 ]
 
+[[package]]
+name = "icu_collections"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2984d1cd16c883d7935b9e07e44071dca8d917fd52ecc02c04d5fa0b5a3f191c"
+dependencies = [
+ "displaydoc",
+ "potential_utf",
+ "utf8_iter",
+ "yoke",
+ "zerofrom",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_locale_core"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92219b62b3e2b4d88ac5119f8904c10f8f61bf7e95b640d25ba3075e6cac2c29"
+dependencies = [
+ "displaydoc",
+ "litemap",
+ "tinystr",
+ "writeable",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c56e5ee99d6e3d33bd91c5d85458b6005a22140021cc324cea84dd0e72cff3b4"
+dependencies = [
+ "icu_collections",
+ "icu_normalizer_data",
+ "icu_properties",
+ "icu_provider",
+ "smallvec",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer_data"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da3be0ae77ea334f4da67c12f149704f19f81d1adf7c51cf482943e84a2bad38"
+
+[[package]]
+name = "icu_properties"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bee3b67d0ea5c2cca5003417989af8996f8604e34fb9ddf96208a033901e70de"
+dependencies = [
+ "icu_collections",
+ "icu_locale_core",
+ "icu_properties_data",
+ "icu_provider",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_properties_data"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e2bbb201e0c04f7b4b3e14382af113e17ba4f63e2c9d2ee626b720cbce54a14"
+
+[[package]]
+name = "icu_provider"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "139c4cf31c8b5f33d7e199446eff9c1e02decfc2f0eec2c8d71f65befa45b421"
+dependencies = [
+ "displaydoc",
+ "icu_locale_core",
+ "writeable",
+ "yoke",
+ "zerofrom",
+ "zerotrie",
+ "zerovec",
+]
+
 [[package]]
 name = "id-arena"
 version = "2.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3d3067d79b975e8844ca9eb072e16b31c3c1c36928edf9c6789548c524d0d954"
 
+[[package]]
+name = "idna"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
+dependencies = [
+ "idna_adapter",
+ "smallvec",
+ "utf8_iter",
+]
+
+[[package]]
+name = "idna_adapter"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714"
+dependencies = [
+ "icu_normalizer",
+ "icu_properties",
+]
+
 [[package]]
 name = "if-addrs"
 version = "0.15.0"
@@ -1952,12 +2133,29 @@ dependencies = [
  "system-deps",
 ]
 
+[[package]]
+name = "libsqlite3-sys"
+version = "0.38.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f6c19a05435c21ac299d71b6a9c13db3e3f47c520517d58990a462a1397a61db"
+dependencies = [
+ "cc",
+ "pkg-config",
+ "vcpkg",
+]
+
 [[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
 
+[[package]]
+name = "litemap"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0"
+
 [[package]]
 name = "lock_api"
 version = "0.4.14"
@@ -2052,6 +2250,16 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
 
+[[package]]
+name = "miniz_oxide"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
 [[package]]
 name = "mio"
 version = "1.2.1"
@@ -2404,6 +2612,13 @@ version = "2.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
 
+[[package]]
+name = "pf-driver-proto"
+version = "0.0.1"
+dependencies = [
+ "bytemuck",
+]
+
 [[package]]
 name = "pin-project-lite"
 version = "0.2.17"
@@ -2477,6 +2692,15 @@ dependencies = [
  "universal-hash",
 ]
 
+[[package]]
+name = "potential_utf"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0103b1cef7ec0cf76490e969665504990193874ea05c85ff9bab8b911d0a0564"
+dependencies = [
+ "zerovec",
+]
+
 [[package]]
 name = "powerfmt"
 version = "0.2.0"
@@ -2547,6 +2771,7 @@ dependencies = [
  "jni",
  "libc",
  "log",
+ "mdns-sd",
  "ndk",
  "opus",
  "punktfunk-core",
@@ -2633,6 +2858,8 @@ dependencies = [
  "audiopus_sys",
  "axum",
  "axum-server",
+ "base64",
+ "bytemuck",
  "cbc",
  "ffmpeg-next",
  "futures-util",
@@ -2647,13 +2874,16 @@ dependencies = [
  "nvidia-video-codec-sdk",
  "openh264",
  "opus",
+ "pf-driver-proto",
  "pipewire",
  "punktfunk-core",
  "quinn",
  "rand 0.8.6",
  "rcgen",
  "reis",
+ "roxmltree",
  "rsa",
+ "rusqlite",
  "rustls",
  "rustls-pemfile",
  "rusty_enet",
@@ -2665,10 +2895,10 @@ dependencies = [
  "tower",
  "tracing",
  "tracing-subscriber",
+ "ureq",
  "utoipa",
  "utoipa-axum",
  "utoipa-scalar",
- "vigem-client",
  "wasapi",
  "wayland-backend",
  "wayland-client",
@@ -2677,6 +2907,7 @@ dependencies = [
  "wayland-scanner",
  "windows 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
  "windows-service",
+ "winreg",
  "x509-parser",
  "xkbcommon",
 ]
@@ -2979,6 +3210,15 @@ dependencies = [
  "windows-sys 0.52.0",
 ]
 
+[[package]]
+name = "roxmltree"
+version = "0.21.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1964b10c76125c36f8afe190065a4bf9a87bf324842c05701330bba9f1cacbb"
+dependencies = [
+ "memchr",
+]
+
 [[package]]
 name = "rpkg-config"
 version = "0.1.2"
@@ -3005,6 +3245,31 @@ dependencies = [
  "zeroize",
 ]
 
+[[package]]
+name = "rsqlite-vfs"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c51c9ae4df8a7fba42103df5c621fa3c37eccf3a3c650879e90fc48b11cc192c"
+dependencies = [
+ "hashbrown 0.16.1",
+ "thiserror 2.0.18",
+]
+
+[[package]]
+name = "rusqlite"
+version = "0.40.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11438310b19e3109b6446c33d1ed5e889428cf2e278407bc7896bc4aaea43323"
+dependencies = [
+ "bitflags",
+ "fallible-iterator",
+ "fallible-streaming-iterator",
+ "hashlink",
+ "libsqlite3-sys",
+ "smallvec",
+ "sqlite-wasm-rs",
+]
+
 [[package]]
 name = "rustc-hash"
 version = "2.1.2"
@@ -3455,6 +3720,12 @@ dependencies = [
  "rand_core 0.6.4",
 ]
 
+[[package]]
+name = "simd-adler32"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "703d5c7ef118737c72f1af64ad2f6f8c5e1921f818cdcb97b8fe6fc69bf66214"
+
 [[package]]
 name = "siphasher"
 version = "1.0.3"
@@ -3525,6 +3796,24 @@ dependencies = [
  "der",
 ]
 
+[[package]]
+name = "sqlite-wasm-rs"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc3efc0da82635d7e1ced0053bbbfa8c7ab9645d0bf36ceb4f7127bb85315d75"
+dependencies = [
+ "cc",
+ "js-sys",
+ "rsqlite-vfs",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "stable_deref_trait"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
+
 [[package]]
 name = "strsim"
 version = "0.11.1"
@@ -3677,6 +3966,16 @@ dependencies = [
  "time-core",
 ]
 
+[[package]]
+name = "tinystr"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8323304221c2a851516f22236c5722a72eaa19749016521d6dff0824447d96d"
+dependencies = [
+ "displaydoc",
+ "zerovec",
+]
+
 [[package]]
 name = "tinytemplate"
 version = "1.2.1"
@@ -3982,6 +4281,40 @@ version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
 
+[[package]]
+name = "ureq"
+version = "2.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "02d1a66277ed75f640d608235660df48c8e3c19f3b4edb6a263315626cc3c01d"
+dependencies = [
+ "base64",
+ "flate2",
+ "log",
+ "once_cell",
+ "rustls",
+ "rustls-pki-types",
+ "url",
+ "webpki-roots 0.26.11",
+]
+
+[[package]]
+name = "url"
+version = "2.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
+dependencies = [
+ "form_urlencoded",
+ "idna",
+ "percent-encoding",
+ "serde",
+]
+
+[[package]]
+name = "utf8_iter"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
+
 [[package]]
 name = "utf8parse"
 version = "0.2.2"
@@ -4072,15 +4405,6 @@ version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 
-[[package]]
-name = "vigem-client"
-version = "0.1.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b857e6f99efe1e1eb1e4dfb035de8ae7ec8ec56bd1928edcbd7c6e4427634d52"
-dependencies = [
- "winapi",
-]
-
 [[package]]
 name = "wait-timeout"
 version = "0.2.1"
@@ -4318,6 +4642,24 @@ dependencies = [
  "rustls-pki-types",
 ]
 
+[[package]]
+name = "webpki-roots"
+version = "0.26.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "521bc38abb08001b01866da9f51eb7c5d647a19260e00054a8c7fd5f9e57f7a9"
+dependencies = [
+ "webpki-roots 1.0.8",
+]
+
+[[package]]
+name = "webpki-roots"
+version = "1.0.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf85cb06032201fa7c6f829d7db5a7e5aa45bcc0655327713065f6f0576731bf"
+dependencies = [
+ "rustls-pki-types",
+]
+
 [[package]]
 name = "wide"
 version = "0.7.33"
@@ -4334,22 +4676,6 @@ version = "1.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "72069c3113ab32ab29e5584db3c6ec55d416895e60715417b5b883a357c3e471"
 
-[[package]]
-name = "winapi"
-version = "0.3.9"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
-dependencies = [
- "winapi-i686-pc-windows-gnu",
- "winapi-x86_64-pc-windows-gnu",
-]
-
-[[package]]
-name = "winapi-i686-pc-windows-gnu"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
-
 [[package]]
 name = "winapi-util"
 version = "0.1.11"
@@ -4359,12 +4685,6 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
-[[package]]
-name = "winapi-x86_64-pc-windows-gnu"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
-
 [[package]]
 name = "windows"
 version = "0.62.2"
@@ -4865,6 +5185,16 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "winreg"
+version = "0.56.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7d6f32a0ff4a9f6f01231eb2059cc85479330739333e0e58cadf03b6af2cca10"
+dependencies = [
+ "cfg-if",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "wit-bindgen"
 version = "0.51.0"
@@ -4959,6 +5289,12 @@ dependencies = [
  "wasmparser",
 ]
 
+[[package]]
+name = "writeable"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
+
 [[package]]
 name = "x509-parser"
 version = "0.16.0"
@@ -5002,6 +5338,29 @@ dependencies = [
  "time",
 ]
 
+[[package]]
+name = "yoke"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5"
+dependencies = [
+ "stable_deref_trait",
+ "yoke-derive",
+ "zerofrom",
+]
+
+[[package]]
+name = "yoke-derive"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+ "synstructure",
+]
+
 [[package]]
 name = "zbus"
 version = "5.16.0"
@@ -5078,12 +5437,66 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "zerofrom"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
+dependencies = [
+ "zerofrom-derive",
+]
+
+[[package]]
+name = "zerofrom-derive"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+ "synstructure",
+]
+
 [[package]]
 name = "zeroize"
 version = "1.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b97154e67e32c85465826e8bcc1c59429aaaf107c1e4a9e53c8d8ccd5eff88d0"
 
+[[package]]
+name = "zerotrie"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0f9152d31db0792fa83f70fb2f83148effb5c1f5b8c7686c3459e361d9bc20bf"
+dependencies = [
+ "displaydoc",
+ "yoke",
+ "zerofrom",
+]
+
+[[package]]
+name = "zerovec"
+version = "0.11.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "90f911cbc359ab6af17377d242225f4d75119aec87ea711a880987b18cd7b239"
+dependencies = [
+ "yoke",
+ "zerofrom",
+ "zerovec-derive",
+]
+
+[[package]]
+name = "zerovec-derive"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "zmij"
 version = "1.0.21"

Cargo.toml

@@ -3,6 +3,7 @@ resolver = "2"
 members = [
     "crates/punktfunk-core",
     "crates/punktfunk-host",
+    "crates/pf-driver-proto",
     "clients/probe",
     "clients/linux",
     "clients/windows",

README.md

@@ -1,13 +1,20 @@
-# punktfunk
+<p align="center">
+  <img src="assets/punktfunk-logo.svg" alt="punktfunk" width="320" />
+</p>
 
-**Low-latency desktop and game streaming, Linux-first.** Run the host on a Linux machine — or a
-Windows PC — with an NVIDIA GPU, connect from a Mac, PC, phone, tablet, or TV, and stream your desktop
-or games — each device at its **own native resolution and refresh rate**, over your local network.
+<p align="center"><b>Low-latency desktop and game streaming with first-class Linux and Windows hosts.</b></p>
+
+Run the host on a Linux machine or a Windows PC, connect from a Mac, PC, phone, tablet, or TV, and
+stream your desktop or games — each device at its **own native resolution and refresh rate**, over
+your local network.
 
 📖 **Documentation: [docs.punktfunk.unom.io](https://docs.punktfunk.unom.io)** — start with
 [How It Works](https://docs.punktfunk.unom.io/docs/how-it-works) or the
 [Quick Start](https://docs.punktfunk.unom.io/docs/quickstart).
 
+💬 **Community: [Discord](https://discord.gg/kaPNvzMuGU)** — chat, support, and **Android beta
+access** · **[r/Punktfunk](https://www.reddit.com/r/Punktfunk/)**.
+
 punktfunk pairs a **virtual-display streaming host** with native clients on every platform. It speaks
 the existing **GameStream** protocol, so any [Moonlight](https://moonlight-stream.org/) client works
 day one — and adds its own faster **`punktfunk/1`** protocol that breaks the ~1 Gbps FEC wall with a
@@ -19,6 +26,11 @@ protocol, FEC, and crypto, linked into the host and every client over a stable C
 - **Your device's exact mode.** For each client that connects, the host spins up a virtual display
   sized to that device — 1080p60 to a laptop, 1440p120 to a desktop, 4K to a TV, all at once. No
   letterboxing, no scaling, no rearranging your real monitors.
+- **A real virtual display on Windows, too.** On Linux the host uses per-compositor virtual outputs;
+  on Windows you get the same on-the-fly virtual display — at the client's exact mode, no physical
+  monitor or dummy HDMI plug, even on the secure desktop (UAC / lock screen). It also has **its own
+  indirect display driver (IDD)** the host pushes finished frames straight into, rather than scraping
+  a screen — tight, push-based integration that's unusual for a Windows streaming host.
 - **Low latency, GPU end to end.** Frames go straight from the compositor to the NVENC encoder with
   zero CPU copies (dmabuf → CUDA/Vulkan → NVENC), over a transport tuned for responsiveness rather
   than throughput. Stable 240 fps at 5120×1440; sub-millisecond capture-to-reassembly on a LAN.
@@ -35,7 +47,7 @@ protocol, FEC, and crypto, linked into the host and every client over a stable C
 | **Core** — `punktfunk-core` + C ABI (protocol · FEC · crypto · QUIC) | ✅ Complete & hardened |
 | **GameStream host** → stock Moonlight | ✅ Live end-to-end: pairing, RTSP, audio, per-client virtual output at native resolution, GPU zero-copy NVENC, gamepads |
 | **Native protocol** — `punktfunk/1` | ✅ Validated live: QUIC control + GF(2¹⁶) FEC/AES-GCM data plane, PIN pairing, mDNS discovery, mid-stream mode renegotiation |
-| **Windows host** (NVIDIA, x64) | 🟡 Implemented & shipping as a signed installer (DXGI capture · SudoVDA virtual display · NVENC · WASAPI · ViGEm); NVIDIA-only, newer than the Linux host |
+| **Windows host** (x64) | 🟡 Implemented & shipping as a signed installer: DXGI/WGC capture · its own all-Rust IddCx **virtual display** (secure-desktop capable) · GPU encode (NVENC on NVIDIA, AMF/QSV on AMD/Intel) · WASAPI audio · bundled virtual-gamepad drivers (no ViGEmBus) · HDR incl. Vulkan-game HDR. NVIDIA live-validated; AMD/Intel CI-green |
 | **macOS / iOS / tvOS client** (`clients/apple`) | ✅ Streaming live: VideoToolbox decode, controllers incl. DualSense, discovery, pairing, speed test |
 | **Linux client** (`clients/linux`, GTK4) | ✅ Streaming live: FFmpeg + VAAPI zero-copy decode, PipeWire audio, SDL3 controllers; ships as Flatpak/apt/rpm/Arch |
 | **Android client** (`clients/android`, phone + TV) | ✅ Streaming live: AMediaCodec decode + HDR10, Oboe audio, controllers, discovery, pairing |
@@ -61,14 +73,14 @@ roadmap: **[/docs/roadmap](https://docs.punktfunk.unom.io/docs/roadmap)**.
 
 Pick your platform and install from its package registry — the per-platform guide covers adding the
 repo, first run, and the web console. The Linux host is the primary, most battle-tested path; a
-Windows host (NVIDIA-only) also ships as a signed installer.
+Windows host also ships as a signed installer (all-vendor: NVIDIA, AMD, Intel).
 
 | Platform | Install | Guide |
 |--------|---------|-------|
 | **Ubuntu / Debian** (apt) | `sudo apt install punktfunk-host` *(after adding the repo)* | [Ubuntu — GNOME](https://docs.punktfunk.unom.io/docs/ubuntu-gnome) · [KDE](https://docs.punktfunk.unom.io/docs/ubuntu-kde) |
 | **Fedora / Bazzite** (rpm-ostree) | `rpm-ostree install punktfunk punktfunk-web` *(or the bootc image)* | [Fedora — KDE](https://docs.punktfunk.unom.io/docs/fedora-kde) · [Bazzite](https://docs.punktfunk.unom.io/docs/bazzite) |
 | **Arch / Steam Deck** (PKGBUILD / sysext) | `makepkg -si` *(Arch)* · sysext `.raw` *(SteamOS)* | [packaging/arch](packaging/arch/README.md) |
-| **Windows** (NVIDIA, x64) | signed `setup.exe` from the package registry | [Windows Host](https://docs.punktfunk.unom.io/docs/windows-host) |
+| **Windows** (x64) | signed `setup.exe` from the package registry | [Windows Host](https://docs.punktfunk.unom.io/docs/windows-host) |
 
 `punktfunk-host` is the streaming host; `punktfunk-web` is the browser console (pairing + status).
 After install, run `punktfunk-host serve` inside your desktop session (the secure native default;
@@ -113,7 +125,7 @@ and the [docs site](https://docs.punktfunk.unom.io).
 ```
 crates/
   punktfunk-core/   protocol · FEC · pacing · crypto · QUIC control plane — the C ABI (lib + cdylib + staticlib)
-  punktfunk-host/   Linux host: virtual displays · capture · encode · input · GameStream · punktfunk/1 · mgmt
+  punktfunk-host/   the host (Linux + Windows): virtual displays · capture · encode · input · GameStream · punktfunk/1 · mgmt
 clients/
   apple/    macOS / iOS / tvOS app (Swift · VideoToolbox · Metal · GameController)
   linux/    Linux desktop app (Rust · GTK4/libadwaita · FFmpeg/VAAPI · PipeWire · SDL3)
@@ -124,7 +136,7 @@ clients/
 web/                         web console (TanStack) over the management API — status · devices · pairing
 packaging/                   apt · rpm / COPR · Arch · Flatpak · Bazzite bootc image
 docs-site/                   public documentation site (Fumadocs) — https://docs.punktfunk.unom.io
-docs/                        design notes & deep-dive plans
+design/                        design notes & deep-dive plans (index: design/README.md)
 include/punktfunk_core.h     cbindgen-generated C header (checked in)
 tools/                       latency-probe · loss-harness (measurement)
 ```

api/openapi.json

@@ -978,6 +978,309 @@
         }
       }
     },
+    "/api/v1/stats/capture/live": {
+      "get": {
+        "tags": [
+          "stats"
+        ],
+        "summary": "Live in-progress capture",
+        "description": "The full sample time-series of the capture currently recording, for live graphing. `404` when\nnothing is armed.",
+        "operationId": "statsCaptureLive",
+        "responses": {
+          "200": {
+            "description": "The in-progress capture (meta + samples so far)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Capture"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No capture is currently recording",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/stats/capture/start": {
+      "post": {
+        "tags": [
+          "stats"
+        ],
+        "summary": "Start a stats capture",
+        "description": "Arms a new performance-stats capture. Idempotent: if a capture is already running this returns\nthe current status unchanged. While armed, the streaming loops emit aggregated samples (~ every\n1–2 s) into the in-progress capture, readable live via `GET /stats/capture/live`.",
+        "operationId": "statsCaptureStart",
+        "responses": {
+          "200": {
+            "description": "Capture armed (or already running)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/StatsStatus"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/stats/capture/status": {
+      "get": {
+        "tags": [
+          "stats"
+        ],
+        "summary": "Stats capture status",
+        "description": "Whether a capture is armed, its sample count, and start time. Poll this (e.g. every 2 s) to\ndrive the capture-control UI.",
+        "operationId": "statsCaptureStatus",
+        "responses": {
+          "200": {
+            "description": "In-progress capture status (idle when not armed)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/StatsStatus"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/stats/capture/stop": {
+      "post": {
+        "tags": [
+          "stats"
+        ],
+        "summary": "Stop the stats capture",
+        "description": "Disarms the in-progress capture and writes it to disk atomically, returning its summary. If\nnothing was recording, returns `204 No Content`.",
+        "operationId": "statsCaptureStop",
+        "responses": {
+          "200": {
+            "description": "Capture stopped and saved",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CaptureMeta"
+                }
+              }
+            }
+          },
+          "204": {
+            "description": "Nothing was recording"
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Could not write the recording to disk",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/stats/recordings": {
+      "get": {
+        "tags": [
+          "stats"
+        ],
+        "summary": "List saved recordings",
+        "description": "Every saved capture's summary (the `meta` head only — not the sample body), newest first.",
+        "operationId": "statsRecordingsList",
+        "responses": {
+          "200": {
+            "description": "Saved capture summaries, newest first",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/CaptureMeta"
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/stats/recordings/{id}": {
+      "get": {
+        "tags": [
+          "stats"
+        ],
+        "summary": "Get a saved recording",
+        "description": "The full capture (meta + samples) for `id`, for graphing or download.",
+        "operationId": "statsRecordingGet",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "The recording id (its filename stem)",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The full capture",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Capture"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No recording with that id",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "The recording file is unreadable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "stats"
+        ],
+        "summary": "Delete a saved recording",
+        "description": "Removes the recording `id` from disk. `404` if there is no such recording.",
+        "operationId": "statsRecordingDelete",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "The recording id (its filename stem)",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Recording deleted"
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No recording with that id",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Could not delete the recording",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/v1/status": {
       "get": {
         "tags": [
@@ -1125,6 +1428,89 @@
           }
         }
       },
+      "Capture": {
+        "type": "object",
+        "description": "A full capture: summary + the sample time-series. The wire + on-disk shape.",
+        "required": [
+          "meta",
+          "samples"
+        ],
+        "properties": {
+          "meta": {
+            "$ref": "#/components/schemas/CaptureMeta"
+          },
+          "samples": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/StatsSample"
+            }
+          }
+        }
+      },
+      "CaptureMeta": {
+        "type": "object",
+        "description": "Capture summary — the filename stem plus the negotiated mode/codec/client. Stored at the head\nof each on-disk recording and listed standalone (without the sample body) by\n[`StatsRecorder::list`].",
+        "required": [
+          "id",
+          "started_unix_ms",
+          "duration_ms",
+          "kind",
+          "width",
+          "height",
+          "fps",
+          "codec",
+          "client",
+          "sample_count"
+        ],
+        "properties": {
+          "client": {
+            "type": "string",
+            "description": "Short label / fingerprint prefix, or `\"\"` if unknown."
+          },
+          "codec": {
+            "type": "string",
+            "description": "`\"h264\" | \"hevc\" | \"av1\"`."
+          },
+          "duration_ms": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0
+          },
+          "fps": {
+            "type": "integer",
+            "format": "int32",
+            "minimum": 0
+          },
+          "height": {
+            "type": "integer",
+            "format": "int32",
+            "minimum": 0
+          },
+          "id": {
+            "type": "string",
+            "description": "e.g. `\"2026-06-26T20-14-03Z_5120x1440\"` — also the filename stem."
+          },
+          "kind": {
+            "type": "string",
+            "description": "`\"native\" | \"gamestream\"`."
+          },
+          "sample_count": {
+            "type": "integer",
+            "format": "int32",
+            "minimum": 0
+          },
+          "started_unix_ms": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0
+          },
+          "width": {
+            "type": "integer",
+            "format": "int32",
+            "minimum": 0
+          }
+        }
+      },
       "CustomEntry": {
         "type": "object",
         "description": "A user-added title, persisted in `~/.config/punktfunk/library.json`. Same shape the API\nreturns and the web console edits.",
@@ -1595,6 +1981,144 @@
           }
         }
       },
+      "StageTiming": {
+        "type": "object",
+        "description": "One pipeline stage's latency in an aggregation window (microseconds).",
+        "required": [
+          "name",
+          "p50_us",
+          "p99_us"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "`\"capture\" | \"submit\" | \"encode\" | \"packetize\" | \"send\"` (path-dependent)."
+          },
+          "p50_us": {
+            "type": "number",
+            "format": "float"
+          },
+          "p99_us": {
+            "type": "number",
+            "format": "float"
+          }
+        }
+      },
+      "StatsSample": {
+        "type": "object",
+        "description": "One aggregated sample (~ every 2 s native, ~ every 1 s GameStream).",
+        "required": [
+          "t_ms",
+          "session_id",
+          "stages",
+          "fps",
+          "repeat_fps",
+          "mbps",
+          "bitrate_kbps",
+          "frames_dropped",
+          "packets_dropped",
+          "send_dropped",
+          "fec_recovered"
+        ],
+        "properties": {
+          "bitrate_kbps": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Configured target bitrate.",
+            "minimum": 0
+          },
+          "fec_recovered": {
+            "type": "integer",
+            "format": "int32",
+            "description": "FEC shards recovered this window (delta).",
+            "minimum": 0
+          },
+          "fps": {
+            "type": "number",
+            "format": "float",
+            "description": "Genuine NEW frames/s from the source."
+          },
+          "frames_dropped": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Frames dropped this window (delta).",
+            "minimum": 0
+          },
+          "mbps": {
+            "type": "number",
+            "format": "float",
+            "description": "Transmit goodput (Mb/s)."
+          },
+          "packets_dropped": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Packets dropped this window (receiver-side / reassembler, where known).",
+            "minimum": 0
+          },
+          "repeat_fps": {
+            "type": "number",
+            "format": "float",
+            "description": "Re-encoded holds/s (source-starvation indicator)."
+          },
+          "send_dropped": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Host send-buffer overflow / EAGAIN this window (delta).",
+            "minimum": 0
+          },
+          "session_id": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Disambiguates concurrent sessions (usually constant).",
+            "minimum": 0
+          },
+          "stages": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/StageTiming"
+            },
+            "description": "Ordered pipeline stages for this path."
+          },
+          "t_ms": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Milliseconds since capture start (monotonic; stamped by [`StatsRecorder::push_sample`]).",
+            "minimum": 0
+          }
+        }
+      },
+      "StatsStatus": {
+        "type": "object",
+        "description": "Snapshot of the in-progress capture for the management API.",
+        "required": [
+          "armed",
+          "sample_count",
+          "started_unix_ms",
+          "kind"
+        ],
+        "properties": {
+          "armed": {
+            "type": "boolean",
+            "description": "Capture currently running."
+          },
+          "kind": {
+            "type": "string",
+            "description": "Path of the in-progress capture (`\"\"` if idle)."
+          },
+          "sample_count": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Samples in the in-progress capture.",
+            "minimum": 0
+          },
+          "started_unix_ms": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Unix start time of the in-progress capture (`0` if idle).",
+            "minimum": 0
+          }
+        }
+      },
       "StreamInfo": {
         "type": "object",
         "description": "RTSP-negotiated stream parameters.",
@@ -1696,6 +2220,10 @@
     {
       "name": "library",
       "description": "Game library: installed-store titles (Steam) plus user-curated custom entries"
+    },
+    {
+      "name": "stats",
+      "description": "Streaming performance-stats capture: arm/stop a recording, read the live + saved time-series for graphing"
     }
   ]
 }

assets/punktfunk-logo.svg

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg width="100%" height="100%" viewBox="0 0 579 298" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
+  <style>
+    /* Theme-adaptive so the logo stays readable on both light and dark README
+       backgrounds: deep violet (the brand-mark palette) on light, the original
+       light violet on dark. Evaluated by the viewer's color scheme. */
+    .pf-wm   { fill: #6c5bf3; }
+    .pf-back { fill: #a79ff8; }
+    .pf-deep { fill: #6c5bf3; }
+    @media (prefers-color-scheme: dark) {
+      .pf-wm   { fill: #cec9fb; }
+      .pf-back { fill: #f2f1fe; }
+      .pf-deep { fill: #8c7ef5; }
+    }
+  </style>
+  <g>
+    <g>
+      <path class="pf-wm" style="fill-rule:nonzero;" d="M21.144,176.635l0,102.687l31.253,0l0,-35.563l73.436,0l0,-23.555l-73.436,0l0,-19.398l77.285,0l0,-24.171l-108.537,0Z"/>
+      <path class="pf-wm" style="fill-rule:nonzero;" d="M136.148,176.635l0,47.264c0.154,16.627 0.154,16.627 0.308,20.014c0.77,15.087 2.463,21.4 7.544,26.634c7.698,8.16 20.014,10.315 59.272,10.315c23.863,0 34.178,-0.616 43.415,-2.463c11.7,-2.463 19.552,-10.623 21.246,-22.323c0.924,-7.236 1.078,-8.929 1.54,-32.176l0,-47.264l-31.253,0l0,47.264c0,2.155 -0.154,7.082 -0.308,10.623c-0.462,9.699 -1.232,12.47 -3.695,15.087c-3.387,3.695 -9.853,4.619 -31.407,4.619c-26.634,0 -32.638,-1.693 -34.332,-9.853c-0.77,-4.157 -0.77,-4.311 -1.078,-20.476l0,-47.264l-31.253,0Z"/>
+      <path class="pf-wm" style="fill-rule:nonzero;" d="M275.938,176.527l0,102.687l31.868,0l-0.77,-76.669l3.387,0l54.038,76.669l54.346,0l0,-102.687l-31.868,0l0.77,76.515l-3.233,0l-53.73,-76.515l-54.808,0Z"/>
+      <path class="pf-wm" style="fill-rule:nonzero;" d="M425.273,176.527l0,102.687l31.253,0l0,-39.258l17.089,0l46.032,39.258l47.418,0l-64.353,-52.344l59.426,-50.959l-47.88,0l-40.644,37.873l-17.089,0l0,-37.257l-31.253,0Z"/>
+    </g>
+    <path class="pf-back" style="fill-rule:nonzero;" d="M65.442,150.143c24.514,0 44.298,-19.784 44.298,-44.298c0,-24.514 -19.784,-44.298 -44.298,-44.298c-24.514,0 -44.298,19.784 -44.298,44.298c0,24.514 19.784,44.298 44.298,44.298Z"/>
+    <path class="pf-deep" style="fill-rule:nonzero;" d="M141.063,92.871c17.334,-17.334 17.334,-45.312 0,-62.647c-17.334,-17.334 -45.312,-17.334 -62.647,-0c-17.334,17.334 -17.334,45.312 0,62.647c17.334,17.334 45.312,17.334 62.647,-0Z"/>
+    <path style="fill:url(#_Linear1);" d="M121.228,104.359c-14.777,3.965 -31.187,0.136 -42.811,-11.488c-11.624,-11.624 -15.453,-28.034 -11.488,-42.811c14.777,-3.965 31.187,-0.136 42.811,11.488c11.624,11.624 15.453,28.034 11.488,42.811Z"/>
+  </g>
+  <defs>
+    <linearGradient id="_Linear1" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(31.323323,-31.323323,31.323323,31.323323,78.416832,92.870811)">
+      <stop offset="0" style="stop-color:#cec9fb;stop-opacity:0"/>
+      <stop offset="1" style="stop-color:#fcfcff;stop-opacity:1"/>
+    </linearGradient>
+  </defs>
+</svg>

clients/android/README.md

@@ -11,8 +11,8 @@ machine, trust logic) instead of re-porting it into Kotlin.
 
 | Side | Owns |
 |------|------|
-| **Rust** (`clients/android/native` → `libpunktfunk_android.so`) | the JNI seam, `NativeClient` (QUIC control + UDP data plane), AnnexB→`AMediaCodec` decode, Opus+Oboe audio, VK keymap, latency math, trust/pairing |
-| **Kotlin** (`clients/android`) | Compose UI (host grid / settings / stream), `SurfaceView` lifecycle, input capture, `NsdManager` discovery, Keystore identity, permissions |
+| **Rust** (`clients/android/native` → `libpunktfunk_android.so`) | the JNI seam, `NativeClient` (QUIC control + UDP data plane), AnnexB→`AMediaCodec` decode, Opus+Oboe audio, VK keymap, latency math, trust/pairing, **mDNS discovery** (`mdns-sd`, the same browse the Linux/Windows clients use) |
+| **Kotlin** (`clients/android`) | Compose UI (host grid / settings / stream), `SurfaceView` lifecycle, input capture, the Wi-Fi `MulticastLock` + permission UX, Keystore identity, permissions |
 
 The single seam is `io.unom.punktfunk.kit.NativeBridge` ⇄ `Java_io_unom_punktfunk_kit_NativeBridge_*`.
 
@@ -30,7 +30,7 @@ clients/android/native/          Rust cdylib (workspace member) — links punktf
 clients/android/                   Gradle project (this dir)
   settings.gradle.kts · build.gradle.kts · gradle.properties · gradlew
   app/                             :app — Compose UI: Connect / Settings / Stream screens (phone + TV)
-  kit/                             :kit — NativeBridge · discovery (NsdManager) · Gamepad · Keymap ·
+  kit/                             :kit — NativeBridge · discovery (native mdns-sd, polled) · Gamepad · Keymap ·
                                          security (Keystore identity + known-host store) · cargo-ndk build
 ```
 
@@ -74,7 +74,8 @@ streaming experience:
 - **Audio** — Opus + Oboe playback with a jitter ring, plus mic uplink to the host.
 - **Input** — game controllers (buttons + axes) with rumble and HID feedback; D-pad /
   game-controller focus navigation for the couch (TV + phone).
-- **Discovery & trust** — `NsdManager` mDNS host list, SPAKE2 PIN pairing and TOFU, with a
+- **Discovery & trust** — native `mdns-sd` mDNS host list (polled over JNI; the same browse the
+  Linux/Windows clients use, not `NsdManager`), SPAKE2 PIN pairing and TOFU, with a
   Keystore-wrapped client identity and a known-host store.
 - **UI** — Compose host list / settings / stream screens, Material You theming.
 - **Shipping** — built for `arm64-v8a` + `x86_64`; published to Google Play (Internal Testing).

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

@@ -4,11 +4,13 @@
     <!-- punktfunk/1 QUIC/UDP data plane. -->
     <uses-permission android:name="android.permission.INTERNET" />
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
-    <!-- mDNS discovery of _punktfunk._udp on the LAN (NsdManager). -->
+    <!-- mDNS discovery of _punktfunk._udp on the LAN (native mdns-sd browse). Requested
+         opportunistically — raw multicast reception needs only the MulticastLock, not this. -->
     <uses-permission
         android:name="android.permission.NEARBY_WIFI_DEVICES"
         android:usesPermissionFlags="neverForLocation" />
-    <!-- Hold a MulticastLock while NsdManager discovery runs (OEM Wi-Fi power-save hedge). -->
+    <!-- HostDiscovery holds a MulticastLock while the native mDNS browse runs — raw multicast
+         reception needs it (also an OEM Wi-Fi power-save hedge). -->
     <uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
     <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
     <!-- Enforced from Android 17 (SDK 37) for ALL local-network traffic incl. the QUIC socket.

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

@@ -84,30 +84,33 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
     val scope = rememberCoroutineScope()
     val context = LocalContext.current
     var host by remember { mutableStateOf("") }
+    var hostName by remember { mutableStateOf("") }
     var port by remember { mutableStateOf("9777") }
     var connecting by remember { mutableStateOf(false) }
     var status by remember { mutableStateOf<String?>(null) }
     // The host streams at exactly this mode; "Native" settings resolve from the device display.
     val (w, h, hz) = settings.effectiveMode(context)
 
-    // mDNS discovery scoped to this screen; NsdManager callbacks arrive on the main thread, so the
-    // onChange callback can set Compose state directly. (Emulator SLIRP drops multicast → empty.)
-    // NsdManager discovery needs NEARBY_WIFI_DEVICES on Android 13+ (a runtime permission) — without
-    // it discoverServices silently finds nothing. Request it once, then (re)start discovery on grant.
+    // mDNS discovery scoped to this screen, via the native mdns-sd browse (HostDiscovery) — its
+    // onChange fires on the main thread, so it can set Compose state directly. (Emulator SLIRP drops
+    // multicast → empty; that's the network, not the API.) Raw multicast reception only needs the
+    // Wi-Fi MulticastLock (HostDiscovery holds it), NOT NEARBY_WIFI_DEVICES — that gated the old
+    // NsdManager path. We still request NEARBY_WIFI_DEVICES opportunistically (some OEMs filter
+    // multicast without it; harmless where it isn't), but never block discovery on the grant — a
+    // denial used to leave discovery dead forever.
     val discovery = remember { HostDiscovery(context) }
     var discovered by remember { mutableStateOf<List<DiscoveredHost>>(emptyList()) }
-    var nearbyGranted by remember { mutableStateOf(hasNearbyPermission(context)) }
     val nearbyLauncher = rememberLauncherForActivityResult(
         ActivityResultContracts.RequestPermission(),
-    ) { granted -> nearbyGranted = granted }
+    ) { _ -> /* best-effort hint; discovery runs regardless of the result */ }
     LaunchedEffect(Unit) {
-        if (!nearbyGranted && Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU && !hasNearbyPermission(context)) {
             nearbyLauncher.launch(Manifest.permission.NEARBY_WIFI_DEVICES)
         }
     }
-    DisposableEffect(nearbyGranted) {
+    DisposableEffect(Unit) {
         discovery.onChange = { discovered = it }
-        if (nearbyGranted) discovery.start()
+        discovery.start()
         onDispose {
             discovery.onChange = null
             discovery.stop()
@@ -127,6 +130,13 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
     }
     // A trust decision awaiting the user (first-connect TOFU / fp changed / PIN pairing).
     var pendingTrust by remember { mutableStateOf<PendingTrust?>(null) }
+    // A saved host whose label is being edited (the Rename dialog).
+    var renameTarget by remember { mutableStateOf<KnownHost?>(null) }
+
+    // Discovered hosts not already saved — a saved host (paired or TOFU) belongs in "Saved hosts",
+    // not also in "Discovered", so we hide the overlap (matched by fingerprint when both carry it, so
+    // it survives a DHCP address change; else by address:port). Mirrors the Apple client.
+    val discoveredUnsaved = discovered.filter { dh -> savedHosts.none { it.matches(dh) } }
 
     // Issue the actual connect with identity + (optional) pin. On a TOFU connect (pinHex null),
     // pin the fingerprint the host presented (as an unpaired known host) so the next connect goes
@@ -176,10 +186,17 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
     // keyed by address:port, so a discovered and a manually-typed connection to the same host share
     // one record. Trust-on-first-use is permitted ONLY when the host advertised pair=optional; a
     // pair=required host, or a manual/unknown-policy host, must pair by PIN.
-    fun connect(targetHost: String, targetPort: Int, dh: DiscoveredHost? = null) {
+    fun connect(
+        targetHost: String,
+        targetPort: Int,
+        dh: DiscoveredHost? = null,
+        manualName: String? = null,
+    ) {
         val known = knownHostStore.get(targetHost, targetPort)
         val adv = dh?.fingerprint?.lowercase()
-        val name = dh?.name ?: targetHost
+        // Label precedence: a saved host keeps its (possibly user-renamed) name; else the discovered
+        // mDNS name; else the name typed in the Add-host sheet; else the bare address.
+        val name = known?.name ?: dh?.name ?: manualName?.trim()?.takeIf { it.isNotEmpty() } ?: targetHost
         when {
             // Known host whose advertised fp still matches the pin → silent pinned reconnect.
             known != null && (adv == null || adv == known.fpHex) ->
@@ -260,7 +277,7 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
                 }
             }
 
-            if (savedHosts.isEmpty() && discovered.isEmpty()) {
+            if (savedHosts.isEmpty() && discoveredUnsaved.isEmpty()) {
                 item(span = { GridItemSpan(maxLineSpan) }) {
                     EmptyHostsState()
                 }
@@ -281,16 +298,17 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
                             knownHostStore.remove(kh.address, kh.port)
                             savedHosts = knownHostStore.all()
                         },
+                        onRename = { renameTarget = kh },
                     )
                 }
             }
 
-            if (discovered.isNotEmpty()) {
+            if (discoveredUnsaved.isNotEmpty()) {
                 item(span = { GridItemSpan(maxLineSpan) }) {
                     Spacer(Modifier.height(12.dp))
                     SectionLabel("Discovered on the network")
                 }
-                items(discovered, key = { "disc-${it.host}-${it.port}" }) { dh ->
+                items(discoveredUnsaved, key = { "disc-${it.host}-${it.port}" }) { dh ->
                     HostCard(
                         name = dh.name,
                         address = "${dh.host}:${dh.port}",
@@ -302,9 +320,10 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
                 }
             }
 
-            // Active-discovery hint: when we're scanning but nothing's turned up yet, show it's
-            // working rather than looking idle/empty.
-            if (nearbyGranted && discovered.isEmpty()) {
+            // Active-discovery hint: discovery runs whenever this screen is up, so while it's
+            // scanning but nothing's turned up yet (and we're not mid-connect), show it's working
+            // rather than looking idle/empty.
+            if (!connecting && discovered.isEmpty()) {
                 item(span = { GridItemSpan(maxLineSpan) }) {
                     Row(
                         modifier = Modifier.fillMaxWidth().padding(vertical = 12.dp),
@@ -363,6 +382,15 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
                     color = MaterialTheme.colorScheme.onSurfaceVariant,
                 )
                 Spacer(Modifier.height(20.dp))
+                OutlinedTextField(
+                    value = hostName,
+                    onValueChange = { hostName = it },
+                    label = { Text("Name (optional)") },
+                    placeholder = { Text("e.g. Living Room") },
+                    singleLine = true,
+                    modifier = Modifier.fillMaxWidth(),
+                )
+                Spacer(Modifier.height(16.dp))
                 OutlinedTextField(
                     value = host,
                     onValueChange = { host = it },
@@ -370,7 +398,7 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
                     singleLine = true,
                     modifier = Modifier.fillMaxWidth(),
                 )
-                Spacer(Modifier.height(8.dp))
+                Spacer(Modifier.height(16.dp))
                 OutlinedTextField(
                     value = port,
                     onValueChange = { v -> port = v.filter { it.isDigit() }.take(5) },
@@ -385,9 +413,10 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
                     onClick = {
                         val h = host.trim()
                         val p = port.toIntOrNull() ?: 9777
+                        val n = hostName
                         scope.launch { sheetState.hide() }.invokeOnCompletion {
                             showManualSheet = false
-                            connect(h, p)
+                            connect(h, p, manualName = n)
                         }
                     },
                     modifier = Modifier.fillMaxWidth(),
@@ -507,10 +536,57 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
             }
         }
     }
+
+    // Rename a saved host's label (discovered hosts are named by mDNS; this is how you give one a
+    // friendly name like "Living Room" after pairing). Keyed by the host so reopening resets the field.
+    renameTarget?.let { kh ->
+        var newName by remember(kh) { mutableStateOf(kh.name) }
+        AlertDialog(
+            onDismissRequest = { renameTarget = null },
+            title = { Text("Rename host") },
+            text = {
+                OutlinedTextField(
+                    value = newName,
+                    onValueChange = { newName = it },
+                    label = { Text("Name") },
+                    placeholder = { Text(kh.address) },
+                    singleLine = true,
+                )
+            },
+            confirmButton = {
+                TextButton(
+                    enabled = newName.isNotBlank(),
+                    onClick = {
+                        knownHostStore.rename(kh.address, kh.port, newName.trim())
+                        savedHosts = knownHostStore.all()
+                        renameTarget = null
+                    },
+                ) { Text("Save") }
+            },
+            dismissButton = {
+                TextButton(onClick = { renameTarget = null }) { Text("Cancel") }
+            },
+        )
+    }
 }
 
-/** NsdManager discovery needs NEARBY_WIFI_DEVICES on API 33+; below that it doesn't apply. */
+/**
+ * Whether NEARBY_WIFI_DEVICES is held (API 33+; not applicable below). We request it opportunistically
+ * as a multicast-reception hedge on OEMs that filter multicast without it, but discovery (raw mDNS via
+ * the native core + MulticastLock) does not depend on it.
+ */
 fun hasNearbyPermission(context: Context): Boolean =
     Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU ||
         ContextCompat.checkSelfPermission(context, Manifest.permission.NEARBY_WIFI_DEVICES) ==
         PackageManager.PERMISSION_GRANTED
+
+/**
+ * True when a saved host and a discovered advert are the same machine — matched by certificate
+ * fingerprint when both carry it (so it survives a DHCP address change), else by address:port.
+ * Mirrors the Apple client's `StoredHost.matches`; de-dupes "Discovered" against "Saved hosts".
+ */
+private fun KnownHost.matches(dh: DiscoveredHost): Boolean {
+    val advFp = dh.fingerprint?.lowercase()
+    if (!advFp.isNullOrEmpty() && fpHex.isNotEmpty() && fpHex.lowercase() == advFp) return true
+    return address == dh.host && port == dh.port
+}

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

@@ -5,9 +5,7 @@ import android.content.pm.PackageManager
 import androidx.activity.compose.BackHandler
 import androidx.activity.compose.rememberLauncherForActivityResult
 import androidx.activity.result.contract.ActivityResultContracts
-import androidx.compose.foundation.BorderStroke
 import androidx.compose.foundation.layout.Arrangement
-import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.ColumnScope
 import androidx.compose.foundation.layout.Row
@@ -16,14 +14,14 @@ import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.rememberScrollState
 import androidx.compose.foundation.verticalScroll
-import androidx.compose.material.icons.Icons
-import androidx.compose.material.icons.filled.ArrowDropDown
-import androidx.compose.material3.DropdownMenu
 import androidx.compose.material3.DropdownMenuItem
-import androidx.compose.material3.Icon
+import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.ExposedDropdownMenuBox
+import androidx.compose.material3.ExposedDropdownMenuAnchorType
+import androidx.compose.material3.ExposedDropdownMenuDefaults
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.OutlinedCard
-import androidx.compose.material3.Surface
+import androidx.compose.material3.OutlinedTextField
 import androidx.compose.material3.Switch
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
@@ -33,7 +31,6 @@ import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
-import androidx.compose.ui.focus.onFocusChanged
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.unit.dp
 import androidx.core.content.ContextCompat
@@ -174,12 +171,8 @@ private fun ToggleRow(
     }
 }
 
-/**
- * A labelled value that opens a menu on click. Uses a clickable [Surface] + [DropdownMenu] rather
- * than `ExposedDropdownMenuBox` — that component's read-only text field traps D-pad / controller
- * focus (directional keys never leave it), so you can't navigate past it on a TV. Calls [onSelect]
- * on a pick. A primary-colour border marks D-pad focus.
- */
+/** A labelled read-only dropdown over [options] (value → label); calls [onSelect] on a pick. */
+@OptIn(ExperimentalMaterial3Api::class)
 @Composable
 private fun <T> SettingDropdown(
     label: String,
@@ -188,35 +181,20 @@ private fun <T> SettingDropdown(
     onSelect: (T) -> Unit,
 ) {
     var expanded by remember { mutableStateOf(false) }
-    var focused by remember { mutableStateOf(false) }
     val selectedLabel = options.firstOrNull { it.first == selected }?.second
         ?: options.firstOrNull()?.second.orEmpty()
-    Box(modifier = Modifier.fillMaxWidth()) {
-        Surface(
-            onClick = { expanded = true },
-            shape = MaterialTheme.shapes.small,
-            color = MaterialTheme.colorScheme.surfaceVariant,
-            border = if (focused) BorderStroke(2.dp, MaterialTheme.colorScheme.primary) else null,
+    ExposedDropdownMenuBox(expanded = expanded, onExpandedChange = { expanded = it }) {
+        OutlinedTextField(
+            value = selectedLabel,
+            onValueChange = {},
+            readOnly = true,
+            label = { Text(label) },
+            trailingIcon = { ExposedDropdownMenuDefaults.TrailingIcon(expanded = expanded) },
             modifier = Modifier
-                .fillMaxWidth()
-                .onFocusChanged { focused = it.isFocused },
-        ) {
-            Row(
-                modifier = Modifier.padding(horizontal = 16.dp, vertical = 12.dp),
-                verticalAlignment = Alignment.CenterVertically,
-            ) {
-                Column(Modifier.weight(1f)) {
-                    Text(
-                        label,
-                        style = MaterialTheme.typography.labelMedium,
-                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                .menuAnchor(ExposedDropdownMenuAnchorType.PrimaryNotEditable)
+                .fillMaxWidth(),
         )
-                    Text(selectedLabel, style = MaterialTheme.typography.bodyLarge)
-                }
-                Icon(Icons.Filled.ArrowDropDown, contentDescription = null)
-            }
-        }
-        DropdownMenu(expanded = expanded, onDismissRequest = { expanded = false }) {
+        ExposedDropdownMenu(expanded = expanded, onDismissRequest = { expanded = false }) {
             options.forEach { (value, lbl) ->
                 DropdownMenuItem(
                     text = { Text(lbl) },

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

@@ -26,7 +26,6 @@ import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.input.pointer.pointerInput
-import androidx.compose.ui.input.pointer.positionChange
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.text.font.FontFamily
 import androidx.compose.ui.unit.dp
@@ -44,6 +43,13 @@ import kotlinx.coroutines.delay
 import kotlin.math.abs
 import kotlin.math.roundToInt
 
+// Touch-gesture tuning (px / ms). TAP_SLOP: movement under this still counts as a tap, not a drag.
+// TAP_DRAG_MS: a new touch within this long after a tap starts a left-button drag. SCROLL_DIV: px of
+// two-finger pan per wheel notch (smaller = faster scroll).
+private const val TAP_SLOP = 12f
+private const val TAP_DRAG_MS = 250L
+private const val SCROLL_DIV = 4f
+
 @Composable
 fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
     val context = LocalContext.current
@@ -139,41 +145,108 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
         if (showStats) {
             stats?.let { StatsOverlay(it, Modifier.align(Alignment.TopStart).padding(12.dp)) }
         }
-        // Touch virtual-trackpad overlay: 1-finger drag → relative mouse move; tap → left click;
-        // 2-finger drag → scroll; 3-finger tap → toggle the stats HUD. (Physical-mouse pointer
-        // capture comes in a later increment.)
+        // Touch → mouse, absolute "direct pointing" like the Apple client: the host cursor follows
+        // your finger (MouseMoveAbs, host-normalized against the overlay size — which fills the video,
+        // so finger position maps straight onto the remote screen). Gestures: tap = left click;
+        // two-finger tap = right click; two-finger drag = scroll; tap-then-press-and-drag = left-drag
+        // (text selection / moving windows); three-finger tap = toggle the stats HUD.
         Box(
             Modifier.fillMaxSize().pointerInput(handle) {
+                var lastTapUp = 0L
+                var lastTapX = 0f
+                var lastTapY = 0f
+                fun moveAbs(x: Float, y: Float) {
+                    val sw = size.width
+                    val sh = size.height
+                    if (sw <= 0 || sh <= 0) return
+                    NativeBridge.nativeSendPointerAbs(
+                        handle,
+                        x.coerceIn(0f, (sw - 1).toFloat()).roundToInt(),
+                        y.coerceIn(0f, (sh - 1).toFloat()).roundToInt(),
+                        sw,
+                        sh,
+                    )
+                }
                 awaitEachGesture {
-                    val first = awaitFirstDown(requireUnconsumed = false)
+                    val down = awaitFirstDown(requireUnconsumed = false)
+                    val startX = down.position.x
+                    val startY = down.position.y
+                    // A touch landing just after a quick tap nearby = tap-and-drag: hold the left
+                    // button for this whole gesture (laptop-trackpad convention).
+                    val isDrag = down.uptimeMillis - lastTapUp < TAP_DRAG_MS &&
+                        abs(startX - lastTapX) < TAP_SLOP && abs(startY - lastTapY) < TAP_SLOP
+                    lastTapUp = 0L // consume the arming either way
+                    moveAbs(startX, startY) // cursor jumps to the finger immediately
+                    if (isDrag) NativeBridge.nativeSendPointerButton(handle, 1, true)
+
                     var moved = false
                     var maxFingers = 1
+                    var scrolling = false
+                    var prevCx = startX
+                    var prevCy = startY
+                    var upTime = down.uptimeMillis
+
                     while (true) {
                         val ev = awaitPointerEvent()
-                        val fingers = ev.changes.count { it.pressed }
-                        if (fingers == 0) break
-                        if (fingers > maxFingers) maxFingers = fingers
-                        val primary = ev.changes.firstOrNull { it.id == first.id } ?: ev.changes.first()
-                        val d = primary.positionChange()
-                        if (abs(d.x) > 0.5f || abs(d.y) > 0.5f) {
-                            moved = true
-                            if (fingers >= 2) {
-                                // screen +y down → wire +up, so negate y. Coarse divisor; tune live.
-                                val sy = (-d.y / 4f).toInt()
-                                val sx = (d.x / 4f).toInt()
-                                if (sy != 0) NativeBridge.nativeSendScroll(handle, 0, sy * 120)
-                                if (sx != 0) NativeBridge.nativeSendScroll(handle, 1, sx * 120)
-                            } else {
-                                NativeBridge.nativeSendPointerMove(handle, d.x.toInt(), d.y.toInt())
+                        val pressed = ev.changes.filter { it.pressed }
+                        if (pressed.isEmpty()) {
+                            upTime = ev.changes.firstOrNull()?.uptimeMillis ?: upTime
+                            break
                         }
+                        if (pressed.size > maxFingers) maxFingers = pressed.size
+
+                        if (pressed.size >= 2) {
+                            // Two fingers → scroll by the centroid delta; never move the cursor.
+                            val cx = (pressed.sumOf { it.position.x.toDouble() } / pressed.size).toFloat()
+                            val cy = (pressed.sumOf { it.position.y.toDouble() } / pressed.size).toFloat()
+                            if (!scrolling) {
+                                scrolling = true
+                                prevCx = cx
+                                prevCy = cy
+                            }
+                            val sy = ((prevCy - cy) / SCROLL_DIV).toInt() // finger up → wheel up
+                            val sx = ((cx - prevCx) / SCROLL_DIV).toInt()
+                            if (sy != 0) {
+                                NativeBridge.nativeSendScroll(handle, 0, sy * 120)
+                                prevCy = cy
+                                moved = true
+                            }
+                            if (sx != 0) {
+                                NativeBridge.nativeSendScroll(handle, 1, sx * 120)
+                                prevCx = cx
+                                moved = true
+                            }
+                        } else if (!scrolling) {
+                            // One finger → the cursor follows it (skipped once a gesture turned into
+                            // a scroll, so dropping back to one finger doesn't jerk the cursor).
+                            val p = pressed.firstOrNull { it.id == down.id } ?: pressed.first()
+                            if (abs(p.position.x - startX) > TAP_SLOP ||
+                                abs(p.position.y - startY) > TAP_SLOP
+                            ) {
+                                moved = true
+                            }
+                            moveAbs(p.position.x, p.position.y)
                         }
                         ev.changes.forEach { it.consume() }
                     }
-                    if (!moved && maxFingers == 1) {
+
+                    if (isDrag) {
+                        NativeBridge.nativeSendPointerButton(handle, 1, false) // end the drag
+                    } else if (!moved) {
+                        when {
+                            maxFingers >= 3 -> showStats = !showStats // in-stream HUD toggle
+                            maxFingers == 2 -> { // two-finger tap → right click
+                                NativeBridge.nativeSendPointerButton(handle, 3, true)
+                                NativeBridge.nativeSendPointerButton(handle, 3, false)
+                            }
+                            else -> { // tap → left click, and arm tap-and-drag
                                 NativeBridge.nativeSendPointerButton(handle, 1, true)
                                 NativeBridge.nativeSendPointerButton(handle, 1, false)
-                    } else if (!moved && maxFingers >= 3) {
-                        showStats = !showStats // quick in-stream HUD toggle
+                                lastTapUp = upTime
+                                lastTapX = startX
+                                lastTapY = startY
+                            }
+                        }
                     }
                 }
             },

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

@@ -49,7 +49,7 @@ fun SectionLabel(text: String) {
 
 /**
  * A host as an Apple-style card: a colored letter-avatar, name + address, a trust pill, and (for
- * saved hosts) an overflow menu with Forget. Tapping the card connects.
+ * saved hosts) an overflow menu with Rename / Forget. Tapping the card connects.
  */
 @Composable
 fun HostCard(
@@ -59,6 +59,7 @@ fun HostCard(
     enabled: Boolean,
     onConnect: () -> Unit,
     onForget: (() -> Unit)?,
+    onRename: (() -> Unit)? = null,
 ) {
     // D-pad / controller focus highlight: a clickable card is focusable, but the default state
     // layer is too subtle on a TV across a room — draw a clear primary-colour border when focused.
@@ -106,7 +107,7 @@ fun HostCard(
                 StatusPill(status)
             }
 
-            if (onForget != null) {
+            if (onForget != null || onRename != null) {
                 var menu by remember { mutableStateOf(false) }
                 Box(modifier = Modifier.align(Alignment.TopEnd)) {
                     IconButton(enabled = enabled, onClick = { menu = true }) {
@@ -118,6 +119,16 @@ fun HostCard(
                         )
                     }
                     DropdownMenu(expanded = menu, onDismissRequest = { menu = false }) {
+                        if (onRename != null) {
+                            DropdownMenuItem(
+                                text = { Text("Rename") },
+                                onClick = {
+                                    menu = false
+                                    onRename()
+                                },
+                            )
+                        }
+                        if (onForget != null) {
                             DropdownMenuItem(
                                 text = { Text("Forget") },
                                 onClick = {
@@ -131,6 +142,7 @@ fun HostCard(
             }
         }
     }
+}
 
 /** A circular avatar with the host's first letter (Apple-contact style). */
 @Composable

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

@@ -67,6 +67,27 @@ object NativeBridge {
     /** Tear down a session handle returned by [nativeConnect]. No-op on `0`. */
     external fun nativeClose(handle: Long)
 
+    // ---- LAN discovery: mDNS browse of `_punktfunk._udp` in Rust (mdns-sd), polled by Kotlin ----
+    // Replaces NsdManager. The caller holds the Wi-Fi MulticastLock for the browse lifetime; raw
+    // multicast *reception* needs it. See io.unom.punktfunk.kit.discovery.HostDiscovery.
+
+    /**
+     * Start browsing `_punktfunk._udp` on the LAN. Returns an opaque discovery handle, or `0` on
+     * failure. Pair with exactly one [nativeDiscoveryStop]. Cheap + non-blocking (spawns the mDNS
+     * daemon + a fold thread).
+     */
+    external fun nativeDiscoveryStart(): Long
+
+    /**
+     * The current resolved-host snapshot for [handle]: newline-joined records, each
+     * `key␟name␟addr␟port␟fp␟pair` (`␟` = U+001F). Empty string = no hosts / `0` handle. Poll ~1 Hz;
+     * cheap (a lock + string build), safe to call on the main thread.
+     */
+    external fun nativeDiscoveryPoll(handle: Long): String
+
+    /** Stop the browse, shut the mDNS daemon down and join its thread. No-op on `0`. */
+    external fun nativeDiscoveryStop(handle: Long)
+
     /**
      * Start the HEVC decode thread rendering onto [surface] (a SurfaceView's surface). Decode runs
      * entirely in Rust (NDK AMediaCodec → ANativeWindow) — no per-frame JNI. No-op if already started.
@@ -108,6 +129,13 @@ object NativeBridge {
     /** Relative mouse move; dx/dy are device-pixel deltas (screen +y down). */
     external fun nativeSendPointerMove(handle: Long, dx: Int, dy: Int)
 
+    /**
+     * Absolute mouse position — the host moves the cursor to (x, y) in a [surfaceWidth]×[surfaceHeight]
+     * pixel space (it normalizes against that size and maps into the output region). Touch
+     * "direct pointing": the cursor jumps to the finger. Parity with the Apple client's absolute touch.
+     */
+    external fun nativeSendPointerAbs(handle: Long, x: Int, y: Int, surfaceWidth: Int, surfaceHeight: Int)
+
     /** One mouse-button transition. button: 1=left 2=middle 3=right 4=X1 5=X2. */
     external fun nativeSendPointerButton(handle: Long, button: Int, down: Boolean)
 

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

@@ -1,17 +1,13 @@
 package io.unom.punktfunk.kit.discovery
 
 import android.content.Context
-import android.net.nsd.NsdManager
-import android.net.nsd.NsdServiceInfo
 import android.net.wifi.WifiManager
-import android.os.Build
+import android.os.Handler
+import android.os.Looper
 import android.util.Log
+import io.unom.punktfunk.kit.NativeBridge
 
-private const val TAG = "PunktfunkNsd"
-
-/** DNS-SD service type punktfunk hosts advertise (host: `_punktfunk._udp.local.`). */
-const val PUNKTFUNK_SERVICE_TYPE = "_punktfunk._udp"
-const val PUNKTFUNK_PROTO = "punktfunk/1"
+private const val TAG = "PunktfunkMdns"
 
 /** One resolved host fit for the picker. [key] is the stable dedup id. */
 data class DiscoveredHost(
@@ -23,165 +19,115 @@ data class DiscoveredHost(
     val pairingRequired: Boolean = false,
 )
 
-/** Parsed TXT fields. Pure — unit-testable without Android (see ParseTxtTest). */
-data class TxtFields(
-    val proto: String?,
-    val fp: String?,
-    val pair: String?,
-    val id: String?,
-) {
-    val pairingRequired: Boolean get() = pair == "required"
-    val isPunktfunk: Boolean get() = proto == PUNKTFUNK_PROTO
-}
+/** Field separator the native browse uses inside one record (ASCII Unit Separator). */
+private const val FIELD_SEP = '\u001F'
 
 /**
- * Pure TXT parser. NSD hands TXT as a `Map<String, ByteArray?>` (a null/empty value = present-but-
- * empty key). Decode UTF-8; missing keys are null, never an error.
+ * Parse one record from [NativeBridge.nativeDiscoveryPoll] (`key␟name␟addr␟port␟fp␟pair`), or null
+ * if it's malformed. Pure — unit-tested without Android (see ParseRecordTest). The native side
+ * already applied the protocol gate and address selection, so this is just field marshaling.
  */
-fun parseTxt(attrs: Map<String, ByteArray?>): TxtFields {
-    fun s(k: String): String? = attrs[k]?.takeIf { it.isNotEmpty() }?.toString(Charsets.UTF_8)
-    return TxtFields(proto = s("proto"), fp = s("fp"), pair = s("pair"), id = s("id"))
+fun parseHostRecord(record: String): DiscoveredHost? {
+    val f = record.split(FIELD_SEP)
+    if (f.size < 6) return null
+    val addr = f[2]
+    val port = f[3].toIntOrNull() ?: return null
+    if (addr.isBlank() || port !in 1..65535) return null
+    return DiscoveredHost(
+        key = f[0].ifBlank { "$addr:$port" },
+        name = f[1].ifBlank { addr },
+        host = addr,
+        port = port,
+        fingerprint = f[4].ifBlank { null },
+        pairingRequired = f[5] == "required",
+    )
 }
 
 /**
- * Browses `_punktfunk._udp` via NsdManager, resolves each service (the reliable
- * `registerServiceInfoCallback` path on API 34+, legacy `resolveService` on 31–33 where its TXT is
- * often empty), and pushes the live host set to [onChange] (invoked on the main thread).
+ * Browses `_punktfunk._udp` for punktfunk/1 hosts via the native `mdns-sd` core (the same browse the
+ * Linux/Windows clients use), exposed over JNI — *not* `NsdManager`, whose per-OEM system daemon
+ * made discovery "mostly broken". [start] spins up the native browse and polls it ~1 Hz on the main
+ * thread, pushing the live host set to [onChange] (also on the main thread, only when it changes);
+ * [stop] tears it down.
  *
- * Lifecycle: [start] when the picker appears, [stop] when it leaves / on connect — holds a
- * MulticastLock while running (an OEM Wi-Fi power-save hedge). Note: the Android emulator's SLIRP
- * NAT drops multicast, so on the emulator discovery starts but never finds a LAN host.
+ * We hold a Wi-Fi [WifiManager.MulticastLock] for the browse lifetime — raw multicast *reception*
+ * needs it. (The Android emulator's SLIRP NAT drops multicast, so on the emulator discovery starts
+ * but never finds a LAN host — same as before; that's the network, not the API.)
  */
 class HostDiscovery(context: Context) {
     private val appCtx = context.applicationContext
-    private val nsd = appCtx.getSystemService(Context.NSD_SERVICE) as NsdManager
 
     /** Invoked on the main thread whenever the resolved host set changes. */
     var onChange: ((List<DiscoveredHost>) -> Unit)? = null
 
-    private val resolved = LinkedHashMap<String, DiscoveredHost>() // key -> host
+    private val handler = Handler(Looper.getMainLooper())
     private var multicastLock: WifiManager.MulticastLock? = null
-    private var discoveryListener: NsdManager.DiscoveryListener? = null
-    private val infoCallbacks = mutableListOf<NsdManager.ServiceInfoCallback>() // API 34+ registrations
+    private var nativeHandle = 0L
     private var running = false
+    private var last: List<DiscoveredHost> = emptyList()
+
+    private val poll = object : Runnable {
+        override fun run() {
+            if (!running) return
+            val hosts = snapshot()
+            if (hosts != last) {
+                last = hosts
+                onChange?.invoke(hosts)
+            }
+            handler.postDelayed(this, POLL_MS)
+        }
+    }
 
-    @Synchronized
     fun start() {
         if (running) return
-        running = true
         acquireMulticastLock()
-        val listener = makeDiscoveryListener()
-        discoveryListener = listener
-        runCatching {
-            nsd.discoverServices(PUNKTFUNK_SERVICE_TYPE, NsdManager.PROTOCOL_DNS_SD, listener)
-        }.onFailure {
-            Log.e(TAG, "discoverServices failed", it)
-            stop()
+        val h = runCatching { NativeBridge.nativeDiscoveryStart() }
+            .onFailure { Log.e(TAG, "nativeDiscoveryStart threw", it) }
+            .getOrDefault(0L)
+        if (h == 0L) {
+            Log.e(TAG, "native mDNS discovery failed to start")
+            releaseMulticastLock()
+            return
         }
+        nativeHandle = h
+        running = true
+        last = emptyList()
+        handler.post(poll)
     }
 
-    @Synchronized
     fun stop() {
-        if (!running) return
+        if (!running && nativeHandle == 0L) return
         running = false
-        discoveryListener?.let { runCatching { nsd.stopServiceDiscovery(it) } }
-        discoveryListener = null
-        if (Build.VERSION.SDK_INT >= 34) {
-            for (cb in infoCallbacks) runCatching { nsd.unregisterServiceInfoCallback(cb) }
-        }
-        infoCallbacks.clear()
+        handler.removeCallbacks(poll)
+        val h = nativeHandle
+        nativeHandle = 0L
+        if (h != 0L) runCatching { NativeBridge.nativeDiscoveryStop(h) }
+            .onFailure { Log.e(TAG, "nativeDiscoveryStop threw", it) }
         releaseMulticastLock()
-        resolved.clear()
+        last = emptyList()
         onChange?.invoke(emptyList())
     }
 
-    private fun publish() {
-        onChange?.invoke(resolved.values.sortedBy { it.name.lowercase() })
-    }
-
-    private fun makeDiscoveryListener() = object : NsdManager.DiscoveryListener {
-        override fun onDiscoveryStarted(type: String) {
-            Log.d(TAG, "discovery started: $type")
-        }
-        override fun onDiscoveryStopped(type: String) {
-            Log.d(TAG, "discovery stopped: $type")
-        }
-        override fun onStartDiscoveryFailed(type: String, code: Int) {
-            Log.e(TAG, "start discovery failed: $code")
-            runCatching { nsd.stopServiceDiscovery(this) }
-        }
-        override fun onStopDiscoveryFailed(type: String, code: Int) {
-            Log.e(TAG, "stop discovery failed: $code")
-        }
-
-        override fun onServiceFound(info: NsdServiceInfo) {
-            Log.d(TAG, "found: ${info.serviceName}")
-            resolve(info)
-        }
-        override fun onServiceLost(info: NsdServiceInfo) {
-            Log.d(TAG, "lost: ${info.serviceName}")
-            // onServiceLost carries no TXT, so drop by the instance-name fallback key only.
-            if (resolved.remove(info.serviceName) != null) publish()
-        }
-    }
-
-    private fun resolve(found: NsdServiceInfo) {
-        if (Build.VERSION.SDK_INT >= 34) resolveViaCallback(found) else resolveViaLegacy(found)
-    }
-
-    private fun resolveViaCallback(found: NsdServiceInfo) {
-        val cb = object : NsdManager.ServiceInfoCallback {
-            override fun onServiceUpdated(info: NsdServiceInfo) = ingest(info)
-            override fun onServiceLost() {}
-            override fun onServiceInfoCallbackRegistrationFailed(code: Int) {
-                Log.e(TAG, "ServiceInfoCallback reg failed: $code")
-            }
-            override fun onServiceInfoCallbackUnregistered() {}
-        }
-        runCatching {
-            nsd.registerServiceInfoCallback(found, appCtx.mainExecutor, cb)
-            infoCallbacks.add(cb)
-        }.onFailure { Log.e(TAG, "registerServiceInfoCallback failed", it) }
-    }
-
-    private fun resolveViaLegacy(found: NsdServiceInfo) {
-        // A ResolveListener can't be reused — allocate one per resolve. TXT may be empty pre-34.
-        val listener = object : NsdManager.ResolveListener {
-            override fun onServiceResolved(info: NsdServiceInfo) = ingest(info)
-            override fun onResolveFailed(info: NsdServiceInfo, code: Int) {
-                Log.e(TAG, "resolve failed: $code")
-            }
-        }
-        runCatching { nsd.resolveService(found, listener) }
-            .onFailure { Log.e(TAG, "resolveService failed", it) }
-    }
-
-    @Suppress("DEPRECATION") // info.host is deprecated at API 34 (replaced by hostAddresses)
-    private fun ingest(info: NsdServiceInfo) {
-        val txt = parseTxt(info.attributes)
-        // Reject an incompatible protocol IF the host advertised one; tolerate empty TXT (pre-34).
-        if (txt.proto != null && !txt.isPunktfunk) {
-            Log.d(TAG, "skip non-punktfunk proto=${txt.proto}")
-            return
-        }
-        val ip = (if (Build.VERSION.SDK_INT >= 34) info.hostAddresses.firstOrNull() else info.host)
-            ?.hostAddress ?: return
-        val key = txt.id?.takeIf { it.isNotBlank() } ?: info.serviceName
-        resolved[key] = DiscoveredHost(
-            key = key,
-            name = info.serviceName.removeSuffix("."),
-            host = ip,
-            port = info.port,
-            fingerprint = txt.fp,
-            pairingRequired = txt.pairingRequired,
-        )
-        Log.d(TAG, "resolved: ${resolved[key]}")
-        publish()
+    private fun snapshot(): List<DiscoveredHost> {
+        val h = nativeHandle
+        if (h == 0L) return emptyList()
+        // getOrNull (not getOrDefault): the JNI returns a platform String!, so a (near-impossible)
+        // native null is a *success* value here — coalesce it so the main-thread poll can't NPE.
+        val blob = runCatching { NativeBridge.nativeDiscoveryPoll(h) }
+            .onFailure { Log.e(TAG, "nativeDiscoveryPoll threw", it) }
+            .getOrNull() ?: ""
+        if (blob.isEmpty()) return emptyList()
+        return blob.split('\n')
+            .filter { it.isNotBlank() }
+            .mapNotNull { parseHostRecord(it) }
+            .associateBy { it.key } // dedup by stable key (id, or addr:port)
+            .values
+            .sortedBy { it.name.lowercase() }
     }
 
     private fun acquireMulticastLock() {
         val wifi = appCtx.getSystemService(Context.WIFI_SERVICE) as WifiManager
-        multicastLock = wifi.createMulticastLock("punktfunk-nsd").apply {
+        multicastLock = wifi.createMulticastLock("punktfunk-mdns").apply {
             setReferenceCounted(true)
             runCatching { acquire() }
         }
@@ -191,4 +137,8 @@ class HostDiscovery(context: Context) {
         multicastLock?.takeIf { it.isHeld }?.let { runCatching { it.release() } }
         multicastLock = null
     }
+
+    private companion object {
+        const val POLL_MS = 1000L
+    }
 }

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

@@ -50,6 +50,12 @@ class KnownHostStore(context: Context) {
         prefs.edit().remove(key(address, port)).apply()
     }
 
+    /** Set a saved host's display name, keeping its pin + paired flag. No-op if not saved. */
+    fun rename(address: String, port: Int, newName: String) {
+        val h = get(address, port) ?: return
+        save(h.copy(name = newName))
+    }
+
     /** All trusted hosts, name-sorted — backs the saved-hosts list. */
     fun all(): List<KnownHost> =
         prefs.all.values.mapNotNull { (it as? String)?.let(::parse) }.sortedBy { it.name.lowercase() }

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

@@ -0,0 +1,62 @@
+package io.unom.punktfunk.kit.discovery
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Pure JVM test of the native-record parser (`key␟name␟addr␟port␟fp␟pair`), the Kotlin half of the
+ * discovery JNI seam. No Android types. Run: `./gradlew :kit:testDebugUnitTest`.
+ */
+class ParseRecordTest {
+    private val s = '\u001F' // field separator (must match the Rust side, discovery.rs FIELD_SEP)
+
+    private fun rec(vararg f: String) = f.joinToString(s.toString())
+
+    @Test
+    fun parsesFullRecord() {
+        val fp = "a".repeat(64)
+        val h = parseHostRecord(rec("host-123", "home-worker-2", "192.168.1.70", "9777", fp, "required"))!!
+        assertEquals("host-123", h.key)
+        assertEquals("home-worker-2", h.name)
+        assertEquals("192.168.1.70", h.host)
+        assertEquals(9777, h.port)
+        assertEquals(fp, h.fingerprint)
+        assertTrue(h.pairingRequired)
+    }
+
+    @Test
+    fun optionalPairingAndEmptyFingerprint() {
+        val h = parseHostRecord(rec("id", "name", "10.0.0.5", "9777", "", "optional"))!!
+        assertNull(h.fingerprint)
+        assertEquals(false, h.pairingRequired)
+    }
+
+    @Test
+    fun emptyKeyFallsBackToAddrPort() {
+        // Host advertised no `id` TXT → the native side leaves the key blank; we synthesize addr:port.
+        val h = parseHostRecord(rec("", "name", "10.0.0.5", "9777", "", "required"))!!
+        assertEquals("10.0.0.5:9777", h.key)
+    }
+
+    @Test
+    fun emptyNameFallsBackToAddr() {
+        val h = parseHostRecord(rec("k", "", "10.0.0.5", "9777", "", "optional"))!!
+        assertEquals("10.0.0.5", h.name)
+    }
+
+    @Test
+    fun rejectsTooFewFields() {
+        assertNull(parseHostRecord("only${'\u001F'}three${'\u001F'}fields"))
+        assertNull(parseHostRecord(""))
+    }
+
+    @Test
+    fun rejectsBadPortOrAddress() {
+        assertNull(parseHostRecord(rec("k", "n", "10.0.0.5", "notaport", "", "required")))
+        assertNull(parseHostRecord(rec("k", "n", "10.0.0.5", "0", "", "required")))
+        assertNull(parseHostRecord(rec("k", "n", "10.0.0.5", "70000", "", "required")))
+        assertNull(parseHostRecord(rec("k", "n", "", "9777", "", "required")))
+    }
+}

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

@@ -1,63 +0,0 @@
-package io.unom.punktfunk.kit.discovery
-
-import org.junit.Assert.assertEquals
-import org.junit.Assert.assertFalse
-import org.junit.Assert.assertNull
-import org.junit.Assert.assertTrue
-import org.junit.Test
-
-/** Pure JVM test of the mDNS TXT parser (no Android types). Run: `./gradlew :kit:testDebugUnitTest`. */
-class ParseTxtTest {
-    private fun b(s: String): ByteArray = s.toByteArray(Charsets.UTF_8)
-
-    @Test
-    fun parsesFullRecord() {
-        val fp = "a".repeat(64)
-        val t = parseTxt(
-            mapOf(
-                "proto" to b("punktfunk/1"),
-                "fp" to b(fp),
-                "pair" to b("required"),
-                "id" to b("host-123"),
-            ),
-        )
-        assertEquals("punktfunk/1", t.proto)
-        assertEquals(fp, t.fp)
-        assertEquals("host-123", t.id)
-        assertTrue(t.isPunktfunk)
-        assertTrue(t.pairingRequired)
-    }
-
-    @Test
-    fun optionalPairingAndMissingKeys() {
-        val t = parseTxt(mapOf("proto" to b("punktfunk/1"), "pair" to b("optional")))
-        assertFalse(t.pairingRequired)
-        assertNull(t.fp)
-        assertNull(t.id)
-    }
-
-    @Test
-    fun emptyMapYieldsAllNull() {
-        val t = parseTxt(emptyMap())
-        assertNull(t.proto)
-        assertNull(t.fp)
-        assertNull(t.pair)
-        assertNull(t.id)
-        assertFalse(t.isPunktfunk)
-        assertFalse(t.pairingRequired)
-    }
-
-    @Test
-    fun nullAndEmptyValuesTreatedAsAbsent() {
-        // NSD delivers present-but-empty TXT keys as null / empty ByteArray.
-        val t = parseTxt(mapOf("fp" to null, "id" to ByteArray(0), "proto" to b("punktfunk/1")))
-        assertNull(t.fp)
-        assertNull(t.id)
-        assertTrue(t.isPunktfunk)
-    }
-
-    @Test
-    fun nonPunktfunkProtoIsNotAccepted() {
-        assertFalse(parseTxt(mapOf("proto" to b("moonlight/7"))).isPunktfunk)
-    }
-}

clients/android/native/Cargo.toml

@@ -19,6 +19,12 @@ crate-type = ["cdylib"]
 punktfunk-core = { path = "../../../crates/punktfunk-core", features = ["quic"] }
 jni = "0.21"
 log = "0.4"
+# LAN host discovery: browse the host's `_punktfunk._udp` mDNS advert — the SAME crate + service the
+# Linux/Windows clients use (`clients/linux/src/discovery.rs`), replacing Android's per-OEM
+# `NsdManager` system daemon with one tested browse path. Pure Rust (socket2/if-addrs/mio), so it
+# cross-compiles to the Android targets AND builds on the host (the JNI seam links into
+# `cargo build --workspace`). Kotlin keeps only the Wi-Fi `MulticastLock` + permission UX.
+mdns-sd = "0.20"
 
 # Android-only deps. Gated so `cargo build --workspace` on the Linux/macOS dev boxes + CI still
 # compiles this crate (as a host cdylib) — the Android-framework glue (logging now; AMediaCodec via

clients/android/native/src/discovery.rs

@@ -0,0 +1,303 @@
+//! LAN host discovery over mDNS, in Rust via `mdns-sd` — the same crate + service type the
+//! Linux/Windows clients use (`clients/linux/src/discovery.rs`), exposed to Kotlin over JNI.
+//!
+//! Why not `NsdManager`: that API delegates to a per-OEM system mDNS daemon whose reliability
+//! varies wildly (the Android client's discovery was "mostly broken"). Browsing in our own Rust
+//! core — the crate is already linked for the whole protocol — gives one tested code path across
+//! every desktop + mobile client and removes the system-daemon dependency. Kotlin still holds the
+//! Wi-Fi `MulticastLock` for the browse lifetime (raw multicast *reception* needs it) and owns the
+//! permission UX; this module owns the socket + resolve.
+//!
+//! Shape: [`Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryStart`] spins up a
+//! [`ServiceDaemon`] browsing `_punktfunk._udp.local.` on a background thread that folds
+//! resolve/remove events into a shared map; Kotlin polls `nativeDiscoveryPoll` ~1 Hz for a
+//! newline-joined snapshot and calls `nativeDiscoveryStop` to tear it down. Polling (not a JVM
+//! callback) mirrors `nativeVideoStats`: no `AttachCurrentThread`/global-ref lifecycle to get
+//! wrong, and 1 Hz is plenty for a host picker.
+
+use crate::session::jni_guard;
+use jni::objects::JObject;
+use jni::sys::jlong;
+use jni::JNIEnv;
+use mdns_sd::{ResolvedService, ServiceDaemon, ServiceEvent};
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex};
+use std::thread::JoinHandle;
+
+/// DNS-SD service type punktfunk hosts advertise (host side: `punktfunk_host::discovery`).
+const SERVICE_TYPE: &str = "_punktfunk._udp.local.";
+/// Wire protocol id in the `proto` TXT record; a host advertising anything else is skipped.
+const PROTO: &str = "punktfunk/1";
+/// Field separator inside one serialized record (ASCII Unit Separator — never in a field value).
+const FIELD_SEP: char = '\u{1f}';
+
+/// One resolved host, serialized to Kotlin as `key␟name␟addr␟port␟fp␟pair` (`␟` = [`FIELD_SEP`]).
+/// Records are newline-joined in a poll snapshot; [`Host::encode`] strips the framing bytes from
+/// every field so no value can break it.
+#[derive(Clone, PartialEq)]
+struct Host {
+    key: String,
+    name: String,
+    addr: String,
+    port: u16,
+    fp: String,
+    pair: String,
+}
+
+impl Host {
+    fn encode(&self) -> String {
+        // mDNS instance labels + TXT values are arbitrary UTF-8 from an UNauthenticated source, so
+        // strip the field/record separators: a rogue advert that smuggled '\n'/U+001F could otherwise
+        // inject or suppress picker rows. (Trust is still gated on connect — this only protects the
+        // list's integrity.)
+        fn clean(s: &str) -> String {
+            s.replace(['\n', '\r', FIELD_SEP], "")
+        }
+        format!(
+            "{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}",
+            clean(&self.key),
+            clean(&self.name),
+            clean(&self.addr),
+            self.port,
+            clean(&self.fp),
+            clean(&self.pair),
+        )
+    }
+}
+
+/// A running browse behind the `jlong` handle: the daemon, the shared resolved-host map keyed by
+/// mDNS fullname (stable across re-announce and present on both resolve *and* remove — which fixes
+/// the old `NsdManager` key mismatch that leaked stale hosts), and the event-fold thread.
+struct Discovery {
+    daemon: ServiceDaemon,
+    hosts: Arc<Mutex<HashMap<String, Host>>>,
+    thread: Option<JoinHandle<()>>,
+}
+
+impl Discovery {
+    fn start() -> Option<Discovery> {
+        let daemon = match ServiceDaemon::new() {
+            Ok(d) => d,
+            Err(e) => {
+                log::error!("mDNS daemon failed — discovery disabled: {e}");
+                return None;
+            }
+        };
+        let rx = match daemon.browse(SERVICE_TYPE) {
+            Ok(r) => r,
+            Err(e) => {
+                log::error!("mDNS browse failed — discovery disabled: {e}");
+                let _ = daemon.shutdown();
+                return None;
+            }
+        };
+        let hosts: Arc<Mutex<HashMap<String, Host>>> = Arc::new(Mutex::new(HashMap::new()));
+        let map = hosts.clone();
+        let spawned = std::thread::Builder::new()
+            .name("pf-mdns".into())
+            .spawn(move || {
+                // Exits when the daemon is shut down (the browse channel closes → recv errors).
+                while let Ok(event) = rx.recv() {
+                    match event {
+                        ServiceEvent::ServiceResolved(info) => {
+                            if let Some(host) = resolve(&info) {
+                                map.lock()
+                                    .unwrap()
+                                    .insert(info.get_fullname().to_string(), host);
+                            }
+                        }
+                        ServiceEvent::ServiceRemoved(_ty, fullname) => {
+                            map.lock().unwrap().remove(&fullname);
+                        }
+                        _ => {}
+                    }
+                }
+            });
+        let thread = match spawned {
+            Ok(t) => t,
+            Err(e) => {
+                // The daemon thread + bound :5353 socket outlive a dropped handle (no Drop impl), so
+                // shut it down explicitly — same cleanup as the browse-failure path above.
+                log::error!("mDNS fold thread spawn failed: {e}");
+                let _ = daemon.shutdown();
+                return None;
+            }
+        };
+        log::info!("native mDNS discovery started ({SERVICE_TYPE})");
+        Some(Discovery {
+            daemon,
+            hosts,
+            thread: Some(thread),
+        })
+    }
+
+    /// Current resolved-host set, newline-joined (empty string = none). Sorted for a stable order
+    /// across polls; Kotlin re-sorts by display name.
+    fn snapshot(&self) -> String {
+        let mut records: Vec<String> = self
+            .hosts
+            .lock()
+            .unwrap()
+            .values()
+            .map(Host::encode)
+            .collect();
+        records.sort();
+        records.join("\n")
+    }
+
+    fn stop(mut self) {
+        let _ = self.daemon.shutdown(); // closes the browse channel → the fold thread exits
+        if let Some(t) = self.thread.take() {
+            let _ = t.join();
+        }
+    }
+}
+
+/// Build a [`Host`] from a resolved mDNS record, or `None` if it isn't a usable punktfunk host
+/// (incompatible advertised proto, or no IPv4 address). IPv4 only on purpose: the core dials with
+/// `format!("{host}:{port}").parse::<SocketAddr>()`, which can't parse a bare/scoped IPv6 literal
+/// (it needs the `[addr%scope]:port` form), so surfacing a v6-only host would present a card that
+/// fails on every tap. Dropping it shows the honest "not found" instead.
+fn resolve(info: &ResolvedService) -> Option<Host> {
+    let val = |k: &str| info.get_property_val_str(k).unwrap_or("").to_string();
+    let proto = val("proto");
+    if !proto.is_empty() && proto != PROTO {
+        return None; // some other DNS-SD service sharing the type — ignore
+    }
+    let addr = info
+        .get_addresses_v4()
+        .iter()
+        .next()
+        .map(|a| a.to_string())?;
+    let id = val("id");
+    let fullname = info.get_fullname();
+    Some(Host {
+        key: if id.is_empty() {
+            fullname.to_string()
+        } else {
+            id
+        },
+        name: fullname.split('.').next().unwrap_or("?").to_string(),
+        addr,
+        port: info.get_port(),
+        fp: val("fp"),
+        pair: val("pair"),
+    })
+}
+
+/// `NativeBridge.nativeDiscoveryStart(): Long` — start browsing `_punktfunk._udp`; returns an opaque
+/// handle, or `0` on failure (logged). Pair with exactly one [`nativeDiscoveryStop`]. Kotlin must
+/// hold the Wi-Fi `MulticastLock` for the browse lifetime.
+///
+/// [`nativeDiscoveryStop`]: Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryStop
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryStart(
+    _env: JNIEnv,
+    _this: JObject,
+) -> jlong {
+    jni_guard(0, || match Discovery::start() {
+        Some(d) => Box::into_raw(Box::new(d)) as jlong,
+        None => 0,
+    })
+}
+
+/// `NativeBridge.nativeDiscoveryPoll(handle): String` — the current resolved-host snapshot,
+/// newline-joined records of `key␟name␟addr␟port␟fp␟pair` (`␟` = U+001F). Empty string = no hosts /
+/// `0` handle. Poll ~1 Hz from the UI thread (cheap: a mutex lock + string build).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryPoll<'local>(
+    env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    handle: jlong,
+) -> jni::sys::jstring {
+    jni_guard(std::ptr::null_mut(), || {
+        let out = if handle == 0 {
+            String::new()
+        } else {
+            // SAFETY: live handle per the start/stop contract — Kotlin owns the lifecycle and never
+            // polls after stop (it nulls the handle first).
+            let d = unsafe { &*(handle as *const Discovery) };
+            d.snapshot()
+        };
+        match env.new_string(out) {
+            Ok(s) => s.into_raw(),
+            Err(_) => std::ptr::null_mut(),
+        }
+    })
+}
+
+/// `NativeBridge.nativeDiscoveryStop(handle)` — stop the browse, shut the daemon down and join its
+/// thread. No-op on `0`.
+///
+/// # Safety contract
+/// `handle` must be `0` or a live handle from [`nativeDiscoveryStart`], stopped exactly once and not
+/// concurrently with [`nativeDiscoveryPoll`] (Kotlin owns this; all calls are on the main thread).
+///
+/// [`nativeDiscoveryStart`]: Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryStart
+/// [`nativeDiscoveryPoll`]: Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryPoll
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryStop(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    jni_guard((), || {
+        if handle != 0 {
+            // SAFETY: live handle from nativeDiscoveryStart, stopped exactly once per the contract.
+            let d = unsafe { Box::from_raw(handle as *mut Discovery) };
+            d.stop();
+        }
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn encode_round_trips_all_fields_with_unit_separator() {
+        let h = Host {
+            key: "host-123".into(),
+            name: "home-worker-2".into(),
+            addr: "192.168.1.70".into(),
+            port: 9777,
+            fp: "ab".repeat(32),
+            pair: "required".into(),
+        };
+        let encoded = h.encode();
+        let fields: Vec<&str> = encoded.split(FIELD_SEP).collect();
+        assert_eq!(fields.len(), 6);
+        assert_eq!(fields[0], "host-123");
+        assert_eq!(fields[1], "home-worker-2");
+        assert_eq!(fields[2], "192.168.1.70");
+        assert_eq!(fields[3], "9777");
+        assert_eq!(fields[4], "ab".repeat(32));
+        assert_eq!(fields[5], "required");
+        assert!(
+            !encoded.contains('\n'),
+            "a record must never contain the record separator"
+        );
+    }
+
+    #[test]
+    fn encode_strips_injected_separators_from_a_hostile_advert() {
+        // A rogue advert could carry framing bytes in its instance label / TXT; encode must strip
+        // them so the snapshot stays exactly one record of exactly six fields.
+        let h = Host {
+            key: "k\u{1f}injected".into(),
+            name: "evil\nhost\r".into(),
+            addr: "10.0.0.5".into(),
+            port: 9777,
+            fp: "ab\u{1f}cd".into(),
+            pair: "required\n".into(),
+        };
+        let encoded = h.encode();
+        assert_eq!(encoded.matches(FIELD_SEP).count(), 5, "exactly six fields");
+        assert!(!encoded.contains('\n') && !encoded.contains('\r'));
+        let fields: Vec<&str> = encoded.split(FIELD_SEP).collect();
+        assert_eq!(fields[0], "kinjected");
+        assert_eq!(fields[1], "evilhost");
+        assert_eq!(fields[4], "abcd");
+        assert_eq!(fields[5], "required");
+    }
+}

clients/android/native/src/lib.rs

@@ -3,13 +3,17 @@
 //! Architecture: the **Rust-heavy** client model (like `punktfunk-client-linux`, *not* the
 //! thin-native-over-C-ABI Apple model). This `cdylib` links `punktfunk-core` directly and drives
 //! the whole `punktfunk/1` protocol through [`punktfunk_core::client::NativeClient`]; Kotlin owns
-//! only the Android-framework surface (Compose UI, `SurfaceView` lifecycle, input capture,
-//! `NsdManager` discovery, Keystore). The JNI seam below is the one place the two languages meet.
+//! only the Android-framework surface (Compose UI, `SurfaceView` lifecycle, input capture, the
+//! Wi-Fi `MulticastLock` + permission UX, Keystore). The JNI seam below is the one place the two
+//! languages meet.
 //!
 //! Why Rust-heavy: Kotlin cannot `import` the cbindgen C header the way Swift can, so a native
 //! bridge is unavoidable. Writing it in Rust lets the Android client reuse the Linux client's
 //! orchestration verbatim — audio jitter ring, the VK keymap inverse, latency/skew math, the
-//! input capture state machine, trust/pairing logic — instead of re-porting it into Kotlin.
+//! input capture state machine, trust/pairing logic, **mDNS discovery** ([`discovery`], the same
+//! `mdns-sd` browse the Linux/Windows clients use) — instead of re-porting it into Kotlin. Kotlin
+//! keeps only the Android-framework surface it must (Compose UI, `SurfaceView`, input capture, the
+//! Wi-Fi `MulticastLock` + permission UX, Keystore identity).
 //!
 //! JNI symbols map to `io.unom.punktfunk.kit.NativeBridge` in the `:kit` Gradle module
 //! (`clients/android`). The current surface is the scaffold's native-link proof
@@ -25,6 +29,9 @@ use jni::JNIEnv;
 mod audio;
 #[cfg(target_os = "android")]
 mod decode;
+// Ungated: pure `mdns-sd` + `jni`, so the browse + its JNI seam link into the host workspace build
+// (and its unit test runs there) exactly like `session`/`stats`. Kotlin only ever calls it on device.
+mod discovery;
 mod feedback;
 #[cfg(target_os = "android")]
 mod mic;

clients/android/native/src/session.rs

@@ -557,6 +557,38 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointer
     });
 }
 
+/// `NativeBridge.nativeSendPointerAbs(handle, x, y, surfaceWidth, surfaceHeight)` — absolute cursor
+/// position: the host moves the pointer to `x`/`y` in a `surfaceWidth`×`surfaceHeight` pixel space,
+/// normalizing against the size packed into `flags` as `(w << 16) | h` and mapping into the output
+/// region (it drops the event if that size is zero). This is the touch "direct pointing" path — the
+/// cursor jumps to the finger — and matches the Apple client's absolute touch forwarding.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointerAbs(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    x: jint,
+    y: jint,
+    surface_width: jint,
+    surface_height: jint,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let w = (surface_width.max(0) as u32) & 0xffff;
+    let ht = (surface_height.max(0) as u32) & 0xffff;
+    let _ = h.client.send_input(&InputEvent {
+        kind: InputKind::MouseMoveAbs,
+        _pad: [0; 3],
+        code: 0,
+        x,
+        y,
+        flags: (w << 16) | ht,
+    });
+}
+
 /// `NativeBridge.nativeSendPointerButton(handle, button, down)` — one button transition.
 /// `button`: GameStream id (1=left, 2=middle, 3=right, 4=X1, 5=X2). `down`: 1=press, 0=release.
 #[no_mangle]

clients/apple/README.md

@@ -174,6 +174,58 @@ signing, bundle id `io.unom.punktfunk`. Notes:
   in a simulator via `xcrun simctl install/launch` — `SIMCTL_CHILD_PUNKTFUNK_AUTOCONNECT=…`
   passes the dev autoconnect env through).
 
+## App Store screenshots
+
+Automated, faithful screenshots of the real UI for App Store Connect — one set per platform at
+exactly the accepted pixel sizes. Driver: **`tools/screenshots.sh`**.
+
+```sh
+tools/screenshots.sh all                 # macOS + (if full Xcode) iOS, iPadOS, tvOS → ./screenshots
+tools/screenshots.sh macos               # just macOS
+OUT=~/Desktop/shots tools/screenshots.sh ios ipad tvos
+PUNKTFUNK_SHOT_HERO=~/frame.png tools/screenshots.sh ios   # real captured frame behind the hero
+```
+
+How it works: the app has a DEBUG-only **shot mode** (`Sources/PunktfunkClient/Screenshots/`).
+Launched with `PUNKTFUNK_SHOT_SCENE=<name>` it renders **one** mock-populated screen full-bleed
+(`ScreenshotHostView`) instead of `ContentView`, then the OS screenshots the *real, fully-rendered*
+window — `screencapture` on macOS, `xcrun simctl io booted screenshot` on the Simulators. The five
+scenes (`ShotScenes.all`): `01-stream` (the stream hero — a synthetic frame + the glass HUD, since
+`StreamView` needs a live connection), `02-hosts`, `03-pair`, `04-trust`, `05-settings`. Mock data
+is in `ShotMock`; nothing touches a host.
+
+Output pixels are App Store Connect's required/largest sizes (Apple auto-derives the smaller ones):
+`mac` 2880×1800 · `iphone-6.9` 1320×2868 (hero 2868×1320) · `ipad-13` 2064×2752 (hero 2752×2064) ·
+`appletv` 1920×1080.
+
+Why not `ImageRenderer` (the obvious offscreen route)? It can't rasterize this app's chrome —
+`NavigationStack`, `Form`/`TabView`, and Liquid-Glass/`NSVisualEffect` materials all render black or
+SwiftUI's "can't render" placeholder. Capturing the live window/Simulator avoids that entirely.
+
+Requirements / gotchas:
+- **macOS**: only the Swift toolchain is needed, **plus a one-time Screen Recording grant** for
+  your terminal (System Settings → Privacy & Security → Screen Recording) — without it
+  `screencapture -l` fails with "could not create image from window". (A no-permission fallback,
+  `PUNKTFUNK_SHOT_SELFCAPTURE=<dir>`, uses `cacheDisplay` — but it omits material blur and can't
+  read `ScrollView` content, so it's for quick checks, not submission.)
+- **iOS/iPadOS/tvOS**: needs **full Xcode** (xcodebuild + Simulators), not just Command Line Tools,
+  and the matching device Simulators installed (iPhone 16 Pro Max, iPad Pro 13", Apple TV). Run it
+  on a full-Xcode Mac (e.g. the `macos-arm64` CI mini).
+- The hero defaults to a synthetic synthwave frame — set `PUNKTFUNK_SHOT_HERO` to a real captured
+  frame for a production-quality lead screenshot.
+
+**CI**: the `apple` workflow's **`screenshots`** job runs on the `macos-arm64` runner on every main
+push + manual dispatch (skipped on PRs), and attaches the result as a single zip artifact,
+**`punktfunk-appstore-screenshots`** (download it from the run's Artifacts; `upload-artifact@v3` —
+Gitea's backend rejects v4). It captures the two **required iOS sizes — iPhone 6.9" + iPad 13"** —
+on the Simulator (auto-creating the device if the runner lacks it), and is isolated from the
+build/test job so a capture hiccup never reds the build.
+
+**macOS and tvOS are NOT in CI**, by design: the self-hosted runner is **headless** (no
+window-server session), so the macOS window capture can't run there, and tvOS needs the Tier-3
+build-std slice. Generate those on a GUI Mac: `tools/screenshots.sh macos tvos`. (If the runner is
+ever switched to a logged-in GUI session, re-adding macOS to the job's capture step is one line.)
+
 ## Notes for whoever picks this up next
 
 1. **cbindgen import quirk** (the predicted "small compile fixes", now fixed): the
@@ -309,4 +361,4 @@ signing, bundle id `io.unom.punktfunk`. Notes:
 - Mid-stream renegotiation (resolution change without reconnect) is designed-for but not
   implemented (the Welcome is one-shot today).
 - Host-side gamepad injection needs `/dev/uinput` access on the box (udev rule from
-  `docs/linux-setup.md`).
+  `design/linux-setup.md`).

clients/apple/Sources/PunktfunkClient/ControllerTestView.swift

@@ -0,0 +1,387 @@
+// DEBUG-only controller test panel, reached from Settings → Controllers → "Test Controller…".
+// It shows the live input of the active controller and lets you fire the host→client feedback
+// channels — rumble, DualSense adaptive triggers, lightbar, player LEDs — straight at the
+// physical pad (no host needed), so the rendering paths a session uses can be confirmed
+// on-device. Driven by PunktfunkKit's `ControllerTester`, which reuses the real renderers.
+//
+// tvOS is excluded for now (it has no segmented picker / the panel wants a pointer-style
+// layout); macOS + iOS/iPadOS cover the validation need.
+
+#if DEBUG && !os(tvOS)
+import GameController
+import PunktfunkKit
+import SwiftUI
+
+@MainActor
+struct ControllerTestView: View {
+    @Environment(\.dismiss) private var dismiss
+    @ObservedObject private var gamepads = GamepadManager.shared
+    @StateObject private var tester = ControllerTester()
+
+    @State private var heavyOn = false
+    @State private var lightOn = false
+    @State private var intensity = 0.75
+    @State private var triggerTarget = TriggerTarget.both
+    @State private var playerLED = -1
+
+    private enum TriggerTarget: String, CaseIterable, Identifiable {
+        case left = "L2", right = "R2", both = "Both"
+        var id: String { rawValue }
+    }
+
+    private struct TriggerDemo: Identifiable {
+        let label: String
+        let effect: DualSenseTriggerEffect
+        var id: String { label }
+    }
+
+    private static let triggerDemos: [TriggerDemo] = [
+        .init(label: "Off", effect: .off),
+        .init(label: "Resistance", effect: .feedback(start: 0.3, strength: 0.7)),
+        .init(label: "Weapon", effect: .weapon(start: 0.4, end: 0.7, strength: 0.9)),
+        .init(label: "Vibration", effect: .vibration(start: 0.1, amplitude: 0.8, frequency: 0.5)),
+        .init(label: "Bow", effect: .slope(start: 0.2, end: 0.9, startStrength: 0.2, endStrength: 0.9)),
+    ]
+
+    // (display name, hardware colour, swatch colour)
+    private static let lightSwatches: [(String, GCColor, Color)] = [
+        ("Red", GCColor(red: 1, green: 0, blue: 0), .red),
+        ("Green", GCColor(red: 0, green: 1, blue: 0), .green),
+        ("Blue", GCColor(red: 0, green: 0.2, blue: 1), .blue),
+        ("White", GCColor(red: 1, green: 1, blue: 1), .white),
+    ]
+
+    var body: some View {
+        VStack(spacing: 0) {
+            HStack {
+                Text("Test Controller").font(.headline)
+                Spacer()
+                Button("Done") { dismiss() }.keyboardShortcut(.cancelAction)
+            }
+            .padding()
+            Divider()
+            ScrollView {
+                VStack(alignment: .leading, spacing: 16) {
+                    if let active = gamepads.active {
+                        header(active)
+                        inputCard
+                        rumbleCard()
+                        triggerCard(active)
+                        extrasCard(active)
+                    } else {
+                        ContentUnavailableView(
+                            "No controller",
+                            systemImage: "gamecontroller",
+                            description: Text("Connect a controller and pick it under "
+                                + "Settings → Controllers → Use controller."))
+                            .frame(maxWidth: .infinity, minHeight: 220)
+                    }
+                }
+                .padding()
+            }
+        }
+        .frame(minWidth: 420, minHeight: 540)
+        .onAppear { tester.target(gamepads.active?.controller) }
+        .onDisappear { tester.stop() }
+        .onChange(of: gamepads.active?.id) { _, _ in
+            heavyOn = false
+            lightOn = false
+            playerLED = -1
+            tester.target(gamepads.active?.controller)
+        }
+    }
+
+    // MARK: Header
+
+    private func header(_ c: GamepadManager.DiscoveredController) -> some View {
+        HStack(spacing: 10) {
+            Image(systemName: c.isDualSense ? "playstation.logo" : "gamecontroller.fill")
+                .font(.title2)
+                .foregroundStyle(.secondary)
+            VStack(alignment: .leading, spacing: 2) {
+                Text(c.name).font(.headline)
+                Text(c.productCategory).font(.caption).foregroundStyle(.secondary)
+            }
+            Spacer()
+        }
+    }
+
+    // MARK: Input
+
+    private var inputCard: some View {
+        card("Input") {
+            // Poll the live controller at 30 Hz — no handlers installed, so nothing else's
+            // capture is disturbed.
+            TimelineView(.periodic(from: .now, by: 1.0 / 30.0)) { _ in
+                if let gp = gamepads.active?.controller.extendedGamepad {
+                    inputReadout(gp, controller: gamepads.active?.controller)
+                } else {
+                    Text("Not an extended gamepad").foregroundStyle(.secondary)
+                }
+            }
+        }
+    }
+
+    @ViewBuilder
+    private func inputReadout(_ g: GCExtendedGamepad, controller: GCController?) -> some View {
+        VStack(alignment: .leading, spacing: 14) {
+            HStack(alignment: .top, spacing: 20) {
+                stick("L", x: g.leftThumbstick.xAxis.value, y: g.leftThumbstick.yAxis.value,
+                      pressed: g.leftThumbstickButton?.isPressed ?? false)
+                stick("R", x: g.rightThumbstick.xAxis.value, y: g.rightThumbstick.yAxis.value,
+                      pressed: g.rightThumbstickButton?.isPressed ?? false)
+                VStack(spacing: 8) {
+                    triggerBar("L2", value: g.leftTrigger.value)
+                    triggerBar("R2", value: g.rightTrigger.value)
+                }
+            }
+            buttonGrid(g)
+            if let tp = Self.touchpad(g) {
+                touchpadView(tp)
+            }
+            if let m = controller?.motion {
+                motionReadout(m)
+            }
+        }
+    }
+
+    private func stick(_ label: String, x: Float, y: Float, pressed: Bool) -> some View {
+        VStack(spacing: 4) {
+            ZStack {
+                Circle().stroke(Color.secondary.opacity(0.3))
+                Circle()
+                    .fill(pressed ? Color.accentColor : Color.secondary)
+                    .frame(width: 12, height: 12)
+                    .offset(x: CGFloat(x) * 22, y: CGFloat(-y) * 22) // GC y is +up
+            }
+            .frame(width: 56, height: 56)
+            Text("\(label) \(sgn(x)),\(sgn(y))").font(.caption2.monospaced()).foregroundStyle(.secondary)
+        }
+    }
+
+    private func triggerBar(_ label: String, value: Float) -> some View {
+        HStack(spacing: 6) {
+            Text(label).font(.caption2.monospaced()).frame(width: 22, alignment: .leading)
+            GeometryReader { geo in
+                ZStack(alignment: .leading) {
+                    Capsule().fill(Color.secondary.opacity(0.15))
+                    Capsule().fill(Color.accentColor).frame(width: geo.size.width * CGFloat(value))
+                }
+            }
+            .frame(height: 10)
+            Text(mag(value)).font(.caption2.monospaced()).frame(width: 34, alignment: .trailing)
+                .foregroundStyle(.secondary)
+        }
+        .frame(width: 150)
+    }
+
+    private func buttonGrid(_ g: GCExtendedGamepad) -> some View {
+        var items: [(String, Bool)] = [
+            ("A", g.buttonA.isPressed), ("B", g.buttonB.isPressed),
+            ("X", g.buttonX.isPressed), ("Y", g.buttonY.isPressed),
+            ("LB", g.leftShoulder.isPressed), ("RB", g.rightShoulder.isPressed),
+            ("L3", g.leftThumbstickButton?.isPressed ?? false),
+            ("R3", g.rightThumbstickButton?.isPressed ?? false),
+            ("Menu", g.buttonMenu.isPressed),
+            ("Opts", g.buttonOptions?.isPressed ?? false),
+            ("↑", g.dpad.up.isPressed), ("↓", g.dpad.down.isPressed),
+            ("←", g.dpad.left.isPressed), ("→", g.dpad.right.isPressed),
+        ]
+        if let tp = Self.touchpad(g) { items.append(("Pad", tp.button.isPressed)) }
+        return LazyVGrid(
+            columns: Array(repeating: GridItem(.flexible(), spacing: 6), count: 5), spacing: 6
+        ) {
+            ForEach(items.indices, id: \.self) { i in
+                Text(items[i].0)
+                    .font(.caption.monospaced())
+                    .frame(maxWidth: .infinity, minHeight: 24)
+                    .background(
+                        RoundedRectangle(cornerRadius: 6)
+                            .fill(items[i].1 ? Color.accentColor : Color.secondary.opacity(0.15)))
+                    .foregroundStyle(items[i].1 ? Color.white : Color.secondary)
+            }
+        }
+    }
+
+    private func touchpadView(
+        _ tp: (primary: GCControllerDirectionPad, secondary: GCControllerDirectionPad,
+               button: GCControllerButtonInput)
+    ) -> some View {
+        VStack(alignment: .leading, spacing: 4) {
+            Text("Touchpad\(tp.button.isPressed ? " — click" : "")")
+                .font(.caption2).foregroundStyle(.secondary)
+            ZStack {
+                RoundedRectangle(cornerRadius: 8).stroke(Color.secondary.opacity(0.3))
+                fingerDot(tp.primary, color: .accentColor)
+                fingerDot(tp.secondary, color: .orange)
+            }
+            .frame(width: 150, height: 74)
+        }
+    }
+
+    private func fingerDot(_ pad: GCControllerDirectionPad, color: Color) -> some View {
+        let x = pad.xAxis.value, y = pad.yAxis.value
+        let active = !(x == 0 && y == 0) // GC snaps a lifted finger to exactly (0, 0)
+        return Circle().fill(color).frame(width: 10, height: 10)
+            .offset(x: CGFloat(x) * 71, y: CGFloat(-y) * 33)
+            .opacity(active ? 1 : 0)
+    }
+
+    private func motionReadout(_ m: GCMotion) -> some View {
+        let a = Self.totalAccel(m)
+        return VStack(alignment: .leading, spacing: 2) {
+            Text("Motion").font(.caption2).foregroundStyle(.secondary)
+            Text(String(format: "gyro  %+.2f %+.2f %+.2f",
+                        m.rotationRate.x, m.rotationRate.y, m.rotationRate.z))
+                .font(.caption2.monospaced())
+            Text(String(format: "accel %+.2f %+.2f %+.2f", a.0, a.1, a.2))
+                .font(.caption2.monospaced())
+        }
+    }
+
+    // MARK: Rumble
+
+    private func rumbleCard() -> some View {
+        card("Rumble") {
+            VStack(alignment: .leading, spacing: 12) {
+                Picker("Strength", selection: $intensity) {
+                    Text("25%").tag(0.25)
+                    Text("50%").tag(0.5)
+                    Text("75%").tag(0.75)
+                    Text("100%").tag(1.0)
+                }
+                .pickerStyle(.segmented)
+                Toggle("Heavy motor (left)", isOn: $heavyOn)
+                Toggle("Light motor (right)", isOn: $lightOn)
+                Label("Backend: \(tester.rumbleBackend)", systemImage: "waveform")
+                    .font(.caption).foregroundStyle(.secondary)
+                Text("Toggle a motor to feel it. The host maps a game's low/high-frequency "
+                    + "rumble onto these two. A DualSense is driven over raw HID (CoreHaptics "
+                    + "can't reach its motors on macOS).")
+                    .font(.caption).foregroundStyle(.secondary)
+            }
+            .onChange(of: heavyOn) { _, _ in applyRumble() }
+            .onChange(of: lightOn) { _, _ in applyRumble() }
+            .onChange(of: intensity) { _, _ in applyRumble() }
+        }
+    }
+
+    private func applyRumble() {
+        tester.rumble(low: heavyOn ? Float(intensity) : 0, high: lightOn ? Float(intensity) : 0)
+    }
+
+    // MARK: Adaptive triggers
+
+    private func triggerCard(_ c: GamepadManager.DiscoveredController) -> some View {
+        card("Adaptive triggers") {
+            if c.hasAdaptiveTriggers {
+                VStack(alignment: .leading, spacing: 12) {
+                    Picker("Apply to", selection: $triggerTarget) {
+                        ForEach(TriggerTarget.allCases) { Text($0.rawValue).tag($0) }
+                    }
+                    .pickerStyle(.segmented)
+                    LazyVGrid(
+                        columns: [GridItem(.adaptive(minimum: 96), spacing: 8)], spacing: 8
+                    ) {
+                        ForEach(Self.triggerDemos) { demo in
+                            Button(demo.label) { applyTrigger(demo.effect) }
+                                .buttonStyle(.bordered)
+                        }
+                    }
+                    Text("Pick an effect, then pull L2/R2 to feel the resistance.")
+                        .font(.caption).foregroundStyle(.secondary)
+                }
+            } else {
+                Text("Adaptive triggers need a DualSense.")
+                    .font(.caption).foregroundStyle(.secondary)
+            }
+        }
+    }
+
+    private func applyTrigger(_ e: DualSenseTriggerEffect) {
+        switch triggerTarget {
+        case .left: tester.applyTrigger(e, right: false)
+        case .right: tester.applyTrigger(e, right: true)
+        case .both:
+            tester.applyTrigger(e, right: false)
+            tester.applyTrigger(e, right: true)
+        }
+    }
+
+    // MARK: Lightbar + player LED
+
+    @ViewBuilder
+    private func extrasCard(_ c: GamepadManager.DiscoveredController) -> some View {
+        if c.hasLight {
+            card("Lightbar & player LED") {
+                VStack(alignment: .leading, spacing: 12) {
+                    HStack(spacing: 12) {
+                        ForEach(Self.lightSwatches.indices, id: \.self) { i in
+                            Button { tester.setLight(Self.lightSwatches[i].1) } label: {
+                                Circle().fill(Self.lightSwatches[i].2)
+                                    .frame(width: 26, height: 26)
+                                    .overlay(Circle().stroke(Color.secondary.opacity(0.4)))
+                            }
+                            .buttonStyle(.plain)
+                        }
+                        Button("Off") { tester.setLight(nil) }.buttonStyle(.bordered)
+                    }
+                    Picker("Player LED", selection: $playerLED) {
+                        Text("Off").tag(-1)
+                        Text("1").tag(0)
+                        Text("2").tag(1)
+                        Text("3").tag(2)
+                        Text("4").tag(3)
+                    }
+                    .pickerStyle(.segmented)
+                    .onChange(of: playerLED) { _, v in
+                        tester.setPlayerIndex(GCControllerPlayerIndex(rawValue: v) ?? .indexUnset)
+                    }
+                }
+            }
+        }
+    }
+
+    // MARK: Helpers
+
+    private func card<Content: View>(
+        _ title: String, @ViewBuilder _ content: () -> Content
+    ) -> some View {
+        VStack(alignment: .leading, spacing: 10) {
+            Text(title).font(.subheadline.weight(.semibold))
+            content()
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .padding(14)
+        .background(RoundedRectangle(cornerRadius: 12).fill(Color.secondary.opacity(0.08)))
+    }
+
+    private func sgn(_ v: Float) -> String { String(format: "%+.2f", v) }
+    private func mag(_ v: Float) -> String { String(format: "%.2f", v) }
+
+    /// The touchpad surface of a PlayStation pad — `GCDualSenseGamepad` and `GCDualShockGamepad`
+    /// don't share a touchpad type, so downcast either. `nil` for any other controller.
+    private static func touchpad(
+        _ g: GCExtendedGamepad
+    ) -> (primary: GCControllerDirectionPad, secondary: GCControllerDirectionPad,
+          button: GCControllerButtonInput)? {
+        if let ds = g as? GCDualSenseGamepad {
+            return (ds.touchpadPrimary, ds.touchpadSecondary, ds.touchpadButton)
+        }
+        if let ds4 = g as? GCDualShockGamepad {
+            return (ds4.touchpadPrimary, ds4.touchpadSecondary, ds4.touchpadButton)
+        }
+        return nil
+    }
+
+    /// Total acceleration in g: gravity + user when the pad splits them, else the raw vector.
+    private static func totalAccel(_ m: GCMotion) -> (Double, Double, Double) {
+        if m.hasGravityAndUserAcceleration {
+            return (m.gravity.x + m.userAcceleration.x,
+                    m.gravity.y + m.userAcceleration.y,
+                    m.gravity.z + m.userAcceleration.z)
+        }
+        return (m.acceleration.x, m.acceleration.y, m.acceleration.z)
+    }
+}
+#endif

clients/apple/Sources/PunktfunkClient/PunktfunkClientApp.swift

@@ -14,8 +14,19 @@ struct PunktfunkClientApp: App {
 
     var body: some Scene {
         WindowGroup("Punktfunk") {
+            #if DEBUG
+            // PUNKTFUNK_SHOT_SCENE=<name> → show that single mock-populated screen full-bleed for
+            // the App Store screenshot capture (tools/screenshots.sh). Normal launch otherwise;
+            // the whole path is absent from Release builds.
+            if let scene = ScreenshotMode.requestedScene {
+                ScreenshotHostView(scene: scene)
+            } else {
                 ContentView()
             }
+            #else
+            ContentView()
+            #endif
+        }
         // The Stream menu (Disconnect ⌘D, Show/Hide Statistics ⌘⇧S) — a real menu bar on
         // macOS, hardware-keyboard shortcuts on iPad. tvOS has neither.
         #if !os(tvOS)

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

@@ -0,0 +1,57 @@
+// App Store screenshot harness — device catalog.
+//
+// The harness captures the REAL running UI (not an offscreen ImageRenderer snapshot, which can't
+// rasterize NavigationStack / Form / Liquid-Glass — they come out black). The app is launched in
+// "shot mode" (PUNKTFUNK_SHOT_SCENE=<name>, see ScreenshotHost) showing one mock-populated scene
+// full-bleed, and the OS screenshots it: `xcrun simctl io booted screenshot` on the iOS/tvOS
+// simulators (native pixels = the exact App Store size), `screencapture` for the mac window.
+// tools/screenshots.sh drives it. DEBUG-only — none of this ships in Release.
+//
+// This catalog records the target App Store sizes; on Apple platforms only the mac size is read
+// at runtime (to size the capture window) — the simulator IS the device, so iOS/tvOS pixels are
+// whatever the booted device is.
+
+#if DEBUG
+import CoreGraphics
+
+enum ShotOrientation { case natural, portrait, landscape }
+
+/// A target App Store canvas: a natural-orientation pixel size + backing scale.
+struct ShotDevice {
+    let id: String
+    let naturalWidth: Int
+    let naturalHeight: Int
+    let scale: CGFloat
+
+    func pixels(_ o: ShotOrientation) -> (w: Int, h: Int) {
+        let long = max(naturalWidth, naturalHeight)
+        let short = min(naturalWidth, naturalHeight)
+        switch o {
+        case .natural: return (naturalWidth, naturalHeight)
+        case .portrait: return (short, long)
+        case .landscape: return (long, short)
+        }
+    }
+
+    /// Logical point size (pixels / scale) — used to size the mac capture window so that a
+    /// `screencapture` on a 2× display yields exactly `pixels(_:)`.
+    func points(_ o: ShotOrientation) -> CGSize {
+        let (w, h) = pixels(o)
+        return CGSize(width: CGFloat(w) / scale, height: CGFloat(h) / scale)
+    }
+
+    /// Mac: 2880×1800 (16:10 Retina) — an accepted size; on a 1× display the window capture is
+    /// 1440×900, also accepted.
+    static let mac = ShotDevice(id: "mac", naturalWidth: 2880, naturalHeight: 1800, scale: 2)
+
+    /// iPhone 6.9" (required) — for reference / the driver script's simulator choice.
+    static let iphone69 = ShotDevice(id: "iphone-6.9", naturalWidth: 1320, naturalHeight: 2868,
+                                     scale: 3)
+    /// iPad 13" (required).
+    static let ipad13 = ShotDevice(id: "ipad-13", naturalWidth: 2064, naturalHeight: 2752,
+                                   scale: 2)
+    /// Apple TV (always landscape).
+    static let appleTV = ShotDevice(id: "appletv", naturalWidth: 1920, naturalHeight: 1080,
+                                    scale: 1)
+}
+#endif

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

@@ -0,0 +1,147 @@
+// App Store screenshot harness — the in-app "shot mode" root.
+//
+// Launched with PUNKTFUNK_SHOT_SCENE=<name> (one of ShotScenes.all), the app shows that single
+// mock-populated scene full-bleed instead of ContentView, so the OS can screenshot the REAL,
+// fully-rendered UI (materials, NavigationStack, glass — all the things ImageRenderer can't
+// rasterize offscreen). tools/screenshots.sh drives one launch per scene per device.
+//
+// Capture per platform:
+//   • iOS / tvOS simulator → `xcrun simctl io booted screenshot` (native pixels = exact size).
+//   • macOS → `screencapture -l<windowID>` of the borderless capture window (the configurator
+//     prints `PF_SHOT_WINDOW=<id>`), or the no-permission self-capture fallback
+//     (PUNKTFUNK_SHOT_SELFCAPTURE=<dir> → cacheDisplay; renders the real hierarchy but, like all
+//     non-window-server capture, omits material blur).
+//
+// Every screen prints `PF_SHOT_READY scene=<name>` to stdout once it has settled, so the driver
+// can wait for layout instead of guessing with a fixed sleep.
+
+#if DEBUG
+import SwiftUI
+#if os(macOS)
+import AppKit
+import ImageIO
+#endif
+
+@MainActor
+enum ScreenshotMode {
+    /// The scene requested via PUNKTFUNK_SHOT_SCENE, or nil for a normal launch.
+    static var requestedScene: ShotScene? {
+        let name = ProcessInfo.processInfo.environment["PUNKTFUNK_SHOT_SCENE"] ?? ""
+        guard !name.isEmpty else { return nil }
+        return ShotScenes.all.first { $0.name == name }
+    }
+}
+
+/// Full-bleed host for a single scene, with per-platform window sizing / orientation and a
+/// readiness ping for the capture script.
+struct ScreenshotHostView: View {
+    let scene: ShotScene
+
+    var body: some View {
+        scene.make()
+            .environment(\.colorScheme, scene.colorScheme)
+            .frame(maxWidth: .infinity, maxHeight: .infinity)
+            .background(Color.black)
+            .ignoresSafeArea()
+            #if os(macOS)
+            .background(MacShotWindowConfigurator(scene: scene))
+            #elseif os(iOS)
+            .background(IOSOrientationConfigurator(orientation: scene.orientation))
+            #endif
+            .task {
+                // Let layout + materials settle, then signal the driver.
+                try? await Task.sleep(nanoseconds: 900_000_000)
+                announceReady()
+            }
+    }
+
+    private func announceReady() {
+        print("PF_SHOT_READY scene=\(scene.name)")
+        fflush(stdout)
+        #if os(macOS)
+        MacSelfCapture.captureIfRequested(scene: scene)
+        #endif
+    }
+}
+
+#if os(macOS)
+/// Sizes the hosting window to the mac canvas, strips the title bar to a clean full-bleed
+/// surface, and prints the CGWindowID for `screencapture -l`.
+private struct MacShotWindowConfigurator: NSViewRepresentable {
+    let scene: ShotScene
+
+    func makeNSView(context: Context) -> NSView { NSView() }
+
+    func updateNSView(_ view: NSView, context: Context) {
+        DispatchQueue.main.async {
+            guard let window = view.window, !context.coordinator.configured else { return }
+            context.coordinator.configured = true
+            // NavigationStack / Form / material chrome follow the WINDOW's appearance, not the
+            // SwiftUI colorScheme — without this the dark scenes render on a light window (white
+            // background, washed-out materials).
+            window.appearance = NSAppearance(named: scene.colorScheme == .dark ? .darkAqua : .aqua)
+            let size = ShotDevice.mac.points(scene.orientation)
+            window.styleMask = [.titled, .fullSizeContentView]
+            window.titlebarAppearsTransparent = true
+            window.titleVisibility = .hidden
+            window.isMovable = false
+            for button in [NSWindow.ButtonType.closeButton, .miniaturizeButton, .zoomButton] {
+                window.standardWindowButton(button)?.isHidden = true
+            }
+            window.setContentSize(size)
+            window.center()
+            window.makeKeyAndOrderFront(nil)
+            NSApp.activate(ignoringOtherApps: true)
+            print("PF_SHOT_WINDOW=\(window.windowNumber) scene=\(scene.name) "
+                + "size=\(Int(size.width))x\(Int(size.height))pt")
+            fflush(stdout)
+        }
+    }
+
+    func makeCoordinator() -> Coordinator { Coordinator() }
+    final class Coordinator { var configured = false }
+}
+
+/// No-permission fallback: capture the window's view tree via cacheDisplay. Renders the real
+/// hierarchy (NavigationStack/Form/cards — unlike ImageRenderer) but omits material blur, which
+/// only the window server (screencapture) composites. Used when PUNKTFUNK_SHOT_SELFCAPTURE is set.
+enum MacSelfCapture {
+    static func captureIfRequested(scene: ShotScene) {
+        guard let dir = ProcessInfo.processInfo.environment["PUNKTFUNK_SHOT_SELFCAPTURE"],
+              !dir.isEmpty,
+              let window = NSApp.windows.first(where: { $0.isVisible }),
+              let content = window.contentView else { return }
+        let outDir = URL(fileURLWithPath: (dir as NSString).expandingTildeInPath, isDirectory: true)
+        try? FileManager.default.createDirectory(at: outDir, withIntermediateDirectories: true)
+        guard let rep = content.bitmapImageRepForCachingDisplay(in: content.bounds) else { return }
+        content.cacheDisplay(in: content.bounds, to: rep)
+        let url = outDir.appendingPathComponent("\(ShotDevice.mac.id)-\(scene.name).png")
+        if let dest = CGImageDestinationCreateWithURL(
+            url as CFURL, "public.png" as CFString, 1, nil), let cg = rep.cgImage {
+            CGImageDestinationAddImage(dest, cg, nil)
+            CGImageDestinationFinalize(dest)
+            print("PF_SHOT_SAVED \(url.path) \(rep.pixelsWide)x\(rep.pixelsHigh)px")
+        }
+        fflush(stdout)
+        exit(0)
+    }
+}
+#endif
+
+#if os(iOS)
+/// Best-effort orientation lock for the requested scene (landscape for the stream hero, portrait
+/// for chrome). Requires the app to allow those orientations in Info.plist.
+private struct IOSOrientationConfigurator: UIViewControllerRepresentable {
+    let orientation: ShotOrientation
+
+    func makeUIViewController(context: Context) -> UIViewController { UIViewController() }
+
+    func updateUIViewController(_ vc: UIViewController, context: Context) {
+        guard let scene = vc.view.window?.windowScene else { return }
+        let mask: UIInterfaceOrientationMask = orientation == .landscape ? .landscapeRight : .portrait
+        scene.requestGeometryUpdate(.iOS(interfaceOrientations: mask))
+        vc.setNeedsUpdateOfSupportedInterfaceOrientations()
+    }
+}
+#endif
+#endif

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

@@ -0,0 +1,284 @@
+// App Store screenshot scenes — the actual screens we render, each wired with mock data so it
+// looks populated without a live host. Every scene is built from the REAL app views (HomeView,
+// SettingsView, PairSheet, TrustCardView) so the screenshots track the shipping UI; only the
+// live stream is faked (StreamView needs a real punktfunk/1 connection — see ShotStreamHero).
+
+#if DEBUG
+import PunktfunkKit
+import SwiftUI
+
+/// One screen to capture: a name (→ file suffix), the canvas orientation, a color scheme, and a
+/// factory that builds the populated view on the main actor.
+struct ShotScene {
+    let name: String
+    let orientation: ShotOrientation
+    let colorScheme: ColorScheme
+    let make: @MainActor () -> AnyView
+}
+
+@MainActor
+enum ShotScenes {
+    static let all: [ShotScene] = [
+        ShotScene(name: "01-stream", orientation: .landscape, colorScheme: .dark) {
+            AnyView(ShotStreamHero())
+        },
+        ShotScene(name: "02-hosts", orientation: .natural, colorScheme: .dark) {
+            AnyView(ShotHome())
+        },
+        ShotScene(name: "03-pair", orientation: .natural, colorScheme: .dark) {
+            AnyView(ShotPair())
+        },
+        ShotScene(name: "04-trust", orientation: .landscape, colorScheme: .dark) {
+            AnyView(ShotTrust())
+        },
+        ShotScene(name: "05-settings", orientation: .natural, colorScheme: .dark) {
+            AnyView(ShotSettings())
+        },
+    ]
+}
+
+// MARK: - Mock data
+
+@MainActor
+enum ShotMock {
+    /// A populated saved-host grid: a pinned recent host, a couple more, mixed online state.
+    static func hostStore() -> HostStore {
+        let store = HostStore()
+        store.hosts = [
+            StoredHost(name: "Battlestation", address: "192.168.1.20", port: 9777,
+                       pinnedSHA256: fingerprint, lastConnected: Date().addingTimeInterval(-420)),
+            StoredHost(name: "Living Room PC", address: "192.168.1.41", port: 9777,
+                       pinnedSHA256: fingerprint),
+            StoredHost(name: "Workshop", address: "10.0.0.7", port: 9777),
+        ]
+        return store
+    }
+
+    static let host = StoredHost(name: "Battlestation", address: "192.168.1.20", port: 9777,
+                                 pinnedSHA256: fingerprint)
+
+    /// A plausible-looking 32-byte SHA-256 for the trust card / pin lock glyphs.
+    static let fingerprint = Data((0..<32).map { UInt8(($0 &* 37 &+ 0x1d) & 0xff) })
+}
+
+// MARK: - Home
+
+private struct ShotHome: View {
+    @StateObject private var store = ShotMock.hostStore()
+    @StateObject private var model = SessionModel()
+    @StateObject private var discovery = HostDiscovery()
+
+    var body: some View {
+        #if os(macOS)
+        HomeView(
+            store: store, model: model, discovery: discovery,
+            showAddHost: .constant(false), pairingTarget: .constant(nil),
+            speedTestTarget: .constant(nil), libraryTarget: .constant(nil),
+            connect: { _ in }, connectDiscovered: { _ in },
+            onPaired: { _, _ in }, onLaunchTitle: { _, _ in })
+        #else
+        HomeView(
+            store: store, model: model, discovery: discovery,
+            showAddHost: .constant(false), pairingTarget: .constant(nil),
+            speedTestTarget: .constant(nil), libraryTarget: .constant(nil),
+            showSettings: .constant(false),
+            connect: { _ in }, connectDiscovered: { _ in },
+            onPaired: { _, _ in }, onLaunchTitle: { _, _ in })
+        #endif
+    }
+}
+
+// MARK: - Settings
+
+private struct ShotSettings: View {
+    var body: some View {
+        #if os(macOS)
+        // The mac Settings window is a fixed-size tabbed panel — float it over a dimmed host
+        // grid so the shot reads as the preferences window over the running app.
+        ZStack {
+            ShotHome().blur(radius: 24).overlay(Color.black.opacity(0.45))
+            SettingsView()
+                .fixedSize()
+                .clipShape(RoundedRectangle(cornerRadius: 12))
+                .shadow(radius: 40, y: 16)
+        }
+        #elseif os(iOS)
+        NavigationStack {
+            SettingsView()
+                .navigationTitle("Settings")
+                .navigationBarTitleDisplayMode(.inline)
+        }
+        #else
+        NavigationStack { SettingsView() }
+        #endif
+    }
+}
+
+// MARK: - Pair (PIN ceremony)
+
+private struct ShotPair: View {
+    var body: some View {
+        ZStack {
+            ShotHome().blur(radius: 28).overlay(Color.black.opacity(0.5))
+            PairSheet(host: ShotMock.host, onPaired: { _ in })
+                .frame(maxWidth: 460)
+                .background(.regularMaterial, in: RoundedRectangle(cornerRadius: 18))
+                .clipShape(RoundedRectangle(cornerRadius: 18))
+                .shadow(radius: 40, y: 16)
+                .padding(40)
+        }
+    }
+}
+
+// MARK: - Trust (TOFU card over the blurred live stream)
+
+private struct ShotTrust: View {
+    var body: some View {
+        ZStack {
+            ShotDesktopFrame()
+                .blur(radius: 32)
+                .overlay(Color.black.opacity(0.45))
+            TrustCardView(
+                fingerprint: ShotMock.fingerprint, hostName: "Battlestation",
+                onCancel: {}, onTrust: {}, onPairInstead: {})
+        }
+    }
+}
+
+// MARK: - Stream hero
+
+/// The marketing hero: a stand-in streamed frame with the real glass HUD chip on top.
+/// StreamView can't render here (it needs a live punktfunk/1 connection), so the frame is
+/// synthetic — set `PUNKTFUNK_SHOT_HERO=/path/to/frame.png` to drop in a real captured frame.
+private struct ShotStreamHero: View {
+    var body: some View {
+        ZStack(alignment: .topTrailing) {
+            ShotDesktopFrame()
+            ShotHUD()
+        }
+        .background(Color.black)
+    }
+}
+
+/// A faithful copy of StreamHUDView's overlay (which needs a live PunktfunkConnection for the
+/// mode line) with representative numbers, reusing the app's real `.glassBackground`.
+private struct ShotHUD: View {
+    var body: some View {
+        VStack(alignment: .trailing, spacing: 4) {
+            HStack(spacing: 6) {
+                Circle().fill(Color.accentColor).frame(width: 7, height: 7)
+                Text("5120×1440@240  240 fps  812.4 Mb/s")
+                    .font(.system(.caption, design: .monospaced))
+            }
+            Text("capture→client 1.3/2.1 ms p50/p95")
+                .font(.system(.caption2, design: .monospaced))
+                .foregroundStyle(.secondary)
+            #if os(macOS)
+            Text("⌘⎋ releases the mouse")
+                .font(.caption2).foregroundStyle(.secondary)
+            #elseif os(tvOS)
+            Text("Press Menu to disconnect")
+                .font(.caption).foregroundStyle(.secondary)
+            #endif
+        }
+        .padding(10)
+        .glassBackground(RoundedRectangle(cornerRadius: 10))
+        .padding(10)
+    }
+}
+
+/// A synthetic "streamed frame" — a synthwave scene that reads as game content without shipping
+/// any real art. Replaced wholesale when `PUNKTFUNK_SHOT_HERO` points at a real PNG.
+private struct ShotDesktopFrame: View {
+    var body: some View {
+        if let image = Self.overrideImage {
+            image.resizable().scaledToFill()
+        } else {
+            synthetic
+        }
+    }
+
+    private var synthetic: some View {
+        ZStack {
+            LinearGradient(
+                colors: [
+                    Color(red: 0.05, green: 0.02, blue: 0.16),
+                    Color(red: 0.35, green: 0.05, blue: 0.42),
+                    Color(red: 0.95, green: 0.30, blue: 0.35),
+                    Color(red: 0.99, green: 0.62, blue: 0.32),
+                ],
+                startPoint: .top, endPoint: .bottom)
+            Canvas { ctx, size in
+                let horizon = size.height * 0.52
+                // Sun.
+                let sunR = size.height * 0.20
+                let sun = CGRect(x: size.width / 2 - sunR, y: horizon - sunR * 1.6,
+                                 width: sunR * 2, height: sunR * 2)
+                ctx.fill(Path(ellipseIn: sun),
+                         with: .linearGradient(
+                            Gradient(colors: [Color(red: 1, green: 0.95, blue: 0.5),
+                                              Color(red: 1, green: 0.35, blue: 0.45)]),
+                            startPoint: CGPoint(x: sun.midX, y: sun.minY),
+                            endPoint: CGPoint(x: sun.midX, y: sun.maxY)))
+                // Sun scanlines — clip a copy so the base context stays unclipped (GraphicsContext
+                // is a value type; there is no resetClip).
+                var sunCtx = ctx
+                sunCtx.clip(to: Path(ellipseIn: sun))
+                for i in 0..<7 {
+                    let y = sun.minY + sun.height * (0.55 + Double(i) * 0.07)
+                    let bar = CGRect(x: sun.minX, y: y, width: sun.width,
+                                     height: sun.height * (0.012 + Double(i) * 0.006))
+                    sunCtx.fill(Path(bar), with: .color(.black.opacity(0.85)))
+                }
+                // Perspective grid below the horizon.
+                ctx.opacity = 0.55
+                let cx = size.width / 2
+                for col in -10...10 {
+                    var p = Path()
+                    p.move(to: CGPoint(x: cx, y: horizon))
+                    p.addLine(to: CGPoint(x: cx + Double(col) * size.width * 0.11,
+                                          y: size.height))
+                    ctx.stroke(p, with: .color(Color(red: 0.6, green: 0.95, blue: 1)),
+                               lineWidth: 1.5)
+                }
+                var row = horizon
+                var step = size.height * 0.012
+                while row < size.height {
+                    var p = Path()
+                    p.move(to: CGPoint(x: 0, y: row))
+                    p.addLine(to: CGPoint(x: size.width, y: row))
+                    ctx.stroke(p, with: .color(Color(red: 0.6, green: 0.95, blue: 1)),
+                               lineWidth: 1.5)
+                    step *= 1.32
+                    row += step
+                }
+            }
+        }
+        .overlay(alignment: .bottomLeading) {
+            // A small "now playing" chip so the frame reads as live content, not a wallpaper.
+            HStack(spacing: 8) {
+                Image(systemName: "gamecontroller.fill")
+                Text("Streaming from Battlestation")
+                    .font(.system(.callout, weight: .semibold))
+            }
+            .padding(.horizontal, 14).padding(.vertical, 9)
+            .glassBackground(Capsule())
+            .padding(18)
+        }
+        .ignoresSafeArea()
+    }
+
+    /// `PUNKTFUNK_SHOT_HERO=/abs/path.png` → use a real captured frame as the hero background.
+    static var overrideImage: Image? {
+        guard let path = ProcessInfo.processInfo.environment["PUNKTFUNK_SHOT_HERO"],
+              !path.isEmpty, FileManager.default.fileExists(atPath: path) else { return nil }
+        #if os(macOS)
+        guard let ns = NSImage(contentsOfFile: path) else { return nil }
+        return Image(nsImage: ns)
+        #else
+        guard let ui = UIImage(contentsOfFile: path) else { return nil }
+        return Image(uiImage: ui)
+        #endif
+    }
+}
+#endif

clients/apple/Sources/PunktfunkClient/SettingsView.swift

@@ -28,6 +28,9 @@ struct SettingsView: View {
     @AppStorage(DefaultsKey.hudEnabled) private var hudEnabled = true
     @AppStorage(DefaultsKey.hudPlacement) private var hudPlacement = HUDPlacement.topTrailing.rawValue
     @ObservedObject private var gamepads = GamepadManager.shared
+    #if DEBUG && !os(tvOS)
+    @State private var showControllerTest = false
+    #endif
     #if os(macOS)
     @AppStorage(DefaultsKey.speakerUID) private var speakerUID = ""
     @AppStorage(DefaultsKey.micUID) private var micUID = ""
@@ -411,6 +414,11 @@ struct SettingsView: View {
                     Text(option.label).tag(option.tag)
                 }
             }
+            #if DEBUG && !os(tvOS)
+            Button("Test Controller…") { showControllerTest = true }
+                .disabled(gamepads.active == nil)
+                .sheet(isPresented: $showControllerTest) { ControllerTestView() }
+            #endif
         } header: {
             Text("Controllers")
         } footer: {

clients/apple/Sources/PunktfunkKit/DualSenseHID.swift

@@ -0,0 +1,153 @@
+// Raw-HID DualSense rumble for macOS.
+//
+// Apple's GameController/CHHapticEngine path does NOT drive the DualSense's rumble motors on
+// macOS — a documented platform gap: adaptive triggers, lightbar and player LEDs all work
+// (different APIs), but `CHHapticEngine` output never reaches the motors. So we write the motor
+// amplitudes straight into the DualSense HID output report, exactly the way SDL and the Linux
+// `hid-playstation` driver do (the same report that already rumbles this pad on a Linux host).
+//
+// USB (report 0x02, 48 bytes, no CRC) and Bluetooth (report 0x31, 78 bytes, trailing CRC32) are
+// both handled. The App Sandbox permits the raw-HID access via the app's `device.usb` +
+// `device.bluetooth` entitlements, and this coexists with GameController holding the same device
+// (non-seized open). Output-only, so no run-loop scheduling is needed.
+//
+// macOS-only: IOKit HID device access isn't available to apps on iOS/tvOS.
+
+#if os(macOS)
+import Foundation
+import IOKit
+import IOKit.hid
+import os
+
+private let log = Logger(subsystem: "io.unom.punktfunk", category: "gamepad")
+
+/// Opens the first connected Sony DualSense and forwards motor rumble to it over raw HID.
+/// Single-pad model (we forward exactly one controller), so the first match is the right one.
+final class DualSenseHID {
+    private let manager: IOHIDManager
+    private var device: IOHIDDevice?
+    private var bluetooth = false
+    private var closed = false
+
+    private static let vendorSony = 0x054C
+    // DualSense (0x0CE6) and DualSense Edge (0x0DF2). The DualShock 4 uses a different report
+    // layout and is intentionally not handled here.
+    private static let productIDs = [0x0CE6, 0x0DF2]
+
+    /// "USB" or "Bluetooth" — for logs / the debug panel. Valid after a successful `open()`.
+    var transport: String { bluetooth ? "Bluetooth" : "USB" }
+
+    init() {
+        manager = IOHIDManagerCreate(kCFAllocatorDefault, IOOptionBits(kIOHIDOptionsTypeNone))
+    }
+
+    deinit { close() }
+
+    /// Find and open the first connected DualSense. Returns false if none is present or it can't
+    /// be opened (caller then falls back to CoreHaptics).
+    func open() -> Bool {
+        let matches = Self.productIDs.map { pid in
+            [kIOHIDVendorIDKey: Self.vendorSony, kIOHIDProductIDKey: pid] as CFDictionary
+        }
+        IOHIDManagerSetDeviceMatchingMultiple(manager, matches as CFArray)
+        guard IOHIDManagerOpen(manager, IOOptionBits(kIOHIDOptionsTypeNone)) == kIOReturnSuccess else {
+            log.info("rumble: DualSense HID manager open failed — falling back to CoreHaptics")
+            return false
+        }
+        guard let devices = IOHIDManagerCopyDevices(manager) as? Set<IOHIDDevice>,
+              let dev = devices.first
+        else {
+            log.info("rumble: no DualSense HID device found — falling back to CoreHaptics")
+            IOHIDManagerClose(manager, IOOptionBits(kIOHIDOptionsTypeNone))
+            return false
+        }
+        device = dev
+        let transport = IOHIDDeviceGetProperty(dev, kIOHIDTransportKey as CFString) as? String
+        bluetooth = transport?.lowercased().contains("bluetooth") ?? false
+        log.info("rumble: DualSense raw-HID rumble active (transport=\(self.transport, privacy: .public))")
+        return true
+    }
+
+    /// Drive the motors. `low` = left/heavy (low-frequency), `high` = right/light (high-frequency),
+    /// each 0...255. (0, 0) stops.
+    func rumble(low: UInt8, high: UInt8) {
+        guard let dev = device else { return }
+        let report = bluetooth
+            ? Self.bluetoothReport(low: low, high: high)
+            : Self.usbReport(low: low, high: high)
+        let rc = report.withUnsafeBufferPointer { buf in
+            IOHIDDeviceSetReport(
+                dev, kIOHIDReportTypeOutput, CFIndex(report[0]), buf.baseAddress!, buf.count)
+        }
+        if rc != kIOReturnSuccess {
+            log.error("rumble: IOHIDDeviceSetReport failed (0x\(String(format: "%08x", rc), privacy: .public))")
+        }
+    }
+
+    func close() {
+        guard !closed else { return }
+        closed = true
+        if device != nil { rumble(low: 0, high: 0) } // silence the motors before releasing
+        device = nil
+        IOHIDManagerClose(manager, IOOptionBits(kIOHIDOptionsTypeNone))
+    }
+
+    // MARK: - Report builders
+
+    // DualSense effects payload (DS5EffectsState_t / hid-playstation `common`) — offsets relative
+    // to the payload start:
+    //   0  flag0 (enable bits)   2  motor_right (high-freq)   3  motor_left (low-freq)
+    //   1  flag1                 38 flag2 (enhanced enable)
+    // We mirror the Linux driver: flag0 = COMPATIBLE_VIBRATION | HAPTICS_SELECT, flag2 =
+    // COMPATIBLE_VIBRATION2 (the enhanced-firmware path), motors sent directly. valid_flag1 stays
+    // 0 so this rumble-only report leaves the lightbar / triggers / player LEDs (driven by
+    // GameController) untouched.
+    private static func fillEffects(_ data: inout [UInt8], at base: Int, low: UInt8, high: UInt8) {
+        data[base + 0] = 0x03 // COMPATIBLE_VIBRATION (0x01) | HAPTICS_SELECT (0x02)
+        data[base + 2] = high // motor_right
+        data[base + 3] = low // motor_left
+        data[base + 38] = 0x04 // COMPATIBLE_VIBRATION2 (enhanced rumble, firmware ≥ 0x0224)
+    }
+
+    // `usbReport` / `bluetoothReport` / `crc32` are internal (not private) so the unit tests can
+    // pin the exact wire layout against the SDL / hid-playstation spec without a physical pad.
+    static func usbReport(low: UInt8, high: UInt8) -> [UInt8] {
+        var d = [UInt8](repeating: 0, count: 48)
+        d[0] = 0x02 // report id
+        fillEffects(&d, at: 1, low: low, high: high)
+        return d
+    }
+
+    static func bluetoothReport(low: UInt8, high: UInt8) -> [UInt8] {
+        var d = [UInt8](repeating: 0, count: 78)
+        d[0] = 0x31 // report id
+        d[1] = 0x00 // seq/tag (static, as SDL)
+        d[2] = 0x10 // magic
+        fillEffects(&d, at: 3, low: low, high: high)
+        // Trailing CRC32 over a 0xA2 seed byte + the report minus its 4 CRC bytes, little-endian.
+        let crc = Self.crc32(seed: 0xA2, d[0..<(d.count - 4)])
+        d[74] = UInt8(crc & 0xFF)
+        d[75] = UInt8((crc >> 8) & 0xFF)
+        d[76] = UInt8((crc >> 16) & 0xFF)
+        d[77] = UInt8((crc >> 24) & 0xFF)
+        return d
+    }
+
+    /// Standard reflected CRC32 (zlib poly 0xEDB88320, init 0xFFFFFFFF, final XOR) over `seed`
+    /// followed by `bytes` — the DualSense Bluetooth output-report checksum (seed 0xA2). Matches
+    /// SDL's `SDL_crc32`/the kernel's `crc32_le` framing.
+    static func crc32<S: Sequence>(seed: UInt8, _ bytes: S) -> UInt32
+    where S.Element == UInt8 {
+        var crc: UInt32 = 0xFFFF_FFFF
+        func step(_ b: UInt8) {
+            crc ^= UInt32(b)
+            for _ in 0..<8 {
+                crc = (crc & 1) != 0 ? (crc >> 1) ^ 0xEDB8_8320 : crc >> 1
+            }
+        }
+        step(seed)
+        for b in bytes { step(b) }
+        return ~crc
+    }
+}
+#endif

clients/apple/Sources/PunktfunkKit/GamepadFeedback.swift

@@ -50,10 +50,12 @@ private final class FeedbackStopFlag: @unchecked Sendable {
 private final class RumbleRenderer: @unchecked Sendable {
     private let queue = DispatchQueue(label: "io.unom.punktfunk.haptics", qos: .userInteractive)
 
+    /// One actuator's started engine plus the player currently driving it (nil = idle). The
+    /// player is rebuilt per level change — `drive` bakes the target intensity into a fresh
+    /// continuous event rather than scaling a long-lived one with a dynamic parameter.
     private struct Motor {
         let engine: CHHapticEngine
-        let player: CHHapticAdvancedPatternPlayer
-        var playing = false
+        var player: CHHapticAdvancedPatternPlayer?
     }
 
     private var controller: GCController?
@@ -67,11 +69,30 @@ private final class RumbleRenderer: @unchecked Sendable {
     /// Last logged active/silent state — for a one-line transition log, not per-event spam.
     private var wasActive = false
 
-    func retarget(_ c: GCController?) {
+    /// CHHapticEvent sharpness = actuator frequency. A DualSense's voice-coil motors need a
+    /// defined frequency to move at all — an intensity-only event (no sharpness) left them
+    /// silent, while a classic Xbox rotor (which ignores sharpness) rumbled fine. 0.5 is the mid
+    /// value the known-working macOS DualSense rumble implementations use. (Used only on the
+    /// CoreHaptics path — a DualSense on macOS is driven over raw HID instead, see below.)
+    private static let sharpness: Float = 0.5
+
+    #if os(macOS)
+    /// Set when the active pad is a DualSense: its motors are driven over raw HID (CoreHaptics
+    /// does not reach them on macOS — adaptive triggers/lightbar work, rumble is silent). nil for
+    /// every other controller, which keeps the CoreHaptics path.
+    private var dualSenseHID: DualSenseHID?
+    #endif
+
+    /// `onBackend`, if given, is invoked (on the internal queue) with a human-readable name of the
+    /// rumble backend now in use — for the debug controller-test panel.
+    func retarget(_ c: GCController?, onBackend: ((String) -> Void)? = nil) {
         queue.async {
             self.teardown()
+            self.closeHID()
             self.controller = c
             self.broken = false
+            _ = self.openHIDIfDualSense(c)
+            onBackend?(self.backendNote(for: c))
         }
     }
 
@@ -83,22 +104,36 @@ private final class RumbleRenderer: @unchecked Sendable {
                 log.debug(
                     "rumble: \(active ? "active" : "stop", privacy: .public) low=\(lowAmp, privacy: .public) high=\(highAmp, privacy: .public)")
             }
+            // A DualSense on macOS is driven over raw HID; CoreHaptics is the path for every
+            // other pad (and for a DualSense whose HID device could not be opened).
+            if self.hidRumble(low: lowAmp, high: highAmp) { return }
             guard !self.broken else { return }
             if active, self.low == nil, self.high == nil {
                 self.setup()
             }
+            let ok: Bool
             if self.high != nil {
-                self.drive(&self.low, Float(lowAmp) / 65535)
-                self.drive(&self.high, Float(highAmp) / 65535)
+                // Per-handle: low = left/heavy motor, high = right/light — the XInput convention
+                // the wire carries.
+                let okLow = self.drive(&self.low, Float(lowAmp) / 65535)
+                let okHigh = self.drive(&self.high, Float(highAmp) / 65535)
+                ok = okLow && okHigh
             } else {
                 // Combined engine: whichever motor is stronger wins.
-                self.drive(&self.low, Float(max(lowAmp, highAmp)) / 65535)
+                ok = self.drive(&self.low, Float(max(lowAmp, highAmp)) / 65535)
             }
+            // Rebuild on the next nonzero amplitude if an engine errored — and tear down OUTSIDE
+            // the `inout` accesses above, so teardown() never mutates a motor that a `drive` call
+            // still holds an exclusive reference to.
+            if !ok { self.teardown() }
         }
     }
 
     func stop() {
-        queue.sync { self.teardown() }
+        queue.sync {
+            self.teardown()
+            self.closeHID()
+        }
     }
 
     /// Engines per handle when the pad distinguishes them (low = left/heavy motor,
@@ -144,44 +179,51 @@ private final class RumbleRenderer: @unchecked Sendable {
             self?.queue.async { self?.teardown() }
         }
         do {
+            // Start the engine now; the player that actually moves the motor is built per level
+            // change in `drive` (a fresh event baked at the target intensity).
             try engine.start()
-            let event = CHHapticEvent(
-                eventType: .hapticContinuous,
-                parameters: [CHHapticEventParameter(parameterID: .hapticIntensity, value: 1)],
-                relativeTime: 0,
-                duration: TimeInterval(GCHapticDurationInfinite))
-            let player = try engine.makeAdvancedPlayer(with: CHHapticPattern(events: [event], parameters: []))
-            return Motor(engine: engine, player: player)
+            return Motor(engine: engine, player: nil)
         } catch {
             log.warning("haptic engine setup failed (\(locality.rawValue, privacy: .public)): \(error, privacy: .public)")
             return nil
         }
     }
 
-    private func drive(_ motor: inout Motor?, _ amplitude: Float) {
-        guard var m = motor else { return }
+    /// Drive one motor at `amplitude` (0...1) by (re)building a continuous player whose intensity
+    /// is BAKED into the event. On a DualSense this is what actually moves the actuators: a
+    /// fixed-intensity event scaled by a dynamic `.hapticIntensityControl` parameter (the old
+    /// path) drives the iPhone Taptic Engine but is silent on a controller's haptic engine. The
+    /// event carries an explicit sharpness (frequency) so the voice coils respond, and an infinite
+    /// duration so a single host update — the host sends rumble only when the level changes —
+    /// sustains until the next one. Returns false if the engine errored; the caller tears down for
+    /// a rebuild (done outside this `inout` access to avoid an exclusivity violation).
+    private func drive(_ motor: inout Motor?, _ amplitude: Float) -> Bool {
+        guard var m = motor else { return true }
+        // Replace any running player: stop the old, and for a zero level leave the motor idle.
+        try? m.player?.stop(atTime: CHHapticTimeImmediate)
+        m.player = nil
+        guard amplitude > 0 else { motor = m; return true }
         do {
-            if amplitude > 0 {
-                if !m.playing {
-                    try m.player.start(atTime: CHHapticTimeImmediate)
-                    m.playing = true
-                }
-                try m.player.sendParameters(
-                    [CHHapticDynamicParameter(
-                        parameterID: .hapticIntensityControl,
-                        value: amplitude, relativeTime: 0)],
-                    atTime: CHHapticTimeImmediate)
-            } else if m.playing {
-                try m.player.stop(atTime: CHHapticTimeImmediate)
-                m.playing = false
-            }
+            let event = CHHapticEvent(
+                eventType: .hapticContinuous,
+                parameters: [
+                    CHHapticEventParameter(parameterID: .hapticIntensity, value: amplitude),
+                    CHHapticEventParameter(parameterID: .hapticSharpness, value: Self.sharpness),
+                ],
+                relativeTime: 0,
+                duration: TimeInterval(GCHapticDurationInfinite))
+            let player = try m.engine.makeAdvancedPlayer(
+                with: CHHapticPattern(events: [event], parameters: []))
+            try player.start(atTime: CHHapticTimeImmediate)
+            m.player = player
             motor = m
+            return true
         } catch {
             // A transient failure (the engine stopped/reset between its handler firing and now).
-            // Tear down so the next nonzero amplitude rebuilds — do NOT latch rumble off for the
-            // session (that was the old "spotty" behaviour).
+            // Signal a rebuild — do NOT latch rumble off for the session (the old "spotty" bug).
             log.warning("rumble: haptic update failed — rebuilding: \(error, privacy: .public)")
-            teardown()
+            motor = m
+            return false
         }
     }
 
@@ -191,12 +233,56 @@ private final class RumbleRenderer: @unchecked Sendable {
             // (Both properties are non-optional closures on this SDK, so assign no-ops, not nil.)
             m.engine.stoppedHandler = { _ in }
             m.engine.resetHandler = {}
-            try? m.player.stop(atTime: CHHapticTimeImmediate)
+            try? m.player?.stop(atTime: CHHapticTimeImmediate)
             m.engine.stop()
         }
         low = nil
         high = nil
     }
+
+    // MARK: - DualSense raw-HID rumble (macOS)
+    //
+    // On macOS the DualSense's motors aren't reachable through CHHapticEngine, so for a DualSense
+    // we drive them over raw HID (see `DualSenseHID`); every other pad keeps the CoreHaptics path.
+    // All three run on the serial `queue`, like the rest of the renderer state.
+
+    private func openHIDIfDualSense(_ c: GCController?) -> Bool {
+        #if os(macOS)
+        guard let c, c.extendedGamepad is GCDualSenseGamepad else { return false }
+        let hid = DualSenseHID()
+        guard hid.open() else { return false }
+        dualSenseHID = hid
+        return true
+        #else
+        return false
+        #endif
+    }
+
+    /// Drive the DualSense's motors over HID if that's the active backend; false → not a HID pad,
+    /// so the caller uses CoreHaptics. The wire's 0...0xFFFF amplitudes scale to the pad's 0...255.
+    private func hidRumble(low: UInt16, high: UInt16) -> Bool {
+        #if os(macOS)
+        guard let hid = dualSenseHID else { return false }
+        hid.rumble(low: UInt8(low >> 8), high: UInt8(high >> 8))
+        return true
+        #else
+        return false
+        #endif
+    }
+
+    private func closeHID() {
+        #if os(macOS)
+        dualSenseHID?.close()
+        dualSenseHID = nil
+        #endif
+    }
+
+    private func backendNote(for c: GCController?) -> String {
+        #if os(macOS)
+        if let hid = dualSenseHID { return "DualSense HID · \(hid.transport)" }
+        #endif
+        return c == nil ? "—" : "CoreHaptics"
+    }
 }
 
 public final class GamepadFeedback {
@@ -369,3 +455,74 @@ public final class GamepadFeedback {
         return which == 0 ? ds.leftTrigger : ds.rightTrigger
     }
 }
+
+#if DEBUG
+/// Local feedback driver for the Settings → Controllers "Test Controller" panel (DEBUG builds
+/// only). It drives the SAME CoreHaptics rumble renderer and `DualSenseTriggerEffect` path a
+/// live session uses — just aimed at the physically-connected controller instead of the
+/// host→client feedback planes — so rumble, the adaptive triggers, the lightbar and the player
+/// LEDs can be confirmed on-device without a host. Reusing the real renderers is the point:
+/// a passing test exercises the exact code a session runs.
+@MainActor
+public final class ControllerTester: ObservableObject {
+    private let renderer = RumbleRenderer()
+    private weak var controller: GCController?
+
+    /// The rumble backend now in use — "DualSense HID · USB/Bluetooth", "CoreHaptics", or "—" —
+    /// for the test panel to display so it's obvious which path a given pad takes.
+    @Published public private(set) var rumbleBackend = "—"
+
+    public init() {}
+
+    /// Aim the feedback at a controller (nil releases it). Idempotent — safe to call on every
+    /// active-controller change.
+    public func target(_ c: GCController?) {
+        guard c !== controller else { return }
+        controller = c
+        renderer.retarget(c) { [weak self] note in
+            Task { @MainActor in self?.rumbleBackend = note }
+        }
+    }
+
+    /// Drive both motors at 0...1 amplitudes — low = left/heavy, high = right/light — mapped to
+    /// the 0...0xFFFF wire range the session carries, through the real `RumbleRenderer`.
+    public func rumble(low: Float, high: Float) {
+        func u16(_ v: Float) -> UInt16 { UInt16((min(max(v, 0), 1) * 65535).rounded()) }
+        renderer.apply(low: u16(low), high: u16(high))
+    }
+
+    public func stopRumble() { renderer.apply(low: 0, high: 0) }
+
+    /// Replay an adaptive-trigger effect on a DualSense via the real `DualSenseTriggerEffect`
+    /// renderer. `right == false` → L2, `true` → R2. No-op on a non-DualSense pad.
+    public func applyTrigger(_ effect: DualSenseTriggerEffect, right: Bool) {
+        guard let ds = controller?.extendedGamepad as? GCDualSenseGamepad else { return }
+        effect.apply(to: right ? ds.rightTrigger : ds.leftTrigger)
+    }
+
+    public func resetTriggers() {
+        guard let ds = controller?.extendedGamepad as? GCDualSenseGamepad else { return }
+        ds.leftTrigger.setModeOff()
+        ds.rightTrigger.setModeOff()
+    }
+
+    /// Lightbar colour (DualSense / DualShock 4); nil turns it off. No-op without a light.
+    public func setLight(_ color: GCColor?) {
+        controller?.light?.color = color ?? GCColor(red: 0, green: 0, blue: 0)
+    }
+
+    /// Player-indicator LEDs (`.index1`...`.index4`, or `.indexUnset` to clear).
+    public func setPlayerIndex(_ index: GCControllerPlayerIndex) {
+        controller?.playerIndex = index
+    }
+
+    /// Silence every channel and release the controller — call on the panel's disappear.
+    public func stop() {
+        resetTriggers()
+        setPlayerIndex(.indexUnset)
+        setLight(nil)
+        renderer.retarget(nil) // async teardown: stops the motors + drops the controller ref
+        controller = nil
+    }
+}
+#endif

clients/apple/Tests/PunktfunkKitTests/DualSenseHIDTests.swift

@@ -0,0 +1,47 @@
+// Locks the DualSense raw-HID rumble report layout to the SDL / Linux hid-playstation spec.
+// The motors can only be confirmed on a physical pad, but these guard against a silent byte
+// error in the offsets, enable flags, lengths, and the Bluetooth CRC32 — the parts most likely
+// to regress unnoticed. macOS-only (DualSenseHID isn't compiled elsewhere).
+
+#if os(macOS)
+import XCTest
+
+@testable import PunktfunkKit
+
+final class DualSenseHIDTests: XCTestCase {
+    func testUSBReportLayout() {
+        let r = DualSenseHID.usbReport(low: 0xAA, high: 0xBB)
+        XCTAssertEqual(r.count, 48)
+        XCTAssertEqual(r[0], 0x02) // report id
+        XCTAssertEqual(r[1], 0x03) // flag0: COMPATIBLE_VIBRATION | HAPTICS_SELECT
+        XCTAssertEqual(r[2], 0x00) // flag1 (untouched — leaves lightbar/LEDs alone)
+        XCTAssertEqual(r[3], 0xBB) // motor_right = high
+        XCTAssertEqual(r[4], 0xAA) // motor_left  = low
+        XCTAssertEqual(r[39], 0x04) // flag2: COMPATIBLE_VIBRATION2 (payload offset 38 + report id)
+    }
+
+    func testBluetoothReportLayoutAndCRC() {
+        let r = DualSenseHID.bluetoothReport(low: 0xAA, high: 0xBB)
+        XCTAssertEqual(r.count, 78)
+        XCTAssertEqual(r[0], 0x31) // report id
+        XCTAssertEqual(r[1], 0x00) // seq/tag
+        XCTAssertEqual(r[2], 0x10) // magic
+        XCTAssertEqual(r[3], 0x03) // flag0
+        XCTAssertEqual(r[5], 0xBB) // motor_right = high (payload offset 2 + 3-byte BT header)
+        XCTAssertEqual(r[6], 0xAA) // motor_left  = low
+        XCTAssertEqual(r[41], 0x04) // flag2 (payload offset 38 + 3)
+
+        // Trailing CRC32 = standard CRC32 over (0xA2 seed + report[0..<74]), little-endian.
+        let expected = DualSenseHID.crc32(seed: 0xA2, r[0..<74])
+        let stored = UInt32(r[74]) | (UInt32(r[75]) << 8) | (UInt32(r[76]) << 16) | (UInt32(r[77]) << 24)
+        XCTAssertEqual(stored, expected)
+    }
+
+    func testCRC32MatchesStandardCheckVector() {
+        // The canonical CRC32 check value: CRC32("123456789") == 0xCBF43926. Our helper folds a
+        // seed byte in first, so feed seed='1' and the rest — proving poly/reflection/init/final.
+        let crc = DualSenseHID.crc32(seed: UInt8(ascii: "1"), Array("23456789".utf8))
+        XCTAssertEqual(crc, 0xCBF4_3926)
+    }
+}
+#endif

clients/apple/tools/screenshots.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# App Store screenshot driver for the Punktfunk Apple client.
+#
+# Launches the app in "shot mode" (PUNKTFUNK_SHOT_SCENE=<name> → one mock-populated screen,
+# full-bleed; see Sources/PunktfunkClient/Screenshots/) once per scene per device, and lets the OS
+# capture the REAL rendered UI:
+#   • macOS  → `screencapture` of the app's borderless window.
+#   • iOS/iPadOS/tvOS → a booted Simulator + `xcrun simctl io booted screenshot` (native pixels =
+#                       the exact App Store size for that device).
+#
+# The captured pixels are exactly App Store Connect's required sizes:
+#   mac        2880×1800   (a 1× display yields 1440×900 — also accepted)
+#   iphone-6.9 1320×2868   (portrait)  /  2868×1320 (the landscape hero)
+#   ipad-13    2064×2752   (portrait)  /  2752×2064 (the landscape hero)
+#   appletv    1920×1080
+#
+# Requirements:
+#   • macOS target: just the Swift toolchain (`swift build`) + a one-time Screen Recording grant
+#     for your terminal (System Settings → Privacy & Security → Screen Recording).
+#   • iOS/iPadOS/tvOS targets: full Xcode (xcodebuild + Simulators), not just Command Line Tools.
+#
+# Usage:
+#   tools/screenshots.sh all            # every platform this machine can build
+#   tools/screenshots.sh macos          # just macOS
+#   tools/screenshots.sh ios ipad tvos  # specific platforms
+#   OUT=~/Desktop/shots tools/screenshots.sh all
+#   PUNKTFUNK_SHOT_HERO=~/frame.png tools/screenshots.sh ios   # real captured frame for the hero
+#
+# Keep SCENES in sync with ShotScenes.all.
+
+set -euo pipefail
+
+APPLE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$APPLE_DIR"
+
+OUT="${OUT:-$APPLE_DIR/screenshots}"
+BUNDLE_ID="io.unom.punktfunk"
+SCENES=(01-stream 02-hosts 03-pair 04-trust 05-settings)
+SETTLE="${SETTLE:-4}" # seconds to let a scene lay out before capturing
+
+mkdir -p "$OUT"
+
+log()  { printf '\033[1;36m[shots]\033[0m %s\n' "$*"; }
+warn() { printf '\033[1;33m[shots]\033[0m %s\n' "$*" >&2; }
+die()  { printf '\033[1;31m[shots]\033[0m %s\n' "$*" >&2; exit 1; }
+
+require_xcode() {
+  xcrun --find simctl >/dev/null 2>&1 \
+    || die "Full Xcode required for simulator capture (have Command Line Tools only).
+       Install Xcode, then: sudo xcode-select -s /Applications/Xcode.app"
+}
+
+# ---------------------------------------------------------------------------- macOS
+
+shoot_macos() {
+  log "macOS — building (swift build -c release)…"
+  swift build -c release >/dev/null
+  local bin=".build/release/PunktfunkClient"
+  [ -x "$bin" ] || die "build produced no $bin"
+
+  for scene in "${SCENES[@]}"; do
+    local logf; logf="$(mktemp)"
+    PUNKTFUNK_SHOT_SCENE="$scene" "$bin" >"$logf" 2>&1 &
+    local pid=$!
+    # Wait for the window to exist and the scene to settle.
+    local win=""
+    for _ in $(seq 1 50); do
+      win="$(grep -o 'PF_SHOT_WINDOW=[0-9]*' "$logf" | head -1 | cut -d= -f2 || true)"
+      [ -n "$win" ] && grep -q PF_SHOT_READY "$logf" && break
+      sleep 0.2
+    done
+    if [ -z "$win" ]; then
+      kill -9 "$pid" 2>/dev/null || true
+      warn "macOS/$scene: app never reported a window — skipping"; cat "$logf" >&2; continue
+    fi
+    local dest="$OUT/mac-$scene.png"
+    if screencapture -x -o -l"$win" "$dest" 2>/dev/null && [ -s "$dest" ]; then
+      log "macOS/$scene → $dest ($(pixels "$dest"))"
+    else
+      warn "macOS/$scene: screencapture failed — grant your terminal Screen Recording permission
+       (System Settings → Privacy & Security → Screen Recording), then re-run."
+    fi
+    kill -9 "$pid" 2>/dev/null || true
+    rm -f "$logf"
+  done
+}
+
+# ------------------------------------------------------------------ iOS / iPadOS / tvOS
+
+# $1 device-type regex (matches both existing device names and the device-type catalog)
+# $2 scheme  $3 sdk  $4 file prefix  $5 runtime platform (iOS|tvOS — for the create fallback)
+shoot_sim() {
+  require_xcode
+  local match="$1" scheme="$2" sdk="$3" prefix="$4" platform="$5"
+
+  # Reuse an existing device of this type; else create a throwaway one against the newest
+  # available runtime for the platform. CI runners commonly ship a runtime but not every device
+  # (the iPhone 16 Pro Max is absent on ours), so create-on-demand is what makes it reproducible.
+  local udid
+  udid="$(xcrun simctl list devices available | grep -E "$match" | grep -oE '[0-9A-F-]{36}' | head -1 || true)"
+  if [ -z "$udid" ]; then
+    local devtype rt
+    devtype="$(xcrun simctl list devicetypes | grep -E "$match" \
+      | grep -oE 'com\.apple\.CoreSimulator\.SimDeviceType\.[A-Za-z0-9.-]+' | head -1 || true)"
+    rt="$(xcrun simctl list runtimes available | grep -E "^$platform " \
+      | grep -oE 'com\.apple\.CoreSimulator\.SimRuntime\.[A-Za-z0-9.-]+' | tail -1 || true)"
+    if [ -n "$devtype" ] && [ -n "$rt" ]; then
+      udid="$(xcrun simctl create "pf-shot-$prefix" "$devtype" "$rt" 2>/dev/null || true)"
+      [ -n "$udid" ] && log "$prefix — created Simulator $udid ($devtype)"
+    fi
+  fi
+  [ -n "$udid" ] || die "$prefix: no Simulator matching /$match/, and none could be created
+       (needs a $platform runtime + a matching device type — check 'xcrun simctl list')."
+  log "$prefix — Simulator $udid"
+  xcrun simctl boot "$udid" 2>/dev/null || true
+  xcrun simctl bootstatus "$udid" -b >/dev/null 2>&1 || true
+
+  log "$prefix — building ($scheme)…"
+  local dd; dd="$(mktemp -d)"
+  xcodebuild -project Punktfunk.xcodeproj -scheme "$scheme" -configuration Debug \
+    -sdk "$sdk" -destination "id=$udid" -derivedDataPath "$dd" \
+    CODE_SIGNING_ALLOWED=NO build >/dev/null \
+    || die "$prefix: xcodebuild failed"
+  local app; app="$(find "$dd/Build/Products" -maxdepth 2 -name '*.app' -type d | head -1)"
+  [ -n "$app" ] || die "$prefix: no .app built"
+  xcrun simctl install "$udid" "$app"
+
+  for scene in "${SCENES[@]}"; do
+    xcrun simctl terminate "$udid" "$BUNDLE_ID" 2>/dev/null || true
+    SIMCTL_CHILD_PUNKTFUNK_SHOT_SCENE="$scene" \
+      ${PUNKTFUNK_SHOT_HERO:+SIMCTL_CHILD_PUNKTFUNK_SHOT_HERO="$PUNKTFUNK_SHOT_HERO"} \
+      xcrun simctl launch "$udid" "$BUNDLE_ID" >/dev/null
+    sleep "$SETTLE"
+    local dest="$OUT/$prefix-$scene.png"
+    xcrun simctl io "$udid" screenshot "$dest" >/dev/null
+    log "$prefix/$scene → $dest ($(pixels "$dest"))"
+  done
+  xcrun simctl terminate "$udid" "$BUNDLE_ID" 2>/dev/null || true
+  rm -rf "$dd"
+}
+
+pixels() { sips -g pixelWidth -g pixelHeight "$1" 2>/dev/null | awk '/pixel/{print $2}' | paste -sd× -; }
+
+# ---------------------------------------------------------------------------- dispatch
+
+[ $# -gt 0 ] || set -- all
+for target in "$@"; do
+  case "$target" in
+    macos) shoot_macos ;;
+    ios)   shoot_sim 'iPhone 16 Pro Max'   Punktfunk-iOS  iphonesimulator  iphone-6.9 iOS ;;
+    ipad)  shoot_sim 'iPad Pro 13|iPad Pro .*M4|iPad Pro \(13' Punktfunk-iOS iphonesimulator ipad-13 iOS ;;
+    tvos)  shoot_sim 'Apple TV'            Punktfunk-tvOS appletvsimulator appletv    tvOS ;;
+    all)
+      shoot_macos
+      if xcrun --find simctl >/dev/null 2>&1; then
+        shoot_sim 'iPhone 16 Pro Max' Punktfunk-iOS iphonesimulator iphone-6.9 iOS
+        shoot_sim 'iPad Pro 13|iPad Pro .*M4|iPad Pro \(13' Punktfunk-iOS iphonesimulator ipad-13 iOS
+        shoot_sim 'Apple TV' Punktfunk-tvOS appletvsimulator appletv tvOS
+      else
+        warn "Skipping iOS/iPadOS/tvOS — full Xcode not found (Command Line Tools only)."
+      fi
+      ;;
+    *) die "unknown target '$target' (use: all macos ios ipad tvos)" ;;
+  esac
+done
+
+log "Done. Screenshots in $OUT"
+ls -1 "$OUT" 2>/dev/null || true

crates/pf-driver-proto/Cargo.toml

@@ -0,0 +1,20 @@
+# Shared host<->driver binary contract for the punktfunk pf-vdisplay virtual display.
+#
+# Deliberately self-contained (no `*.workspace = true` inheritance, no Windows deps): this crate is a
+# path dependency of BOTH the host workspace (crates/punktfunk-host) AND the out-of-workspace driver
+# workspace (packaging/windows/drivers/), so it must resolve identically from either build graph. It is
+# `no_std` (+ alloc) and platform-neutral; the GUID/LUID are plain integers each side converts to its
+# own OS type. Defining every wire struct ONCE here — with `const` size/offset asserts + bytemuck
+# round-trips — makes host<->driver ABI drift a COMPILE error instead of a silent frame/IOCTL corruption.
+[package]
+name = "pf-driver-proto"
+version = "0.0.1"
+edition = "2021"
+rust-version = "1.82"
+license = "MIT OR Apache-2.0"
+description = "Shared host<->driver binary contract for the punktfunk pf-vdisplay virtual display (control IOCTLs + IDD-push frame transport)."
+publish = false
+
+[dependencies]
+# `min_const_generics`: Pod/Zeroable for `[u8; N]` of any N (the gamepad SHM reserved tails are >32).
+bytemuck = { version = "1.19", features = ["derive", "min_const_generics"] }

crates/pf-driver-proto/src/lib.rs

@@ -0,0 +1,485 @@
+//! Shared binary contract between the punktfunk host and the `pf-vdisplay` IddCx driver.
+//!
+//! Two planes:
+//! * [`control`] — the low-frequency `DeviceIoControl` plane (add/remove a virtual monitor, pin the
+//!   render adapter, keepalive, info, clear-all). Owned, clean, versioned — NOT the SudoVDA ABI.
+//! * [`frame`] — the IDD-push frame transport: the host creates a ring of shared keyed-mutex textures
+//!   (+ a header + a frame-ready event) and the driver opens them and publishes composited frames into
+//!   them. This crate owns the [`frame::SharedHeader`] layout, the [`frame::FrameToken`] packing, the
+//!   `Global\` object-name scheme, and the driver-status codes.
+//!
+//! Both planes were previously hand-duplicated, byte-for-byte, across `idd_push.rs`/`frame_transport.rs`
+//! and `vdisplay/sudovda.rs`/`control.rs` with only "must match" comments guarding them. Defining them
+//! once here — with bytemuck `Pod` derives and `const` size asserts — makes any drift a compile error.
+//!
+//! The GUID and LUID are carried as plain integers; the host converts to `windows::core::GUID` /
+//! `windows::Win32::Foundation::LUID` and the driver to its own bindgen types via the same constants.
+
+#![cfg_attr(not(test), no_std)]
+
+extern crate alloc;
+
+/// Freshly-minted pf-vdisplay device-interface GUID — `{70667664-7044-5350-a1b2-c3d4e5f60001}`.
+/// Deliberately NOT SudoVDA's `{e5bcc234-…}`: we own the driver, so a private interface GUID signals
+/// it and removes any accidental coexistence with a real SudoVDA install. Construct on each side via
+/// `GUID::from_u128(PF_VDISPLAY_INTERFACE_GUID_U128)`.
+pub const PF_VDISPLAY_INTERFACE_GUID_U128: u128 = 0x7066_7664_7044_5350_a1b2_c3d4_e5f6_0001;
+
+/// The interface GUID split into Windows `GUID` fields — `(Data1, Data2, Data3, Data4)` — so the driver
+/// (and host) can build a `windows`/`wdk_sys` `GUID` without re-deriving the byte layout. Standard GUID
+/// layout from the u128: `Data1` = high 32 bits, `Data2`/`Data3` = next two 16-bit groups, `Data4` =
+/// the low 64 bits big-endian. (This crate is `no_std` + provider-agnostic, so it returns the fields
+/// rather than depend on a `GUID` type.)
+#[must_use]
+pub const fn interface_guid_fields() -> (u32, u16, u16, [u8; 8]) {
+    let g = PF_VDISPLAY_INTERFACE_GUID_U128;
+    (
+        (g >> 96) as u32,
+        (g >> 80) as u16,
+        (g >> 64) as u16,
+        (g as u64).to_be_bytes(),
+    )
+}
+
+/// Bumped on any incompatible change to either plane. Exchanged via [`control::IOCTL_GET_INFO`]; host
+/// and driver assert a match at startup so a mismatched pair fails loudly instead of corrupting.
+pub const PROTOCOL_VERSION: u32 = 1;
+
+/// `CTL_CODE(FILE_DEVICE_UNKNOWN = 0x22, func, METHOD_BUFFERED = 0, FILE_ANY_ACCESS = 0)`.
+pub const fn ctl_code(func: u32) -> u32 {
+    (0x22u32 << 16) | (func << 2)
+}
+
+/// The control (`DeviceIoControl`) plane: add/remove a virtual monitor + adapter pin + keepalive.
+pub mod control {
+    use super::ctl_code;
+    use bytemuck::{Pod, Zeroable};
+
+    // Contiguous op space at 0x900 — distinct from SudoVDA's gappy 0x800/0x888/0x8FF numbering.
+    /// Add a virtual monitor at a mode → [`AddReply`]. Input [`AddRequest`].
+    pub const IOCTL_ADD: u32 = ctl_code(0x900);
+    /// Remove a virtual monitor by session id. Input [`RemoveRequest`].
+    pub const IOCTL_REMOVE: u32 = ctl_code(0x901);
+    /// Pin the IddCx render adapter (hybrid-GPU IDD-push). Input [`SetRenderAdapterRequest`].
+    pub const IOCTL_SET_RENDER_ADAPTER: u32 = ctl_code(0x902);
+    /// Keepalive (resets the driver watchdog). No payload.
+    pub const IOCTL_PING: u32 = ctl_code(0x903);
+    /// Version + watchdog handshake → [`InfoReply`]. No input.
+    pub const IOCTL_GET_INFO: u32 = ctl_code(0x904);
+    /// Tear down every virtual monitor (host-startup orphan reap). No payload. First-class op — NOT the
+    /// SudoVDA "send-and-hope-it's-ignored" hack.
+    pub const IOCTL_CLEAR_ALL: u32 = ctl_code(0x905);
+
+    /// `IOCTL_ADD` input. A monotonic `session_id` keys the monitor (the host's refcount manager owns
+    /// collision safety — no more SudoVDA's 16-byte GUID + pid-mangling). The driver advertises this
+    /// mode as preferred; the host still CCD-forces the active mode (the OS activates IDDs at a default).
+    #[repr(C)]
+    #[derive(Clone, Copy, Pod, Zeroable, Debug, PartialEq, Eq)]
+    pub struct AddRequest {
+        pub session_id: u64,
+        pub width: u32,
+        pub height: u32,
+        pub refresh_hz: u32,
+        pub _reserved: u32,
+    }
+
+    /// `IOCTL_ADD` reply: the OS target id + the adapter LUID the IDD landed on (split low/high to
+    /// match `windows` `LUID { LowPart: u32, HighPart: i32 }`).
+    #[repr(C)]
+    #[derive(Clone, Copy, Pod, Zeroable, Debug, PartialEq, Eq)]
+    pub struct AddReply {
+        pub adapter_luid_low: u32,
+        pub adapter_luid_high: i32,
+        pub target_id: u32,
+        pub _reserved: u32,
+    }
+
+    /// `IOCTL_REMOVE` input.
+    #[repr(C)]
+    #[derive(Clone, Copy, Pod, Zeroable, Debug, PartialEq, Eq)]
+    pub struct RemoveRequest {
+        pub session_id: u64,
+    }
+
+    /// `IOCTL_SET_RENDER_ADAPTER` input (the GPU the IddCx swap-chain should render on).
+    #[repr(C)]
+    #[derive(Clone, Copy, Pod, Zeroable, Debug, PartialEq, Eq)]
+    pub struct SetRenderAdapterRequest {
+        pub luid_low: u32,
+        pub luid_high: i32,
+    }
+
+    /// `IOCTL_GET_INFO` reply: the protocol version (asserted against [`super::PROTOCOL_VERSION`]) and
+    /// the watchdog timeout the host must ping within.
+    #[repr(C)]
+    #[derive(Clone, Copy, Pod, Zeroable, Debug, PartialEq, Eq)]
+    pub struct InfoReply {
+        pub protocol_version: u32,
+        pub watchdog_timeout_s: u32,
+    }
+
+    // Layout is load-bearing across the process boundary — pin it. (bytemuck's Pod derive already
+    // rejects any internal padding; these assert the externally-visible sizes too.) The `offset_of!`
+    // asserts additionally catch a SAME-SIZE field reorder, which the size+Pod checks alone miss.
+    const _: () = {
+        use core::mem::{offset_of, size_of};
+
+        assert!(size_of::<AddRequest>() == 24);
+        assert!(offset_of!(AddRequest, session_id) == 0);
+        assert!(offset_of!(AddRequest, width) == 8);
+        assert!(offset_of!(AddRequest, height) == 12);
+        assert!(offset_of!(AddRequest, refresh_hz) == 16);
+
+        assert!(size_of::<AddReply>() == 16);
+        assert!(offset_of!(AddReply, adapter_luid_low) == 0);
+        assert!(offset_of!(AddReply, adapter_luid_high) == 4);
+        assert!(offset_of!(AddReply, target_id) == 8);
+
+        assert!(size_of::<RemoveRequest>() == 8);
+        assert!(offset_of!(RemoveRequest, session_id) == 0);
+
+        assert!(size_of::<SetRenderAdapterRequest>() == 8);
+        assert!(offset_of!(SetRenderAdapterRequest, luid_low) == 0);
+        assert!(offset_of!(SetRenderAdapterRequest, luid_high) == 4);
+
+        assert!(size_of::<InfoReply>() == 8);
+        assert!(offset_of!(InfoReply, protocol_version) == 0);
+        assert!(offset_of!(InfoReply, watchdog_timeout_s) == 4);
+    };
+}
+
+/// The IDD-push frame transport: the host-created shared ring header, the publish token, the names, and
+/// the driver-status codes. The texture ring itself is host-created D3D11 keyed-mutex textures (opened
+/// by name on the driver side); only the *layout/contract* lives here.
+pub mod frame {
+    use alloc::string::String;
+    use bytemuck::{Pod, Zeroable};
+
+    /// Header magic (`"PFVD"` LE). The host stamps it LAST (after the ring textures exist) so the driver
+    /// only attaches to a fully-published ring.
+    pub const MAGIC: u32 = 0x4456_4650;
+    /// Frame-plane version (independent bump of the header layout).
+    pub const VERSION: u32 = 1;
+    /// Ring slots. Headroom so the driver's 0 ms-timeout publish always finds a free slot while the host
+    /// holds one across the convert/copy + the pipelined encode. MUST be identical on both sides — it is,
+    /// because both read this one constant.
+    pub const RING_LEN: u32 = 6;
+
+    /// `driver_status` values the driver writes into the host header (the host logs them on a timeout).
+    pub const DRV_STATUS_NONE: u32 = 0;
+    /// Driver attached to the ring and is publishing.
+    pub const DRV_STATUS_OPENED: u32 = 1;
+    /// Driver could not open the host's textures — render-adapter mismatch (it renders on a different GPU
+    /// than where the host created the ring). `driver_status_detail` carries the HRESULT.
+    pub const DRV_STATUS_TEX_FAIL: u32 = 2;
+    /// Driver has no `ID3D11Device1` to open shared resources.
+    pub const DRV_STATUS_NO_DEVICE1: u32 = 3;
+
+    /// The shared metadata header (host-created, mapped by both sides). Atomic fields (`magic`, `latest`,
+    /// `generation`) are accessed via each side's own atomic view over the mapping; this is the layout.
+    #[repr(C)]
+    #[derive(Clone, Copy, Pod, Zeroable, Debug)]
+    pub struct SharedHeader {
+        pub magic: u32,
+        pub version: u32,
+        /// Bumped by the host on a ring recreate (HDR-mode flip → new texture format/names). The driver
+        /// re-attaches when it changes; a publish carries it so the host rejects a stale-ring publish.
+        pub generation: u32,
+        pub ring_len: u32,
+        pub width: u32,
+        pub height: u32,
+        pub dxgi_format: u32,
+        pub _pad: u32,
+        /// Driver-written after each copy; host loads `Acquire`. See [`FrameToken`].
+        pub latest: u64,
+        pub qpc_pts: u64,
+        /// Driver-written: the adapter the swap-chain actually renders on (mismatch detection).
+        pub driver_render_luid_low: u32,
+        pub driver_render_luid_high: i32,
+        /// Driver-written status (visibility channel — UMDF hides OutputDebugString + the restricted
+        /// token blocks file writes, so this header is how the driver reports state).
+        pub driver_status: u32,
+        pub driver_status_detail: u32,
+    }
+
+    /// The `SharedHeader.latest` publish token: `(generation << 40) | (seq << 8) | slot`.
+    /// `generation` is 24-bit, `seq` 32-bit, `slot` 8-bit. The generation tag lets the host REJECT a
+    /// publish from a stale ring (an old-generation publisher racing a mid-session recreate) so it never
+    /// consumes an unwritten new-ring slot — eliminating the toggle-time garbage frame.
+    #[derive(Clone, Copy, Debug, PartialEq, Eq)]
+    pub struct FrameToken {
+        pub generation: u32,
+        pub seq: u32,
+        pub slot: u8,
+    }
+
+    impl FrameToken {
+        /// Low 24 bits of `generation` are significant (see the field docs).
+        pub const GENERATION_MASK: u32 = 0x00FF_FFFF;
+
+        pub const fn pack(self) -> u64 {
+            (((self.generation & Self::GENERATION_MASK) as u64) << 40)
+                | (((self.seq as u64) & 0xFFFF_FFFF) << 8)
+                | (self.slot as u64)
+        }
+
+        pub const fn unpack(v: u64) -> Self {
+            Self {
+                generation: ((v >> 40) as u32) & Self::GENERATION_MASK,
+                seq: ((v >> 8) & 0xFFFF_FFFF) as u32,
+                slot: (v & 0xFF) as u8,
+            }
+        }
+    }
+
+    /// `Global\pfvd-hdr-<target>` — the shared metadata header mapping name.
+    pub fn header_name(target_id: u32) -> String {
+        alloc::format!("Global\\pfvd-hdr-{target_id}")
+    }
+    /// `Global\pfvd-evt-<target>` — the frame-ready auto-reset event name.
+    pub fn event_name(target_id: u32) -> String {
+        alloc::format!("Global\\pfvd-evt-{target_id}")
+    }
+    /// `Global\pfvd-tex-<target>-<generation>-<slot>` — a ring texture's shared-handle name. The
+    /// generation in the name means a recreate's new textures never collide with the old ring's
+    /// not-yet-released handles.
+    pub fn texture_name(target_id: u32, generation: u32, slot: u32) -> String {
+        alloc::format!("Global\\pfvd-tex-{target_id}-{generation}-{slot}")
+    }
+
+    // Size + per-field offsets are load-bearing: both sides access these via raw atomic views over the
+    // mapping, so a same-size field reorder would silently corrupt. Pin every offset. The `_pad` after
+    // `dxgi_format` is what 8-aligns the `u64 latest` at offset 32 — assert that too.
+    const _: () = {
+        use core::mem::{offset_of, size_of};
+
+        assert!(size_of::<SharedHeader>() == 64);
+        assert!(offset_of!(SharedHeader, magic) == 0);
+        assert!(offset_of!(SharedHeader, version) == 4);
+        assert!(offset_of!(SharedHeader, generation) == 8);
+        assert!(offset_of!(SharedHeader, ring_len) == 12);
+        assert!(offset_of!(SharedHeader, width) == 16);
+        assert!(offset_of!(SharedHeader, height) == 20);
+        assert!(offset_of!(SharedHeader, dxgi_format) == 24);
+        assert!(offset_of!(SharedHeader, _pad) == 28);
+        assert!(offset_of!(SharedHeader, latest) == 32);
+        assert!(offset_of!(SharedHeader, qpc_pts) == 40);
+        assert!(offset_of!(SharedHeader, driver_render_luid_low) == 48);
+        assert!(offset_of!(SharedHeader, driver_render_luid_high) == 52);
+        assert!(offset_of!(SharedHeader, driver_status) == 56);
+        assert!(offset_of!(SharedHeader, driver_status_detail) == 60);
+    };
+}
+
+/// Gamepad shared-memory layouts (host ↔ the UMDF gamepad drivers `pf_xusb` / `pf_dualsense`).
+///
+/// These were hand-duplicated as `OFF_*`/`SHM_*` constants in `inject/{gamepad,dualsense}_windows.rs`
+/// and (as bare literals — `*view.add(140)`) in the standalone `xusb-driver`/`dualsense-driver`
+/// workspaces, guarded only by "must match" comments — the top ABI-drift hazard the audit flagged
+/// (`design/windows-host-rewrite.md` §2.7). Owning them here with `Pod` derives + `offset_of!`
+/// asserts makes a one-sided edit a compile error.
+///
+/// The host creates the section (privileged, permissive DACL so the restricted WUDFHost token can
+/// open it) and the driver maps it. Layout only; the section itself is host-created shared memory.
+pub mod gamepad {
+    use alloc::string::String;
+    use bytemuck::{Pod, Zeroable};
+
+    /// XUSB section magic — the exact u32 the shipped host + `pf_xusb` driver compare (loosely "PFXU").
+    pub const XUSB_MAGIC: u32 = 0x5558_4650;
+    /// Pad section magic — the exact u32 the shipped host + `pf_dualsense` driver compare (loosely
+    /// "PFDS"). (Note: the two magics happen to use opposite byte-order mnemonics in the legacy code;
+    /// only the u32 value is the contract.)
+    pub const PAD_MAGIC: u32 = 0x5046_4453;
+
+    /// `device_type` selector the `pf_dualsense` driver reads to pick its HID identity. The section is
+    /// zeroed, so `0` = DualSense is the default; one driver serves either identity.
+    pub const DEVTYPE_DUALSENSE: u8 = 0;
+    /// `device_type` = DualShock 4 (`VID_054C&PID_09CC` HID identity).
+    pub const DEVTYPE_DUALSHOCK4: u8 = 1;
+
+    /// `Global\pfxusb-shm-<index>` — the virtual Xbox 360 (XInput) shared section.
+    pub fn xusb_shm_name(index: u8) -> String {
+        alloc::format!("Global\\pfxusb-shm-{index}")
+    }
+    /// `Global\pfds-shm-<index>` — the virtual DualSense / DualShock 4 shared section.
+    pub fn pad_shm_name(index: u8) -> String {
+        alloc::format!("Global\\pfds-shm-{index}")
+    }
+
+    /// Virtual Xbox 360 (XInput) shared section (64 B). The host writes the XInput state (a bumped
+    /// `packet` number + buttons/triggers/sticks in XInput conventions); the driver answers
+    /// `XInputGetState`. The driver writes force-feedback (`XInputSetState`) into `rumble_*`, bumping
+    /// `rumble_seq`, which the host relays to the client.
+    #[repr(C)]
+    #[derive(Clone, Copy, Pod, Zeroable, Debug)]
+    pub struct XusbShm {
+        pub magic: u32,
+        /// XInput `dwPacketNumber` — bumped by the host on every state change.
+        pub packet: u32,
+        pub buttons: u16,
+        pub left_trigger: u8,
+        pub right_trigger: u8,
+        pub thumb_lx: i16,
+        pub thumb_ly: i16,
+        pub thumb_rx: i16,
+        pub thumb_ry: i16,
+        pub _reserved0: u32,
+        /// Bumped by the driver on a new force-feedback packet.
+        pub rumble_seq: u32,
+        pub rumble_large: u8,
+        pub rumble_small: u8,
+        pub _reserved1: [u8; 34],
+    }
+
+    /// Virtual DualSense / DualShock 4 shared section (256 B). The host writes the `0x01`-style HID
+    /// input report into `input`; the driver feeds it to game `READ_REPORT`s and publishes a game's
+    /// `0x02` output (rumble / lightbar / player-LEDs / adaptive triggers) into `output`, bumping
+    /// `out_seq`. `device_type` selects the HID identity ([`DEVTYPE_DUALSENSE`] / [`DEVTYPE_DUALSHOCK4`]).
+    #[repr(C)]
+    #[derive(Clone, Copy, Pod, Zeroable, Debug)]
+    pub struct PadShm {
+        pub magic: u32,
+        pub _reserved0: u32,
+        /// Input report region (host-written; the codec's report is <= 64 B — see
+        /// `inject::dualsense_proto::DS_INPUT_REPORT_LEN`). The region spans `magic`+pad .. `out_seq`.
+        pub input: [u8; 64],
+        /// Bumped by the driver when it publishes a new `output` report.
+        pub out_seq: u32,
+        /// Output report region (driver-written): rumble / lightbar / player-LEDs / adaptive triggers.
+        pub output: [u8; 64],
+        /// HID identity selector — see [`DEVTYPE_DUALSENSE`] / [`DEVTYPE_DUALSHOCK4`].
+        pub device_type: u8,
+        pub _reserved1: [u8; 115],
+    }
+
+    // Offsets are the wire contract the shipped drivers already read by hand — pin every one. A failing
+    // assert here means the struct no longer matches the historical `OFF_*` layout (host) / `view.add(N)`
+    // literal (driver) and must be fixed before either side switches to the type.
+    const _: () = {
+        use core::mem::{offset_of, size_of};
+
+        assert!(size_of::<XusbShm>() == 64);
+        assert!(offset_of!(XusbShm, magic) == 0);
+        assert!(offset_of!(XusbShm, packet) == 4);
+        assert!(offset_of!(XusbShm, buttons) == 8);
+        assert!(offset_of!(XusbShm, left_trigger) == 10);
+        assert!(offset_of!(XusbShm, right_trigger) == 11);
+        assert!(offset_of!(XusbShm, thumb_lx) == 12);
+        assert!(offset_of!(XusbShm, thumb_ly) == 14);
+        assert!(offset_of!(XusbShm, thumb_rx) == 16);
+        assert!(offset_of!(XusbShm, thumb_ry) == 18);
+        assert!(offset_of!(XusbShm, rumble_seq) == 24);
+        assert!(offset_of!(XusbShm, rumble_large) == 28);
+        assert!(offset_of!(XusbShm, rumble_small) == 29);
+
+        assert!(size_of::<PadShm>() == 256);
+        assert!(offset_of!(PadShm, magic) == 0);
+        assert!(offset_of!(PadShm, input) == 8);
+        assert!(offset_of!(PadShm, out_seq) == 72);
+        assert!(offset_of!(PadShm, output) == 76);
+        assert!(offset_of!(PadShm, device_type) == 140);
+    };
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use bytemuck::Zeroable;
+
+    #[test]
+    fn frame_token_roundtrips() {
+        for (g, s, slot) in [
+            (1u32, 0u32, 0u8),
+            (5, 12_345, 3),
+            (frame::FrameToken::GENERATION_MASK, 0xFFFF_FFFF, 5),
+            (0, 1, 255),
+        ] {
+            let t = frame::FrameToken {
+                generation: g,
+                seq: s,
+                slot,
+            };
+            assert_eq!(frame::FrameToken::unpack(t.pack()), t);
+        }
+    }
+
+    #[test]
+    fn frame_token_packing_matches_legacy_layout() {
+        // The legacy code packed (gen<<40)|(seq<<8)|slot by hand; lock the bit positions.
+        let t = frame::FrameToken {
+            generation: 7,
+            seq: 42,
+            slot: 3,
+        };
+        assert_eq!(t.pack(), (7u64 << 40) | (42u64 << 8) | 3u64);
+    }
+
+    #[test]
+    fn shared_header_is_pod_and_64_bytes() {
+        let mut h = frame::SharedHeader::zeroed();
+        h.magic = frame::MAGIC;
+        h.width = 5120;
+        h.height = 1440;
+        let bytes = bytemuck::bytes_of(&h);
+        assert_eq!(bytes.len(), 64);
+        let back: frame::SharedHeader = *bytemuck::from_bytes(bytes);
+        assert_eq!(back.magic, frame::MAGIC);
+        assert_eq!(back.width, 5120);
+        assert_eq!(back.height, 1440);
+    }
+
+    #[test]
+    fn control_structs_roundtrip_through_bytes() {
+        let req = control::AddRequest {
+            session_id: 0xDEAD_BEEF_CAFE_F00D,
+            width: 3840,
+            height: 2160,
+            refresh_hz: 120,
+            _reserved: 0,
+        };
+        let bytes = bytemuck::bytes_of(&req);
+        assert_eq!(bytes.len(), 24);
+        assert_eq!(*bytemuck::from_bytes::<control::AddRequest>(bytes), req);
+    }
+
+    #[test]
+    fn names_are_stable() {
+        assert_eq!(frame::header_name(10), "Global\\pfvd-hdr-10");
+        assert_eq!(frame::event_name(10), "Global\\pfvd-evt-10");
+        assert_eq!(frame::texture_name(10, 3, 5), "Global\\pfvd-tex-10-3-5");
+    }
+
+    #[test]
+    fn gamepad_names_and_magics_are_stable() {
+        assert_eq!(gamepad::xusb_shm_name(0), "Global\\pfxusb-shm-0");
+        assert_eq!(gamepad::pad_shm_name(2), "Global\\pfds-shm-2");
+        // Lock the exact u32 magics the shipped host/drivers use (inject/{gamepad,dualsense}_windows.rs).
+        assert_eq!(gamepad::XUSB_MAGIC, 0x5558_4650);
+        assert_eq!(gamepad::PAD_MAGIC, 0x5046_4453);
+    }
+
+    #[test]
+    fn ctl_codes_are_contiguous_and_distinct() {
+        assert_eq!(control::IOCTL_ADD, ctl_code(0x900));
+        let all = [
+            control::IOCTL_ADD,
+            control::IOCTL_REMOVE,
+            control::IOCTL_SET_RENDER_ADAPTER,
+            control::IOCTL_PING,
+            control::IOCTL_GET_INFO,
+            control::IOCTL_CLEAR_ALL,
+        ];
+        for (i, a) in all.iter().enumerate() {
+            for b in &all[i + 1..] {
+                assert_ne!(a, b);
+            }
+        }
+    }
+
+    #[test]
+    fn guid_is_not_sudovda() {
+        const SUDOVDA: u128 = 0xE5BC_C234_1E0C_418A_A0D4_EF8B_7501_414D;
+        assert_ne!(PF_VDISPLAY_INTERFACE_GUID_U128, SUDOVDA);
+    }
+}

crates/punktfunk-core/src/quic.rs

@@ -1454,11 +1454,16 @@ pub mod endpoint {
     /// close, while a genuinely dead peer is still detected within `MAX_IDLE`.
     fn stream_transport() -> Arc<quinn::TransportConfig> {
         use std::time::Duration;
-        const MAX_IDLE: Duration = Duration::from_secs(20);
+        // 8s idle (was 20s): a vanished client is declared dead within 8s instead of 20, so its
+        // session tears down promptly — which the Windows IDD-push path needs so a RECONNECT recreates
+        // a fresh virtual monitor (a reused monitor's IddCx swap-chain dies) instead of joining the
+        // still-lingering old session. Active sessions are unaffected: video keeps the connection live,
+        // and the 4s keep-alive holds it open through quiet control periods.
+        const MAX_IDLE: Duration = Duration::from_secs(8);
         const KEEP_ALIVE: Duration = Duration::from_secs(4);
         let mut t = quinn::TransportConfig::default();
         t.max_idle_timeout(Some(
-            quinn::IdleTimeout::try_from(MAX_IDLE).expect("20s is a valid QUIC idle timeout"),
+            quinn::IdleTimeout::try_from(MAX_IDLE).expect("8s is a valid QUIC idle timeout"),
         ));
         t.keep_alive_interval(Some(KEEP_ALIVE));
         Arc::new(t)

crates/punktfunk-host/Cargo.toml

@@ -25,6 +25,14 @@ aes-gcm = "0.10"
 cbc = { version = "0.1", features = ["alloc"] }
 rand = "0.8"
 hex = "0.4"
+# Cover-art delivery in the game library: encode Lutris's local JPEGs into `data:` URLs and decode
+# the Epic launcher's base64 `catcache.bin`. Cross-platform (Linux Lutris art + Windows Epic art).
+base64 = "0.22"
+# Blocking HTTP for the library cover-art warmer (no-auth GOG api.gog.com + Xbox displaycatalog),
+# run on a background thread off the hot path. `ureq` is small + sync (no tokio here) and bundles
+# webpki roots (no system cert dependency). Cross-platform so the fetch/parse code is compiled +
+# checked everywhere even though only the Windows GOG/Xbox providers need it today.
+ureq = "2"
 rcgen = { version = "0.13", default-features = false, features = ["aws_lc_rs", "pem"] }
 x509-parser = "0.16"
 axum-server = { version = "0.7", features = ["tls-rustls"] }
@@ -85,6 +93,10 @@ wayland-scanner = "0.31"
 wayland-backend = "0.3"
 # Parse `pw-dump` JSON to find gamescope's PipeWire node (gamescope backend).
 serde_json = "1"
+# Read the Lutris library DB (`pga.db`) for the Lutris store provider. `bundled` vendors + compiles
+# SQLite (cc, already needed for ffmpeg/opus) so there's no system libsqlite3 runtime dependency —
+# clean for the deb/rpm/flatpak packaging. Opened read-only/immutable (Lutris may hold it open).
+rusqlite = { version = "0.40", features = ["bundled"] }
 # Builds/validates the xkb keymap uploaded to the virtual keyboard + tracks modifier state.
 xkbcommon = "0.8"
 # The safe `opus` crate is stereo-only; surround (5.1/7.1) needs the libopus *multistream*
@@ -116,7 +128,13 @@ libloading = "0.8"
 windows = { version = "0.62", features = [
     "Win32_Foundation",
     "Win32_Security",
+    # ConvertStringSecurityDescriptorToSecurityDescriptorW — the SDDL on the virtual-DualSense
+    # shared-memory section (inject/dualsense_windows.rs) so the UMDF host can open it.
+    "Win32_Security_Authorization",
     "Win32_Devices_DeviceAndDriverInstallation",
+    # SwDeviceCreate/SwDeviceClose — the per-session virtual-DualSense devnode
+    # (inject/dualsense_windows.rs).
+    "Win32_Devices_Enumeration_Pnp",
     "Win32_Devices_Display",
     "Win32_Storage_FileSystem",
     "Win32_System_IO",
@@ -149,7 +167,7 @@ windows = { version = "0.62", features = [
     "Win32_System_LibraryLoader",
     # VirtualProtect — for the inline patch of the win32u GPU-preference shim (Apollo's MinHook port:
     # the hybrid-GPU output-reparenting hook that keeps Desktop Duplication stable on a 4090+iGPU box).
-    # See capture/dxgi.rs `install_gpu_pref_hook`. No trampoline (we fully replace the fn) → no detour
+    # See capture/windows/dxgi.rs `install_gpu_pref_hook`. No trampoline (we fully replace the fn) → no detour
     # crate / no C length-disassembler dep; a 12-byte absolute-jmp prologue patch suffices.
     "Win32_System_Memory",
     # Per-monitor-v2 DPI awareness — IDXGIOutput5::DuplicateOutput1 (the modern capture path Apollo
@@ -163,21 +181,37 @@ windows = { version = "0.62", features = [
 # handler / ServiceManager install). Wraps the Win32 service API; the supervision loop itself uses
 # the `windows` crate above.
 windows-service = "0.7"
+# Read the GOG.com install registry (HKLM\SOFTWARE\WOW6432Node\GOG.com\Games) for the GOG store
+# provider — ergonomic + correct-by-construction vs. hand-rolled Reg* FFI for subkey enumeration.
+winreg = "0.56"
+# Parse each Xbox/Game-Pass game's MicrosoftGame.config (GDK manifest XML) for the Xbox store
+# provider — a small read-only DOM is all we need (Identity/Executable/ShellVisuals/StoreId).
+roxmltree = "0.21"
 # Software H.264 encoder (GPU-less path + NVENC fallback). The default `source` feature statically
 # compiles OpenH264 (BSD-2) — no system lib, builds on MSVC; nasm on PATH adds the SIMD fast path.
 openh264 = "0.9"
 # WASAPI loopback audio capture (default render endpoint -> 48 kHz stereo f32 for the Opus path).
 wasapi = "0.23"
-# Virtual Xbox 360 gamepad via ViGEmBus (the uinput-xpad analogue) — driver installed separately.
-# `unstable_xtarget_notification` exposes the rumble/LED back-channel (the game's force-feedback →
-# `request_notification`), the analogue of the Linux uinput EV_FF read path.
-vigem-client = { version = "0.1", features = ["unstable_xtarget_notification"] }
+# Virtual Xbox 360 gamepad: the in-tree XUSB companion UMDF driver (packaging/windows/xusb-driver),
+# driven over shared memory from inject/windows/gamepad_windows.rs — no ViGEmBus dependency.
 # NVENC hardware encoder (NVENC SDK, D3D11 input). The SDK pins `cudarc` with
 # `cuda-version-from-build-system` (a build-time CUDA-toolkit probe); its `ci-check` feature switches
 # cudarc to `dynamic-loading` (loads nvcuda.dll at runtime — nothing needed at build), which is how
 # the crate builds on docs.rs/CI. We enable it so the GPU-less VM/CI compiles; the DirectX NVENC path
 # never calls CUDA at runtime, so the pinned CUDA bindings version is irrelevant.
 nvidia-video-codec-sdk = { version = "0.4", features = ["ci-check"], optional = true }
+# AMD (AMF) + Intel (QSV) hardware encode on Windows via libavcodec — the analogue of the Linux
+# VAAPI backend (`src/encode/ffmpeg_win.rs`). Optional + behind the `amf-qsv` feature because it
+# link-imports the FFmpeg libs at build time (needs a `FFMPEG_DIR` with the AMF/QSV encoders — the
+# same BtbN gpl-shared tree the Windows client uses) and pulls the shared `avcodec/avutil/...` DLLs
+# at runtime. `ffmpeg-sys-next` auto-detects the FFmpeg version (7.x/avcodec-61 or 8.x/62).
+ffmpeg-next = { version = "8", optional = true }
+# Shared host<->driver wire contract for the pf-vdisplay IddCx virtual-display backend
+# (vdisplay/pf_vdisplay.rs): the control-plane IOCTL codes + `#[repr(C)] Pod` request/reply structs,
+# defined ONCE so host<->driver ABI drift is a compile error. `bytemuck` serializes those structs
+# to/from the DeviceIoControl byte buffers.
+pf-driver-proto = { path = "../pf-driver-proto" }
+bytemuck = { version = "1.19", features = ["derive"] }
 
 [features]
 # NVENC hardware encode (Windows). OFF by default: it pulls the NVENC SDK, and the host then needs
@@ -185,3 +219,7 @@ nvidia-video-codec-sdk = { version = "0.4", features = ["ci-check"], optional =
 # time — i.e. `nvencodeapi.lib` from the NVIDIA Video Codec SDK (or an import lib generated from
 # nvEncodeAPI64.dll) on the linker path. Build the GPU host with `--features nvenc`.
 nvenc = ["dep:nvidia-video-codec-sdk"]
+# AMD/Intel hardware encode on Windows (AMF/QSV via ffmpeg-next). OFF by default: it needs a
+# `FFMPEG_DIR` (BtbN gpl-shared, includes `*_amf`/`*_qsv`) at build time and bundles the FFmpeg
+# DLLs at runtime. Build the all-vendor GPU host with `--features nvenc,amf-qsv`.
+amf-qsv = ["dep:ffmpeg-next"]

crates/punktfunk-host/src/audio.rs

@@ -88,6 +88,8 @@ pub fn open_virtual_mic(_channels: u32) -> Result<Box<dyn VirtualMic>> {
 #[cfg(target_os = "linux")]
 mod linux;
 #[cfg(target_os = "windows")]
+#[path = "audio/windows/wasapi_cap.rs"]
 mod wasapi_cap;
 #[cfg(target_os = "windows")]
+#[path = "audio/windows/wasapi_mic.rs"]
 mod wasapi_mic;

crates/punktfunk-host/src/audio/windows/wasapi_mic.rs

@@ -13,6 +13,9 @@
 //! when the client isn't talking. WASAPI objects are `!Send`, so they live entirely on that thread
 //! (mirrors `WasapiLoopbackCapturer`).
 
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it.
+#![deny(clippy::undocumented_unsafe_blocks)]
+
 use super::{VirtualMic, SAMPLE_RATE};
 use anyhow::{anyhow, Context, Result};
 use std::collections::VecDeque;
@@ -154,6 +157,13 @@ fn find_or_install_device() -> Result<wasapi::Device> {
         Ok(d) => Ok(d),
         Err(e) => {
             tracing::info!("no virtual mic device present — attempting auto-install");
+            // SAFETY: `try_install_virtual_mic` is `unsafe` only because it `LoadLibraryExW`s
+            // `newdev.dll` and calls `DiInstallDriverW` through a `transmute`d function pointer;
+            // calling it imposes no extra precondition here (it takes no args and aliases nothing).
+            // Its internal contract holds: the `DiInstall` type matches the documented
+            // `BOOL DiInstallDriverW(HWND, PCWSTR, DWORD, PBOOL)` ABI, and it passes a
+            // NUL-terminated UTF-16 INF path with null/zero optional args. Invoked once on the
+            // dedicated mic thread.
             if unsafe { try_install_virtual_mic() } {
                 find_device()
             } else {

crates/punktfunk-host/src/capture.rs

@@ -2,6 +2,10 @@
 //! CPU-copy fallback (the portal delivers a CPU buffer; the encoder uploads it to the GPU
 //! internally). Zero-copy dmabuf→NVENC import is deferred (plan §9 risk).
 
+// Every unsafe block in this module tree carries a `// SAFETY:` proof; enforce it (unsafe-proof
+// program). As a parent module this also covers the child modules (capture::windows/linux::*).
+#![deny(clippy::undocumented_unsafe_blocks)]
+
 use anyhow::Result;
 
 /// Packed pixel layout of a [`CapturedFrame`]. The ScreenCast portal negotiates the
@@ -44,6 +48,49 @@ impl PixelFormat {
     }
 }
 
+/// What a Windows capturer should produce, resolved **once** per session and passed **into**
+/// [`capture_virtual_output`] (Goal-1 stage 5, plan §2.3/§5). Passing the format in is what lets a
+/// capturer stop re-deriving the encode backend itself — it kills the
+/// `capture/dxgi.rs → encode::windows_resolved_backend()` back-reference (the highest-severity coupling:
+/// capture and encode could otherwise disagree on whether frames are GPU-resident). Neutral type; the
+/// Linux portal capturer ignores it (it negotiates its own format with PipeWire).
+#[derive(Clone, Copy, Debug)]
+pub struct OutputFormat {
+    /// Produce GPU-resident D3D11 frames (zero-copy for a GPU encoder — NVENC/AMF/QSV) rather than CPU
+    /// staging. `false` **only** for the GPU-less software encoder.
+    pub gpu: bool,
+    /// HDR: the capturer converts to 10-bit (IDD-push FP16 → `Rgb10a2`; the DDA secure-desktop HDR hint).
+    /// `false` = 8-bit SDR.
+    pub hdr: bool,
+}
+
+impl OutputFormat {
+    /// Resolve the output format for an entry point that doesn't build a full [`SessionPlan`]
+    /// (`crate::session_plan`) — the GameStream + spike paths: `gpu` from the resolved encode backend,
+    /// `hdr` as given. The native punktfunk/1 path uses `SessionPlan::output_format()` instead (it already
+    /// resolved the encoder), so neither path makes a capturer re-derive it.
+    pub fn resolve(hdr: bool) -> Self {
+        OutputFormat {
+            gpu: gpu_encode(),
+            hdr,
+        }
+    }
+}
+
+/// True if the resolved encode backend produces GPU frames (anything but the software encoder). The single
+/// source for [`OutputFormat::resolve`]'s `gpu`; on Linux always true (the portal/VAAPI/CUDA path is GPU).
+#[cfg(target_os = "windows")]
+pub(crate) fn gpu_encode() -> bool {
+    !matches!(
+        crate::encode::windows_resolved_backend(),
+        crate::encode::WindowsBackend::Software
+    )
+}
+#[cfg(not(target_os = "windows"))]
+pub(crate) fn gpu_encode() -> bool {
+    true
+}
+
 /// A captured frame. [`format`](Self::format)/dimensions describe the pixels regardless of
 /// where they live — [`payload`](Self::payload) is either a CPU buffer (the spike/fallback path)
 /// or a GPU buffer already on the device (the zero-copy path, plan §9).
@@ -142,6 +189,16 @@ pub trait Capturer: Send {
     fn hdr_meta(&self) -> Option<punktfunk_core::quic::HdrMeta> {
         None
     }
+
+    /// How many frames the encode loop may keep in flight (submitted but not yet polled) before it
+    /// blocks. `1` (the default) is the synchronous loop: capture → submit → poll-blocks, so the
+    /// per-frame wall time is `capture+convert + encode`. A capturer that hands a fresh output texture
+    /// per frame (so the encode of N reads a different texture than the convert of N+1 writes) can return
+    /// `>1` to PIPELINE: the loop submits N+1 before polling N, overlapping the convert/copy on the 3D
+    /// engine with the NVENC-ASIC encode of the prior frame, dropping per-frame wall toward `max(...)`.
+    fn pipeline_depth(&self) -> usize {
+        1
+    }
 }
 
 /// A deterministic moving test pattern (BGRx). Lets the spike exercise the encode → file →
@@ -302,7 +359,14 @@ pub fn open_portal_monitor() -> Result<Box<dyn Capturer>> {
 /// [`crate::vdisplay::VirtualDisplay`] backend. The captured size is the size the output was
 /// created at — native, no scaling.
 #[cfg(target_os = "linux")]
-pub fn capture_virtual_output(vout: crate::vdisplay::VirtualOutput) -> Result<Box<dyn Capturer>> {
+pub fn capture_virtual_output(
+    vout: crate::vdisplay::VirtualOutput,
+    _want: OutputFormat,
+    _capture: crate::session_plan::CaptureBackend,
+) -> Result<Box<dyn Capturer>> {
+    // The Linux host stays 8-bit (HDR is blocked upstream) and the portal negotiates its own format, so
+    // the `OutputFormat` is unused here; the capture backend is always the portal (the `CaptureBackend`
+    // arg is a Windows-only dispatch — ignored here).
     linux::PortalCapturer::from_virtual_output(vout).map(|c| Box::new(c) as Box<dyn Capturer>)
 }
 
@@ -313,11 +377,16 @@ pub fn capture_virtual_output(vout: crate::vdisplay::VirtualOutput) -> Result<Bo
 /// compiled and comes back the moment the flag is unset.
 #[cfg(target_os = "windows")]
 pub(crate) fn wgc_disabled() -> bool {
-    std::env::var_os("PUNKTFUNK_NO_WGC").is_some()
+    crate::config::config().no_wgc
 }
 
 #[cfg(target_os = "windows")]
-pub fn capture_virtual_output(vout: crate::vdisplay::VirtualOutput) -> Result<Box<dyn Capturer>> {
+pub fn capture_virtual_output(
+    vout: crate::vdisplay::VirtualOutput,
+    want: OutputFormat,
+    capture: crate::session_plan::CaptureBackend,
+) -> Result<Box<dyn Capturer>> {
+    use crate::session_plan::CaptureBackend;
     let target = vout.win_capture.clone().ok_or_else(|| {
         anyhow::anyhow!(
             "SudoVDA target not yet an active display (needs a WDDM GPU to activate it)"
@@ -325,16 +394,39 @@ pub fn capture_virtual_output(vout: crate::vdisplay::VirtualOutput) -> Result<Bo
     })?;
     let pref = vout.preferred_mode;
     let keep = vout.keepalive;
+    // P2 direct frame push (kill DDA): consume frames straight from the pf-vdisplay driver's shared
+    // ring — no Desktop Duplication, no win32u reparenting hook. Resolved once in the `SessionPlan`
+    // (was re-derived from `config().idd_push` here); `IddPush` takes the keepalive (owns the virtual
+    // display) so there's no fall-through.
+    if capture == CaptureBackend::IddPush {
+        // Recreate the monitor + ring per session (fix-teardown): a FRESH monitor reliably gets a
+        // working IddCx swap-chain, whereas a REUSED monitor's swap-chain dies after ~2 sessions and
+        // the host can't revive it. The driver's recreate crash (target id resolved to 0) is fixed by
+        // stamping target_id onto the monitor context. The ring is always FP16 (the driver composes
+        // the IDD in FP16); `want_hdr` selects the per-frame conversion (FP16 → Rgb10a2 vs Bgra).
+        // If IDD-push can't open OR the driver doesn't attach to the ring within a few seconds (e.g. a
+        // hybrid-GPU render mismatch), fall back to DDA so the session is NEVER left black (audit §5.1).
+        // `open()` hands the keepalive back on failure so DDA can take ownership of the virtual display.
+        match idd_push::IddPushCapturer::open(target.clone(), pref, want.hdr, keep) {
+            Ok(c) => return Ok(Box::new(c) as Box<dyn Capturer>),
+            Err((e, keep)) => {
+                tracing::warn!(
+                    error = %format!("{e:#}"),
+                    "IDD-push open/attach failed — falling back to DDA"
+                );
+                return dxgi::DuplCapturer::open(target, pref, keep, want.gpu, false)
+                    .map(|c| Box::new(c) as Box<dyn Capturer>);
+            }
+        }
+    }
     // WGC (Windows.Graphics.Capture) is the default: it captures the COMPOSED desktop including the
     // overlay/independent-flip planes DXGI Desktop Duplication misses (the frozen-HDR-animation bug),
     // and has no ACCESS_LOST-on-overlay churn. DDA stays available via PUNKTFUNK_CAPTURE=dda and is
     // the secure-desktop (lock/UAC) fallback (WGC can't capture those). `keep` is moved into the
-    // chosen backend (it owns the SudoVDA keepalive), so there's no open-time auto-fallback.
-    let backend = std::env::var("PUNKTFUNK_CAPTURE")
-        .unwrap_or_default()
-        .to_ascii_lowercase();
-    if backend == "dda" || backend == "dxgi" || wgc_disabled() {
-        return dxgi::DuplCapturer::open(target, pref, keep, false)
+    // chosen backend (it owns the SudoVDA keepalive), so there's no open-time auto-fallback. The
+    // backend choice (`dda`/`dxgi`/`PUNKTFUNK_NO_WGC` → DDA, else WGC) is now resolved once in the plan.
+    if capture == CaptureBackend::Dda {
+        return dxgi::DuplCapturer::open(target, pref, keep, want.gpu, false)
             .map(|c| Box::new(c) as Box<dyn Capturer>);
     }
     // WGC default, with a watchdog'd DDA fallback. WGC's Direct3D11CaptureFramePool::CreateFreeThreaded
@@ -345,6 +437,11 @@ pub fn capture_virtual_output(vout: crate::vdisplay::VirtualOutput) -> Result<Bo
     // DDA is the safety net (+ the secure-desktop path). The encode thread is set MTA so the WGC
     // objects built on the watchdog thread (also MTA) are usable here; the keepalive is handed to WGC
     // only on success, else to DDA. A hung watchdog thread is abandoned (holds no keepalive).
+    // SAFETY: `RoInitialize` is a combase FFI call that initializes the WinRT apartment for the calling
+    // thread. It takes the `RO_INIT_MULTITHREADED` enum by value and borrows no memory, so there is no
+    // pointer/lifetime/aliasing obligation; it is safe on any thread and idempotent — a second call on a
+    // thread already in a compatible apartment returns S_FALSE / RPC_E_CHANGED_MODE, which we discard.
+    // Runs on the encode thread that goes on to use the WGC (WinRT) objects built by the watchdog thread.
     unsafe {
         let _ = windows::Win32::System::WinRT::RoInitialize(
             windows::Win32::System::WinRT::RO_INIT_MULTITHREADED,
@@ -364,31 +461,45 @@ pub fn capture_virtual_output(vout: crate::vdisplay::VirtualOutput) -> Result<Bo
         }
         Ok(Err(e)) => {
             tracing::warn!(error = %format!("{e:#}"), "WGC open failed — falling back to DDA");
-            dxgi::DuplCapturer::open(target, pref, keep, false)
+            dxgi::DuplCapturer::open(target, pref, keep, want.gpu, false)
                 .map(|c| Box::new(c) as Box<dyn Capturer>)
         }
         Err(_) => {
             tracing::warn!("WGC open timed out (CreateFreeThreaded hang on the virtual display) — falling back to DDA");
-            dxgi::DuplCapturer::open(target, pref, keep, false)
+            dxgi::DuplCapturer::open(target, pref, keep, want.gpu, false)
                 .map(|c| Box::new(c) as Box<dyn Capturer>)
         }
     }
 }
 
 #[cfg(not(any(target_os = "linux", target_os = "windows")))]
-pub fn capture_virtual_output(_vout: crate::vdisplay::VirtualOutput) -> Result<Box<dyn Capturer>> {
+pub fn capture_virtual_output(
+    _vout: crate::vdisplay::VirtualOutput,
+    _want: OutputFormat,
+    _capture: crate::session_plan::CaptureBackend,
+) -> Result<Box<dyn Capturer>> {
     anyhow::bail!("virtual-output capture requires Linux or Windows")
 }
 
+// Goal-1 stage 6: the Windows backends live under `capture/windows/`, the Linux one under `capture/linux/`
+// (`#[path]` keeps the module names flat, so every `crate::capture::*` path is unchanged).
 #[cfg(target_os = "windows")]
+#[path = "capture/windows/composed_flip.rs"]
 pub mod composed_flip;
 #[cfg(target_os = "windows")]
+#[path = "capture/windows/desktop_watch.rs"]
 pub mod desktop_watch;
 #[cfg(target_os = "windows")]
+#[path = "capture/windows/dxgi.rs"]
 pub mod dxgi;
+#[cfg(target_os = "windows")]
+#[path = "capture/windows/idd_push.rs"]
+pub mod idd_push;
 #[cfg(target_os = "linux")]
 mod linux;
 #[cfg(target_os = "windows")]
+#[path = "capture/windows/wgc.rs"]
 pub mod wgc;
 #[cfg(target_os = "windows")]
+#[path = "capture/windows/wgc_relay.rs"]
 pub mod wgc_relay;

crates/punktfunk-host/src/capture/linux/mod.rs

@@ -17,6 +17,9 @@
 //! instead of leaking it to process exit. The portal thread (when used) still parks on its zbus
 //! connection until process exit.
 
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
+#![deny(clippy::undocumented_unsafe_blocks)]
+
 use super::{CapturedFrame, Capturer, DmabufFrame, FramePayload, PixelFormat};
 use anyhow::{anyhow, Context, Result};
 use std::os::fd::OwnedFd;
@@ -498,6 +501,12 @@ mod pipewire {
 
     impl DmabufMap {
         fn new(fd: i32, len: usize) -> Option<DmabufMap> {
+            // SAFETY: a null `addr` lets the kernel choose the mapping address; `fd` is a caller-owned
+            // dmabuf/MemFd fd, valid for the duration of this call, and `len` is the requested map length.
+            // `mmap` reads no Rust memory — it installs a fresh PROT_READ/MAP_SHARED page mapping and
+            // returns its base (or MAP_FAILED, checked below before `DmabufMap` adopts it). The returned
+            // region is a brand-new VMA, so it aliases no live Rust object, and it keeps the underlying
+            // object mapped independently of `fd` (which may be closed after this returns).
             let ptr = unsafe {
                 libc::mmap(
                     std::ptr::null_mut(),
@@ -514,6 +523,11 @@ mod pipewire {
 
     impl Drop for DmabufMap {
         fn drop(&mut self) {
+            // SAFETY: `self.ptr`/`self.len` are exactly the base+length of a successful `mmap` in
+            // `DmabufMap::new` (constructed only when `ptr != MAP_FAILED`). This `DmabufMap` uniquely owns
+            // that mapping and `drop` runs once, so `munmap` releases a live mapping exactly once — no
+            // double-unmap. Every `&[u8]` derived from the mapping is bounded by this `DmabufMap`'s
+            // lifetime, so no borrow outlives the unmap.
             unsafe {
                 libc::munmap(self.ptr, self.len);
             }
@@ -719,6 +733,14 @@ mod pipewire {
         if !ud.active.load(Ordering::Relaxed) {
             return;
         }
+        // SAFETY: `spa_buf` is the `*mut spa_buffer` of the PipeWire buffer we dequeued and still hold for
+        // this `.process` callback (not requeued until after `consume_frame` returns), so it is live. The
+        // block null-checks `spa_buf`, requires `n_datas != 0`, and null-checks the `datas` array pointer
+        // before forming any slice. `(*spa_buf).datas` points to `n_datas` libspa `spa_data` structs, and
+        // `pw::spa::buffer::Data` is `#[repr(transparent)]` over `spa_data` (the same cast
+        // `Buffer::datas_mut` performs — see the function doc), so the pointer cast + length describe
+        // exactly that array, in bounds. The PipeWire loop is single-threaded and owns the buffer here, so
+        // this `&mut` slice is the only reference to it (no aliasing/data race).
         let datas: &mut [pw::spa::buffer::Data] = unsafe {
             if spa_buf.is_null() || (*spa_buf).n_datas == 0 || (*spa_buf).datas.is_null() {
                 &mut []
@@ -783,6 +805,10 @@ mod pipewire {
                         // dup the fd so it survives the SPA buffer recycle — the encode thread
                         // imports it. (Content stability across the brief map+CSC window relies on
                         // the compositor's buffer-pool depth, like any zero-copy capture.)
+                        // SAFETY: `datas[0].fd()` is the dmabuf fd owned by the live PipeWire buffer (valid
+                        // for this callback). `fcntl(fd, F_DUPFD_CLOEXEC, 0)` reads only the integer fd,
+                        // touches no Rust memory, and returns a fresh independent CLOEXEC duplicate (or -1).
+                        // The original stays owned by PipeWire; the dup is a new fd we own (checked >= 0).
                         let dup =
                             unsafe { libc::fcntl(datas[0].fd() as i32, libc::F_DUPFD_CLOEXEC, 0) };
                         if dup >= 0 {
@@ -796,6 +822,10 @@ mod pipewire {
                                 pts_ns,
                                 format: fmt,
                                 payload: FramePayload::Dmabuf(DmabufFrame {
+                                    // SAFETY: `dup` is the fresh fd `fcntl(F_DUPFD_CLOEXEC)` just returned
+                                    // (checked `dup >= 0`); nothing else owns it, so `OwnedFd` takes sole
+                                    // ownership and closes it exactly once on drop — no alias, no
+                                    // double-close.
                                     fd: unsafe { OwnedFd::from_raw_fd(dup) },
                                     fourcc,
                                     modifier: ud.modifier,
@@ -930,6 +960,11 @@ mod pipewire {
         // cleanly if the real buffer is genuinely too small. MemPtr buffers (no fd) are same-process —
         // trust `d.data()`.
         let fd_len = if raw_fd > 0 {
+            // SAFETY: `libc::stat` is a C plain-old-data struct for which all-zero is a valid value, so
+            // `mem::zeroed()` is a sound initializer. `raw_fd` is the buffer's fd (`> 0` checked here) and
+            // valid for this callback; `fstat` writes metadata into `&mut st`, a live, aligned,
+            // correctly-sized stack `stat` that outlives the synchronous call. `st.st_size` is read only
+            // after the return value is confirmed `== 0`. `st` is a fresh local, so nothing aliases it.
             unsafe {
                 let mut st: libc::stat = std::mem::zeroed();
                 (libc::fstat(raw_fd as i32, &mut st) == 0 && st.st_size > 0)
@@ -946,6 +981,14 @@ mod pipewire {
             match DmabufMap::new(raw_fd as i32, map_len) {
                 Some(m) => {
                     _mapping = m;
+                    // SAFETY: `_mapping` is the `DmabufMap` just stored; its `ptr`/`len` come from a
+                    // successful `mmap` of `map_len` PROT_READ bytes, so `ptr` is non-null, page-aligned,
+                    // and the VMA is one allocated object of `len` bytes valid for reads. In the common
+                    // path `map_len == fd_len` (the fd's real size from `fstat`), so the mapping spans the
+                    // whole object; the de-pad copy below is further bounded by the `offset <= buf.len()`
+                    // and `needed > avail` guards. The `&[u8]` borrows `_mapping`, which lives to the end
+                    // of `consume_frame`, so the slice never outlives the mapping, and the memory is only
+                    // read here, so there is no aliasing/mutation.
                     Some(unsafe {
                         std::slice::from_raw_parts(_mapping.ptr as *const u8, _mapping.len)
                     })
@@ -1177,24 +1220,43 @@ mod pipewire {
                     // Latest-frame-only (OBS pattern): Mutter delivers buffers in bursts and
                     // recycles its pool; an older queued buffer carries a STALE frame. Drain all
                     // queued buffers, requeue the older ones, keep only the newest.
+                    // SAFETY: `stream` is the live stream PipeWire passes into this `.process` callback on
+                    // the loop thread, where `pw_stream_dequeue_buffer` is the documented call. It returns
+                    // a `*mut pw_buffer` owned by the stream (or null when the queue is drained),
+                    // null-checked before any use. The loop is single-threaded, so no concurrent access.
                     let mut newest = unsafe { stream.dequeue_raw_buffer() };
                     if newest.is_null() {
                         return;
                     }
                     let mut drained = 1u32;
                     loop {
+                        // SAFETY: same stream/loop-thread contract as the dequeue above; each call returns
+                        // the next stream-owned `*mut pw_buffer` or null (null-checked before use).
                         let next = unsafe { stream.dequeue_raw_buffer() };
                         if next.is_null() {
                             break;
                         }
+                        // SAFETY: `newest` is a non-null `*mut pw_buffer` previously dequeued from this same
+                        // stream and not yet requeued; `pw_stream_queue_buffer` hands ownership back to the
+                        // stream. We immediately overwrite `newest = next`, so the requeued pointer is never
+                        // touched again (no use-after-requeue). Loop thread, single-threaded.
                         unsafe { stream.queue_raw_buffer(newest) };
                         newest = next;
                         drained += 1;
                     }
+                    // SAFETY: `newest` is the non-null buffer we still own (dequeued, not requeued);
+                    // `.buffer` is a `*mut spa_buffer` field libpipewire populated. This is a single field
+                    // load through a valid pointer — no mutation or aliasing.
                     let spa_buf = unsafe { (*newest).buffer };
 
                     // Inspect the newest buffer's header + first chunk for the diagnostic and the
                     // CORRUPTED skip. SPA_META_Header is optional — `hdr` may be null.
+                    // SAFETY: `spa_buf` is the `*mut spa_buffer` of the buffer we still hold.
+                    // `spa_buffer_find_meta_data` scans that buffer's metadata array for a `SPA_META_Header`
+                    // of at least `size_of::<spa_meta_header>()` bytes and returns a pointer into the held
+                    // buffer's metadata (or null). The size argument matches the struct the result is cast
+                    // to, and the pointer stays valid as long as the buffer is held (until requeue). Null is
+                    // handled below.
                     let hdr = unsafe {
                         spa::sys::spa_buffer_find_meta_data(
                             spa_buf,
@@ -1205,11 +1267,20 @@ mod pipewire {
                     let hdr_flags = if hdr.is_null() {
                         0u32
                     } else {
+                        // SAFETY: reached only when `hdr` is non-null; it points to a `spa_meta_header`
+                        // inside the live buffer's metadata (returned for a size >=
+                        // `size_of::<spa_meta_header>()`, so `.flags` is in bounds). A single field read
+                        // while the buffer is still held.
                         unsafe { (*hdr).flags }
                     };
                     // First data chunk's size + flags (used for the diagnostic + CORRUPTED check)
                     // and its data type (a dmabuf legitimately reports chunk size 0, so the size-0
                     // stale skip only applies to mappable SHM buffers).
+                    // SAFETY: every dereference is guarded in order before any field read — `spa_buf`
+                    // non-null, `n_datas > 0`, the `datas` (`*mut spa_data`) array non-null, and the first
+                    // element's `chunk` (`*mut spa_chunk`) non-null. `d0` is that first `spa_data` and `c`
+                    // its chunk; reading `(*d0).type_`, `(*c).size`, `(*c).flags` are in-bounds field loads
+                    // of libspa structs inside the buffer we still hold. Single-threaded loop, no mutation.
                     let (chunk_size, chunk_flags, is_dmabuf) = unsafe {
                         if !spa_buf.is_null()
                             && (*spa_buf).n_datas > 0
@@ -1246,11 +1317,17 @@ mod pipewire {
                                 "capture: skipped a stale CORRUPTED/cursor buffer (GNOME)"
                             );
                         }
+                        // SAFETY: `newest` is the non-null buffer we own (dequeued, never requeued on this
+                        // skip path); hand it back to the stream exactly once and return without touching it
+                        // again. Loop thread inside `.process`.
                         unsafe { stream.queue_raw_buffer(newest) };
                         return;
                     }
 
                     consume_frame(ud, spa_buf);
+                    // SAFETY: `consume_frame` has finished reading `spa_buf` (and the `datas` borrows derived
+                    // from `newest`), so requeuing the owned `newest` exactly once here is sound — no
+                    // use-after-requeue. Loop thread inside `.process`.
                     unsafe { stream.queue_raw_buffer(newest) };
                 }));
                 if outcome.is_err() {

crates/punktfunk-host/src/capture/windows/composed_flip.rs

@@ -15,6 +15,9 @@
 //! composed while a session is live). Effectiveness can be build/driver-dependent; gated by
 //! `PUNKTFUNK_FORCE_COMPOSED` (default ON; set =0 to disable).
 
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
+#![deny(clippy::undocumented_unsafe_blocks)]
+
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::Arc;
 use windows::core::w;
@@ -48,6 +51,10 @@ impl ForceComposedFlip {
         let st = stop.clone();
         std::thread::Builder::new()
             .name("composed-flip".into())
+            // SAFETY: `run` is this module's `unsafe fn` (it owns a desktop+window lifecycle via Win32
+            // FFI); it takes ownership of `st` (the stop `Arc<AtomicBool>`) and has no caller-side memory
+            // precondition. It is designed to own its thread for its whole duration — exactly the
+            // dedicated `composed-flip` thread spawned here.
             .spawn(move || unsafe { run(st) })
             .ok()?;
         tracing::info!("force-composed-flip overlay started (Winlogon-aware)");
@@ -62,6 +69,9 @@ impl Drop for ForceComposedFlip {
 }
 
 extern "system" fn wndproc(hwnd: HWND, msg: u32, wp: WPARAM, lp: LPARAM) -> LRESULT {
+    // SAFETY: this is the window procedure the OS invokes with the window's own `hwnd` and a real
+    // message `(msg, wp, lp)`. `DefWindowProcW` performs default processing for exactly those
+    // parameters (all passed straight through by value); it borrows no Rust memory and is synchronous.
     unsafe { DefWindowProcW(hwnd, msg, wp, lp) }
 }
 

crates/punktfunk-host/src/capture/windows/desktop_watch.rs

@@ -1,5 +1,5 @@
 //! Input-desktop watcher (Windows) — the authoritative "normal vs secure desktop" signal for the
-//! two-process secure-desktop design (docs/windows-secure-desktop.md).
+//! two-process secure-desktop design (design/archive/windows-secure-desktop.md).
 //!
 //! Windows switches the *input desktop* to "Winlogon" (the secure desktop) for UAC elevation, the
 //! lock screen and the login screen, and back to "Default" for the normal session. WGC captures only
@@ -7,6 +7,9 @@
 //! desktop's NAME (WTS session notifications miss UAC entirely, so the name is the reliable signal)
 //! and publishes it as an atomic the capture mux + input path read.
 
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
+#![deny(clippy::undocumented_unsafe_blocks)]
+
 use std::sync::atomic::{AtomicBool, AtomicU8, Ordering};
 use std::sync::Arc;
 use std::time::Duration;
@@ -33,6 +36,10 @@ impl DesktopWatcher {
         // mux) sees the real state immediately. Otherwise a session that begins already on the secure
         // desktop (e.g. a reconnect to a locked box) would read DESKTOP_NORMAL for the first poll
         // interval and relay one stale normal-desktop frame — the "flash of the login screen" bug.
+        // SAFETY: `is_secure_desktop` is this module's `unsafe fn` — unsafe only because it calls Win32
+        // desktop FFI (`OpenInputDesktop`/`GetUserObjectInformationW`/`CloseDesktop`), with no caller
+        // precondition; it opens, names, and closes the input-desktop handle internally and is safe to
+        // call from any thread (here, on the thread running `DesktopWatcher::start`).
         let initial = if unsafe { is_secure_desktop() } {
             DESKTOP_SECURE
         } else {
@@ -53,6 +60,9 @@ impl DesktopWatcher {
                 let mut candidate = initial;
                 let mut stable = 0u32;
                 while !st.load(Ordering::Relaxed) {
+                    // SAFETY: same as in `start` — `is_secure_desktop` is self-contained Win32 desktop
+                    // FFI with no caller precondition, called here on the dedicated `desktop-watch`
+                    // polling thread.
                     let v = if unsafe { is_secure_desktop() } {
                         DESKTOP_SECURE
                     } else {

crates/punktfunk-host/src/capture/windows/dxgi.rs

@@ -7,6 +7,9 @@
 //! Validates only with a real GPU + an *activated* SudoVDA monitor (`DuplicateOutput` needs a live
 //! WDDM output). Compiles on the GPU-less VM; the pure helpers are unit-tested there.
 
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
+#![deny(clippy::undocumented_unsafe_blocks)]
+
 use super::{CapturedFrame, Capturer, FramePayload, PixelFormat};
 use anyhow::{anyhow, bail, Context, Result};
 use std::ffi::c_void;
@@ -69,7 +72,12 @@ pub struct D3d11Frame {
     pub texture: ID3D11Texture2D,
     pub device: ID3D11Device,
 }
-// COM pointers, used only from the single owning thread.
+// 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
+// created free-threaded (`make_device` passes no `D3D11_CREATE_DEVICE_SINGLETHREADED`), so handing
+// ownership of the frame to another thread — the capture→encode handoff — and releasing it there is
+// sound. The value is moved, never aliased (no `Sync`), so there is no concurrent use of the
+// single-threaded immediate context.
 unsafe impl Send for D3d11Frame {}
 
 pub fn pack_luid(luid: LUID) -> i64 {
@@ -202,41 +210,35 @@ pub(crate) unsafe fn make_device(
     Ok((device, context))
 }
 
-/// Apollo-style GPU scheduling-priority hardening (Sunshine `display_base.cpp:599-709`). On a
-/// GPU-saturated game our capture+encode process is starved of GPU time slices — NVENC sits ~idle but
-/// `lock_bitstream` waits ~20 ms for our context to be scheduled. Elevating the PROCESS GPU scheduling
-/// priority class (the strong cross-process lever — far more effective than `SetGPUThreadPriority`
-/// alone, which we measured as no help) lets our brief encode preempt the game. Uses HIGH, NOT
-/// realtime: realtime on NVIDIA + HAGS can freeze/crash NVENC (Apollo downgrades it for exactly this).
-/// Runs once per process; best-effort. `PUNKTFUNK_GPU_PRIORITY_CLASS = off|normal|high|realtime`
-/// (default high).
-fn elevate_process_gpu_priority() {
-    use std::sync::Once;
-    static ONCE: Once = Once::new();
-    ONCE.call_once(|| unsafe {
-        use windows::core::{s, PCWSTR};
+/// Resolve the configured GPU scheduling-priority class from `PUNKTFUNK_GPU_PRIORITY_CLASS`
+/// (`off|normal|high|realtime`, default high). `None` = leave it at the OS default (the `off` opt-out).
+/// D3DKMT_SCHEDULINGPRIORITYCLASS: IDLE 0, BELOW_NORMAL 1, NORMAL 2, ABOVE_NORMAL 3, HIGH 4, REALTIME 5.
+fn configured_gpu_priority_class() -> Option<i32> {
+    match std::env::var("PUNKTFUNK_GPU_PRIORITY_CLASS")
+        .ok()
+        .as_deref()
+    {
+        Some("off") => None,
+        Some("normal") => Some(2),
+        Some("realtime") => Some(5),
+        _ => Some(4), // HIGH — safe on NVIDIA+HAGS (realtime can freeze NVENC)
+    }
+}
+
+/// Enable SE_INC_BASE_PRIORITY on the CURRENT process token (best-effort) — the kernel gates the
+/// HIGH/REALTIME GPU scheduling-priority bump on it. Held by SYSTEM/Administrators; a UAC-FILTERED
+/// token (what `CreateProcessAsUserW` hands the WGC helper) does NOT have it, which is why the helper
+/// can't elevate itself and the SYSTEM host stamps the class onto it cross-process instead (see
+/// [`set_child_gpu_priority_class`]).
+unsafe fn enable_inc_base_priority() {
+    use windows::core::PCWSTR;
     use windows::Win32::Foundation::{CloseHandle, HANDLE, LUID};
     use windows::Win32::Security::{
         AdjustTokenPrivileges, LookupPrivilegeValueW, LUID_AND_ATTRIBUTES,
-            SE_INC_BASE_PRIORITY_NAME, SE_PRIVILEGE_ENABLED, TOKEN_ADJUST_PRIVILEGES,
-            TOKEN_PRIVILEGES, TOKEN_QUERY,
+        SE_INC_BASE_PRIORITY_NAME, SE_PRIVILEGE_ENABLED, TOKEN_ADJUST_PRIVILEGES, TOKEN_PRIVILEGES,
+        TOKEN_QUERY,
     };
-        use windows::Win32::System::LibraryLoader::{GetProcAddress, LoadLibraryA};
     use windows::Win32::System::Threading::{GetCurrentProcess, OpenProcessToken};
-
-        // D3DKMT_SCHEDULINGPRIORITYCLASS: IDLE 0, BELOW_NORMAL 1, NORMAL 2, ABOVE_NORMAL 3, HIGH 4,
-        // REALTIME 5.
-        let prio: i32 = match std::env::var("PUNKTFUNK_GPU_PRIORITY_CLASS").ok().as_deref() {
-            Some("off") => {
-                tracing::info!("GPU process scheduling priority class left at default (off)");
-                return;
-            }
-            Some("normal") => 2,
-            Some("realtime") => 5,
-            _ => 4, // HIGH — safe on NVIDIA+HAGS (realtime can freeze NVENC)
-        };
-
-        // 1. Enable SE_INC_BASE_PRIORITY so the kernel permits the GPU priority bump.
     let mut token = HANDLE::default();
     if OpenProcessToken(
         GetCurrentProcess(),
@@ -269,29 +271,97 @@ fn elevate_process_gpu_priority() {
         }
         let _ = CloseHandle(token);
     }
+}
 
-        // 2. D3DKMTSetProcessSchedulingPriorityClass via gdi32 (no stable windows-rs binding).
-        if let Ok(gdi32) = LoadLibraryA(s!("gdi32.dll")) {
-            if let Some(p) = GetProcAddress(gdi32, s!("D3DKMTSetProcessSchedulingPriorityClass")) {
+/// Call `gdi32!D3DKMTSetProcessSchedulingPriorityClass(process, prio)` (no stable windows-rs binding —
+/// loaded by name). Returns the NTSTATUS (0 = success) or `None` if the export can't be resolved. The
+/// CALLING process must hold SE_INC_BASE_PRIORITY ([`enable_inc_base_priority`]) for HIGH/REALTIME; the
+/// kernel checks the caller's privilege whether the target is self or a child we created.
+unsafe fn d3dkmt_set_scheduling_priority_class(
+    process: windows::Win32::Foundation::HANDLE,
+    prio: i32,
+) -> Option<i32> {
+    use windows::core::s;
+    use windows::Win32::Foundation::HANDLE;
+    use windows::Win32::System::LibraryLoader::{GetProcAddress, LoadLibraryA};
+    let gdi32 = LoadLibraryA(s!("gdi32.dll")).ok()?;
+    let p = GetProcAddress(gdi32, s!("D3DKMTSetProcessSchedulingPriorityClass"))?;
     type SetPrio = unsafe extern "system" fn(HANDLE, i32) -> i32;
     let f: SetPrio = std::mem::transmute(p);
-                let st = f(GetCurrentProcess(), prio);
-                if st == 0 {
-                    tracing::info!(
+    Some(f(process, prio))
+}
+
+/// Apollo-style GPU scheduling-priority hardening (Sunshine `display_base.cpp:599-709`). On a
+/// GPU-saturated game our capture+encode process is starved of GPU time slices — NVENC sits ~idle but
+/// `lock_bitstream` waits ~20 ms for our context to be scheduled. Elevating the PROCESS GPU scheduling
+/// priority class (the strong cross-process lever — far more effective than `SetGPUThreadPriority`
+/// alone, which we measured as no help) lets our brief encode preempt the game. Uses HIGH, NOT
+/// realtime: realtime on NVIDIA + HAGS can freeze/crash NVENC (Apollo downgrades it for exactly this).
+/// Runs once per process; best-effort. `PUNKTFUNK_GPU_PRIORITY_CLASS = off|normal|high|realtime`
+/// (default high). NOTE: in the SYSTEM-host + user-session-helper deployment this self-set NO-OPs in
+/// the helper (filtered token), so the host also sets it on the helper via [`set_child_gpu_priority_class`].
+fn elevate_process_gpu_priority() {
+    use std::sync::Once;
+    static ONCE: Once = Once::new();
+    // SAFETY: the closure calls two of this module's `unsafe fn`s — `enable_inc_base_priority`
+    // (adjusts the current-process token; it has no caller precondition and builds all its FFI args
+    // locally) and `d3dkmt_set_scheduling_priority_class` (loads gdi32 by name and calls the export).
+    // The latter requires `process` to be a valid process handle; `GetCurrentProcess()` returns the
+    // current-process pseudo-handle, which is always valid and needs no close. Runs once via
+    // `Once::call_once`; no raw pointers are dereferenced here.
+    ONCE.call_once(|| unsafe {
+        use windows::Win32::System::Threading::GetCurrentProcess;
+        let Some(prio) = configured_gpu_priority_class() else {
+            tracing::info!("GPU process scheduling priority class left at default (off)");
+            return;
+        };
+        enable_inc_base_priority();
+        match d3dkmt_set_scheduling_priority_class(GetCurrentProcess(), prio) {
+            Some(0) => tracing::info!(
                 priority_class = prio,
                 "GPU process scheduling priority class set (2=normal 4=high 5=realtime)"
-                    );
-                } else {
-                    tracing::warn!(
+            ),
+            Some(st) => tracing::warn!(
                 status = format!("0x{st:08X}"),
                 "D3DKMTSetProcessSchedulingPriorityClass failed (run as admin/SYSTEM for GPU priority)"
-                    );
-                }
-            }
+            ),
+            None => tracing::warn!("D3DKMTSetProcessSchedulingPriorityClass export not found"),
         }
     });
 }
 
+/// Set the GPU scheduling-priority class of ANOTHER process we created — the WGC capture+encode helper
+/// in the interactive user session. The helper is spawned with the user's UAC-FILTERED token, which
+/// lacks SE_INC_BASE_PRIORITY, so its own [`elevate_process_gpu_priority`] silently no-ops and NVENC
+/// gets starved under a GPU-saturating game (the "240→40 fps in-game collapse"). The SYSTEM host DOES
+/// hold the privilege, so it stamps the class onto the child's process handle right after spawn — the
+/// process-level class applies to GPU contexts the child creates afterwards. Best-effort; logged.
+/// `PUNKTFUNK_GPU_PRIORITY_CLASS=off` disables it (same knob as the self path).
+///
+/// # Safety
+/// `process` must be a valid handle to a process we own with at least PROCESS_SET_INFORMATION access
+/// (the just-created helper, `PROCESS_INFORMATION::hProcess`).
+pub(crate) unsafe fn set_child_gpu_priority_class(process: windows::Win32::Foundation::HANDLE) {
+    let Some(prio) = configured_gpu_priority_class() else {
+        return;
+    };
+    enable_inc_base_priority(); // the SYSTEM host holds SE_INC_BASE_PRIORITY; the helper does not
+    match d3dkmt_set_scheduling_priority_class(process, prio) {
+        Some(0) => tracing::info!(
+            priority_class = prio,
+            "WGC helper GPU scheduling priority class set cross-process from the SYSTEM host \
+             (2=normal 4=high 5=realtime)"
+        ),
+        Some(st) => tracing::warn!(
+            status = format!("0x{st:08X}"),
+            "cross-process D3DKMTSetProcessSchedulingPriorityClass on the WGC helper failed"
+        ),
+        None => tracing::warn!(
+            "D3DKMTSetProcessSchedulingPriorityClass export not found — WGC helper has no GPU priority"
+        ),
+    }
+}
+
 /// Re-find the output, make a fresh device on its adapter, and duplicate it. Used by the ACCESS_LOST
 /// recovery to rebuild the whole capture on the current (possibly secure) input desktop.
 unsafe fn reopen_duplication(
@@ -482,6 +552,17 @@ unsafe extern "system" fn hybrid_query_hook(gpu_preference: *mut u32) -> i32 {
 pub(crate) fn install_gpu_pref_hook() {
     use std::sync::Once;
     static HOOK: Once = Once::new();
+    // SAFETY: this one-time hook install only touches a region it has just validated.
+    // `LoadLibraryA("win32u.dll")` + `GetProcAddress("NtGdiDdDDIGetCachedHybridQueryValue")` yield the
+    // live base of the real exported function, so `target` is a valid executable code pointer to at
+    // least the 12 bytes the patch overwrites (an x64 prologue, per Apollo's verified hook). The two
+    // `ptr::copy_nonoverlapping`s each move exactly 12 bytes between the 12-byte stack arrays
+    // (`patch`/`readback`) and `target`, which `VirtualProtect(target, 12, PAGE_EXECUTE_READWRITE, …)`
+    // has just made writable (and is restored to `old` after) — source and dest never overlap (stack
+    // vs. loaded module image), so every access stays in mapped, in-bounds memory.
+    // `FlushInstructionCache` gets the current-process pseudo-handle + that same range. The DPI calls
+    // take by-value context handles / fill the live local `&mut old`/`&mut restore` for the duration of
+    // each synchronous call. Runs once via `Once::call_once`, before any DXGI use.
     HOOK.call_once(|| unsafe {
         use windows::Win32::System::LibraryLoader::{GetProcAddress, LoadLibraryA};
         use windows::Win32::System::Memory::{
@@ -1333,6 +1414,14 @@ pub fn hdr_p010_selftest() -> Result<()> {
         }
     }
 
+    // SAFETY: this self-test creates its own D3D11 device + immediate context (`D3D11CreateDevice`,
+    // both checked non-null) and uses ONLY that device for the rest of the block: every
+    // `CreateTexture2D`/`CreateShaderResourceView`/`HdrP010Converter::{new,convert}`/`CopyResource`/
+    // `Map` is invoked on that device or its context, so all resources share one device and run on this
+    // single thread. The source texture's `D3D11_SUBRESOURCE_DATA` points at `fp16`, a live
+    // `Vec<u16>` of `W*H*4` samples with `SysMemPitch = W*8`, matching the W×H R16G16B16A16 texture;
+    // `fp16` outlives the synchronous `CreateTexture2D` that reads it. The mapped-pointer reads are
+    // proven individually at the `read_u16` closure below.
     unsafe {
         // Hardware D3D11 device (no adapter pin — the default GPU is fine for the self-test).
         let mut device: Option<ID3D11Device> = None;
@@ -1982,7 +2071,11 @@ pub struct DuplCapturer {
     dbg_cursor: u64,
     _keepalive: Box<dyn Send>,
 }
-// COM objects used only from the one thread that owns the capturer (the encode thread).
+// SAFETY: `DuplCapturer` holds D3D11 device/context/duplication COM pointers plus plain data. The
+// device is created free-threaded (`make_device` sets no `D3D11_CREATE_DEVICE_SINGLETHREADED`) and
+// COM reference counting is interlocked, so moving ownership of the whole capturer to another thread
+// is sound. It is used by exactly one thread (the encode thread) at a time — moved to it once, never
+// shared (no `Sync`) — so the single-threaded immediate context is never touched concurrently.
 unsafe impl Send for DuplCapturer {}
 
 impl DuplCapturer {
@@ -1990,8 +2083,18 @@ impl DuplCapturer {
         target: WinCaptureTarget,
         preferred: Option<(u32, u32, u32)>,
         keepalive: Box<dyn Send>,
+        // Whether the (already-resolved) encode backend wants GPU-resident frames — passed IN (Goal-1
+        // stage 5) so the capturer never re-derives the encode backend itself.
+        gpu: bool,
         want_hdr: bool,
     ) -> Result<Self> {
+        // SAFETY: runs on the capture thread that will own this `DuplCapturer`. `install_gpu_pref_hook()`
+        // and the DPI-context calls take by-value handles / no args and touch only thread/process state;
+        // `SetThreadExecutionState` takes a flags bitmask by value. `CreateDXGIFactory1` yields a live
+        // `IDXGIFactory1`, and every subsequent COM method (`EnumAdapters1`/`EnumOutputs`/`GetDesc1`/
+        // `GetDesc`/`cast`) is called on that factory or on an adapter/output it returned — each obtained
+        // through a checked `while let Ok(..)`/`?` — all from this one thread. No raw pointers are
+        // dereferenced; the borrowed strings/locals outlive each synchronous call.
         unsafe {
             // Stop DXGI hybrid-GPU output reparenting BEFORE we create the factory / enumerate outputs
             // (the cause of the 0x887A0026 ACCESS_LOST churn on this hybrid box: RTX 4090 + AMD iGPU).
@@ -2127,9 +2230,9 @@ impl DuplCapturer {
             let context = context.context("null D3D11 context")?;
             // 3) duplicate the output. Attach to the current input desktop first (as SYSTEM this can
             // be the Winlogon secure desktop) so a session that starts at the lock/login screen works.
-            // The SudoVDA is kept the sole desktop via the CCD isolation in sudovda::create_monitor
-            // (registry-persisted), so the secure desktop has nowhere to render but the output we
-            // capture — no per-open re-isolation needed.
+            // The virtual display is kept the sole desktop via the CCD isolation the pf-vdisplay backend
+            // applies at monitor creation (registry-persisted), so the secure desktop has nowhere to render
+            // but the output we capture — no per-open re-isolation needed.
             attach_input_desktop();
             let dupl = duplicate_output(&output, &device, want_hdr)
                 .context("DuplicateOutput (already duplicated by another app?)")?;
@@ -2157,9 +2260,13 @@ impl DuplCapturer {
                 .ok()
                 .and_then(|s| s.parse().ok())
                 .unwrap_or((2000 / refresh_hz.max(1)).max(100));
-            let gpu_mode = std::env::var("PUNKTFUNK_ENCODER")
-                .map(|v| matches!(v.to_ascii_lowercase().as_str(), "nvenc" | "hw" | "nvidia"))
-                .unwrap_or(false);
+            // Produce GPU-resident D3D11 frames (zero-copy NVENC, or the NV12/P010 the AMF/QSV backends
+            // read back / import) whenever the encode backend is a GPU one — so the capturer's output
+            // format matches the encoder's input. Only the software (GPU-less) path takes CPU staging.
+            // The decision is resolved ONCE per session and passed in (Goal-1 stage 5), instead of this
+            // capturer re-calling `encode::windows_resolved_backend()` — the back-reference that let
+            // capture and encode disagree (plan §2.3/§5).
+            let gpu_mode = gpu;
             // Read the source display's HDR mastering metadata while we still hold `output` (it is
             // moved into the struct below). Only meaningful for an HDR (FP16) duplication.
             let is_hdr_init = dd.ModeDesc.Format == DXGI_FORMAT_R16G16B16A16_FLOAT;
@@ -2651,7 +2758,7 @@ impl DuplCapturer {
         }
         // The SudoVDA output's GDI name can CHANGE across a secure-desktop topology rebuild —
         // re-resolve from the STABLE target id so we find it under its current name.
-        if let Some(n) = crate::vdisplay::sudovda::resolve_gdi_name(self.target_id) {
+        if let Some(n) = crate::win_display::resolve_gdi_name(self.target_id) {
             self.gdi_name = n;
         }
         // Re-sync the capture thread to the CURRENT input desktop on EVERY rebuild — symmetric for
@@ -3144,6 +3251,11 @@ impl Capturer for DuplCapturer {
         // the duplication up to 12 s). Better a few seconds of frozen-last-frame than dropping the stream.
         let mut deadline = Instant::now() + Duration::from_secs(20);
         loop {
+            // SAFETY: `acquire` is an `unsafe fn` because it drives the D3D11 immediate context + the
+            // output duplication, which must be touched only from the capturer's owning thread.
+            // `next_frame` runs on that one thread — `DuplCapturer` is `Send` but not `Sync`, so it is
+            // owned by a single (encode) thread for its whole life — and `&mut self` gives exclusive
+            // access for the call, satisfying that contract.
             if let Some(f) = unsafe { self.acquire() }? {
                 self.ever_got_frame = true;
                 return Ok(f);
@@ -3190,6 +3302,8 @@ impl Capturer for DuplCapturer {
     }
 
     fn try_latest(&mut self) -> Result<Option<CapturedFrame>> {
+        // SAFETY: as in `next_frame` — `acquire` must run on the capturer's single owning thread, and
+        // `try_latest` is called on it (`DuplCapturer` is `Send`, not `Sync`); `&mut self` is exclusive.
         unsafe { self.acquire() }
     }
 
@@ -3201,11 +3315,19 @@ impl Capturer for DuplCapturer {
 impl Drop for DuplCapturer {
     fn drop(&mut self) {
         if self.holding_frame {
+            // SAFETY: `self.dupl` is the live `IDXGIOutputDuplication` this capturer created and owns;
+            // `ReleaseFrame` is a valid COM method on it, called only when `holding_frame` records that a
+            // frame was acquired and not yet released (so it is not an unbalanced release). Drop runs on
+            // whichever thread owns the capturer — its sole owner, since it is `!Sync` — and the `&`
+            // borrow of the duplication outlives this synchronous call.
             unsafe {
                 let _ = self.dupl.as_ref().map(|d| d.ReleaseFrame());
             }
         }
         // Release the display/system-required execution state we took at open().
+        // SAFETY: `SetThreadExecutionState` is a Win32 FFI call taking an execution-state flag bitmask
+        // by value (`ES_CONTINUOUS` clears the display/system-required state taken at open); it borrows
+        // no Rust memory and is safe to call from any thread.
         unsafe {
             SetThreadExecutionState(ES_CONTINUOUS);
         }

crates/punktfunk-host/src/capture/windows/wgc.rs

@@ -16,6 +16,9 @@
 //! Limitation: WGC cannot capture the secure desktop (lock / UAC / login) — the caller falls back to
 //! the DDA backend ([`super::dxgi::DuplCapturer`]) for those (see capture.rs).
 
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
+#![deny(clippy::undocumented_unsafe_blocks)]
+
 use super::dxgi::{
     find_output, hdr_shader_p010_enabled, make_device, nudge_cursor_onto, D3d11Frame, HdrConverter,
     HdrP010Converter, VideoConverter, WinCaptureTarget,
@@ -92,6 +95,10 @@ struct Deimpersonate(Option<HANDLE>);
 impl Drop for Deimpersonate {
     fn drop(&mut self) {
         if let Some(tok) = self.0.take() {
+            // SAFETY: `RevertToSelf` takes no arguments and undoes the thread impersonation set during
+            // WGC activation; `tok` is the impersonation token `HANDLE` from `impersonate_active_user`,
+            // owned by this `Deimpersonate` and closed exactly once here (taken out of the `Option`, so
+            // no double-close). Both are FFI calls borrowing no Rust memory.
             unsafe {
                 let _ = RevertToSelf();
                 let _ = CloseHandle(tok);
@@ -174,7 +181,12 @@ pub struct WgcCapturer {
     _keepalive: Option<Box<dyn Send>>,
 }
 
-// COM + WinRT pointers; confined to the single owning (encode) thread, like DuplCapturer.
+// SAFETY: like `DuplCapturer`. `WgcCapturer` holds D3D11 (free-threaded device/context) plus WGC WinRT
+// objects (`Direct3D11CaptureFramePool` etc., created free-threaded via `CreateFreeThreaded`). COM/WinRT
+// reference counting is interlocked, and the capturer is owned + used by exactly one encode thread,
+// moved to it once and never shared (no `Sync`), so transferring ownership across threads is sound. The
+// free-threaded `FrameArrived` callback touches only the `Arc<WgcSignal>` (itself `Send + Sync`), not
+// the capturer's COM fields.
 unsafe impl Send for WgcCapturer {}
 
 impl WgcCapturer {
@@ -182,6 +194,15 @@ impl WgcCapturer {
     /// [`attach_keepalive`](Self::attach_keepalive) only after open succeeds, so a failure leaves the
     /// keepalive with the caller to hand to the DDA fallback.
     pub fn open(target: WinCaptureTarget, preferred: Option<(u32, u32, u32)>) -> Result<Self> {
+        // SAFETY: runs on the thread opening the WGC session. `RoInitialize` inits this thread's WinRT
+        // apartment (idempotent; result ignored). `impersonate_active_user()` and `find_output()` are
+        // this module's `unsafe fn`s whose contracts (call on the activating thread; pass a GDI name)
+        // are met, and the impersonation is reverted by `_deimp`'s Drop on every return path. Every
+        // COM/WinRT call thereafter operates on an object obtained + `?`-checked earlier in this same
+        // block on this single thread — the `IDXGIOutput1` from `find_output`, the device/context from
+        // `make_device`, the factory/interop/item/pool/session — and the `TypedEventHandler` closure
+        // captures an `Arc<WgcSignal>` (Send+Sync) by move. No raw pointers are dereferenced; borrowed
+        // locals outlive their synchronous calls.
         unsafe {
             // WGC is WinRT — the calling thread needs a COM/WinRT apartment for the GraphicsCaptureItem
             // activation factory (RoGetActivationFactory). Initialize MTA; ignore "already initialized"
@@ -196,7 +217,7 @@ impl WgcCapturer {
             // The SudoVDA output appears a beat after the display is created — settle-retry like DDA.
             let deadline = Instant::now() + Duration::from_millis(2000);
             let (adapter, output) = loop {
-                if let Some(n) = crate::vdisplay::sudovda::resolve_gdi_name(target.target_id) {
+                if let Some(n) = crate::win_display::resolve_gdi_name(target.target_id) {
                     if let Ok(found) = find_output(&n) {
                         break found;
                     }
@@ -585,6 +606,15 @@ impl WgcCapturer {
     }
 
     fn process_frame(&mut self, frame: Direct3D11CaptureFrame) -> Result<CapturedFrame> {
+        // SAFETY: runs on the capturer's single owning thread. `frame` is a live
+        // `Direct3D11CaptureFrame` from `self.pool`; `frame.Surface().cast::<IDirect3DDxgiInterfaceAccess
+        // >().GetInterface()` yields the frame's backing `ID3D11Texture2D`, which belongs to
+        // `self.device` (the pool was created on it via `CreateDirect3D11DeviceFromDXGIDevice`). Every
+        // helper called here — `hdr_to_p010`, `convert_to_yuv`, `ensure_fp16_src`, `ensure_out_ring`,
+        // `HdrConverter::convert`, `CopyResource`, `CreateRenderTargetView` — operates on
+        // `self.device`/`self.context` and that same-device texture, so all resources share one device.
+        // The frame is held in `self.held` until its async GPU read completes for the zero-copy paths.
+        // Single-threaded immediate-context use; borrowed textures/SRVs/RTVs outlive each synchronous call.
         unsafe {
             let surface = frame.Surface().context("frame Surface")?;
             let access: IDirect3DDxgiInterfaceAccess = surface

crates/punktfunk-host/src/capture/windows/wgc_relay.rs

@@ -1,5 +1,5 @@
 //! Host-side WGC helper relay (Windows two-process secure-desktop design,
-//! docs/windows-secure-desktop.md — step 4).
+//! design/archive/windows-secure-desktop.md — step 4).
 //!
 //! WGC won't activate under the SYSTEM account, so the SYSTEM host can't capture the normal desktop
 //! itself. Instead it spawns `punktfunk-host wgc-helper` in the **interactive user session** (so WGC works)
@@ -13,6 +13,9 @@
 //! Wire framing (must match `wgc_helper::write_au`): per AU
 //! `[u32 magic "PFAU" LE][u32 len LE][u64 pts_ns LE][u8 keyframe][len bytes data]`.
 
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
+#![deny(clippy::undocumented_unsafe_blocks)]
+
 use crate::capture::dxgi::WinCaptureTarget;
 use anyhow::{bail, Context, Result};
 use std::io::{BufRead, BufReader, Read};
@@ -56,9 +59,15 @@ pub struct HelperRelay {
     rx: Receiver<RelayAu>,
 }
 
-// HANDLEs are just kernel handle values; we own them for the relay's lifetime and close them on Drop.
+// SAFETY: every field is itself `Send`: the `proc`/`thread` `HANDLE`s are process-global kernel
+// handle values (plain integers valid from any thread, owned for the relay's lifetime and closed once
+// on Drop), `stdin_w` is a `Mutex<HANDLE>`, and `rx` is an mpsc `Receiver<RelayAu>` (which is `Send`).
+// The relay is moved to one thread and owned there, so transferring it across threads is sound.
 unsafe impl Send for HelperRelay {}
-unsafe impl Sync for HelperRelay {}
+// NOTE: `HelperRelay` is deliberately NOT `Sync`. Its `rx: Receiver<RelayAu>` is `!Sync` (std mpsc
+// is single-consumer), and the relay is only ever a single-owner local in the punktfunk1 two-process
+// mux loop — never shared by `&` across threads — so `Sync` is neither sound nor needed. (A prior
+// `unsafe impl Sync` here asserted more than the fields support; removed.)
 
 /// Control byte on the helper's stdin: force the next encoded frame to be an IDR (client decode
 /// recovery). Mirrors `enc.request_keyframe()` in the single-process path.
@@ -84,6 +93,10 @@ impl HelperRelay {
         );
         tracing::info!(cmd = %cmdline, "spawning WGC helper in user session");
 
+        // SAFETY: `spawn_inner` is an `unsafe fn` only because it drives raw Win32 token/pipe/process
+        // FFI; it imposes no caller-side memory precondition beyond valid arguments. `cmdline` is a live
+        // `&str` borrowed for the synchronous call and `(w, h, hz)` are plain `u32`s. It validates its
+        // own runtime requirements (active console session, SYSTEM token) and returns `Err` otherwise.
         unsafe { spawn_inner(&cmdline, w, h, hz) }
     }
 
@@ -108,6 +121,11 @@ impl HelperRelay {
     pub fn request_keyframe(&self) {
         let h = self.stdin_w.lock().unwrap();
         let mut written = 0u32;
+        // SAFETY: `*h` is the host's write end of the helper's stdin pipe — a live `HANDLE` owned by
+        // this `HelperRelay` (held under the `stdin_w` Mutex, locked here), closed only in Drop.
+        // `WriteFile` reads the 1-byte `&[CTL_KEYFRAME]` buffer and writes the byte count into
+        // `written`; both are live locals that outlive the synchronous call. A failure (helper gone) is
+        // discarded as documented.
         unsafe {
             let _ = windows::Win32::Storage::FileSystem::WriteFile(
                 *h,
@@ -121,6 +139,10 @@ impl HelperRelay {
 
 impl Drop for HelperRelay {
     fn drop(&mut self) {
+        // SAFETY: `self.proc`/`self.thread` are the child process/thread `HANDLE`s from
+        // `CreateProcessAsUserW`, and `stdin_w` is the host's pipe write end — all owned by this
+        // `HelperRelay` and closed exactly once here in Drop (no double-close). `TerminateProcess` and
+        // the three `CloseHandle`s are FFI calls taking those handles by value, borrowing no Rust memory.
         unsafe {
             // Terminate the child first so its WGC capture + NVENC session tear down, then close our
             // handles (the reader threads end on the resulting broken pipe).
@@ -278,6 +300,13 @@ unsafe fn spawn_inner(cmdline: &str, w: u32, h: u32, hz: u32) -> Result<HelperRe
     }
     tracing::info!(pid = pi.dwProcessId, mode = %format!("{w}x{h}@{hz}"), "WGC helper spawned");
 
+    // The helper does the WGC capture + NVENC encode, but it runs under the user's UAC-FILTERED token
+    // (no SE_INC_BASE_PRIORITY), so it can't raise its OWN GPU scheduling-priority class — under a
+    // GPU-saturating game NVENC then gets starved (the "240→40 fps in-game collapse"). The SYSTEM host
+    // holds the privilege, so stamp the HIGH GPU priority class onto the child here, right after spawn
+    // (the process-level class applies to the GPU contexts the helper creates afterwards).
+    crate::capture::dxgi::set_child_gpu_priority_class(pi.hProcess);
+
     // stderr → host tracing, line by line.
     let err_handle = HandleReader(err_r);
     std::thread::Builder::new()
@@ -357,10 +386,17 @@ fn au_reader(mut r: HandleReader, tx: SyncSender<RelayAu>) {
 
 /// Minimal `Read` over a Win32 pipe HANDLE (the windows crate doesn't impl `Read` on HANDLE).
 struct HandleReader(HANDLE);
+// SAFETY: `HandleReader` owns a single pipe `HANDLE` (a process-global kernel handle value, valid from
+// any thread). It is moved into the dedicated reader thread and used only there (and closed once on
+// Drop), never shared — so transferring ownership across threads is sound.
 unsafe impl Send for HandleReader {}
 impl Read for HandleReader {
     fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
         let mut read = 0u32;
+        // SAFETY: `self.0` is the live read end of an anonymous pipe owned by this `HandleReader`
+        // (closed only in Drop). `ReadFile` fills the caller-provided `buf` (writing at most `buf.len()`
+        // bytes) and stores the count in `read`; both outlive the synchronous call. A broken pipe
+        // surfaces as `Err` and is mapped to EOF below.
         let ok = unsafe {
             windows::Win32::Storage::FileSystem::ReadFile(self.0, Some(buf), Some(&mut read), None)
         };
@@ -373,6 +409,8 @@ impl Read for HandleReader {
 }
 impl Drop for HandleReader {
     fn drop(&mut self) {
+        // SAFETY: `self.0` is the pipe `HANDLE` this `HandleReader` owns; `CloseHandle` (an FFI call
+        // taking the handle by value) is invoked exactly once here in Drop, so there is no double-close.
         unsafe {
             let _ = CloseHandle(self.0);
         }
@@ -384,6 +422,13 @@ impl Drop for HandleReader {
 pub fn running_as_system() -> bool {
     use windows::Win32::Security::{GetTokenInformation, TokenUser, TOKEN_QUERY, TOKEN_USER};
     use windows::Win32::System::Threading::{GetCurrentProcess, OpenProcessToken};
+    // SAFETY: `OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &mut token)` opens the current-process
+    // token (the pseudo-handle is always valid) into `token`, which is closed once before each return.
+    // The first `GetTokenInformation` (null buffer) queries the required `len`; `buf` is then a
+    // `Vec<u8>` of exactly `len` bytes and the second call fills it, so `&*(buf.as_ptr() as *const
+    // TOKEN_USER)` reads a `TOKEN_USER` the kernel just wrote into a sufficiently-sized buffer (the
+    // variable-length SID it points at also lies within `buf`, which outlives the borrow).
+    // `is_local_system_sid` is this module's `unsafe fn`, given that in-buffer `PSID`. Safe on any thread.
     unsafe {
         let mut token = HANDLE::default();
         if OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &mut token).is_err() {

crates/punktfunk-host/src/config.rs

@@ -0,0 +1,128 @@
+//! `HostConfig` — the host's runtime knobs parsed ONCE from the environment, instead of the ~68 scattered
+//! `env::var` reads recomputed at every call site (some up to 8×, which lets capture + encode silently
+//! disagree on the resolved backend — plan §2.4). The service / launcher loads `host.env` into the process
+//! environment before the host starts, and **for the knobs captured here the environment is constant for the
+//! process lifetime**, so a lazily-parsed global is equivalent to "parsed once at startup".
+//!
+//! **Goal-1 stages 1–2** (`design/windows-host-rewrite.md` §2.2): stage 1 stood this up; stage 2 migrated the
+//! genuinely-constant operator/dispatch knobs onto it (the dispatch-disagreement bug class: `idd_push`,
+//! `capture_backend`, `encoder_pref`, `render_adapter`, `no_wgc`, the vdisplay backend select — plus the
+//! plan-named `secure_dda`/`idd_depth`/`zerocopy`/`ten_bit` and the multi-site `perf`/`compositor`/
+//! `video_source`/`gamepad`). `SessionPlan` (stage 3) consumes it as the single owner of the
+//! capture/topology/encoder decision.
+//!
+//! **What is deliberately NOT here (and must stay a live `env::var` read):**
+//! - **Runtime-mutated session vars.** On Linux, [`crate::vdisplay::apply_session_env`] rewrites the process
+//!   env on *every connect* so one host follows a Bazzite box across Gaming↔Desktop: `WAYLAND_DISPLAY`,
+//!   `XDG_CURRENT_DESKTOP`, `XDG_RUNTIME_DIR`, `DBUS_SESSION_BUS_ADDRESS`, and the *derived* `PUNKTFUNK_*`
+//!   vars `INPUT_BACKEND`, `GAMESCOPE_SESSION`/`GAMESCOPE_NODE`, `KWIN_VIRTUAL_PRIMARY`,
+//!   `MUTTER_VIRTUAL_PRIMARY`, `FORCE_SHM` (+ `GAMESCOPE_APP` on the launch path). Parsing these once would
+//!   freeze them at startup and silently break session-following — they are NOT constant.
+//! - **Single-use local tuning** read exactly where it is used (no resolve-once benefit, and a parse with a
+//!   call-site-local default/clamp): e.g. `FEC_PCT` (two *different* semantics — GameStream default-20 vs
+//!   punktfunk/1 `Option`/clamp-90), `VIDEO_DROP`, `VBV_FRAMES`, `SPLIT_ENCODE`, `PACE_BURST_KB`, the
+//!   `capture/dxgi.rs` timing knobs, the `*_LIVE` test gates.
+//! - **Path / genuinely-dynamic reads**: the config-dir resolution, `PATH` executable search, the
+//!   env-forward-to-child loop, `PUNKTFUNK_MGMT_TOKEN`, `PUNKTFUNK_HOST_CMD`, `PUNKTFUNK_RENDER_NODE`.
+//!
+//! `PUNKTFUNK_ZEROCOPY` note: this field uses **presence** semantics (`var_os(..).is_some()`) to match the
+//! Windows `encode/ffmpeg_win.rs` reader. The Linux `zerocopy` module keeps its own *truthy* parser
+//! (`1|true|yes|on`) — the two are independent features that share a name; do NOT conflate them.
+
+use std::sync::OnceLock;
+
+/// Resolved host configuration. Holds the genuinely-constant operator/dispatch knobs (see module docs for
+/// what is deliberately excluded). Fields read on only one platform are kept alive cross-platform by the
+/// derived `Debug` impl, so the parser can stay a single platform-neutral function.
+#[derive(Debug, Clone, Default)]
+pub struct HostConfig {
+    /// `PUNKTFUNK_IDD_PUSH` — capture from the pf-vdisplay driver's shared ring (in-process Session-0
+    /// capture; no WGC helper). **Value-aware** (`0`/`false`/`no`/`off`/empty ⇒ off, else on); unset ⇒ off.
+    /// The installer's default `host.env` sets it on, so a fresh install runs the validated IDD-push path
+    /// (it falls back to DDA if the driver can't attach — see [`crate::capture`]). NOT a bare presence flag
+    /// (so an operator can turn it OFF in `host.env` with `=0`, which a `var_os` presence check can't).
+    pub idd_push: bool,
+    /// `PUNKTFUNK_ENCODER` — explicit encoder-backend override (lowercased; empty = auto-detect by GPU vendor).
+    pub encoder_pref: String,
+    /// `PUNKTFUNK_NO_HELPER` — never spawn the user-session WGC helper.
+    pub no_helper: bool,
+    /// `PUNKTFUNK_FORCE_HELPER` — force the WGC helper even when not running as SYSTEM.
+    pub force_helper: bool,
+    /// `PUNKTFUNK_NO_WGC` — force the pure single-process DDA path (skip WGC and the two-process relay).
+    pub no_wgc: bool,
+    /// `PUNKTFUNK_CAPTURE` — explicit Windows capture-backend override (lowercased; `dda`/`dxgi` vs the WGC default).
+    pub capture_backend: String,
+    /// `PUNKTFUNK_RENDER_ADAPTER` — discrete render-GPU pin by description substring (`Some` even when empty:
+    /// the empty string still counts as "set" for the presence checks, and the value reader filters it).
+    pub render_adapter: Option<String>,
+    /// `PUNKTFUNK_SECURE_DDA` — enable the experimental DDA-on-secure-desktop (Winlogon/UAC) mux leg.
+    pub secure_dda: bool,
+    /// `PUNKTFUNK_IDD_DEPTH` — IDD-push pipeline depth override (default 2; the call site clamps to its `OUT_RING`).
+    pub idd_depth: usize,
+    /// `PUNKTFUNK_ZEROCOPY` — opt into the Windows D3D11 zero-copy encode path (presence semantics; see module docs).
+    pub zerocopy: bool,
+    /// `PUNKTFUNK_10BIT` — host policy gate for HEVC Main10 (only honored when the client also advertised 10-bit).
+    pub ten_bit: bool,
+    /// `PUNKTFUNK_PERF` — per-stage timing instrumentation.
+    pub perf: bool,
+    /// `PUNKTFUNK_VIDEO_SOURCE` — GameStream video source select (`virtual` / `portal` / unset → synthetic).
+    pub video_source: Option<String>,
+    /// `PUNKTFUNK_COMPOSITOR` — explicit compositor override (operator/CI/test). NOT the runtime-detected
+    /// session — this one is a constant operator knob; `apply_session_env` never writes it.
+    pub compositor: Option<String>,
+    /// `PUNKTFUNK_GAMEPAD` — client/operator virtual-pad backend preference (fed to `pick_gamepad`).
+    pub gamepad: Option<String>,
+    /// `PUNKTFUNK_VDISPLAY` — Windows virtual-display backend. The pf-vdisplay IddCx driver is now the only
+    /// 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>,
+}
+
+impl HostConfig {
+    fn from_env() -> Self {
+        // Presence flag: set ⇒ true. Matches the original `var_os(k).is_some()` reads (and the few
+        // `var(k).is_ok()` flag reads, which coincide for every real-world value).
+        let flag = |k: &str| std::env::var_os(k).is_some();
+        // String value: `var(k).ok()` — `Some` (possibly empty) when set with valid UTF-8, else `None`.
+        let val = |k: &str| std::env::var(k).ok();
+        Self {
+            // Value-aware (not a bare presence flag): the shipped default `host.env` turns it ON, and an
+            // operator turns it OFF with `PUNKTFUNK_IDD_PUSH=0` (a `var_os` presence check would read `=0`
+            // as "on"). Unset ⇒ off (the dev / non-pf-driver default).
+            idd_push: match std::env::var("PUNKTFUNK_IDD_PUSH") {
+                Ok(v) => !matches!(
+                    v.trim().to_ascii_lowercase().as_str(),
+                    "" | "0" | "false" | "no" | "off"
+                ),
+                Err(_) => false,
+            },
+            encoder_pref: std::env::var("PUNKTFUNK_ENCODER")
+                .unwrap_or_default()
+                .to_ascii_lowercase(),
+            no_helper: flag("PUNKTFUNK_NO_HELPER"),
+            force_helper: flag("PUNKTFUNK_FORCE_HELPER"),
+            no_wgc: flag("PUNKTFUNK_NO_WGC"),
+            capture_backend: std::env::var("PUNKTFUNK_CAPTURE")
+                .unwrap_or_default()
+                .to_ascii_lowercase(),
+            render_adapter: val("PUNKTFUNK_RENDER_ADAPTER"),
+            secure_dda: flag("PUNKTFUNK_SECURE_DDA"),
+            idd_depth: val("PUNKTFUNK_IDD_DEPTH")
+                .and_then(|s| s.parse::<usize>().ok())
+                .unwrap_or(2),
+            zerocopy: flag("PUNKTFUNK_ZEROCOPY"),
+            ten_bit: flag("PUNKTFUNK_10BIT"),
+            perf: flag("PUNKTFUNK_PERF"),
+            video_source: val("PUNKTFUNK_VIDEO_SOURCE"),
+            compositor: val("PUNKTFUNK_COMPOSITOR"),
+            gamepad: val("PUNKTFUNK_GAMEPAD"),
+            vdisplay: val("PUNKTFUNK_VDISPLAY"),
+        }
+    }
+}
+
+/// The process-wide host configuration, parsed once on first access.
+pub fn config() -> &'static HostConfig {
+    static CFG: OnceLock<HostConfig> = OnceLock::new();
+    CFG.get_or_init(HostConfig::from_env)
+}

crates/punktfunk-host/src/encode.rs

@@ -3,6 +3,9 @@
 //! RGB→YUV on the GPU, so no host-side CSC) and VAAPI on AMD/Intel (`*_vaapi`; the CPU-input
 //! fallback swscales RGB→NV12, the zero-copy path imports the capture dmabuf straight into a
 //! VA surface). One [`Encoder`] trait, selected in [`open_video`].
+// Every unsafe block in this module tree carries a `// SAFETY:` proof; enforce it (unsafe-proof
+// program). As a parent module this also covers the child modules (encode::windows/linux::*).
+#![deny(clippy::undocumented_unsafe_blocks)]
 
 use crate::capture::{CapturedFrame, PixelFormat};
 use anyhow::Result;
@@ -49,11 +52,56 @@ impl Codec {
             Codec::Av1 => "av1_vaapi",
         }
     }
+
+    /// The FFmpeg AMD **AMF** encoder name (the Windows AMD backend). Selected by name (the codec id
+    /// would pick the software encoder). AV1 (`av1_amf`) is RDNA3+/RX 7000+ — probe, never assume.
+    pub fn amf_name(self) -> &'static str {
+        match self {
+            Codec::H264 => "h264_amf",
+            Codec::H265 => "hevc_amf",
+            Codec::Av1 => "av1_amf",
+        }
+    }
+
+    /// The FFmpeg Intel **QSV** encoder name (the Windows Intel backend). Selected by name. AV1
+    /// (`av1_qsv`) is Arc/Xe2+; HEVC Main10 is Gen9.5+ — probe, never assume.
+    pub fn qsv_name(self) -> &'static str {
+        match self {
+            Codec::H264 => "h264_qsv",
+            Codec::H265 => "hevc_qsv",
+            Codec::Av1 => "av1_qsv",
+        }
+    }
+}
+
+/// Static capabilities an [`Encoder`] declares so the session glue routes loss-recovery and HDR
+/// plumbing by *query* rather than relying on a method's no-op/`false` default. Cheap `Copy`; fixed
+/// for the session (an HDR toggle re-initialises the encoder — re-query if that matters).
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct EncoderCaps {
+    /// The encoder can perform real reference-frame invalidation — i.e.
+    /// [`invalidate_ref_frames`](Encoder::invalidate_ref_frames) can return `true`. When `false`
+    /// the caller skips that always-`false` call and forces a keyframe directly on loss recovery.
+    /// Only the Windows direct-NVENC path implements RFI; libavcodec (Linux NVENC), VAAPI and
+    /// AMF/QSV always keyframe.
+    pub supports_rfi: bool,
+    /// The encoder emits in-band HDR mastering/CLL SEI from [`set_hdr_meta`](Encoder::set_hdr_meta).
+    /// When `false`, `set_hdr_meta` is a no-op and no in-band grade reaches the client. Only the
+    /// Windows direct-NVENC path attaches it today.
+    pub supports_hdr_metadata: bool,
 }
 
 /// A hardware encoder. One per session; runs on the encode thread.
 pub trait Encoder: Send {
     fn submit(&mut self, frame: &CapturedFrame) -> Result<()>;
+    /// This encoder's static [capabilities](EncoderCaps) (RFI, HDR SEI), so the session glue can
+    /// route by query rather than rely on the no-op/`false` defaults of
+    /// [`invalidate_ref_frames`](Self::invalidate_ref_frames) / [`set_hdr_meta`](Self::set_hdr_meta).
+    /// Default: no optional capabilities (the SDR / libavcodec backends) — only the direct-NVENC
+    /// path overrides it.
+    fn caps(&self) -> EncoderCaps {
+        EncoderCaps::default()
+    }
     /// Force the next submitted frame to be an IDR keyframe (e.g. after a client
     /// reference-frame-invalidation request). Default: no-op.
     fn request_keyframe(&mut self) {}
@@ -153,14 +201,12 @@ pub fn open_video(
         // AMD/Intel → VAAPI (one libavcodec backend for both). Auto-detect by default so a single
         // Linux binary serves any GPU; `PUNKTFUNK_ENCODER` forces a specific backend (and surfaces
         // its errors crisply instead of silently trying the other).
-        let pref = std::env::var("PUNKTFUNK_ENCODER")
-            .unwrap_or_default()
-            .to_ascii_lowercase();
+        let pref = crate::config::config().encoder_pref.as_str();
         let open_vaapi = || -> Result<Box<dyn Encoder>> {
             vaapi::VaapiEncoder::open(codec, format, width, height, fps, bitrate_bps, bit_depth)
                 .map(|e| Box::new(e) as Box<dyn Encoder>)
         };
-        match pref.as_str() {
+        match pref {
             "nvenc" | "nvidia" | "cuda" => open_nvenc_probed(
                 codec,
                 format,
@@ -198,16 +244,15 @@ pub fn open_video(
     #[cfg(target_os = "windows")]
     {
         let _ = cuda; // always false on Windows (no Cuda payload)
-        let _ = bit_depth; // used by the NVENC path below; the software H.264 path is 8-bit only
-        let pref = std::env::var("PUNKTFUNK_ENCODER")
-            .unwrap_or_default()
-            .to_ascii_lowercase();
-        if matches!(pref.as_str(), "nvenc" | "hw" | "nvidia") {
+                      // NVIDIA → NVENC (direct SDK), AMD → AMF, Intel → QSV (both libavcodec), else → software
+                      // H.264. `auto` (the default) resolves from the DXGI adapter vendor.
+        match windows_resolved_backend() {
+            WindowsBackend::Nvenc => {
                 // Hardware path: NVENC over D3D11. The DXGI capturer switches to its zero-copy
                 // FramePayload::D3d11 output under the same env var so capture + encode share textures.
                 #[cfg(feature = "nvenc")]
                 {
-                let enc = nvenc::NvencD3d11Encoder::open(
+                    nvenc::NvencD3d11Encoder::open(
                         codec,
                         format,
                         width,
@@ -215,32 +260,67 @@ pub fn open_video(
                         fps,
                         bitrate_bps,
                         bit_depth,
-                )?;
-                return Ok(Box::new(enc) as Box<dyn Encoder>);
+                    )
+                    .map(|e| Box::new(e) as Box<dyn Encoder>)
                 }
                 #[cfg(not(feature = "nvenc"))]
                 {
                     anyhow::bail!(
-                    "NVENC requested but this host was built without it — rebuild with \
-                     `--features nvenc` (needs the NVENC SDK's nvencodeapi.lib at link time)"
-                );
+                        "NVENC requested/detected but this host was built without it — rebuild \
+                         with `--features nvenc` (needs the NVENC SDK's nvencodeapi.lib at link time)"
+                    )
                 }
             }
+            backend @ (WindowsBackend::Amf | WindowsBackend::Qsv) => {
+                // AMD AMF / Intel QSV via libavcodec (the Windows analogue of the Linux VAAPI path).
+                #[cfg(feature = "amf-qsv")]
+                {
+                    let vendor = if matches!(backend, WindowsBackend::Amf) {
+                        ffmpeg_win::WinVendor::Amf
+                    } else {
+                        ffmpeg_win::WinVendor::Qsv
+                    };
+                    ffmpeg_win::FfmpegWinEncoder::open(
+                        vendor,
+                        codec,
+                        format,
+                        width,
+                        height,
+                        fps,
+                        bitrate_bps,
+                        bit_depth,
+                    )
+                    .map(|e| Box::new(e) as Box<dyn Encoder>)
+                }
+                #[cfg(not(feature = "amf-qsv"))]
+                {
+                    let _ = backend;
+                    anyhow::bail!(
+                        "AMD/Intel (AMF/QSV) encode requested/detected but this host was built \
+                         without it — rebuild with `--features amf-qsv` (needs ffmpeg-next + a \
+                         FFMPEG_DIR with the AMF/QSV encoders at build time)"
+                    )
+                }
+            }
+            WindowsBackend::Software => {
                 anyhow::ensure!(
                     codec == Codec::H264,
                     "the Windows software encoder supports H.264 only; client negotiated {codec:?} \
-             (set PUNKTFUNK_ENCODER=nvenc for a GPU host, or request H264)"
+                     (build a GPU backend: --features nvenc or amf-qsv, or request H264)"
                 );
+                let _ = bit_depth; // the software H.264 path is 8-bit only
                                    // Software H.264 realistically caps far below the negotiated hardware rates.
                 const SW_BITRATE_CEIL: u64 = 100_000_000;
-        let enc = sw::OpenH264Encoder::open(
+                sw::OpenH264Encoder::open(
                     format,
                     width,
                     height,
                     fps,
                     bitrate_bps.min(SW_BITRATE_CEIL),
-        )?;
-        Ok(Box::new(enc) as Box<dyn Encoder>)
+                )
+                .map(|e| Box::new(e) as Box<dyn Encoder>)
+            }
+        }
     }
     #[cfg(not(any(target_os = "linux", target_os = "windows")))]
     {
@@ -325,11 +405,7 @@ fn nvidia_present() -> bool {
 /// passthrough for VAAPI vs the EGL→CUDA import for NVENC).
 #[cfg(target_os = "linux")]
 pub fn linux_zero_copy_is_vaapi() -> bool {
-    match std::env::var("PUNKTFUNK_ENCODER")
-        .unwrap_or_default()
-        .to_ascii_lowercase()
-        .as_str()
-    {
+    match crate::config::config().encoder_pref.as_str() {
         "nvenc" | "nvidia" | "cuda" => false,
         "vaapi" | "amd" | "intel" => true,
         _ => !nvidia_present(),
@@ -339,7 +415,7 @@ pub fn linux_zero_copy_is_vaapi() -> bool {
 /// Which codecs the active GPU can actually ENCODE. Used to build the GameStream codec
 /// advertisement so a client never negotiates a codec the GPU can't do (AV1 encode is narrow —
 /// Intel Arc/Xe2+, AMD RDNA3+/RDNA4 — so it must be probed, not assumed).
-#[cfg(target_os = "linux")]
+#[cfg(any(target_os = "linux", target_os = "windows"))]
 #[derive(Clone, Copy, Debug)]
 pub struct CodecSupport {
     pub h264: bool,
@@ -370,13 +446,142 @@ pub fn vaapi_codec_support() -> CodecSupport {
     })
 }
 
+// ---------------------------------------------------------------------------------------------
+// Windows backend selection (the analogue of the Linux nvidia_present / linux_zero_copy_is_vaapi
+// logic). NVIDIA → NVENC, AMD → AMF, Intel → QSV; `auto` (default) reads the DXGI adapter vendor.
+// ---------------------------------------------------------------------------------------------
+
+#[cfg(target_os = "windows")]
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum WindowsBackend {
+    Nvenc,
+    Amf,
+    Qsv,
+    Software,
+}
+
+#[cfg(target_os = "windows")]
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum GpuVendor {
+    Nvidia,
+    Amd,
+    Intel,
+}
+
+/// Resolve the active Windows encode backend from `PUNKTFUNK_ENCODER` (`auto` → the DXGI adapter
+/// vendor). Shared by [`open_video`] and the GameStream codec advertisement so both agree.
+#[cfg(target_os = "windows")]
+pub(crate) fn windows_resolved_backend() -> WindowsBackend {
+    // Resolved ONCE in HostConfig (Goal-1) — was re-read from PUNKTFUNK_ENCODER on every call.
+    match crate::config::config().encoder_pref.as_str() {
+        "nvenc" | "hw" | "nvidia" | "cuda" => WindowsBackend::Nvenc,
+        "amf" | "amd" => WindowsBackend::Amf,
+        "qsv" | "intel" => WindowsBackend::Qsv,
+        "sw" | "software" | "openh264" => WindowsBackend::Software,
+        _ => match windows_gpu_vendor() {
+            Some(GpuVendor::Nvidia) => WindowsBackend::Nvenc,
+            Some(GpuVendor::Amd) => WindowsBackend::Amf,
+            Some(GpuVendor::Intel) => WindowsBackend::Qsv,
+            None => WindowsBackend::Software,
+        },
+    }
+}
+
+/// True if the active Windows backend is the libavcodec AMF/QSV path (so the codec advertisement
+/// consults a real GPU probe rather than the NVENC static superset). Always false when the
+/// `amf-qsv` feature is off — there's then no ffmpeg backend to probe.
+#[cfg(target_os = "windows")]
+pub fn windows_backend_is_ffmpeg() -> bool {
+    cfg!(feature = "amf-qsv")
+        && matches!(
+            windows_resolved_backend(),
+            WindowsBackend::Amf | WindowsBackend::Qsv
+        )
+}
+
+/// Detect the host GPU vendor from the first hardware DXGI adapter (Windows has no `/dev/nvidia*`
+/// probe). Cached. NVIDIA=0x10DE, AMD=0x1002, Intel=0x8086; the software/WARP adapter is skipped.
+#[cfg(target_os = "windows")]
+fn windows_gpu_vendor() -> Option<GpuVendor> {
+    use std::sync::OnceLock;
+    use windows::Win32::Graphics::Dxgi::{
+        CreateDXGIFactory1, IDXGIFactory1, DXGI_ADAPTER_FLAG_SOFTWARE,
+    };
+    static CACHE: OnceLock<Option<GpuVendor>> = OnceLock::new();
+    // SAFETY: `CreateDXGIFactory1` returns a fresh owned `IDXGIFactory1` COM object (refcounted by the
+    // windows-rs wrapper, Released when the local drops); `.ok()?` bails on failure so `factory` is a
+    // valid interface before any use. `EnumAdapters1(i)` hands back the i-th adapter as an owned
+    // `IDXGIAdapter1` (or an error past the last adapter, which ends the loop). `GetDesc1()` returns the
+    // `DXGI_ADAPTER_DESC1` by value (no out-pointer), so reading `desc.Flags`/`desc.VendorId` is plain
+    // field access. Every call only touches COM objects this closure owns; the `OnceLock` runs the
+    // closure once (no data race) and all interfaces are Released as the locals drop. No raw pointer is
+    // dereferenced and nothing is aliased.
+    *CACHE.get_or_init(|| unsafe {
+        let factory: IDXGIFactory1 = CreateDXGIFactory1().ok()?;
+        let mut i = 0u32;
+        while let Ok(adapter) = factory.EnumAdapters1(i) {
+            i += 1;
+            // windows-rs 0.62: GetDesc1 returns the desc by value (no out-param).
+            let Ok(desc) = adapter.GetDesc1() else {
+                continue;
+            };
+            if (desc.Flags & DXGI_ADAPTER_FLAG_SOFTWARE.0 as u32) != 0 {
+                continue; // skip the Microsoft Basic Render / WARP adapter
+            }
+            match desc.VendorId {
+                0x10DE => return Some(GpuVendor::Nvidia),
+                0x1002 => return Some(GpuVendor::Amd),
+                0x8086 => return Some(GpuVendor::Intel),
+                _ => continue,
+            }
+        }
+        None
+    })
+}
+
+/// Probe the active Windows AMF/QSV backend for its encodable codecs (cached; opens a tiny encoder
+/// per codec, once). Mirrors [`vaapi_codec_support`]; called only when [`windows_backend_is_ffmpeg`]
+/// is true. AV1 is narrow (AMD RDNA3+, Intel Arc/Xe2+), so it must be probed, not assumed.
+#[cfg(all(target_os = "windows", feature = "amf-qsv"))]
+pub fn windows_codec_support() -> CodecSupport {
+    use std::sync::OnceLock;
+    static CACHE: OnceLock<CodecSupport> = OnceLock::new();
+    *CACHE.get_or_init(|| {
+        let vendor = match windows_resolved_backend() {
+            WindowsBackend::Qsv => ffmpeg_win::WinVendor::Qsv,
+            _ => ffmpeg_win::WinVendor::Amf,
+        };
+        let caps = CodecSupport {
+            h264: ffmpeg_win::probe_can_encode(vendor, Codec::H264),
+            h265: ffmpeg_win::probe_can_encode(vendor, Codec::H265),
+            av1: ffmpeg_win::probe_can_encode(vendor, Codec::Av1),
+        };
+        tracing::info!(
+            backend = ?vendor,
+            h264 = caps.h264,
+            h265 = caps.h265,
+            av1 = caps.av1,
+            "Windows AMF/QSV encode capabilities probed"
+        );
+        caps
+    })
+}
+
+// Goal-1 stage 6: GPU/CPU encoders confined to `encode/windows/` (NVENC, AMF/QSV ffmpeg, software) and
+// `encode/linux/` (NVENC/CUDA + VAAPI); `#[path]` keeps the `crate::encode::*` module names flat.
+#[cfg(all(target_os = "windows", feature = "amf-qsv"))]
+#[path = "encode/windows/ffmpeg_win.rs"]
+mod ffmpeg_win;
 #[cfg(target_os = "linux")]
 mod linux;
 #[cfg(all(target_os = "windows", feature = "nvenc"))]
+#[path = "encode/windows/nvenc.rs"]
 mod nvenc;
 #[cfg(target_os = "windows")]
+#[path = "encode/windows/sw.rs"]
 mod sw;
 #[cfg(target_os = "linux")]
+#[path = "encode/linux/vaapi.rs"]
 mod vaapi;
 
 #[cfg(test)]

crates/punktfunk-host/src/encode/linux/mod.rs

@@ -8,6 +8,8 @@
 //! does *not* accept — we expand it to `rgb0` (one padding byte/pixel, no colour math).
 //! The encoder is opened *without* a global header so VPS/SPS/PPS are emitted in-band on
 //! every IDR — the output is both a playable raw Annex-B stream and self-contained AUs.
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
+#![deny(clippy::undocumented_unsafe_blocks)]
 
 use super::{Codec, EncodedFrame, Encoder};
 use crate::capture::{CapturedFrame, FramePayload, PixelFormat};
@@ -79,6 +81,12 @@ impl CudaHw {
 
 impl Drop for CudaHw {
     fn drop(&mut self) {
+        // SAFETY: `frames_ref`/`device_ref` are the two non-null `AVBufferRef`s `CudaHw::new` created
+        // (it bails before returning `Self` if either alloc fails, so a live `CudaHw` always holds
+        // both). `av_buffer_unref` drops one reference and nulls the pointer through the `&mut`. This
+        // `Drop` runs exactly once and `CudaHw` owns these refs exclusively → no double-free /
+        // use-after-free. Frames are unref'd before the device (the frames ctx internally refs the
+        // device; refcounted, so the order is sound regardless).
         unsafe {
             ffi::av_buffer_unref(&mut self.frames_ref);
             ffi::av_buffer_unref(&mut self.device_ref);
@@ -136,6 +144,13 @@ pub struct NvencEncoder {
 
 // `CudaHw` holds raw `AVBufferRef`s; the encoder lives on a single thread. The CPU encoder is
 // already `Send` via ffmpeg-next; assert it for the CUDA fields too.
+// SAFETY: `NvencEncoder` owns an ffmpeg-next `Encoder`/`VideoFrame` (already `Send`) plus a `CudaHw`
+// holding raw `AVBufferRef`s, which are not `Send` by default. The encoder is owned and driven by
+// exactly ONE thread — the per-session encode thread it is moved to — and is only touched through
+// `&mut self` methods, so it is never aliased or accessed concurrently. The wrapped libav contexts
+// (and the shared `CUcontext` the `CudaHw` references) have no thread affinity, so transferring
+// ownership across threads is sound. This asserts `Send` (transfer) only, extending ffmpeg-next's
+// existing `Send` to the raw CUDA fields; `Sync` (shared `&`) is deliberately NOT implemented.
 unsafe impl Send for NvencEncoder {}
 
 impl NvencEncoder {
@@ -162,6 +177,9 @@ impl NvencEncoder {
         }
         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)
+            // is a valid level with no pointer args, and libav was just initialized by `ffmpeg::init()`
+            // above — always sound.
             unsafe { ffi::av_log_set_level(48) }; // AV_LOG_DEBUG — surface NVENC hw-frame rejects
         }
         let name = codec.nvenc_name();
@@ -195,6 +213,11 @@ impl NvencEncoder {
             .unwrap_or(1.0);
         let vbv_bits = ((bitrate_bps as f64 / fps.max(1) as f64) * vbv_frames as f64)
             .clamp(1.0, i32::MAX as f64);
+        // SAFETY: `video` is the ffmpeg-next encoder builder wrapping a freshly-allocated
+        // `AVCodecContext` that we hold by value and have not opened yet; `video.as_mut_ptr()` returns
+        // that non-null, properly-aligned, exclusively-owned context. Writing the plain `rc_buffer_size`
+        // int field before `open_with` is the supported way to set a field ffmpeg-next exposes no
+        // setter for. Sole owner → no aliasing; synchronous in-bounds scalar write.
         unsafe {
             (*video.as_mut_ptr()).rc_buffer_size = vbv_bits as i32;
         }
@@ -204,6 +227,9 @@ impl NvencEncoder {
         // "freeze". NVENC emits one IDR at stream start, then P-frames only; `forced-idr` (below)
         // turns a client recovery request (RFI, via `request_keyframe`) into an IDR on demand.
         // This is the Moonlight/Sunshine low-latency model.
+        // SAFETY: same `video` builder as above — a non-null, properly-aligned, sole-owned, not-yet-
+        // opened `AVCodecContext`. We write the plain `gop_size` int field (= -1, infinite GOP) before
+        // `open_with`, which ffmpeg-next has no setter for. No aliasing; synchronous scalar write.
         unsafe {
             (*video.as_mut_ptr()).gop_size = -1;
         }
@@ -214,6 +240,10 @@ impl NvencEncoder {
         // RGB-input paths leave these unset (NVENC's internal CSC writes its own VUI). Matches the
         // Windows NV12 path's BT.709 limited-range signalling.
         if matches!(format, PixelFormat::Nv12) {
+            // 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-
+            // Characteristic` variants before `open_with`. Sole owner → no aliasing; synchronous writes.
             unsafe {
                 let raw = video.as_mut_ptr();
                 (*raw).colorspace = ffi::AVColorSpace::AVCOL_SPC_BT709;
@@ -228,7 +258,17 @@ impl NvencEncoder {
         // *before* open (NVENC derives the device from `hw_frames_ctx`).
         let cuda_hw = if cuda {
             let cu_ctx = crate::zerocopy::cuda::context().context("shared CUDA context")?;
+            // SAFETY: `CudaHw::new` (an `unsafe fn`) requires libav initialized (the `ffmpeg::init()`
+            // above ran) and a valid `CUcontext`; `cu_ctx` is the shared importer context from
+            // `zerocopy::cuda::context()?`, non-null on the `Ok` path. `nvenc_pixel` is a valid `Pixel`
+            // and `width`/`height` are the validated positive dims. It returns a RAII `CudaHw` wrapping
+            // (not owning) `cu_ctx` and owning two `AVBufferRef`s freed on drop.
             let hw = unsafe { CudaHw::new(cu_ctx, nvenc_pixel, width, height)? };
+            // SAFETY: `raw = video.as_mut_ptr()` is the non-null, sole-owned, not-yet-opened
+            // `AVCodecContext`. We set `pix_fmt = CUDA` and attach NEW refs (`av_buffer_ref`) of
+            // `hw.device_ref`/`hw.frames_ref` — both non-null (`CudaHw::new` guarantees) and from the
+            // live `hw`, which is moved into `NvencEncoder.cuda` next to `enc` and so outlives the
+            // encoder. The context owns its own refs (freed when the context closes). No aliasing.
             unsafe {
                 let raw = video.as_mut_ptr();
                 (*raw).pix_fmt = ffi::AVPixelFormat::AV_PIX_FMT_CUDA;
@@ -428,6 +468,19 @@ impl NvencEncoder {
         // The device→device copy below uses our shared context directly; make it current on the
         // encode thread (ffmpeg pushes its own around the pool alloc, so order is fine).
         crate::zerocopy::cuda::make_current().context("CUDA context current (encode thread)")?;
+        // SAFETY: `frames_ref` is the non-null CUDA frames ctx from `self.cuda` (unwrapped via
+        // `.context(..)?` above), and the shared CUDA context was just made current on THIS thread
+        // (`make_current()?`), the precondition for the device-pointer copies below.
+        //  * `av_frame_alloc` → `f` (null-checked). `av_hwframe_get_buffer(frames_ref, f, 0)` fills `f`
+        //    with a pooled CUDA surface (sets `data[]`/`linesize[]`/`buf[0]`/`hw_frames_ctx`); on
+        //    failure we free `f` and bail.
+        //  * For NV12 we read `(*f).data[0..2]` / `linesize[0..2]` (Y + interleaved UV), else
+        //    `data[0]`/`linesize[0]` — in-struct fields of the non-null `f`, valid for the surface dims
+        //    ffmpeg allocated — and pass them to the cuda copy helpers, which device→device copy `buf`
+        //    (the imported `DeviceBuffer`, owned by the caller and live for this call) into the surface.
+        //  * On copy error we free `f` and return. Otherwise we write `pts`/`pict_type` through `f` and
+        //    `avcodec_send_frame` it into the live owned `self.enc` context (which takes its own ref of
+        //    the pooled surface), then free our `f` ref exactly once. Single-threaded encoder → no race.
         unsafe {
             let mut f = ffi::av_frame_alloc();
             if f.is_null() {

crates/punktfunk-host/src/encode/linux/vaapi.rs

@@ -19,6 +19,8 @@
 //! hwdevice/hwframes/buffersrc/buffersink calls go through `ffmpeg::ffi` (= `ffmpeg_sys_next`),
 //! as the CUDA encode path and the clients' decode paths already do. The encoder is opened
 //! *without* a global header, so VPS/SPS/PPS are in-band on every IDR.
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
+#![deny(clippy::undocumented_unsafe_blocks)]
 
 use super::{Codec, EncodedFrame, Encoder};
 use crate::capture::{CapturedFrame, DmabufFrame, FramePayload, PixelFormat};
@@ -133,6 +135,14 @@ pub fn probe_can_encode(codec: Codec) -> bool {
     if ffmpeg::init().is_err() {
         return false;
     }
+    // SAFETY: `ffmpeg::init()` returned Ok above, so libav is initialized. `av_log_get_level`/
+    // `av_log_set_level` only read/write libav's global integer log level (no pointer args) and are
+    // always sound to call post-init. `VaapiHw::new` (an `unsafe fn`) builds a VAAPI device + NV12
+    // frames pool from the literal NV12/640x480/pool=2 args and hands back a RAII handle that unrefs
+    // both `AVBufferRef`s on drop. `open_vaapi_encoder` (an `unsafe fn`) borrows `hw.device_ref`/
+    // `hw.frames_ref` — the two non-null refs `VaapiHw::new` just created — and `av_buffer_ref`s them
+    // into the encoder; `hw` is a live local for the whole match arm, so the borrows outlive the
+    // synchronous call, and both `hw` and the probe encoder are dropped (RAII) when the arm ends.
     unsafe {
         // A missing VA device (non-VAAPI host, GPU-less CI) is an expected probe outcome — quiet
         // ffmpeg's "No VA display found" error for the probe, then restore the level.
@@ -224,6 +234,12 @@ impl VaapiHw {
 
 impl Drop for VaapiHw {
     fn drop(&mut self) {
+        // SAFETY: `frames_ref`/`device_ref` are the two non-null `AVBufferRef`s `VaapiHw::new`
+        // created (it bails before constructing `Self` if either alloc fails, so a live `VaapiHw`
+        // always holds both). `av_buffer_unref` drops one reference and nulls the pointer through the
+        // `&mut`. This `Drop` runs exactly once and `VaapiHw` owns these refs exclusively, so there
+        // is no double-free / use-after-free. Frames are unref'd before the device because the frames
+        // ctx internally holds a ref on the device (refcounted, so the order is sound either way).
         unsafe {
             ffi::av_buffer_unref(&mut self.frames_ref);
             ffi::av_buffer_unref(&mut self.device_ref);
@@ -252,7 +268,16 @@ impl CpuInner {
     ) -> Result<Self> {
         let src_pixel = vaapi_sws_src(format)?;
         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)? };
+        // 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
+        // the encoder holds its own references; `hw` is also moved into the returned `CpuInner` next to
+        // `enc`, keeping the device/frames alive for the encoder's whole lifetime.
         let enc = unsafe {
             open_vaapi_encoder(
                 codec,
@@ -266,6 +291,12 @@ impl CpuInner {
         };
         // swscale RGB→NV12, BT.709 limited (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.
         let sws = unsafe {
             ffi::sws_getContext(
                 width as c_int,
@@ -283,10 +314,23 @@ impl CpuInner {
         if sws.is_null() {
             bail!("sws_getContext(RGB→NV12) failed");
         }
+        // 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.
         unsafe {
             let cs709 = ffi::sws_getCoefficients(SWS_CS_ITU709);
             ffi::sws_setColorspaceDetails(sws, cs709, 1, cs709, 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.
         let nv12 = unsafe {
             let f = ffi::av_frame_alloc();
             if f.is_null() {
@@ -329,6 +373,18 @@ impl CpuInner {
         let h = self.height as usize;
         let src_row = w * self.src_format.bytes_per_pixel();
         anyhow::ensure!(bytes.len() >= src_row * h, "captured buffer too small");
+        // SAFETY: The `ensure!`s above guarantee `format == self.src_format` and
+        // `bytes.len() >= src_row * h`. `sws_scale` reads `h` rows of `src_row` bytes from
+        // `src_data[0] = bytes.as_ptr()` (the other planes null/0 — packed RGB is single-plane), all
+        // in bounds; `bytes`, `src_data`, `src_stride` are live locals for this synchronous call.
+        // `self.sws` is the non-null context built in `open`; it writes into `self.nv12` (a non-null
+        // owned frame whose `data`/`linesize` in-struct arrays were sized by `av_frame_get_buffer`).
+        // `av_frame_alloc` (null-checked) yields a fresh `hwf`; `av_hwframe_get_buffer` pulls a pooled
+        // VAAPI surface from the live non-null `self.hw.frames_ref`; `av_hwframe_transfer_data` uploads
+        // the staged NV12 into it — both frames live, failures free `hwf` and bail. We then write
+        // `pts`/`pict_type` through the non-null `hwf` and `avcodec_send_frame` it into the live
+        // owned `self.enc` context (which takes its own ref), then free our `hwf` ref exactly once.
+        // The encoder runs only on this thread (see `unsafe impl Send`), so no aliasing/data race.
         unsafe {
             let src_data: [*const u8; 4] = [bytes.as_ptr(), ptr::null(), ptr::null(), ptr::null()];
             let src_stride: [c_int; 4] = [src_row as c_int, 0, 0, 0];
@@ -374,6 +430,12 @@ impl CpuInner {
 
 impl Drop for CpuInner {
     fn drop(&mut self) {
+        // SAFETY: `self.nv12` (an owned `AVFrame`) and `self.sws` (an owned `SwsContext`) are each
+        // freed exactly once here, guarded by `is_null()` so a never-set pointer is skipped (no double
+        // free). `CpuInner` owns both exclusively and `Drop` runs once. `av_frame_free` takes `&mut`
+        // and nulls the pointer. `self.enc`/`self.hw` are freed afterward by their own `Drop` impls;
+        // the encoder holds its own `av_buffer_ref`'d device/frames copies, so field-drop order is
+        // irrelevant to soundness.
         unsafe {
             if !self.nv12.is_null() {
                 ffi::av_frame_free(&mut self.nv12);
@@ -417,6 +479,31 @@ impl DmabufInner {
         let drm_fourcc = crate::zerocopy::drm_fourcc(format)
             .ok_or_else(|| anyhow!("no DRM fourcc for {format:?} (VAAPI zero-copy)"))?;
         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
+        // allocated by the immediately-preceding ffmpeg call and null-checked, or an in-struct field of
+        // such an object:
+        //  * `node` is a `CString` (from `render_node`) live for the whole block; its `.as_ptr()` is a
+        //    NUL-terminated path read only during `av_hwdevice_ctx_create`.
+        //  * `av_hwdevice_ctx_create(&mut drm_device, DRM, …)` / `…_create_derived(&mut vaapi_device,
+        //    VAAPI, drm_device, …)`: on `r < 0` the out-param stays null and we bail (the derive path
+        //    unrefs `drm_device` first); on success each is a non-null owned `AVBufferRef`.
+        //  * `av_hwframe_ctx_alloc(drm_device)` → `drm_frames` (null-checked); `(*drm_frames).data` is
+        //    its `AVHWFramesContext` payload, written before `av_hwframe_ctx_init`.
+        //  * `avfilter_graph_alloc` → `graph` (null-checked); `avfilter_get_by_name` returns a static
+        //    const `AVFilter` (process-lifetime) or null; `avfilter_graph_alloc_filter` allocates each
+        //    filter ctx inside `graph`; the four are null-checked together. `inst`/arg strings are
+        //    'static C literals.
+        //  * `(*hwmap/scale).hw_device_ctx = av_buffer_ref(vaapi_device)` attaches a NEW ref owned by
+        //    the filter (freed by `avfilter_graph_free`); our `vaapi_device` ref is untouched.
+        //  * `av_buffersink_get_hw_frames_ctx(sink)` → `nv12_ctx` is a borrowed ref owned by the sink,
+        //    valid while `graph` lives (and `graph` is moved into the returned `DmabufInner`).
+        //  * `open_vaapi_encoder` borrows `vaapi_device` (our live owned ref) and `nv12_ctx` (sink's
+        //    live ref) and `av_buffer_ref`s both into the encoder.
+        // Every early-error path unref's the allocated buffers and frees the graph in the right order
+        // before bailing; on success the four `AVBufferRef`s + `graph` + `src`/`sink` are moved into
+        // `DmabufInner` and freed in its `Drop`. (Two non-UB leaks noted below: `av_buffersrc_*` and
+        // the final `?`.)
         unsafe {
             // DRM device (source dmabuf frames) + a VAAPI device derived from it (same GPU) for
             // hwmap/scale_vaapi/the encoder.
@@ -509,7 +596,12 @@ impl DmabufInner {
                 num: 1,
                 den: fps as c_int,
             };
-            (*par).hw_frames_ctx = ffi::av_buffer_ref(drm_frames);
+            // Assign `drm_frames` BORROWED (no extra ref): `av_buffersrc_parameters_set` takes its
+            // own ref of `par->hw_frames_ctx` (via av_buffer_replace), and `av_free(par)` frees only
+            // the struct, not the ref. Our single owned `drm_frames` ref is retained, lives in
+            // `DmabufInner`, and is unref'd in `Drop`. Wrapping it in `av_buffer_ref` here would leak
+            // that extra ref every session (the persistent listener would accumulate them).
+            (*par).hw_frames_ctx = drm_frames;
             let r = ffi::av_buffersrc_parameters_set(src, par);
             ffi::av_free(par as *mut _);
             if r < 0 {
@@ -564,7 +656,12 @@ impl DmabufInner {
                 ffi::av_buffer_unref(&mut drm_device);
                 bail!("filter sink has no VAAPI frames context");
             }
-            let enc = open_vaapi_encoder(
+            // On encoder-open failure, free the graph + our owned buffer refs before bailing (matching
+            // every error path above) so a failed session doesn't leak them. `nv12_ctx` is borrowed
+            // from the sink (owned by `graph`), so `avfilter_graph_free` reclaims it — don't unref it
+            // separately. On success the encoder takes its own ref of `vaapi_device`, and `drm_frames`/
+            // `vaapi_device`/`drm_device`/`graph` move into `DmabufInner` (freed in `Drop`).
+            let enc = match open_vaapi_encoder(
                 codec,
                 width,
                 height,
@@ -572,7 +669,16 @@ impl DmabufInner {
                 bitrate_bps,
                 vaapi_device,
                 nv12_ctx,
-            )?;
+            ) {
+                Ok(enc) => enc,
+                Err(e) => {
+                    ffi::avfilter_graph_free(&mut graph);
+                    ffi::av_buffer_unref(&mut drm_frames);
+                    ffi::av_buffer_unref(&mut vaapi_device);
+                    ffi::av_buffer_unref(&mut drm_device);
+                    return Err(e);
+                }
+            };
 
             tracing::info!(
                 encoder = codec.vaapi_name(),
@@ -600,6 +706,23 @@ impl DmabufInner {
             dmabuf.fourcc,
             self.fourcc
         );
+        // SAFETY: The `ensure!` above checked `dmabuf.fourcc == self.fourcc`.
+        //  * `std::mem::zeroed::<AVDRMFrameDescriptor>()` is sound: it is a `#[repr(C)]` POD of ints and
+        //    nested int-struct arrays (no `NonNull`/refs), for which all-zero is a valid bit pattern;
+        //    `Box` puts it on the heap with a unique owner.
+        //  * `dmabuf.fd.as_raw_fd()` is the fd of the caller's `&DmabufFrame`, which owns it for the
+        //    whole synchronous `submit`; we describe one object/layer/plane from its
+        //    fourcc/modifier/offset/stride and pass `object.size = 0` (ffmpeg queries the real size).
+        //  * `av_frame_alloc` → `drm` (null-checked); we set its scalar fields and
+        //    `hw_frames_ctx = av_buffer_ref(self.drm_frames)` (new ref of the live owned ctx).
+        //  * `data[0] = Box::into_raw(desc)` transfers the box into the frame; `buf[0] =
+        //    av_buffer_create(.., free_desc, ..)` registers a destructor that reclaims it exactly once
+        //    when the buffer's refcount hits zero — matched alloc/free, no leak/double-free.
+        //  * `av_buffersrc_add_frame_flags(self.src, drm, KEEP_REF)` pushes a ref into the live
+        //    buffersrc; KEEP_REF keeps our own `drm` ref, which we then `av_frame_free`. We pull the
+        //    converted surface with `av_buffersink_get_frame(self.sink, nv12)` BEFORE returning, so the
+        //    dmabuf (owned by the caller) is read while still valid. `nv12` is sent into the live owned
+        //    `self.enc` (takes its own ref) and our ref freed once. Single-threaded encoder → no race.
         unsafe {
             // Build a DRM-PRIME AVFrame describing the dmabuf (one object/fd, one layer/plane).
             let mut desc: Box<ffi::AVDRMFrameDescriptor> = Box::new(std::mem::zeroed());
@@ -626,6 +749,11 @@ impl DmabufInner {
             // Own the descriptor so it frees with the frame (the fd is owned by the DmabufFrame,
             // which outlives this call — the graph reads the surface before submit returns).
             extern "C" fn free_desc(_opaque: *mut std::ffi::c_void, data: *mut u8) {
+                // SAFETY: `data` is exactly the pointer produced by `Box::into_raw(desc)` and passed as
+                // `av_buffer_create`'s first arg, which libav hands back verbatim to this callback. It
+                // is a valid, uniquely-owned `Box<AVDRMFrameDescriptor>` raw pointer; libav invokes the
+                // callback exactly once (when the last buffer ref drops), so `from_raw` + `drop`
+                // reclaims it exactly once — no double-free. `_opaque` is unused (we passed null).
                 unsafe { drop(Box::from_raw(data as *mut ffi::AVDRMFrameDescriptor)) };
             }
             (*drm).buf[0] = ffi::av_buffer_create(
@@ -673,6 +801,13 @@ impl DmabufInner {
 
 impl Drop for DmabufInner {
     fn drop(&mut self) {
+        // SAFETY: `graph`/`drm_frames`/`vaapi_device`/`drm_device` are the non-null objects
+        // `DmabufInner::open` built and moved into `self` (open bails before constructing `Self` if any
+        // alloc fails). `avfilter_graph_free` frees the graph (and the per-filter device refs it owns);
+        // each `av_buffer_unref` drops one ref and nulls the pointer via `&mut`. `DmabufInner` owns all
+        // four exclusively and `Drop` runs once → no double-free/use-after-free. The graph is freed
+        // first (it holds refs on the devices), then frames, then the derived VAAPI device, then DRM.
+        // (`self.enc` drops via ffmpeg-next afterward, holding its own refs.)
         unsafe {
             ffi::avfilter_graph_free(&mut self.graph);
             ffi::av_buffer_unref(&mut self.drm_frames);
@@ -703,6 +838,13 @@ pub struct VaapiEncoder {
 }
 
 // Raw FFI pointers; the encoder lives on a single thread (same contract as `NvencEncoder`).
+// SAFETY: `VaapiEncoder`'s `Inner` holds raw FFI pointers (`SwsContext`, `AVFrame`, `AVBufferRef`,
+// `AVFilterContext`, `AVCodecContext`) that are not `Send` by default. The encoder is owned and
+// driven by exactly ONE thread — the host's per-session encode thread it is moved (transferred) to —
+// and is only ever touched through `&mut self` methods, so it is never aliased or accessed
+// concurrently from two threads. None of the underlying libav/libswscale objects have thread
+// affinity (they are not thread-local), so transferring ownership across threads is sound. This
+// asserts `Send` (transfer) only; `Sync` (shared `&`) is deliberately NOT implemented.
 unsafe impl Send for VaapiEncoder {}
 
 impl VaapiEncoder {
@@ -720,6 +862,9 @@ impl VaapiEncoder {
         }
         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)
+            // is a valid level and there are no pointer args. libav was just initialized by the
+            // `ffmpeg::init()` above, so the call is always sound.
             unsafe { ffi::av_log_set_level(48) };
         }
         // Validate the codec/format up front so a bad request fails at open, not on the first frame.

crates/punktfunk-host/src/encode/windows/nvenc.rs

@@ -13,7 +13,10 @@
 //! Needs a real NVIDIA GPU at runtime (session creation fails otherwise) — compiles GPU-less, but
 //! `open`/`submit` only succeed on a GPU box. The software encoder (`super::sw`) is the fallback.
 
-use super::{Codec, EncodedFrame, Encoder};
+// Every `unsafe` block / impl in this file carries a `// SAFETY:` proof; enforce it.
+#![deny(clippy::undocumented_unsafe_blocks)]
+
+use super::{Codec, EncodedFrame, Encoder, EncoderCaps};
 use crate::capture::{CapturedFrame, FramePayload, PixelFormat};
 use anyhow::{anyhow, bail, Context, Result};
 use std::collections::{HashMap, VecDeque};
@@ -88,7 +91,15 @@ pub struct NvencD3d11Encoder {
     init_device: *mut c_void,
 }
 
-// Raw NVENC handle + COM ptrs; confined to the single encode thread (like the Linux encoder).
+// SAFETY: the `!Send` fields are the raw NVENC session/device handles (`encoder`, `init_device`),
+// the raw NVENC bitstream/registered/mapped pointers carried in `bitstreams`/`regs`/`pending`, and
+// the `ID3D11Texture2D` COM refs — none of which may be touched concurrently from two threads. This
+// encoder is owned by exactly one thread: it is moved onto the host encode thread once at
+// construction, and every NVENC call and D3D11 access happens only from that thread thereafter
+// (`submit`/`poll`/`invalidate_ref_frames`/`Drop` all run there, like the Linux encoder). Moving the
+// handles across that single ownership-transfer boundary is sound because no NVENC/D3D11 call is in
+// flight during the move and the session and its D3D11 immediate context are never shared (`&`) or
+// used concurrently — so `Send` introduces no data race on the non-`Send` fields.
 unsafe impl Send for NvencD3d11Encoder {}
 
 impl NvencD3d11Encoder {
@@ -403,6 +414,17 @@ impl NvencD3d11Encoder {
 
     /// Lazily create the session on the first frame's D3D11 device (so capture + encode share it).
     fn init_session(&mut self, device: &ID3D11Device) -> Result<()> {
+        // SAFETY: every call below goes through a function pointer resolved once from the loaded
+        // `nvidia_video_codec_sdk::ENCODE_API` (`nvEncodeAPI`) table, or through this type's own
+        // `unsafe fn`s whose contract is met here. `query_caps`/`try_open_session` receive `device`,
+        // the live `ID3D11Device` the caller pulled off the first frame; each returns either a valid
+        // open NVENC session handle or an `Err`. `destroy_encoder` is only ever called on a handle a
+        // `try_open_session` just returned (and `best` only when `!best.is_null()`), so it never frees
+        // a dangling or null session. `create_bitstream_buffer` is passed `enc` — the one chosen live
+        // session — and `&mut cb`, a `#[repr(C)] NV_ENC_CREATE_BITSTREAM_BUFFER` whose `version` is set
+        // to `NV_ENC_CREATE_BITSTREAM_BUFFER_VER`; `cb` lives across the synchronous call and its
+        // returned `bitstreamBuffer` is copied into `self.bitstreams` before `cb` drops. No handle
+        // escapes the encode thread.
         unsafe {
             // Probe real GPU caps first (max dims / 10-bit / custom-VBV / RFI) so the config below is
             // gated on what this card supports and an out-of-range mode fails with a clear error
@@ -589,6 +611,11 @@ impl Encoder for NvencD3d11Encoder {
                 new = format!("{}x{}", captured.width, captured.height),
                 "NVENC: capture device/size/HDR changed — re-initializing session"
             );
+            // SAFETY: `teardown` (an `unsafe fn`) requires the encode thread with no NVENC call in
+            // flight and a session whose cached regs/bitstreams/pending all belong to `self.encoder`.
+            // All hold: this is the synchronous encode thread, `self.inited` so `self.encoder` is the
+            // live session every cached resource was created against, and the previous frame's encode
+            // has already been polled (synchronous submit→poll), so nothing is mid-encode.
             unsafe { self.teardown() };
         }
         if !self.inited {
@@ -609,7 +636,14 @@ impl Encoder for NvencD3d11Encoder {
                     self.bit_depth = 10;
                     nv::NV_ENC_BUFFER_FORMAT::NV_ENC_BUFFER_FORMAT_ABGR10
                 }
-                PixelFormat::Nv12 => nv::NV_ENC_BUFFER_FORMAT::NV_ENC_BUFFER_FORMAT_NV12,
+                PixelFormat::Nv12 => {
+                    // NV12 is 8-bit 4:2:0. Force 8-bit so a transition from a prior P010 (10-bit) session
+                    // — or a 10-bit-negotiated client on an SDR display — re-inits at the matching depth.
+                    // Unlike ARGB (which NVENC upconverts to Main10), NV12 cannot feed a 10-bit session:
+                    // `register_resource` rejects it as InvalidParam (the HDR→SDR-toggle stream drop).
+                    self.bit_depth = 8;
+                    nv::NV_ENC_BUFFER_FORMAT::NV_ENC_BUFFER_FORMAT_NV12
+                }
                 _ => nv::NV_ENC_BUFFER_FORMAT::NV_ENC_BUFFER_FORMAT_ARGB,
             };
             let device = frame.device.clone();
@@ -618,6 +652,21 @@ impl Encoder for NvencD3d11Encoder {
         }
         let slot = self.next % POOL;
         self.next += 1;
+        // SAFETY: every NVENC call goes through a function pointer from the loaded `ENCODE_API` table
+        // and takes `self.encoder`, the live session `init_session` just established (non-null on the
+        // path that reaches here). `NV_ENC_REGISTER_RESOURCE rr` has `version =
+        // NV_ENC_REGISTER_RESOURCE_VER` and registers `frame.texture` — a D3D11 texture from
+        // `frame.device`, which is the SAME device the session was opened against (any device change
+        // tears down and re-inits above, so `init_device == frame.device.as_raw()` here); the cloned
+        // `ID3D11Texture2D` is kept alive in `regs` so NVENC's registration never outlives the texture.
+        // `mp` (`NV_ENC_MAP_INPUT_RESOURCE`, version set) maps that registration and the map is recorded
+        // in `pending` to be unmapped exactly once in `poll`/`teardown`. `pic` (`NV_ENC_PIC_PARAMS`,
+        // version set) points `inputBuffer` at `mp.mappedResource` and `outputBitstream` at the live
+        // pool bitstream `bitstreams[slot]`; the optional SEI scratch (`mastering_sei`/`cll_sei` and the
+        // `sei` Vec whose `as_mut_ptr()` is written into the codec union) are stack locals that outlive
+        // the synchronous `encode_picture`. Every `#[repr(C)]` param is a live local borrowed `&mut`
+        // for the duration of its one synchronous call. (In-place encode without `CopyResource` is
+        // sound because the encode loop is synchronous, as the module docs state.)
         unsafe {
             // Register the capturer's texture with NVENC once (cached by raw pointer), then encode it
             // IN PLACE — no `CopyResource` into an encoder-owned pool. This is the zero-copy win: the
@@ -732,6 +781,15 @@ impl Encoder for NvencD3d11Encoder {
         self.force_kf = true;
     }
 
+    fn caps(&self) -> EncoderCaps {
+        // RFI is probed once at open (`rfi_supported`); HDR SEI rides keyframes whenever the
+        // session is in HDR mode. Both are the real capabilities the session glue routes on.
+        EncoderCaps {
+            supports_rfi: self.rfi_supported,
+            supports_hdr_metadata: self.hdr,
+        }
+    }
+
     fn set_hdr_meta(&mut self, meta: Option<punktfunk_core::quic::HdrMeta>) {
         // Stored and emitted as in-band SEI on the next keyframe (see `submit`). Cheap to call every
         // frame; only changes when the source is regraded or HDR toggles.
@@ -765,6 +823,12 @@ impl Encoder for NvencD3d11Encoder {
         // We tag each input with `inputTimeStamp = frame_idx` (0,1,2,…), which is also the client's
         // frame number (the packetizer numbers frames in submit order), so the client's lost-frame
         // range maps 1:1 onto the timestamps NVENC invalidates here.
+        // SAFETY: `invalidate_ref_frames` is a function pointer from the loaded `ENCODE_API` table.
+        // `self.encoder` was checked non-null at the top of this fn and is the live session; this runs
+        // on the encode thread (like submit/poll), so there is no concurrent NVENC use. Each `ts` was
+        // clamped to `[oldest_in_dpb, frame_idx - 1]` above, so it names a frame still in the session's
+        // DPB; the call passes only that `u64` timestamp (no struct), so there is no struct-size or
+        // lifetime concern.
         unsafe {
             for ts in first..=last {
                 if (API.invalidate_ref_frames)(self.encoder, ts as u64)
@@ -783,6 +847,16 @@ impl Encoder for NvencD3d11Encoder {
         let Some((bs, map, pts_ns)) = self.pending.pop_front() else {
             return Ok(None);
         };
+        // SAFETY: a non-empty `pending` implies `submit` ran, so `self.encoder` is the live session
+        // (`teardown` clears `pending` whenever it nulls the handle); all calls below use function
+        // pointers from the loaded `ENCODE_API` table on the encode thread. `NV_ENC_LOCK_BITSTREAM lock`
+        // (version = `NV_ENC_LOCK_BITSTREAM_VER`) locks `bs`, a pool bitstream a prior `encode_picture`
+        // targeted; `lock_bitstream` blocks until that encode finishes, so on success
+        // `lock.bitstreamBufferPtr` is non-null and points at `lock.bitstreamSizeInBytes` bytes of
+        // NVENC-owned, CPU-readable output valid until `unlock_bitstream`. The `from_raw_parts` slice is
+        // only read (copied via `to_vec()`) BEFORE `unlock_bitstream(bs)` — lock and unlock pair on the
+        // same buffer — so it never outlives the lock. `map` (the input resource paired with `bs` in
+        // `pending`) is unmapped here, after the encode completed, exactly once.
         unsafe {
             let mut lock = nv::NV_ENC_LOCK_BITSTREAM {
                 version: nv::NV_ENC_LOCK_BITSTREAM_VER,
@@ -822,6 +896,11 @@ impl Encoder for NvencD3d11Encoder {
 
 impl Drop for NvencD3d11Encoder {
     fn drop(&mut self) {
+        // SAFETY: `teardown` (an `unsafe fn`) needs the owning thread with no NVENC call in flight and
+        // a session whose cached resources all belong to `self.encoder`. At Drop this encoder is owned
+        // exclusively (no other reference can exist), runs on the encode thread it was confined to, and
+        // `teardown` early-returns when `self.encoder` is null; otherwise every cached reg/bitstream/
+        // pending was created against that live session. It runs exactly once (here).
         unsafe { self.teardown() };
     }
 }

crates/punktfunk-host/src/encode/windows/sw.rs

@@ -2,6 +2,8 @@
 //! fallback when NVENC is unavailable). Low-latency screen-content config: single-reference,
 //! no B-frames (Baseline), bitrate rate-control, in-band SPS/PPS each IDR, BT.709 limited range.
 //! Synchronous: `submit` encodes immediately and stashes the AU for `poll` (no internal queue).
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
+#![deny(clippy::undocumented_unsafe_blocks)]
 
 use super::{EncodedFrame, Encoder};
 use crate::capture::{CapturedFrame, FramePayload, PixelFormat};
@@ -30,6 +32,12 @@ pub struct OpenH264Encoder {
 }
 
 // openh264's Encoder holds a raw C handle (not auto-Send); it lives on the single encode thread.
+// SAFETY: `OpenH264Encoder` wraps `Oh264` (openh264's `Encoder`), which holds a raw C handle to the
+// openh264 `ISVCEncoder` and is not auto-`Send`; the other fields (`YUVBuffer`, `Vec`, scalars,
+// `Option<EncodedFrame>`) are plain owned data. The session creates the encoder, calls
+// `submit`/`poll`/`flush`, and drops it all on one dedicated encode thread, never sharing it by
+// reference across threads, so the C handle is only ever touched from a single thread. Moving the
+// whole value to that thread is therefore sound — there is no concurrent access to the handle.
 unsafe impl Send for OpenH264Encoder {}
 
 impl OpenH264Encoder {

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

@@ -17,6 +17,9 @@
 //! data packets are consumed immediately and missing parity only costs loss recovery — so
 //! the validated stereo path stays byte-identical (data packets only, exactly as before).
 
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it.
+#![deny(clippy::undocumented_unsafe_blocks)]
+
 #[cfg(any(target_os = "linux", target_os = "windows", test))]
 use crate::audio::SAMPLE_RATE;
 #[cfg(any(target_os = "linux", target_os = "windows"))]
@@ -409,7 +412,10 @@ struct MsEncoder {
     st: std::ptr::NonNull<audiopus_sys::OpusMSEncoder>,
 }
 
-// The raw encoder state has no thread affinity; the session owns it on one thread at a time.
+// SAFETY: `MsEncoder` owns a unique `OpusMSEncoder` via `NonNull` (it is neither `Clone` nor
+// `Sync`, so the pointer is never aliased). libopus's multistream encoder state is a self-contained
+// heap allocation with no thread-local or thread-affine state, so moving ownership to another thread
+// is sound; every method takes `&mut self`, keeping access single-threaded at any instant.
 #[cfg(target_os = "linux")]
 unsafe impl Send for MsEncoder {}
 
@@ -418,6 +424,13 @@ impl MsEncoder {
     fn new(layout: &OpusLayout) -> Result<MsEncoder> {
         use std::os::raw::c_int;
         let mut err: c_int = 0;
+        // SAFETY: every scalar arg is a valid libopus input (sample rate, channel/stream/coupled
+        // counts, the RESTRICTED_LOWDELAY application constant). `layout.mapping.as_ptr()` addresses
+        // a 'static slice of exactly `layout.channels` bytes (every `OpusLayout` constant upholds
+        // that), which is the element count `opus_multistream_encoder_create` reads through it, and
+        // `&mut err` is a live local the call writes its status into. libopus copies the mapping into
+        // its own allocation, so the pointer need only be valid for the call; the returned pointer is
+        // null/`OPUS_OK`-checked below before any use.
         let st = unsafe {
             audiopus_sys::opus_multistream_encoder_create(
                 SAMPLE_RATE as i32,
@@ -432,6 +445,11 @@ impl MsEncoder {
         let st = std::ptr::NonNull::new(st)
             .filter(|_| err == audiopus_sys::OPUS_OK)
             .ok_or_else(|| anyhow::anyhow!("opus_multistream_encoder_create failed ({err})"))?;
+        // SAFETY: `st` is the non-null encoder `opus_multistream_encoder_create` just returned, owned
+        // exclusively here. Each `opus_multistream_encoder_ctl` call passes a valid request constant
+        // with the single by-value `c_int` argument that request's variadic ABI expects
+        // (`OPUS_SET_BITRATE_REQUEST` → bitrate, `OPUS_SET_VBR_REQUEST` → 0). No pointer escapes the
+        // call and the encoder outlives it.
         unsafe {
             audiopus_sys::opus_multistream_encoder_ctl(
                 st.as_ptr(),
@@ -453,6 +471,13 @@ impl MsEncoder {
         samples_per_channel: usize,
         out: &mut [u8],
     ) -> Result<usize> {
+        // SAFETY: `self.st` is the live encoder from `new`. libopus reads `samples_per_channel *
+        // channels` f32s through `frame.as_ptr()`; every caller passes a `frame` of exactly that
+        // length together with the matching `samples_per_channel` (`audio_body`'s `frame_len =
+        // samples_per_channel * layout.channels`; the round-trip tests size identically), so the read
+        // stays in bounds. `out.as_mut_ptr()` is written for at most `out.len()` bytes, which is
+        // passed as the capacity bound. Both buffers are live locals outliving this synchronous call;
+        // the return value is range-checked before being used as a length.
         let n = unsafe {
             audiopus_sys::opus_multistream_encode_float(
                 self.st.as_ptr(),
@@ -470,6 +495,9 @@ impl MsEncoder {
 #[cfg(target_os = "linux")]
 impl Drop for MsEncoder {
     fn drop(&mut self) {
+        // SAFETY: `self.st` is the encoder `opus_multistream_encoder_create` returned; this
+        // `MsEncoder` owns it uniquely and `drop` runs exactly once, so the destroy frees it once
+        // with no subsequent use.
         unsafe { audiopus_sys::opus_multistream_encoder_destroy(self.st.as_ptr()) }
     }
 }
@@ -761,6 +789,10 @@ mod tests {
         let client_mapping = client_swap(&digits[3..]);
 
         let mut err = 0i32;
+        // SAFETY: scalar args are valid libopus inputs. `client_mapping.as_ptr()` addresses a
+        // `Vec<u8>` of exactly `ch` entries (derived from the advertised surround-params), which is
+        // the element count the decoder reads through it, and `&mut err` is a live local the call
+        // writes. The returned pointer is `OPUS_OK`/non-null-checked immediately below before use.
         let dec = unsafe {
             audiopus_sys::opus_multistream_decoder_create(
                 SAMPLE_RATE as i32,
@@ -789,6 +821,11 @@ mod tests {
                 }
                 let n = enc.encode_float(&frame, samples, &mut out).unwrap();
                 assert!(n > 0);
+                // SAFETY: `dec` is the non-null decoder asserted above. `out.as_ptr()` is read for
+                // the `n` encoded bytes just produced by `encode_float`; `decoded.as_mut_ptr()` is
+                // written for up to `samples * ch` f32s and `decoded` is exactly that long; `samples`
+                // is the per-channel frame size. All buffers are live locals outliving the call; the
+                // return is checked to equal `samples`.
                 let got = unsafe {
                     audiopus_sys::opus_multistream_decode_float(
                         dec,
@@ -817,6 +854,8 @@ mod tests {
                  (energies: {energy:?})"
             );
         }
+        // SAFETY: `dec` is the decoder `opus_multistream_decoder_create` returned; the test owns it
+        // and destroys it exactly once here, after the final decode — no later use, no double free.
         unsafe { audiopus_sys::opus_multistream_decoder_destroy(dec) };
     }
 
@@ -853,6 +892,9 @@ mod tests {
         let digits: Vec<u8> = s.bytes().map(|b| b - b'0').collect();
         let client_mapping = client_swap(&digits[3..]);
         let mut err = 0i32;
+        // SAFETY: scalar args are valid; `client_mapping.as_ptr()` addresses a 6-entry `Vec<u8>`
+        // (matches the 6-channel layout the decoder reads through it), alive past the call, and
+        // `&mut err` is a live local. The pointer is `OPUS_OK`-checked before use.
         let dec = unsafe {
             audiopus_sys::opus_multistream_decoder_create(
                 48000,
@@ -865,6 +907,10 @@ mod tests {
         };
         assert_eq!(err, audiopus_sys::OPUS_OK);
         let mut pcm = vec![0f32; 240 * 6];
+        // SAFETY: `dec` is the non-null decoder from create. `out.as_ptr()` is read for the CBR
+        // packet length passed in (`*sizes.first()`, a real encoded packet size in `out`);
+        // `pcm.as_mut_ptr()` is written for up to `240 * 6` f32s and `pcm` is exactly that long;
+        // `240` is the per-channel frame size. All buffers are live locals outliving the call.
         let got = unsafe {
             audiopus_sys::opus_multistream_decode_float(
                 dec,
@@ -875,6 +921,7 @@ mod tests {
                 0,
             )
         };
+        // SAFETY: `dec` is owned by the test; destroyed exactly once here after the final decode.
         unsafe { audiopus_sys::opus_multistream_decoder_destroy(dec) };
         assert_eq!(got, 240);
     }

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

@@ -1,7 +1,7 @@
 //! Pairing crypto primitives (control plane only — distinct from `punktfunk_core`'s AES-GCM
 //! data-plane sealing). GameStream pairing uses: AES-128-**ECB** with **no padding**,
 //! SHA-256 (host appversion major ≥ 7), and RSA-PKCS1v15-SHA256 signatures. See the
-//! `serverinfo + pairing` section of `docs/research/gamestream-protocol-research.json`.
+//! `serverinfo + pairing` section of `design/research/gamestream-protocol-research.json`.
 
 use aes::cipher::generic_array::GenericArray;
 use aes::cipher::{BlockDecrypt, BlockEncrypt, KeyInit};

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

@@ -1,7 +1,7 @@
 //! GameStream (P1) control plane — what a stock Moonlight/Artemis client talks to around
 //! the media streams: mDNS discovery, the nvhttp serverinfo + pairing HTTP(S) API, RTSP,
 //! and the ENet control stream. `tokio`/`axum` live here (control plane, I/O-bound — never
-//! the per-frame hot path; that is `punktfunk_core`'s P1 wire codec). See `docs/gamestream-host-plan.md`.
+//! the per-frame hot path; that is `punktfunk_core`'s P1 wire codec). See `design/gamestream-host-plan.md`.
 //!
 //! Status: P1.1 — mDNS `_nvstream._tcp` advertisement + `/serverinfo`. Pairing, RTSP, and
 //! the media streams follow (see the GameStream host task list / plan).
@@ -125,12 +125,21 @@ pub struct AppState {
     /// (avoids a PipeWire stream setup per reconnect); drained on reuse so no stale audio is
     /// sent, dropped + reopened when a session negotiates a different channel count.
     pub audio_cap: std::sync::Arc<std::sync::Mutex<Option<Box<dyn crate::audio::AudioCapturer>>>>,
+    /// Shared streaming-stats recorder (web-console capture/graph). The GameStream encode loop
+    /// reads `is_armed()` per frame and emits samples; the same `Arc` is shared with the mgmt API
+    /// and the native punktfunk/1 loops so one capture spans whichever path is streaming.
+    pub stats: Arc<crate::stats_recorder::StatsRecorder>,
 }
 
 impl AppState {
     /// Fresh control-plane state: no active session; the pairing allow-list is loaded from
-    /// disk (pairings persist across restarts).
-    pub fn new(host: Host, identity: cert::ServerIdentity) -> AppState {
+    /// disk (pairings persist across restarts). `stats` is the shared recorder handed to both the
+    /// mgmt API and the streaming loops.
+    pub fn new(
+        host: Host,
+        identity: cert::ServerIdentity,
+        stats: Arc<crate::stats_recorder::StatsRecorder>,
+    ) -> AppState {
         AppState {
             host,
             identity,
@@ -145,6 +154,7 @@ impl AppState {
             rfi_range: std::sync::Arc::new(std::sync::Mutex::new(None)),
             video_cap: std::sync::Arc::new(std::sync::Mutex::new(None)),
             audio_cap: std::sync::Arc::new(std::sync::Mutex::new(None)),
+            stats,
         }
     }
 }
@@ -166,7 +176,10 @@ pub fn serve(
 ) -> Result<()> {
     let host = Host::detect()?;
     let identity = cert::ServerIdentity::load_or_create().context("host certificate")?;
-    let state = Arc::new(AppState::new(host, identity));
+    // The shared streaming-stats recorder: one handle for the mgmt API, the GameStream encode loop
+    // (via `AppState`), and the native punktfunk/1 loops (passed to `punktfunk1::serve`).
+    let stats = crate::stats_recorder::StatsRecorder::new(crate::stats_recorder::default_dir());
+    let state = Arc::new(AppState::new(host, identity, stats.clone()));
     // The native plane always runs, so the shared native-pairing handle (linking the QUIC ceremony
     // and the management API) always exists.
     let np = Arc::new(
@@ -206,8 +219,8 @@ pub fn serve(
             );
             tokio::try_join!(
                 nvhttp::run(state.clone()),
-                crate::mgmt::run(state.clone(), mgmt, Some(np.clone())),
-                crate::punktfunk1::serve(native_opts, np),
+                crate::mgmt::run(state.clone(), mgmt, Some(np.clone()), stats.clone()),
+                crate::punktfunk1::serve(native_opts, np, stats.clone()),
             )?;
         } else {
             // Secure default: native punktfunk/1 + management API only (no GameStream surface).
@@ -217,8 +230,8 @@ pub fn serve(
                  (GameStream OFF — pass --gamestream for stock-Moonlight compat)"
             );
             tokio::try_join!(
-                crate::mgmt::run(state.clone(), mgmt, Some(np.clone())),
-                crate::punktfunk1::serve(native_opts, np),
+                crate::mgmt::run(state.clone(), mgmt, Some(np.clone()), stats.clone()),
+                crate::punktfunk1::serve(native_opts, np, stats.clone()),
             )?;
         }
         Ok(())

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

@@ -291,7 +291,10 @@ mod tests {
             https_port: HTTPS_PORT,
         };
         let identity = super::super::cert::ServerIdentity::ephemeral().expect("ephemeral identity");
-        Arc::new(AppState::new(host, identity))
+        let stats = crate::stats_recorder::StatsRecorder::new(
+            std::env::temp_dir().join(format!("pf-nvhttp-stats-{}", std::process::id())),
+        );
+        Arc::new(AppState::new(host, identity, stats))
     }
 
     fn fp_of(der: &[u8]) -> String {

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

@@ -1,7 +1,7 @@
 //! The 4-phase GameStream pairing state machine (over HTTP), keyed by `uniqueid`. Proves
 //! both sides know the PIN (via the SHA-256(salt||pin) AES-ECB key) and own their certs
 //! (RSA signatures), then pins the client cert. The final `pairchallenge` happens over
-//! HTTPS (handled in `nvhttp`). Byte-exact spec: `docs/research/…-research.json`.
+//! HTTPS (handled in `nvhttp`). Byte-exact spec: `design/research/…-research.json`.
 
 use super::cert::ServerIdentity;
 use super::crypto;

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

@@ -234,6 +234,7 @@ fn handle_request(req: &Request, state: &AppState) -> String {
                         state.force_idr.clone(),
                         state.rfi_range.clone(),
                         state.video_cap.clone(),
+                        state.stats.clone(),
                     );
                 }
                 Some(_) => tracing::info!("RTSP PLAY — stream already running"),

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

@@ -50,8 +50,28 @@ pub fn serverinfo_xml(host: &Host, https: bool, paired: bool) -> String {
 fn codec_mode_support() -> u32 {
     #[cfg(target_os = "linux")]
     if crate::encode::linux_zero_copy_is_vaapi() {
+        if let Some(m) = probed_mask(crate::encode::vaapi_codec_support()) {
+            return m;
+        }
+    }
+    // Windows AMD/Intel (AMF/QSV): advertise only what the GPU actually encodes (AV1 is narrow, an
+    // old iGPU might lack HEVC). NVENC and the GPU-less software path keep the static superset.
+    #[cfg(all(target_os = "windows", feature = "amf-qsv"))]
+    if crate::encode::windows_backend_is_ffmpeg() {
+        if let Some(m) = probed_mask(crate::encode::windows_codec_support()) {
+            return m;
+        }
+    }
+    SERVER_CODEC_MODE_SUPPORT
+}
+
+/// Turn a probed [`CodecSupport`](crate::encode::CodecSupport) into a `ServerCodecModeSupport` mask,
+/// or `None` if the probe found nothing — meaning the GPU wasn't usable at probe time (GPU-less CI,
+/// a misconfigured/wrong-vendor host), NOT that it encodes zero codecs; the caller then advertises
+/// the static superset (pre-probe behaviour) rather than claiming nothing.
+#[cfg(any(target_os = "linux", all(target_os = "windows", feature = "amf-qsv")))]
+fn probed_mask(caps: crate::encode::CodecSupport) -> Option<u32> {
     use super::{SCM_AV1_MAIN8, SCM_H264, SCM_HEVC};
-        let caps = crate::encode::vaapi_codec_support();
     let mut m = 0;
     if caps.h264 {
         m |= SCM_H264;
@@ -62,15 +82,7 @@ fn codec_mode_support() -> u32 {
     if caps.av1 {
         m |= SCM_AV1_MAIN8;
     }
-        // Only trust a probe that actually found an encoder. An empty result means VAAPI wasn't
-        // usable at probe time (no VA display — a GPU-less CI box, or a misconfigured host), NOT
-        // that the GPU encodes nothing; advertise the static superset (pre-probe behaviour) rather
-        // than claiming zero codecs.
-        if m != 0 {
-            return m;
-        }
-    }
-    SERVER_CODEC_MODE_SUPPORT
+    (m != 0).then_some(m)
 }
 
 #[cfg(test)]

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

@@ -3,6 +3,9 @@
 //! either real portal desktop capture (`PUNKTFUNK_VIDEO_SOURCE=portal`, the portal PipeWire path) or
 //! a synthetic test pattern (default). Runs on its own native thread.
 
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it.
+#![deny(clippy::undocumented_unsafe_blocks)]
+
 use super::video::{FrameType, VideoPacketizer};
 use super::VIDEO_PORT;
 use crate::capture::{self, Capturer, FastSyntheticCapturer};
@@ -45,6 +48,7 @@ pub fn start(
     force_idr: Arc<AtomicBool>,
     rfi_range: RfiSlot,
     video_cap: CapturerSlot,
+    stats: Arc<crate::stats_recorder::StatsRecorder>,
 ) {
     let _ = std::thread::Builder::new()
         .name("punktfunk-video".into())
@@ -57,6 +61,7 @@ pub fn start(
                 &force_idr,
                 &rfi_range,
                 &video_cap,
+                &stats,
             ) {
                 tracing::error!(error = %format!("{e:#}"), "video stream failed");
             }
@@ -65,6 +70,7 @@ pub fn start(
         });
 }
 
+#[allow(clippy::too_many_arguments)]
 fn run(
     cfg: StreamConfig,
     app: Option<&super::apps::AppEntry>,
@@ -72,6 +78,9 @@ fn run(
     force_idr: &AtomicBool,
     rfi_range: &std::sync::Mutex<Option<(i64, i64)>>,
     video_cap: &std::sync::Mutex<Option<Box<dyn Capturer>>>,
+    // Shared stats recorder for the web-console capture/graph. Threaded into `stream_body` (the
+    // encode loop); per-frame sample emission is wired by a later pass.
+    stats: &Arc<crate::stats_recorder::StatsRecorder>,
 ) -> Result<()> {
     // GameStream capture/encode thread: apply Windows session tuning (no-op off Windows).
     crate::session_tuning::on_hot_thread();
@@ -97,12 +106,14 @@ fn run(
     sock.connect(client)
         .context("connect client video endpoint")?;
     tracing::info!(%client, "video: client endpoint learned");
+    // Short label for web-console stats captures: the client's peer IP.
+    let client_label = client.ip().to_string();
 
     // Native client-resolution source: create a compositor virtual output sized to the client's
     // request and capture it (no scaling). Self-contained — deliberately NOT pooled in
     // `video_cap`, since a reconnect at a different resolution needs a freshly-sized output; the
     // output is released when this capturer drops at stream end (RAII via its keepalive).
-    if std::env::var("PUNKTFUNK_VIDEO_SOURCE").as_deref() == Ok("virtual") {
+    if crate::config::config().video_source.as_deref() == Some("virtual") {
         // The launched app picks the compositor (e.g. gamescope for game entries) and the
         // nested command.
         let compositor = app
@@ -127,10 +138,49 @@ fn run(
                 refresh_hz: cfg.fps,
             })
             .context("create virtual output at client resolution")?;
-        let mut capturer =
-            capture::capture_virtual_output(vout).context("capture virtual output")?;
+        // `want_hdr=false`: the IDD-push backend (opt-in PUNKTFUNK_IDD_PUSH) has no monitor-HDR
+        // auto-detection — it converts its always-FP16 ring per this flag — and GameStream HDR is not
+        // negotiated into StreamConfig here, so an IDD-push GameStream session streams SDR even on an
+        // HDR desktop. (The default WGC backend DOES auto-detect HDR from the output colorspace, but
+        // IDD-push bypasses WGC.) Acceptable for the experimental IDD-push A/B path; HDR over IDD-push
+        // is wired only for punktfunk/1 (want_hdr = negotiated bit_depth >= 10). TODO: derive want_hdr
+        // from a GameStream HDR flag once StreamConfig carries one.
+        let mut capturer = capture::capture_virtual_output(
+            vout,
+            capture::OutputFormat::resolve(false),
+            crate::session_plan::CaptureBackend::resolve(),
+        )
+        .context("capture virtual output")?;
         capturer.set_active(true);
-        return stream_body(&mut *capturer, &sock, cfg, running, force_idr, rfi_range);
+        // Launch the app's command now that capture is live, for the backends that DON'T nest it via
+        // set_launch_command above: Windows (no gamescope) and Linux kwin/mutter/wlroots (which stream
+        // the existing desktop, so the app must be spawned into the session to land on the streamed
+        // output). Linux gamescope already nested it via set_launch_command, so skip it there.
+        #[cfg(windows)]
+        let launch_here = true;
+        #[cfg(target_os = "linux")]
+        let launch_here = compositor != crate::vdisplay::Compositor::Gamescope;
+        #[cfg(any(windows, target_os = "linux"))]
+        if launch_here {
+            if let Some(cmd) = app
+                .and_then(|a| a.cmd.as_deref())
+                .filter(|c| !c.trim().is_empty())
+            {
+                if let Err(e) = crate::library::launch_gamestream_command(cmd) {
+                    tracing::warn!(command = %cmd, error = %e, "gamestream: could not launch app");
+                }
+            }
+        }
+        return stream_body(
+            &mut *capturer,
+            &sock,
+            cfg,
+            running,
+            force_idr,
+            rfi_range,
+            stats,
+            &client_label,
+        );
     }
 
     // Reuse the persistent capturer (one screencast session → clean reconnect); create it on
@@ -140,7 +190,7 @@ fn run(
             tracing::info!("video source: reusing capturer");
             c
         }
-        None if std::env::var("PUNKTFUNK_VIDEO_SOURCE").is_ok_and(|v| v == "portal") => {
+        None if crate::config::config().video_source.as_deref() == Some("portal") => {
             tracing::info!("video source: portal desktop capture");
             capture::open_portal_monitor().context("open portal capturer")?
         }
@@ -150,7 +200,16 @@ fn run(
         }
     };
     capturer.set_active(true);
-    let result = stream_body(&mut *capturer, &sock, cfg, running, force_idr, rfi_range);
+    let result = stream_body(
+        &mut *capturer,
+        &sock,
+        cfg,
+        running,
+        force_idr,
+        rfi_range,
+        stats,
+        &client_label,
+    );
     capturer.set_active(false);
     *video_cap.lock().unwrap() = Some(capturer);
     result
@@ -177,6 +236,10 @@ fn sendmmsg_all(sock: &UdpSocket, pkts: &[Vec<u8>]) -> std::io::Result<()> {
         let mut hdrs: Vec<libc::mmsghdr> = iovs
             .iter_mut()
             .map(|iov| {
+                // SAFETY: `libc::mmsghdr` is a plain `#[repr(C)]` struct of integers and raw
+                // pointers, for which an all-zero bit pattern is valid (null pointers / zero
+                // lengths); the fields we rely on (`msg_iov`, `msg_iovlen`) are overwritten on the
+                // next two lines before the struct is handed to the kernel.
                 let mut h: libc::mmsghdr = unsafe { std::mem::zeroed() };
                 h.msg_hdr.msg_iov = iov;
                 h.msg_hdr.msg_iovlen = 1;
@@ -185,6 +248,13 @@ fn sendmmsg_all(sock: &UdpSocket, pkts: &[Vec<u8>]) -> std::io::Result<()> {
             .collect();
         let mut off = 0usize;
         while off < hdrs.len() {
+            // SAFETY: `fd` is `sock`'s live raw fd (`sock` outlives the call). `hdrs[off..]
+            // .as_mut_ptr()` is a live slice of `(hdrs.len() - off)` `mmsghdr`s — exactly the count
+            // passed — into which the kernel writes each `msg_len`. Each header's `msg_iov` points
+            // into `iovs` (a local that outlives this call, with `msg_iovlen == 1` matching its one
+            // entry) and each `iovec.iov_base` points into the `chunk` packet buffers (the caller's
+            // `pkts`, alive for the call); the kernel only reads those payloads. Flags 0; the return
+            // is error-/progress-checked before advancing `off`.
             let n = unsafe {
                 libc::sendmmsg(fd, hdrs[off..].as_mut_ptr(), (hdrs.len() - off) as u32, 0)
             };
@@ -282,8 +352,20 @@ fn spawn_sender(
     Ok(())
 }
 
+/// Percentile of a slice (sorts it in place first). `q` in `0.0..=1.0`. Used for the web-console
+/// stats sample's per-stage p50/p99.
+fn percentile(v: &mut [u32], q: f64) -> u32 {
+    if v.is_empty() {
+        return 0;
+    }
+    v.sort_unstable();
+    let i = ((v.len() as f64 * q) as usize).min(v.len() - 1);
+    v[i]
+}
+
 /// The encode → packetize loop, over a borrowed capturer. Sending runs on a dedicated thread
 /// (see [`spawn_sender`]) so a send spike can never stall capture/encode.
+#[allow(clippy::too_many_arguments)]
 fn stream_body(
     capturer: &mut dyn Capturer,
     sock: &UdpSocket,
@@ -291,6 +373,11 @@ fn stream_body(
     running: &Arc<AtomicBool>,
     force_idr: &AtomicBool,
     rfi_range: &std::sync::Mutex<Option<(i64, i64)>>,
+    // Shared stats recorder. The encode loop reads `stats.is_armed()` per frame to decide whether
+    // to accumulate the per-stage split, then emits a `StatsSample` at its 1 s aggregation boundary.
+    stats: &Arc<crate::stats_recorder::StatsRecorder>,
+    // Short client label (peer IP) seeded into the capture meta on the first armed registration.
+    client_label: &str,
 ) -> Result<()> {
     // The first frame establishes the authoritative size/format for the encoder.
     let mut frame = capturer.next_frame().context("capture first frame")?;
@@ -351,14 +438,34 @@ fn stream_body(
 
     // Per-stage timing (PUNKTFUNK_PERF=1): max µs/stage per second + unique vs re-encoded frames,
     // to pinpoint stalls. `unique` counts genuinely-new captured frames (vs re-encoded holds).
-    let perf = std::env::var_os("PUNKTFUNK_PERF").is_some();
+    let perf = crate::config::config().perf;
     let (mut mx_cap, mut mx_enc, mut mx_pkt, mut mx_send, mut mx_pkts, mut uniq) =
         (0u128, 0u128, 0u128, 0u128, 0usize, 0u32);
+    // Web-console stats accumulation (active when `perf` OR a capture is armed): per-stage vectors
+    // for p50/p99, the goodput bytes queued to the sender this window, the previous window's
+    // dropped-frame count for delta computation, and the registration id cached on the first sample.
+    let codec_name = match cfg.codec {
+        Codec::H264 => "h264",
+        Codec::H265 => "hevc",
+        Codec::Av1 => "av1",
+    };
+    let mut sid: Option<u32> = None;
+    let (mut v_cap, mut v_enc, mut v_pkt, mut v_send): (Vec<u32>, Vec<u32>, Vec<u32>, Vec<u32>) =
+        (Vec::new(), Vec::new(), Vec::new(), Vec::new());
+    let mut bytes_win: u64 = 0;
+    let mut last_dropped_batches: u64 = 0;
     // Absolute next-frame deadline — the single pacing clock for the loop.
     let mut next_frame = Instant::now();
+    // RFI capability is fixed for the session (probed at encoder open). Query it once so the
+    // recovery path skips the always-`false` invalidate call on encoders without NVENC RFI and
+    // forces a keyframe directly instead.
+    let supports_rfi = enc.caps().supports_rfi;
 
     while running.load(Ordering::SeqCst) {
         let tick = Instant::now();
+        // Measure per-stage timing when `PUNKTFUNK_PERF` is set OR a web-console stats capture is
+        // armed (cheap Relaxed atomic, re-read each frame).
+        let measure = perf || stats.is_armed();
         // Advance to the freshest captured frame if one arrived; otherwise reuse the last.
         if let Some(f) = capturer.try_latest().context("capture frame")? {
             frame = f;
@@ -369,7 +476,9 @@ fn stream_body(
         // re-references an older still-valid frame — no costly IDR spike); if the encoder can't
         // invalidate (range too old, or no NVENC RFI) it returns false and we force a keyframe.
         if let Some((first, last)) = rfi_range.lock().unwrap().take() {
-            if !enc.invalidate_ref_frames(first, last) {
+            // Prefer reference-frame invalidation when the encoder supports it (no costly IDR
+            // spike); otherwise — or if the range is too old to invalidate — force a keyframe.
+            if !(supports_rfi && enc.invalidate_ref_frames(first, last)) {
                 enc.request_keyframe();
             }
         }
@@ -397,9 +506,19 @@ fn stream_body(
         // Hand the frame's packets to the send thread; never block here. A full queue means
         // the sender is behind — drop this batch (FEC/RFI covers the client) and keep encoding.
         let n = batch.len();
+        // Goodput this window = bytes actually queued to the sender (a dropped batch never reaches
+        // the wire, so it's excluded). Summed only when measuring, to keep the idle path free.
+        let batch_bytes: u64 = if measure {
+            batch.iter().map(|p| p.len() as u64).sum()
+        } else {
+            0
+        };
         if n > 0 {
             match batch_tx.try_send(batch) {
-                Ok(()) => sent_batches += 1,
+                Ok(()) => {
+                    sent_batches += 1;
+                    bytes_win += batch_bytes;
+                }
                 Err(std::sync::mpsc::TrySendError::Full(_)) => {
                     dropped_batches += 1;
                     if dropped_batches.is_power_of_two() {
@@ -411,17 +530,26 @@ fn stream_body(
                 }
             }
         }
-        if perf {
+        if measure {
             let t_send = tick.elapsed();
-            mx_cap = mx_cap.max(t_cap.as_micros());
-            mx_enc = mx_enc.max((t_enc - t_cap).as_micros());
-            mx_pkt = mx_pkt.max((t_pkt - t_enc).as_micros());
-            mx_send = mx_send.max((t_send - t_pkt).as_micros());
+            let cap_us = t_cap.as_micros();
+            let enc_us = (t_enc - t_cap).as_micros();
+            let pkt_us = (t_pkt - t_enc).as_micros();
+            let send_us = (t_send - t_pkt).as_micros();
+            mx_cap = mx_cap.max(cap_us);
+            mx_enc = mx_enc.max(enc_us);
+            mx_pkt = mx_pkt.max(pkt_us);
+            mx_send = mx_send.max(send_us);
             mx_pkts = mx_pkts.max(n);
+            v_cap.push(cap_us as u32);
+            v_enc.push(enc_us as u32);
+            v_pkt.push(pkt_us as u32);
+            v_send.push(send_us as u32);
         }
 
         fps_count += 1;
         if fps_t.elapsed() >= Duration::from_secs(1) {
+            let secs = fps_t.elapsed().as_secs_f64();
             if perf {
                 // Max µs/stage this second: cap=drain channel, enc=submit (zero-copy device
                 // copy + NVENC), pkt=poll+FEC+packetize, send=paced packet send. `uniq`=new
@@ -436,12 +564,6 @@ fn stream_body(
                     max_pkts = mx_pkts,
                     "video: streaming (perf)"
                 );
-                mx_cap = 0;
-                mx_enc = 0;
-                mx_pkt = 0;
-                mx_send = 0;
-                mx_pkts = 0;
-                uniq = 0;
             } else {
                 tracing::info!(
                     fps = fps_count,
@@ -450,6 +572,68 @@ fn stream_body(
                     "video: streaming"
                 );
             }
+            // Web-console capture: build the aggregated sample. The host send side exposes no
+            // receiver-side packet loss / FEC-recovery / send-buffer EAGAIN counters, so those stay
+            // 0 (not fabricated); `frames_dropped` is the per-frame send-queue overflow delta.
+            if stats.is_armed() {
+                let session_id = *sid.get_or_insert_with(|| {
+                    stats.register_session(
+                        "gamestream",
+                        cfg.width,
+                        cfg.height,
+                        cfg.fps,
+                        codec_name,
+                        client_label,
+                    )
+                });
+                let sample = crate::stats_recorder::StatsSample {
+                    t_ms: 0, // stamped by push_sample from the capture's monotonic start
+                    session_id,
+                    stages: vec![
+                        crate::stats_recorder::StageTiming {
+                            name: "capture".into(),
+                            p50_us: percentile(&mut v_cap, 0.50) as f32,
+                            p99_us: percentile(&mut v_cap, 0.99) as f32,
+                        },
+                        crate::stats_recorder::StageTiming {
+                            name: "encode".into(),
+                            p50_us: percentile(&mut v_enc, 0.50) as f32,
+                            p99_us: percentile(&mut v_enc, 0.99) as f32,
+                        },
+                        crate::stats_recorder::StageTiming {
+                            name: "packetize".into(),
+                            p50_us: percentile(&mut v_pkt, 0.50) as f32,
+                            p99_us: percentile(&mut v_pkt, 0.99) as f32,
+                        },
+                        crate::stats_recorder::StageTiming {
+                            name: "send".into(),
+                            p50_us: percentile(&mut v_send, 0.50) as f32,
+                            p99_us: percentile(&mut v_send, 0.99) as f32,
+                        },
+                    ],
+                    fps: (uniq as f64 / secs) as f32,
+                    repeat_fps: (fps_count.saturating_sub(uniq) as f64 / secs) as f32,
+                    mbps: (bytes_win as f64 * 8.0 / secs / 1_000_000.0) as f32,
+                    bitrate_kbps: cfg.bitrate_kbps,
+                    frames_dropped: dropped_batches.saturating_sub(last_dropped_batches) as u32,
+                    packets_dropped: 0,
+                    send_dropped: 0,
+                    fec_recovered: 0,
+                };
+                stats.push_sample(session_id, sample);
+            }
+            mx_cap = 0;
+            mx_enc = 0;
+            mx_pkt = 0;
+            mx_send = 0;
+            mx_pkts = 0;
+            uniq = 0;
+            v_cap.clear();
+            v_enc.clear();
+            v_pkt.clear();
+            v_send.clear();
+            bytes_win = 0;
+            last_dropped_batches = dropped_batches;
             fps_count = 0;
             fps_t = Instant::now();
         }

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

@@ -3,7 +3,7 @@
 //!   `RTP_PACKET(12, big-endian) + reserved[4] + NV_VIDEO_PACKET(16, little-endian) + payload`
 //! and the frame's bitstream is prefixed with an 8-byte `video_short_frame_header_t`, then
 //! striped into ≤4 FEC blocks of ≤255 shards. Byte-exact spec:
-//! `docs/research/gamestream-protocol-research.json` (video plane).
+//! `design/research/gamestream-protocol-research.json` (video plane).
 //!
 //! FEC (P1.5): each block carries `m = ⌈k·pct/100⌉` Reed–Solomon parity shards generated by
 //! `punktfunk_core::fec::Gf8Coder` (the nanors-compatible Cauchy GF(2⁸) coder). Crucially, RS runs

crates/punktfunk-host/src/inject.rs

@@ -112,8 +112,10 @@ pub fn default_backend() -> Backend {
     }
     #[cfg(not(target_os = "windows"))]
     {
-        if std::env::var("PUNKTFUNK_COMPOSITOR")
-            .is_ok_and(|v| v.trim().eq_ignore_ascii_case("gamescope"))
+        if crate::config::config()
+            .compositor
+            .as_deref()
+            .is_some_and(|v| v.trim().eq_ignore_ascii_case("gamescope"))
         {
             return Backend::GamescopeEi;
         }
@@ -260,8 +262,10 @@ fn coalesce(events: Vec<InputEvent>) -> Vec<InputEvent> {
 /// (`org.gnome.Mutter.RemoteDesktop`), the same direct API the Mutter video backend uses.
 #[cfg(target_os = "linux")]
 fn libei_ei_source() -> libei::EiSource {
-    let gnome = std::env::var("PUNKTFUNK_COMPOSITOR")
-        .is_ok_and(|v| v.trim().eq_ignore_ascii_case("mutter"))
+    let gnome = crate::config::config()
+        .compositor
+        .as_deref()
+        .is_some_and(|v| v.trim().eq_ignore_ascii_case("mutter"))
         || std::env::var("XDG_CURRENT_DESKTOP")
             .unwrap_or_default()
             .to_ascii_uppercase()
@@ -421,17 +425,46 @@ fn gs_button_to_evdev(b: u32) -> Option<u32> {
     })
 }
 
+// Goal-1 stage 6: Linux UHID/uinput/libei/wlr backends under `inject/linux/`, the Windows UMDF/SendInput
+// backends under `inject/windows/`, and the transport-independent HID codecs under `inject/proto/`;
+// `#[path]` keeps every `crate::inject::*` module name flat.
 #[cfg(target_os = "linux")]
+#[path = "inject/linux/dualsense.rs"]
 pub mod dualsense;
-#[cfg(target_os = "linux")]
-pub mod dualshock4;
-#[cfg(target_os = "linux")]
-pub mod gamepad;
-/// Windows: virtual Xbox 360 pads via ViGEmBus.
+/// Transport-independent DualSense HID contract, shared by the Linux UHID backend ([`dualsense`])
+/// and the Windows UMDF-driver backend ([`dualsense_windows`]).
+#[cfg(any(target_os = "linux", target_os = "windows"))]
+#[path = "inject/proto/dualsense_proto.rs"]
+pub mod dualsense_proto;
+/// Windows: virtual DualSense via the UMDF minidriver + a shared-memory host channel.
 #[cfg(target_os = "windows")]
-#[path = "inject/gamepad_windows.rs"]
+#[path = "inject/windows/dualsense_windows.rs"]
+pub mod dualsense_windows;
+#[cfg(target_os = "linux")]
+#[path = "inject/linux/dualshock4.rs"]
+pub mod dualshock4;
+/// Transport-independent DualShock 4 HID codec used by the Windows UMDF-driver backend
+/// ([`dualshock4_windows`]). (The Linux backend still carries its own copy — see the module FIXME.)
+#[cfg(any(target_os = "linux", target_os = "windows"))]
+#[path = "inject/proto/dualshock4_proto.rs"]
+pub mod dualshock4_proto;
+/// Windows: virtual DualShock 4 via the same UMDF minidriver + shared-memory channel (device-type 1).
+#[cfg(target_os = "windows")]
+#[path = "inject/windows/dualshock4_windows.rs"]
+pub mod dualshock4_windows;
+#[cfg(target_os = "linux")]
+#[path = "inject/linux/gamepad.rs"]
 pub mod gamepad;
-/// Stub — virtual gamepads need Linux uinput or Windows ViGEmBus; events are dropped elsewhere.
+/// Windows: virtual Xbox 360 pads via the in-tree XUSB companion UMDF driver (classic XInput).
+#[cfg(target_os = "windows")]
+#[path = "inject/windows/gamepad_windows.rs"]
+pub mod gamepad;
+/// Windows: small RAII wrappers (`Shm` section+view, `SwDevice` devnode) shared by the three gamepad
+/// backends (DualSense / DualShock 4 / XUSB), so each per-pad resource closes deterministically on drop.
+#[cfg(target_os = "windows")]
+#[path = "inject/windows/gamepad_raii.rs"]
+mod gamepad_raii;
+/// Stub — virtual gamepads need Linux uinput or the Windows UMDF drivers; events are dropped elsewhere.
 #[cfg(not(any(target_os = "linux", target_os = "windows")))]
 pub mod gamepad {
     #[derive(Default)]
@@ -445,10 +478,13 @@ pub mod gamepad {
     }
 }
 #[cfg(target_os = "linux")]
+#[path = "inject/linux/libei.rs"]
 mod libei;
 #[cfg(target_os = "windows")]
+#[path = "inject/windows/sendinput.rs"]
 mod sendinput;
 #[cfg(target_os = "linux")]
+#[path = "inject/linux/wlr.rs"]
 mod wlr;
 
 #[cfg(test)]

crates/punktfunk-host/src/inject/gamepad_windows.rs

@@ -1,138 +0,0 @@
-//! Windows virtual gamepad via ViGEmBus — the analogue of the Linux uinput Xbox-360 pad.
-//! One virtual Xbox 360 controller per client pad index. GameStream/Moonlight already uses the
-//! XInput button/stick/trigger conventions (low 16 button bits, sticks −32768..32767 +Y up,
-//! triggers 0..255), so the mapping is ~1:1.
-//!
-//! Needs the ViGEmBus driver installed (like SudoVDA for the display); absent → gamepad is disabled
-//! and the session continues without it. Rumble flows back the *other* way: a game on the host writes
-//! force-feedback to the virtual pad, ViGEm's notification API delivers it on a background thread,
-//! and [`GamepadManager::pump_rumble`] relays level changes to the client (the universal 0xCA plane),
-//! mirroring the Linux `EV_FF` read path.
-
-use crate::gamestream::gamepad::GamepadEvent;
-use std::collections::HashMap;
-use std::sync::atomic::{AtomicU32, Ordering};
-use std::sync::Arc;
-use std::thread::JoinHandle;
-use vigem_client::{Client, TargetId, XButtons, XGamepad, Xbox360Wired};
-
-/// A plugged virtual pad plus its rumble back-channel. The notification thread stores the latest
-/// motor levels into `rumble` (packed `large << 8 | small`, both 0..255); [`GamepadManager::pump_rumble`]
-/// reads it and emits level changes. Dropping `target` aborts the outstanding notification request,
-/// so the thread's `poll` returns an error and it exits on its own — we detach it (per ViGEm's docs,
-/// dropping the `JoinHandle` does not stop the thread, but the target-drop abort does).
-struct PadEntry {
-    target: Xbox360Wired<Arc<Client>>,
-    rumble: Arc<AtomicU32>,
-    last_emitted: u32,
-    _notif_thread: Option<JoinHandle<()>>,
-}
-
-pub struct GamepadManager {
-    client: Option<Arc<Client>>,
-    pads: HashMap<u8, PadEntry>,
-}
-
-impl GamepadManager {
-    pub fn new() -> GamepadManager {
-        let client = match Client::connect() {
-            Ok(c) => {
-                tracing::info!("ViGEmBus connected (virtual Xbox 360 gamepads)");
-                Some(Arc::new(c))
-            }
-            Err(e) => {
-                tracing::warn!(
-                    error = format!("{e:?}"),
-                    "ViGEmBus unavailable — gamepad disabled (install ViGEmBus)"
-                );
-                None
-            }
-        };
-        GamepadManager {
-            client,
-            pads: HashMap::new(),
-        }
-    }
-
-    /// Lazily plug pad `index` on its first event, arming the rumble notification thread. Returns
-    /// `None` if ViGEmBus is unavailable or the pad failed to plug.
-    fn ensure_pad(&mut self, index: u8) -> Option<&mut PadEntry> {
-        if !self.pads.contains_key(&index) {
-            let client = self.client.clone()?;
-            let mut target = Xbox360Wired::new(client, TargetId::XBOX360_WIRED);
-            if let Err(e) = target.plugin() {
-                tracing::warn!(error = format!("{e:?}"), "ViGEm pad plugin failed");
-                return None;
-            }
-            let _ = target.wait_ready();
-            // Arm the force-feedback back-channel: a background thread writes each notification's
-            // motor levels into the shared atomic; the input thread drains changes via pump_rumble.
-            let rumble = Arc::new(AtomicU32::new(0));
-            let notif_thread = match target.request_notification() {
-                Ok(req) => {
-                    let sink = rumble.clone();
-                    Some(req.spawn_thread(move |_req, n| {
-                        sink.store(
-                            ((n.large_motor as u32) << 8) | n.small_motor as u32,
-                            Ordering::Relaxed,
-                        );
-                    }))
-                }
-                Err(e) => {
-                    tracing::warn!(
-                        error = format!("{e:?}"),
-                        "ViGEm rumble notification unavailable — pad runs without force feedback"
-                    );
-                    None
-                }
-            };
-            self.pads.insert(
-                index,
-                PadEntry {
-                    target,
-                    rumble,
-                    last_emitted: 0,
-                    _notif_thread: notif_thread,
-                },
-            );
-        }
-        self.pads.get_mut(&index)
-    }
-
-    pub fn handle(&mut self, ev: &GamepadEvent) {
-        let GamepadEvent::State(f) = ev else {
-            return; // Arrival metadata — the pad is created lazily on the first State
-        };
-        let Some(entry) = self.ensure_pad(f.index.max(0) as u8) else {
-            return;
-        };
-        let gp = XGamepad {
-            buttons: XButtons {
-                raw: (f.buttons & 0xffff) as u16,
-            },
-            left_trigger: f.left_trigger,
-            right_trigger: f.right_trigger,
-            thumb_lx: f.ls_x,
-            thumb_ly: f.ls_y,
-            thumb_rx: f.rs_x,
-            thumb_ry: f.rs_y,
-        };
-        let _ = entry.target.update(&gp);
-    }
-
-    /// Relay any changed rumble level to the client. The notification thread keeps `rumble` current;
-    /// we emit only on change (the input thread re-sends the steady state every 500 ms to heal drops).
-    /// ViGEm motors are 0..255; the wire carries 0..65535, so scale by 257 (255 → 65535). `large`
-    /// (low-frequency) maps to the universal datagram's `low`, `small` (high-frequency) to `high`.
-    pub fn pump_rumble(&mut self, mut send: impl FnMut(u16, u16, u16)) {
-        for (idx, entry) in self.pads.iter_mut() {
-            let packed = entry.rumble.load(Ordering::Relaxed);
-            if packed != entry.last_emitted {
-                entry.last_emitted = packed;
-                let large = ((packed >> 8) & 0xff) as u16;
-                let small = (packed & 0xff) as u16;
-                send(*idx as u16, large * 257, small * 257);
-            }
-        }
-    }
-}

crates/punktfunk-host/src/inject/linux/dualsense.rs

@@ -0,0 +1,360 @@
+//! Virtual Sony DualSense via UHID — the rich-controller path (roadmap §5).
+//!
+//! Unlike the uinput X-Box-360 pad ([`super::gamepad`]), which only carries buttons + axes + a
+//! rumble back-channel, a UHID device presents a *real* DualSense HID interface to the kernel:
+//! `hid-playstation` binds it (matched by VID `054C`/PID `0CE6`) and exposes the full controller
+//! — gamepad, motion sensors, touchpad, lightbar + player LEDs, and adaptive triggers — to games.
+//! The host writes HID **input** reports (report `0x01`, our controller state) and reads HID
+//! **output** reports (report `0x02`, a game's rumble/LED/trigger feedback) back, which it
+//! forwards to the client as [`punktfunk_core::quic::HidOutput`].
+//!
+//! The transport-independent contract (report descriptor, feature blobs, [`DsState`], the `0x01`
+//! serializer and `0x02` parser) lives in [`super::dualsense_proto`], shared with the Windows
+//! UMDF-driver backend; this module is just the `/dev/uhid` plumbing around it.
+
+use super::dualsense_proto::{
+    parse_ds_output, serialize_state, DsFeedback, DsState, DS_FEATURE_CALIBRATION,
+    DS_FEATURE_FIRMWARE, DS_FEATURE_PAIRING, DS_INPUT_REPORT_LEN, DS_PRODUCT, DS_TOUCH_H,
+    DS_TOUCH_W, DS_VENDOR, DUALSENSE_RDESC,
+};
+use crate::gamestream::gamepad::{GamepadEvent, MAX_PADS};
+use anyhow::{Context, Result};
+use punktfunk_core::quic::{HidOutput, RichInput};
+use std::fs::{File, OpenOptions};
+use std::io::{Read, Write};
+use std::os::unix::fs::OpenOptionsExt;
+use std::time::{Duration, Instant};
+
+// /dev/uhid event ABI (linux/uhid.h). `struct uhid_event` is __packed__: a u32 `type` then a
+// union whose largest member is uhid_create2_req (128+64+64 + 2+2 + 4*4 + rd_data[4096] = 4372).
+const UHID_PATH: &str = "/dev/uhid";
+const UHID_DESTROY: u32 = 1;
+const UHID_OUTPUT: u32 = 6;
+const UHID_GET_REPORT: u32 = 9;
+const UHID_GET_REPORT_REPLY: u32 = 10;
+const UHID_CREATE2: u32 = 11;
+const UHID_INPUT2: u32 = 12;
+const HID_MAX_DESCRIPTOR_SIZE: usize = 4096;
+const UHID_EVENT_SIZE: usize = 4 + 4372; // type + union (create2)
+const BUS_USB: u16 = 0x03;
+
+/// Copy a NUL-padded C string field into the event buffer.
+fn put_cstr(ev: &mut [u8], off: usize, cap: usize, s: &str) {
+    let n = s.len().min(cap - 1);
+    ev[off..off + n].copy_from_slice(&s.as_bytes()[..n]); // rest already zero (NUL-terminated)
+}
+
+/// A virtual DualSense backed by `/dev/uhid` (hand-rolled codec — no bindgen, mirroring the
+/// uinput pad's style). Dropping it destroys the device (the kernel tears down the bound
+/// `hid-playstation` interface).
+pub struct DualSensePad {
+    fd: File,
+    seq: u8,
+    ts: u32,
+}
+
+impl DualSensePad {
+    /// Create the UHID DualSense for pad `index` (used only to make the device name/uniq unique).
+    pub fn open(index: u8) -> Result<DualSensePad> {
+        let fd = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .custom_flags(libc::O_NONBLOCK)
+            .open(UHID_PATH)
+            .with_context(|| {
+                format!("open {UHID_PATH} (is the 60-punktfunk.rules uhid rule installed + are you in 'input'?)")
+            })?;
+        let mut ds = DualSensePad { fd, seq: 0, ts: 0 };
+        ds.send_create2(index).context("UHID_CREATE2 DualSense")?;
+        Ok(ds)
+    }
+
+    fn send_create2(&mut self, index: u8) -> Result<()> {
+        let mut ev = [0u8; UHID_EVENT_SIZE];
+        ev[0..4].copy_from_slice(&UHID_CREATE2.to_ne_bytes());
+        // union (uhid_create2_req) starts at byte 4.
+        put_cstr(&mut ev, 4, 128, &format!("Punktfunk DualSense {index}")); // name[128]
+        put_cstr(&mut ev, 132, 64, &format!("punktfunk/dualsense/{index}")); // phys[64]
+        put_cstr(&mut ev, 196, 64, &format!("punktfunk-ds-{index}")); // uniq[64]
+        ev[260..262].copy_from_slice(&(DUALSENSE_RDESC.len() as u16).to_ne_bytes()); // rd_size
+        ev[262..264].copy_from_slice(&BUS_USB.to_ne_bytes()); // bus
+        ev[264..268].copy_from_slice(&DS_VENDOR.to_ne_bytes());
+        ev[268..272].copy_from_slice(&DS_PRODUCT.to_ne_bytes());
+        ev[272..276].copy_from_slice(&0x0100u32.to_ne_bytes()); // version
+        ev[276..280].copy_from_slice(&0u32.to_ne_bytes()); // country
+        ev[280..280 + DUALSENSE_RDESC.len()].copy_from_slice(DUALSENSE_RDESC); // rd_data
+        self.fd.write_all(&ev).context("write UHID_CREATE2")?;
+        Ok(())
+    }
+
+    /// Serialize `st` into report `0x01` and write it to the kernel (UHID_INPUT2).
+    pub fn write_state(&mut self, st: &DsState) -> Result<()> {
+        self.seq = self.seq.wrapping_add(1);
+        self.ts = self.ts.wrapping_add(1); // monotonic sensor timestamp is all the kernel needs
+        let mut r = [0u8; DS_INPUT_REPORT_LEN];
+        serialize_state(&mut r, st, self.seq, self.ts);
+
+        let mut ev = [0u8; UHID_EVENT_SIZE];
+        ev[0..4].copy_from_slice(&UHID_INPUT2.to_ne_bytes());
+        ev[4..6].copy_from_slice(&(r.len() as u16).to_ne_bytes()); // input2.size
+        ev[6..6 + r.len()].copy_from_slice(&r); // input2.data
+        self.fd.write_all(&ev).context("write UHID_INPUT2")?;
+        Ok(())
+    }
+
+    /// Service the device, non-blocking: answer the kernel's feature-report GET_REPORTs (calibration
+    /// / pairing / firmware — required during `hid-playstation` init, or no input devices appear)
+    /// and parse any HID OUTPUT reports (rumble / lightbar / player LEDs / adaptive triggers) into
+    /// a [`DsFeedback`] for pad `pad`. Call frequently — especially right after [`open`] so the
+    /// init handshake completes. The fd is `O_NONBLOCK`, so once drained `read` returns `WouldBlock`.
+    pub fn service(&mut self, pad: u8) -> DsFeedback {
+        let mut fb = DsFeedback::default();
+        let mut ev = [0u8; UHID_EVENT_SIZE];
+        while let Ok(n) = self.fd.read(&mut ev) {
+            if n < UHID_EVENT_SIZE {
+                break;
+            }
+            match u32::from_ne_bytes([ev[0], ev[1], ev[2], ev[3]]) {
+                UHID_OUTPUT => {
+                    // uhid_output_req: data[4096] at [4..4100], size u16 at [4100..4102].
+                    let size = u16::from_ne_bytes([ev[4100], ev[4101]]) as usize;
+                    let end = 4 + size.min(HID_MAX_DESCRIPTOR_SIZE);
+                    parse_ds_output(pad, &ev[4..end], &mut fb);
+                }
+                UHID_GET_REPORT => {
+                    // uhid_get_report_req: id u32 [4..8], rnum u8 [8].
+                    let id = u32::from_ne_bytes([ev[4], ev[5], ev[6], ev[7]]);
+                    let data: &[u8] = match ev[8] {
+                        0x05 => DS_FEATURE_CALIBRATION,
+                        0x09 => DS_FEATURE_PAIRING,
+                        0x20 => DS_FEATURE_FIRMWARE,
+                        _ => &[],
+                    };
+                    let _ = self.reply_get_report(id, data);
+                }
+                _ => {} // Start/Stop/Open/Close/SetReport — ignore
+            }
+        }
+        fb
+    }
+
+    fn reply_get_report(&mut self, id: u32, data: &[u8]) -> Result<()> {
+        let mut ev = [0u8; UHID_EVENT_SIZE];
+        ev[0..4].copy_from_slice(&UHID_GET_REPORT_REPLY.to_ne_bytes());
+        // uhid_get_report_reply_req: id u32 [4..8], err u16 [8..10], size u16 [10..12], data [12..].
+        ev[4..8].copy_from_slice(&id.to_ne_bytes());
+        let err: u16 = if data.is_empty() { 5 } else { 0 }; // EIO if we don't know the report
+        ev[8..10].copy_from_slice(&err.to_ne_bytes());
+        ev[10..12].copy_from_slice(&(data.len() as u16).to_ne_bytes());
+        ev[12..12 + data.len()].copy_from_slice(data);
+        self.fd
+            .write_all(&ev)
+            .context("write UHID_GET_REPORT_REPLY")?;
+        Ok(())
+    }
+}
+
+impl Drop for DualSensePad {
+    fn drop(&mut self) {
+        let mut ev = [0u8; UHID_EVENT_SIZE];
+        ev[0..4].copy_from_slice(&UHID_DESTROY.to_ne_bytes());
+        let _ = self.fd.write_all(&ev);
+    }
+}
+
+/// All virtual DualSense pads of a session — the rich-controller analog of
+/// [`GamepadManager`](super::gamepad::GamepadManager), selected with `PUNKTFUNK_GAMEPAD=dualsense`.
+///
+/// Unlike the uinput pad, a DualSense carries touchpad + motion, which arrive on a *separate*
+/// rich-input plane ([`apply_rich`](Self::apply_rich)) from the button/stick frames
+/// ([`handle`](Self::handle)). So the manager keeps each pad's full [`DsState`] and re-emits the
+/// merged report whenever either source changes. [`pump`](Self::pump) services the kernel
+/// handshake and routes a game's feedback back out: motor rumble on the universal plane, the rich
+/// LED/player-LED/trigger feedback on the HID-output plane.
+pub struct DualSenseManager {
+    pads: Vec<Option<DualSensePad>>,
+    /// Each pad's current full report — buttons/sticks merged with persisted touch + motion.
+    state: Vec<DsState>,
+    /// Last rumble forwarded per pad, so a report that only changes the LED doesn't re-send it.
+    last_rumble: Vec<(u16, u16)>,
+    /// When each pad last wrote an input report — drives [`DualSenseManager::heartbeat`], which
+    /// re-emits the current state during input silence so the kernel never sees the device go quiet.
+    last_write: Vec<Instant>,
+    /// Pad creation failed (e.g. /dev/uhid permissions) — warn once, drop events.
+    broken: bool,
+}
+
+impl Default for DualSenseManager {
+    fn default() -> DualSenseManager {
+        DualSenseManager::new()
+    }
+}
+
+impl DualSenseManager {
+    pub fn new() -> DualSenseManager {
+        DualSenseManager {
+            pads: (0..MAX_PADS).map(|_| None).collect(),
+            state: vec![DsState::neutral(); MAX_PADS],
+            last_rumble: vec![(0, 0); MAX_PADS],
+            last_write: vec![Instant::now(); MAX_PADS],
+            broken: false,
+        }
+    }
+
+    /// Handle one decoded controller event (create/destroy by mask, then merge button/stick state).
+    pub fn handle(&mut self, ev: &GamepadEvent) {
+        match ev {
+            GamepadEvent::Arrival { index, kind, .. } => {
+                tracing::info!(index, kind, "controller arrival (DualSense)");
+                self.ensure(*index as usize);
+            }
+            GamepadEvent::State(f) => {
+                let idx = f.index as usize;
+                if idx >= MAX_PADS {
+                    return;
+                }
+                // Unplugs: drop any allocated pad whose mask bit cleared, resetting its state.
+                for (i, slot) in self.pads.iter_mut().enumerate() {
+                    if slot.is_some() && f.active_mask & (1 << i) == 0 {
+                        tracing::info!(index = i, "controller unplugged (DualSense)");
+                        *slot = None;
+                        self.state[i] = DsState::neutral();
+                        self.last_rumble[i] = (0, 0);
+                    }
+                }
+                if f.active_mask & (1 << idx) == 0 {
+                    return; // this event WAS the unplug
+                }
+                self.ensure(idx);
+                // Merge buttons/sticks/triggers from the frame, preserving touch + motion (those
+                // come on the rich-input plane and must survive a button-only frame).
+                let prev = self.state[idx];
+                let mut s = DsState::from_gamepad(
+                    f.buttons,
+                    f.ls_x,
+                    f.ls_y,
+                    f.rs_x,
+                    f.rs_y,
+                    f.left_trigger,
+                    f.right_trigger,
+                );
+                s.touch = prev.touch;
+                s.gyro = prev.gyro;
+                s.accel = prev.accel;
+                self.state[idx] = s;
+                self.write(idx);
+            }
+        }
+    }
+
+    /// Apply one rich client→host event (touchpad contact / motion sample) to an existing pad,
+    /// preserving its button/stick state. Rich events never create a pad (a controller must have
+    /// arrived first); they're dropped if the pad isn't present.
+    pub fn apply_rich(&mut self, rich: RichInput) {
+        let idx = match rich {
+            RichInput::Touchpad { pad, .. } | RichInput::Motion { pad, .. } => pad as usize,
+        };
+        if idx >= MAX_PADS || self.pads[idx].is_none() {
+            return;
+        }
+        match rich {
+            RichInput::Touchpad {
+                finger,
+                active,
+                x,
+                y,
+                ..
+            } => {
+                // The DualSense touchpad carries two contacts; clamp to a valid slot and keep the
+                // reported contact id consistent with it (the wire `finger` is untrusted).
+                let slot = (finger as usize).min(1);
+                let t = &mut self.state[idx].touch[slot];
+                t.active = active;
+                t.id = slot as u8;
+                // Normalized 0..=65535 → the touchpad's coordinate range (0..=W-1 / 0..=H-1,
+                // what the kernel advertises as the ABS_MT extents).
+                t.x = ((x as u32 * (DS_TOUCH_W - 1) as u32) / u16::MAX as u32) as u16;
+                t.y = ((y as u32 * (DS_TOUCH_H - 1) as u32) / u16::MAX as u32) as u16;
+            }
+            RichInput::Motion { gyro, accel, .. } => {
+                self.state[idx].gyro = gyro;
+                self.state[idx].accel = accel;
+            }
+        }
+        self.write(idx);
+    }
+
+    fn write(&mut self, idx: usize) {
+        let st = self.state[idx];
+        if let Some(pad) = self.pads[idx].as_mut() {
+            let _ = pad.write_state(&st);
+        }
+        // Reset the heartbeat timer on every write (real input or heartbeat), so an actively-used
+        // pad emits no extra reports — the heartbeat only fills genuine input-silence gaps.
+        self.last_write[idx] = Instant::now();
+    }
+
+    /// Re-emit each live pad's CURRENT report if it's been silent for `max_gap`. A real DualSense
+    /// streams report `0x01` continuously (~250 Hz); the kernel `hid-playstation` driver / Proton /
+    /// SDL treat a multi-second silence (a held-steady stick produces no wire events) as an
+    /// unplugged controller — the "controller disconnected every few seconds" symptom. Re-sending
+    /// the current state is idempotent (a stale-but-correct frame, never a phantom input);
+    /// `write_state` bumps the report's seq + timestamp, so each is a fresh, well-formed report.
+    pub fn heartbeat(&mut self, max_gap: Duration) {
+        let now = Instant::now();
+        for i in 0..self.pads.len() {
+            if self.pads[i].is_some() && now.duration_since(self.last_write[i]) >= max_gap {
+                self.write(i);
+            }
+        }
+    }
+
+    fn ensure(&mut self, idx: usize) {
+        if idx >= MAX_PADS || self.pads[idx].is_some() || self.broken {
+            return;
+        }
+        match DualSensePad::open(idx as u8) {
+            Ok(p) => {
+                tracing::info!(
+                    index = idx,
+                    "virtual DualSense created (UHID hid-playstation)"
+                );
+                self.pads[idx] = Some(p);
+                self.state[idx] = DsState::neutral();
+                self.last_rumble[idx] = (0, 0);
+                self.last_write[idx] = Instant::now();
+            }
+            Err(e) => {
+                tracing::error!(error = %format!("{e:#}"), "virtual DualSense creation failed — controller input disabled");
+                self.broken = true;
+            }
+        }
+    }
+
+    /// Service every pad: answer the kernel's init handshake and parse a game's feedback. `rumble`
+    /// is invoked `(index, low, high)` only when the motor level *changes* (the universal 0xCA
+    /// plane — both backends use it); `hidout` is invoked for each DualSense-only rich feedback
+    /// event (lightbar / player LEDs / adaptive triggers — the 0xCD plane). Call frequently:
+    /// the kernel blocks `hid-playstation` init until its GET_REPORTs are answered.
+    pub fn pump(
+        &mut self,
+        mut rumble: impl FnMut(u16, u16, u16),
+        mut hidout: impl FnMut(HidOutput),
+    ) {
+        for i in 0..self.pads.len() {
+            let Some(pad) = self.pads[i].as_mut() else {
+                continue;
+            };
+            let fb = pad.service(i as u8);
+            if let Some(r) = fb.rumble {
+                if self.last_rumble[i] != r {
+                    self.last_rumble[i] = r;
+                    rumble(i as u16, r.0, r.1);
+                }
+            }
+            for h in fb.hidout {
+                hidout(h);
+            }
+        }
+    }
+}

crates/punktfunk-host/src/inject/linux/dualshock4.rs

@@ -13,7 +13,7 @@
 //! resolution differ. The report descriptor + struct offsets are the canonical real-DS4-USB layout
 //! the kernel `struct dualshock4_input_report_usb` / `_output_report_common` parse.
 
-use super::dualsense::{DsState, Touch};
+use super::dualsense_proto::{DsState, Touch};
 use crate::gamestream::gamepad::{GamepadEvent, MAX_PADS};
 use anyhow::{Context, Result};
 use punktfunk_core::quic::{HidOutput, RichInput};
@@ -258,6 +258,7 @@ impl DualShock4Pad {
         // union (uhid_create2_req) starts at byte 4.
         put_cstr(&mut ev, 4, 128, &format!("Punktfunk DualShock 4 {index}")); // name[128]
         put_cstr(&mut ev, 132, 64, &format!("punktfunk/dualshock4/{index}")); // phys[64]
+
         // A unique uniq[64] keeps the sysfs nodes tidy when several pads coexist (the kernel's
         // duplicate-device check itself keys off the per-pad MAC in the pairing feature report).
         put_cstr(&mut ev, 196, 64, &format!("punktfunk-ds4-{index}")); // uniq[64]

crates/punktfunk-host/src/inject/linux/gamepad.rs

@@ -15,6 +15,9 @@
 //! `<linux/uinput.h>` on x86_64. `/dev/uinput` needs a udev rule + `input` group membership
 //! (see `scripts/60-punktfunk.rules`); creation fails with a clear error otherwise.
 
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
+#![deny(clippy::undocumented_unsafe_blocks)]
+
 use crate::gamestream::gamepad::{self, GamepadFrame, MAX_PADS};
 use anyhow::{bail, Result};
 use std::collections::HashMap;
@@ -215,6 +218,11 @@ const _: () = {
 };
 
 fn ioctl_int(fd: i32, req: libc::c_ulong, arg: libc::c_int, what: &str) -> Result<()> {
+    // SAFETY: every caller passes one of UI_SET_EVBIT/KEYBIT/FFBIT/UI_DEV_CREATE/UI_DEV_DESTROY as
+    // `req` — all integer-argument ioctls whose third arg the kernel takes BY VALUE, so nothing is
+    // dereferenced through `arg` and no memory must outlive the call. The only precondition is `fd`
+    // being a valid open descriptor; callers pass the live `/dev/uinput` fd, and even a stale fd
+    // would merely return -1/EBADF (reported below), never UB.
     if unsafe { libc::ioctl(fd, req, arg) } < 0 {
         bail!("{what}: {}", std::io::Error::last_os_error());
     }
@@ -222,6 +230,12 @@ fn ioctl_int(fd: i32, req: libc::c_ulong, arg: libc::c_int, what: &str) -> Resul
 }
 
 fn ioctl_ptr<T>(fd: i32, req: libc::c_ulong, arg: *mut T, what: &str) -> Result<()> {
+    // SAFETY: `fd` is the caller's live `/dev/uinput` fd. Every call site passes `&mut x` for a live,
+    // uniquely-borrowed `#[repr(C)]` `x: T` whose size matches the struct the request number encodes
+    // (UI_DEV_SETUP=0x405c_5503 → 0x5c=92=size_of::<UinputSetup>(); UI_ABS_SETUP → 0x1c=28; the FF
+    // upload/erase ioctls → 0x68/0x0c — all pinned by the `size_of` asserts above). The kernel copies
+    // exactly that many bytes in/out through `arg`; the `&mut` keeps the pointee alive and unaliased
+    // for the whole synchronous call.
     if unsafe { libc::ioctl(fd, req, arg) } < 0 {
         bail!("{what}: {}", std::io::Error::last_os_error());
     }
@@ -251,6 +265,9 @@ pub struct VirtualPad {
 impl VirtualPad {
     pub fn create(index: usize, identity: PadIdentity) -> Result<VirtualPad> {
         use std::os::fd::FromRawFd;
+        // SAFETY: `c"/dev/uinput"` is a 'static NUL-terminated C string literal; `as_ptr()` yields a
+        // valid pointer the kernel only reads as a filesystem path. `open` returns a fresh fd (or -1)
+        // and retains nothing; no Rust memory is aliased or handed to the kernel beyond that 'static path.
         let raw = unsafe {
             libc::open(
                 c"/dev/uinput".as_ptr(),
@@ -264,6 +281,9 @@ impl VirtualPad {
                 std::io::Error::last_os_error()
             );
         }
+        // SAFETY: `raw >= 0` here (the `< 0` branch above already bailed), so it is a freshly-opened fd
+        // from `libc::open` that is not stored or owned anywhere else. Transferring it to `OwnedFd` makes
+        // this the unique owner, which will `close` it exactly once on drop (no double-close, no leak).
         let fd = unsafe { OwnedFd::from_raw_fd(raw) };
 
         ioctl_int(raw, UI_SET_EVBIT, EV_KEY as i32, "UI_SET_EVBIT(EV_KEY)")?;
@@ -356,6 +376,11 @@ impl VirtualPad {
             code,
             value,
         };
+        // SAFETY: `ev` is a live local `#[repr(C)]` struct of all-integer fields with no padding bytes
+        // (timeval=16 + u16 + u16 + i32 = 24, the size asserted above), so every byte is initialized and
+        // valid to read as `u8`. The pointer is non-null and `u8`-aligned (align 1), the length is exactly
+        // `size_of::<InputEventRaw>()` so the slice spans precisely `ev`'s bytes (in bounds), and `ev`
+        // outlives `bytes` (used immediately below) with no concurrent mutation (single-threaded local).
         let bytes = unsafe {
             std::slice::from_raw_parts(
                 &ev as *const _ as *const u8,
@@ -363,6 +388,10 @@ impl VirtualPad {
             )
         };
         // Best-effort: a full kernel queue drops the event; the next frame re-syncs state.
+        // SAFETY: `self.fd` is the live uinput `OwnedFd` (borrowed via `as_raw_fd`, so it stays open for
+        // the call); `bytes` is the slice above backed by the still-live local `ev`. `write` only READS
+        // exactly `bytes.len()` bytes from `bytes.as_ptr()` (in bounds) and retains nothing past return,
+        // so the buffer outlives the synchronous call and the read-only access cannot race or alias.
         let _ = unsafe {
             libc::write(
                 self.fd.as_raw_fd(),
@@ -404,6 +433,10 @@ impl VirtualPad {
         let raw = self.fd.as_raw_fd();
         let mut buf = [0u8; std::mem::size_of::<InputEventRaw>()];
         loop {
+            // SAFETY: `raw` is the live raw fd of `self.fd` (the non-blocking uinput device). `buf` is a
+            // live local `[u8; size_of::<InputEventRaw>()]`; `buf.as_mut_ptr()` is a valid writable pointer
+            // to its `buf.len()` bytes. `read` writes AT MOST `buf.len()` bytes (in bounds), the buffer
+            // outlives this synchronous call, and `buf` is borrowed uniquely here (no alias/race).
             let n = unsafe { libc::read(raw, buf.as_mut_ptr() as *mut libc::c_void, buf.len()) };
             if n != buf.len() as isize {
                 break; // EAGAIN / short read — queue drained
@@ -415,6 +448,10 @@ impl VirtualPad {
                 unsafe { std::ptr::read_unaligned(buf.as_ptr() as *const InputEventRaw) };
             match (ev.type_, ev.code) {
                 (EV_UINPUT, UI_FF_UPLOAD) => {
+                    // SAFETY: `UinputFfUpload` is `#[repr(C)]` over integers (`u32`, `i32`) and two
+                    // `FfEffect`s (integers + `[u8; 32]`); all-zero is a valid bit pattern for every field
+                    // (no bool/NonZero/enum/reference niche), so `zeroed` yields a fully-initialized valid
+                    // value — `request_id` is then set below and the rest filled by UI_BEGIN_FF_UPLOAD.
                     let mut up: UinputFfUpload = unsafe { std::mem::zeroed() };
                     up.request_id = ev.value as u32;
                     if ioctl_ptr(raw, UI_BEGIN_FF_UPLOAD, &mut up, "UI_BEGIN_FF_UPLOAD").is_ok() {
@@ -442,6 +479,9 @@ impl VirtualPad {
                     }
                 }
                 (EV_UINPUT, UI_FF_ERASE) => {
+                    // SAFETY: `UinputFfErase` is `#[repr(C)]` over three integer fields (`u32`, `i32`,
+                    // `u32`); all-zero is a valid bit pattern for each, so `zeroed` produces a fully-valid
+                    // initialized value — `request_id` is set below and `effect_id` filled by the ioctl.
                     let mut er: UinputFfErase = unsafe { std::mem::zeroed() };
                     er.request_id = ev.value as u32;
                     if ioctl_ptr(raw, UI_BEGIN_FF_ERASE, &mut er, "UI_BEGIN_FF_ERASE").is_ok() {
@@ -492,6 +532,9 @@ impl VirtualPad {
 
 impl Drop for VirtualPad {
     fn drop(&mut self) {
+        // SAFETY: `self.fd` is still the live owned uinput fd here (the `OwnedFd` field is closed only
+        // AFTER this `drop` body returns), borrowed by `as_raw_fd`. UI_DEV_DESTROY takes its argument
+        // (0) BY VALUE, so nothing is dereferenced or aliased; the ioctl just tears down the device.
         let _ = unsafe { libc::ioctl(self.fd.as_raw_fd(), UI_DEV_DESTROY, 0) };
     }
 }

crates/punktfunk-host/src/inject/linux/wlr.rs

@@ -5,6 +5,9 @@
 //! keymap, and translate events into virtual pointer/keyboard requests, tracking modifier state
 //! so the compositor resolves shifted keysyms correctly.
 
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
+#![deny(clippy::undocumented_unsafe_blocks)]
+
 use super::{gs_button_to_evdev, vk_to_evdev, InputEvent, InputInjector};
 use anyhow::{bail, Context, Result};
 use punktfunk_core::input::InputKind;
@@ -264,10 +267,17 @@ impl InputInjector for WlrootsInjector {
 /// Create an anonymous in-memory file holding `s` + a trailing NUL (for the keymap fd).
 fn memfd_with(s: &str) -> Result<std::fs::File> {
     let name = b"punktfunk-keymap\0";
+    // SAFETY: `name` is a byte-string literal with an explicit trailing NUL, so `name.as_ptr()` is a
+    // valid NUL-terminated C string; `memfd_create` only reads that name (copying it) and creates an
+    // anonymous file, returning a fresh fd (or -1). `MFD_CLOEXEC` is a valid flag. The 'static literal
+    // outlives the synchronous call and nothing aliases it. The result is checked `< 0` below.
     let fd = unsafe { libc::memfd_create(name.as_ptr() as *const libc::c_char, libc::MFD_CLOEXEC) };
     if fd < 0 {
         bail!("memfd_create failed: {}", std::io::Error::last_os_error());
     }
+    // SAFETY: `fd` is the fresh memfd `memfd_create` just returned and checked `>= 0`; it is a unique
+    // open fd nothing else owns, so `File` takes sole ownership and closes it exactly once on drop —
+    // no alias, no double-close.
     let mut f = unsafe { std::fs::File::from_raw_fd(fd) };
     f.write_all(s.as_bytes()).context("write keymap")?;
     f.write_all(&[0]).context("write keymap NUL")?;

crates/punktfunk-host/src/inject/proto/dualsense_proto.rs

@@ -1,63 +1,51 @@
-//! Virtual Sony DualSense via UHID — the rich-controller path (roadmap §5).
+//! Transport-independent DualSense HID contract — shared by the Linux UHID backend
+//! ([`super::dualsense`]) and the Windows UMDF-driver backend ([`super::dualsense_windows`]).
 //!
-//! Unlike the uinput X-Box-360 pad ([`super::gamepad`]), which only carries buttons + axes + a
-//! rumble back-channel, a UHID device presents a *real* DualSense HID interface to the kernel:
-//! `hid-playstation` binds it (matched by VID `054C`/PID `0CE6`) and exposes the full controller
-//! — gamepad, motion sensors, touchpad, lightbar + player LEDs, and adaptive triggers — to games.
-//! The host writes HID **input** reports (report `0x01`, our controller state) and reads HID
-//! **output** reports (report `0x02`, a game's rumble/LED/trigger feedback) back, which it
-//! forwards to the client as [`punktfunk_core::quic::HidOutput`].
+//! This is the pure logic: the report descriptor, feature blobs, the [`DsState`] controller model
+//! and its `GameStream`/XInput mapper, the input-report serializer (report `0x01`) and the
+//! output-report parser (report `0x02`, a game's rumble / lightbar / player-LED / adaptive-trigger
+//! feedback). Neither half depends on a transport — the Linux backend writes `0x01` to `/dev/uhid`
+//! and reads `0x02` via `UHID_OUTPUT`; the Windows backend pushes `0x01` to the UMDF driver and
+//! pulls `0x02` back over its control channel — but both build/parse the exact same bytes.
 //!
-//! The report descriptor + field layout are the canonical inputtino ones (games-on-whales/
-//! inputtino `src/uhid/include/uhid/ps5.hpp`), so `hid-playstation` binds the same as a USB pad.
+//! The descriptor + field layout are the canonical inputtino ones (games-on-whales/inputtino
+//! `src/uhid/include/uhid/ps5.hpp`), so `hid-playstation` (Linux) and `hidclass` (Windows) bind the
+//! same as a real USB DualSense.
 
-use crate::gamestream::gamepad::{GamepadEvent, MAX_PADS};
-use anyhow::{Context, Result};
-use punktfunk_core::quic::{HidOutput, RichInput};
-use std::fs::{File, OpenOptions};
-use std::io::{Read, Write};
-use std::os::unix::fs::OpenOptionsExt;
-use std::time::{Duration, Instant};
+use punktfunk_core::quic::HidOutput;
 
-// /dev/uhid event ABI (linux/uhid.h). `struct uhid_event` is __packed__: a u32 `type` then a
-// union whose largest member is uhid_create2_req (128+64+64 + 2+2 + 4*4 + rd_data[4096] = 4372).
-const UHID_PATH: &str = "/dev/uhid";
-const UHID_DESTROY: u32 = 1;
-const UHID_OUTPUT: u32 = 6;
-const UHID_GET_REPORT: u32 = 9;
-const UHID_GET_REPORT_REPLY: u32 = 10;
-const UHID_CREATE2: u32 = 11;
-const UHID_INPUT2: u32 = 12;
-const HID_MAX_DESCRIPTOR_SIZE: usize = 4096;
-const UHID_EVENT_SIZE: usize = 4 + 4372; // type + union (create2)
-const BUS_USB: u16 = 0x03;
-
-// Feature reports `hid-playstation` GET_REPORTs during init — without these replies it never
-// finishes calibration and creates no input devices. Verbatim from inputtino (each array's
-// first byte is the report id). The pairing report carries a fixed virtual MAC.
+// Feature reports the host stack GET_REPORTs during init — without these replies the kernel
+// (`hid-playstation`) never finishes calibration and creates no input devices. Verbatim from
+// inputtino (each array's first byte is the report id). The pairing report carries a fixed
+// virtual MAC.
 #[rustfmt::skip]
-const DS_FEATURE_CALIBRATION: &[u8] = &[ // report 0x05 (motion calibration)
+// FIXME(cal-len): the descriptor declares report 0x05 as a 40-byte feature (id + 40 = 41 total),
+// but this blob is 42 bytes (one trailing pad byte too many). Linux `hid-playstation` tolerates it
+// (the backend is live-validated), and `hidclass` truncates to the declared length, so it is not
+// currently blocking; trim the trailing 0x00 to 41 once a physical DualSense is available to
+// re-verify motion calibration on both backends.
+pub const DS_FEATURE_CALIBRATION: &[u8] = &[ // report 0x05 (motion calibration)
     0x05, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x27, 0xF0, 0xD8, 0x10, 0x27, 0xF0, 0xD8, 0x10,
     0x27, 0xF0, 0xD8, 0xF4, 0x01, 0xF4, 0x01, 0x10, 0x27, 0xF0, 0xD8, 0x10, 0x27, 0xF0, 0xD8, 0x10,
     0x27, 0xF0, 0xD8, 0x0B, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
 ];
 #[rustfmt::skip]
-const DS_FEATURE_PAIRING: &[u8] = &[ // report 0x09 (pairing info: MAC at bytes 1..7)
+pub const DS_FEATURE_PAIRING: &[u8] = &[ // report 0x09 (pairing info: MAC at bytes 1..7)
     0x09, 0x74, 0xE7, 0xD6, 0x3A, 0x53, 0x35, 0x08, 0x25, 0x00, 0x1E, 0x00, 0xEE, 0x74, 0xD0, 0xBC,
     0x00, 0x00, 0x00, 0x00,
 ];
 #[rustfmt::skip]
-const DS_FEATURE_FIRMWARE: &[u8] = &[ // report 0x20 (firmware info / build date)
+pub const DS_FEATURE_FIRMWARE: &[u8] = &[ // report 0x20 (firmware info / build date)
     0x20, 0x4A, 0x75, 0x6E, 0x20, 0x31, 0x39, 0x20, 0x32, 0x30, 0x32, 0x33, 0x31, 0x34, 0x3A, 0x34,
     0x37, 0x3A, 0x33, 0x34, 0x03, 0x00, 0x44, 0x00, 0x08, 0x02, 0x00, 0x01, 0x36, 0x00, 0x00, 0x01,
     0xC1, 0xC8, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x54, 0x01, 0x00, 0x00,
     0x14, 0x00, 0x00, 0x00, 0x0B, 0x00, 0x01, 0x00, 0x06, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
 ];
 
-/// Sony DualSense USB HID report descriptor (232 bytes), verbatim from inputtino — the exact
-/// descriptor `hid-playstation` parses to bind a UHID device as a DualSense.
+/// Sony DualSense USB HID report descriptor (273 bytes), verbatim from inputtino — the exact
+/// descriptor `hid-playstation` (Linux) / `hidclass` (Windows) parses to bind a DualSense.
 #[rustfmt::skip]
-const DUALSENSE_RDESC: &[u8] = &[
+pub const DUALSENSE_RDESC: &[u8] = &[
     0x05, 0x01, 0x09, 0x05, 0xA1, 0x01, 0x85, 0x01, 0x09, 0x30, 0x09, 0x31, 0x09, 0x32, 0x09, 0x35,
     0x09, 0x33, 0x09, 0x34, 0x15, 0x00, 0x26, 0xFF, 0x00, 0x75, 0x08, 0x95, 0x06, 0x81, 0x02, 0x06,
     0x00, 0xFF, 0x09, 0x20, 0x95, 0x01, 0x81, 0x02, 0x05, 0x01, 0x09, 0x39, 0x15, 0x00, 0x25, 0x07,
@@ -78,23 +66,23 @@ const DUALSENSE_RDESC: &[u8] = &[
     0xC0,
 ];
 
-const DS_VENDOR: u32 = 0x054C; // Sony Interactive Entertainment
-const DS_PRODUCT: u32 = 0x0CE6; // DualSense Wireless Controller
+pub const DS_VENDOR: u32 = 0x054C; // Sony Interactive Entertainment
+pub const DS_PRODUCT: u32 = 0x0CE6; // DualSense Wireless Controller
 /// USB input report `0x01` is 64 bytes total (report id + 63-byte body).
-const DS_INPUT_REPORT_LEN: usize = 64;
+pub const DS_INPUT_REPORT_LEN: usize = 64;
 /// The DualSense touchpad's reported resolution (the kernel exposes it as ABS_MT 0..1920/1080).
 pub const DS_TOUCH_W: u16 = 1920;
 pub const DS_TOUCH_H: u16 = 1080;
 
 /// Bit positions inside the DualSense face/dpad button byte (`buttons[0]`, low nibble = hat).
-mod btn0 {
+pub mod btn0 {
     pub const SQUARE: u8 = 0x10;
     pub const CROSS: u8 = 0x20;
     pub const CIRCLE: u8 = 0x40;
     pub const TRIANGLE: u8 = 0x80;
 }
 /// `buttons[1]`: shoulders, triggers-as-buttons, create/options, stick clicks.
-mod btn1 {
+pub mod btn1 {
     pub const L1: u8 = 0x01;
     pub const R1: u8 = 0x02;
     pub const L2: u8 = 0x04;
@@ -105,7 +93,7 @@ mod btn1 {
     pub const R3: u8 = 0x80;
 }
 /// `buttons[2]`: PS, touchpad click, mute (+ a rolling counter in the high bits).
-mod btn2 {
+pub mod btn2 {
     pub const PS: u8 = 0x01;
     pub const TOUCHPAD: u8 = 0x02;
     #[allow(dead_code)]
@@ -249,12 +237,12 @@ impl DsState {
     }
 }
 
-/// Serialize a full input report `0x01` (pure — unit-testable without `/dev/uhid`). Field
+/// Serialize a full input report `0x01` (pure — unit-testable without a transport). Field
 /// offsets per the kernel's `struct dualsense_input_report`, this report's one consumer:
 /// x..rz 0-5, seq 6, buttons[4] 7-10, reserved[4] 11-14, gyro[3] 15-20, accel[3] 21-26,
 /// sensor_timestamp 27-30, reserved2 31, points[2] 32-39 (static_assert(sizeof == 63)).
 /// The report id occupies r[0], so struct offset N = r[N + 1].
-fn serialize_state(r: &mut [u8; DS_INPUT_REPORT_LEN], st: &DsState, seq: u8, ts: u32) {
+pub fn serialize_state(r: &mut [u8; DS_INPUT_REPORT_LEN], st: &DsState, seq: u8, ts: u32) {
     r[0] = 0x01; // report id; the struct fields follow (struct offset 0 == r[1])
     r[1] = st.lx;
     r[2] = st.ly;
@@ -293,7 +281,7 @@ fn pack_touch(dst: &mut [u8], t: &Touch) {
     dst[3] = ((y >> 4) & 0xFF) as u8;
 }
 
-/// What one [`DualSensePad::service`] pass extracted from the device's HID output reports.
+/// What one service pass extracted from the device's HID output reports.
 /// Rich feedback (lightbar / player LEDs / adaptive triggers) rides the HID-output plane (0xCD);
 /// motor rumble rides the universal rumble plane (0xCA) so non-DualSense clients still feel it.
 #[derive(Default)]
@@ -303,139 +291,15 @@ pub struct DsFeedback {
     pub rumble: Option<(u16, u16)>,
 }
 
-/// A virtual DualSense backed by `/dev/uhid` (hand-rolled codec — no bindgen, mirroring the
-/// uinput pad's style). Dropping it destroys the device (the kernel tears down the bound
-/// `hid-playstation` interface).
-pub struct DualSensePad {
-    fd: File,
-    seq: u8,
-    ts: u32,
-}
-
-/// Copy a NUL-padded C string field into the event buffer.
-fn put_cstr(ev: &mut [u8], off: usize, cap: usize, s: &str) {
-    let n = s.len().min(cap - 1);
-    ev[off..off + n].copy_from_slice(&s.as_bytes()[..n]); // rest already zero (NUL-terminated)
-}
-
-impl DualSensePad {
-    /// Create the UHID DualSense for pad `index` (used only to make the device name/uniq unique).
-    pub fn open(index: u8) -> Result<DualSensePad> {
-        let fd = OpenOptions::new()
-            .read(true)
-            .write(true)
-            .custom_flags(libc::O_NONBLOCK)
-            .open(UHID_PATH)
-            .with_context(|| {
-                format!("open {UHID_PATH} (is the 60-punktfunk.rules uhid rule installed + are you in 'input'?)")
-            })?;
-        let mut ds = DualSensePad { fd, seq: 0, ts: 0 };
-        ds.send_create2(index).context("UHID_CREATE2 DualSense")?;
-        Ok(ds)
-    }
-
-    fn send_create2(&mut self, index: u8) -> Result<()> {
-        let mut ev = [0u8; UHID_EVENT_SIZE];
-        ev[0..4].copy_from_slice(&UHID_CREATE2.to_ne_bytes());
-        // union (uhid_create2_req) starts at byte 4.
-        put_cstr(&mut ev, 4, 128, &format!("Punktfunk DualSense {index}")); // name[128]
-        put_cstr(&mut ev, 132, 64, &format!("punktfunk/dualsense/{index}")); // phys[64]
-        put_cstr(&mut ev, 196, 64, &format!("punktfunk-ds-{index}")); // uniq[64]
-        ev[260..262].copy_from_slice(&(DUALSENSE_RDESC.len() as u16).to_ne_bytes()); // rd_size
-        ev[262..264].copy_from_slice(&BUS_USB.to_ne_bytes()); // bus
-        ev[264..268].copy_from_slice(&DS_VENDOR.to_ne_bytes());
-        ev[268..272].copy_from_slice(&DS_PRODUCT.to_ne_bytes());
-        ev[272..276].copy_from_slice(&0x0100u32.to_ne_bytes()); // version
-        ev[276..280].copy_from_slice(&0u32.to_ne_bytes()); // country
-        ev[280..280 + DUALSENSE_RDESC.len()].copy_from_slice(DUALSENSE_RDESC); // rd_data
-        self.fd.write_all(&ev).context("write UHID_CREATE2")?;
-        Ok(())
-    }
-
-    /// Serialize `st` into report `0x01` and write it to the kernel (UHID_INPUT2).
-    pub fn write_state(&mut self, st: &DsState) -> Result<()> {
-        self.seq = self.seq.wrapping_add(1);
-        self.ts = self.ts.wrapping_add(1); // monotonic sensor timestamp is all the kernel needs
-        let mut r = [0u8; DS_INPUT_REPORT_LEN];
-        serialize_state(&mut r, st, self.seq, self.ts);
-
-        let mut ev = [0u8; UHID_EVENT_SIZE];
-        ev[0..4].copy_from_slice(&UHID_INPUT2.to_ne_bytes());
-        ev[4..6].copy_from_slice(&(r.len() as u16).to_ne_bytes()); // input2.size
-        ev[6..6 + r.len()].copy_from_slice(&r); // input2.data
-        self.fd.write_all(&ev).context("write UHID_INPUT2")?;
-        Ok(())
-    }
-
-    /// Service the device, non-blocking: answer the kernel's feature-report GET_REPORTs (calibration
-    /// / pairing / firmware — required during `hid-playstation` init, or no input devices appear)
-    /// and parse any HID OUTPUT reports (rumble / lightbar / player LEDs / adaptive triggers) into
-    /// a [`DsFeedback`] for pad `pad`. Call frequently — especially right after [`open`] so the
-    /// init handshake completes. The fd is `O_NONBLOCK`, so once drained `read` returns `WouldBlock`.
-    pub fn service(&mut self, pad: u8) -> DsFeedback {
-        let mut fb = DsFeedback::default();
-        let mut ev = [0u8; UHID_EVENT_SIZE];
-        while let Ok(n) = self.fd.read(&mut ev) {
-            if n < UHID_EVENT_SIZE {
-                break;
-            }
-            match u32::from_ne_bytes([ev[0], ev[1], ev[2], ev[3]]) {
-                UHID_OUTPUT => {
-                    // uhid_output_req: data[4096] at [4..4100], size u16 at [4100..4102].
-                    let size = u16::from_ne_bytes([ev[4100], ev[4101]]) as usize;
-                    let end = 4 + size.min(HID_MAX_DESCRIPTOR_SIZE);
-                    parse_ds_output(pad, &ev[4..end], &mut fb);
-                }
-                UHID_GET_REPORT => {
-                    // uhid_get_report_req: id u32 [4..8], rnum u8 [8].
-                    let id = u32::from_ne_bytes([ev[4], ev[5], ev[6], ev[7]]);
-                    let data: &[u8] = match ev[8] {
-                        0x05 => DS_FEATURE_CALIBRATION,
-                        0x09 => DS_FEATURE_PAIRING,
-                        0x20 => DS_FEATURE_FIRMWARE,
-                        _ => &[],
-                    };
-                    let _ = self.reply_get_report(id, data);
-                }
-                _ => {} // Start/Stop/Open/Close/SetReport — ignore
-            }
-        }
-        fb
-    }
-
-    fn reply_get_report(&mut self, id: u32, data: &[u8]) -> Result<()> {
-        let mut ev = [0u8; UHID_EVENT_SIZE];
-        ev[0..4].copy_from_slice(&UHID_GET_REPORT_REPLY.to_ne_bytes());
-        // uhid_get_report_reply_req: id u32 [4..8], err u16 [8..10], size u16 [10..12], data [12..].
-        ev[4..8].copy_from_slice(&id.to_ne_bytes());
-        let err: u16 = if data.is_empty() { 5 } else { 0 }; // EIO if we don't know the report
-        ev[8..10].copy_from_slice(&err.to_ne_bytes());
-        ev[10..12].copy_from_slice(&(data.len() as u16).to_ne_bytes());
-        ev[12..12 + data.len()].copy_from_slice(data);
-        self.fd
-            .write_all(&ev)
-            .context("write UHID_GET_REPORT_REPLY")?;
-        Ok(())
-    }
-}
-
-impl Drop for DualSensePad {
-    fn drop(&mut self) {
-        let mut ev = [0u8; UHID_EVENT_SIZE];
-        ev[0..4].copy_from_slice(&UHID_DESTROY.to_ne_bytes());
-        let _ = self.fd.write_all(&ev);
-    }
-}
-
 /// Parse a DualSense USB output report (`0x02`) into a [`DsFeedback`]. The byte layout below is
 /// the USB DualSense common report; only the well-understood fields (motor rumble, lightbar RGB,
 /// player LEDs) are surfaced — adaptive-trigger blocks are forwarded raw for the client.
 ///
 /// Every field is gated on the report's valid-flags (`valid_flag0` at data[1], `valid_flag1`
-/// at data[2]) — writers only set the bits for fields they mean to change (the kernel zeroes
-/// the rest), so an ungated parse would turn every plain rumble write into a lightbar-off +
-/// triggers-off broadcast.
-fn parse_ds_output(pad: u8, data: &[u8], fb: &mut DsFeedback) {
+/// at data[2]) — writers only set the bits for fields they mean to change (the rest is zeroed),
+/// so an ungated parse would turn every plain rumble write into a lightbar-off + triggers-off
+/// broadcast.
+pub fn parse_ds_output(pad: u8, data: &[u8], fb: &mut DsFeedback) {
     // data[0] is the report id (0x02). Be defensive about short reports.
     if data.first() != Some(&0x02) || data.len() < 48 {
         return;
@@ -482,203 +346,6 @@ fn parse_ds_output(pad: u8, data: &[u8], fb: &mut DsFeedback) {
     }
 }
 
-/// All virtual DualSense pads of a session — the rich-controller analog of
-/// [`GamepadManager`](super::gamepad::GamepadManager), selected with `PUNKTFUNK_GAMEPAD=dualsense`.
-///
-/// Unlike the uinput pad, a DualSense carries touchpad + motion, which arrive on a *separate*
-/// rich-input plane ([`apply_rich`](Self::apply_rich)) from the button/stick frames
-/// ([`handle`](Self::handle)). So the manager keeps each pad's full [`DsState`] and re-emits the
-/// merged report whenever either source changes. [`pump`](Self::pump) services the kernel
-/// handshake and routes a game's feedback back out: motor rumble on the universal plane, the rich
-/// LED/player-LED/trigger feedback on the HID-output plane.
-pub struct DualSenseManager {
-    pads: Vec<Option<DualSensePad>>,
-    /// Each pad's current full report — buttons/sticks merged with persisted touch + motion.
-    state: Vec<DsState>,
-    /// Last rumble forwarded per pad, so a report that only changes the LED doesn't re-send it.
-    last_rumble: Vec<(u16, u16)>,
-    /// When each pad last wrote an input report — drives [`DualSenseManager::heartbeat`], which
-    /// re-emits the current state during input silence so the kernel never sees the device go quiet.
-    last_write: Vec<Instant>,
-    /// Pad creation failed (e.g. /dev/uhid permissions) — warn once, drop events.
-    broken: bool,
-}
-
-impl Default for DualSenseManager {
-    fn default() -> DualSenseManager {
-        DualSenseManager::new()
-    }
-}
-
-impl DualSenseManager {
-    pub fn new() -> DualSenseManager {
-        DualSenseManager {
-            pads: (0..MAX_PADS).map(|_| None).collect(),
-            state: vec![DsState::neutral(); MAX_PADS],
-            last_rumble: vec![(0, 0); MAX_PADS],
-            last_write: vec![Instant::now(); MAX_PADS],
-            broken: false,
-        }
-    }
-
-    /// Handle one decoded controller event (create/destroy by mask, then merge button/stick state).
-    pub fn handle(&mut self, ev: &GamepadEvent) {
-        match ev {
-            GamepadEvent::Arrival { index, kind, .. } => {
-                tracing::info!(index, kind, "controller arrival (DualSense)");
-                self.ensure(*index as usize);
-            }
-            GamepadEvent::State(f) => {
-                let idx = f.index as usize;
-                if idx >= MAX_PADS {
-                    return;
-                }
-                // Unplugs: drop any allocated pad whose mask bit cleared, resetting its state.
-                for (i, slot) in self.pads.iter_mut().enumerate() {
-                    if slot.is_some() && f.active_mask & (1 << i) == 0 {
-                        tracing::info!(index = i, "controller unplugged (DualSense)");
-                        *slot = None;
-                        self.state[i] = DsState::neutral();
-                        self.last_rumble[i] = (0, 0);
-                    }
-                }
-                if f.active_mask & (1 << idx) == 0 {
-                    return; // this event WAS the unplug
-                }
-                self.ensure(idx);
-                // Merge buttons/sticks/triggers from the frame, preserving touch + motion (those
-                // come on the rich-input plane and must survive a button-only frame).
-                let prev = self.state[idx];
-                let mut s = DsState::from_gamepad(
-                    f.buttons,
-                    f.ls_x,
-                    f.ls_y,
-                    f.rs_x,
-                    f.rs_y,
-                    f.left_trigger,
-                    f.right_trigger,
-                );
-                s.touch = prev.touch;
-                s.gyro = prev.gyro;
-                s.accel = prev.accel;
-                self.state[idx] = s;
-                self.write(idx);
-            }
-        }
-    }
-
-    /// Apply one rich client→host event (touchpad contact / motion sample) to an existing pad,
-    /// preserving its button/stick state. Rich events never create a pad (a controller must have
-    /// arrived first); they're dropped if the pad isn't present.
-    pub fn apply_rich(&mut self, rich: RichInput) {
-        let idx = match rich {
-            RichInput::Touchpad { pad, .. } | RichInput::Motion { pad, .. } => pad as usize,
-        };
-        if idx >= MAX_PADS || self.pads[idx].is_none() {
-            return;
-        }
-        match rich {
-            RichInput::Touchpad {
-                finger,
-                active,
-                x,
-                y,
-                ..
-            } => {
-                // The DualSense touchpad carries two contacts; clamp to a valid slot and keep the
-                // reported contact id consistent with it (the wire `finger` is untrusted).
-                let slot = (finger as usize).min(1);
-                let t = &mut self.state[idx].touch[slot];
-                t.active = active;
-                t.id = slot as u8;
-                // Normalized 0..=65535 → the touchpad's coordinate range (0..=W-1 / 0..=H-1,
-                // what the kernel advertises as the ABS_MT extents).
-                t.x = ((x as u32 * (DS_TOUCH_W - 1) as u32) / u16::MAX as u32) as u16;
-                t.y = ((y as u32 * (DS_TOUCH_H - 1) as u32) / u16::MAX as u32) as u16;
-            }
-            RichInput::Motion { gyro, accel, .. } => {
-                self.state[idx].gyro = gyro;
-                self.state[idx].accel = accel;
-            }
-        }
-        self.write(idx);
-    }
-
-    fn write(&mut self, idx: usize) {
-        let st = self.state[idx];
-        if let Some(pad) = self.pads[idx].as_mut() {
-            let _ = pad.write_state(&st);
-        }
-        // Reset the heartbeat timer on every write (real input or heartbeat), so an actively-used
-        // pad emits no extra reports — the heartbeat only fills genuine input-silence gaps.
-        self.last_write[idx] = Instant::now();
-    }
-
-    /// Re-emit each live pad's CURRENT report if it's been silent for `max_gap`. A real DualSense
-    /// streams report `0x01` continuously (~250 Hz); the kernel `hid-playstation` driver / Proton /
-    /// SDL treat a multi-second silence (a held-steady stick produces no wire events) as an
-    /// unplugged controller — the "controller disconnected every few seconds" symptom. Re-sending
-    /// the current state is idempotent (a stale-but-correct frame, never a phantom input);
-    /// `write_state` bumps the report's seq + timestamp, so each is a fresh, well-formed report.
-    pub fn heartbeat(&mut self, max_gap: Duration) {
-        let now = Instant::now();
-        for i in 0..self.pads.len() {
-            if self.pads[i].is_some() && now.duration_since(self.last_write[i]) >= max_gap {
-                self.write(i);
-            }
-        }
-    }
-
-    fn ensure(&mut self, idx: usize) {
-        if idx >= MAX_PADS || self.pads[idx].is_some() || self.broken {
-            return;
-        }
-        match DualSensePad::open(idx as u8) {
-            Ok(p) => {
-                tracing::info!(
-                    index = idx,
-                    "virtual DualSense created (UHID hid-playstation)"
-                );
-                self.pads[idx] = Some(p);
-                self.state[idx] = DsState::neutral();
-                self.last_rumble[idx] = (0, 0);
-                self.last_write[idx] = Instant::now();
-            }
-            Err(e) => {
-                tracing::error!(error = %format!("{e:#}"), "virtual DualSense creation failed — controller input disabled");
-                self.broken = true;
-            }
-        }
-    }
-
-    /// Service every pad: answer the kernel's init handshake and parse a game's feedback. `rumble`
-    /// is invoked `(index, low, high)` only when the motor level *changes* (the universal 0xCA
-    /// plane — both backends use it); `hidout` is invoked for each DualSense-only rich feedback
-    /// event (lightbar / player LEDs / adaptive triggers — the 0xCD plane). Call frequently:
-    /// the kernel blocks `hid-playstation` init until its GET_REPORTs are answered.
-    pub fn pump(
-        &mut self,
-        mut rumble: impl FnMut(u16, u16, u16),
-        mut hidout: impl FnMut(HidOutput),
-    ) {
-        for i in 0..self.pads.len() {
-            let Some(pad) = self.pads[i].as_mut() else {
-                continue;
-            };
-            let fb = pad.service(i as u8);
-            if let Some(r) = fb.rumble {
-                if self.last_rumble[i] != r {
-                    self.last_rumble[i] = r;
-                    rumble(i as u16, r.0, r.1);
-                }
-            }
-            for h in fb.hidout {
-                hidout(h);
-            }
-        }
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -725,12 +392,12 @@ mod tests {
         assert_eq!(triggers, vec![(1, 0x21), (0, 0x26)]);
     }
 
-    /// Writers set only the valid-flag bits for the fields they mean to change (the kernel
-    /// zeroes the rest of the report) — a plain rumble write must NOT blank the lightbar /
-    /// player LEDs / triggers, and an LED-only write must not stop the motors.
+    /// Writers set only the valid-flag bits for the fields they mean to change (the rest of the
+    /// report is zeroed) — a plain rumble write must NOT blank the lightbar / player LEDs /
+    /// triggers, and an LED-only write must not stop the motors.
     #[test]
     fn parse_output_respects_valid_flags() {
-        // Kernel-style rumble write: only the vibration flags set, everything else zero.
+        // Rumble write: only the vibration flags set, everything else zero.
         let mut data = vec![0u8; 48];
         data[0] = 0x02;
         data[1] = 0x03; // compatible vibration + haptics select

crates/punktfunk-host/src/inject/proto/dualshock4_proto.rs

@@ -0,0 +1,180 @@
+//! Transport-independent DualShock 4 HID contract — the pure report codec used by the Windows
+//! UMDF-driver backend ([`super::dualshock4_windows`]).
+//!
+//! FIXME(ds4-dedup): the Linux UHID backend ([`super::dualshock4`]) still carries its own byte-
+//! identical copy of this codec (`serialize_state` / `parse_ds4_output` / `Ds4Feedback` / the touch
+//! dims). Fold it onto this module once the Linux build can be re-validated (it is `cfg(linux)`, so
+//! it can't be compile-checked from a Windows host). Keep the two in sync until then.
+//!
+//! The PS4 sibling of [`super::dualsense_proto`]: the pure report codec with no transport. The DS4
+//! reuses the DualSense [`DsState`] controller model + its `GameStream`/XInput mapper
+//! ([`DsState::from_gamepad`]) — only the report *byte layout*, the touchpad resolution, and the
+//! feedback report differ. The Linux backend writes report `0x01` to `/dev/uhid` and reads `0x05` via
+//! `UHID_OUTPUT`; the Windows backend pushes `0x01` to the UMDF driver and pulls `0x05` back over its
+//! shared-memory channel — both build/parse the exact same bytes here.
+//!
+//! Field offsets are the canonical real-DS4-USB layout the kernel `struct
+//! dualshock4_input_report_usb` / `_output_report_common` parse.
+
+use super::dualsense_proto::{DsState, Touch};
+use punktfunk_core::quic::HidOutput;
+
+/// DualShock 4 v2 USB identity (Sony Interactive Entertainment / CUH-ZCT2).
+pub const DS4_VENDOR: u16 = 0x054C;
+pub const DS4_PRODUCT: u16 = 0x09CC;
+/// USB input report `0x01` is 64 bytes total (report id + 63-byte body).
+pub const DS4_INPUT_REPORT_LEN: usize = 64;
+/// The DualShock 4 touchpad resolution the kernel advertises (ABS_MT 0..1919 / 0..941). Narrower
+/// than the DualSense's 1920×1080.
+pub const DS4_TOUCH_W: u16 = 1920;
+pub const DS4_TOUCH_H: u16 = 942;
+
+/// Pack one touchpad contact into the DS4's 4-byte point (same bit layout as the DualSense's:
+/// byte0 bit7 = NOT-active, bits0-6 = id; 12-bit X then 12-bit Y).
+fn pack_touch(dst: &mut [u8], t: &Touch) {
+    dst[0] = (t.id & 0x7F) | if t.active { 0 } else { 0x80 };
+    // Never emit the extent itself — the kernel advertises 0..=W-1 / 0..=H-1.
+    let (x, y) = (t.x.min(DS4_TOUCH_W - 1), t.y.min(DS4_TOUCH_H - 1));
+    dst[1] = (x & 0xFF) as u8;
+    dst[2] = (((x >> 8) & 0x0F) as u8) | (((y & 0x0F) as u8) << 4);
+    dst[3] = ((y >> 4) & 0xFF) as u8;
+}
+
+/// Serialize a full DS4 input report `0x01` (pure — unit-testable without a transport). Field offsets
+/// per the kernel's `struct dualshock4_input_report_usb` { report_id; common; num_touch; touch[3];
+/// rsvd[3] } where `common` = { x,y,rx,ry; buttons[3]; z,rz; sensor_ts le16; temp; gyro[3] le16;
+/// accel[3] le16; rsvd[5]; status[2]; rsvd }. The report id is byte 0, so a `common` field at struct
+/// offset N sits at report byte N+1.
+pub fn serialize_state(r: &mut [u8; DS4_INPUT_REPORT_LEN], st: &DsState, counter: u8, ts: u16) {
+    r[0] = 0x01; // report id
+    r[1] = st.lx;
+    r[2] = st.ly;
+    r[3] = st.rx;
+    r[4] = st.ry;
+    r[5] = (st.dpad & 0x0F) | (st.buttons[0] & 0xF0); // dpad hat (low) + face buttons (high)
+    r[6] = st.buttons[1]; // L1/R1, L2/R2 digital, Share/Options, L3/R3
+    r[7] = (st.buttons[2] & 0x03) | ((counter & 0x3F) << 2); // PS + touchpad-click + report counter
+    r[8] = st.l2; // L2 analog (z)
+    r[9] = st.r2; // R2 analog (rz)
+    r[10..12].copy_from_slice(&ts.to_le_bytes()); // sensor_timestamp (struct off 9)
+                                                  // r[12] temperature stays 0
+    for (i, v) in st.gyro.iter().enumerate() {
+        r[13 + i * 2..15 + i * 2].copy_from_slice(&v.to_le_bytes()); // gyro at struct off 12
+    }
+    for (i, v) in st.accel.iter().enumerate() {
+        r[19 + i * 2..21 + i * 2].copy_from_slice(&v.to_le_bytes()); // accel at struct off 18
+    }
+    // r[25..30] reserved2.
+    // status[0] (struct off 29 → r[30]): bit4 = cable/wired, low nibble = battery capacity. Report
+    // wired + full (0x1B) so SteamOS / the kernel never warn "low battery" on a virtual pad.
+    r[30] = 0x10 | 0x0B;
+    // r[31] status[1] = 0 (no headphone/mic), r[32] reserved3 = 0.
+    r[33] = 1; // num_touch_reports: one frame carrying the two contacts (a real DS4 always sends one)
+    r[34] = ts as u8; // touch_reports[0].timestamp
+    pack_touch(&mut r[35..39], &st.touch[0]); // touch point 0
+    pack_touch(&mut r[39..43], &st.touch[1]); // touch point 1
+                                              // remaining touch frames (r[43..61]) + reserved (r[61..64]) stay zero
+}
+
+/// What one feedback pass extracted from the device's HID output reports. Rumble rides the universal
+/// 0xCA plane; the lightbar rides the HID-output 0xCD plane (DS4 has no player LEDs or adaptive
+/// triggers, so those never appear).
+#[derive(Default)]
+pub struct Ds4Feedback {
+    pub hidout: Vec<HidOutput>,
+    /// `(low, high)` motor levels (0..=0xFF00), if a report carried them.
+    pub rumble: Option<(u16, u16)>,
+    /// Lightbar RGB, if the report carried it (deduped by the manager).
+    pub led: Option<(u8, u8, u8)>,
+}
+
+/// Parse a DualShock 4 USB output report (`0x05`) into a [`Ds4Feedback`]. Layout per the kernel
+/// `struct dualshock4_output_report_common`: valid_flag0 (bit0 motor, bit1 LED, bit2 blink) at [1],
+/// valid_flag1 [2], reserved [3], motor_right (weak/small) [4], motor_left (strong/large) [5],
+/// lightbar R/G/B [6..9], blink on/off [9..11]. Gated on the valid-flags so a rumble-only write
+/// doesn't masquerade as a lightbar change.
+pub fn parse_ds4_output(data: &[u8], fb: &mut Ds4Feedback) {
+    if data.first() != Some(&0x05) || data.len() < 11 {
+        return; // not the USB output report (BT 0x11 is shifted) / too short
+    }
+    let flag0 = data[1];
+    if flag0 & 0x01 != 0 {
+        // motor_left (strong/large/low-freq) at [5], motor_right (weak/small/high-freq) at [4];
+        // scale 0..255 → 0..0xFF00, same (low, high) convention as the other backends.
+        let low = (data[5] as u16) << 8;
+        let high = (data[4] as u16) << 8;
+        fb.rumble = Some((low, high));
+    }
+    if flag0 & 0x02 != 0 {
+        fb.led = Some((data[6], data[7], data[8]));
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Report 0x01 places sticks/buttons/triggers/motion/touch at the kernel's DS4 offsets.
+    #[test]
+    fn serialize_offsets() {
+        use punktfunk_core::input::gamepad as gs;
+        let mut st = DsState::from_gamepad(
+            gs::BTN_A | gs::BTN_DPAD_UP | gs::BTN_LB,
+            16384, // lx (right)
+            0,
+            0,
+            -32768, // ry (down) — inverted to 0xFF
+            200,    // L2
+            0,
+        );
+        st.gyro = [0x0102, 0x0304, 0x0506];
+        st.accel = [0x1112, 0x1314, 0x1516];
+        st.touch[0] = Touch {
+            active: true,
+            id: 0,
+            x: 100,
+            y: 200,
+        };
+        let mut r = [0u8; DS4_INPUT_REPORT_LEN];
+        serialize_state(&mut r, &st, 0, 0);
+        assert_eq!(r[0], 0x01); // report id
+        assert_eq!(r[8], 200); // L2 analog at byte 8 (not the DualSense's byte 5)
+        assert_eq!(r[5] & 0x0F, 0); // dpad hat = N (up)
+        assert_eq!(r[5] & 0x20, 0x20); // Cross (A) face bit
+        assert_eq!(r[6] & 0x01, 0x01); // L1
+                                       // gyro le16 at 13..19, accel le16 at 19..25.
+        assert_eq!(&r[13..19], &[0x02, 0x01, 0x04, 0x03, 0x06, 0x05]);
+        assert_eq!(&r[19..25], &[0x12, 0x11, 0x14, 0x13, 0x16, 0x15]);
+        assert_eq!(r[33], 1); // one touch frame
+        assert_eq!(r[35] & 0x80, 0); // contact 0 active (bit7 clear)
+        assert_eq!(r[35] & 0x7F, 0); // contact id 0
+        assert_eq!(r[30] & 0x10, 0x10); // cable/wired bit set
+    }
+
+    /// A DS4 USB output report (`0x05`) with motor + LED flags parses into rumble (0xCA) and a
+    /// lightbar `Led` (0xCD); a rumble-only report (no LED flag) leaves the lightbar untouched.
+    #[test]
+    fn parse_output_rumble_and_lightbar() {
+        let mut report = [0u8; 32];
+        report[0] = 0x05;
+        report[1] = 0x01 | 0x02; // MOTOR | LED
+        report[4] = 0x40; // motor_right (weak/high)
+        report[5] = 0x80; // motor_left (strong/low)
+        report[6] = 0x11; // R
+        report[7] = 0x22; // G
+        report[8] = 0x33; // B
+        let mut fb = Ds4Feedback::default();
+        parse_ds4_output(&report, &mut fb);
+        assert_eq!(fb.rumble, Some((0x8000, 0x4000))); // (low=strong, high=weak)
+        assert_eq!(fb.led, Some((0x11, 0x22, 0x33)));
+
+        let mut motor_only = [0u8; 32];
+        motor_only[0] = 0x05;
+        motor_only[1] = 0x01; // MOTOR only
+        motor_only[5] = 0x10;
+        let mut fb2 = Ds4Feedback::default();
+        parse_ds4_output(&motor_only, &mut fb2);
+        assert!(fb2.rumble.is_some());
+        assert_eq!(fb2.led, None); // lightbar not asserted → no spurious change
+    }
+}

crates/punktfunk-host/src/inject/windows/dualsense_windows.rs

@@ -0,0 +1,482 @@
+//! Virtual Sony DualSense on Windows via the UMDF minidriver (`packaging/windows/dualsense-driver`).
+//!
+//! The Windows analogue of the Linux UHID backend ([`super::dualsense`]): same [`DsState`] model and
+//! the same byte-level report codec ([`super::dualsense_proto`]), but a different transport. Where
+//! the Linux backend writes report `0x01` to `/dev/uhid` and reads report `0x02` via `UHID_OUTPUT`,
+//! the Windows backend talks to the UMDF driver over a **named shared-memory section**
+//! `Global\pfds-shm-<idx>` (256 B: magic `u32@0`, input report `@8`, output seq `u32@72`, output
+//! report `@76`). The host creates the section (privileged → a permissive SDDL so the WUDFHost can
+//! open it); the driver maps it from its timer, feeds game `READ_REPORT`s from the input bytes, and
+//! publishes a game's `0x02` (rumble / lightbar / player-LEDs / adaptive triggers) into the output
+//! bytes. `hidclass` gates the device stack, so this user-mode IPC is the only viable channel (a
+//! UMDF driver has no control device); see `windows-dualsense-scoping.md`.
+//!
+//! Device lifecycle: each pad `SwDeviceCreate`s a `pf_pad_<index>` software devnode (hardware id
+//! `pf_dualsense`, enumerator `punktfunk`) on open and `SwDeviceClose`s it on drop, so the virtual
+//! DualSense appears/disappears with the session — matching the Linux UHID pad. (The driver itself
+//! must already be installed; the installer stages it.)
+
+use super::dualsense_proto::{
+    parse_ds_output, serialize_state, DsFeedback, DsState, DS_INPUT_REPORT_LEN, DS_TOUCH_H,
+    DS_TOUCH_W,
+};
+use crate::gamestream::gamepad::{GamepadEvent, MAX_PADS};
+use anyhow::{anyhow, Result};
+use punktfunk_core::quic::{HidOutput, RichInput};
+use std::ffi::c_void;
+use std::time::{Duration, Instant};
+use windows::core::{w, GUID, HRESULT, HSTRING, PCWSTR};
+use windows::Win32::Devices::Enumeration::Pnp::{
+    SwDeviceClose, SwDeviceCreate, HSWDEVICE, SW_DEVICE_CREATE_INFO,
+};
+use windows::Win32::Foundation::{CloseHandle, HANDLE};
+use windows::Win32::System::Threading::{CreateEventW, SetEvent, WaitForSingleObject};
+
+/// Shared-section layout — the single source of truth is [`pf_driver_proto::gamepad::PadShm`] (offset
+/// asserts pin every field; the `pf_dualsense` driver maps the same struct). Derive the size/offsets/magic
+/// from it so a layout change is a compile error, not a hand-synced literal (audit §6.1). `pub(super)` so
+/// the sibling DualShock 4 backend ([`super::dualshock4_windows`]) reuses the exact offsets.
+pub(super) const SHM_SIZE: usize = core::mem::size_of::<pf_driver_proto::gamepad::PadShm>();
+pub(super) const SHM_MAGIC: u32 = pf_driver_proto::gamepad::PAD_MAGIC; // "PFDS"
+pub(super) const OFF_INPUT: usize = core::mem::offset_of!(pf_driver_proto::gamepad::PadShm, input);
+pub(super) const OFF_OUT_SEQ: usize =
+    core::mem::offset_of!(pf_driver_proto::gamepad::PadShm, out_seq);
+pub(super) const OFF_OUTPUT: usize =
+    core::mem::offset_of!(pf_driver_proto::gamepad::PadShm, output);
+/// Device-type selector the driver reads to choose which HID identity/descriptor it serves: 0 =
+/// DualSense (the default — the section is zeroed), 1 = DualShock 4.
+pub(super) const OFF_DEVTYPE: usize =
+    core::mem::offset_of!(pf_driver_proto::gamepad::PadShm, device_type);
+pub(super) const DEVTYPE_DUALSHOCK4: u8 = pf_driver_proto::gamepad::DEVTYPE_DUALSHOCK4;
+
+/// A single virtual DualSense: the SwDeviceCreate'd `pf_pad_<index>` software devnode (the driver
+/// loads on it and the HID DualSense appears to games) plus the shared-memory section the driver maps.
+/// Dropping it removes the devnode (`SwDeviceClose`) and unmaps + closes the section.
+struct DsWinPad {
+    /// Per-session devnode from SwDeviceCreate, when it succeeds (RAII — `SwDeviceClose` on drop).
+    /// `None` falls back to an out-of-band `pf_dualsense` devnode (installer/devgen).
+    _sw: Option<super::gamepad_raii::SwDevice>,
+    /// The named shared section the driver maps (RAII — unmapped + closed on drop).
+    shm: super::gamepad_raii::Shm,
+    seq: u8,
+    ts: u32,
+    last_out_seq: u32,
+}
+
+/// Context for the `SwDeviceCreate` completion callback: an event to signal + the HRESULT it reports.
+#[repr(C)]
+struct SwCreateCtx {
+    event: HANDLE,
+    result: HRESULT,
+}
+
+/// `SwDeviceCreate` fires this once PnP has enumerated the device; stash the result and wake the
+/// creator, which blocks on the event (so there's no concurrent access to `*ctx`).
+unsafe extern "system" fn sw_create_cb(
+    _dev: HSWDEVICE,
+    result: HRESULT,
+    ctx: *const c_void,
+    _id: PCWSTR,
+) {
+    if !ctx.is_null() {
+        // SAFETY: ctx is the &mut SwCreateCtx the creator passed; it outlives this callback.
+        unsafe {
+            let c = ctx as *mut SwCreateCtx;
+            (*c).result = result;
+            let _ = SetEvent((*c).event);
+        }
+    }
+}
+
+/// The PnP identity for a virtual controller devnode — varies by controller type so the same
+/// [`create_swdevice`] builds a DualSense (`VID_054C&PID_0CE6`) or a DualShock 4
+/// (`VID_054C&PID_09CC`). The fields map onto the `SW_DEVICE_CREATE_INFO` identity discussed below.
+pub(super) struct SwDeviceProfile<'a> {
+    /// PnP instance id — distinct namespaces per type (`pf_pad_<idx>` vs `pf_ds4_<idx>`) so the two
+    /// never reuse the same devnode shell.
+    pub instance: &'a str,
+    /// Index for the deterministic per-pad ContainerId.
+    pub container_index: u8,
+    /// The INF-matched hardware id (`pf_dualsense` / `pf_dualshock4`), listed FIRST so the INF binds.
+    pub hwid: &'a str,
+    /// The USB VID&PID token (`VID_054C&PID_0CE6`) used to synthesize the USB hardware/compatible ids.
+    pub usb_vid_pid: &'a str,
+    /// Device description shown in Device Manager.
+    pub description: &'a str,
+}
+
+/// Spawn the per-session virtual controller devnode under enumerator `punktfunk` (instance
+/// `profile.instance`). The returned `HSWDEVICE` owns it — `SwDeviceClose` removes it on drop, so the
+/// pad appears/disappears with the session and nothing persists.
+///
+/// **Game-detection identity** (see `design/windows-dualsense-game-detection.md`). `HIDD_ATTRIBUTES`
+/// alone (VID/PID via the IOCTL) satisfies SDL/HIDAPI/RawInput, but a native PS5 path (libScePad-
+/// style raw HID) classifies the *connection type* by walking from the HID child to its parent
+/// (`CM_Get_Parent`) and string-matching `"USB"`/`"BTHENUM"` in that parent's
+/// `DEVPKEY_Device_CompatibleIds`; with no bus identity the pad reads as `UNKNOWN` and the native
+/// path rejects it. So we set, via `SW_DEVICE_CREATE_INFO` (NOT `pProperties` — bus/identity info is
+/// create-time-only and a `DEVPROPERTY` write of these keys is ignored):
+/// - `pszzCompatibleIds` starting with a `USB\` token → the parent walk resolves `bus_type = USB`.
+/// - `pszzHardwareIds` = `pf_dualsense` **first** (so the INF still binds our UMDF driver) followed
+///   by `USB\VID_054C&PID_0CE6[&REV_0100]`, which makes hidclass derive the real-DualSense child
+///   hardware ids `HID\VID_054C&PID_0CE6[&REV_0100]` (the set a genuine USB DS5 exposes).
+/// - a deterministic, non-sentinel per-pad `pContainerId` (groups the pad's devnodes; avoids the
+///   null-sentinel ContainerId that trips an `xinput1_4` slot-skip bug).
+///
+/// (Validated live on `.173`: the INF still binds, the child gains the `HID\VID&PID` ids, and the
+/// parent walk reports USB. Remaining gap: GameInput parses VID/PID from the child *instance path*
+/// `HID\punktfunk\…`, which only a real USB-bus instance path — a bus driver — would change.)
+///
+/// Two requirements each yield E_INVALIDARG if violated: the enumerator name must not contain `_`
+/// (hence `punktfunk`, not `pf_dualsense`), and the completion callback is mandatory (the docs mark
+/// `pCallback` as `[in]`, not optional — a NULL callback is rejected). The caller must be
+/// Administrator (the host service runs as LocalSystem).
+pub(super) fn create_swdevice(p: &SwDeviceProfile) -> Result<HSWDEVICE> {
+    // Build a double-NUL-terminated UTF-16 multi-sz from a list of ids.
+    let multi_sz = |ids: &[&str]| -> Vec<u16> {
+        ids.iter()
+            .flat_map(|s| s.encode_utf16().chain(std::iter::once(0)))
+            .chain(std::iter::once(0))
+            .collect()
+    };
+    let usb_rev = format!("USB\\{}&REV_0100", p.usb_vid_pid);
+    let usb = format!("USB\\{}", p.usb_vid_pid);
+    let hwids = multi_sz(&[
+        p.hwid, // FIRST → the INF binds our UMDF driver on this id
+        usb_rev.as_str(),
+        usb.as_str(),
+    ]);
+    let compat = multi_sz(&[
+        usb.as_str(), // a `USB\` token → native bus-type detection resolves USB
+        "USB\\Class_03&SubClass_00&Prot_00",
+        "USB\\Class_03",
+    ]);
+    let instid: Vec<u16> = p
+        .instance
+        .encode_utf16()
+        .chain(std::iter::once(0))
+        .collect();
+    let desc: Vec<u16> = p
+        .description
+        .encode_utf16()
+        .chain(std::iter::once(0))
+        .collect();
+    // The pad index, stamped into the device Location — the driver reads it to map `pfds-shm-<index>`
+    // (multi-pad). The buffer outlives the SwDeviceCreate call (we wait on the event before return).
+    let loc: Vec<u16> = format!("{}", p.container_index)
+        .encode_utf16()
+        .chain(std::iter::once(0))
+        .collect();
+    // Deterministic per-pad ContainerId {50464453-0000-0000-0000-0000000000<idx>} ("PFDS").
+    let container = GUID::from_values(
+        0x5046_4453,
+        0x0000,
+        0x0000,
+        [0, 0, 0, 0, 0, 0, 0, p.container_index],
+    );
+
+    // SAFETY: zeroed then the fields we use are set; cbSize identifies the struct version. The id
+    // buffers and `container` outlive the SwDeviceCreate call (we wait on the event before return).
+    let mut info: SW_DEVICE_CREATE_INFO = unsafe { std::mem::zeroed() };
+    info.cbSize = std::mem::size_of::<SW_DEVICE_CREATE_INFO>() as u32;
+    info.pszInstanceId = PCWSTR(instid.as_ptr());
+    info.pszzHardwareIds = PCWSTR(hwids.as_ptr());
+    info.pszzCompatibleIds = PCWSTR(compat.as_ptr());
+    info.pContainerId = &container;
+    info.pszDeviceDescription = PCWSTR(desc.as_ptr());
+    info.pszDeviceLocation = PCWSTR(loc.as_ptr());
+    info.CapabilityFlags = 0x0000_000B; // DriverRequired | SilentInstall | Removable
+
+    // SAFETY: a manual-reset, initially-unsignaled, unnamed event.
+    let event = unsafe { CreateEventW(None, true, false, PCWSTR::null())? };
+    let mut ctx = SwCreateCtx {
+        event,
+        result: HRESULT(0),
+    };
+    // SAFETY: info + the buffers + ctx outlive the call (we wait on the event before returning);
+    // windows-rs returns the HSWDEVICE (the C out-param) as the Result value.
+    let hsw = match unsafe {
+        SwDeviceCreate(
+            w!("punktfunk"),
+            w!("HTREE\\ROOT\\0"),
+            &info,
+            None,
+            Some(sw_create_cb),
+            Some(&mut ctx as *mut SwCreateCtx as *const c_void),
+        )
+    } {
+        Ok(h) => h,
+        Err(e) => {
+            // SAFETY: event is valid.
+            unsafe {
+                let _ = CloseHandle(event);
+            }
+            return Err(anyhow!("SwDeviceCreate failed: {e}"));
+        }
+    };
+    // Block until PnP finishes enumerating (the callback signals), then check its result.
+    // SAFETY: event is valid.
+    unsafe {
+        WaitForSingleObject(event, 10_000);
+        let _ = CloseHandle(event);
+    }
+    if ctx.result.is_err() {
+        // SAFETY: hsw is the handle SwDeviceCreate returned.
+        unsafe { SwDeviceClose(hsw) };
+        return Err(anyhow!(
+            "SwDeviceCreate enumeration failed: {:?}",
+            ctx.result
+        ));
+    }
+    Ok(hsw)
+}
+
+impl DsWinPad {
+    /// Create + map the section `Global\pfds-shm-<index>`, stamp the magic, then spawn the
+    /// `root\pf_dualsense` devnode (the driver loads on it and maps the section). The devnode lives
+    /// for the pad's lifetime — dropping the pad removes it (`SwDeviceClose`).
+    fn open(index: u8) -> Result<DsWinPad> {
+        let shm = super::gamepad_raii::Shm::create(
+            &HSTRING::from(pf_driver_proto::gamepad::pad_shm_name(index)),
+            SHM_SIZE,
+        )?;
+        let base = shm.base();
+        // Stamp the neutral input report, then the magic LAST (the driver only accepts the section
+        // once magic is set). The device-type stays 0 (DualSense — the section is already zeroed).
+        // SAFETY: base points at SHM_SIZE writable bytes.
+        unsafe {
+            std::ptr::write_unaligned(base.add(OFF_INPUT) as *mut [u8; DS_INPUT_REPORT_LEN], {
+                let mut r = [0u8; DS_INPUT_REPORT_LEN];
+                serialize_state(&mut r, &DsState::neutral(), 0, 0);
+                r
+            });
+            std::ptr::write_unaligned(base as *mut u32, SHM_MAGIC);
+        }
+        // Spawn the per-session devnode via SwDeviceCreate; `SwDeviceClose` removes it on drop. On the
+        // rare failure we keep the section + data plane and fall back to an out-of-band `pf_dualsense`
+        // devnode (installer / dev-box devgen).
+        let inst = format!("pf_pad_{index}");
+        let hsw = match create_swdevice(&SwDeviceProfile {
+            instance: &inst,
+            container_index: index,
+            hwid: "pf_dualsense",
+            usb_vid_pid: "VID_054C&PID_0CE6",
+            description: "punktfunk Virtual DualSense",
+        }) {
+            Ok(h) => Some(h),
+            Err(e) => {
+                tracing::warn!(error = %format!("{e:#}"), "SwDeviceCreate failed; falling back to an out-of-band pf_dualsense devnode");
+                None
+            }
+        };
+        let _sw = hsw.map(super::gamepad_raii::SwDevice::new);
+        Ok(DsWinPad {
+            _sw,
+            shm,
+            seq: 0,
+            ts: 0,
+            last_out_seq: 0,
+        })
+    }
+
+    /// Serialize `st` into report `0x01` and publish it to the section's input slot.
+    fn write_state(&mut self, st: &DsState) {
+        self.seq = self.seq.wrapping_add(1);
+        self.ts = self.ts.wrapping_add(1);
+        let mut r = [0u8; DS_INPUT_REPORT_LEN];
+        serialize_state(&mut r, st, self.seq, self.ts);
+        // SAFETY: base points at SHM_SIZE bytes; input slot is OFF_INPUT..OFF_INPUT+64.
+        unsafe {
+            std::ptr::copy_nonoverlapping(r.as_ptr(), self.shm.base().add(OFF_INPUT), r.len())
+        };
+    }
+
+    /// Poll the section's output slot; parse a new `0x02` report (rumble / LEDs / triggers) into a
+    /// [`DsFeedback`] for pad `pad`. Returns empty feedback if the driver hasn't published anything new.
+    fn service(&mut self, pad: u8) -> DsFeedback {
+        let mut fb = DsFeedback::default();
+        // SAFETY: base points at SHM_SIZE bytes.
+        let seq =
+            unsafe { std::ptr::read_unaligned(self.shm.base().add(OFF_OUT_SEQ) as *const u32) };
+        if seq != self.last_out_seq {
+            self.last_out_seq = seq;
+            let mut out = [0u8; 64];
+            // SAFETY: output slot is OFF_OUTPUT..OFF_OUTPUT+64 within the section.
+            unsafe {
+                std::ptr::copy_nonoverlapping(self.shm.base().add(OFF_OUTPUT), out.as_mut_ptr(), 64)
+            };
+            parse_ds_output(pad, &out, &mut fb);
+        }
+        fb
+    }
+}
+
+/// All virtual DualSense pads of a session — the Windows analogue of
+/// [`DualSenseManager`](super::dualsense::DualSenseManager). Same method surface so the session input
+/// thread drives either backend identically.
+pub struct DualSenseWindowsManager {
+    pads: Vec<Option<DsWinPad>>,
+    state: Vec<DsState>,
+    last_rumble: Vec<(u16, u16)>,
+    last_write: Vec<Instant>,
+    broken: bool,
+}
+
+impl Default for DualSenseWindowsManager {
+    fn default() -> DualSenseWindowsManager {
+        DualSenseWindowsManager::new()
+    }
+}
+
+impl DualSenseWindowsManager {
+    pub fn new() -> DualSenseWindowsManager {
+        DualSenseWindowsManager {
+            pads: (0..MAX_PADS).map(|_| None).collect(),
+            state: vec![DsState::neutral(); MAX_PADS],
+            last_rumble: vec![(0, 0); MAX_PADS],
+            last_write: vec![Instant::now(); MAX_PADS],
+            broken: false,
+        }
+    }
+
+    /// Handle one decoded controller event (create/destroy by mask, then merge button/stick state).
+    pub fn handle(&mut self, ev: &GamepadEvent) {
+        match ev {
+            GamepadEvent::Arrival { index, kind, .. } => {
+                tracing::info!(index, kind, "controller arrival (DualSense/Windows)");
+                self.ensure(*index as usize);
+            }
+            GamepadEvent::State(f) => {
+                let idx = f.index as usize;
+                if idx >= MAX_PADS {
+                    return;
+                }
+                for (i, slot) in self.pads.iter_mut().enumerate() {
+                    if slot.is_some() && f.active_mask & (1 << i) == 0 {
+                        tracing::info!(index = i, "controller unplugged (DualSense/Windows)");
+                        *slot = None;
+                        self.state[i] = DsState::neutral();
+                        self.last_rumble[i] = (0, 0);
+                    }
+                }
+                if f.active_mask & (1 << idx) == 0 {
+                    return;
+                }
+                self.ensure(idx);
+                let prev = self.state[idx];
+                let mut s = DsState::from_gamepad(
+                    f.buttons,
+                    f.ls_x,
+                    f.ls_y,
+                    f.rs_x,
+                    f.rs_y,
+                    f.left_trigger,
+                    f.right_trigger,
+                );
+                s.touch = prev.touch;
+                s.gyro = prev.gyro;
+                s.accel = prev.accel;
+                self.state[idx] = s;
+                self.write(idx);
+            }
+        }
+    }
+
+    /// Apply one rich client→host event (touchpad contact / motion sample) to an existing pad.
+    pub fn apply_rich(&mut self, rich: RichInput) {
+        let idx = match rich {
+            RichInput::Touchpad { pad, .. } | RichInput::Motion { pad, .. } => pad as usize,
+        };
+        if idx >= MAX_PADS || self.pads[idx].is_none() {
+            return;
+        }
+        match rich {
+            RichInput::Touchpad {
+                finger,
+                active,
+                x,
+                y,
+                ..
+            } => {
+                let slot = (finger as usize).min(1);
+                let t = &mut self.state[idx].touch[slot];
+                t.active = active;
+                t.id = slot as u8;
+                t.x = ((x as u32 * (DS_TOUCH_W - 1) as u32) / u16::MAX as u32) as u16;
+                t.y = ((y as u32 * (DS_TOUCH_H - 1) as u32) / u16::MAX as u32) as u16;
+            }
+            RichInput::Motion { gyro, accel, .. } => {
+                self.state[idx].gyro = gyro;
+                self.state[idx].accel = accel;
+            }
+        }
+        self.write(idx);
+    }
+
+    fn write(&mut self, idx: usize) {
+        let st = self.state[idx];
+        if let Some(pad) = self.pads[idx].as_mut() {
+            pad.write_state(&st);
+        }
+        self.last_write[idx] = Instant::now();
+    }
+
+    /// Re-emit each live pad's current report if it's been silent for `max_gap` (the driver's timer
+    /// streams whatever's in the section, so this just keeps the section fresh / future-proofs parity
+    /// with the UHID backend's heartbeat).
+    pub fn heartbeat(&mut self, max_gap: Duration) {
+        let now = Instant::now();
+        for i in 0..self.pads.len() {
+            if self.pads[i].is_some() && now.duration_since(self.last_write[i]) >= max_gap {
+                self.write(i);
+            }
+        }
+    }
+
+    fn ensure(&mut self, idx: usize) {
+        if idx >= MAX_PADS || self.pads[idx].is_some() || self.broken {
+            return;
+        }
+        match DsWinPad::open(idx as u8) {
+            Ok(p) => {
+                tracing::info!(
+                    index = idx,
+                    "virtual DualSense created (Windows UMDF shm channel)"
+                );
+                self.pads[idx] = Some(p);
+                self.state[idx] = DsState::neutral();
+                self.last_rumble[idx] = (0, 0);
+                self.last_write[idx] = Instant::now();
+            }
+            Err(e) => {
+                tracing::error!(error = %format!("{e:#}"), "virtual DualSense creation failed — controller input disabled");
+                self.broken = true;
+            }
+        }
+    }
+
+    /// Service every pad: poll the section for a game's feedback. `rumble` fires `(index, low, high)`
+    /// only on change (universal 0xCA plane); `hidout` fires for each rich DualSense feedback event
+    /// (lightbar / player LEDs / adaptive triggers — 0xCD plane).
+    pub fn pump(
+        &mut self,
+        mut rumble: impl FnMut(u16, u16, u16),
+        mut hidout: impl FnMut(HidOutput),
+    ) {
+        for i in 0..self.pads.len() {
+            let Some(pad) = self.pads[i].as_mut() else {
+                continue;
+            };
+            let fb = pad.service(i as u8);
+            if let Some(r) = fb.rumble {
+                if self.last_rumble[i] != r {
+                    self.last_rumble[i] = r;
+                    rumble(i as u16, r.0, r.1);
+                }
+            }
+            for h in fb.hidout {
+                hidout(h);
+            }
+        }
+    }
+}

crates/punktfunk-host/src/inject/windows/dualshock4_windows.rs

@@ -0,0 +1,290 @@
+//! Virtual Sony DualShock 4 on Windows via the UMDF minidriver — the PS4 sibling of
+//! [`super::dualsense_windows`]. Same transport (a per-session `SwDeviceCreate` devnode + the
+//! `Global\pfds-shm-<idx>` shared section the driver maps), same controller model ([`DsState`]); only
+//! the PnP identity (`VID_054C&PID_09CC`, hardware id `pf_dualshock4`) and the report codec
+//! ([`super::dualshock4_proto`]) differ. The host stamps `device_type = 1` (DualShock 4) into the
+//! section so the one UMDF driver serves the DS4 descriptor / attributes / features instead of the
+//! DualSense ones. Feedback is motor rumble (universal 0xCA plane) + the lightbar (0xCD `Led`); a DS4
+//! has no adaptive triggers / player LEDs.
+
+use super::dualsense_proto::DsState;
+use super::dualsense_windows::{
+    create_swdevice, SwDeviceProfile, DEVTYPE_DUALSHOCK4, OFF_DEVTYPE, OFF_INPUT, OFF_OUTPUT,
+    OFF_OUT_SEQ, SHM_MAGIC, SHM_SIZE,
+};
+use super::dualshock4_proto::{
+    parse_ds4_output, serialize_state, Ds4Feedback, DS4_INPUT_REPORT_LEN, DS4_TOUCH_H, DS4_TOUCH_W,
+};
+use crate::gamestream::gamepad::{GamepadEvent, MAX_PADS};
+use anyhow::Result;
+use punktfunk_core::quic::{HidOutput, RichInput};
+use std::time::{Duration, Instant};
+use windows::core::HSTRING;
+
+/// A single virtual DualShock 4: the `SwDeviceCreate`'d `pf_ds4_<index>` devnode plus the mapped
+/// shared section. Dropping it removes the devnode and unmaps + closes the section.
+struct Ds4WinPad {
+    /// Per-session devnode from SwDeviceCreate, when it succeeds (RAII — `SwDeviceClose` on drop).
+    _sw: Option<super::gamepad_raii::SwDevice>,
+    /// The named shared section the driver maps (RAII — unmapped + closed on drop).
+    shm: super::gamepad_raii::Shm,
+    counter: u8,
+    ts: u16,
+    last_out_seq: u32,
+}
+
+impl Ds4WinPad {
+    /// Create + map the section, stamp `device_type = DualShock 4` + a neutral report + the magic,
+    /// then spawn the `pf_ds4_<index>` devnode (the driver loads on it and maps the section).
+    fn open(index: u8) -> Result<Ds4WinPad> {
+        let shm = super::gamepad_raii::Shm::create(
+            &HSTRING::from(pf_driver_proto::gamepad::pad_shm_name(index)),
+            SHM_SIZE,
+        )?;
+        let base = shm.base();
+        // device-type FIRST (so it's visible the moment magic is), neutral report, magic LAST.
+        // SAFETY: base points at SHM_SIZE writable bytes; OFF_DEVTYPE/OFF_INPUT are in range.
+        unsafe {
+            *base.add(OFF_DEVTYPE) = DEVTYPE_DUALSHOCK4;
+            std::ptr::write_unaligned(base.add(OFF_INPUT) as *mut [u8; DS4_INPUT_REPORT_LEN], {
+                let mut r = [0u8; DS4_INPUT_REPORT_LEN];
+                serialize_state(&mut r, &DsState::neutral(), 0, 0);
+                r
+            });
+            std::ptr::write_unaligned(base as *mut u32, SHM_MAGIC);
+        }
+        let inst = format!("pf_ds4_{index}");
+        let hsw = match create_swdevice(&SwDeviceProfile {
+            instance: &inst,
+            container_index: index,
+            hwid: "pf_dualshock4",
+            usb_vid_pid: "VID_054C&PID_09CC",
+            description: "punktfunk Virtual DualShock 4",
+        }) {
+            Ok(h) => Some(h),
+            Err(e) => {
+                tracing::warn!(error = %format!("{e:#}"), "SwDeviceCreate failed; DualShock 4 devnode unavailable");
+                None
+            }
+        };
+        let _sw = hsw.map(super::gamepad_raii::SwDevice::new);
+        Ok(Ds4WinPad {
+            _sw,
+            shm,
+            counter: 0,
+            ts: 0,
+            last_out_seq: 0,
+        })
+    }
+
+    /// Serialize `st` into report `0x01` and publish it to the section's input slot.
+    fn write_state(&mut self, st: &DsState) {
+        self.counter = self.counter.wrapping_add(1);
+        self.ts = self.ts.wrapping_add(188); // ~1ms in the DS4's 5.33µs sensor-clock units
+        let mut r = [0u8; DS4_INPUT_REPORT_LEN];
+        serialize_state(&mut r, st, self.counter, self.ts);
+        // SAFETY: base points at SHM_SIZE bytes; input slot is OFF_INPUT..OFF_INPUT+64.
+        unsafe {
+            std::ptr::copy_nonoverlapping(r.as_ptr(), self.shm.base().add(OFF_INPUT), r.len())
+        };
+    }
+
+    /// Poll the section's output slot; parse a new `0x05` report (rumble / lightbar) into a
+    /// [`Ds4Feedback`]. Returns empty feedback if the driver hasn't published anything new.
+    fn service(&mut self) -> Ds4Feedback {
+        let mut fb = Ds4Feedback::default();
+        // SAFETY: base points at SHM_SIZE bytes.
+        let seq =
+            unsafe { std::ptr::read_unaligned(self.shm.base().add(OFF_OUT_SEQ) as *const u32) };
+        if seq != self.last_out_seq {
+            self.last_out_seq = seq;
+            let mut out = [0u8; 64];
+            // SAFETY: output slot is OFF_OUTPUT..OFF_OUTPUT+64 within the section.
+            unsafe {
+                std::ptr::copy_nonoverlapping(self.shm.base().add(OFF_OUTPUT), out.as_mut_ptr(), 64)
+            };
+            parse_ds4_output(&out, &mut fb);
+        }
+        fb
+    }
+}
+
+/// All virtual DualShock 4 pads of a session — the Windows analogue of
+/// [`DualShock4Manager`](super::dualshock4::DualShock4Manager), with the same method surface as the
+/// Windows DualSense manager so the session input thread drives either backend identically.
+pub struct DualShock4WindowsManager {
+    pads: Vec<Option<Ds4WinPad>>,
+    state: Vec<DsState>,
+    last_rumble: Vec<(u16, u16)>,
+    last_led: Vec<Option<(u8, u8, u8)>>,
+    last_write: Vec<Instant>,
+    broken: bool,
+}
+
+impl Default for DualShock4WindowsManager {
+    fn default() -> DualShock4WindowsManager {
+        DualShock4WindowsManager::new()
+    }
+}
+
+impl DualShock4WindowsManager {
+    pub fn new() -> DualShock4WindowsManager {
+        DualShock4WindowsManager {
+            pads: (0..MAX_PADS).map(|_| None).collect(),
+            state: vec![DsState::neutral(); MAX_PADS],
+            last_rumble: vec![(0, 0); MAX_PADS],
+            last_led: vec![None; MAX_PADS],
+            last_write: vec![Instant::now(); MAX_PADS],
+            broken: false,
+        }
+    }
+
+    /// Handle one decoded controller event (create/destroy by mask, then merge button/stick state).
+    pub fn handle(&mut self, ev: &GamepadEvent) {
+        match ev {
+            GamepadEvent::Arrival { index, kind, .. } => {
+                tracing::info!(index, kind, "controller arrival (DualShock 4/Windows)");
+                self.ensure(*index as usize);
+            }
+            GamepadEvent::State(f) => {
+                let idx = f.index as usize;
+                if idx >= MAX_PADS {
+                    return;
+                }
+                for (i, slot) in self.pads.iter_mut().enumerate() {
+                    if slot.is_some() && f.active_mask & (1 << i) == 0 {
+                        tracing::info!(index = i, "controller unplugged (DualShock 4/Windows)");
+                        *slot = None;
+                        self.state[i] = DsState::neutral();
+                        self.last_rumble[i] = (0, 0);
+                        self.last_led[i] = None;
+                    }
+                }
+                if f.active_mask & (1 << idx) == 0 {
+                    return;
+                }
+                self.ensure(idx);
+                let prev = self.state[idx];
+                let mut s = DsState::from_gamepad(
+                    f.buttons,
+                    f.ls_x,
+                    f.ls_y,
+                    f.rs_x,
+                    f.rs_y,
+                    f.left_trigger,
+                    f.right_trigger,
+                );
+                s.touch = prev.touch;
+                s.gyro = prev.gyro;
+                s.accel = prev.accel;
+                self.state[idx] = s;
+                self.write(idx);
+            }
+        }
+    }
+
+    /// Apply one rich client→host event (touchpad contact / motion sample) to an existing pad.
+    pub fn apply_rich(&mut self, rich: RichInput) {
+        let idx = match rich {
+            RichInput::Touchpad { pad, .. } | RichInput::Motion { pad, .. } => pad as usize,
+        };
+        if idx >= MAX_PADS || self.pads[idx].is_none() {
+            return;
+        }
+        match rich {
+            RichInput::Touchpad {
+                finger,
+                active,
+                x,
+                y,
+                ..
+            } => {
+                let slot = (finger as usize).min(1);
+                let t = &mut self.state[idx].touch[slot];
+                t.active = active;
+                t.id = slot as u8;
+                t.x = ((x as u32 * (DS4_TOUCH_W - 1) as u32) / u16::MAX as u32) as u16;
+                t.y = ((y as u32 * (DS4_TOUCH_H - 1) as u32) / u16::MAX as u32) as u16;
+            }
+            RichInput::Motion { gyro, accel, .. } => {
+                self.state[idx].gyro = gyro;
+                self.state[idx].accel = accel;
+            }
+        }
+        self.write(idx);
+    }
+
+    fn write(&mut self, idx: usize) {
+        let st = self.state[idx];
+        if let Some(pad) = self.pads[idx].as_mut() {
+            pad.write_state(&st);
+        }
+        self.last_write[idx] = Instant::now();
+    }
+
+    /// Re-emit each live pad's current report if it's been silent for `max_gap` (parity with the
+    /// other backends' heartbeat — keeps the section fresh).
+    pub fn heartbeat(&mut self, max_gap: Duration) {
+        let now = Instant::now();
+        for i in 0..self.pads.len() {
+            if self.pads[i].is_some() && now.duration_since(self.last_write[i]) >= max_gap {
+                self.write(i);
+            }
+        }
+    }
+
+    fn ensure(&mut self, idx: usize) {
+        if idx >= MAX_PADS || self.pads[idx].is_some() || self.broken {
+            return;
+        }
+        match Ds4WinPad::open(idx as u8) {
+            Ok(p) => {
+                tracing::info!(
+                    index = idx,
+                    "virtual DualShock 4 created (Windows UMDF shm channel)"
+                );
+                self.pads[idx] = Some(p);
+                self.state[idx] = DsState::neutral();
+                self.last_rumble[idx] = (0, 0);
+                self.last_led[idx] = None;
+                self.last_write[idx] = Instant::now();
+            }
+            Err(e) => {
+                tracing::error!(error = %format!("{e:#}"), "virtual DualShock 4 creation failed — controller input disabled");
+                self.broken = true;
+            }
+        }
+    }
+
+    /// Service every pad: poll the section for a game's feedback. `rumble` fires `(index, low, high)`
+    /// only on change (universal 0xCA plane); `hidout` fires the lightbar (0xCD `Led`), deduped.
+    pub fn pump(
+        &mut self,
+        mut rumble: impl FnMut(u16, u16, u16),
+        mut hidout: impl FnMut(HidOutput),
+    ) {
+        for i in 0..self.pads.len() {
+            let Some(pad) = self.pads[i].as_mut() else {
+                continue;
+            };
+            let fb = pad.service();
+            if let Some(r) = fb.rumble {
+                if self.last_rumble[i] != r {
+                    self.last_rumble[i] = r;
+                    rumble(i as u16, r.0, r.1);
+                }
+            }
+            if let Some(rgb) = fb.led {
+                if self.last_led[i] != Some(rgb) {
+                    self.last_led[i] = Some(rgb);
+                    hidout(HidOutput::Led {
+                        pad: i as u8,
+                        r: rgb.0,
+                        g: rgb.1,
+                        b: rgb.2,
+                    });
+                }
+            }
+        }
+    }
+}

crates/punktfunk-host/src/inject/windows/gamepad_raii.rs

@@ -0,0 +1,115 @@
+//! Per-pad Windows resource RAII for the gamepad backends (DualSense / DualShock 4 / XUSB).
+//!
+//! Each virtual pad owns two OS resources: the named shared-memory section (+ its mapped view) the
+//! `pf_dualsense`/`pf_xusb` driver reads, and the `SwDeviceCreate`'d software devnode the driver loads
+//! on. Before this module, all three backends hand-rolled the same `CreateFileMappingW` +
+//! `MapViewOfFile` and an identical `Drop` doing `SwDeviceClose` + `UnmapViewOfFile` + `CloseHandle` —
+//! easy to drift or leak on an error path. [`Shm`] and [`SwDevice`] own those resources with RAII, so a
+//! backend just holds them and the cleanup (and ordering) happens by construction.
+
+use anyhow::{anyhow, Result};
+use std::os::windows::io::{FromRawHandle, OwnedHandle};
+use windows::core::{w, HSTRING, PCWSTR};
+use windows::Win32::Devices::Enumeration::Pnp::{SwDeviceClose, HSWDEVICE};
+use windows::Win32::Foundation::INVALID_HANDLE_VALUE;
+use windows::Win32::Security::Authorization::{
+    ConvertStringSecurityDescriptorToSecurityDescriptorW, SDDL_REVISION_1,
+};
+use windows::Win32::Security::{PSECURITY_DESCRIPTOR, SECURITY_ATTRIBUTES};
+use windows::Win32::System::Memory::{
+    CreateFileMappingW, MapViewOfFile, UnmapViewOfFile, FILE_MAP_ALL_ACCESS,
+    MEMORY_MAPPED_VIEW_ADDRESS, PAGE_READWRITE,
+};
+
+/// A named, anonymous (pagefile-backed) shared section + its mapped read/write view, created with the
+/// permissive `D:(A;;GA;;;WD)` SDDL the restricted-token driver needs to open it. RAII: drop unmaps the
+/// view, then the [`OwnedHandle`] closes the section handle (in that order). Replaces the three backends'
+/// hand-duplicated `CreateFileMappingW` + `MapViewOfFile` + manual `Drop`.
+pub(super) struct Shm {
+    /// Owns the section handle (closed on drop). Held only for ownership — never read after construction.
+    _handle: OwnedHandle,
+    view: MEMORY_MAPPED_VIEW_ADDRESS,
+}
+
+impl Shm {
+    /// Create + zero a `size`-byte section named `name`, mapped read/write. The section handle is owned
+    /// immediately, so any failure below (or the returned `Shm`'s drop) closes it.
+    pub(super) fn create(name: &HSTRING, size: usize) -> Result<Shm> {
+        let mut psd = PSECURITY_DESCRIPTOR::default();
+        // SAFETY: the SDDL literal is valid; `psd` receives an OS-allocated descriptor (freed at process
+        // exit — acceptable for a host-lifetime object).
+        unsafe {
+            ConvertStringSecurityDescriptorToSecurityDescriptorW(
+                w!("D:(A;;GA;;;WD)"),
+                SDDL_REVISION_1,
+                &mut psd,
+                None,
+            )?;
+        }
+        let sa = SECURITY_ATTRIBUTES {
+            nLength: core::mem::size_of::<SECURITY_ATTRIBUTES>() as u32,
+            lpSecurityDescriptor: psd.0,
+            bInheritHandle: false.into(),
+        };
+        // SAFETY: an anonymous (pagefile-backed) section of `size` bytes with the SDDL above.
+        let map = unsafe {
+            CreateFileMappingW(
+                INVALID_HANDLE_VALUE,
+                Some(&sa),
+                PAGE_READWRITE,
+                0,
+                size as u32,
+                PCWSTR(name.as_ptr()),
+            )?
+        };
+        // SAFETY: `map` is a fresh section handle we own; take ownership immediately so that the early
+        // return below (and the eventual drop) closes it. `map` (a `Copy` `HANDLE`) stays usable for the
+        // `MapViewOfFile` borrow that follows — `from_raw_handle` only copies the inner pointer.
+        let handle = unsafe { OwnedHandle::from_raw_handle(map.0) };
+        // SAFETY: `map` is a valid section handle; map the whole thing read/write.
+        let view = unsafe { MapViewOfFile(map, FILE_MAP_ALL_ACCESS, 0, 0, size) };
+        if view.Value.is_null() {
+            // `handle` drops here → closes the section. No view to unmap.
+            return Err(anyhow!("MapViewOfFile failed for {name}"));
+        }
+        // SAFETY: `view` points at `size` writable bytes (just mapped).
+        unsafe { core::ptr::write_bytes(view.Value as *mut u8, 0, size) };
+        Ok(Shm {
+            _handle: handle,
+            view,
+        })
+    }
+
+    /// The mapped section's base pointer. Stable for the `Shm`'s lifetime (moving the `Shm` does not
+    /// relocate the OS mapping — the view address is fixed by `MapViewOfFile`).
+    pub(super) fn base(&self) -> *mut u8 {
+        self.view.Value as *mut u8
+    }
+}
+
+impl Drop for Shm {
+    fn drop(&mut self) {
+        // SAFETY: `view` came from `MapViewOfFile`; unmap it BEFORE the `_handle` field closes the
+        // section (struct fields drop only after this `Drop::drop` returns).
+        unsafe {
+            let _ = UnmapViewOfFile(self.view);
+        }
+    }
+}
+
+/// A `SwDeviceCreate`'d software devnode; drop removes it via `SwDeviceClose`. Replaces the manual
+/// `SwDeviceClose` each backend used to call in its `Drop`.
+pub(super) struct SwDevice(HSWDEVICE);
+
+impl SwDevice {
+    pub(super) fn new(hsw: HSWDEVICE) -> Self {
+        SwDevice(hsw)
+    }
+}
+
+impl Drop for SwDevice {
+    fn drop(&mut self) {
+        // SAFETY: `self.0` is the handle `SwDeviceCreate` returned; `SwDeviceClose` removes the devnode.
+        unsafe { SwDeviceClose(self.0) };
+    }
+}

crates/punktfunk-host/src/inject/windows/gamepad_windows.rs

@@ -0,0 +1,315 @@
+//! Windows virtual Xbox 360 gamepad via the punktfunk **XUSB companion** UMDF driver
+//! (`packaging/windows/xusb-driver`) — the in-tree replacement for ViGEmBus. One virtual Xbox 360
+//! controller per client pad index, visible to classic **XInput** (`XInputGetState`) with no kernel
+//! bus driver: each pad `SwDeviceCreate`s a `pf_xusb_<index>` devnode (the driver loads on it and
+//! registers `GUID_DEVINTERFACE_XUSB`) and the host pushes the XInput state into the shared section
+//! `Global\pfxusb-shm-<index>`. GameStream/Moonlight already speak the XInput conventions (low-16
+//! button bits, sticks −32768..32767 +Y up, triggers 0..255), so the state copy is ~1:1.
+//!
+//! Rumble flows back the other way: a game writes force-feedback via `XInputSetState`, the driver
+//! parses the `SET_STATE` packet into the shared section, and [`GamepadManager::pump_rumble`] relays
+//! level changes to the client (the universal 0xCA plane), mirroring the Linux `EV_FF` read path.
+//!
+//! NB: the driver currently maps `Global\pfxusb-shm-0` (hardcoded), so a single pad (index 0) is
+//! fully correct; mixed multi-pad needs the driver to read its own index first (same limitation as
+//! the DualSense backend).
+
+use crate::gamestream::gamepad::{GamepadEvent, MAX_PADS};
+use anyhow::{anyhow, Result};
+use std::ffi::c_void;
+use windows::core::{w, GUID, HRESULT, HSTRING, PCWSTR};
+use windows::Win32::Devices::Enumeration::Pnp::{
+    SwDeviceClose, SwDeviceCreate, HSWDEVICE, SW_DEVICE_CREATE_INFO,
+};
+use windows::Win32::Foundation::{CloseHandle, HANDLE};
+use windows::Win32::System::Threading::{CreateEventW, SetEvent, WaitForSingleObject};
+
+// Shared-section layout — the single source of truth is `pf_driver_proto::gamepad::XusbShm` (offset
+// asserts pin every field; the `pf_xusb` driver maps the same struct). Derive the size/offsets/magic from
+// it so a layout change is a compile error, not a hand-synced literal (audit §6.1).
+use pf_driver_proto::gamepad::XusbShm;
+const SHM_SIZE: usize = core::mem::size_of::<XusbShm>();
+const SHM_MAGIC: u32 = pf_driver_proto::gamepad::XUSB_MAGIC; // "PFXU"
+const OFF_PACKET: usize = core::mem::offset_of!(XusbShm, packet);
+const OFF_BUTTONS: usize = core::mem::offset_of!(XusbShm, buttons);
+const OFF_LT: usize = core::mem::offset_of!(XusbShm, left_trigger);
+const OFF_RT: usize = core::mem::offset_of!(XusbShm, right_trigger);
+const OFF_LX: usize = core::mem::offset_of!(XusbShm, thumb_lx);
+const OFF_LY: usize = core::mem::offset_of!(XusbShm, thumb_ly);
+const OFF_RX: usize = core::mem::offset_of!(XusbShm, thumb_rx);
+const OFF_RY: usize = core::mem::offset_of!(XusbShm, thumb_ry);
+const OFF_RUMBLE_SEQ: usize = core::mem::offset_of!(XusbShm, rumble_seq);
+const OFF_RUMBLE: usize = core::mem::offset_of!(XusbShm, rumble_large); // large @28, small @29
+
+/// Context for the `SwDeviceCreate` completion callback: an event to signal + the HRESULT it reports.
+#[repr(C)]
+struct SwCreateCtx {
+    event: HANDLE,
+    result: HRESULT,
+}
+
+/// `SwDeviceCreate` fires this once PnP has enumerated the device; stash the result + wake the creator.
+unsafe extern "system" fn sw_create_cb(
+    _dev: HSWDEVICE,
+    result: HRESULT,
+    ctx: *const c_void,
+    _id: PCWSTR,
+) {
+    if !ctx.is_null() {
+        // SAFETY: ctx is the &mut SwCreateCtx the creator passed; it outlives this callback.
+        unsafe {
+            let c = ctx as *mut SwCreateCtx;
+            (*c).result = result;
+            let _ = SetEvent((*c).event);
+        }
+    }
+}
+
+/// Spawn the `pf_xusb_<index>` companion devnode (hardware id `pf_xusb`, enumerator `punktfunk`). The
+/// INF (System class) binds our UMDF driver, which registers the XUSB interface. Unlike the HID pads,
+/// no USB compatible-ids are needed — XInput finds the device by the interface GUID, not VID/PID — but
+/// we still pass a deterministic non-null `pContainerId` (the null-sentinel trips an `xinput1_4`
+/// slot-skip bug). `SwDeviceClose` removes it on drop.
+fn create_swdevice(index: u8) -> Result<HSWDEVICE> {
+    let hwids: Vec<u16> = "pf_xusb".encode_utf16().chain([0u16, 0u16]).collect();
+    let instid: Vec<u16> = format!("pf_xusb_{index}")
+        .encode_utf16()
+        .chain(std::iter::once(0))
+        .collect();
+    let desc: Vec<u16> = "punktfunk Virtual Xbox 360 (XUSB)"
+        .encode_utf16()
+        .chain(std::iter::once(0))
+        .collect();
+    // The pad index, stamped into the device Location — the driver reads it to map `pfxusb-shm-<index>`
+    // (multi-pad). The buffer must outlive the SwDeviceCreate call (it does; we wait on the event).
+    let loc: Vec<u16> = format!("{index}")
+        .encode_utf16()
+        .chain(std::iter::once(0))
+        .collect();
+    let container = GUID::from_values(0x5046_5855, 0x0000, 0x0000, [0, 0, 0, 0, 0, 0, 0, index]);
+
+    // SAFETY: zeroed then the fields we use are set; the buffers + container outlive the call.
+    let mut info: SW_DEVICE_CREATE_INFO = unsafe { std::mem::zeroed() };
+    info.cbSize = std::mem::size_of::<SW_DEVICE_CREATE_INFO>() as u32;
+    info.pszInstanceId = PCWSTR(instid.as_ptr());
+    info.pszzHardwareIds = PCWSTR(hwids.as_ptr());
+    info.pContainerId = &container;
+    info.pszDeviceDescription = PCWSTR(desc.as_ptr());
+    info.pszDeviceLocation = PCWSTR(loc.as_ptr());
+    info.CapabilityFlags = 0x0000_000B; // DriverRequired | SilentInstall | Removable
+
+    // SAFETY: a manual-reset, initially-unsignaled, unnamed event.
+    let event = unsafe { CreateEventW(None, true, false, PCWSTR::null())? };
+    let mut ctx = SwCreateCtx {
+        event,
+        result: HRESULT(0),
+    };
+    // SAFETY: info + buffers + ctx outlive the call (we wait on the event before returning).
+    let hsw = match unsafe {
+        SwDeviceCreate(
+            w!("punktfunk"),
+            w!("HTREE\\ROOT\\0"),
+            &info,
+            None,
+            Some(sw_create_cb),
+            Some(&mut ctx as *mut SwCreateCtx as *const c_void),
+        )
+    } {
+        Ok(h) => h,
+        Err(e) => {
+            // SAFETY: event is valid.
+            unsafe {
+                let _ = CloseHandle(event);
+            }
+            return Err(anyhow!("SwDeviceCreate(pf_xusb) failed: {e}"));
+        }
+    };
+    // SAFETY: event valid; block until PnP finishes enumerating, then check the callback result.
+    unsafe {
+        WaitForSingleObject(event, 10_000);
+        let _ = CloseHandle(event);
+    }
+    if ctx.result.is_err() {
+        // SAFETY: hsw is the handle SwDeviceCreate returned.
+        unsafe { SwDeviceClose(hsw) };
+        return Err(anyhow!(
+            "SwDeviceCreate(pf_xusb) enumeration failed: {:?}",
+            ctx.result
+        ));
+    }
+    Ok(hsw)
+}
+
+/// A single virtual Xbox 360 pad: the `pf_xusb_<index>` devnode plus the mapped shared section.
+struct XusbWinPad {
+    /// Owns the `pf_xusb_<index>` devnode (dropped → `SwDeviceClose`). `None` if `SwDeviceCreate` failed.
+    _sw: Option<super::gamepad_raii::SwDevice>,
+    /// Owns `Global\pfxusb-shm-<index>` (the section + its mapped view; drop unmaps + closes).
+    shm: super::gamepad_raii::Shm,
+    packet: u32,
+    last_rumble_seq: u32,
+}
+
+impl XusbWinPad {
+    /// Create + map `Global\pfxusb-shm-<index>`, stamp the magic, then spawn the devnode.
+    fn open(index: u8) -> Result<XusbWinPad> {
+        // Permissive-DACL named section the WUDFHost (whatever account) can open; `Shm` owns the
+        // section handle + its mapped view (zero-filled) and unmaps/closes on drop.
+        let shm = super::gamepad_raii::Shm::create(
+            &HSTRING::from(pf_driver_proto::gamepad::xusb_shm_name(index)),
+            SHM_SIZE,
+        )?;
+        let base = shm.base();
+        // Zero the section then stamp the magic LAST (the driver only accepts it once magic is set).
+        // SAFETY: base points at SHM_SIZE writable bytes.
+        unsafe {
+            std::ptr::write_bytes(base, 0, SHM_SIZE);
+            std::ptr::write_unaligned(base as *mut u32, SHM_MAGIC);
+        }
+        let hsw = match create_swdevice(index) {
+            Ok(h) => Some(h),
+            Err(e) => {
+                tracing::warn!(error = %format!("{e:#}"), "SwDeviceCreate failed; XUSB devnode unavailable");
+                None
+            }
+        };
+        let _sw = hsw.map(super::gamepad_raii::SwDevice::new);
+        Ok(XusbWinPad {
+            _sw,
+            shm,
+            packet: 0,
+            last_rumble_seq: 0,
+        })
+    }
+
+    /// Publish the XInput state to the section and bump the packet number (XInput uses it to detect
+    /// change). `buttons` is the XINPUT_GAMEPAD_* bitmap; sticks are i16, triggers u8.
+    #[allow(clippy::too_many_arguments)]
+    fn write_state(&mut self, buttons: u16, lt: u8, rt: u8, lx: i16, ly: i16, rx: i16, ry: i16) {
+        self.packet = self.packet.wrapping_add(1);
+        let base = self.shm.base();
+        // SAFETY: `base` is the start of the mapped section (`SHM_SIZE` bytes, owned by `Shm`); every
+        // `OFF_*` is a fixed in-range offset into it and `write_unaligned` handles the unaligned field
+        // writes. Single owner (`&mut self`), so no concurrent writer races these stores.
+        unsafe {
+            std::ptr::write_unaligned(base.add(OFF_BUTTONS) as *mut u16, buttons);
+            *base.add(OFF_LT) = lt;
+            *base.add(OFF_RT) = rt;
+            std::ptr::write_unaligned(base.add(OFF_LX) as *mut i16, lx);
+            std::ptr::write_unaligned(base.add(OFF_LY) as *mut i16, ly);
+            std::ptr::write_unaligned(base.add(OFF_RX) as *mut i16, rx);
+            std::ptr::write_unaligned(base.add(OFF_RY) as *mut i16, ry);
+            std::ptr::write_unaligned(base.add(OFF_PACKET) as *mut u32, self.packet);
+        }
+    }
+
+    /// Poll the section for a game's rumble (the driver bumps `rumble_seq` on each SET_STATE). Returns
+    /// `(large, small)` motor levels (0..=255) when a new one arrived.
+    fn service(&mut self) -> Option<(u8, u8)> {
+        let base = self.shm.base();
+        // SAFETY: base points at SHM_SIZE bytes.
+        let seq = unsafe { std::ptr::read_unaligned(base.add(OFF_RUMBLE_SEQ) as *const u32) };
+        if seq == self.last_rumble_seq {
+            return None;
+        }
+        self.last_rumble_seq = seq;
+        // SAFETY: rumble bytes at OFF_RUMBLE / OFF_RUMBLE+1.
+        let (large, small) = unsafe { (*base.add(OFF_RUMBLE), *base.add(OFF_RUMBLE + 1)) };
+        Some((large, small))
+    }
+}
+
+/// All virtual Xbox 360 pads of a session — the Windows analogue of the Linux uinput-xpad manager,
+/// now backed by the XUSB companion driver. Same method surface (`new`/`handle`/`pump_rumble`) the
+/// session input thread already drives.
+pub struct GamepadManager {
+    pads: Vec<Option<XusbWinPad>>,
+    last_rumble: Vec<(u8, u8)>,
+    broken: bool,
+}
+
+impl Default for GamepadManager {
+    fn default() -> GamepadManager {
+        GamepadManager::new()
+    }
+}
+
+impl GamepadManager {
+    pub fn new() -> GamepadManager {
+        GamepadManager {
+            pads: (0..MAX_PADS).map(|_| None).collect(),
+            last_rumble: vec![(0, 0); MAX_PADS],
+            broken: false,
+        }
+    }
+
+    fn ensure(&mut self, idx: usize) {
+        if idx >= MAX_PADS || self.pads[idx].is_some() || self.broken {
+            return;
+        }
+        match XusbWinPad::open(idx as u8) {
+            Ok(p) => {
+                tracing::info!(
+                    index = idx,
+                    "virtual Xbox 360 created (Windows XUSB companion)"
+                );
+                self.pads[idx] = Some(p);
+                self.last_rumble[idx] = (0, 0);
+            }
+            Err(e) => {
+                tracing::error!(error = %format!("{e:#}"), "virtual Xbox 360 creation failed — controller input disabled (is the pf_xusb driver installed?)");
+                self.broken = true;
+            }
+        }
+    }
+
+    pub fn handle(&mut self, ev: &GamepadEvent) {
+        let GamepadEvent::State(f) = ev else {
+            return; // Arrival metadata — the pad is created lazily on the first State
+        };
+        let idx = f.index.max(0) as usize;
+        if idx >= MAX_PADS {
+            return;
+        }
+        // Unplugs: drop any allocated pad whose mask bit cleared.
+        for (i, slot) in self.pads.iter_mut().enumerate() {
+            if slot.is_some() && f.active_mask & (1 << i) == 0 {
+                tracing::info!(index = i, "controller unplugged (Xbox 360/Windows)");
+                *slot = None;
+                self.last_rumble[i] = (0, 0);
+            }
+        }
+        if f.active_mask & (1 << idx) == 0 {
+            return;
+        }
+        self.ensure(idx);
+        if let Some(pad) = self.pads[idx].as_mut() {
+            pad.write_state(
+                (f.buttons & 0xffff) as u16,
+                f.left_trigger,
+                f.right_trigger,
+                f.ls_x,
+                f.ls_y,
+                f.rs_x,
+                f.rs_y,
+            );
+        }
+    }
+
+    /// Relay any changed rumble level to the client. XUSB motors are 0..255; the wire carries
+    /// 0..65535, so scale by 257. `large` (low-frequency) → the datagram's `low`, `small`
+    /// (high-frequency) → `high` — matching the other backends.
+    pub fn pump_rumble(&mut self, mut send: impl FnMut(u16, u16, u16)) {
+        for i in 0..self.pads.len() {
+            let Some(pad) = self.pads[i].as_mut() else {
+                continue;
+            };
+            if let Some((large, small)) = pad.service() {
+                if self.last_rumble[i] != (large, small) {
+                    self.last_rumble[i] = (large, small);
+                    send(i as u16, large as u16 * 257, small as u16 * 257);
+                }
+            }
+        }
+    }
+}

crates/punktfunk-host/src/inject/windows/sendinput.rs

@@ -5,6 +5,9 @@
 //! thread stays bound to its desktop and only reattaches (`OpenInputDesktop`/`SetThreadDesktop`) when
 //! `SendInput` reports a short write (the input desktop switched) — no per-event reattach overhead.
 
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it.
+#![deny(clippy::undocumented_unsafe_blocks)]
+
 use anyhow::Result;
 use punktfunk_core::input::{InputEvent, InputKind};
 use std::mem::size_of;
@@ -35,7 +38,12 @@ pub struct SendInputInjector {
     desktop: Option<HDESK>,
 }
 
-// Only ever used from the host's single injector thread (like SudoVdaDisplay).
+// SAFETY: `SendInputInjector` holds only an `Option<HDESK>` (a desktop handle). The host creates
+// and drives it from a single dedicated injector thread; the handle is opened, rebound, and closed
+// on whichever thread owns the value, and the type is not `Sync`, so there is never concurrent
+// access. A desktop `HDESK` is not thread-affine for ownership (`CloseDesktop` works from any
+// thread; `SetThreadDesktop` rebinds the current thread), so transferring ownership via `Send` is
+// sound.
 unsafe impl Send for SendInputInjector {}
 
 impl SendInputInjector {
@@ -49,6 +57,12 @@ impl SendInputInjector {
     /// Bind this thread to the desktop currently receiving input. UAC / lock screen / Ctrl-Alt-Del
     /// swap the input desktop; `SendInput` silently no-ops unless our thread is on it.
     fn reattach_input_desktop(&mut self) {
+        // SAFETY: `OpenInputDesktop`/`SetThreadDesktop`/`CloseDesktop` are FFI calls passed only
+        // by-value args (constant desktop flags, a `bool`, an access mask). `OpenInputDesktop`
+        // yields an owned `HDESK` only on `Ok`; we then either install it with `SetThreadDesktop`
+        // (closing the previously-owned handle exactly once) or close the fresh handle on failure —
+        // so every handle is closed exactly once and none is used after close. `SetThreadDesktop`
+        // only rebinds this calling thread, which is where the injector runs.
         unsafe {
             match OpenInputDesktop(
                 DESKTOP_CONTROL_FLAGS(0),
@@ -75,12 +89,17 @@ impl SendInputInjector {
     /// switched out from under us, e.g. into UAC/lock) do we reattach to the now-current input desktop
     /// and retry once. This serves both the normal and secure desktops with no steady-state overhead.
     fn send(&mut self, inputs: &[INPUT]) -> Result<()> {
+        // SAFETY: `inputs` is a live `&[INPUT]` slice that outlives this synchronous `SendInput`
+        // call; `size_of::<INPUT>()` is the exact per-element stride Win32 requires as `cbSize`. The
+        // call only reads the array (one event per element) and returns the count injected.
         let n = unsafe { SendInput(inputs, size_of::<INPUT>() as i32) };
         if n as usize == inputs.len() {
             return Ok(());
         }
         // Short write → the input desktop likely changed. Reattach + retry once.
         self.reattach_input_desktop();
+        // SAFETY: same as the first `SendInput` — `inputs` is the identical live slice outliving the
+        // call and `cbSize == size_of::<INPUT>()`; only re-issued after reattaching the input desktop.
         let n = unsafe { SendInput(inputs, size_of::<INPUT>() as i32) };
         if n as usize != inputs.len() {
             anyhow::bail!(
@@ -95,6 +114,9 @@ impl SendInputInjector {
 impl Drop for SendInputInjector {
     fn drop(&mut self) {
         if let Some(h) = self.desktop.take() {
+            // SAFETY: `h` is the `HDESK` this injector owned (moved out of `self.desktop`);
+            // `CloseDesktop` runs once here in `Drop` on that still-valid handle, with no later use —
+            // no double close.
             unsafe {
                 let _ = CloseDesktop(h);
             }
@@ -216,7 +238,11 @@ impl InputInjector for SendInputInjector {
             }
             InputKind::KeyDown | InputKind::KeyUp => {
                 let down = event.kind == InputKind::KeyDown;
-                let vk = (event.code & 0xff) as u16; // client sends Windows VK
+                // client sends Windows VK
+                let vk = (event.code & 0xff) as u16;
+                // SAFETY: `MapVirtualKeyExW` is a pure value translation (VK → scancode); all three
+                // args are by-value (`u32`, the `MAPVK_VK_TO_VSC_EX` map-type constant, a `None`
+                // HKL). It dereferences no pointer and returns a `u32` — FFI-`unsafe` only.
                 let sc_ex = unsafe { MapVirtualKeyExW(vk as u32, MAPVK_VK_TO_VSC_EX, None) };
                 if sc_ex == 0 {
                     return Ok(()); // unmappable -> drop
@@ -264,6 +290,8 @@ fn key(ki: KEYBDINPUT) -> INPUT {
 }
 
 fn virtual_desktop_rect() -> (i32, i32, i32, i32) {
+    // SAFETY: each `GetSystemMetrics` takes a single by-value `SYSTEM_METRICS_INDEX` constant and
+    // returns an `i32`; it dereferences no pointer and has no side effects — FFI-`unsafe` only.
     unsafe {
         (
             GetSystemMetrics(SM_XVIRTUALSCREEN),

crates/punktfunk-host/src/linux/dmabuf_fence.rs

@@ -13,6 +13,9 @@
 //! attaches none, the export yields an already-signaled sync_file (poll returns immediately) — no
 //! wait, no harm, and `waited=false` tells us the driver doesn't fence (so zero-copy would still race).
 
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
+#![deny(clippy::undocumented_unsafe_blocks)]
+
 use std::os::fd::RawFd;
 
 // linux/dma-buf.h ioctls on the DMA_BUF_BASE ('b' = 0x62) magic. _IOWR = dir(3)<<30 | size<<16 | base<<8 | nr.
@@ -40,6 +43,11 @@ pub fn wait_read_ready(dmabuf_fd: RawFd, timeout_ms: i32) -> std::io::Result<boo
         flags: DMA_BUF_SYNC_READ,
         fd: -1,
     };
+    // SAFETY: `dmabuf_fd` is a live dmabuf fd supplied by the caller (borrowed for this call; we
+    // never close it). `DMA_BUF_IOCTL_EXPORT_SYNC_FILE` encodes `size_of::<DmaBufExportSyncFile>()`
+    // — the exact byte count the kernel copies — and `&mut req` is a live, correctly-sized
+    // `#[repr(C)]` struct the EXPORT_SYNC_FILE ioctl reads (`flags`) and writes (`fd`). `req`
+    // outlives this synchronous call and is not aliased elsewhere.
     let r = unsafe { libc::ioctl(dmabuf_fd, DMA_BUF_IOCTL_EXPORT_SYNC_FILE, &mut req) };
     if r < 0 {
         return Err(std::io::Error::last_os_error());
@@ -54,11 +62,21 @@ pub fn wait_read_ready(dmabuf_fd: RawFd, timeout_ms: i32) -> std::io::Result<boo
         revents: 0,
     };
     // Non-blocking probe: not-yet-signaled (poll==0) means the producer is still rendering.
+    // SAFETY: `&mut pfd` points at a single live `libc::pollfd` and `nfds == 1` matches that one
+    // element; `pfd.fd` is `sync_fd`, the sync_file fd just exported (already checked `>= 0`).
+    // `poll` reads `fd`/`events` and writes `revents` for this non-blocking (timeout 0) probe, then
+    // returns — `pfd` outlives the call and aliases nothing.
     let pending = unsafe { libc::poll(&mut pfd, 1, 0) } == 0;
     if pending {
         pfd.revents = 0;
+        // SAFETY: same live single-element `pfd` (its `revents` reset to 0 just above), `nfds == 1`,
+        // and `sync_fd` still open. This blocking `poll` (up to `timeout_ms`) waits for the render
+        // fence to signal; it reads `fd`/`events`, writes `revents`, and returns before `pfd` ends.
         unsafe { libc::poll(&mut pfd, 1, timeout_ms) }; // block until the render fence signals
     }
+    // SAFETY: `sync_fd` is the sync_file fd the EXPORT_SYNC_FILE ioctl created and handed us to own;
+    // this point is reached only when `sync_fd >= 0`, this `close` runs exactly once on it, and it is
+    // never used afterward — no double-close or use-after-close.
     unsafe { libc::close(sync_fd) };
     Ok(pending)
 }

crates/punktfunk-host/src/linux/drm_sync.rs

@@ -8,6 +8,8 @@
 //! verified (ioctl numbers + a live signal→wait round trip), ready to wire in the moment a producer
 //! gains working `SPA_META_SyncTimeline`.
 #![allow(dead_code)]
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
+#![deny(clippy::undocumented_unsafe_blocks)]
 //!
 //! Compositors that render directly into the PipeWire buffer pool (Mutter's virtual
 //! monitors) hand buffers over at GPU-submit time; on drivers without implicit dmabuf
@@ -81,6 +83,8 @@ pub struct DrmSync {
 impl DrmSync {
     pub fn open() -> Result<DrmSync> {
         let path = c"/dev/dri/renderD128";
+        // SAFETY: `path` is a 'static NUL-terminated C string literal; `open` only reads it as a
+        // filesystem path and returns an fd (or -1). No Rust memory is aliased or handed to the kernel.
         let fd = unsafe { libc::open(path.as_ptr(), libc::O_RDWR | libc::O_CLOEXEC) };
         if fd < 0 {
             bail!("open /dev/dri/renderD128 for syncobj ops: {}", errno());
@@ -94,6 +98,9 @@ impl DrmSync {
             fd: syncobj_fd,
             ..Default::default()
         };
+        // SAFETY: `self.fd` is the live render-node fd from `open`; the request number encodes
+        // `size_of::<DrmSyncobjHandle>()` (the bytes the kernel copies), and `&mut req` is a live,
+        // correctly-sized `#[repr(C)]` struct the FD_TO_HANDLE ioctl reads (`fd`) and writes (`handle`).
         let r = unsafe { libc::ioctl(self.fd, DRM_IOCTL_SYNCOBJ_FD_TO_HANDLE, &mut req) };
         if r < 0 {
             bail!("SYNCOBJ_FD_TO_HANDLE: {}", errno());
@@ -106,6 +113,8 @@ impl DrmSync {
             handle,
             ..Default::default()
         };
+        // SAFETY: `self.fd` is the live render-node fd; `DRM_IOCTL_SYNCOBJ_DESTROY` encodes
+        // `size_of::<DrmSyncobjDestroy>()`, and `&mut req` is a live correctly-sized struct the kernel reads.
         unsafe { libc::ioctl(self.fd, DRM_IOCTL_SYNCOBJ_DESTROY, &mut req) };
     }
 
@@ -117,6 +126,8 @@ impl DrmSync {
             tv_sec: 0,
             tv_nsec: 0,
         };
+        // SAFETY: `CLOCK_MONOTONIC` is a valid clock id and `&mut now` is a live `libc::timespec` the
+        // kernel fills in; the call returns before `now` is read, so there is no aliasing/lifetime issue.
         unsafe { libc::clock_gettime(libc::CLOCK_MONOTONIC, &mut now) };
         let deadline = now.tv_sec * 1_000_000_000 + now.tv_nsec + timeout_ms as i64 * 1_000_000;
         let handles = [handle];
@@ -129,6 +140,11 @@ impl DrmSync {
             flags: DRM_SYNCOBJ_WAIT_FLAGS_WAIT_FOR_SUBMIT,
             ..Default::default()
         };
+        // SAFETY: `self.fd` is the live render-node fd; the request number encodes
+        // `size_of::<DrmSyncobjTimelineWait>()`; `&mut req` is a live correctly-sized struct. Its
+        // `handles`/`points` u64 fields hold the addresses of the local `handles`/`points` arrays, which
+        // outlive this synchronous call, and `count_handles == 1` matches their length — so every kernel
+        // read through those addresses stays in bounds.
         let r = unsafe { libc::ioctl(self.fd, DRM_IOCTL_SYNCOBJ_TIMELINE_WAIT, &mut req) };
         let saved = errno();
         self.destroy(handle);
@@ -151,6 +167,10 @@ impl DrmSync {
             count_handles: 1,
             flags: 0,
         };
+        // SAFETY: `self.fd` is the live render-node fd; the request number encodes
+        // `size_of::<DrmSyncobjTimelineArray>()`; `&mut req` is a live correctly-sized struct whose
+        // `handles`/`points` u64 fields address the local `handles`/`points` arrays (alive for this
+        // synchronous call, `count_handles == 1` matching their length).
         let r = unsafe { libc::ioctl(self.fd, DRM_IOCTL_SYNCOBJ_TIMELINE_SIGNAL, &mut req) };
         let saved = errno();
         self.destroy(handle);
@@ -163,6 +183,8 @@ impl DrmSync {
 
 impl Drop for DrmSync {
     fn drop(&mut self) {
+        // SAFETY: `self.fd` is the fd `open` returned; this `DrmSync` owns it exclusively and `close`
+        // runs exactly once (here, in `Drop`), so there is no double-close or use-after-close.
         unsafe { libc::close(self.fd) };
     }
 }
@@ -203,14 +225,19 @@ mod tests {
         const CREATE: u64 = iowr(0xBF, std::mem::size_of::<Create>());
         const HANDLE_TO_FD: u64 = iowr(0xC1, std::mem::size_of::<DrmSyncobjHandle>());
         let mut c = Create::default();
+        // SAFETY: `sync.fd` is the live render-node fd; `CREATE` encodes `size_of::<Create>()`, and
+        // `&mut c` is a live correctly-sized struct the kernel fills (`handle`).
         assert!(unsafe { libc::ioctl(sync.fd, CREATE, &mut c) } >= 0);
         let mut h = DrmSyncobjHandle {
             handle: c.handle,
             ..Default::default()
         };
+        // SAFETY: `sync.fd` is live; `HANDLE_TO_FD` encodes `size_of::<DrmSyncobjHandle>()`; `&mut h`
+        // is a live correctly-sized struct (the kernel reads `handle`, writes `fd`).
         assert!(unsafe { libc::ioctl(sync.fd, HANDLE_TO_FD, &mut h) } >= 0);
         sync.signal_point(h.fd, 1).expect("signal");
         sync.wait_point(h.fd, 1, 100).expect("wait after signal");
+        // SAFETY: `h.fd` is the fd HANDLE_TO_FD just exported; we own it and close it exactly once here.
         unsafe { libc::close(h.fd) };
         sync.destroy(c.handle);
     }

crates/punktfunk-host/src/linux/zerocopy/cuda.rs

@@ -11,6 +11,8 @@
 //! thread) and ffmpeg's `hevc_nvenc` (encode thread); each thread makes it current before use.
 
 #![allow(non_camel_case_types, non_snake_case)]
+// Every `unsafe` block/impl below carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
+#![deny(clippy::undocumented_unsafe_blocks)]
 
 use anyhow::{bail, Result};
 use std::os::raw::{c_int, c_uint, c_void};
@@ -128,8 +130,14 @@ struct CudaApi {
     ) -> CUresult,
     cuDestroyExternalMemory: unsafe extern "C" fn(CUexternalMemory) -> CUresult,
 }
-// The resolved fn pointers are plain addresses into a process-lifetime mapping; safe to share.
+// SAFETY: every field is a bare `extern "C" fn` address into the leaked, process-lifetime
+// `libcuda` mapping (`cuda_api` `forget`s the `Library`, so it is never unloaded) — an immutable
+// value with no interior mutability and no thread affinity. Moving the table to another thread
+// cannot dangle (the code it points at stays mapped) or race (the fields are read-only).
 unsafe impl Send for CudaApi {}
+// SAFETY: as above — the table is a set of immutable fn-pointer addresses with no interior
+// mutability, so concurrent shared reads from multiple threads cannot race; the driver entry
+// points they address are themselves thread-safe.
 unsafe impl Sync for CudaApi {}
 
 /// `CUresult` returned by the wrappers when `libcuda` isn't loaded (no NVIDIA driver). Non-zero so
@@ -143,6 +151,14 @@ static CUDA_API: OnceLock<Option<CudaApi>> = OnceLock::new();
 /// (the expected case on AMD/Intel hosts) — logged at debug, not an error.
 fn cuda_api() -> Option<&'static CudaApi> {
     CUDA_API
+        // SAFETY: `Library::new` runs `libcuda.so.1`'s initializers — it is the trusted NVIDIA
+        // driver library, so loading has no unexpected effects; `?`/`None` handle its absence.
+        // Each `lib.get::<T>(name)` asserts the symbol's real ABI equals `T`: every NUL-terminated
+        // name is a documented CUDA Driver API entry point and `T` is the exact
+        // `unsafe extern "C" fn(..)` signature from cuda.h/cudaGL.h (`_v2` for ctx/mem ops). Each
+        // `Symbol` only borrows `lib` until the end of the struct-literal statement; we deref-copy
+        // the raw fn-pointer out first, then `forget(lib)` leaks the mapping so those addresses
+        // stay valid for the whole process. Runs once under the `OnceLock` init — no aliasing.
         .get_or_init(|| unsafe {
             let lib = libloading::Library::new("libcuda.so.1")
                 .or_else(|_| libloading::Library::new("libcuda.so"))
@@ -361,6 +377,12 @@ pub fn read_plane_to_host(
         Height: height,
         ..Default::default()
     };
+    // SAFETY: `copy_blocking` is unsafe because it issues a CUDA copy; its contract is a valid
+    // descriptor with the shared context current (the caller's responsibility — self-test path).
+    // `&copy` is a live local `#[repr(C)] CUDA_MEMCPY2D` that outlives the synchronous call:
+    // `srcDevice`/`srcPitch` are the caller's live pitched device plane, `dstHost` addresses the
+    // freshly-allocated `host` `Vec` of exactly `width_bytes*height` bytes, and `WidthInBytes`×
+    // `Height` fit both. The copy is synchronous, so `host` is fully written before we return it.
     unsafe { copy_blocking(&copy, "cuMemcpy2DAsync_v2(dev->host)")? };
     Ok(host)
 }
@@ -369,7 +391,13 @@ pub fn read_plane_to_host(
 /// in a `OnceLock`; the raw `CUcontext` is thread-safe to make current from any thread.
 #[derive(Clone, Copy)]
 pub struct Context(pub CUcontext);
+// SAFETY: `CUcontext` is an opaque CUDA driver handle, not a dereferenceable Rust pointer. It is
+// created once and never destroyed (process lifetime), and the only thing done with it is
+// `cuCtxSetCurrent`, which the Driver API explicitly allows from any thread — so transferring the
+// handle to another thread cannot dangle or race (the driver owns the synchronization).
 unsafe impl Send for Context {}
+// SAFETY: as above — the wrapped handle is an immutable opaque address and the driver does all the
+// synchronization, so sharing `&Context` across threads is sound.
 unsafe impl Sync for Context {}
 
 static CONTEXT: OnceLock<Context> = OnceLock::new();
@@ -382,6 +410,12 @@ pub fn context() -> Result<CUcontext> {
     if cuda_api().is_none() {
         bail!("libcuda.so.1 not available — no NVIDIA driver (CUDA zero-copy disabled)");
     }
+    // SAFETY: we returned above unless `cuda_api()` is `Some`, so every wrapper here forwards into
+    // the live, leaked `libcuda` table rather than the not-loaded stub. `cuInit(0)` passes the
+    // API-required flags value 0. `&mut dev`/`&mut ctx` are live, zero/null-initialized stack
+    // out-params the driver writes the device handle / new context into; each outlives its
+    // synchronous call and they are distinct locals (no aliasing). `cuCtxCreate_v2` yields a valid
+    // `CUcontext` on success (`ck` bails otherwise), which becomes the block's value.
     let ctx = unsafe {
         ck(cuInit(0), "cuInit")?;
         let mut dev: CUdevice = 0;
@@ -401,6 +435,10 @@ pub fn context() -> Result<CUcontext> {
 /// Make the shared context current on the calling thread (required before any CUDA op here).
 pub fn make_current() -> Result<()> {
     let ctx = context()?;
+    // SAFETY: `ctx` came from `context()?`, so it is the live shared `CUcontext` and the driver
+    // table is present. `cuCtxSetCurrent` binds that opaque handle to the calling thread; it takes
+    // no Rust-memory pointer and is thread-safe (affects only this thread's current context), so
+    // there is no aliasing or lifetime hazard.
     unsafe { ck(cuCtxSetCurrent(ctx), "cuCtxSetCurrent") }
 }
 
@@ -423,6 +461,12 @@ fn copy_stream() -> CUstream {
         if let Some(s) = cell.get() {
             return s;
         }
+        // SAFETY: `copy_stream` runs with the shared context current (its doc contract), so the
+        // wrappers forward into the live `libcuda` table. `&mut least`/`&mut greatest` are live
+        // stack `i32`s the driver fills with the priority range; `&mut s` is a live null-init
+        // `CUstream` the driver writes the new stream into. All out-params outlive their
+        // synchronous calls and are distinct locals. On any non-zero result we fall back to a null
+        // (NULL-stream) value and never read an uninitialized handle.
         let stream = unsafe {
             let (mut least, mut greatest) = (0i32, 0i32);
             if cuCtxGetStreamPriorityRange(&mut least, &mut greatest) != 0 {
@@ -459,6 +503,11 @@ unsafe fn copy_blocking(copy: &CUDA_MEMCPY2D, what: &str) -> Result<()> {
 fn alloc_pitched(width: u32, height: u32) -> Result<(CUdeviceptr, usize)> {
     let mut ptr: CUdeviceptr = 0;
     let mut pitch: usize = 0;
+    // SAFETY: `cuMemAllocPitch_v2` allocates a pitched device buffer (the wrapper forwards to the
+    // live table on any path that reached allocation). `&mut ptr` (`CUdeviceptr`) and `&mut pitch`
+    // (`usize`) are live, distinct stack out-params the driver writes the allocation pointer and
+    // its pitch into; both outlive the synchronous call. Width/height/element-size are by-value
+    // ints. No aliasing — two separate locals.
     unsafe {
         ck(
             cuMemAllocPitch_v2(
@@ -486,6 +535,10 @@ fn alloc_pitched_nv12(
     let mut y_pitch: usize = 0;
     let mut uv_ptr: CUdeviceptr = 0;
     let mut uv_pitch: usize = 0;
+    // SAFETY: two independent `cuMemAllocPitch_v2` calls (wrapper → live table). `&mut y_ptr`/
+    // `&mut y_pitch` and `&mut uv_ptr`/`&mut uv_pitch` are live, distinct stack out-params the
+    // driver writes each plane's pointer and pitch into; all outlive their synchronous calls. The
+    // dimension/element-size args are by-value ints. No aliasing — four separate locals.
     unsafe {
         ck(
             cuMemAllocPitch_v2(
@@ -524,6 +577,13 @@ struct PoolInner {
 
 impl Drop for PoolInner {
     fn drop(&mut self) {
+        // SAFETY: the pool only exists because allocation succeeded, so the driver table is live.
+        // `PoolInner` drops only once every `DeviceBuffer` that referenced it (each holds an `Arc`
+        // clone) has been recycled, so `free`/`free_uv` hold every outstanding allocation exactly
+        // once and nothing else still uses them — no double-free or use-after-free. We make the
+        // shared context current first (drop may run off the allocating thread) so `cuMemFree_v2`
+        // targets the right context. Each `p` is a `CUdeviceptr` previously returned by
+        // `cuMemAllocPitch_v2`; results are ignored (best-effort teardown).
         unsafe {
             if let Some(c) = CONTEXT.get() {
                 let _ = cuCtxSetCurrent(c.0);
@@ -697,6 +757,12 @@ impl Drop for DeviceBuffer {
             }
         } else {
             // The buffer may be freed on the encode thread; cuMemFree needs a current context.
+            // SAFETY: this is the un-pooled branch (`pool` is `None`), so this `DeviceBuffer`
+            // exclusively owns `self.ptr` (and `self.uv`'s `uv_ptr`), each returned by
+            // `cuMemAllocPitch_v2` and freed exactly once here — `drop` runs once and the
+            // `self.ptr == 0` guard above skips the sentinel/empty case, so no double-free. We set
+            // the shared context current first because drop may run on a thread where it isn't, and
+            // `cuMemFree_v2` needs it. Wrapper → live table; results ignored (teardown).
             unsafe {
                 if let Some(c) = CONTEXT.get() {
                     let _ = cuCtxSetCurrent(c.0);
@@ -745,6 +811,16 @@ impl RegisteredTexture {
     /// unmap. The copy is synchronized (on our priority stream) before unmap so `dst` is ready
     /// before the source dmabuf is recycled. Always unmaps, even if the copy errors.
     pub fn copy_mapped_to(&mut self, dst: &DeviceBuffer) -> Result<()> {
+        // SAFETY: `self.resource` is the valid `CUgraphicsResource` from a successful `register_gl`
+        // (its only constructor), so the wrappers forward to the live table; the caller holds the
+        // GL+CUDA contexts current (the registration's contract). `cuGraphicsMapResources` maps
+        // `count == 1` resource via `&mut self.resource` (a live field) on the default stream;
+        // `cuGraphicsSubResourceGetMappedArray` writes the mapped `CUarray` into the live local
+        // `array` (index 0, mip 0). On failure we unmap and bail (balanced). `&copy` is a live
+        // local `CUDA_MEMCPY2D` outliving the synchronous `copy_blocking`: `srcArray` is valid
+        // while mapped, `dstDevice`/`dstPitch` are `dst`'s live allocation, `width*4`×`height` fit
+        // both. `copy_blocking` syncs before we unmap, so the array stays valid through the copy;
+        // we always unmap afterward (even on error), keeping the map/unmap pair balanced.
         unsafe {
             ck(
                 cuGraphicsMapResources(1, &mut self.resource, std::ptr::null_mut()),
@@ -783,6 +859,14 @@ impl RegisteredTexture {
         width_bytes: usize,
         height: usize,
     ) -> Result<()> {
+        // SAFETY: identical contract to `copy_mapped_to` — `self.resource` is the valid
+        // `CUgraphicsResource` from `register_gl` (wrappers → live table; caller holds GL+CUDA
+        // contexts current). Map `count == 1` resource via the live `&mut self.resource`; the
+        // mapped `CUarray` is written into the live local `array` (index 0, mip 0); on failure we
+        // unmap and bail (balanced). `&copy` is a live local outliving the synchronous
+        // `copy_blocking`: `srcArray` valid while mapped, `dstDevice`/`dstPitch` are the caller's
+        // live plane, `width_bytes`×`height` fit it. We always unmap afterward, even on copy error,
+        // so the map/unmap pair stays balanced and the array outlives the copy.
         unsafe {
             ck(
                 cuGraphicsMapResources(1, &mut self.resource, std::ptr::null_mut()),
@@ -847,6 +931,10 @@ pub fn copy_device_to_device(
         Height: src.height as usize,
         ..Default::default()
     };
+    // SAFETY: `copy_blocking` is unsafe (issues a CUDA copy); the caller must have the shared
+    // context current (documented). `&copy` is a live local device→device `CUDA_MEMCPY2D` outliving
+    // the synchronous call: `srcDevice`/`srcPitch` are `src`'s live allocation, `dstDevice`/
+    // `dstPitch` the caller's live region, `width*4`×`height` within both. Wrapper → live table.
     unsafe { copy_blocking(&copy, "cuMemcpy2DAsync_v2(dev->dev)") }
 }
 
@@ -888,6 +976,12 @@ pub fn copy_nv12_to_device(
         Height: h / 2,
         ..Default::default()
     };
+    // SAFETY: two unsafe `copy_blocking` device→device copies; the caller must have the shared
+    // context current (documented). `&y`/`&uv` are live local `CUDA_MEMCPY2D`s outliving each
+    // synchronous call. All four device pointers are valid: `src.ptr`/`src_uv_ptr` come from a live
+    // NV12 `DeviceBuffer` (its `.uv` presence was checked via `ok_or_else`), `y_dst`/`uv_dst` are
+    // the caller's live NVENC surface planes; the luma copy is `w`×`h`, the chroma copy
+    // `(w/2)*2`×`h/2`, each within its planes. Wrappers → live table.
     unsafe {
         copy_blocking(&y, "cuMemcpy2DAsync_v2(nv12 Y dev->dev)")?;
         copy_blocking(&uv, "cuMemcpy2DAsync_v2(nv12 UV dev->dev)")
@@ -897,6 +991,12 @@ pub fn copy_nv12_to_device(
 impl Drop for RegisteredTexture {
     fn drop(&mut self) {
         if !self.resource.is_null() {
+            // SAFETY: `self.resource` is non-null (just checked) and is the valid
+            // `CUgraphicsResource` from `register_gl`, owned exclusively by this `RegisteredTexture`
+            // and unregistered exactly once here (drop runs once) — no use-after-free or
+            // double-unregister. `cuGraphicsUnregisterResource` releases the GL↔CUDA registration;
+            // wrapper → live table (the resource exists ⇒ the driver was present). Result ignored
+            // (best-effort teardown).
             unsafe {
                 let _ = cuGraphicsUnregisterResource(self.resource);
             }
@@ -913,7 +1013,11 @@ pub struct ExternalDmabuf {
     pub size: u64,
 }
 
-// Raw driver handles; used from the single capture thread but moved with the importer.
+// SAFETY: the fields are opaque CUDA driver handles — an external-memory handle and a device
+// pointer — not dereferenceable Rust memory, and the value is uniquely owned (no `Clone`). It is
+// used from a single capture thread but constructed on / moved between threads with the importer;
+// transferring these handles is sound because uniqueness rules out aliasing and they are destroyed
+// exactly once in `Drop`. Only `Send` (not `Sync`) is asserted, matching the single-thread use.
 unsafe impl Send for ExternalDmabuf {}
 
 impl ExternalDmabuf {
@@ -921,6 +1025,9 @@ impl ExternalDmabuf {
     /// from then on) and map its full `size` bytes to a device pointer. The shared context
     /// must be current.
     pub fn import(fd: i32, size: u64) -> Result<ExternalDmabuf> {
+        // SAFETY: `libc::dup` only reads the integer `fd` and returns a new descriptor (or -1); it
+        // touches no Rust memory and `fd` is the caller's still-owned dmabuf fd (not consumed
+        // here). No aliasing or lifetime concern — a pure syscall on an integer.
         let dup = unsafe { libc::dup(fd) };
         if dup < 0 {
             bail!("dup(dmabuf fd) failed");
@@ -938,8 +1045,17 @@ impl ExternalDmabuf {
         };
         desc.handle[0] = dup as u32 as u64; // union member `int fd` (little-endian low bytes)
         let mut ext: CUexternalMemory = std::ptr::null_mut();
+        // SAFETY: `cuImportExternalMemory` imports the memory described by `&desc`, a live local
+        // `#[repr(C)] CUDA_EXTERNAL_MEMORY_HANDLE_DESC` (cuda.h 64-bit layout) that outlives this
+        // synchronous call: `type_` is OPAQUE_FD, `handle[0]` holds the dup'd fd in the union's
+        // `int fd` low bytes, `size` is set. `&mut ext` is a live null-init out-param the driver
+        // writes the imported handle into. The driver takes ownership of the fd only on success.
+        // Distinct locals → no aliasing. Wrapper → live table (caller holds the context current).
         let r = unsafe { cuImportExternalMemory(&mut ext, &desc) };
         if r != 0 {
+            // SAFETY: import failed (`r != 0`), so the driver did NOT take ownership of `dup`; we
+            // still own it and close it exactly once here on the error path (the success path never
+            // closes it — the driver does). `libc::close` acts on the integer fd alone.
             unsafe { libc::close(dup) }; // import failed → the driver did not take the fd
             bail!("cuImportExternalMemory failed ({r}) — LINEAR dmabuf import unsupported?");
         }
@@ -949,8 +1065,17 @@ impl ExternalDmabuf {
             ..Default::default()
         };
         let mut ptr: CUdeviceptr = 0;
+        // SAFETY: maps a device pointer from `ext` (the valid `CUexternalMemory` just imported) per
+        // `&buf`, a live local `CUDA_EXTERNAL_MEMORY_BUFFER_DESC` (offset 0, full `size`) that
+        // outlives this synchronous call. `&mut ptr` is a live zero-init out-param the driver writes
+        // the mapped device address into; distinct locals → no aliasing. Wrapper → live table
+        // (context current).
         let r = unsafe { cuExternalMemoryGetMappedBuffer(&mut ptr, ext, &buf) };
         if r != 0 {
+            // SAFETY: mapping failed; `ext` is the valid `CUexternalMemory` we imported and
+            // exclusively own. We destroy it exactly once here on the error path (the success path
+            // instead moves it into the returned `ExternalDmabuf`, whose `Drop` destroys it),
+            // releasing the fd the driver took — no double-destroy or use-after-free.
             unsafe {
                 let _ = cuDestroyExternalMemory(ext);
             }
@@ -962,6 +1087,12 @@ impl ExternalDmabuf {
 
 impl Drop for ExternalDmabuf {
     fn drop(&mut self) {
+        // SAFETY: this `ExternalDmabuf` only exists after a successful import, so the driver table
+        // is live. It exclusively owns `self.ptr` (the mapped buffer) and `self.ext` (the external
+        // memory), each torn down exactly once here (drop runs once; guarded by `!= 0` / `!null`) —
+        // no double-free or use-after-free. We make the shared context current first because drop
+        // may run off the import thread, and we free the mapped buffer before destroying its
+        // backing external memory. Results ignored (best-effort teardown).
         unsafe {
             if let Some(c) = CONTEXT.get() {
                 let _ = cuCtxSetCurrent(c.0);
@@ -996,5 +1127,10 @@ pub fn copy_pitched_to_buffer(
     };
     // copy_blocking syncs our priority stream before returning, so the copy is complete before the
     // dmabuf is requeued to the producer.
+    // SAFETY: `copy_blocking` is unsafe (issues a CUDA copy); the caller must have the shared
+    // context current (documented). `&copy` is a live local device→device `CUDA_MEMCPY2D` outliving
+    // the synchronous call: `srcDevice`/`srcPitch` are the caller's live mapped span (e.g. an
+    // `ExternalDmabuf`), `dstDevice`/`dstPitch` are `dst`'s live allocation, `width*4`×`height`
+    // within both. Wrapper → live table.
     unsafe { copy_blocking(&copy, "cuMemcpy2DAsync_v2(ext->dev)") }
 }

crates/punktfunk-host/src/linux/zerocopy/egl.rs

@@ -12,6 +12,8 @@
 //! owned [`DeviceBuffer`] so the dmabuf can be returned to the compositor immediately.
 
 #![allow(non_upper_case_globals)]
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
+#![deny(clippy::undocumented_unsafe_blocks)]
 
 use super::cuda::{self, DeviceBuffer};
 use anyhow::{bail, ensure, Context as _, Result};
@@ -415,6 +417,14 @@ impl Nv12Blit {
 
 impl Drop for Nv12Blit {
     fn drop(&mut self) {
+        // SAFETY: these GL names (textures/FBOs/VAO/programs) were all created by THIS `Nv12Blit`
+        // in `Nv12Blit::new` on the current GL context, which is still current because the owning
+        // `EglImporter` is dropped on its single capture thread (fields drop before
+        // `EglImporter::drop`, which never releases the context). `glDelete*` takes a count + a
+        // pointer to that many names: `&self.y_tex`/`&self.vao` are `&u32` to one live field (n=1);
+        // `[self.y_fbo, self.uv_fbo].as_ptr()` points at a 2-element temporary that lives for the
+        // whole `glDeleteFramebuffers` call (n=2 matches). The symbols dispatch through libGL
+        // (libglvnd) to the driver for the current context. Each name is deleted exactly once.
         unsafe {
             glDeleteTextures(1, &self.y_tex);
             glDeleteTextures(1, &self.uv_tex);
@@ -459,7 +469,14 @@ pub struct EglImporter {
     render_fd: c_int,
 }
 
-// The EGL handles are confined to the capture thread; the struct is moved there once.
+// SAFETY: `EglImporter` owns thread-affine handles — an EGLDisplay/contexts made current on one
+// thread, a loaded GL proc pointer, a `gbm_device*`, a raw fd, and CUDA-registered GL textures —
+// none safe to touch concurrently. It is constructed inside `pipewire_thread` on the dedicated
+// `punktfunk-pipewire` thread, and every method (`import*`, `supported_modifiers`, `Drop`) runs on
+// that same thread; it is never accessed through a shared `&` from another thread. `Send` asserts
+// only that transferring *ownership* is sound (needed so the importer can live in the PipeWire
+// stream's user-data, whose API imposes a `Send` bound) — the live handles are never used
+// off-thread. `Sync` is deliberately NOT implied.
 unsafe impl Send for EglImporter {}
 
 impl EglImporter {
@@ -470,16 +487,38 @@ impl EglImporter {
         // to the same DRM device CUDA-GL interop associates with, which the EGL device platform
         // did not (cuGraphicsGLRegisterImage rejected device-platform GL textures).
         let path = std::ffi::CString::new("/dev/dri/renderD128").unwrap();
+        // SAFETY: `path` is a live local `CString` (built from a string with no interior NUL, so it
+        // is NUL-terminated); `path.as_ptr()` is a valid pointer to that buffer which outlives this
+        // synchronous `open`. `open` only reads the path and returns a new fd (or -1); it neither
+        // retains the pointer nor writes through it, so there is no aliasing or lifetime hazard.
         let render_fd = unsafe { libc::open(path.as_ptr(), libc::O_RDWR | libc::O_CLOEXEC) };
         ensure!(render_fd >= 0, "open /dev/dri/renderD128 for GBM");
+        // SAFETY: `render_fd` is the live DRM render-node fd just returned by `open` and checked
+        // `>= 0`. `gbm_create_device` (libgbm, linked above) builds a `gbm_device` over that fd and
+        // returns a `*mut gbm_device` (or null); it borrows but does not take ownership of the fd,
+        // which `EglImporter` keeps open and closes only in `Drop` after `gbm_device_destroy`. No
+        // Rust-owned memory is passed, so there is nothing to alias.
         let gbm = unsafe { gbm_create_device(render_fd) };
         if gbm.is_null() {
+            // SAFETY: reached only when `gbm_create_device` failed (null) — the fd was not consumed
+            // and no `EglImporter` exists yet to close it again, so this `close` runs exactly once on
+            // the live `render_fd`, releasing it before the error return. No double-close.
             unsafe { libc::close(render_fd) };
             anyhow::bail!("gbm_create_device failed");
         }
 
+        // SAFETY: `Egl::load_required` dlopens the system libEGL and binds its entry points,
+        // trusting that libEGL (libglvnd) is a genuine EGL 1.5 implementation whose core symbols
+        // match the ABI the `khronos_egl` `EGL1_5` bindings declare. No Rust memory is passed; the
+        // returned instance is afterwards used only through the safe `khronos_egl` wrappers.
         let egl: Egl =
             unsafe { Egl::load_required() }.context("load libEGL (EGL 1.5 dynamic instance)")?;
+        // SAFETY: `gbm` is the non-null `gbm_device*` created just above (checked), and
+        // `EGL_PLATFORM_GBM_KHR` is exactly the platform enum that pairs with a GBM device as the
+        // native-display handle, so the `gbm as NativeDisplayType` cast hands EGL a valid native
+        // display for the requested platform. `&[egl::ATTRIB_NONE]` is a properly terminated, empty
+        // attribute array borrowed for this synchronous call; EGL only reads it and returns an
+        // `EGLDisplay`, retaining no pointer into Rust memory.
         let display = unsafe {
             egl.get_platform_display(
                 EGL_PLATFORM_GBM_KHR,
@@ -533,6 +572,13 @@ impl EglImporter {
             .context("eglCreateContext(OpenGL)")?;
         egl.make_current(display, None, None, Some(gl_ctx))
             .context("eglMakeCurrent surfaceless (needs EGL_KHR_surfaceless_context)")?;
+        // SAFETY: the GL context was made current on this thread just above, which `eglGetProcAddress`
+        // requires to return a usable pointer. The non-null (`?`-checked) pointer it returns for
+        // "glEGLImageTargetTexture2DOES" is the driver's implementation of that GL-OES entry point,
+        // whose real ABI is `void(GLenum, GLeglImageOES)` = `(u32, *mut c_void)` `extern "system"`.
+        // `EglImageTargetFn` is declared with exactly that signature, so the transmute only retypes a
+        // same-size, same-ABI thin function pointer (no value/representation change). The function is
+        // present because `EGL_EXT_image_dma_buf_import` was asserted on this display above.
         let egl_image_target: EglImageTargetFn = unsafe {
             std::mem::transmute(
                 egl.get_proc_address("glEGLImageTargetTexture2DOES")
@@ -543,6 +589,10 @@ impl EglImporter {
         // Create the shared CUDA context up front so import() is pure hot path.
         cuda::context().context("create CUDA context")?;
 
+        // SAFETY: `egl::NO_CONTEXT` is EGL's defined sentinel (a null handle) for "no context";
+        // `Context::from_ptr` only stores the handle (it never dereferences it), so wrapping the
+        // null sentinel is sound and yields exactly the `EGL_NO_CONTEXT` value that
+        // `eglCreateImage(EGL_LINUX_DMA_BUF_EXT)` requires as its context argument later.
         let no_ctx = unsafe { egl::Context::from_ptr(egl::NO_CONTEXT) };
         tracing::info!(
             "zero-copy EGL importer ready (GBM platform + GL texture interop, dma_buf_import + modifiers)"
@@ -602,8 +652,21 @@ impl EglImporter {
         let Some(sym) = self.egl.get_proc_address("eglQueryDmaBufModifiersEXT") else {
             return Vec::new();
         };
+        // SAFETY: `sym` is the non-null pointer `eglGetProcAddress("eglQueryDmaBufModifiersEXT")`
+        // returned (the `let-else` already bailed on `None`) — the driver's implementation of that
+        // EGL extension entry point. `QueryFn` is declared with that function's exact documented ABI
+        // (`EGLDisplay, EGLint, EGLint, EGLuint64* , EGLBoolean*, EGLint* -> EGLBoolean`), all
+        // `extern "system"`, so the transmute only retypes a same-size, same-ABI thin fn pointer.
         let query: QueryFn = unsafe { std::mem::transmute(sym) };
         let dpy = self.display.as_ptr();
+        // SAFETY: `dpy` is this importer's live, initialized `EGLDisplay`; `query` is the proc loaded
+        // just above. The first call passes null out-arrays with `max_modifiers == 0`, which the
+        // extension defines as "write only the count" — it writes solely through `&mut count` (a live
+        // local `i32`). For the second call, `mods`/`ext` are freshly allocated `Vec`s of exactly
+        // `count` elements and `max_modifiers == count`, so the driver writes at most `count`
+        // `u64`/`u32` entries (in bounds) plus the actual count through `&mut n` (a live local). All
+        // four Rust addresses outlive these synchronous calls and alias nothing else. `truncate` only
+        // shrinks, so even a misbehaving `n > count` cannot read out of bounds.
         unsafe {
             let mut count: i32 = 0;
             if query(
@@ -699,6 +762,10 @@ impl EglImporter {
             ]);
         }
         attrs.push(egl::ATTRIB_NONE);
+        // SAFETY: `eglCreateImage(EGL_LINUX_DMA_BUF_EXT, ...)` mandates a NULL `EGLClientBuffer`
+        // (the source is described entirely by the attribute list built above), so wrapping
+        // `null_mut()` is the required value. `from_ptr` only stores the pointer without
+        // dereferencing it, so constructing it from null is sound.
         let client = unsafe { egl::ClientBuffer::from_ptr(std::ptr::null_mut()) };
         let image = self
             .egl
@@ -733,11 +800,21 @@ impl EglImporter {
     ) -> Result<DeviceBuffer> {
         cuda::make_current()?;
         if self.blit.as_ref().map(|b| (b.width, b.height)) != Some((width, height)) {
+            // SAFETY: `GlBlit::new` requires the GL context current on the calling thread and a
+            // current CUDA context. Both hold: this runs on the capture thread where
+            // `EglImporter::new` made the GL context current and never released it, and
+            // `cuda::make_current()?` ran at the top of this function. `width`/`height` are plain
+            // `Copy` frame dimensions.
             self.blit = Some(unsafe { GlBlit::new(width, height)? });
         }
         let egl_image_target = self.egl_image_target;
         let blit = self.blit.as_mut().unwrap();
-        // SAFETY: GL + CUDA contexts current on this thread; `image` is a valid EGLImage.
+        // SAFETY: `GlBlit::run` requires a current GL context and a valid `EGLImage`. The GL context
+        // is current on this capture thread (made current in `EglImporter::new`, never released) and
+        // `cuda::make_current()` ran above; `egl_image_target` is the `glEGLImageTargetTexture2DOES`
+        // pointer loaded in `new`; `image` is the raw handle of the live `EGLImage` that
+        // `import_inner` created with `eglCreateImage` and destroys only AFTER this call returns, so
+        // it stays valid for the whole synchronous `run`.
         unsafe { blit.run(egl_image_target, image)? };
         // Persistent registration (mapped per frame) + a pooled buffer — no per-frame
         // cuGraphicsGLRegisterImage / cuMemAllocPitch.
@@ -757,11 +834,21 @@ impl EglImporter {
     ) -> Result<DeviceBuffer> {
         cuda::make_current()?;
         if self.nv12_blit.as_ref().map(|b| (b.width, b.height)) != Some((width, height)) {
+            // SAFETY: `Nv12Blit::new` requires the GL context current on the calling thread and a
+            // current CUDA context. Both hold: this runs on the capture thread where
+            // `EglImporter::new` made the GL context current and never released it, and
+            // `cuda::make_current()?` ran at the top of this function. `width`/`height` are plain
+            // `Copy` frame dimensions.
             self.nv12_blit = Some(unsafe { Nv12Blit::new(width, height)? });
         }
         let egl_image_target = self.egl_image_target;
         let blit = self.nv12_blit.as_mut().unwrap();
-        // SAFETY: GL + CUDA contexts current on this thread; `image` is a valid EGLImage.
+        // SAFETY: `Nv12Blit::run` requires a current GL context and a valid `EGLImage`. The GL
+        // context is current on this capture thread (made current in `EglImporter::new`, never
+        // released) and `cuda::make_current()` ran above; `egl_image_target` is the
+        // `glEGLImageTargetTexture2DOES` pointer loaded in `new`; `image` is the raw handle of the
+        // live `EGLImage` that `import_inner` created with `eglCreateImage` and destroys only AFTER
+        // this call returns, so it stays valid for the whole synchronous `run`.
         unsafe { blit.run(egl_image_target, image)? };
         let dst = blit.pool.get()?;
         cuda::copy_mapped_nv12(&mut blit.y_registered, &mut blit.uv_registered, &dst)?;
@@ -787,9 +874,22 @@ impl EglImporter {
         );
         cuda::make_current()?;
         if self.nv12_blit.as_ref().map(|b| (b.width, b.height)) != Some((width, height)) {
+            // SAFETY: `Nv12Blit::new` requires the GL context current on the calling thread and a
+            // current CUDA context. Both hold: this self-test path runs on the thread that owns this
+            // `EglImporter` with its GL context current, and `cuda::make_current()?` ran just above.
+            // `width`/`height` are plain `Copy` scalars.
             self.nv12_blit = Some(unsafe { Nv12Blit::new(width, height)? });
         }
         let blit = self.nv12_blit.as_mut().unwrap();
+        // SAFETY: runs on the thread that owns this `EglImporter` with its GL context current.
+        // `blit.src_tex` is a texture this `Nv12Blit` owns; `glTexStorage2D` allocates immutable
+        // RGBA8 storage exactly once (guarded by `test_src_storage`) sized `width×height`.
+        // `glTexSubImage2D` then uploads exactly `width×height` RGBA8 texels, reading `width*height*4`
+        // bytes from `rgba.as_ptr()`; the caller already asserted `rgba.len() == width*height*4`, rows
+        // are `width*4` bytes (a multiple of the default 4-byte unpack alignment, so no row-padding
+        // over-read), and `rgba` is a live borrow that outlives this synchronous upload. `run_passes`
+        // then needs only the current GL context (no further Rust pointers). All GL names are this
+        // blit's own, alias no other live object, and nothing is retained past the calls.
         unsafe {
             // Upload the host RGBA into `src_tex` (an immutable GL_RGBA8 backing must exist first;
             // the live path never allocates it — it retargets `src_tex` via EGLImage instead).
@@ -824,9 +924,16 @@ impl EglImporter {
 impl Drop for EglImporter {
     fn drop(&mut self) {
         if !self.gbm.is_null() {
+            // SAFETY: `self.gbm` is the non-null `gbm_device*` from `gbm_create_device` in `new`
+            // (checked non-null here), owned exclusively by this `EglImporter` and destroyed exactly
+            // once (in `Drop`). It is freed BEFORE `render_fd` is closed below — the correct order,
+            // since the device borrowed that fd for its lifetime.
             unsafe { gbm_device_destroy(self.gbm) };
         }
         if self.render_fd >= 0 {
+            // SAFETY: `self.render_fd` is the fd `open` returned in `new` (checked `>= 0`), owned
+            // exclusively by this `EglImporter`; this `close` runs exactly once, after the gbm device
+            // that borrowed it has been destroyed. No double-close or use-after-close.
             unsafe { libc::close(self.render_fd) };
         }
     }

crates/punktfunk-host/src/linux/zerocopy/vulkan.rs

@@ -16,6 +16,9 @@
 //! a stream's life). Falls back cleanly: any init/import error disables the importer and the
 //! CPU mmap path takes over.
 
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
+#![deny(clippy::undocumented_unsafe_blocks)]
+
 use super::cuda::{self, DeviceBuffer};
 use anyhow::{anyhow, bail, Context as _, Result};
 use ash::vk;
@@ -51,12 +54,27 @@ pub struct VkBridge {
     dst: Option<DstBuf>,
 }
 
-// Confined to the capture thread; moved there once.
+// SAFETY: `VkBridge` owns ash Vulkan handles (instance/device/queue/command pool+buffer/fence), a
+// CUDA external-memory mapping, and an fd→buffer cache — none `Sync`, and a single queue +
+// command buffer must be externally synchronized. It is created inside `EglImporter::import_linear`
+// on the dedicated `punktfunk-pipewire` capture thread and every method (`import_linear`, `Drop`)
+// runs on that thread; it is never shared via `&` across threads. `Send` asserts only that
+// transferring ownership is sound (so the bridge can live inside the `Send` `EglImporter`); the live
+// handles are never touched off-thread, and `Sync` is deliberately NOT implied.
 unsafe impl Send for VkBridge {}
 
 impl VkBridge {
     /// Bring up Vulkan on the NVIDIA GPU with the external-memory extensions.
     pub fn new() -> Result<VkBridge> {
+        // SAFETY: standard ash bring-up — every call is `unsafe` only because ash cannot statically
+        // verify Vulkan handle/CreateInfo validity. `ash::Entry::load` dlopens a real system
+        // libvulkan. Each `*CreateInfo`/`AllocateInfo` is built by ash's builders from locals (`app`,
+        // `exts`, `prio`, `qci`, and the inline infos) that all live for the duration of the
+        // synchronous `create_*`/`enumerate_*` call that reads them — in particular the
+        // `enabled_extension_names(&exts)` and `queue_priorities(&prio)` borrows outlive their calls.
+        // Every handle passed (`instance`, `phys`, `device`, `qf`, `cmd_pool`) was just created and
+        // checked via `?`/`ok_or_else` in this same function, so no invalid handle is ever used. This
+        // constructor shares nothing across threads.
         unsafe {
             let entry = ash::Entry::load().context("load libvulkan")?;
             let app = vk::ApplicationInfo::default().api_version(vk::API_VERSION_1_1);
@@ -294,6 +312,19 @@ impl VkBridge {
         height: u32,
         pool: &cuda::BufferPool,
     ) -> Result<DeviceBuffer> {
+        // SAFETY: `fd` is the live dmabuf fd handed in by the caller (borrowed; `import_src` dup's it
+        // internally and Vulkan owns the dup). `libc::lseek` only queries the fd's size. The unsafe
+        // `import_src`/`ensure_dst` are called with a valid fd and a checked size. The bounds are
+        // proven: `import_src` asserts `size >= span` (so the cached `src_size >= span`),
+        // `copy_size = src_size.min(span)`, and `ensure_dst(copy_size)` makes `dst` at least
+        // `copy_size` — so the GPU `cmd_copy_buffer` of `copy_size` bytes reads/writes within both
+        // buffers, and the later CUDA pitched copy reading `[offset, span)` from `dst.cuda.ptr` (=
+        // `offset + stride*height = span <= copy_size`) stays inside the freshly-copied region. The
+        // `*Info`/`region`/`cmds`/`submit` are locals that outlive the synchronous calls reading them.
+        // `cmd`/`queue`/`fence` are this bridge's own handles, used on this single thread only. The
+        // host-side `wait_for_fences` fully retires the Vulkan copy BEFORE CUDA reads the shared
+        // memory, so there is no GPU write/read data race. `dst` is an `&self.dst` shared borrow that
+        // does not alias the `&self.device` calls.
         unsafe {
             let span = offset as u64 + stride as u64 * height as u64;
             if !self.src_cache.contains_key(&fd) {
@@ -347,6 +378,15 @@ impl VkBridge {
 
 impl Drop for VkBridge {
     fn drop(&mut self) {
+        // SAFETY: runs once when the bridge is dropped on its owning capture thread.
+        // `device_wait_idle` first drains all in-flight GPU work, so no queued command still
+        // references these objects. Every handle freed (the `src_cache` buffers+memories, the `dst`
+        // buffer+memory, `fence`, `cmd_pool`, `device`, `instance`) was created by this `VkBridge`
+        // and owned exclusively by it, so each `destroy_*`/`free_*` runs exactly once with no
+        // double-free, in dependency order (child objects before `device`, `device` before
+        // `instance`). `dst.cuda` is dropped after `free_memory`, which is safe because CUDA holds
+        // its own dup'd OPAQUE_FD reference to the underlying allocation. No other thread touches
+        // these handles.
         unsafe {
             let _ = self.device.device_wait_idle();
             for (_, s) in self.src_cache.drain() {

crates/punktfunk-host/src/main.rs

@@ -13,18 +13,33 @@
 
 // Scaffold: trait methods and config paths are defined ahead of their backends.
 #![allow(dead_code)]
+// Unsafe-proof program: every `unsafe {}` / `unsafe impl` in the crate must carry a `// SAFETY:`
+// proof of why it is sound. This crate-root deny is the permanent, catch-all gate (it also covers
+// any future module); individual files keep their own `#![deny(...)]` as belt-and-suspenders.
+#![deny(clippy::undocumented_unsafe_blocks)]
 
 mod audio;
 mod capture;
+mod config;
 mod discovery;
+// Goal-1 stage 6: top-level platform-only modules live under `src/linux/` and `src/windows/`; `#[path]`
+// keeps the `crate::*` module names flat (every existing path is unchanged).
 #[cfg(target_os = "linux")]
+#[path = "linux/dmabuf_fence.rs"]
 mod dmabuf_fence;
 #[cfg(target_os = "linux")]
+#[path = "linux/drm_sync.rs"]
 mod drm_sync;
 mod encode;
 mod gamestream;
 mod hdr;
 mod inject;
+#[cfg(target_os = "windows")]
+#[path = "windows/install.rs"]
+mod install;
+#[cfg(target_os = "windows")]
+#[path = "windows/interactive.rs"]
+mod interactive;
 mod library;
 mod mgmt;
 mod mgmt_token;
@@ -33,13 +48,24 @@ mod pipeline;
 mod punktfunk1;
 mod pwinit;
 #[cfg(target_os = "windows")]
+#[path = "windows/service.rs"]
 mod service;
+mod session_plan;
 mod session_tuning;
 mod spike;
+mod stats_recorder;
 mod vdisplay;
 #[cfg(target_os = "windows")]
+#[path = "windows/wgc_helper.rs"]
 mod wgc_helper;
+#[cfg(target_os = "windows")]
+#[path = "windows/win_adapter.rs"]
+mod win_adapter;
+#[cfg(target_os = "windows")]
+#[path = "windows/win_display.rs"]
+mod win_display;
 #[cfg(target_os = "linux")]
+#[path = "linux/zerocopy/mod.rs"]
 mod zerocopy;
 
 use anyhow::{bail, Context, Result};
@@ -152,7 +178,8 @@ fn real_main() -> Result<()> {
         // sends back. Verify with `evtest` / `ls /dev/input/by-id/*Punktfunk*` / `wpctl status`.
         #[cfg(target_os = "linux")]
         Some("dualsense-test") => {
-            use inject::dualsense::{DsState, DualSensePad};
+            use inject::dualsense::DualSensePad;
+            use inject::dualsense_proto::DsState;
             let secs: u64 = args
                 .iter()
                 .skip_while(|a| *a != "--seconds")
@@ -200,6 +227,134 @@ fn real_main() -> Result<()> {
             println!("dualsense-test: done");
             Ok(())
         }
+        // Windows: create a virtual DualSense via the UMDF driver (SwDeviceCreate per-session devnode
+        // + the shared-memory channel) and hold it, pushing one fixed frame (Cross + LS-right). Drives
+        // the real DualSenseWindowsManager, so it validates the device lifecycle end to end. Verify
+        // while it holds: `Get-PnpDevice` shows a VID_054C device, and a HID read returns the pushed
+        // report (byte1=0xC0, byte8=0x28). On exit the pad drops → SwDeviceClose removes the devnode.
+        #[cfg(target_os = "windows")]
+        Some("dualsense-windows-test") => {
+            use crate::gamestream::gamepad::{GamepadEvent, GamepadFrame};
+            use std::time::{Duration, Instant};
+            let secs: u64 = args
+                .iter()
+                .skip_while(|a| *a != "--seconds")
+                .nth(1)
+                .and_then(|s| s.parse().ok())
+                .unwrap_or(20);
+            // `--index N` creates pad `pf_pad_N` (default 0) — use a spare index (e.g. 1) to test
+            // alongside a running host that already holds pad 0. `--ds4` drives the DualShock 4
+            // backend instead of the DualSense one.
+            let idx: u8 = args
+                .iter()
+                .skip_while(|a| *a != "--index")
+                .nth(1)
+                .and_then(|s| s.parse().ok())
+                .unwrap_or(0);
+            let ds4 = args.iter().any(|a| a == "--ds4");
+            let xbox = args.iter().any(|a| a == "--xbox");
+            // Same drive loop for either backend (identical method surface): Arrival creates the pad,
+            // State pushes a cycling report, pump surfaces a game's rumble/lightbar feedback.
+            macro_rules! drive {
+                ($mgr:expr, $label:expr) => {{
+                    let mut mgr = $mgr;
+                    mgr.handle(&GamepadEvent::Arrival {
+                        index: idx,
+                        kind: 2,
+                        capabilities: 0,
+                    });
+                    println!(
+                        "virtual {} up — cycling Cross + sweeping the left stick for {secs}s. Watch \
+                         it in joy.cpl / Steam / a game; any feedback the game sends prints below.",
+                        $label
+                    );
+                    let deadline = Instant::now() + Duration::from_secs(secs);
+                    let (mut i, mut last) = (0i32, Instant::now());
+                    while Instant::now() < deadline {
+                        mgr.pump(
+                            |pad, lo, hi| {
+                                println!("  rumble from game: pad={pad} low={lo} high={hi}")
+                            },
+                            |o| println!("  hid output from game: {o:?}"),
+                        );
+                        if last.elapsed() >= Duration::from_millis(400) {
+                            last = Instant::now();
+                            i += 1;
+                            let buttons = if i % 2 == 0 {
+                                punktfunk_core::input::gamepad::BTN_A // Cross
+                            } else {
+                                0
+                            };
+                            let lx = (((i % 64) - 32) * 1024) as i16; // sweep left stick X
+                            mgr.handle(&GamepadEvent::State(GamepadFrame {
+                                index: idx as i16,
+                                active_mask: 1 << idx,
+                                buttons,
+                                left_trigger: 0,
+                                right_trigger: 0,
+                                ls_x: lx,
+                                ls_y: 0,
+                                rs_x: 0,
+                                rs_y: 0,
+                            }));
+                        }
+                        std::thread::sleep(Duration::from_millis(15));
+                    }
+                }};
+            }
+            if xbox {
+                // Xbox 360 via the XUSB companion: a different surface (handle + pump_rumble, no
+                // HID-output plane), so drive it inline rather than via the macro.
+                let mut mgr = inject::gamepad::GamepadManager::new();
+                mgr.handle(&GamepadEvent::Arrival {
+                    index: idx,
+                    kind: 1,
+                    capabilities: 0,
+                });
+                println!(
+                    "virtual Xbox 360 (XUSB) up — sweeping LS + toggling A for {secs}s. Check with \
+                     an XInput game or xinputtest.exe."
+                );
+                let deadline = Instant::now() + Duration::from_secs(secs);
+                let mut t = 0i32;
+                while Instant::now() < deadline {
+                    mgr.pump_rumble(|pad, lo, hi| {
+                        println!("  rumble from game: pad={pad} low={lo} high={hi}")
+                    });
+                    t += 1;
+                    let lx = (((t % 200) - 100) * 327).clamp(-32768, 32767) as i16; // sweep ±32700
+                    let buttons = if (t / 67) % 2 == 0 {
+                        punktfunk_core::input::gamepad::BTN_A
+                    } else {
+                        0
+                    };
+                    mgr.handle(&GamepadEvent::State(GamepadFrame {
+                        index: idx as i16,
+                        active_mask: 1 << idx,
+                        buttons,
+                        left_trigger: 0,
+                        right_trigger: 0,
+                        ls_x: lx,
+                        ls_y: 0,
+                        rs_x: 0,
+                        rs_y: 0,
+                    }));
+                    std::thread::sleep(Duration::from_millis(15));
+                }
+            } else if ds4 {
+                drive!(
+                    inject::dualshock4_windows::DualShock4WindowsManager::new(),
+                    "DualShock 4"
+                );
+            } else {
+                drive!(
+                    inject::dualsense_windows::DualSenseWindowsManager::new(),
+                    "DualSense"
+                );
+            }
+            println!("dualsense-windows-test: done (devnode removed)");
+            Ok(())
+        }
         // Capture→encode→file pipeline spike (dev tool).
         Some("spike") => spike::run(parse_spike(&args[1..])?),
         // Native punktfunk/1 host (QUIC control plane + UDP data plane).
@@ -238,7 +393,7 @@ fn real_main() -> Result<()> {
         }
         // USER-session WGC helper (Windows two-process secure-desktop design): capture the EXISTING
         // SudoVDA via WGC + NVENC, stream AUs on stdout to the SYSTEM host. Spawned by the host
-        // (CreateProcessAsUser), not run by hand. See docs/windows-secure-desktop.md.
+        // (CreateProcessAsUser), not run by hand. See design/archive/windows-secure-desktop.md.
         #[cfg(target_os = "windows")]
         Some("wgc-helper") => {
             let get = |flag: &str| {
@@ -270,6 +425,12 @@ fn real_main() -> Result<()> {
         // that launches the host into the active interactive session.
         #[cfg(target_os = "windows")]
         Some("service") => service::main(&args[1..]),
+        // Install-time work the Windows installer delegates to the exe instead of locale-parsed
+        // PowerShell *files* (the ANSI-codepage parse-break root fix; see windows/install.rs).
+        #[cfg(target_os = "windows")]
+        Some("driver") => install::driver_main(&args[1..]),
+        #[cfg(target_os = "windows")]
+        Some("web") => install::web_main(&args[1..]),
         Some("-h") | Some("--help") | Some("help") | None => {
             print_usage();
             Ok(())
@@ -553,7 +714,7 @@ SPIKE OPTIONS:
 
 NOTES:
     'portal' needs headless Sway + xdg-desktop-portal-wlr running in this session
-    (see docs/linux-setup.md). 'synthetic' needs no capture session and always runs.
+    (see design/linux-setup.md). 'synthetic' needs no capture session and always runs.
     Encoded AUs are written to a playable file AND (unless --no-loopback) fed through a
     punktfunk_core host→client loopback that reassembles and byte-verifies each one.
     Both 'serve' and 'punktfunk1-host' advertise the native service over mDNS

crates/punktfunk-host/src/mgmt.rs

@@ -6,7 +6,7 @@
 //! The API is versioned under `/api/v1` and described by an OpenAPI 3.1 document generated
 //! at compile time with `utoipa` — `punktfunk-host openapi` prints it for client codegen, the
 //! running server serves it at `/api/v1/openapi.json` plus interactive docs at `/api/docs`,
-//! and a copy is checked in at `docs/api/openapi.json` (a test fails if it drifts, like the
+//! and a copy is checked in at `api/openapi.json` (a test fails if it drifts, like the
 //! cbindgen header).
 //!
 //! Security: binds loopback by default, serves HTTPS with the host's identity cert, and requires
@@ -20,6 +20,7 @@ use crate::gamestream::{
     tls::{serve_https, PeerCertFingerprint},
     AppState, APP_VERSION, AUDIO_PORT, CONTROL_PORT, GFE_VERSION, RTSP_PORT, VIDEO_PORT,
 };
+use crate::stats_recorder::{Capture, CaptureMeta, StatsStatus};
 use anyhow::{Context, Result};
 use axum::{
     extract::{Path, Request, State},
@@ -66,6 +67,9 @@ struct MgmtState {
     /// Native (punktfunk/1) pairing — shared with the QUIC host when the unified `serve --native`
     /// runs it. `None` ⇒ GameStream-only host (the native endpoints report `enabled: false`).
     native: Option<Arc<crate::native_pairing::NativePairing>>,
+    /// Shared streaming-stats recorder — the same handle the streaming loops emit into, so an
+    /// operator can arm/stop a capture here and review/list/delete saved recordings.
+    stats: Arc<crate::stats_recorder::StatsRecorder>,
     token: Option<String>,
     /// The port we serve on, echoed in [`PortMap`] so a client can persist a full endpoint map.
     port: u16,
@@ -77,6 +81,7 @@ pub async fn run(
     state: Arc<AppState>,
     opts: Options,
     native: Option<Arc<crate::native_pairing::NativePairing>>,
+    stats: Arc<crate::stats_recorder::StatsRecorder>,
 ) -> Result<()> {
     // The mgmt API is HTTPS + token-authenticated ALWAYS (even on loopback): `parse_serve`
     // guarantees a token (CLI flag / env / persisted ~/.config/punktfunk/mgmt-token / generated).
@@ -100,7 +105,7 @@ pub async fn run(
         auth = "mTLS (paired cert) or bearer (required)",
         "management API listening over HTTPS (docs at /api/docs, spec at /api/v1/openapi.json)"
     );
-    let app = app(state, Some(token), opts.bind.port(), native);
+    let app = app(state, Some(token), opts.bind.port(), native, stats);
     serve_https(opts.bind, app, tls).await
 }
 
@@ -110,10 +115,12 @@ fn app(
     token: Option<String>,
     port: u16,
     native: Option<Arc<crate::native_pairing::NativePairing>>,
+    stats: Arc<crate::stats_recorder::StatsRecorder>,
 ) -> Router {
     let shared = Arc::new(MgmtState {
         app: state,
         native,
+        stats,
         token,
         port,
     });
@@ -158,13 +165,19 @@ fn api_router_parts() -> (Router<Arc<MgmtState>>, utoipa::openapi::OpenApi) {
                 .routes(routes!(request_idr))
                 .routes(routes!(get_library))
                 .routes(routes!(create_custom_game))
-                .routes(routes!(update_custom_game, delete_custom_game)),
+                .routes(routes!(update_custom_game, delete_custom_game))
+                .routes(routes!(stats_capture_start))
+                .routes(routes!(stats_capture_stop))
+                .routes(routes!(stats_capture_status))
+                .routes(routes!(stats_capture_live))
+                .routes(routes!(stats_recordings_list))
+                .routes(routes!(stats_recording_get, stats_recording_delete)),
         )
         .split_for_parts()
 }
 
 /// The OpenAPI document as pretty JSON — what `punktfunk-host openapi` prints and what is
-/// checked in at `docs/api/openapi.json` for client codegen.
+/// checked in at `api/openapi.json` for client codegen.
 pub fn openapi_json() -> String {
     let (_, api) = api_router_parts();
     let mut json = api.to_pretty_json().expect("serialize OpenAPI document");
@@ -190,6 +203,7 @@ pub fn openapi_json() -> String {
         (name = "native", description = "Native punktfunk/1 pairing: arm a window, display the host PIN, manage paired devices"),
         (name = "session", description = "Active streaming session control"),
         (name = "library", description = "Game library: installed-store titles (Steam) plus user-curated custom entries"),
+        (name = "stats", description = "Streaming performance-stats capture: arm/stop a recording, read the live + saved time-series for graphing"),
     )
 )]
 struct ApiDoc;
@@ -1218,6 +1232,185 @@ async fn delete_custom_game(Path(id): Path<String>) -> Response {
     }
 }
 
+// ---------------------------------------------------------------------------------------
+// Streaming stats capture (design/stats-capture-plan.md §2)
+// ---------------------------------------------------------------------------------------
+
+/// Start a stats capture
+///
+/// Arms a new performance-stats capture. Idempotent: if a capture is already running this returns
+/// the current status unchanged. While armed, the streaming loops emit aggregated samples (~ every
+/// 1–2 s) into the in-progress capture, readable live via `GET /stats/capture/live`.
+#[utoipa::path(
+    post,
+    path = "/stats/capture/start",
+    tag = "stats",
+    operation_id = "statsCaptureStart",
+    responses(
+        (status = OK, description = "Capture armed (or already running)", body = StatsStatus),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+async fn stats_capture_start(State(st): State<Arc<MgmtState>>) -> Json<StatsStatus> {
+    let status = st.stats.start();
+    tracing::info!(
+        started_unix_ms = status.started_unix_ms,
+        "management API: stats capture armed"
+    );
+    Json(status)
+}
+
+/// Stop the stats capture
+///
+/// Disarms the in-progress capture and writes it to disk atomically, returning its summary. If
+/// nothing was recording, returns `204 No Content`.
+#[utoipa::path(
+    post,
+    path = "/stats/capture/stop",
+    tag = "stats",
+    operation_id = "statsCaptureStop",
+    responses(
+        (status = OK, description = "Capture stopped and saved", body = CaptureMeta),
+        (status = NO_CONTENT, description = "Nothing was recording"),
+        (status = INTERNAL_SERVER_ERROR, description = "Could not write the recording to disk", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+async fn stats_capture_stop(State(st): State<Arc<MgmtState>>) -> Response {
+    match st.stats.stop() {
+        Ok(Some(meta)) => {
+            tracing::info!(id = %meta.id, samples = meta.sample_count, "management API: stats capture saved");
+            (StatusCode::OK, Json(meta)).into_response()
+        }
+        Ok(None) => StatusCode::NO_CONTENT.into_response(),
+        Err(e) => api_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            &format!("could not save capture: {e}"),
+        ),
+    }
+}
+
+/// Stats capture status
+///
+/// Whether a capture is armed, its sample count, and start time. Poll this (e.g. every 2 s) to
+/// drive the capture-control UI.
+#[utoipa::path(
+    get,
+    path = "/stats/capture/status",
+    tag = "stats",
+    operation_id = "statsCaptureStatus",
+    responses(
+        (status = OK, description = "In-progress capture status (idle when not armed)", body = StatsStatus),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+async fn stats_capture_status(State(st): State<Arc<MgmtState>>) -> Json<StatsStatus> {
+    Json(st.stats.status())
+}
+
+/// Live in-progress capture
+///
+/// The full sample time-series of the capture currently recording, for live graphing. `404` when
+/// nothing is armed.
+#[utoipa::path(
+    get,
+    path = "/stats/capture/live",
+    tag = "stats",
+    operation_id = "statsCaptureLive",
+    responses(
+        (status = OK, description = "The in-progress capture (meta + samples so far)", body = Capture),
+        (status = NOT_FOUND, description = "No capture is currently recording", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+async fn stats_capture_live(State(st): State<Arc<MgmtState>>) -> Response {
+    match st.stats.live_snapshot() {
+        Some(capture) => Json(capture).into_response(),
+        None => api_error(StatusCode::NOT_FOUND, "no capture is currently recording"),
+    }
+}
+
+/// List saved recordings
+///
+/// Every saved capture's summary (the `meta` head only — not the sample body), newest first.
+#[utoipa::path(
+    get,
+    path = "/stats/recordings",
+    tag = "stats",
+    operation_id = "statsRecordingsList",
+    responses(
+        (status = OK, description = "Saved capture summaries, newest first", body = [CaptureMeta]),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+async fn stats_recordings_list(State(st): State<Arc<MgmtState>>) -> Json<Vec<CaptureMeta>> {
+    Json(st.stats.list())
+}
+
+/// Get a saved recording
+///
+/// The full capture (meta + samples) for `id`, for graphing or download.
+#[utoipa::path(
+    get,
+    path = "/stats/recordings/{id}",
+    tag = "stats",
+    operation_id = "statsRecordingGet",
+    params(("id" = String, Path, description = "The recording id (its filename stem)")),
+    responses(
+        (status = OK, description = "The full capture", body = Capture),
+        (status = NOT_FOUND, description = "No recording with that id", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+        (status = INTERNAL_SERVER_ERROR, description = "The recording file is unreadable", body = ApiError),
+    )
+)]
+async fn stats_recording_get(State(st): State<Arc<MgmtState>>, Path(id): Path<String>) -> Response {
+    match st.stats.load(&id) {
+        Ok(capture) => Json(capture).into_response(),
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
+            api_error(StatusCode::NOT_FOUND, "no recording with that id")
+        }
+        Err(e) => api_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            &format!("could not read recording: {e}"),
+        ),
+    }
+}
+
+/// Delete a saved recording
+///
+/// Removes the recording `id` from disk. `404` if there is no such recording.
+#[utoipa::path(
+    delete,
+    path = "/stats/recordings/{id}",
+    tag = "stats",
+    operation_id = "statsRecordingDelete",
+    params(("id" = String, Path, description = "The recording id (its filename stem)")),
+    responses(
+        (status = NO_CONTENT, description = "Recording deleted"),
+        (status = NOT_FOUND, description = "No recording with that id", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+        (status = INTERNAL_SERVER_ERROR, description = "Could not delete the recording", body = ApiError),
+    )
+)]
+async fn stats_recording_delete(
+    State(st): State<Arc<MgmtState>>,
+    Path(id): Path<String>,
+) -> Response {
+    match st.stats.delete(&id) {
+        Ok(()) => {
+            tracing::info!(id, "management API: recording deleted");
+            StatusCode::NO_CONTENT.into_response()
+        }
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
+            api_error(StatusCode::NOT_FOUND, "no recording with that id")
+        }
+        Err(e) => api_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            &format!("could not delete recording: {e}"),
+        ),
+    }
+}
+
 // ---------------------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------------------
@@ -1231,6 +1424,15 @@ mod tests {
     use std::net::{IpAddr, Ipv4Addr};
     use tower::ServiceExt;
 
+    /// A throwaway stats recorder rooted in a unique temp dir (never touches the real config dir).
+    fn test_stats() -> Arc<crate::stats_recorder::StatsRecorder> {
+        crate::stats_recorder::StatsRecorder::new(std::env::temp_dir().join(format!(
+            "pf-mgmt-stats-{}-{:p}",
+            std::process::id(),
+            &0u8 as *const u8
+        )))
+    }
+
     fn test_state() -> Arc<AppState> {
         let host = Host {
             hostname: "test-host".into(),
@@ -1240,18 +1442,20 @@ mod tests {
             https_port: HTTPS_PORT,
         };
         let identity = ServerIdentity::ephemeral().expect("ephemeral identity");
-        Arc::new(AppState::new(host, identity))
+        Arc::new(AppState::new(host, identity, test_stats()))
     }
 
     // The mgmt API now always requires auth, so the router always has a token. A test that passes
     // `None` gets the default "test-secret" (and `send` auto-attaches the matching bearer); a test
     // that passes an explicit token exercises a mismatch (e.g. `bearer_token_is_enforced`).
     fn test_app(state: Arc<AppState>, token: Option<&str>) -> Router {
+        let stats = state.stats.clone();
         app(
             state,
             Some(token.unwrap_or("test-secret").to_string()),
             DEFAULT_PORT,
             None,
+            stats,
         )
     }
 
@@ -1261,11 +1465,13 @@ mod tests {
     ) -> Router {
         // Auth required always; the paired-cert tests inject a fingerprint (cert branch wins), the
         // rest authenticate via the `send`-attached default bearer.
+        let stats = state.stats.clone();
         app(
             state,
             Some("test-secret".to_string()),
             DEFAULT_PORT,
             Some(np),
+            stats,
         )
     }
 
@@ -1580,7 +1786,9 @@ mod tests {
             bind: "127.0.0.1:0".parse().unwrap(),
             token: Some("   ".into()),
         };
-        let err = run(test_state(), opts, None).await.unwrap_err();
+        let err = run(test_state(), opts, None, test_stats())
+            .await
+            .unwrap_err();
         assert!(err.to_string().contains("no token"), "{err}");
     }
 
@@ -1663,14 +1871,14 @@ mod tests {
             serde_json::json!([{}])
         );
 
-        let checked_in = include_str!("../../../docs/api/openapi.json");
+        let checked_in = include_str!("../../../api/openapi.json");
         // Compare content, not line-ending style: the generated `json` is LF (serde_json), but git
         // may check the file out CRLF on Windows.
         assert_eq!(
             json.trim().replace('\r', ""),
             checked_in.trim().replace('\r', ""),
-            "docs/api/openapi.json is stale — regenerate with: \
-             cargo run -p punktfunk-host -- openapi > docs/api/openapi.json"
+            "api/openapi.json is stale — regenerate with: \
+             cargo run -p punktfunk-host -- openapi > api/openapi.json"
         );
     }
 

crates/punktfunk-host/src/session_plan.rs

@@ -0,0 +1,171 @@
+//! `SessionPlan` — the per-session capture / topology / encoder decision, resolved **once** from
+//! [`HostConfig`](crate::config) (+ the handshake-negotiated bit depth) into a typed, logged value.
+//!
+//! **Goal-1 stage 3** (`design/windows-host-rewrite.md` §2.2): before this, the Windows session decision was
+//! re-derived at three call sites — the capture backend inside `capture::capture_virtual_output`, the
+//! process topology in `punktfunk1::should_use_helper`, and the encode backend in
+//! `encode::windows_resolved_backend` — each reading [`config`](crate::config) independently, with no
+//! single owner (the latent "capture and encode disagree on the backend" hazard, plan §2.4). `SessionPlan`
+//! resolves them together, once, so the deployed path reads one typed artifact.
+//!
+//! Stage 3 routes the **capture** and **topology** decisions through the plan (see
+//! `capture::capture_virtual_output` taking [`CaptureBackend`] in, and `virtual_stream` reading
+//! [`SessionTopology`]). The **encoder** is resolved by `encode::windows_resolved_backend` (config-backed
+//! and GPU-vendor cached since stage 2, so already a single source) and *recorded* here as
+//! [`EncoderBackend`]. Threading `encoder`/`input_format` into the encoder + capturer opens — which
+//! removes the `capture → encode::windows_resolved_backend()` back-reference recomputed in `dxgi.rs` —
+//! is **stage 5**.
+//!
+//! The type is platform-neutral so it threads through the shared `virtual_stream`/`build_pipeline`
+//! signatures; on Linux it resolves to the single portal/single-process path (the 3-way dispatch is a
+//! Windows-only concern).
+
+/// Where a session's frames come from.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum CaptureBackend {
+    /// Linux: the xdg ScreenCast portal → PipeWire (the only Linux capture path).
+    Portal,
+    /// Windows: IDD direct-push — frames pulled straight from the pf-vdisplay driver's shared ring
+    /// (in-process, Session 0; no Desktop Duplication, no WGC helper).
+    IddPush,
+    /// Windows: DXGI Desktop Duplication (`PUNKTFUNK_CAPTURE=dda|dxgi` or `PUNKTFUNK_NO_WGC`).
+    Dda,
+    /// Windows: Windows.Graphics.Capture (the composed-desktop default), with a DDA watchdog fallback.
+    Wgc,
+}
+
+impl CaptureBackend {
+    /// Resolve the capture backend from [`config`](crate::config). This is the single resolver shared by
+    /// [`SessionPlan::resolve`] and the standalone callers (GameStream / spike), so they can't drift.
+    #[cfg(target_os = "linux")]
+    pub fn resolve() -> Self {
+        CaptureBackend::Portal
+    }
+
+    /// Windows precedence (identical to the pre-stage-3 `capture_virtual_output` branch order):
+    /// IDD-push wins; else an explicit `dda`/`dxgi` request or `PUNKTFUNK_NO_WGC` selects DDA; else WGC.
+    #[cfg(target_os = "windows")]
+    pub fn resolve() -> Self {
+        let cfg = crate::config::config();
+        if cfg.idd_push {
+            CaptureBackend::IddPush
+        } else if matches!(cfg.capture_backend.as_str(), "dda" | "dxgi")
+            || crate::capture::wgc_disabled()
+        {
+            CaptureBackend::Dda
+        } else {
+            CaptureBackend::Wgc
+        }
+    }
+
+    #[cfg(not(any(target_os = "linux", target_os = "windows")))]
+    pub fn resolve() -> Self {
+        CaptureBackend::Portal
+    }
+}
+
+/// How a session is structured across processes.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum SessionTopology {
+    /// One process captures + encodes (Linux; Windows non-SYSTEM / IDD-push / `NO_WGC`).
+    SingleProcess,
+    /// SYSTEM host + a user-session WGC helper relay (the Windows normal-desktop path under SYSTEM,
+    /// where in-process WGC can't activate). See `virtual_stream_relay`.
+    TwoProcessRelay,
+}
+
+/// The resolved encode backend (recorded for logging / stages 4–5; the per-session encoder open still
+/// resolves via `encode::windows_resolved_backend`, which is config-backed + GPU-vendor cached).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum EncoderBackend {
+    /// Linux: NVENC vs VAAPI is auto-detected inside `encode::open_video` (not modeled here).
+    PlatformAuto,
+    Nvenc,
+    Amf,
+    Qsv,
+    Software,
+}
+
+impl EncoderBackend {
+    /// True if this backend encodes on the GPU (so the capturer should produce GPU-resident frames). Only
+    /// the software encoder takes CPU staging; `PlatformAuto` (Linux NVENC/VAAPI) is always GPU.
+    pub fn is_gpu(self) -> bool {
+        !matches!(self, EncoderBackend::Software)
+    }
+}
+
+/// The per-session decision, resolved once. `Copy` so it threads through the capture/encode chain
+/// without ceremony (stage 4 folds it, with the rest of the arg soup, into a `SessionContext`).
+#[derive(Clone, Copy, Debug)]
+pub struct SessionPlan {
+    pub capture: CaptureBackend,
+    pub topology: SessionTopology,
+    pub encoder: EncoderBackend,
+    /// Handshake-negotiated encode bit depth (8, or 10 = HEVC Main10).
+    pub bit_depth: u8,
+    /// The IDD-push HDR hint (`bit_depth >= 10`) — the want-HDR flag the capturer was passed before.
+    /// Non-IDD-push Windows backends ignore it and auto-detect HDR from the monitor; Linux is 8-bit.
+    pub hdr: bool,
+}
+
+impl SessionPlan {
+    /// Resolve the whole plan once from [`config`](crate::config) + the negotiated `bit_depth`.
+    pub fn resolve(bit_depth: u8) -> Self {
+        SessionPlan {
+            capture: CaptureBackend::resolve(),
+            topology: resolve_topology(),
+            encoder: resolve_encoder(),
+            bit_depth,
+            hdr: bit_depth >= 10,
+        }
+    }
+
+    /// The capturer's target output format (Goal-1 stage 5): `gpu` from the already-resolved `encoder`
+    /// (no second backend probe), `hdr` from the plan. Handed into `capture::capture_virtual_output` so the
+    /// capturer never re-derives the encode backend.
+    pub fn output_format(&self) -> crate::capture::OutputFormat {
+        crate::capture::OutputFormat {
+            gpu: self.encoder.is_gpu(),
+            hdr: self.hdr,
+        }
+    }
+}
+
+/// Process topology. On Windows this is the former `punktfunk1::should_use_helper` logic verbatim; on
+/// every other platform the session is always single-process.
+#[cfg(target_os = "windows")]
+fn resolve_topology() -> SessionTopology {
+    let cfg = crate::config::config();
+    // `NO_HELPER`/`NO_WGC` force single-process; IDD-push captures in-process in Session 0 (no helper);
+    // otherwise the helper runs when forced or when we're SYSTEM (in-process WGC can't activate there).
+    let helper = if cfg.no_helper || crate::capture::wgc_disabled() || cfg.idd_push {
+        false
+    } else {
+        cfg.force_helper || crate::capture::wgc_relay::running_as_system()
+    };
+    if helper {
+        SessionTopology::TwoProcessRelay
+    } else {
+        SessionTopology::SingleProcess
+    }
+}
+
+#[cfg(not(target_os = "windows"))]
+fn resolve_topology() -> SessionTopology {
+    SessionTopology::SingleProcess
+}
+
+#[cfg(target_os = "windows")]
+fn resolve_encoder() -> EncoderBackend {
+    match crate::encode::windows_resolved_backend() {
+        crate::encode::WindowsBackend::Nvenc => EncoderBackend::Nvenc,
+        crate::encode::WindowsBackend::Amf => EncoderBackend::Amf,
+        crate::encode::WindowsBackend::Qsv => EncoderBackend::Qsv,
+        crate::encode::WindowsBackend::Software => EncoderBackend::Software,
+    }
+}
+
+#[cfg(not(target_os = "windows"))]
+fn resolve_encoder() -> EncoderBackend {
+    EncoderBackend::PlatformAuto
+}

crates/punktfunk-host/src/session_tuning.rs

@@ -9,7 +9,10 @@
 //! Raw C-ABI FFI (winmm/kernel32/dwmapi/avrt) rather than the `windows` crate so it builds without
 //! pulling new windows-rs features. No-op on non-Windows. Per-thread effects (MMCSS, execution
 //! state) auto-revert at thread exit (= session end); the process-wide bits revert at process exit.
-//! See `docs/host-latency-plan.md` Tier 3A.
+//! See `design/host-latency-plan.md` Tier 3A.
+
+// Every `unsafe` block in this file carries a `// SAFETY:` proof; enforce it (unsafe-proof program).
+#![deny(clippy::undocumented_unsafe_blocks)]
 
 #[cfg(target_os = "windows")]
 mod imp {
@@ -49,6 +52,10 @@ mod imp {
     /// Process-wide tuning, applied exactly once. Reverts at process exit. Best-effort: each call is
     /// independent and a failure is ignored (e.g. a non-elevated host may not get HIGH class).
     fn tune_process_once() {
+        // SAFETY: each call is a C-ABI FFI into winmm/kernel32/dwmapi declared with a matching
+        // `extern "system"` signature; every argument is a plain integer (no pointers/buffers escape),
+        // and `GetCurrentProcess()` returns the current-process pseudo-handle (a constant, always valid,
+        // never closed). The body runs inside `get_or_init`, so it executes exactly once per process.
         PROCESS_TUNED.get_or_init(|| unsafe {
             // 1 ms timer granularity (default ~15.6 ms) — the floor for precise frame pacing and the
             // encode|send split's sub-ms sleeps.
@@ -70,6 +77,11 @@ mod imp {
     /// thread exits, so a session that ends tears them down without explicit bookkeeping.
     pub fn on_hot_thread() {
         tune_process_once();
+        // SAFETY: C-ABI FFI declared with matching `extern "system"` signatures. SetThreadExecutionState
+        // takes only flag bits. `task` is a local NUL-terminated UTF-16 buffer ("Games\0") alive for the
+        // whole block, so `task.as_ptr()` is a valid LPCWSTR for the call, and `&mut idx` is a live local
+        // u32 the call writes the task index into. The returned MMCSS handle is intentionally leaked (the
+        // OS reverts the characteristics at thread exit), so there is nothing to free or double-free.
         unsafe {
             SetThreadExecutionState(ES_CONTINUOUS | ES_DISPLAY_REQUIRED | ES_SYSTEM_REQUIRED);
             let task: Vec<u16> = "Games\0".encode_utf16().collect();

crates/punktfunk-host/src/spike.rs

@@ -76,7 +76,12 @@ pub fn run(opts: Options) -> Result<()> {
                     refresh_hz: opts.fps,
                 })
                 .context("create virtual output")?;
-            capture::capture_virtual_output(vout).context("capture virtual output")?
+            capture::capture_virtual_output(
+                vout,
+                capture::OutputFormat::resolve(false),
+                crate::session_plan::CaptureBackend::resolve(),
+            )
+            .context("capture virtual output")?
         }
     };