chore(release): bump workspace version to 0.7.4

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.cargo/audit.toml

@@ -5,16 +5,46 @@
 # 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.
+# `unmaintained` warnings (audiopus_sys via opus, paste via utoipa-axum). Both are transitive, at
+# their latest published version with no successor, so there's nothing to bump — left visible on
+# purpose so we keep getting the maintenance signal; they do not fail CI. (rustls-pemfile was dropped
+# 2026-06-29 by removing axum-server's unused tls-rustls feature + moving our own PEM parsing to
+# rustls-pki-types; memmap2's unsoundness was fixed by the 0.9.11 bump.)
 
 [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.
+    # rsa "Marvin Attack" (RUSTSEC-2023-0071): a timing side-channel in the rsa crate's variable-time
+    # modular exponentiation of the SECRET exponent. IMPORTANT — this affects the RSA private-key op in
+    # general, INCLUDING signing (m^d mod n), which the host DOES perform (gamestream/pairing.rs
+    # `signing_key.sign(&serversecret)`). It is NOT, as an earlier version of this note wrongly claimed,
+    # limited to decryption — so "the vulnerable path isn't exercised" is false; signing exercises it.
+    # We accept it because the attack is not practically reachable here, NOT because the path is unused:
+    #   * No RSA decryption / PKCS#1v1.5 padding oracle exists anywhere (every `decrypt` in the tree is
+    #     AES/AES-GCM), so the classic Bleichenbacher/Marvin chosen-ciphertext oracle is absent.
+    #   * The only signed message (`serversecret`) is HOST-generated random, never attacker-chosen — so
+    #     there's no adaptive chosen-input probing (the lever remote RSA-timing key recovery needs); and
+    #     signing is gated behind the operator-entered pairing PIN, ONE signature per ceremony (a
+    #     repeated phase-3 is rejected — gamestream/pairing.rs — to deny a passive timing-sample harvester).
+    #   * GameStream is OFF by default (bare `serve` is native-only); the secure native QUIC plane uses
+    #     rustls' constant-time backend, NOT the rsa crate. RSA is touched only on the opt-in,
+    #     trusted-LAN GameStream/Moonlight pairing handshake. Moonlight mandates RSA-2048, so the
+    #     GameStream identity cannot move to Ed25519/ECDSA (only the native identity could, and it
+    #     already avoids the rsa crate).
+    # There is NO fixed rsa release (the constant-time rewrite is still unreleased upstream). Revisit if:
+    # a constant-time rsa ships (then drop this), the host ever signs an attacker-chosen message with
+    # this key, or any RSA decryption / key-transport using the private key is added.
     "RUSTSEC-2023-0071",
+
+    # quick-xml DoS advisories (RUSTSEC-2026-0194 quadratic-time duplicate-attribute check;
+    # RUSTSEC-2026-0195 unbounded namespace-declaration allocation in NsReader). Both are
+    # exploited by feeding attacker-controlled XML to a running parser. In this tree quick-xml is
+    # a BUILD-TIME-ONLY, transitive dependency of `wayland-scanner` (a proc-macro that parses the
+    # TRUSTED wayland protocol XML files shipped with the wayland-rs crates at compile time). It is
+    # never linked into any shipped binary and never parses runtime/attacker-controlled input, so
+    # neither DoS is reachable. There is no fix to bump to: wayland-scanner 0.31.10 (latest) pins
+    # `quick-xml ^0.39`, and the fixes only exist in quick-xml >=0.41. Revisit (drop these) when
+    # wayland-scanner releases against quick-xml >=0.41, or if quick-xml is ever pulled onto a
+    # runtime path that parses untrusted XML.
+    "RUSTSEC-2026-0194",
+    "RUSTSEC-2026-0195",
 ]

.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/ISSUE_TEMPLATE/config.yaml

@@ -0,0 +1,9 @@
+# Shown on the "new issue" chooser so security reports go to the private channel, not a public issue.
+blank_issues_enabled: true
+contact_links:
+  - name: 🔒 Report a security vulnerability
+    url: https://git.unom.io/unom/punktfunk/src/branch/main/SECURITY.md
+    about: >-
+      Found a security issue? Please report it privately by email to security@punktfunk.com — do not
+      open a public issue, so other users aren't exposed before a fix ships. See SECURITY.md for the
+      full policy.

.gitea/workflows/android-screenshots.yml

@@ -0,0 +1,57 @@
+# Android client screenshots for the Play listing / marketing. Roborazzi renders the real Compose
+# UI with mock state on the host JVM via Robolectric — NO emulator, GPU, KVM, host, or JNI core
+# (`-PskipRustBuild` skips the cargo-ndk native build). The Android analogue of apple.yml's
+# `screenshots` job, gated to STABLE RELEASE tags only. Standalone + best-effort: a failure here
+# reds nothing else. PNGs land as a 30-day artifact; not committed or published.
+name: android-screenshots
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  screenshots:
+    if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: JDK 21 (AGP 9.2 + Robolectric's SDK-36 android-all jar both want 17–21)
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "21"
+
+      - name: Android SDK
+        uses: android-actions/setup-android@v3
+
+      # No NDK/CMake — the screenshot unit tests are pure JVM. compileSdk 37 auto-downloads via AGP
+      # if the platform channel lacks it (same note as android.yml).
+      - name: platform-tools + platform 36 + build-tools
+        run: sdkmanager "platform-tools" "platforms;android-36" "build-tools;37.0.0"
+
+      - name: Cache (gradle)
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+          key: android-screenshots-${{ hashFiles('clients/android/**/*.gradle.kts') }}
+          restore-keys: android-screenshots-
+
+      # Roborazzi renders Compose on the JVM (Robolectric Native Graphics). `-PskipRustBuild` keeps
+      # the cargo-ndk native build out of the graph — the tests never load libpunktfunk_android.so.
+      - name: Capture screenshots (Roborazzi)
+        working-directory: clients/android
+        run: ./gradlew :app:testDebugUnitTest -PskipRustBuild --stacktrace
+
+      - name: Upload screenshots
+        if: always()
+        # v3: Gitea's API rejects upload-artifact@v4 (see apple.yml). Download is a zip.
+        uses: actions/upload-artifact@v3
+        with:
+          name: punktfunk-android-screenshots
+          path: clients/android/app/build/outputs/roborazzi
+          retention-days: 30

.gitea/workflows/android.yml

@@ -78,9 +78,10 @@ jobs:
       - name: Version + channel
         if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
         run: |
+          eval "$(bash scripts/ci/pf-version.sh)"   # -> PF_BASE (one minor ahead of the latest stable tag)
           case "$GITHUB_REF" in
             refs/tags/v*) VN="${GITHUB_REF_NAME#v}"; TRACK="alpha" ;;   # alpha = built-in closed testing
-            *)            VN="0.3.0-ci${GITHUB_RUN_NUMBER}"; TRACK="internal" ;;
+            *)            VN="${PF_BASE}-ci${GITHUB_RUN_NUMBER}"; TRACK="internal" ;;
           esac
           echo "VERSION_NAME=$VN" >> "$GITHUB_ENV"
           echo "PLAY_TRACK=$TRACK" >> "$GITHUB_ENV"

.gitea/workflows/apple.yml

@@ -32,6 +32,25 @@ jobs:
           dirname "$RUSTUP" >> "$GITHUB_PATH"
           "$RUSTUP" target add aarch64-apple-darwin x86_64-apple-darwin
 
+      # `punktfunk-core` now decodes Opus in-core for the Apple client (surround), pulling
+      # `audiopus_sys`, which builds a vendored static libopus via CMake when pkg-config can't find a
+      # system Opus — so the xcframework is self-contained (no runtime libopus.dylib on end-user Macs).
+      # CMake must be on PATH; install it self-healing on a fresh runner.
+      - name: CMake (for the vendored libopus audiopus_sys builds)
+        run: |
+          # Runner steps run with `bash --noprofile --norc`, so Homebrew's bin dir isn't on PATH —
+          # locate brew explicitly, install cmake if missing, and export its bin dir to GITHUB_PATH so
+          # the xcframework build step (audiopus_sys → vendored libopus) finds `cmake`.
+          for B in /opt/homebrew/bin/brew /usr/local/bin/brew; do [ -x "$B" ] && BREW="$B" && break; done
+          if [ -z "$BREW" ]; then echo "::error::Homebrew not found on the runner"; exit 1; fi
+          BREW_BIN="$(dirname "$BREW")"; export PATH="$BREW_BIN:$PATH"
+          command -v cmake >/dev/null || "$BREW" install cmake
+          echo "$BREW_BIN" >> "$GITHUB_PATH"
+          # Homebrew's CMake 4 dropped compatibility with the vendored libopus's pre-3.5
+          # `cmake_minimum_required`; treat 3.5 as the policy minimum (the cmake crate's child cmake
+          # inherits this from the env during the xcframework build).
+          echo "CMAKE_POLICY_VERSION_MINIMUM=3.5" >> "$GITHUB_ENV"
+
       - name: Build PunktfunkCore.xcframework
         run: bash scripts/build-xcframework.sh
 
@@ -71,6 +90,22 @@ jobs:
           "$RUSTUP" target add aarch64-apple-darwin x86_64-apple-darwin \
             aarch64-apple-ios aarch64-apple-ios-sim x86_64-apple-ios
 
+      # See the swift job: audiopus_sys (via the in-core Opus decode) builds vendored libopus with CMake.
+      - name: CMake (for the vendored libopus audiopus_sys builds)
+        run: |
+          # Runner steps run with `bash --noprofile --norc`, so Homebrew's bin dir isn't on PATH —
+          # locate brew explicitly, install cmake if missing, and export its bin dir to GITHUB_PATH so
+          # the xcframework build step (audiopus_sys → vendored libopus) finds `cmake`.
+          for B in /opt/homebrew/bin/brew /usr/local/bin/brew; do [ -x "$B" ] && BREW="$B" && break; done
+          if [ -z "$BREW" ]; then echo "::error::Homebrew not found on the runner"; exit 1; fi
+          BREW_BIN="$(dirname "$BREW")"; export PATH="$BREW_BIN:$PATH"
+          command -v cmake >/dev/null || "$BREW" install cmake
+          echo "$BREW_BIN" >> "$GITHUB_PATH"
+          # Homebrew's CMake 4 dropped compatibility with the vendored libopus's pre-3.5
+          # `cmake_minimum_required`; treat 3.5 as the policy minimum (the cmake crate's child cmake
+          # inherits this from the env during the xcframework build).
+          echo "CMAKE_POLICY_VERSION_MINIMUM=3.5" >> "$GITHUB_ENV"
+
       - name: Build PunktfunkCore.xcframework (mac + iOS slices)
         run: BUILD_IOS=1 bash scripts/build-xcframework.sh
 

.gitea/workflows/arch.yml

@@ -0,0 +1,142 @@
+# Build the punktfunk-host / punktfunk-client / punktfunk-web pacman packages from
+# packaging/arch/PKGBUILD and publish them to Gitea's Arch package registry, so Arch boxes
+# get new builds via `pacman -Syu`. Counterpart to deb.yml (apt) and rpm.yml (dnf/rpm-ostree).
+# Arch is rolling, so the packages build against whatever the archlinux:base-devel container
+# resolves today — the same sonames an up-to-date Arch box runs.
+#
+# Registry (public, unom org) — box setup (once), see packaging/arch/README.md. The registry
+# SIGNS the DB + packages, so the box imports the registry key first (pacman-key --add +
+# --lsign-key), then no SigLevel line is needed (pacman's default Required verifies):
+#   [punktfunk]                         # or [punktfunk-canary] for main-push builds
+#   Server = https://git.unom.io/api/packages/unom/arch/$repo/$arch
+#
+# REGISTRY_TOKEN: repo Actions secret, a PAT with write:package scope (shared with docker.yml).
+# NOTE: this token + the registry-held private key are the trust root — a token holder can
+# publish a validly-signed package (the signature attests "via the registry", not "built by CI").
+name: arch
+
+on:
+  push:
+    branches: [main]
+    # Single project version: a `vX.Y.Z` tag is THE release. main publishes to the
+    # `punktfunk-canary` pacman repo as X.Y.Z-0.<run#> (sorts below the eventual X.Y.Z-1),
+    # tags to `punktfunk` — separate repos, so neither channel can shadow the other.
+    tags: ['v*']
+  workflow_dispatch:
+
+env:
+  REGISTRY: git.unom.io
+  OWNER: unom
+
+jobs:
+  build-publish:
+    runs-on: ubuntu-24.04
+    container:
+      image: docker.io/library/archlinux:base-devel
+    timeout-minutes: 90
+    env:
+      CARGO_HOME: /usr/local/cargo
+    steps:
+      # git + nodejs must exist before actions/checkout — base-devel ships neither, and
+      # act_runner runs the action's JS with the CONTAINER's node, it does not inject one.
+      - name: Install build + runtime-dev deps
+        run: |
+          pacman -Syu --noconfirm --needed \
+            git nodejs rust clang cmake nasm pkgconf python \
+            gtk4 libadwaita sdl3 ffmpeg pipewire wayland libxkbcommon opus libei \
+            mesa libglvnd unzip libarchive
+          # bun builds the punktfunk-web console AND is vendored as its runtime (PF_WITH_WEB=1);
+          # it's AUR-only on Arch, so bootstrap the official binary.
+          command -v bun >/dev/null || {
+            curl -fsSL https://bun.sh/install | bash
+            install -m0755 "$HOME/.bun/bin/bun" /usr/local/bin/bun
+          }
+          bun --version
+
+      - uses: actions/checkout@v4
+
+      # Cache cargo's git dir too, not just the registry: the workspace includes
+      # clients/windows, whose windows-reactor/windows deps are git-pinned — cargo must CLONE
+      # them (windows-rs is huge) merely to resolve the workspace, even though nothing Windows
+      # is ever compiled here. Cached, that cost is paid once per runner.
+      - uses: actions/cache@v4
+        with:
+          path: |
+            /usr/local/cargo/registry
+            /usr/local/cargo/git
+          key: cargo-home-arch-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-home-arch-
+
+      - name: Version + channel
+        # vX.Y.Z tag -> X.Y.Z-1 in the `punktfunk` repo; main push -> <next-minor>-0.<run#> in
+        # `punktfunk-canary` (pkgrel accepts only digits+dots — the run number carries the
+        # monotonic ordering; the commit sha is stamped into the binary via the workflow log).
+        run: |
+          eval "$(bash scripts/ci/pf-version.sh)"   # -> PF_BASE (one minor ahead of latest stable)
+          case "$GITHUB_REF" in
+            refs/tags/v*) V="${GITHUB_REF_NAME#v}"; R="1";                       REPO=punktfunk ;;
+            *)            V="$PF_BASE";             R="0.${GITHUB_RUN_NUMBER}";  REPO=punktfunk-canary ;;
+          esac
+          echo "PF_PKGVER=$V" >> "$GITHUB_ENV"
+          echo "PF_PKGREL=$R" >> "$GITHUB_ENV"
+          echo "REPO=$REPO" >> "$GITHUB_ENV"
+          echo "pacman $V-$R -> repo '$REPO'"
+
+      - name: Build packages (makepkg)
+        run: |
+          git config --global --add safe.directory "$PWD"
+          # libcuda link stub — same trick as packaging/rpm/build-rpm.sh: the zerocopy FFI
+          # links -lcuda but the builder has no GPU; synthesize every cu* symbol the source
+          # references so a newly-added call can't silently break the link.
+          CU_SYMS="$(grep -rhoE '\bcu[A-Z][A-Za-z0-9_]*' crates/punktfunk-host/src/ | sort -u || true)"
+          if [ -n "$CU_SYMS" ] && [ ! -e /usr/lib/libcuda.so ]; then
+            STUB_C="$(mktemp --suffix=.c)"
+            for s in $CU_SYMS; do printf 'int %s(void){return 0;}\n' "$s" >> "$STUB_C"; done
+            gcc -shared -fPIC -Wl,-soname,libcuda.so.1 -o /usr/lib/libcuda.so.1 "$STUB_C"
+            ln -sf libcuda.so.1 /usr/lib/libcuda.so
+            rm -f "$STUB_C"; ldconfig
+            echo "== libcuda stub: $(printf '%s\n' "$CU_SYMS" | wc -l) symbols =="
+          fi
+          # makepkg refuses to run as root; deps are already installed above (-d skips the
+          # RPM-level check that can't see the script-installed bun anyway).
+          useradd -m builder
+          mkdir -p "$CARGO_HOME"   # actions/cache doesn't create it on a cache miss
+          chown -R builder: "$PWD" "$CARGO_HOME"
+          sudo -u builder git config --global --add safe.directory "$PWD"
+          mkdir -p dist && chown builder: dist
+          cd packaging/arch
+          sudo -u builder env PF_SRCDIR="$GITHUB_WORKSPACE" PF_WITH_WEB=1 \
+            PF_PKGVER="$PF_PKGVER" PF_PKGREL="$PF_PKGREL" \
+            CARGO_HOME="$CARGO_HOME" PKGDEST="$GITHUB_WORKSPACE/dist" \
+            makepkg -f -d --holdver
+          ls -lh "$GITHUB_WORKSPACE/dist"
+
+      - name: Publish to the Gitea Arch registry
+        env:
+          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          for pkg in dist/*.pkg.tar.zst; do
+            echo "uploading $pkg"
+            NAME=$(bsdtar -xOf "$pkg" .PKGINFO | sed -n 's/^pkgname = //p')
+            VER=$(bsdtar -xOf "$pkg" .PKGINFO | sed -n 's/^pkgver = //p')
+            ARCH=$(bsdtar -xOf "$pkg" .PKGINFO | sed -n 's/^arch = //p')
+            # A re-tagged release re-fires this workflow and the registry 409s on duplicate
+            # package versions — delete any prior copy first (404 on the first publish is fine).
+            curl -fsS -o /dev/null --user "enricobuehler:$TOKEN" -X DELETE \
+              "https://$REGISTRY/api/packages/$OWNER/arch/$REPO/$NAME/$VER/$ARCH" || true
+            curl -fsS --user "enricobuehler:$TOKEN" --upload-file "$pkg" \
+              "https://$REGISTRY/api/packages/$OWNER/arch/$REPO"
+          done
+          echo "published to $OWNER/arch/$REPO"
+
+      # On a real release, also attach the packages to the unified Gitea Release.
+      - name: Attach packages to the Gitea release (stable tags only)
+        if: startsWith(gitea.ref, 'refs/tags/v')
+        env:
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          . scripts/ci/gitea-release.sh
+          RID=$(ensure_release "$GITHUB_REF_NAME" "$GITHUB_REF_NAME" auto)
+          for pkg in dist/*.pkg.tar.zst; do
+            upsert_asset "$RID" "$pkg"
+          done

.gitea/workflows/deb.yml

@@ -36,16 +36,17 @@ jobs:
 
       - name: Version + channel
         # vX.Y.Z tag -> X.Y.Z, published to the `stable` apt distribution (a real release).
-        # A main push -> 0.3.0~ciN.g<sha>, published to the `canary` distribution: the '~' sorts
-        # below the eventual 0.3.0 tag, it climbs monotonically by run number, and the canary base
-        # stays one minor AHEAD of the latest stable so a stable->canary box re-point still moves
-        # forward (see channels.md). Computed BEFORE the build so it's stamped into the binary
+        # A main push -> <next-minor>~ciN.g<sha>, published to the `canary` distribution: the '~' sorts
+        # below the eventual tag, it climbs monotonically by run number, and the canary base is
+        # derived one minor AHEAD of the latest stable tag (scripts/ci/pf-version.sh) so a
+        # stable->canary box re-point still moves forward (see channels.md). Computed BEFORE the build so it's stamped into the binary
         # (PUNKTFUNK_BUILD_VERSION -> build.rs -> --version).
         run: |
+          eval "$(bash scripts/ci/pf-version.sh)"   # -> PF_BASE (one minor ahead of the latest stable tag)
           SHORT=$(echo "$GITHUB_SHA" | cut -c1-8)
           case "$GITHUB_REF" in
             refs/tags/v*) V="${GITHUB_REF_NAME#v}"; DIST=stable ;;
-            *)            V="0.3.0~ci${GITHUB_RUN_NUMBER}.g${SHORT}"; DIST=canary ;;
+            *)            V="${PF_BASE}~ci${GITHUB_RUN_NUMBER}.g${SHORT}"; DIST=canary ;;
           esac
           echo "VERSION=$V" >> "$GITHUB_ENV"
           echo "DISTRIBUTION=$DIST" >> "$GITHUB_ENV"
@@ -87,12 +88,13 @@ jobs:
           git config --global --add safe.directory "$PWD"
           cargo build --release -p punktfunk-host -p punktfunk-client-linux --locked
 
-      - name: Build + smoke-boot web console (node-server preset)
-        # Gate the .deb on a real node boot: the punktfunk-web .deb runs `node .output/server`,
-        # so prove the node-server build exists, isn't a bun bundle, and actually serves /login.
+      - name: Build + smoke-boot web console (bun preset)
+        # Gate the .deb on a real bun boot: the punktfunk-web .deb runs the Nitro `bun` preset
+        # (our Bun.serve TLS entry), so prove the build IS a bun bundle and serves /login.
+        # No TLS env here, so the custom entry binds plain HTTP — the smoke curl stays simple.
         run: |
-          # bun builds the console. It's baked into the rust-ci image, but bootstrap it here too so
-          # the job stays green against the PREVIOUS image (docker.yml bootstrap lag).
+          # bun builds AND runs the console. Baked into the rust-ci image; bootstrap here too so the
+          # job stays green against the PREVIOUS image (docker.yml bootstrap lag).
           command -v bun >/dev/null || {
             apt-get install -y --no-install-recommends unzip
             curl -fsSL https://bun.sh/install | bash
@@ -101,21 +103,23 @@ jobs:
           cd web
           bun install --frozen-lockfile
           bun run build
-          if grep -q 'Bun\.serve' .output/server/index.mjs; then
-            echo "ERROR: web build is a bun bundle (Bun.serve) — need the node-server preset"; exit 1
+          if ! grep -q 'Bun\.serve' .output/server/index.mjs; then
+            echo "ERROR: web build is not a bun bundle — need the 'bun' preset + custom entry"; exit 1
           fi
-          PORT=3009 HOST=127.0.0.1 PUNKTFUNK_UI_PASSWORD=ci node .output/server/index.mjs &
+          PORT=3009 HOST=127.0.0.1 PUNKTFUNK_UI_PASSWORD=ci bun .output/server/index.mjs &
           NP=$!; sleep 3
           code=$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3009/login || echo 000)
           kill "$NP" 2>/dev/null || true
           echo "web console smoke: /login -> $code"
-          [ "$code" = 200 ] || { echo "ERROR: web console failed to boot under node"; exit 1; }
+          [ "$code" = 200 ] || { echo "ERROR: web console failed to boot under bun"; exit 1; }
 
       - name: Build .debs
         run: |
+          export PATH="$HOME/.bun/bin:$PATH"
           VERSION="$VERSION" bash packaging/debian/build-deb.sh
           VERSION="$VERSION" bash packaging/debian/build-client-deb.sh
-          VERSION="$VERSION" bash packaging/debian/build-web-deb.sh
+          # Reuse CI's bun for the vendored runtime (matches the amd64 runner) instead of downloading.
+          VERSION="$VERSION" BUN_BIN="$(command -v bun || true)" bash packaging/debian/build-web-deb.sh
 
       - name: Publish to the Gitea apt registry
         env:
@@ -123,6 +127,14 @@ jobs:
         run: |
           for DEB in dist/*.deb; do
             echo "uploading $DEB"
+            # A re-tagged release re-fires this workflow and the apt registry 409s on duplicate
+            # package versions — delete any prior copy of this exact name/version/arch first
+            # (404 on the first publish is fine).
+            NAME=$(dpkg-deb -f "$DEB" Package)
+            VER=$(dpkg-deb -f "$DEB" Version)
+            ARCH=$(dpkg-deb -f "$DEB" Architecture)
+            curl -fsS -o /dev/null --user "enricobuehler:$TOKEN" -X DELETE \
+              "https://$REGISTRY/api/packages/$OWNER/debian/pool/$DISTRIBUTION/$COMPONENT/$NAME/$VER/$ARCH" || true
             # PAT owner (enricobuehler), not the push actor — matches docker.yml's registry login.
             curl -fsS --user "enricobuehler:$TOKEN" --upload-file "$DEB" \
               "https://$REGISTRY/api/packages/$OWNER/debian/pool/$DISTRIBUTION/$COMPONENT/upload"

.gitea/workflows/decky.yml

@@ -11,12 +11,18 @@
 #   punktfunk.zip
 #     punktfunk/                  <- single top-level dir == plugin.json "name"
 #       plugin.json   [required]
-#       package.json  [required]
+#       package.json  [required; CI stamps "version" — Decky reads the installed version here]
 #       main.py       [required: python backend]
 #       dist/index.js [required: rollup output]
+#       update.json   [CI-baked {channel, manifest}: where the plugin's self-update check polls]
 #       README.md     (recommended)
 #       LICENSE       [required by the plugin store]
 #
+# SELF-UPDATE (no Decky store): alongside the zip we also publish a tiny per-channel
+# `manifest.json` ({version, artifact=<immutable per-version zip URL>, sha256}). The installed
+# plugin polls it (main.py check_update), and the frontend drives Decky's own install RPC to
+# apply a newer build. See clients/decky/README.md "Updating".
+#
 # REGISTRY_TOKEN: repo Actions secret, a PAT with write:package scope (shared with deb/rpm/docker).
 name: decky
 
@@ -56,20 +62,30 @@ jobs:
           pnpm install --frozen-lockfile
           pnpm run build          # rollup -> clients/decky/dist/index.js
 
-      - name: Version + channel
-        # Tag vX.Y.Z -> X.Y.Z (stable `latest/` alias + Gitea Release); main push -> 0.3.0-ciN.g<sha>
-        # (`canary/` alias). Used for the registry version path + the zip name (the plugin.json
-        # version is the source of truth Decky reads after install — bump it in the release commit).
+      - name: Version + channel + stamp
+        # Tag vX.Y.Z -> X.Y.Z (stable `latest/` alias + Gitea Release); main push -> <next-minor>.<run>
+        # (base one minor ahead of the latest stable tag via scripts/ci/pf-version.sh)
+        # (`canary/` alias). Decky reads a plugin's INSTALLED version from package.json (NOT
+        # plugin.json), and the plugin's own update check (clients/decky/main.py check_update)
+        # compares against it — so the build version is STAMPED into package.json here (mirrored
+        # into plugin.json for store parity). Canary is a PLAIN numeric semver, never a
+        # `-ci<N>` prerelease: compare-versions orders prerelease identifiers lexically
+        # (ci10 < ci9), which would break update detection; the run number is monotonic.
         working-directory: ${{ gitea.workspace }}
         run: |
-          SHORT=$(echo "$GITHUB_SHA" | cut -c1-8)
+          eval "$(bash scripts/ci/pf-version.sh)"   # -> PF_MAJOR/PF_MINOR (base one minor ahead of latest stable)
           case "$GITHUB_REF" in
             refs/tags/v*) V="${GITHUB_REF_NAME#v}"; ALIAS=latest ;;
-            *)            V="0.3.0-ci${GITHUB_RUN_NUMBER}.g${SHORT}"; ALIAS=canary ;;
+            # Canary MUST be a plain monotonic numeric semver (see the note above): <major>.<minor>.<run>,
+            # where major.minor track one minor ahead of the latest stable and the run number climbs.
+            *)            V="${PF_MAJOR}.${PF_MINOR}.${GITHUB_RUN_NUMBER}"; ALIAS=canary ;;
           esac
+          BASE="https://$REGISTRY/api/packages/$OWNER/generic/$PACKAGE"
           echo "VERSION=$V" >> "$GITHUB_ENV"
           echo "ALIAS=$ALIAS" >> "$GITHUB_ENV"
+          echo "BASE=$BASE" >> "$GITHUB_ENV"
           echo "decky version $V -> alias '$ALIAS'"
+          VERSION="$V" node -e 'const fs=require("fs");for(const f of ["clients/decky/package.json","clients/decky/plugin.json"]){const j=JSON.parse(fs.readFileSync(f,"utf8"));j.version=process.env.VERSION;fs.writeFileSync(f,JSON.stringify(j,null,2)+"\n");}'
 
       - name: Assemble store-layout zip
         working-directory: ${{ gitea.workspace }}
@@ -89,9 +105,20 @@ jobs:
           chmod 0755 "$DEST/bin/punktfunkrun.sh"
           # Store requires a LICENSE in the plugin root; the project is MIT OR Apache-2.0.
           cp LICENSE-MIT                 "$DEST/LICENSE"
+          # Self-update channel pointer the backend reads (main.py check_update). It points at
+          # THIS channel's manifest.json (published below); that manifest in turn points at the
+          # immutable per-version zip, so its sha256 stays valid across future alias re-uploads.
+          printf '{"channel":"%s","manifest":"%s/%s/manifest.json"}\n' "$ALIAS" "$BASE" "$ALIAS" > "$DEST/update.json"
           ( cd "$STAGE" && zip -r "$RUNNER_TEMP/punktfunk.zip" "$PLUGIN" )
           ls -lh "$RUNNER_TEMP/punktfunk.zip"
           unzip -l "$RUNNER_TEMP/punktfunk.zip"
+          # The update manifest the plugin polls: the immutable per-version artifact + its
+          # sha256 (Decky's installer verifies the download against this hash, aborting on
+          # mismatch — so it MUST be the per-version URL, never the mutable alias).
+          SHA=$(sha256sum "$RUNNER_TEMP/punktfunk.zip" | cut -d' ' -f1)
+          printf '{"version":"%s","artifact":"%s/%s/punktfunk.zip","sha256":"%s"}\n' \
+            "$VERSION" "$BASE" "$VERSION" "$SHA" > "$RUNNER_TEMP/manifest.json"
+          cat "$RUNNER_TEMP/manifest.json"
 
       - name: Publish to the Gitea generic registry
         working-directory: ${{ gitea.workspace }}
@@ -99,18 +126,31 @@ jobs:
           TOKEN: ${{ secrets.REGISTRY_TOKEN }}
         run: |
           BASE="https://$REGISTRY/api/packages/$OWNER/generic/$PACKAGE"
-          # 1) Immutable, versioned URL.
+          # 1) Versioned URL + its update manifest (the manifest's `artifact` points here, so the
+          #    published sha256 keeps matching what Decky later downloads). A re-tagged release
+          #    re-fires this workflow and the registry 409s on duplicate uploads — delete any
+          #    prior copy of this version first (404 on the first publish is fine).
+          for f in punktfunk.zip manifest.json; do
+            curl -fsS -o /dev/null --user "enricobuehler:$TOKEN" -X DELETE "$BASE/$VERSION/$f" || true
+          done
           curl -fsS --user "enricobuehler:$TOKEN" --upload-file "$RUNNER_TEMP/punktfunk.zip" \
             "$BASE/$VERSION/punktfunk.zip"
+          curl -fsS --user "enricobuehler:$TOKEN" --upload-file "$RUNNER_TEMP/manifest.json" \
+            "$BASE/$VERSION/manifest.json"
           echo "published $BASE/$VERSION/punktfunk.zip"
-          # 2) Channel alias (stable release -> latest/, canary main build -> canary/) — the link
-          #    to paste into Decky's "install from URL". The generic registry rejects re-uploading
-          #    an existing version/file (409), so delete the prior alias first (ignore 404 on run #1).
-          curl -fsS -o /dev/null --user "enricobuehler:$TOKEN" -X DELETE \
-            "$BASE/$ALIAS/punktfunk.zip" || true
+          # 2) Channel alias (stable release -> latest/, canary main build -> canary/) — the
+          #    zip is the "install from URL" link; manifest.json is what the installed plugin
+          #    polls for updates. The generic registry rejects re-uploading an existing
+          #    version/file (409), so delete the prior alias copies first (ignore 404 on run #1).
+          for f in punktfunk.zip manifest.json; do
+            curl -fsS -o /dev/null --user "enricobuehler:$TOKEN" -X DELETE "$BASE/$ALIAS/$f" || true
+          done
           curl -fsS --user "enricobuehler:$TOKEN" --upload-file "$RUNNER_TEMP/punktfunk.zip" \
             "$BASE/$ALIAS/punktfunk.zip"
+          curl -fsS --user "enricobuehler:$TOKEN" --upload-file "$RUNNER_TEMP/manifest.json" \
+            "$BASE/$ALIAS/manifest.json"
           echo "install-from-URL link: $BASE/$ALIAS/punktfunk.zip"
+          echo "update manifest:       $BASE/$ALIAS/manifest.json"
 
       - name: Attach zip to the Gitea release (stable tags only)
         if: startsWith(gitea.ref, 'refs/tags/v')

.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/**'
@@ -73,15 +73,17 @@ jobs:
 
       - name: Version + channel
         # Tag vX.Y.Z -> X.Y.Z on the OSTree `stable` branch (a real release); a main push ->
-        # 0.3.0-ciN.g<sha> on the `canary` branch. The two branches live side-by-side in one repo
+        # <next-minor>-ciN.g<sha> on the `canary` branch (base one minor ahead of the latest stable
+        # tag via scripts/ci/pf-version.sh). The two branches live side-by-side in one repo
         # (rsync runs without --delete), each tracked by its own .flatpakref, so `flatpak update`
         # on a stable box never jumps to a canary build. The generic-registry version string allows
         # letters/dots/hyphens.
         run: |
+          eval "$(bash scripts/ci/pf-version.sh)"   # -> PF_BASE (one minor ahead of the latest stable tag)
           SHORT=$(echo "$GITHUB_SHA" | cut -c1-8)
           case "$GITHUB_REF" in
             refs/tags/v*) V="${GITHUB_REF_NAME#v}"; BRANCH=stable; ALIAS=latest ;;
-            *)            V="0.3.0-ci${GITHUB_RUN_NUMBER}.g${SHORT}"; BRANCH=canary; ALIAS=canary ;;
+            *)            V="${PF_BASE}-ci${GITHUB_RUN_NUMBER}.g${SHORT}"; BRANCH=canary; ALIAS=canary ;;
           esac
           echo "VERSION=$V" >> "$GITHUB_ENV"
           echo "BUNDLE=punktfunk-client-${V}.flatpak" >> "$GITHUB_ENV"
@@ -106,6 +108,40 @@ jobs:
           python3 /tmp/flatpak-cargo-generator.py /tmp/Cargo.flatpak.lock \
             -o packaging/flatpak/cargo-sources.json
 
+      - name: Seed the local OSTree repo from the live server (keep BOTH channels in the summary)
+        # Each CI run builds only ONE branch (canary on main, stable on a tag). The deploy step's
+        # `flatpak build-update-repo` regenerates the repo SUMMARY from whatever refs are in the
+        # LOCAL repo, and the rsync publishes it (without --delete). A fresh single-branch local
+        # repo therefore produces a single-branch summary that CLOBBERS the other channel on the
+        # server — the exact bug that made `app/io.unom.Punktfunk/x86_64/stable` unresolvable
+        # ("No such ref") after a canary main-push overwrote the post-release summary, even though
+        # the stable commit's objects were still on disk. Fix: mirror the published repo DOWN first,
+        # so the local repo carries every existing branch; the build below then only ADDS this run's
+        # commit and the regenerated+signed summary keeps both channels. No-op on a fresh repo (first
+        # publish) or when the deploy secrets aren't set (the build still produces a valid bundle).
+        env:
+          DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
+          DEPLOY_USER: ${{ secrets.DEPLOY_USER }}
+          DEPLOY_PORT: ${{ secrets.DEPLOY_PORT }}
+          DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
+        run: |
+          set -euo pipefail
+          if [ -z "${DEPLOY_HOST:-}" ] || [ -z "${DEPLOY_SSH_KEY:-}" ]; then
+            echo "::warning::DEPLOY_* not set — no seed; building a fresh single-branch repo."
+            exit 0
+          fi
+          install -d -m700 ~/.ssh
+          printf '%s\n' "$DEPLOY_SSH_KEY" > ~/.ssh/deploy; chmod 600 ~/.ssh/deploy
+          SSH="ssh -i $HOME/.ssh/deploy -p ${DEPLOY_PORT:-22} -o StrictHostKeyChecking=accept-new"
+          DEST="${DEPLOY_USER}@${DEPLOY_HOST}"
+          mkdir -p "$PWD/repo"
+          # Pull the currently-published repo (all channels' objects + refs) into the repo the build
+          # will extend. No --delete: the local repo starts empty, so this only ADDS. A missing
+          # server repo (very first publish) is fine — we continue with a fresh repo.
+          rsync -az --info=stats1 -e "$SSH" "$DEST:$DEPLOY_DIR/site/repo/" "$PWD/repo/" \
+            || echo "::warning::no published repo to seed (first publish?) — continuing fresh"
+          echo "seeded refs:"; ls "$PWD/repo/refs/heads/app/$APP_ID/x86_64/" 2>/dev/null || echo "  (none)"
+
       - name: Build the flatpak (install deps from Flathub, offline build)
         run: |
           # --install-deps-from=flathub pulls everything the manifest declares: the GNOME 50
@@ -133,7 +169,10 @@ jobs:
           TOKEN: ${{ secrets.REGISTRY_TOKEN }}
         run: |
           BASE="https://$REGISTRY/api/packages/$OWNER/generic/$PACKAGE"
-          # 1) Immutable, versioned URL.
+          # 1) Versioned URL. A re-tagged release re-fires this workflow and the registry 409s on
+          #    duplicate uploads — delete any prior copy first (404 on the first publish is fine).
+          curl -fsS -o /dev/null --user "enricobuehler:$TOKEN" -X DELETE \
+            "$BASE/$VERSION/$BUNDLE" || true
           curl -fsS --user "enricobuehler:$TOKEN" --upload-file "$BUNDLE" \
             "$BASE/$VERSION/$BUNDLE"
           echo "published $BASE/$VERSION/$BUNDLE"
@@ -174,6 +213,10 @@ jobs:
             --gpg-sign="$KEYID" --gpg-homedir="$GNUPGHOME"
           flatpak build-update-repo --generate-static-deltas \
             --gpg-sign="$KEYID" --gpg-homedir="$GNUPGHOME" "$PWD/repo"
+          # The regenerated summary advertises exactly these refs — must include EVERY channel that
+          # has ever published (the seed step ensures the other channel's commit is present). If this
+          # ever shows only one branch on a repo that had two, the seed didn't run — investigate.
+          echo "published summary advertises:"; ls "$PWD/repo/refs/heads/app/$APP_ID/x86_64/" 2>/dev/null || echo "  (none)"
           # 2) Build the install descriptors (GPGKey = the committed public key, base64).
           GPGKEY="$(base64 -w0 packaging/flatpak/unom-flatpak.gpg)"
           rm -rf site && mkdir -p site
@@ -185,9 +228,12 @@ jobs:
           Comment=unom Flatpak applications
           GPGKey=$GPGKEY
           EOF
-          # Two refs, one per channel — both regenerated every run and rsync'd without --delete, so
-          # the server always offers both (the stable ref only resolves once a release has built the
-          # `stable` branch). A box installs ONE; `flatpak update` then tracks that channel's branch.
+          # Two refs, one per channel. Both descriptor files are regenerated every run and rsync'd
+          # without --delete; the repo SUMMARY carries both branches because the build was seeded
+          # from the live repo above (so build-update-repo below re-signs a summary listing every
+          # published channel, not just this run's). The stable ref resolves for good once any
+          # release has built the `stable` branch. A box installs ONE; `flatpak update` then tracks
+          # that channel's branch.
           write_ref() {  # <filename> <branch> <title>
             cat > "site/$1" <<EOF
           [Flatpak Ref]

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

@@ -0,0 +1,67 @@
+# Native Linux client screenshots for the app/marketing listings. The client renders
+# host-free mock scenes (PUNKTFUNK_SHOT_SCENE) under a virtual X display; the driver
+# (clients/linux/tools/screenshots.sh) grabs each one — no host, GPU, or Wayland. The
+# Linux analogue of apple.yml's `screenshots` job, gated to STABLE RELEASE tags only.
+# Standalone + best-effort: a failure here reds nothing else. PNGs land as a 30-day
+# artifact; they are not committed or published.
+name: linux-client-screenshots
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  screenshots:
+    if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-24.04
+    # Same image as ci.yml/deb.yml — already carries the Rust toolchain + GTK/SDL build deps.
+    container:
+      image: git.unom.io/unom/punktfunk-rust-ci:latest
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v4
+
+      # Client link deps (baked into the image; kept here so the job is green across image
+      # rebuilds — a no-op once present) PLUS the headless-render extras: a virtual X server,
+      # software GL+Vulkan (llvmpipe/lavapipe), the icon theme + fonts the UI draws with, and a
+      # root-window grab tool.
+      - name: Client link + headless-render deps
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends \
+            libgtk-4-dev libadwaita-1-dev libsdl3-dev \
+            xvfb x11-utils imagemagick scrot \
+            libgl1-mesa-dri mesa-vulkan-drivers \
+            adwaita-icon-theme fonts-cantarell fonts-dejavu-core
+
+      # Reuse the workspace cargo caches (same keys as ci.yml/deb.yml).
+      - name: Cache keys
+        run: echo "rustc=$(rustc --version | cut -d' ' -f2)" >> "$GITHUB_ENV"
+      - uses: actions/cache@v4
+        with:
+          path: |
+            /usr/local/cargo/registry
+            /usr/local/cargo/git
+          key: cargo-home-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-home-
+      - uses: actions/cache@v4
+        with:
+          path: target
+          key: cargo-target-v3-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-target-v3-${{ env.rustc }}-
+
+      - name: Build client
+        run: cargo build --release -p punktfunk-client-linux --locked
+
+      - name: Capture screenshots
+        run: bash clients/linux/tools/screenshots.sh
+
+      - name: Upload screenshots
+        if: always()
+        # v3: Gitea's API rejects upload-artifact@v4 (see apple.yml). Download is a zip.
+        uses: actions/upload-artifact@v3
+        with:
+          name: punktfunk-linux-client-screenshots
+          path: clients/linux/screenshots
+          retention-days: 30

.gitea/workflows/release.yml

@@ -14,8 +14,12 @@
 # The macOS app is App-SANDBOXED for both channels (Config/Punktfunk-macOS.entitlements —
 # app-sandbox + network client/server + audio-input + bluetooth/usb device access; the
 # shared Config/Punktfunk.entitlements stays iOS/tvOS-only, where app-sandbox is invalid).
-# The Developer ID DMG is codesigned with the SAME macOS entitlements, so what we test
-# locally equals what App Store users get.
+# The Developer ID DMG is codesigned with the SAME macOS entitlements as the App Store build,
+# BUT it must ALSO embed a Developer ID provisioning profile: keychain-access-groups is a
+# MANAGED entitlement that AMFI only honors when an embedded profile authorizes it. A DMG
+# without one is SIGKILLed at spawn ("Launchd job spawn failed", POSIX errno 163) even though
+# it is validly signed AND notarized. ⌘R hides this (Xcode embeds a development profile); the
+# raw Developer ID codesign path does NOT, so ⌘R is NOT equivalent to the shipped DMG here.
 #
 # macOS App Store prerequisites (one-time, Apple portal — NOT done by this workflow; the
 # step is continue-on-error until they exist):
@@ -27,6 +31,15 @@
 #     the runner's login keychain, in addition to "Apple Distribution" — the App Store
 #     .pkg is installer-signed with it.
 #
+# macOS Developer ID (DMG) prerequisite (one-time, Apple portal — the DMG step embeds it):
+#   * A "Punktfunk macOS Developer ID" provisioning profile (Distribution -> Developer ID,
+#     App ID io.unom.punktfunk, with the Keychain Sharing capability) installed on the runner
+#     under ~/Library/Developer/Xcode/UserData/Provisioning Profiles/. It authorizes the
+#     managed keychain-access-groups entitlement; without it the DMG is SIGKILLed at launch
+#     (errno 163). If it is missing the DMG step warns and strips that entitlement (the app
+#     then uses ClientIdentityStore's legacy file-keychain fallback) so the build still ships
+#     a launchable app.
+#
 # Signing setup (NOT secret-based anymore): the runner is a LaunchAgent in the user's
 # logged-in Aqua session, so it uses the **login keychain** directly. Install the signing
 # identities there once via Xcode (Settings -> Accounts -> Manage Certificates): Developer
@@ -99,13 +112,14 @@ jobs:
 
       - name: Version from tag
         run: |
+          eval "$(bash scripts/ci/pf-version.sh)"   # -> PF_BASE, PF_CHANNEL, PF_STABLE_TAG (single source of truth)
           case "$GITHUB_REF" in
             refs/tags/v*) V="${GITHUB_REF_NAME#v}"; V="${V%%-*}" ;;  # App Store marketing version is numeric X.Y.Z (drop -rc)
-            *)            V="0.3.0" ;;                                # canary marketing version; the build number disambiguates
+            *)            V="$PF_BASE" ;;                             # canary marketing version = one minor ahead of the latest stable tag; the build number disambiguates
           esac
           echo "VERSION=$V" >> "$GITHUB_ENV"
           echo "BUILD_NUM=$GITHUB_RUN_NUMBER" >> "$GITHUB_ENV"
-          echo "version $V build $GITHUB_RUN_NUMBER"
+          echo "version $V build $GITHUB_RUN_NUMBER (channel $PF_CHANNEL, latest stable ${PF_STABLE_TAG})"
 
       - name: Rust toolchain (mac + iOS + tvOS slices)
         run: |
@@ -118,6 +132,23 @@ jobs:
           "$RUSTUP" toolchain install nightly --profile minimal
           "$RUSTUP" component add rust-src --toolchain nightly
 
+      # The in-core Opus decode (surround) pulls audiopus_sys, which builds a vendored static libopus
+      # via CMake — keep the xcframework self-contained (no runtime libopus.dylib on end-user devices).
+      - name: CMake (for the vendored libopus audiopus_sys builds)
+        run: |
+          # Runner steps run with `bash --noprofile --norc`, so Homebrew's bin dir isn't on PATH —
+          # locate brew explicitly, install cmake if missing, and export its bin dir to GITHUB_PATH so
+          # the xcframework build step (audiopus_sys → vendored libopus) finds `cmake`.
+          for B in /opt/homebrew/bin/brew /usr/local/bin/brew; do [ -x "$B" ] && BREW="$B" && break; done
+          if [ -z "$BREW" ]; then echo "::error::Homebrew not found on the runner"; exit 1; fi
+          BREW_BIN="$(dirname "$BREW")"; export PATH="$BREW_BIN:$PATH"
+          command -v cmake >/dev/null || "$BREW" install cmake
+          echo "$BREW_BIN" >> "$GITHUB_PATH"
+          # Homebrew's CMake 4 dropped compatibility with the vendored libopus's pre-3.5
+          # `cmake_minimum_required`; treat 3.5 as the policy minimum (the cmake crate's child cmake
+          # inherits this from the env during the xcframework build).
+          echo "CMAKE_POLICY_VERSION_MINIMUM=3.5" >> "$GITHUB_ENV"
+
       - 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
@@ -138,9 +169,8 @@ jobs:
         run: |
           # Archive UNSIGNED, then codesign with the Developer ID Application identity from the
           # login keychain. Unsigned archive sidesteps Xcode's keychain-access-groups
-          # provisioning-profile gate; codesign just needs the (now valid) identity + the
-          # team-prefixed entitlements, no profile (App Sandbox + the network/device
-          # capabilities are self-asserted for Developer ID — no profile entry needed).
+          # provisioning-profile gate at archive time; we re-assert that authorization below by
+          # EMBEDDING a Developer ID profile before codesign (see the keychain note further down).
           # Bundle is a single static binary.
           DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild archive \
             -project "$PROJECT" -scheme Punktfunk \
@@ -155,6 +185,35 @@ jobs:
           RESOLVED="$RUNNER_TEMP/macos.entitlements"
           sed "s/\$(AppIdentifierPrefix)/${TEAM_ID}./g" \
             clients/apple/Config/Punktfunk-macOS.entitlements > "$RESOLVED"
+
+          # keychain-access-groups is a MANAGED (restricted) entitlement: App Sandbox and the
+          # network/device keys are self-asserted for Developer ID, but a keychain access group
+          # must be AUTHORIZED by an embedded provisioning profile. Without one, AMFI refuses to
+          # spawn the sandboxed process at launch — "Launchd job spawn failed" (POSIX errno 163),
+          # SIGKILL before main() — even though the bundle is validly signed and notarized. Embed
+          # a "Developer ID" distribution profile for io.unom.punktfunk (Keychain Sharing) so its
+          # entitlements authorize the access group, exactly like the App Store build's profile
+          # does. Located by profile Name among the profiles installed on the runner (see header).
+          DEVID_PROFILE_NAME="Punktfunk macOS Developer ID"
+          PROFILE_SRC=""
+          for p in "$HOME/Library/Developer/Xcode/UserData/Provisioning Profiles/"*.provisionprofile \
+                   "$HOME/Library/MobileDevice/Provisioning Profiles/"*.provisionprofile; do
+            [ -e "$p" ] || continue
+            NAME=$(security cms -D -i "$p" 2>/dev/null | plutil -extract Name raw - 2>/dev/null || true)
+            [ "$NAME" = "$DEVID_PROFILE_NAME" ] && PROFILE_SRC="$p" && break
+          done
+          if [ -n "$PROFILE_SRC" ]; then
+            # Must land BEFORE codesign so it's sealed into the bundle.
+            cp "$PROFILE_SRC" "$APP/Contents/embedded.provisionprofile"
+            echo "embedded Developer ID profile: $PROFILE_SRC"
+          else
+            # Fallback so a missing/expired profile NEVER reships the errno-163 brick: drop the
+            # managed entitlement and let ClientIdentityStore fall back to the legacy file keychain
+            # (its errSecMissingEntitlement path). Degraded (one Keychain prompt) but launchable.
+            echo "::warning::Developer ID profile '$DEVID_PROFILE_NAME' not installed on the runner — stripping keychain-access-groups so the DMG still launches (legacy file keychain). Create it in the Apple portal + install it on the runner to restore the no-prompt data-protection keychain."
+            /usr/libexec/PlistBuddy -c "Delete :keychain-access-groups" "$RESOLVED" 2>/dev/null || true
+          fi
+
           codesign --force --options runtime --timestamp \
             --entitlements "$RESOLVED" \
             --sign "Developer ID Application" "$APP"
@@ -190,10 +249,20 @@ jobs:
         # (Config/Punktfunk-macOS.entitlements) — mandatory for the Mac App Store.
         continue-on-error: true
         run: |
-          # Separate archive from the Developer ID one above: App Store needs a profile-signed
-          # archive (manual signing), not the unsigned-then-codesign DMG path. Same App-Manager
-          # ASC-key constraint as iOS/tvOS — MANUAL signing, NOT -allowProvisioningUpdates
-          # (cloud signing the key can't do). Quit Xcode so it can't prune the dropped profile.
+          # Separate archive from the Developer ID one above: App Store needs a signed, entitled
+          # archive that -exportArchive can re-sign for distribution, not the unsigned-then-codesign
+          # DMG path. Archive with AUTOMATIC signing (development). Why not a manually-specified
+          # profile (as this step used to do): the in-app license screens added a SwiftPM resource
+          # bundle (PunktfunkKit_PunktfunkKit), and a resource bundle is a product type that cannot
+          # carry a provisioning profile — a global PROVISIONING_PROFILE_SPECIFIER (here) or an
+          # sdk-scoped one (iOS/tvOS) lands on it and fails the archive ("does not support
+          # provisioning profiles"). Automatic signing assigns a profile only to the app and leaves
+          # the resource bundle (and the macOS-host macro plugins) alone, and bakes the sandbox
+          # entitlements in. No -allowProvisioningUpdates → it stays OFFLINE and never cloud-signs
+          # (the App-Manager ASC key can't), so the runner must have a macOS *development* profile
+          # for io.unom.punktfunk installed. DISTRIBUTION signing happens in the export step below
+          # (manual, via the plist). Quit Xcode so it can't prune the manually-installed App Store
+          # distribution profile that export needs.
           osascript -e 'tell application "Xcode" to quit' >/dev/null 2>&1 || true
           pkill -x Xcode 2>/dev/null || true
           PROFILE="Punktfunk macOS App Store Distribution"
@@ -201,11 +270,10 @@ jobs:
             -project "$PROJECT" -scheme Punktfunk \
             -destination 'generic/platform=macOS' \
             -archivePath "$RUNNER_TEMP/Punktfunk-macos-appstore.xcarchive" \
+            -skipMacroValidation -skipPackagePluginValidation \
             MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM" \
-            CODE_SIGN_STYLE=Manual \
-            CODE_SIGN_IDENTITY="Apple Distribution" \
-            DEVELOPMENT_TEAM="$TEAM_ID" \
-            PROVISIONING_PROFILE_SPECIFIER="$PROFILE"
+            CODE_SIGN_STYLE=Automatic \
+            DEVELOPMENT_TEAM="$TEAM_ID"
           cat > "$RUNNER_TEMP/export-macos-appstore.plist" <<EOF
           <?xml version="1.0" encoding="UTF-8"?>
           <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -235,35 +303,27 @@ jobs:
         # Best-effort until the App Store Connect app record for io.unom.punktfunk exists.
         continue-on-error: true
         run: |
-          # MANUAL App Store signing: the local (valid) Apple Distribution identity + the App
-          # Store provisioning profile. NOT -allowProvisioningUpdates — with an App-Manager-role
-          # ASC key that forces Xcode's CLOUD-managed signing, which the role can't do ("Cloud
-          # signing permission error"). The profile must be installed on the runner under
-          # ~/Library/Developer/Xcode/UserData/Provisioning Profiles/ (install it once with
-          # Xcode.app quit, or it prunes the manually-dropped distribution profile).
-          # A running Xcode.app prunes unrecognized profiles from that dir — quit it so the App
-          # Store profile survives this build; headless xcodebuild doesn't need the GUI app.
+          # Archive with AUTOMATIC signing (development) — see the macOS App Store step for the full
+          # rationale. The SwiftPM resource bundle (PunktfunkKit_PunktfunkKit, added with the in-app
+          # license screens) builds for iphoneos, so even the sdk-scoped PROVISIONING_PROFILE_SPECIFIER
+          # this step used to set matched it and failed the archive ("does not support provisioning
+          # profiles"). Automatic signing profiles only the app and leaves the resource bundle (and
+          # the macOS-host macro plugins) alone. No -allowProvisioningUpdates → OFFLINE, never
+          # cloud-signs (the App-Manager ASC key can't), so the runner needs an iOS *development*
+          # profile for io.unom.punktfunk installed. DISTRIBUTION signing is the export step below
+          # (manual, via the plist). A running Xcode.app prunes unrecognized profiles — quit it so the
+          # manually-installed App Store distribution profile survives for export.
           osascript -e 'tell application "Xcode" to quit' >/dev/null 2>&1 || true
           pkill -x Xcode 2>/dev/null || true
           PROFILE="Punktfunk iOS App Store Distribution"
-          # Scope signing to the iOS device SDK via an xcconfig — see the tvOS step below for the
-          # full rationale. A global (CLI) profile specifier would also be forced onto the shared
-          # macOS-host SwiftPM macro plugins, which reject it and fail the archive; [sdk=iphoneos*]
-          # in an xcconfig lands it on the app/framework slices only.
-          SIGN_XCCONFIG="$RUNNER_TEMP/sign-ios.xcconfig"
-          cat > "$SIGN_XCCONFIG" <<XCCONF
-          CODE_SIGN_STYLE = Manual
-          DEVELOPMENT_TEAM = $TEAM_ID
-          CODE_SIGN_IDENTITY[sdk=iphoneos*] = Apple Distribution
-          PROVISIONING_PROFILE_SPECIFIER[sdk=iphoneos*] = $PROFILE
-          XCCONF
           DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild archive \
             -project "$PROJECT" -scheme Punktfunk-iOS \
             -destination 'generic/platform=iOS' \
             -archivePath "$RUNNER_TEMP/Punktfunk-ios.xcarchive" \
             -skipMacroValidation -skipPackagePluginValidation \
-            -xcconfig "$SIGN_XCCONFIG" \
-            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM"
+            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM" \
+            CODE_SIGN_STYLE=Automatic \
+            DEVELOPMENT_TEAM="$TEAM_ID"
           cat > "$RUNNER_TEMP/export-appstore.plist" <<EOF
           <?xml version="1.0" encoding="UTF-8"?>
           <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -295,33 +355,24 @@ jobs:
         # on the runner (xcodebuild -downloadPlatform tvOS).
         continue-on-error: true
         run: |
-          # Same manual App Store signing as iOS (the App-Manager ASC key can't cloud-sign).
+          # Archive with AUTOMATIC signing (development) — see the macOS App Store step. The SwiftPM
+          # resource bundle (PunktfunkKit_PunktfunkKit) builds for appletvos and rejected the
+          # sdk-scoped profile this step used to set; Automatic signing profiles only the app and
+          # leaves the resource bundle + the macOS-host macro plugins (OnceMacro/SwizzlingMacro/
+          # AssociationMacro) alone. No -allowProvisioningUpdates → OFFLINE, never cloud-signs (the
+          # App-Manager ASC key can't), so the runner needs a tvOS *development* profile for
+          # io.unom.punktfunk installed. DISTRIBUTION signing is the export step below (manual, plist).
           osascript -e 'tell application "Xcode" to quit' >/dev/null 2>&1 || true
           pkill -x Xcode 2>/dev/null || true
           PROFILE="Punktfunk tvOS App Store Distribution"
-          # Scope signing to the tvOS device SDK via an xcconfig. A global (CLI) profile specifier
-          # hits EVERY target, including the shared SwiftPM macro plugins (OnceMacro/SwizzlingMacro/
-          # AssociationMacro) which build for the macOS host and reject a provisioning profile
-          # ("<macro> does not support provisioning profiles"), failing the archive. Conditionals
-          # work only in an xcconfig (xcodebuild mis-parses a CLI "SETTING[sdk=..]=val"), and a
-          # command-line -xcconfig outranks target settings, so [sdk=appletvos*] puts the profile on
-          # the app/framework slices only — the macosx-host macros get nothing. (The macOS archive
-          # above is immune: its host-SDK macros are CODE_SIGNING_ALLOWED=NO, so a global specifier
-          # is ignored there.)
-          SIGN_XCCONFIG="$RUNNER_TEMP/sign-tvos.xcconfig"
-          cat > "$SIGN_XCCONFIG" <<XCCONF
-          CODE_SIGN_STYLE = Manual
-          DEVELOPMENT_TEAM = $TEAM_ID
-          CODE_SIGN_IDENTITY[sdk=appletvos*] = Apple Distribution
-          PROVISIONING_PROFILE_SPECIFIER[sdk=appletvos*] = $PROFILE
-          XCCONF
           DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild archive \
             -project "$PROJECT" -scheme Punktfunk-tvOS \
             -destination 'generic/platform=tvOS' \
             -archivePath "$RUNNER_TEMP/Punktfunk-tvos.xcarchive" \
             -skipMacroValidation -skipPackagePluginValidation \
-            -xcconfig "$SIGN_XCCONFIG" \
-            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM"
+            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM" \
+            CODE_SIGN_STYLE=Automatic \
+            DEVELOPMENT_TEAM="$TEAM_ID"
           cat > "$RUNNER_TEMP/export-tvos.plist" <<EOF
           <?xml version="1.0" encoding="UTF-8"?>
           <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

.gitea/workflows/rpm.yml

@@ -35,8 +35,10 @@ jobs:
         include:
           - image: punktfunk-fedora-rpm     # Fedora 43 == Bazzite base
             group: bazzite
+            fedver: 43
           - image: punktfunk-fedora44-rpm   # Fedora 44 == Fedora KDE spin
             group: fedora-44
+            fedver: 44
     container:
       image: git.unom.io/unom/${{ matrix.image }}:latest
     timeout-minutes: 90
@@ -53,6 +55,8 @@ jobs:
         run: |
           git config --global --add safe.directory "$PWD"
           dnf -y install gtk4-devel libadwaita-devel SDL3-devel
+          # sysext build (packaging/bazzite/build-sysext.sh): squashfs + SELinux labeling.
+          dnf -y install squashfs-tools cpio libselinux-utils selinux-policy-targeted
           # bun builds the punktfunk-web console (--with web). Baked into the image; install it
           # here too so the job stays green against the PREVIOUS image (docker.yml bootstrap note).
           command -v bun >/dev/null || {
@@ -68,16 +72,17 @@ jobs:
           restore-keys: cargo-home-
 
       - name: Version + channel
-        # vX.Y.Z tag -> X.Y.Z-1 in the base group (a real release); main push -> 0.3.0-0.ciN.g<sha>
-        # in the `<base>-canary` group, whose "0." release sorts below the eventual 0.3.0-1 yet
-        # climbs by run number. The canary base stays one minor ahead of the latest stable so a
-        # stable->canary box re-point still moves forward. The spec %build stamps
+        # vX.Y.Z tag -> X.Y.Z-1 in the base group (a real release); main push -> <next-minor>-0.ciN.g<sha>
+        # in the `<base>-canary` group, whose "0." release sorts below the eventual <next-minor>-1 yet
+        # climbs by run number. The canary base is derived one minor ahead of the latest stable tag
+        # (scripts/ci/pf-version.sh) so a stable->canary box re-point still moves forward. The spec %build stamps
         # PUNKTFUNK_BUILD_VERSION from these macros into the binary (--version provenance).
         run: |
+          eval "$(bash scripts/ci/pf-version.sh)"   # -> PF_BASE (one minor ahead of the latest stable tag)
           SHORT=$(echo "$GITHUB_SHA" | cut -c1-8)
           case "$GITHUB_REF" in
             refs/tags/v*) V="${GITHUB_REF_NAME#v}"; R="1"; GROUP="${{ matrix.group }}" ;;
-            *)            V="0.3.0"; R="0.ci${GITHUB_RUN_NUMBER}.g${SHORT}"; GROUP="${{ matrix.group }}-canary" ;;
+            *)            V="$PF_BASE"; R="0.ci${GITHUB_RUN_NUMBER}.g${SHORT}"; GROUP="${{ matrix.group }}-canary" ;;
           esac
           echo "PF_VERSION=$V" >> "$GITHUB_ENV"
           echo "PF_RELEASE=$R" >> "$GITHUB_ENV"
@@ -103,11 +108,40 @@ jobs:
           for rpm in dist/*.rpm; do
             case "$rpm" in *debuginfo*|*debugsource*) echo "skip $rpm"; continue;; esac
             echo "uploading $rpm"
+            # A re-tagged release re-fires this workflow and the rpm registry 409s on duplicate
+            # package versions — delete any prior copy of this exact name/version-release/arch
+            # first (404 on the first publish is fine).
+            NAME=$(rpm -qp --qf '%{NAME}' "$rpm" 2>/dev/null)
+            VR=$(rpm -qp --qf '%{VERSION}-%{RELEASE}' "$rpm" 2>/dev/null)
+            ARCH=$(rpm -qp --qf '%{ARCH}' "$rpm" 2>/dev/null)
+            curl -fsS -o /dev/null --user "enricobuehler:$TOKEN" -X DELETE \
+              "https://$REGISTRY/api/packages/$OWNER/rpm/$GROUP/package/$NAME/$VR/$ARCH" || true
             curl -fsS --user "enricobuehler:$TOKEN" --upload-file "$rpm" \
               "https://$REGISTRY/api/packages/$OWNER/rpm/$GROUP/upload"
           done
           echo "published to $OWNER/rpm/$GROUP"
 
+      # The no-layering Bazzite path: wrap the just-built host + web RPMs into a systemd-sysext
+      # image and publish it to the per-Fedora-major feed (punktfunk-sysext/f43[-canary], …) that
+      # `punktfunk-sysext install|update` reads. Same RPMs, same channels — just no rpm-ostree.
+      - name: Build the sysext image
+        run: |
+          bash packaging/bazzite/build-sysext.sh --version-id "${{ matrix.fedver }}" \
+            --out "dist-sysext/punktfunk-${PF_VERSION}-${PF_RELEASE}-x86-64.raw" \
+            dist/punktfunk-"${PF_VERSION}-${PF_RELEASE}"*.rpm \
+            dist/punktfunk-web-"${PF_VERSION}-${PF_RELEASE}"*.rpm
+
+      - name: Publish the sysext feed
+        env:
+          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          case "$GROUP" in
+            *-canary) FEED="f${{ matrix.fedver }}-canary"; KEEP=6 ;;  # rolling: bound the pile-up
+            *)        FEED="f${{ matrix.fedver }}";        KEEP=0 ;;  # stable: keep every release
+          esac
+          KEEP=$KEEP bash packaging/bazzite/publish-sysext-feed.sh "$FEED" \
+            "dist-sysext/punktfunk-${PF_VERSION}-${PF_RELEASE}-x86-64.raw"
+
       # On a real release, also attach the .rpms to the unified Gitea Release. Both Fedora bases
       # (bazzite=F43, fedora-44) build the SAME filename, so suffix the asset with the base to keep
       # both on the release; canary builds live in the `*-canary` rpm groups (no release page).
@@ -123,3 +157,6 @@ jobs:
             base="$(basename "$rpm" .rpm)"
             upsert_asset "$RID" "$rpm" "${base}.${{ matrix.group }}.rpm"
           done
+          for raw in dist-sysext/*.raw; do
+            upsert_asset "$RID" "$raw" "$(basename "$raw" .raw).f${{ matrix.fedver }}.raw"
+          done

.gitea/workflows/web-screenshots.yml

@@ -0,0 +1,53 @@
+# Management-console screenshots for the app/marketing listings. Captured from the
+# built Storybook with headless Chromium (web/tools/screenshots.mjs) — the page
+# stories render from fixtures, so no live mgmt API, login, or GPU is needed. This
+# is the web analogue of apple.yml's `screenshots` job, but gated to STABLE RELEASE
+# tags only (the console has no release workflow of its own — it ships inside the
+# host packaging). Best-effort: a standalone workflow, so a failure here reds
+# nothing else. PNGs land as a 30-day artifact; they are not committed or published.
+name: web-screenshots
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  screenshots:
+    if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-24.04
+    container:
+      image: oven/bun:1
+    timeout-minutes: 30
+    defaults:
+      run:
+        working-directory: web
+    steps:
+      # oven/bun ships neither git nor a real node (the driver runs under node), and
+      # the slim Debian base lacks a CA bundle — without it actions/checkout's HTTPS
+      # fetch dies with "Problem with the SSL CA cert" (same as ci.yml's web job).
+      - name: Install git + node + CA certs
+        working-directory: /
+        run: apt-get update && apt-get install -y --no-install-recommends ca-certificates git nodejs
+      - uses: actions/checkout@v4
+      # --ignore-scripts skips the prepare→codegen hook (mirrors ci.yml); run codegen
+      # explicitly since build-storybook has no prebuild hook of its own.
+      - name: Install dependencies
+        run: bun install --frozen-lockfile --ignore-scripts
+      - name: Generate API client + i18n messages
+        run: bun run codegen
+      # Pulls the matching Chromium build + the apt libs it needs (root in-container).
+      - name: Install Chromium
+        run: bunx playwright install --with-deps chromium
+      - name: Build Storybook
+        run: bun run build-storybook
+      - name: Capture screenshots
+        run: bun run screenshots
+      - name: Upload screenshots
+        if: always()
+        # v3: Gitea's API rejects upload-artifact@v4 (see apple.yml). Download is a zip.
+        uses: actions/upload-artifact@v3
+        with:
+          name: punktfunk-web-console-screenshots
+          path: web/screenshots
+          retention-days: 30

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

@@ -1,27 +0,0 @@
-# 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 (docs/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

@@ -1,9 +1,9 @@
-# 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 (docs/windows-host-rewrite.md, M0).
+# Windows driver workspace CI — runs on a self-hosted Windows runner (home-windows-runner-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-vdisplay-proto) on MSVC to prove it compiles cross-OS and the
+# 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.
@@ -18,15 +18,16 @@ on:
     branches: [main]
     paths:
       - '.gitea/workflows/windows-drivers.yml'
-      - 'crates/pf-vdisplay-proto/**'
+      - 'crates/pf-driver-proto/**'
       - 'packaging/windows/drivers/**'
   pull_request:
     paths:
       - '.gitea/workflows/windows-drivers.yml'
-      - 'crates/pf-vdisplay-proto/**'
+      - 'crates/pf-driver-proto/**'
       - 'packaging/windows/drivers/**'
 
-# Driver builds need the WDK on the runner (provision once via windows-drivers-provision.yml).
+# Driver builds need the WDK on the runner - the driver-build job below self-provisions it via
+# scripts/ci/ensure-windows-toolchain.ps1, a fast no-op once already present.
 
 jobs:
   probe-and-proto:
@@ -76,7 +77,7 @@ jobs:
           head "EWDK"
           Write-Host ("EWDKROOT = " + ($env:EWDKROOT ?? '<unset>'))
 
-          head "LLVM / clang (README pins 21.1.2 for wdk-sys bindgen)"
+          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" }
@@ -93,17 +94,17 @@ jobs:
           Write-Host ("CARGO_HOME     = " + ($env:CARGO_HOME ?? '<unset>'))
           Write-Host ("CARGO_TARGET_DIR (daemon) = " + ($env:CARGO_TARGET_DIR ?? '<unset>'))
 
-      - name: Build + test pf-vdisplay-proto (MSVC)
+      - 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-vdisplay-proto
-          cargo test  -p pf-vdisplay-proto
-          cargo clippy -p pf-vdisplay-proto --all-targets -- -D warnings
-          cargo fmt -p pf-vdisplay-proto -- --check
+          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-vdisplay-proto path-deps into a driver, and exposes the produced
+  # 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
@@ -119,21 +120,32 @@ jobs:
     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'
-      # wdk-sys bindgen layout tests overflow (E0080) on the runner's default LLVM (ToT/22-dev); point at
-      # the pinned LLVM 21.1.2 that windows-drivers-rs builds clean against (provisioned to C:\llvm-21).
-      LIBCLANG_PATH: 'C:\llvm-21\bin'
+      # 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 + LLVM 21.1.2 (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)
+      - name: Ensure Windows toolchain (WDK, FFmpeg, Inno Setup, ARM64 target)
+        # Shared self-provision step (also used by windows.yml/windows-msix.yml/windows-host.yml) so
+        # driver-build is self-sufficient on any windows-amd64 runner and never races a manually
+        # dispatched provisioning workflow landing on a different one. Path is relative to the job
+        # working-directory (packaging/windows/drivers). Near-noop once the toolchain is present.
+        run: ../../../scripts/ci/ensure-windows-toolchain.ps1
+      - name: cargo build the driver workspace (wdk-probe + wdk-iddcx + pf-vdisplay + gamepad drivers)
         # 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).
+        # pf-vdisplay (the real IddCx driver) + pf-umdf-util (the safe UMDF primitive layer) + the two
+        # gamepad drivers. pf-vdisplay linking proves the IddCx call sites resolve against IddCxStub
+        # end-to-end (M1 step 2 gate); the gamepad drivers prove pf-umdf-util's WDF dispatch links.
         run: cargo build -v
+      - name: cargo clippy the shipped drivers (-D warnings — enforces the unsafe-audit gates)
+        # The gamepad drivers' business logic is 100% safe (it moved onto pf-umdf-util, the audited
+        # unsafe layer); pf-vdisplay + wdk-iddcx are inherently FFI-bound but every `unsafe {}` carries a
+        # `// SAFETY:` proof. Both invariants are lint-gated (`unsafe_op_in_unsafe_fn` +
+        # `undocumented_unsafe_blocks`); this step keeps them from regressing. (wdk-probe is a
+        # toolchain-only probe crate and is excluded.)
+        run: cargo clippy -p pf-umdf-util -p pf-xusb -p pf-dualsense -p wdk-iddcx -p pf-vdisplay --all-targets -- -D warnings
+      - name: cargo fmt --check the safe-layer + gamepad drivers
+        run: cargo fmt -p pf-umdf-util -p pf-xusb -p pf-dualsense --check
       - name: Inspect /INTEGRITYCHECK (before) — expect FORCE_INTEGRITY set by wdk-build
         run: |
           # explicit --target (.cargo/config.toml) -> output under the triple subdir.

.gitea/workflows/windows-host.yml

@@ -1,8 +1,9 @@
 # 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
 # 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.
+# bun) from one signed setup.exe. Runs on a self-hosted windows-amd64 runner
+# (host mode; same MSVC/Windows-SDK/LLVM env as windows.yml — generic from unom/infra's
+# windows-runner/, FFmpeg/Inno Setup self-provision via the "Ensure Windows toolchain" step below).
 #
 # Why an installer and not MSIX (like the client): the host installs a LocalSystem SCM service that
 # CreateProcessAsUserW's into the interactive session for secure-desktop capture, and bundles a
@@ -15,17 +16,20 @@
 # Versioning (free-form; not MSIX's 4-part rule) — single project version:
 #   vX.Y.Z tag -> X.Y.Z   (THE release; published + stable `latest/` alias + attached to the
 #                          unified Gitea Release).
-#   main push / dispatch -> 0.3.<run_number>  (canary; `canary/` alias; climbs by run number).
+#   main push / dispatch -> <next-minor>.<run_number>  (canary; `canary/` alias; base one minor
+#                          ahead of the latest stable tag via scripts/ci/pf-version.ps1, run climbs).
 #
 # Signing reuses the client's MSIX_CERT_PFX_B64 / MSIX_CERT_PASSWORD secrets (CN=unom). Without them
 # 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.
 #
 # 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
+#  - NVENC (NVIDIA, direct SDK): nothing needed at build time — the entry points are resolved at
+#    RUNTIME from the driver's nvEncodeAPI64.dll (a link-time import would kill the binary on
+#    AMD/Intel-only boxes before main).
+#  - AMF/QSV (AMD/Intel, libavcodec): link-imports the FFmpeg libs from FFMPEG_DIR (the BtbN lgpl-shared
 #    tree the client uses; includes the *_amf/*_qsv encoders) and bundles its DLLs into the installer.
+#    lgpl-shared (not gpl-shared) keeps those bundled DLLs LGPL (we never use the GPL-only x264/x265).
 # CI never launches the exe, so no GPU is needed here — this is build + Windows clippy coverage only.
 name: windows-host
 
@@ -35,6 +39,7 @@ on:
     paths:
       - 'crates/punktfunk-host/**'
       - 'crates/punktfunk-core/**'
+      - 'crates/punktfunk-tray/**'
       - 'packaging/windows/**'
       - 'scripts/windows/**'
       - 'web/**'
@@ -56,6 +61,26 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Ensure Windows toolchain (WDK, FFmpeg, Inno Setup, ARM64 target)
+        shell: pwsh
+        run: ./scripts/ci/ensure-windows-toolchain.ps1
+
+      - 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: |
@@ -64,45 +89,59 @@ 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
+          # FFMPEG_DIR: the same BtbN lgpl-shared x64 tree the Windows CLIENT links against (provisioned
+          # by scripts/ci/provision-windows-punktfunk-extras.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
           }
+          # VBCABLE_DIR: the pinned official VB-CABLE package (provisioned by
+          # provision-windows-punktfunk-extras.ps1) -> pack-host-installer.ps1 bundles the
+          # streaming virtual microphone. Same daemon-env-or-fallback pattern as FFMPEG_DIR
+          # (the daemon env only refreshes on a runner-task restart).
+          if (-not $env:VBCABLE_DIR) {
+            "VBCABLE_DIR=C:\Users\Public\vbcable" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          }
+          $pf = & "$env:GITHUB_WORKSPACE/scripts/ci/pf-version.ps1"   # single source of truth: base is one minor ahead of the latest stable tag
           $v = if ($env:GITHUB_REF -like 'refs/tags/v*') {
             $env:GITHUB_REF_NAME -replace '^v', ''
           } else {
-            "0.3.$($env:GITHUB_RUN_NUMBER)"
+            # Canary: <major>.<minor>.<run> — major.minor track one minor ahead of stable, run climbs monotonically.
+            "$($pf.PF_MAJOR).$($pf.PF_MINOR).$($env:GITHUB_RUN_NUMBER)"
           }
           "HOST_VERSION=$v" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
           "PUNKTFUNK_BUILD_VERSION=$v" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
           Write-Output "host version $v"
 
-      - name: Generate NVENC import lib
-        shell: pwsh
-        run: |
-          & 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 + amf-qsv)
         shell: pwsh
         # 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)
+      - name: Build (release, status tray)
+        shell: pwsh
+        # The per-user notification-area companion the installer bundles (punktfunk-tray.exe).
+        run: cargo build --release -p punktfunk-tray
+
+      - name: Clippy (host + tray, 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,amf-qsv -- -D warnings
-
-      - name: Ensure Inno Setup
-        shell: pwsh
         run: |
-          if (-not (Test-Path 'C:\Program Files (x86)\Inno Setup 6\ISCC.exe') -and -not (Get-Command iscc -ErrorAction SilentlyContinue)) {
-            Write-Output "installing Inno Setup via choco"
-            choco install innosetup -y --no-progress
-          }
+          cargo clippy -p punktfunk-host --features nvenc,amf-qsv -- -D warnings; if ($LASTEXITCODE) { throw "host clippy" }
+          cargo clippy -p punktfunk-tray -- -D warnings; if ($LASTEXITCODE) { throw "tray clippy" }
+
+      - 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: Fetch portable bun runtime (build tool + bundled to run the console)
         shell: pwsh
@@ -142,8 +181,8 @@ jobs:
           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"
+          if (-not (Select-String -Path .output\server\index.mjs -Pattern 'Bun\.serve' -Quiet)) {
+            throw "web build is not a bun bundle - need the 'bun' preset + custom entry"
           }
           Pop-Location
           # Gate the installer on a real boot under the BUNDLED bun (the runtime it ships), serving /login.
@@ -174,9 +213,15 @@ jobs:
           # Check curl's exit code ourselves — a best-effort DELETE (404 on first run) must not abort.
           $PSNativeCommandUseErrorActionPreference = $false
           function Publish-File($f, $url) {
-            curl.exe -fsS --user "enricobuehler:$($env:REGISTRY_TOKEN)" --upload-file "$f" "$url"
-            if ($LASTEXITCODE -ne 0) { throw "upload failed ($LASTEXITCODE): $url" }
-            Write-Output "published $url"
+            # The generic registry makes a versioned path immutable and 409s a re-upload, so a tag
+            # re-run re-publishing the identical artifact must be tolerated as a no-op. (The channel
+            # alias below is delete-then-reuploaded and never 409s.) No curl -f, so we can read the
+            # status code instead of aborting on it.
+            $code = [int](curl.exe -sS -o NUL -w "%{http_code}" --user "enricobuehler:$($env:REGISTRY_TOKEN)" --upload-file "$f" "$url")
+            if ($LASTEXITCODE -ne 0) { throw "upload failed (curl exit $LASTEXITCODE): $url" }
+            if ($code -eq 409) { Write-Output "already published (409, immutable): $url"; return }
+            if ($code -lt 200 -or $code -ge 300) { throw "upload failed (HTTP $code): $url" }
+            Write-Output "published ($code): $url"
           }
           $files = @($env:HOST_SETUP_PATH, $env:HOST_CER_PATH) | Where-Object { $_ -and (Test-Path $_) }
           if (-not $files) { throw "pack produced no artifacts to publish" }

.gitea/workflows/windows-msix.yml

@@ -1,8 +1,9 @@
 # Build the punktfunk Windows client as signed MSIX packages (x64 + ARM64) and publish them to
 # Gitea's generic package registry, so Windows boxes can download + install a real package (Start
-# tile, clean install/uninstall) instead of a loose exe. Runs on the self-hosted Windows runner
-# (host mode; scripts/ci/setup-windows-runner.ps1) — the MSVC/WinUI/FFmpeg toolchain + the Windows
-# SDK's makeappx/signtool are baked into the runner's daemon env, same as windows.yml.
+# tile, clean install/uninstall) instead of a loose exe. Runs on a self-hosted windows-amd64
+# runner (host mode; the MSVC/WinUI toolchain comes from unom/infra's windows-runner/, FFmpeg
+# self-provisions via the "Ensure Windows toolchain" step below, same as windows.yml) — the
+# Windows SDK's makeappx/signtool are baked into the runner's daemon env.
 #
 # Both arches come off the ONE x64 runner: x86_64 natively, aarch64 cross-compiled (the x64 MSVC
 # toolset has the ARM64 cross compiler; the matrix points FFMPEG_DIR at the ARM64 FFmpeg tree). See
@@ -15,7 +16,8 @@
 #   vX.Y.Z tag -> X.Y.Z.0  (THE release; any -rc/+meta pre-release suffix is dropped for MSIX).
 #                Published to the generic registry + the stable `latest/` alias + attached to the
 #                unified Gitea Release alongside every other platform's artifact.
-#   main push / dispatch -> 0.3.<run_number>.0  (canary; climbs monotonically by run number).
+#   main push / dispatch -> <next-minor>.<run_number>.0  (canary; base is one minor ahead of the
+#                latest stable tag via scripts/ci/pf-version.ps1, run number climbs monotonically).
 #                Published to the generic registry + the `canary/` alias.
 # Both arches share the version; artifacts are arch-suffixed (..._x64.msix / ..._arm64.msix).
 #
@@ -62,6 +64,10 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Ensure Windows toolchain (WDK, FFmpeg, Inno Setup, ARM64 target)
+        shell: pwsh
+        run: ./scripts/ci/ensure-windows-toolchain.ps1
+
       - name: Configure + version
         shell: pwsh
         run: |
@@ -73,11 +79,13 @@ jobs:
           "CARGO_TARGET_DIR=${{ matrix.td }}" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
           "FFMPEG_DIR=${{ matrix.ffmpeg }}" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
           rustup target add ${{ matrix.target }}
+          $pf = & "$env:GITHUB_WORKSPACE/scripts/ci/pf-version.ps1"   # single source of truth: base is one minor ahead of the latest stable tag
           $parts = if ($env:GITHUB_REF -like 'refs/tags/v*') {
             # MSIX needs a purely-numeric 4-part version: drop any -rc/+meta pre-release suffix.
             (($env:GITHUB_REF_NAME -replace '^v', '') -replace '[-+].*$', '').Split('.')
           } else {
-            @('0', '3', $env:GITHUB_RUN_NUMBER)
+            # Canary: <major>.<minor>.<run>.0 — major.minor track one minor ahead of stable, run climbs monotonically.
+            @($pf.PF_MAJOR, $pf.PF_MINOR, $env:GITHUB_RUN_NUMBER)
           }
           while ($parts.Count -lt 4) { $parts += '0' }
           $v = ($parts[0..3] -join '.')
@@ -115,9 +123,15 @@ jobs:
           $files = @($env:MSIX_PATH, $env:MSIX_CER_PATH) | Where-Object { $_ -and (Test-Path $_) }
           if (-not $files) { throw "pack produced no artifacts to publish" }
           function Put($f, $url) {
-            curl.exe -fsS --user "enricobuehler:$($env:REGISTRY_TOKEN)" --upload-file "$f" "$url"
-            if ($LASTEXITCODE -ne 0) { throw "upload failed ($LASTEXITCODE): $url" }
-            Write-Output "published $url"
+            # The generic registry makes a versioned path immutable and 409s a re-upload, so a tag
+            # re-run re-publishing the identical artifact must be tolerated as a no-op. (The channel
+            # alias below is delete-then-reuploaded and never 409s.) No curl -f, so we can read the
+            # status code instead of aborting on it.
+            $code = [int](curl.exe -sS -o NUL -w "%{http_code}" --user "enricobuehler:$($env:REGISTRY_TOKEN)" --upload-file "$f" "$url")
+            if ($LASTEXITCODE -ne 0) { throw "upload failed (curl exit $LASTEXITCODE): $url" }
+            if ($code -eq 409) { Write-Output "already published (409, immutable): $url"; return }
+            if ($code -lt 200 -or $code -ge 300) { throw "upload failed (HTTP $code): $url" }
+            Write-Output "published ($code): $url"
           }
           foreach ($f in $files) {
             $name = Split-Path $f -Leaf

.gitea/workflows/windows.yml

@@ -1,5 +1,8 @@
-# Windows client CI — runs on the self-hosted Windows runner (home-windows-1, host mode; see
-# scripts/ci/setup-windows-runner.ps1). Build + clippy + fmt + test the WinUI 3 client
+# Windows client CI — runs on a self-hosted windows-amd64 runner (host mode; the generic runner +
+# toolchain come from unom/infra's windows-runner/; punktfunk's own extras - FFmpeg, WDK, Inno
+# Setup, the ARM64 rustup target - self-provision via the "Ensure Windows toolchain" step below, a
+# fast no-op once already present, so any runner with that label works with no manual dispatch
+# step first). Build + clippy + fmt + test the WinUI 3 client
 # (windows-reactor + D3D11/SwapChainPanel + WASAPI + SDL3).
 #
 # Two architectures from ONE x64 runner: x86_64-pc-windows-msvc natively and
@@ -61,6 +64,10 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Ensure Windows toolchain (WDK, FFmpeg, Inno Setup, ARM64 target)
+        shell: pwsh
+        run: ./scripts/ci/ensure-windows-toolchain.ps1
+
       - name: Configure + toolchain versions
         shell: pwsh
         run: |
@@ -68,9 +75,15 @@ jobs:
           # Per-arch short target root (dodges MAX_PATH; keeps the two legs from sharing target\).
           $td = if ('${{ matrix.target }}' -eq 'aarch64-pc-windows-msvc') { 'C:\t-a64' } else { 'C:\t' }
           "CARGO_TARGET_DIR=$td" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
-          # Per-arch FFmpeg import libs (the runner provisions both — setup-windows-runner.ps1).
+          # Per-arch FFmpeg import libs (provision-windows-punktfunk-extras.ps1 fetches both).
           $ff = if ('${{ matrix.target }}' -eq 'aarch64-pc-windows-msvc') { 'C:\Users\Public\ffmpeg-arm64' } else { 'C:\Users\Public\ffmpeg' }
           "FFMPEG_DIR=$ff" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          # $ff\bin on PATH too (not just FFMPEG_DIR, which only satisfies the linker): the test
+          # binary needs the actual DLLs to load at runtime. Set here rather than relying on the
+          # daemon's own env (project-env.ps1) - on a freshly cloned/registered runner the daemon
+          # starts before this job's "Ensure Windows toolchain" step ever writes that file, so its
+          # PATH doesn't include this yet on a first run (confirmed live: STATUS_DLL_NOT_FOUND).
+          "$ff\bin" | Out-File -FilePath $env:GITHUB_PATH -Append -Encoding utf8
           rustup target add ${{ matrix.target }}
           rustc --version
           cargo --version

.gitignore

@@ -13,6 +13,7 @@ clients/apple/PunktfunkCore.xcframework/
 clients/apple/.swiftpm/
 # Generated App Store screenshots (tools/screenshots.sh output; uploaded as a CI artifact)
 clients/apple/screenshots/
+clients/linux/screenshots/
 # Xcode per-user state
 xcuserdata/
 
@@ -30,3 +31,6 @@ xcuserdata/
 # Python bytecode (e.g. clients/android/ci tooling)
 __pycache__/
 *.pyc
+
+# Claude Code project instructions — local to each dev box, not part of the repo.
+CLAUDE.md

CLAUDE.md

@@ -1,342 +0,0 @@
-# CLAUDE.md — punktfunk
-
-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`.
-
-## Where the work stands
-
-- **Core (`punktfunk-core` + C ABI): complete and hardened.** FEC recovery, loopback-under-loss,
-  proptests, C ABI harness all green; 13 adversarial-review findings fixed +
-  regression-tested (`a913042`).
-- **GameStream host: working end-to-end with a stock Moonlight client.** Validated live
-  on this box: pairing (persists across restarts), serverinfo/applist (app catalog from
-  `~/.config/punktfunk/apps.json` → each entry picks a compositor + nested command), RTSP, ENet
-  control, audio, and video at the **client's native resolution and refresh** — the host
-  creates a per-session virtual output via per-compositor `VirtualDisplay` backends:
-  **KWin** (`zkde_screencast stream_virtual_output`, needs KWin ≥ 6.5.6 headless; >60 Hz via
-  custom modes), **gamescope** (spawned headless at WxH@Hz, its PipeWire node captured, needs
-  gamescope ≥ 3.16.22 — older deadlocks on PipeWire ≥ 1.6), **Mutter** (D-Bus
-  `RecordVirtual` virtual monitor; validated live on headless GNOME Shell 50, zero-copy),
-  **Sway/wlroots** (`swaymsg create_output` + custom mode, xdpw portal capture with a
-  managed chooser config; validated live on sway 1.11, zero-copy).
-  Performance work landed and measured: GPU **zero-copy** on all paths (tiled dmabuf →
-  EGL/GL → CUDA; LINEAR dmabuf → **Vulkan bridge** → CUDA → NVENC), auto 2-way NVENC
-  split-encode above ~1 Gpix/s (5K@240), infinite GOP + RFI keyframes (killed the periodic
-  freeze), encode|send thread split with `sendmmsg` batching. Stable 240 fps at 5120×1440.
-  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`).
-- **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**
-  (inexpressible in GameStream), host creates the native virtual output at the client's
-  requested mode. `punktfunk1-host` is a **persistent listener** (sessions back to back;
-  `--max-sessions`). QUIC datagrams carry the side planes, demuxed by first byte: input
-  0xC8 (incl. **gamepads** — incremental events accumulated into the uinput xpad), **Opus
-  audio** 0xC9 (48 kHz stereo, 5 ms, host→client), **rumble** 0xCA (host→client). **Trust:**
-  host serves its persistent identity (`~/.config/punktfunk/cert.pem`, shared with GameStream
-  pairing) and logs the SHA-256 fingerprint; clients pin it, established by a **SPAKE2 PIN pairing
-  ceremony** (host arms pairing and displays a 4-digit PIN; a PAKE binds both cert fingerprints so an
-  attacker gets one online guess, no offline dictionary attack) — PIN pairing is the default for new
-  hosts. **TOFU on first connect** (`endpoint::client_pinned`) stays as an explicit host opt-in
-  (`punktfunk1-host --allow-tofu` / `serve --open`, advertised as `pair=optional`) for fully trusted LANs;
-  clients only offer the TOFU "Trust" path for a host that advertised `pair=optional`, route every
-  other new host straight to the PIN ceremony, and on a pinned-fingerprint change force re-pairing
-  (no re-TOFU shortcut). Clients present persistent identities via QUIC client auth, the host stores
-  paired fingerprints (`punktfunk1-paired.json`) and gates sessions with `--require-pairing` (the
-  default; `--allow-tofu`/`--open` accept unpaired clients).
-  **LAN auto-discovery**: both `serve` and `punktfunk1-host` advertise the native service over
-  mDNS (`_punktfunk._udp`, `crate::discovery`) with TXT `proto`/`fp`(cert fingerprint to
-  pin)/`pair`(required|optional)/`id`; `punktfunk-probe --discover` lists hosts, Apple clients
-  browse the same service via NWBrowser (validated cross-LAN 2026-06-12).
-  **Mid-stream mode renegotiation**: `Reconfigure` on the still-open control stream — the
-  host rebuilds output+encoder at the new mode in ~90 ms while the data plane runs on
-  (validated live: one .h265 with 720p and 1080p segments). Measured on-box at 720p120: 1680/1680 frames, **p50 0.83 ms**
-  capture→…→reassembled; audio measured live (~200 pkts/s). A **wall-clock skew handshake**
-  (`ClockProbe`/`ClockEcho`, 8 NTP rounds after `Start`, `clock_offset_ns`) aligns the client to the
-  host clock, so that latency is now valid **cross-machine** (`skew_corrected=true`) — measured GNOME
-  box → dev box over the LAN: **p50 1.30 ms** (the −1.57 ms inter-box clock offset removed).
-  `punktfunk-probe` is the
-  working reference client (`--pin`, datagram counters, `--input-test` incl. gamepad).
-  The embeddable connector (`NativeClient`) exposes it all over the C ABI: `punktfunk_connect`
-  (pin/TOFU) + `next_au`/`next_audio`/`next_rumble`/`next_hidout`/`send_input`/
-  `send_rich_input`. **Client-negotiated virtual pad type**: the Hello carries a gamepad
-  preference byte (same trailing-byte back-compat pattern as the compositor), the Welcome
-  echoes the resolved backend — precedence: explicit client choice > `PUNKTFUNK_GAMEPAD`
-  env > uinput Xbox 360. Backends: **Xbox 360** (uinput / ViGEm), **Xbox One/Series** (the same
-  XInput backend with the One/Series USB identity for matching glyphs — no extra game-visible
-  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). 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`), 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). **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
-
-1. **Native clients — decode + present: macOS stage 1 done, first light achieved
-   (2026-06-10).** PunktfunkKit compiles and is tested on macOS (AnnexB → VideoToolbox →
-   `AVSampleBufferDisplayLayer`, GCMouse/GCKeyboard capture, `PunktfunkClient` app shell);
-   validated live Mac ↔ this box at 720p60 — vkcube on glass, input injected via gamescope
-   EIS. The app speaks the full ABI v2 trust surface: Keychain-persisted client identity
-   presented on every connect, SPAKE2 PIN pairing UI (host-card context menu + the trust
-   prompt's "Pair with PIN instead…"), TOFU fingerprint prompt. **Gamepads (2026-06-11):**
-   controller discovery + selection in Settings (`GamepadManager` — exactly one pad
-   forwarded as pad 0, auto or pinned; pad TYPE auto-resolves from the physical
-   controller, user-overridable), capture incl. DualSense touchpad/motion
-   (`GamepadCapture`/`GamepadWire`), feedback rendering (rumble → CoreHaptics; lightbar /
-   player LEDs / adaptive triggers → `GCDeviceLight`/`playerIndex`/
-   `GCDualSenseAdaptiveTrigger` via the table-driven `DualSenseTriggerEffect` parser).
-   Loopback-tested end to end (`PUNKTFUNK_TEST_FEEDBACK=1` scripted burst); DualSense
-   motion sign/scale derived, not yet live-verified. Tests: `swift test` in
-   `clients/apple` (unit + real-codec round trip),
-   `test-loopback.sh` (Swift client vs synthetic punktfunk1-hosts on loopback — runs on macOS;
-   includes the pairing ceremony + `--require-pairing` gate),
-   `RemoteFirstLightTests` (full pipeline over the LAN). See
-   [`clients/apple/README.md`](clients/apple/README.md). **Stage 2 presenter**
-   (`VTDecompressionSession` + `CAMetalLayer`) is built and live-validated on glass behind the opt-in
-   `punktfunk.presenter` flag (~11 ms p50 capture→present), to become the default after a few
-   resolution/HDR checks. Next: make stage 2 the default, glass-to-glass numbers via
-   `tools/latency-probe`, iOS/iPadOS/tvOS variants.
-   **Linux stage 1 done, first light 2026-06-12** (`clients/linux`, binary
-   `punktfunk-client`): GTK4/libadwaita shell linking `punktfunk-core` directly (no C ABI;
-   `NativeClient` is now `Sync` — mutexed plane receivers), mDNS host list, TOFU + SPAKE2
-   PIN dialogs (identity shared with client-rs), FFmpeg software HEVC decode (LOW_DELAY,
-   slice threads) → `GtkGraphicsOffload`-wrapped picture, PipeWire playback (mic-player
-   jitter ring inverted), SDL3 gamepad capture + rumble/lightbar feedback, keyboard via
-   exact inverse of the host VK table, absolute mouse + 120-unit scroll. Validated live
-   against `serve` on this box: 1080p60, steady 60 fps, capture→decoded p50
-   ≈6.4 ms (debug build). `--connect host[:port]` for scripting. **Swift-parity batch +
-   stage 1.5 (2026-06-12 evening)**: capture state machine (click-to-capture,
-   Ctrl+Alt+Shift+Q / focus-loss release, held-state flush), app-lifetime SDL gamepad
-   service (pad pin UI, auto type from the physical pad, DualSense touchpad/motion 0xCC +
-   raw-DS5-effects trigger/player-LED replay — needs a physical pad to live-verify), mic
-   uplink (validated live), per-host speed test, compositor pref, native-display mode
-   default, saved-hosts list, .deb + RPM-subpackage CI (deb.yml/rpm.yml). **VAAPI decode
-   → DRM-PRIME dmabuf → `GdkDmabufTexture`** (BT.709 color state; Tier-1 zero-copy on
-   Intel/AMD, `PUNKTFUNK_DECODER=software|vaapi` override) with a proven fallback ladder —
-   no VAAPI device (NVIDIA) or mid-session VAAPI error → software decode. **First AMD test
-   (Steam Deck) hit a green-screen bug, fixed:** FFmpeg's VAAPI export uses
-   `SEPARATE_LAYERS`, so NV12 arrives as two single-plane layers (R8 luma + GR88 chroma,
-   one shared fd); the mapper took `layers[0]` only → GTK got a luma-only R8 texture, chroma
-   read as 0 → green field / red whites. Fix derives the combined fourcc from the decoder
-   `sw_format` (→ `DRM_FORMAT_NV12`) and flattens all planes across all layers (mpv's
-   pattern); a first-frame descriptor dump logs the real layout. Awaiting Steam Deck
-   reconfirm. Next: the stage-2 raw-Wayland
-   presenter (wp_presentation feedback, tearing-control, Vulkan Video on NVIDIA) —
-   **wgpu/winit rejected** (no dmabuf import / presentation feedback / shortcuts-inhibit).
-   **Windows stage 1 done 2026-06-15** (`clients/windows`, binary
-   `punktfunk-client`): pure-Rust **WinUI 3** UI via **windows-reactor** (a declarative React-like
-   framework backed by WinUI; PR #4499 added the `SwapChainPanel` widget + `set_swap_chain`). The
-   video is a **`SwapChainPanel`** bound to a **D3D11 composition swapchain** (WARP fallback for
-   the GPU-less dev box; runtime-compiled fullscreen-triangle shaders, Contain-fit letterbox),
-   driven by reactor's per-frame `on_rendering`. **FFmpeg HEVC decode with a D3D11VA
-   zero-copy hardware path** (`gpu.rs` shares one D3D11 device — hardware+`VIDEO_SUPPORT`, WARP
-   fallback, multithread-protected — between the decoder and presenter; the decoder outputs
-   NV12/P010 `ID3D11Texture2D` array slices with `BIND_SHADER_RESOURCE` and the presenter samples
-   them via per-plane SRVs + YUV→RGB shaders — NV12/BT.709, P010/BT.2020-PQ; **software CPU decode
-   stays as the robust fallback**, auto-selected with a `DecoderPref` override). **HDR10**: the
-   client advertises 10-bit/HDR (Settings toggle), detects PQ in-band (`transfer == SMPTE2084`),
-   and flips the swapchain to `R10G10B10A2` + ST.2084 with HDR10 metadata. **WASAPI** render + mic
-   capture, **SDL3** gamepads (rumble/lightbar/DualSense), `mdns-sd` discovery, and the full trust
-   surface — all **in-app**: a polished WinUI shell (host cards w/ monogram + status pills,
-   `InfoBar` errors/hints, `ToggleSwitch` settings, status-chip stream HUD showing GPU/CPU decode +
-   HDR), host list (live mDNS + saved + manual), settings (resolution/refresh/decoder/bitrate/HDR/
-   mic), SPAKE2 PIN pairing screen, TOFU, pinned-fp-mismatch re-pair. **(D3D11VA + HDR present + the
-   GUI polish are written against the windows-rs/reactor APIs but not yet on-glass validated — the
-   dev VM is headless/WARP; needs the RTX box.)** **Stream input** is Win32 low-level hooks (`WH_KEYBOARD_LL`/`WH_MOUSE_LL`) — reactor
-   exposes no raw key/pointer events; native Windows VK + absolute mouse (client-rect Contain-fit) +
-   wheel, Ctrl+Alt+Shift+Q capture toggle. `--headless`/`--discover` keep CLI paths. Builds + clippy
-   + fmt green on **`x86_64-pc-windows-msvc` and `aarch64-pc-windows-msvc`** — the latter
-   **cross-compiled off the one x64 runner** (no ARM64 runner; the x64 MSVC toolset's ARM64 cross
-   compiler + a per-arch `FFMPEG_DIR` ARM64 tree, SDL3/libopus build-from-source cross-compile
-   cleanly), and both ship as signed MSIX (`windows-msix.yml` matrix → `..._x64.msix`/`..._arm64.msix`,
-   verified: ARM64 binaries + manifest arch). **windows-reactor is unpublished** (git
-   dep pinned to commit `b4129fcc`; `windows` pinned to the SAME commit so `IDXGISwapChain1` unifies
-   with `set_swap_chain`); its `build.rs` downloads the Win App SDK NuGets + needs `CARGO_WORKSPACE_DIR`
-   set (in the VM build env; `/temp`+`/winmd` gitignored). Gotcha: `CARGO_HOME` must be an ASCII path
-   — the `ü` in the dev box's username breaks SDL3's MSVC precompiled-header build. Next: **on-glass
-   validation** of the D3D11VA decode + HDR present + GUI on the RTX box (the dev VM is
-   headless/Session-0/WARP → the WinUI window + hardware decode need a real display+GPU: RDP or the
-   RTX box), then RAWINPUT relative-mouse pointer-lock and a per-host speed test in the UI.
-   **Android stage 1 done** (`clients/android`, Kotlin app + `native/` Rust JNI core linking
-   `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`), **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.
-2. **Sub-frame pipelining**: overlap encode and transmit within a frame. Requires a direct
-   NVENC SDK wrapper (libavcodec only emits whole AUs) — the next big latency lever (~2–4 ms
-   at high res).
-3. **punktfunk/1 protocol growth.** **Done:** unified host (`serve --gamestream` runs GameStream + the
-   punktfunk/1 QUIC host in one process; bare `serve` is the secure native-only default — GameStream is
-   opt-in, trusted-LAN only, security-review #5/#9) with native pairing driven over the mgmt API /
-   web console (`mod native_pairing`: arm-on-demand → display PIN, paired-device list).
-   **Done:** PIN pairing is the default, host-gated — the host requires pairing and advertises
-   `pair=required` unless opted out with `--allow-tofu`/`--open` (then `pair=optional`, accepts
-   unpaired clients); clients render TOFU only for a `pair=optional` host and force re-pairing on a
-   fingerprint change. **Done:** concurrent sessions — the accept loop spawns each session
-   (`--max-concurrent`, default 4, an NVENC bound), each with its own virtual output + encoder, sharing
-   the host-lifetime input/audio/mic services (shared-desktop multi-view on kwin/mutter/wlroots).
-   **Done:** delegated pairing approval (§8b-1) — an unpaired device shows up as a pending request in
-   the web console, one click approves + pins it. Next (see roadmap): gamescope multi-user isolation
-   (per-session input/audio = independent desktops); §8b-2 peer-push approval from a paired device's
-   own app.
-4. **GameStream host polish**: HDR/10-bit (needs HDR capture + metadata plumbing; `av1_nvenc
-   -highbitdepth 1` already encodes Main10 from 8-bit input on this box),
-   reconnect-at-new-mode robustness. AV1 negotiation and surround audio are implemented
-   and unit/live-capture tested — both still need a live Moonlight confirmation (select
-   AV1 in a stock client; a real 5.1/7.1 listen incl. FEC under loss).
-
-Box one-time setup is complete: udev rule + `input` group (gamepads validated live),
-gamescope 3.16.22 installed system-wide (no PATH override), gnome-shell installed (Mutter
-backend validated live). All three compositor backends are live-validated.
-
-## Build / test / run
-
-```sh
-cargo build --workspace          # green on Linux and macOS
-cargo test  --workspace          # unit + loopback + proptest + C ABI harness (~100 tests)
-cargo clippy --workspace --all-targets -- -D warnings
-cargo fmt --all --check
-
-cargo run -p loss-harness        # FEC loss-resilience sweep (no network needed)
-bash crates/punktfunk-core/tests/c/run.sh   # standalone C-ABI link + round-trip proof
-```
-
-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`).
-
-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
-build+typecheck; `docker.yml` builds+pushes the web/docs/rust-ci images (host and native
-clients are deliberately NOT containerized); `apple.yml` builds the xcframework and runs
-`swift build`/`swift test` on the `macos-arm64` host-mode runner (home-mac-mini-1,
-provisioned by `scripts/ci/setup-macos-runner.sh`). Per-client/host release workflows:
-`deb.yml`/`rpm.yml`/`flatpak.yml` (Linux client), `android.yml` (Google Play), `windows-msix.yml`
-(Windows client), `windows-host.yml` (Windows host installer), `release.yml` (Apple notarized DMG +
-TestFlight), `decky.yml` (Steam Deck plugin); Windows builds run on a self-hosted Windows runner.
-
-## Layout
-
-```
-crates/punktfunk-core/        protocol · FEC · crypto · quic (punktfunk/1 control plane, feature-gated)
-crates/punktfunk-host/
-  gamestream/             Moonlight compat: nvhttp · pairing · rtsp · control · stream · gamepad · apps
-  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)
-  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
-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,encode/ffmpeg_win,inject/gamepad_windows,audio/wasapi_*,service}.rs   Windows host backends
-web/                          TanStack web console over the mgmt API (status · devices · pairing)
-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/
-include/punktfunk_core.h      generated C header
-```
-
-## Design invariants — do not regress
-
-- **One core, linked everywhere.** Protocol/FEC/crypto live only in `punktfunk-core`, behind a
-  stable, versioned C ABI. `tokio`/`quinn` exist only behind the `quic` feature (control
-  plane); **no async on the per-frame path** — native threads only.
-- **Native client resolution, no scaling.** A session gets a virtual output at exactly the
-  client's WxH@Hz via the `VirtualDisplay` trait (`create(mode) → VirtualOutput { node_id,
-  remote_fd, preferred_mode, keepalive }`, RAII teardown). There is no cross-compositor
-  protocol for this — each compositor keeps its own backend.
-- **FEC is the wall-breaker.** GF(2⁸) (≤255 shards/block, Moonlight-compatible) and GF(2¹⁶)
-  Leopard (≤65535 shards/block) — punktfunk/1 negotiates the latter, removing the ~1 Gbps
-  ceiling.
-- **Core security hardening stays intact**: reassembler bounds attacker-controlled fields
-  before allocating (`ReassemblerLimits`); AES-GCM per-direction nonce salts + seq-as-AAD;
-  ABI `struct_size` checks. Regression tests exist — keep them green.
-- **PipeWire consumer discipline**: our capture streams set `node.dont-reconnect` and tear
-  down promptly on negotiation timeout — one wedged link head-blocks the daemon's shared
-  work queue system-wide.
-
-## Running on this box
-
-Headless QEMU VM (Ubuntu 26.04, kernel 7.0), passthrough RTX 5070 Ti (driver 595 **open**
-module — a kernel update silently drops it; reinstall `nvidia-driver-595-open`), no KMS
-scanout → KWin `--drm` impossible; everything renders offscreen via `renderD128`.
-
-```sh
-# compositor session (shell 1, or the systemd unit in scripts/): full headless Plasma.
-# The script sets XDG_MENU_PREFIX=plasma- & co. — without it plasmashell runs but the
-# launcher menu is EMPTY (no apps, no System Settings).
-bash scripts/headless/run-headless-kde.sh 1920x1080
-
-# host (shell 2): bare `serve` is native-only (secure default); add --gamestream for Moonlight compat.
-WAYLAND_DISPLAY=wayland-kde XDG_CURRENT_DESKTOP=KDE PUNKTFUNK_VIDEO_SOURCE=virtual \
-PUNKTFUNK_ZEROCOPY=1 cargo run -rp punktfunk-host -- serve --gamestream
-
-# punktfunk/1 native loopback test (no Moonlight needed; same env as serve, listener persists
-# across sessions — bound it with --max-sessions):
-cargo run -rp punktfunk-host -- punktfunk1-host --source virtual --seconds 10 --max-sessions 1
-cargo run -rp punktfunk-probe -- --mode 1280x720x120 --out /tmp/a.h265 --input-test  # + --pin HEX
-```
-
-Pinned crate facts: `ashpd` 0.13 + `pipewire` 0.9 (must match ashpd's) + `ffmpeg-next` 8.x
-(`ffmpeg-sys-next` auto-detects the system FFmpeg, so it builds against **FFmpeg 7.x/libavcodec 61
-or 8.x/libavcodec 62** — validated live on Ubuntu 26.04 (8) and Bazzite F43 (7.1); the zero-copy
-FFI also link-needs `libGL`/`libgbm`/`libcuda` at build time). Env knobs: `PUNKTFUNK_VIDEO_SOURCE=virtual|portal`,
-`PUNKTFUNK_COMPOSITOR=kwin|gamescope|mutter`, `PUNKTFUNK_ZEROCOPY=1`, `PUNKTFUNK_GAMESCOPE_APP=...`,
-`PUNKTFUNK_INPUT_BACKEND=...`, `PUNKTFUNK_PERF=1` (per-stage timing), `PUNKTFUNK_VIDEO_DROP=N` (FEC
-test), `PUNKTFUNK_FEC_PCT=N`, `PUNKTFUNK_DSCP=1` (opt-in DSCP/SO_PRIORITY media QoS on the data +
-GameStream video/audio sockets; no-op on the wire on Windows without a qWAVE policy).
-
-## Conventions
-
-- Rust 2021, `rustfmt` + `clippy -D warnings` clean before commit.
-- Match the surrounding code's comment density and naming.
-- Commit messages end with the Co-Authored-By trailer (see `git log`).
-- `pkill` caution on this box: match exact comm names (`pkill -x gamescope-wl`,
-  `pkill -x punktfunk-host`) — `pkill -f` self-matches the invoking shell.

CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing to punktfunk
+
+Thanks for your interest in contributing!
+
+## Licensing of contributions (inbound = outbound)
+
+punktfunk is dual-licensed under **MIT OR Apache-2.0**.
+
+> Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in
+> the work by you, as defined in the Apache-2.0 license, shall be dual licensed as **MIT OR
+> Apache-2.0**, without any additional terms or conditions.
+
+By opening a pull request you agree to license your contribution under these terms. This is the
+standard Rust-ecosystem "inbound = outbound" model; it keeps the project's licensing unambiguous
+(including the Apache-2.0 §5 contributor patent grant) and any future relicensing clean. You retain
+the copyright to your contributions.
+
+### Do not paste copyleft (or otherwise incompatibly-licensed) code
+
+The single thing that could poison the permissive license is **copied source from a copyleft
+project**. Several adjacent projects (Sunshine, Apollo, Moonlight) are GPL-3.0. You may study them
+and reimplement a *technique*, protocol, or wire format — those are not copyrightable — but **never
+paste their code**, and do not translate a GPL implementation line-by-line. When a comment credits
+prior art, make clear it is an independent reimplementation, not a copy. The same applies to any
+third party's code under a license incompatible with MIT/Apache.
+
+If you add a new third-party dependency, it must be permissive (MIT / Apache-2.0 / BSD / ISC / Zlib /
+Unicode-3.0 / etc.). `about.toml` holds the accepted-license allow-list; regenerate the attribution
+file with `scripts/gen-third-party-notices.sh` when the dependency tree changes.
+
+## Before you push
+
+```sh
+cargo fmt --all --check
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test  --workspace
+```
+
+Generated artifacts are checked in and CI fails on drift: `include/punktfunk_core.h` (cbindgen) and
+`api/openapi.json` (`cargo run -p punktfunk-host -- openapi`). Match the surrounding code's comment
+density and naming. Commit messages end with the `Co-Authored-By` trailer (see `git log`).
+
+See [`CLAUDE.md`](CLAUDE.md) for the full build/test/run guide and design invariants.

Cargo.toml

@@ -3,7 +3,9 @@ resolver = "2"
 members = [
     "crates/punktfunk-core",
     "crates/punktfunk-host",
-    "crates/pf-vdisplay-proto",
+    "crates/punktfunk-host/vendor/usbip-sim",
+    "crates/punktfunk-tray",
+    "crates/pf-driver-proto",
     "clients/probe",
     "clients/linux",
     "clients/windows",
@@ -11,9 +13,11 @@ members = [
     "tools/latency-probe",
     "tools/loss-harness",
 ]
+# Standalone PoC (built on its own; pulls usbip/tokio/libusb we don't want in the workspace).
+exclude = ["packaging/linux/steam-deck-gadget/usbip-poc"]
 
 [workspace.package]
-version = "0.0.1"
+version = "0.7.4"
 edition = "2021"
 rust-version = "1.82"
 license = "MIT OR Apache-2.0"

README.md

@@ -1,13 +1,23 @@
-# 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/)**.
+
+🔒 **Security:** found a vulnerability? Report it privately to **security@punktfunk.com** — see
+[SECURITY.md](SECURITY.md). Please don't open a public issue.
+
 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,9 +29,16 @@ 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.
+  than throughput. Stable 240 fps at 5120×1440; sub-millisecond capture-to-reassembly on-box,
+  ~1.3 ms cross-machine on a LAN. (AMD/Intel encode via VAAPI, and a GPU-less software H.264
+  encoder exists as a fallback.)
 - **Works with what you already have.** Any Moonlight/Artemis client connects over GameStream — and
   native apps for macOS, Linux, Windows, and Android use the lower-latency `punktfunk/1` protocol.
 - **Secure by default.** Hosts require a one-time SPAKE2 **PIN pairing**; after that, devices
@@ -35,19 +52,19 @@ 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** (Windows 11 22H2+, x64) | 🟡 Implemented & shipping as a signed installer: DXGI/WGC capture · its own all-Rust IddCx **virtual display** (secure-desktop capable) · GPU encode (NVENC on NVIDIA, AMF/QSV on AMD/Intel, software H.264 without a GPU) · WASAPI audio · bundled virtual-gamepad drivers (no ViGEmBus) · HDR incl. Vulkan-game HDR. NVIDIA live-validated; AMD/Intel CI-green |
 | **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 |
-| **Windows client** (`clients/windows`, WinUI 3) | 🟡 Stage 1 complete, ships as signed MSIX (x64 + ARM64); D3D11VA decode + HDR present pending on-glass validation |
-| **Web console + management API** (`web/`) | ✅ TanStack console over the OpenAPI mgmt API: host status, paired devices, on-demand PIN pairing |
+| **Android client** (`clients/android`, phone + TV) | ✅ Streaming live: AMediaCodec decode + HDR10, AAudio audio, controllers, discovery, pairing |
+| **Windows client** (`clients/windows`, WinUI 3) | ✅ Streaming live: D3D11VA hardware decode on all GPU vendors (NVIDIA + Intel validated on glass) with software fallback, WASAPI audio, SDL3 controllers, discovery, pairing; ships as signed MSIX (x64 + ARM64). HDR10 implemented, on-glass validation pending |
+| **Web console + management API** (`web/`) | ✅ TanStack console over the OpenAPI mgmt API: host status, paired devices, on-demand PIN pairing, GPU selection, performance capture graphs, live host logs |
 
 The **GameStream host works with a stock Moonlight client** — validated live on NVIDIA hardware
 (RTX 5070 Ti, RTX 4090): PIN pairing that persists across restarts, an app catalog, RTSP/ENet/audio,
 and **video at the client's exact resolution and refresh** via a per-session virtual output (KWin,
 gamescope, Mutter, and Sway/wlroots backends), encoded with GPU **zero-copy** (dmabuf → CUDA/Vulkan →
 NVENC) up to 5120×1440@240. The native **`punktfunk/1`** protocol adds a QUIC control plane and a
-GF(2¹⁶) Leopard-FEC + AES-GCM data plane (p50 ~0.8 ms capture→reassembled at 720p120), with
+GF(2¹⁶) Leopard-FEC + AES-GCM data plane (p50 ~0.8 ms capture→received at 720p120), with
 mid-stream mode renegotiation and a wall-clock skew handshake so latency stays valid across machines.
 Both run from **one process**: bare `punktfunk-host serve` is the **secure native-only default**
 (`punktfunk/1` + the management API/web console), and `serve --gamestream` additionally enables the
@@ -61,14 +78,15 @@ 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) |
+| **Bazzite / Fedora Atomic** (systemd-sysext) | `sudo bash punktfunk-sysext.sh install` *(no layering, no reboot; rpm-ostree + bootc also supported)* | [Bazzite](https://docs.punktfunk.unom.io/docs/bazzite) |
+| **Fedora** (dnf) | `dnf install punktfunk punktfunk-web` *(after adding the repo)* | [Fedora — KDE](https://docs.punktfunk.unom.io/docs/fedora-kde) |
+| **Arch / Steam Deck** (pacman / sysext) | `pacman -Sy punktfunk-host` *(binary repo)* · sysext `.raw` *(SteamOS)* | [packaging/arch](packaging/arch/README.md) |
+| **Windows** (11 22H2+, 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,18 +131,17 @@ 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)
   windows/  Windows desktop app (Rust · WinUI 3 · D3D11 · WASAPI · SDL3)
-  android/  Android phone + TV app (Kotlin · Rust JNI core · AMediaCodec · Oboe)
+  android/  Android phone + TV app (Kotlin · Rust JNI core · AMediaCodec · AAudio)
   probe/    headless reference / measurement client for punktfunk/1
   decky/    Steam Deck Decky plugin
-web/                         web console (TanStack) over the management API — status · devices · pairing
+web/                         web console (TanStack) over the management API — status · devices · pairing · GPUs · performance · logs
 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
 include/punktfunk_core.h     cbindgen-generated C header (checked in)
 tools/                       latency-probe · loss-harness (measurement)
 ```
@@ -143,4 +160,31 @@ tools/                       latency-probe · loss-harness (measurement)
 
 ## License
 
-MIT OR Apache-2.0.
+Licensed under either of
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
+  <https://www.apache.org/licenses/LICENSE-2.0>)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/licenses/MIT>)
+
+at your option — `SPDX-License-Identifier: MIT OR Apache-2.0`.
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in
+the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
+additional terms or conditions. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+### Third-party components
+
+punktfunk's own source is MIT/Apache-2.0. Shipped binaries additionally link third-party components
+under their own (permissive) licenses — see [`THIRD-PARTY-NOTICES.txt`](THIRD-PARTY-NOTICES.txt)
+(regenerate with `scripts/gen-third-party-notices.sh`). The Windows host and client builds also
+bundle FFmpeg under the **LGPL v2.1+** (dynamically linked, replaceable DLLs; the license text and
+notice ship in the installed `licenses/` folder).
+
+### Trademarks
+
+punktfunk is an independent project and is **not affiliated with, endorsed by, or sponsored by**
+NVIDIA, Microsoft, Sony, Valve, or the Moonlight project. "GameStream", "Moonlight", "Xbox",
+"DualSense", "DualShock", and "PlayStation" are trademarks of their respective owners and are used
+here only to describe interoperability.

SECURITY.md

@@ -0,0 +1,69 @@
+# Security Policy
+
+punktfunk is a low-latency desktop/game streaming stack. A host is effectively remote control of a
+machine, so we take security reports seriously and appreciate responsible disclosure.
+
+## Reporting a vulnerability
+
+**Please report security issues privately by email to security@punktfunk.com.**
+
+Do **not** open a public issue, pull request, or chat/forum post for a suspected vulnerability — that
+exposes other users before a fix exists.
+
+### What to include
+
+The more of this you can give us, the faster we can act:
+
+- The component and version (e.g. `punktfunk-host 0.6.0`, Windows or Linux, which client).
+- The impact — what an attacker can do, and from what position (same LAN, a local service account,
+  admin, a paired client, …).
+- Steps to reproduce, a proof-of-concept, or a crash/log if you have one.
+- Any suggested fix or mitigation (optional).
+
+## What to expect
+
+We're a small team, so timelines are best-effort, but we commit to:
+
+- **Acknowledge** your report within **3 business days**.
+- Give an **initial assessment** (severity + whether we can reproduce) within about **7 days**.
+- Keep you updated, and tell you when a fix ships.
+- **Credit** you in the advisory / release notes when the fix is public — unless you'd rather stay
+  anonymous.
+
+We practice **coordinated disclosure**: please give us reasonable time to release a fix before
+publishing details. We aim to resolve valid issues within **90 days** and will agree a disclosure
+date with you.
+
+## Scope
+
+In scope — the code in this repository:
+
+- The host (`punktfunk-host`), its Windows drivers, and the protocol/crypto core (`punktfunk-core`).
+- The native clients (Apple, Linux, Windows, Android), the web management console, and the management
+  API.
+
+Known limits — documented behavior, not vulnerabilities (see
+https://docs.punktfunk.unom.io/docs/security):
+
+- **Admin/SYSTEM already on the host = out of scope.** An attacker who is already administrator or
+  SYSTEM on the host owns the machine regardless of punktfunk.
+- **The virtual display is a real monitor** — any process already in the interactive desktop session
+  can capture it via the normal OS screen-capture APIs, exactly as it could a physical monitor.
+- **GameStream/Moonlight compatibility** (`--gamestream`) uses legacy encryption and is documented as
+  opt-in, trusted-LAN-only.
+- **Public-internet exposure is unsupported** — issues that only arise from exposing the host to the
+  WAN are expected; keep the host on a trusted LAN or a VPN.
+
+If you're unsure whether something is in scope, report it anyway — we'd rather hear about it.
+
+## Safe harbor
+
+We consider good-faith security research that follows this policy to be authorized, and we won't
+pursue legal action against researchers who:
+
+- make a good-faith effort to avoid privacy violations, data loss, and service disruption,
+- only test systems they own or have explicit permission to test,
+- give us reasonable time to remediate before public disclosure,
+- don't exfiltrate more data than needed to demonstrate the issue.
+
+Thank you for helping keep punktfunk and its users safe.

about.hbs

@@ -0,0 +1,23 @@
+THIRD-PARTY SOFTWARE NOTICES
+============================================================================
+
+punktfunk (https://git.unom.io/unom/punktfunk) is licensed under MIT OR Apache-2.0.
+The binaries it ships statically/dynamically link the third-party Rust crates below.
+Each is distributed under its own permissive license; full texts follow.
+Generated by `cargo about generate about.hbs` (see about.toml) — do not edit by hand.
+
+Overview:
+{{#each overview}}
+  {{name}} ({{id}}): {{count}} crate(s)
+{{/each}}
+
+{{#each licenses}}
+----------------------------------------------------------------------------
+{{name}} ({{id}})
+Used by:
+{{#each used_by}}  - {{crate.name}} {{crate.version}}{{#if crate.repository}}  ({{crate.repository}}){{/if}}
+{{/each}}
+----------------------------------------------------------------------------
+{{text}}
+
+{{/each}}

about.toml

@@ -0,0 +1,49 @@
+# cargo-about config — full-fidelity third-party license harvest for CI.
+#
+#   cargo install cargo-about
+#   cargo about generate about.hbs > THIRD-PARTY-NOTICES.txt   # (or use scripts/gen-third-party-notices.sh)
+#
+# `accepted` is the allow-list of SPDX licenses permitted in the dependency tree. CI fails if a crate
+# carries anything not listed here — which is exactly the regression guard we want against a copyleft
+# dependency silently entering the linked set. All entries
+# below are permissive / attribution-only; deliberately NO GPL/LGPL/AGPL/MPL-link/SSPL/EPL.
+#
+# The dependency-free fallback is scripts/gen-third-party-notices.py (reads the cargo registry cache),
+# which is what produced the committed baseline when cargo-about is unavailable offline.
+
+accepted = [
+    "MIT",
+    "MIT-0",
+    "Apache-2.0",
+    "Apache-2.0 WITH LLVM-exception",
+    "BSD-2-Clause",
+    "BSD-3-Clause",
+    "ISC",
+    "Zlib",
+    "0BSD",
+    "BSL-1.0",
+    "Unicode-3.0",
+    "Unicode-DFS-2016",
+    "CDLA-Permissive-2.0",
+    "CC0-1.0",
+    "Unlicense",
+    "WTFPL",
+    "OpenSSL",
+]
+
+# cbindgen is MPL-2.0 but it is a BUILD-ONLY codegen tool that never links into a shipped artifact
+# (its generated header is not a derivative work), so it is excluded from the notices rather than
+# accepted as a linked license.
+ignore-build-dependencies = true
+ignore-dev-dependencies = true
+
+# r-efi offers an LGPL-2.1-or-later arm but is tri-licensed; take a permissive arm. (It is also
+# UEFI-target-gated out of every shipped build.)
+[r-efi.clarify]
+license = "MIT OR Apache-2.0"
+
+[ring.clarify]
+license = "MIT AND ISC AND OpenSSL"
+
+[aws-lc-sys.clarify]
+license = "ISC AND Apache-2.0 AND MIT AND BSD-3-Clause AND OpenSSL"

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>

ci/fedora-rpm.Dockerfile

@@ -16,8 +16,9 @@ RUN dnf -y install \
       "https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm" \
       "https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm" \
   && dnf -y install \
-      # rpmbuild + source-tarball tooling; nodejs runs the Gitea Actions JS (checkout/cache)
-      # AND the punktfunk-web .output at runtime; unzip is for the bun installer below.
+      # rpmbuild + source-tarball tooling; nodejs runs the Gitea Actions JS (checkout/cache) only
+      # — the punktfunk-web console builds AND runs on bun (installed below); unzip is for the bun
+      # installer.
       rpm-build rpmdevtools systemd-rpm-macros git tar gzip nodejs unzip \
       # build toolchain + bindgen
       gcc gcc-c++ clang clang-devel cmake nasm pkgconf-pkg-config curl ca-certificates \
@@ -28,9 +29,10 @@ RUN dnf -y install \
       gtk4-devel libadwaita-devel SDL3-devel \
   && dnf clean all
 
-# bun — the build tool for the punktfunk-web console (`bun run build` -> the node-server .output
-# the punktfunk-web RPM ships and runs with plain node). Not in Fedora repos; install the official
-# standalone binary to a system PATH dir so the rpmbuild `%build` (run as any uid) finds it.
+# bun — both the BUILD tool and the RUNTIME for the punktfunk-web console (`bun run build` -> the
+# Nitro `bun`-preset .output, served by `Bun.serve` with TLS — HTTP/1.1 over TLS). The
+# RPM vendors THIS bun binary. Not in Fedora repos; install the official standalone binary to a
+# system PATH dir so the rpmbuild `%build`/`%install` (run as any uid) find it.
 RUN curl -fsSL https://bun.sh/install | bash \
     && install -m0755 /root/.bun/bin/bun /usr/local/bin/bun \
     && bun --version

clients/android/README.md

@@ -1,83 +1,79 @@
-# punktfunk Android client
+# punktfunk — Android client (phone & TV)
 
-Native Android client for **punktfunk/1**, targeting **phone + TV** (Compose, D-pad + touch).
+The native **Android** app for streaming a punktfunk host to your phone, tablet, or Android TV. A
+Compose app that finds hosts on your network, pairs with a PIN, and streams at the display's own
+resolution — with hardware HEVC decode, HDR10, and controller support, built for both touch and the
+couch (D-pad / gamepad focus navigation).
 
-## Architecture — Rust-heavy (like the Linux client, not thin-native like Apple)
+## Features
 
-Kotlin cannot `import` the cbindgen C header the way Swift can, so a native bridge is unavoidable.
-We write it in **Rust** and link `punktfunk-core` directly — so the Android client reuses the Linux
+- **Hardware decode** — NDK `AMediaCodec` HEVC → `SurfaceView`, including **HDR10** (Main10 /
+  BT.2020 PQ), with low-latency tuning and a live stats HUD.
+- **Audio both ways** — Opus + AAudio playback with a jitter ring, plus mic uplink to the host.
+- **Controller support** — buttons + axes with rumble and HID feedback (lightbar / adaptive
+  triggers); D-pad / gamepad focus navigation for TV and phone.
+- **Find hosts automatically** — native mDNS discovery; first connect does a one-time **SPAKE2 PIN
+  pairing** (or TOFU on trusted LANs), then reconnects on a Keystore-wrapped, pinned identity.
+- **Compose UI** — Connect / Settings / Stream screens with Material You theming.
+
+Built for `arm64-v8a` + `x86_64`.
+
+## Get it
+
+Published to **Google Play (Internal Testing)** — join the beta via the
+[Discord](https://discord.gg/kaPNvzMuGU). Per-device setup and pairing:
+**[docs.punktfunk.unom.io/docs/install-client](https://docs.punktfunk.unom.io/docs/install-client)**.
+
+## How it's built — Rust-heavy
+
+Kotlin can't `import` the cbindgen C header the way Swift can, so a native bridge is unavoidable. We
+write it in **Rust** and link `punktfunk-core` directly — so the Android client reuses the Linux
 client's orchestration (audio jitter ring, VK keymap inverse, latency/skew math, capture state
 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, **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 |
+| **Rust** (`native/` → `libpunktfunk_android.so`) | the JNI seam, `NativeClient` (QUIC control + UDP data plane), AnnexB → `AMediaCodec` decode (incl. HDR10), Opus + AAudio audio + mic, controller feedback, latency math, trust/pairing, `mdns-sd` discovery |
+| **Kotlin** (`app/`, `kit/`) | Compose UI, `SurfaceView` lifecycle, input capture, the Wi-Fi `MulticastLock` + permission UX, Keystore identity |
 
 The single seam is `io.unom.punktfunk.kit.NativeBridge` ⇄ `Java_io_unom_punktfunk_kit_NativeBridge_*`.
 
-## Layout
-
 ```
-clients/android/native/          Rust cdylib (workspace member) — links punktfunk-core directly
-  src/lib.rs                       JNI seam (connect/pair, input, plane getters, abi/core version)
-  src/session.rs                   session lifecycle + plane pumps
-  src/decode.rs                    AnnexB → AMediaCodec HEVC hardware decode → SurfaceView (incl. HDR10)
-  src/audio.rs · src/mic.rs        Opus + Oboe playback / mic uplink (jitter ring)
-  src/feedback.rs                  rumble + HID output (lightbar / adaptive triggers)
-  src/stats.rs                     live video stats
-
-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 (native mdns-sd, polled) · Gamepad · Keymap ·
-                                         security (Keystore identity + known-host store) · cargo-ndk build
+native/           Rust cdylib (workspace member) — links punktfunk-core directly
+  src/lib.rs        crate doc · JNI_OnLoad · version probes
+  src/session/      session lifecycle: connect/pair + trust, plane start/stop, input shims
+  src/decode.rs     AnnexB → AMediaCodec HEVC hardware decode → SurfaceView (incl. HDR10)
+  src/audio.rs · src/mic.rs   Opus + AAudio playback / mic uplink
+  src/feedback.rs · src/stats.rs   rumble + HID feedback; live video stats
+  src/discovery.rs  native mdns-sd browse of the host's _punktfunk._udp advert
+app/              :app — Compose UI: Connect / Settings / Stream (phone + TV)
+kit/              :kit — NativeBridge · native mDNS discovery · Gamepad · Keymap · Keystore identity
 ```
 
-## Prerequisites
-
-- Android SDK + **NDK r30** (`30.0.14904198`), `platforms;android-37.0`, `build-tools;37.0.0`,
-  **`cmake;3.22.1`** (`sdkmanager "cmake;3.22.1"` — the `cmake` crate builds libopus with it)
-- **JDK 21** for Gradle/AGP (AGP 9.2 runs on JDK 17–21, *not* a newer default JDK like 25)
-- Rust + `rustup target add aarch64-linux-android x86_64-linux-android` + `cargo install cargo-ndk`
-
-Toolchain pinned: AGP 9.2.0 · Gradle 9.4.1 · Kotlin 2.3.21 · Compose BOM 2026.05.01 ·
-compileSdk 37 · targetSdk 36 · minSdk 31 · ABIs arm64-v8a + x86_64.
-
 ## Build & run
 
-**Android Studio:** open `clients/android` — it uses its bundled JBR 21 automatically. The
-`cargoNdk*` task builds the `.so` as part of the normal build.
+**Prerequisites:** Android SDK + **NDK r30** (`30.0.14904198`), `platforms;android-37.0`,
+`build-tools;37.0.0`, **`cmake;3.22.1`** (builds libopus); **JDK 21** (AGP 9.2 runs on JDK 17–21, not
+a newer default); Rust with `rustup target add aarch64-linux-android x86_64-linux-android` and
+`cargo install cargo-ndk`. Toolchain is pinned (AGP 9.2 · Gradle 9.4.1 · Kotlin 2.3.21 · Compose BOM
+2026.05.01 · compileSdk 37 · minSdk 31).
 
-**CLI** (point Gradle at a JDK 21 if your machine default is newer, e.g. JDK 25):
+**Android Studio:** open `clients/android` — it uses its bundled JBR 21, and the `cargoNdk*` task
+builds the `.so` as part of the normal build.
+
+**CLI** (point Gradle at JDK 21 if your machine default is newer):
 
 ```sh
-# Adoptium/Temurin 21 (installed by the Android Studio setup, or `brew install temurin@21`):
-export JAVA_HOME="$(/usr/libexec/java_home -v 21)"
+export JAVA_HOME="$(/usr/libexec/java_home -v 21)"   # or your Temurin 21 path
 cd clients/android
-./gradlew :app:assembleDebug      # cargo-ndk cross-compiles libpunktfunk_android.so first
-./gradlew :app:installDebug       # onto a running emulator/device
-
-# Emulators (created during env setup):  emulator -avd pf_phone   |   emulator -avd pf_tv
+./gradlew :app:assembleDebug     # cargo-ndk cross-compiles libpunktfunk_android.so first
+./gradlew :app:installDebug      # onto a running emulator/device
+# emulators from env setup:  emulator -avd pf_phone   |   emulator -avd pf_tv
 ```
 
-The debug APK lands in `app/build/outputs/apk/debug/`. Launch it, pick a host from the list, pair,
-and stream.
+The debug APK lands in `app/build/outputs/apk/debug/`. Launch it, pick a host, pair, and stream.
 
-## Status
+## Related
 
-A working native client (phone + Android TV), at parity with the Linux and Apple apps for the core
-streaming experience:
-
-- **Video** — `AMediaCodec` hardware HEVC decode → `SurfaceView`, including **HDR10** (Main10 /
-  BT.2020 PQ), with low-latency decode tuning and a live stats HUD.
-- **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** — 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).
-
-`crates/punktfunk-core` uses the `ring` `rcgen` backend so the client `.so` is aws-lc-free.
+- **[Documentation](https://docs.punktfunk.unom.io)** — quick start, pairing, troubleshooting
+- **[Project README](../../README.md)** — the host, the other clients, and how it all fits together

clients/android/app/build.gradle.kts

@@ -62,6 +62,10 @@ android {
 
     buildFeatures { compose = true }
 
+    // Roborazzi/Robolectric render Compose on the host JVM (the CI screenshot harness) and need the
+    // merged Android resources + the app's manifest/theme available to the unit tests.
+    testOptions { unitTests { isIncludeAndroidResources = true } }
+
     compileOptions {
         sourceCompatibility = JavaVersion.VERSION_21
         targetCompatibility = JavaVersion.VERSION_21
@@ -99,4 +103,21 @@ dependencies {
     // Android TV components (we target phone + TV) land in the TV-UI milestone:
     //   implementation("androidx.tv:tv-material:1.1.0")
     // The manifest already declares leanback so the scaffold installs on TV.
+
+    // --- CI screenshot harness (Roborazzi on the JVM via Robolectric — no emulator/GPU). The
+    // screenshot tests render the real Compose UI with mock state; never load the JNI core, so the
+    // job runs `:app:testDebugUnitTest -PskipRustBuild` (see kit/build.gradle.kts). ---
+    testImplementation(composeBom)
+    testImplementation("androidx.compose.ui:ui-test-junit4")
+    debugImplementation("androidx.compose.ui:ui-test-manifest") // the ComponentActivity test host
+    testImplementation("junit:junit:4.13.2")
+    testImplementation("org.robolectric:robolectric:4.16.1")
+    testImplementation("io.github.takahirom.roborazzi:roborazzi:1.64.0")
+    testImplementation("io.github.takahirom.roborazzi:roborazzi-compose:1.64.0")
+}
+
+// Record (write) the screenshots when the unit tests run. These tests exist to GENERATE marketing
+// images, not to diff goldens, so always capture rather than verify.
+tasks.withType<Test>().configureEach {
+    systemProperty("roborazzi.test.record", "true")
 }

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

@@ -27,8 +27,15 @@
     <uses-feature android:name="android.software.leanback" android:required="false" />
     <uses-feature android:name="android.hardware.gamepad" android:required="false" />
 
+    <!-- appCategory="game": a game-streaming client IS a game as far as the SoC is concerned.
+         On Snapdragon devices (and other OEMs with a Game Mode / Game Dashboard) this makes the app
+         eligible for the vendor's game performance profile — the aggressive CPU/GPU governor and
+         scheduler treatment games get — which, together with the ADPF hints in the native decode
+         path, is what keeps clocks up for low, consistent decode latency. Also groups it correctly
+         under Games in battery/data usage. Advisory: devices without Game Mode ignore it. -->
     <application
         android:allowBackup="false"
+        android:appCategory="game"
         android:icon="@mipmap/ic_launcher"
         android:roundIcon="@mipmap/ic_launcher_round"
         android:label="@string/app_name"

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

@@ -0,0 +1,355 @@
+package io.unom.punktfunk
+
+import android.os.Build
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.material3.AlertDialog
+import androidx.compose.material3.Button
+import androidx.compose.material3.CircularProgressIndicator
+import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.ModalBottomSheet
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.material3.rememberModalBottomSheetState
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.input.KeyboardType
+import androidx.compose.ui.unit.dp
+import io.unom.punktfunk.kit.NativeBridge
+import io.unom.punktfunk.kit.security.ClientIdentity
+import io.unom.punktfunk.kit.security.KnownHost
+import io.unom.punktfunk.models.PendingTrust
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
+
+/**
+ * The "Add host" bottom sheet: optional name + address + port, then connect at [modeLabel]. Field
+ * state stays hoisted in ConnectScreen so a dismissed sheet keeps its half-typed values.
+ */
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+internal fun AddHostSheet(
+    hostName: String,
+    onHostNameChange: (String) -> Unit,
+    host: String,
+    onHostChange: (String) -> Unit,
+    port: String,
+    onPortChange: (String) -> Unit,
+    connecting: Boolean,
+    modeLabel: String,
+    onDismiss: () -> Unit,
+    onConnect: (host: String, port: Int, name: String) -> Unit,
+) {
+    val scope = rememberCoroutineScope()
+    val sheetState = rememberModalBottomSheetState()
+    ModalBottomSheet(
+        onDismissRequest = onDismiss,
+        sheetState = sheetState,
+    ) {
+        Column(
+            modifier = Modifier
+                .fillMaxWidth()
+                .padding(horizontal = 24.dp)
+                .padding(bottom = 32.dp),
+        ) {
+            Text("Add a host", style = MaterialTheme.typography.titleLarge)
+            Spacer(Modifier.height(4.dp))
+            Text(
+                "Enter its address. You'll pair with the host's PIN on first connect.",
+                style = MaterialTheme.typography.bodyMedium,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+            Spacer(Modifier.height(20.dp))
+            OutlinedTextField(
+                value = hostName,
+                onValueChange = onHostNameChange,
+                label = { Text("Name (optional)") },
+                placeholder = { Text("e.g. Living Room") },
+                singleLine = true,
+                modifier = Modifier.fillMaxWidth(),
+            )
+            Spacer(Modifier.height(16.dp))
+            OutlinedTextField(
+                value = host,
+                onValueChange = onHostChange,
+                label = { Text("Host") },
+                singleLine = true,
+                modifier = Modifier.fillMaxWidth(),
+            )
+            Spacer(Modifier.height(16.dp))
+            OutlinedTextField(
+                value = port,
+                onValueChange = { v -> onPortChange(v.filter { it.isDigit() }.take(5)) },
+                label = { Text("Port") },
+                singleLine = true,
+                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
+                modifier = Modifier.fillMaxWidth(),
+            )
+            Spacer(Modifier.height(20.dp))
+            Button(
+                enabled = !connecting && host.isNotBlank() && port.isNotBlank(),
+                onClick = {
+                    val h = host.trim()
+                    val p = port.toIntOrNull() ?: 9777
+                    val n = hostName
+                    scope.launch { sheetState.hide() }.invokeOnCompletion {
+                        onDismiss()
+                        onConnect(h, p, n)
+                    }
+                },
+                modifier = Modifier.fillMaxWidth(),
+            ) { Text("Connect  ($modeLabel)") }
+        }
+    }
+}
+
+/** First connection to a host that advertised pair=optional: offer TOFU, but pitch PIN pairing. */
+@Composable
+internal fun TrustNewHostDialog(
+    pt: PendingTrust,
+    onTrust: () -> Unit,
+    onPairInstead: () -> Unit,
+    onDismiss: () -> Unit,
+) {
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        title = { Text("Trust this host?") },
+        text = {
+            Column {
+                Text("First connection to ${pt.host}:${pt.port}.")
+                pt.advertisedFp?.let { Text("Fingerprint ${it.take(16)}…") }
+                Text(
+                    "This host allows trust-on-first-use, but that can't tell an impostor " +
+                        "from the real host. Pairing with a PIN is stronger — it proves both sides.",
+                )
+            }
+        },
+        confirmButton = {
+            TextButton(onClick = onTrust) { Text("Trust (TOFU)") }
+        },
+        dismissButton = {
+            Row {
+                TextButton(onClick = onPairInstead) { Text("Pair with PIN…") }
+                TextButton(onClick = onDismiss) { Text("Cancel") }
+            }
+        },
+    )
+}
+
+/** The pinned fingerprint no longer matches — force re-pairing (never a silent re-trust). */
+@Composable
+internal fun FingerprintChangedDialog(
+    pt: PendingTrust,
+    onRepair: () -> Unit,
+    onDismiss: () -> Unit,
+) {
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        title = { Text("Host identity changed") },
+        text = {
+            Text(
+                "The pinned fingerprint for ${pt.host} no longer matches what it now " +
+                    "advertises. This can mean a host reinstall — or an impostor. Re-pair " +
+                    "with the host's PIN to continue.",
+            )
+        },
+        confirmButton = {
+            TextButton(onClick = onRepair) { Text("Re-pair") }
+        },
+        dismissButton = {
+            TextButton(onClick = onDismiss) { Text("Cancel") }
+        },
+    )
+}
+
+/**
+ * A fresh pair=required (or manual/unknown-policy) host: offer the two ways in. "Request access" is
+ * the no-PIN path — connect and wait for the operator to click Approve in the host's console;
+ * "Use a PIN…" switches to the SPAKE2 ceremony.
+ */
+@Composable
+internal fun RequestAccessDialog(
+    pt: PendingTrust,
+    onRequestAccess: () -> Unit,
+    onUsePin: () -> Unit,
+    onDismiss: () -> Unit,
+) {
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        title = { Text("Pairing required") },
+        text = {
+            Column {
+                Text("${pt.host}:${pt.port} requires pairing before it will stream.")
+                Text(
+                    "Request access and approve this device in the host's console (or web " +
+                        "UI) — no PIN needed. Or pair with the 4-digit PIN the host displays.",
+                )
+            }
+        },
+        confirmButton = {
+            TextButton(onClick = onRequestAccess) { Text("Request access") }
+        },
+        dismissButton = {
+            Row {
+                TextButton(onClick = onUsePin) { Text("Use a PIN…") }
+                TextButton(onClick = onDismiss) { Text("Cancel") }
+            }
+        },
+    )
+}
+
+/**
+ * The SPAKE2 PIN ceremony dialog. Runs [NativeBridge.nativePair] off the UI thread itself (the
+ * pin/name/error state is dialog-local); on success hands the host's verified fingerprint to
+ * [onPaired], which saves + connects. Dismissal is blocked while a pair attempt is in flight.
+ */
+@Composable
+internal fun PairPinDialog(
+    pt: PendingTrust,
+    identity: ClientIdentity?,
+    onPaired: (fpHex: String) -> Unit,
+    onDismiss: () -> Unit,
+) {
+    val scope = rememberCoroutineScope()
+    var pin by remember(pt) { mutableStateOf("") }
+    var name by remember(pt) { mutableStateOf(Build.MODEL ?: "Android") }
+    var pairing by remember(pt) { mutableStateOf(false) }
+    var err by remember(pt) { mutableStateOf<String?>(null) }
+    AlertDialog(
+        onDismissRequest = { if (!pairing) onDismiss() },
+        title = { Text("Pair with PIN") },
+        text = {
+            Column {
+                Text("Enter the 4-digit PIN shown on the host.")
+                OutlinedTextField(
+                    value = pin,
+                    onValueChange = { v -> pin = v.filter { it.isDigit() }.take(4) },
+                    label = { Text("PIN") },
+                    singleLine = true,
+                    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
+                )
+                OutlinedTextField(
+                    value = name,
+                    onValueChange = { name = it },
+                    label = { Text("This device") },
+                    singleLine = true,
+                )
+                err?.let { Text(it, color = MaterialTheme.colorScheme.error) }
+            }
+        },
+        confirmButton = {
+            TextButton(
+                enabled = !pairing && pin.length == 4 && identity != null,
+                onClick = {
+                    val id = identity
+                    if (id != null) {
+                        pairing = true
+                        err = null
+                        scope.launch {
+                            val fp = withContext(Dispatchers.IO) {
+                                NativeBridge.nativePair(
+                                    pt.host, pt.port, id.certPem, id.privateKeyPem, pin, name,
+                                )
+                            }
+                            pairing = false
+                            if (fp.isNotEmpty()) {
+                                onPaired(fp) // verified host fp — caller saves + connects
+                            } else {
+                                err = "Pairing failed — wrong PIN, or the host isn't armed."
+                            }
+                        }
+                    }
+                },
+            ) { Text(if (pairing) "Pairing…" else "Pair") }
+        },
+        dismissButton = {
+            TextButton(enabled = !pairing, onClick = onDismiss) { Text("Cancel") }
+        },
+    )
+}
+
+/**
+ * The no-PIN "request access" wait: the connect is parked on the host until the operator approves
+ * this device. Cancel returns the UI immediately — the caller trips the per-attempt flag so a late
+ * approval is torn down silently (see ConnectScreen.requestAccess) and resumes discovery.
+ */
+@Composable
+internal fun AwaitingApprovalDialog(hostLabel: String, onCancel: () -> Unit) {
+    AlertDialog(
+        onDismissRequest = onCancel,
+        title = { Text("Waiting for approval") },
+        text = {
+            val deviceName = Build.MODEL ?: "this device"
+            Column(verticalArrangement = Arrangement.spacedBy(12.dp)) {
+                Row(
+                    verticalAlignment = Alignment.CenterVertically,
+                    horizontalArrangement = Arrangement.spacedBy(12.dp),
+                ) {
+                    CircularProgressIndicator(modifier = Modifier.size(20.dp), strokeWidth = 2.dp)
+                    Text("Approve this device on $hostLabel.")
+                }
+                Text(
+                    "Open the host's console (or web UI) and approve “$deviceName”. It connects " +
+                        "automatically once you approve — no PIN needed.",
+                    style = MaterialTheme.typography.bodyMedium,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+        },
+        confirmButton = {},
+        dismissButton = {
+            TextButton(onClick = onCancel) { Text("Cancel") }
+        },
+    )
+}
+
+/**
+ * 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.
+ */
+@Composable
+internal fun RenameHostDialog(
+    target: KnownHost,
+    onRename: (String) -> Unit,
+    onDismiss: () -> Unit,
+) {
+    var newName by remember(target) { mutableStateOf(target.name) }
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        title = { Text("Rename host") },
+        text = {
+            OutlinedTextField(
+                value = newName,
+                onValueChange = { newName = it },
+                label = { Text("Name") },
+                placeholder = { Text(target.address) },
+                singleLine = true,
+            )
+        },
+        confirmButton = {
+            TextButton(
+                enabled = newName.isNotBlank(),
+                onClick = { onRename(newName.trim()) },
+            ) { Text("Save") }
+        },
+        dismissButton = {
+            TextButton(onClick = onDismiss) { Text("Cancel") }
+        },
+    )
+}

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

@@ -6,11 +6,6 @@ import android.content.pm.PackageManager
 import android.os.Build
 import androidx.activity.compose.rememberLauncherForActivityResult
 import androidx.activity.result.contract.ActivityResultContracts
-import androidx.compose.animation.AnimatedVisibility
-import androidx.compose.animation.fadeIn
-import androidx.compose.animation.fadeOut
-import androidx.compose.animation.scaleIn
-import androidx.compose.animation.scaleOut
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.Column
@@ -27,24 +22,14 @@ import androidx.compose.foundation.lazy.grid.GridCells
 import androidx.compose.foundation.lazy.grid.GridItemSpan
 import androidx.compose.foundation.lazy.grid.LazyVerticalGrid
 import androidx.compose.foundation.lazy.grid.items
-import androidx.compose.foundation.rememberScrollState
-import androidx.compose.foundation.text.KeyboardOptions
-import androidx.compose.foundation.verticalScroll
 import androidx.compose.material.icons.Icons
 import androidx.compose.material.icons.filled.Add
-import androidx.compose.material3.AlertDialog
-import androidx.compose.material3.Button
 import androidx.compose.material3.CircularProgressIndicator
-import androidx.compose.material3.ExperimentalMaterial3Api
 import androidx.compose.material3.ExtendedFloatingActionButton
 import androidx.compose.material3.Icon
 import androidx.compose.material3.MaterialTheme
-import androidx.compose.material3.ModalBottomSheet
-import androidx.compose.material3.OutlinedTextField
 import androidx.compose.material3.Surface
 import androidx.compose.material3.Text
-import androidx.compose.material3.TextButton
-import androidx.compose.material3.rememberModalBottomSheetState
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.LaunchedEffect
@@ -56,7 +41,6 @@ import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.platform.LocalContext
-import androidx.compose.ui.text.input.KeyboardType
 import androidx.compose.ui.text.style.TextAlign
 import androidx.compose.ui.unit.dp
 import androidx.core.content.ContextCompat
@@ -74,11 +58,31 @@ import io.unom.punktfunk.kit.security.KnownHostStore
 import io.unom.punktfunk.kit.security.obtainIdentity
 import io.unom.punktfunk.models.HostStatus
 import io.unom.punktfunk.models.PendingTrust
+import java.util.concurrent.atomic.AtomicBoolean
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
 
-@OptIn(ExperimentalMaterial3Api::class)
+/** Handshake budget for a normal connect (the prior hardcoded value, now passed explicitly). */
+private const val CONNECT_TIMEOUT_MS = 10_000
+
+/**
+ * Handshake budget for the no-PIN "request access" connect. Must exceed the host's approval-park
+ * window (~180 s) so a slow operator approval still lands on this same parked connection rather than
+ * timing the client out first. Mirrors the Linux client's 185 s.
+ */
+private const val REQUEST_ACCESS_TIMEOUT_MS = 185_000
+
+/**
+ * A no-PIN "request access" connect in flight — the host being requested (drives the cancelable
+ * "Waiting for approval…" dialog) and a per-attempt flag the Cancel button trips. The connect is a
+ * blocking call with no abort, so Cancel returns the UI immediately and a late result checks
+ * [cancelled] and tears the (possibly just-approved) session down silently rather than navigating.
+ */
+private class RequestAccessState(val target: PendingTrust) {
+    val cancelled = AtomicBoolean(false)
+}
+
 @Composable
 fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
     val scope = rememberCoroutineScope()
@@ -120,6 +124,25 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
     val identityStore = remember { IdentityStore(context) }
     val knownHostStore = remember { KnownHostStore(context) }
     var savedHosts by remember { mutableStateOf(knownHostStore.all()) }
+    // Learn wake MAC(s) from live adverts for hosts we've saved (parity with the desktop clients),
+    // so we can Wake-on-LAN them once they sleep. Runs only when the discovered set changes; the
+    // prefs write is guarded (no-op when unchanged), and we refresh the saved list only if a MAC
+    // was actually newly learned.
+    LaunchedEffect(discovered) {
+        val learned = withContext(Dispatchers.IO) {
+            var any = false
+            discovered.forEach { dh ->
+                if (dh.mac.isNotEmpty() &&
+                    knownHostStore.get(dh.host, dh.port)?.let { it.mac != dh.mac } == true
+                ) {
+                    knownHostStore.learnMac(dh.host, dh.port, dh.mac)
+                    any = true
+                }
+            }
+            any
+        }
+        if (learned) savedHosts = knownHostStore.all()
+    }
     // Mint-once on genuine first run; an Unrecoverable store (decrypt failure) surfaces here and
     // refuses to connect — never silently shadow-minting a new identity (which would force re-pair).
     var identity by remember { mutableStateOf<ClientIdentity?>(null) }
@@ -128,8 +151,11 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
             .onSuccess { identity = it }
             .onFailure { status = "Identity unavailable: ${it.message} — re-pair may be required" }
     }
-    // A trust decision awaiting the user (first-connect TOFU / fp changed / PIN pairing).
+    // A trust decision awaiting the user (first-connect TOFU / fp changed / PIN pairing / the
+    // request-access-or-PIN choice).
     var pendingTrust by remember { mutableStateOf<PendingTrust?>(null) }
+    // A no-PIN "request access" connect in flight (the cancelable "Waiting for approval…" dialog).
+    var awaiting by remember { mutableStateOf<RequestAccessState?>(null) }
     // A saved host whose label is being edited (the Rename dialog).
     var renameTarget by remember { mutableStateOf<KnownHost?>(null) }
 
@@ -138,6 +164,26 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
     // it survives a DHCP address change; else by address:port). Mirrors the Apple client.
     val discoveredUnsaved = discovered.filter { dh -> savedHosts.none { it.matches(dh) } }
 
+    // The one place the full nativeConnect is issued (shared by the normal connect and the
+    // request-access path), including the HDR/gamepad derivation both need.
+    suspend fun connectNative(id: ClientIdentity, targetHost: String, targetPort: Int, pinHex: String, timeoutMs: Int): Long {
+        // Advertise HDR only when the user enabled it AND this device's display can present it
+        // (else the host sends a proper SDR stream rather than PQ the panel would mis-tone-map).
+        val hdrEnabled = settings.hdrEnabled && displaySupportsHdr(context)
+        // "Automatic" resolves to a concrete pad type from the connected controller's VID/PID
+        // (Android exposes no controller-type enum) — parity with the Linux/Apple clients. An
+        // explicit choice is passed through unchanged.
+        val gamepadPref = Gamepad.resolvePref(settings.gamepad)
+        return withContext(Dispatchers.IO) {
+            NativeBridge.nativeConnect(
+                targetHost, targetPort, w, h, hz,
+                id.certPem, id.privateKeyPem, pinHex,
+                settings.bitrateKbps, settings.compositor, gamepadPref,
+                hdrEnabled, settings.audioChannels, settings.preferredCodec(), timeoutMs,
+            )
+        }
+    }
+
     // 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
     // straight through and it appears in the saved-hosts list.
@@ -149,23 +195,17 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
         }
         connecting = true
         status = "Connecting to $targetHost:$targetPort…"
+        // Auto-wake: reconnecting to a saved host that may be asleep. If we learned its MAC while it
+        // was online and it isn't currently advertising, fire a magic packet first — the connect's
+        // own timeout gives a woken host time to come up (harmless if it's already awake).
+        knownHostStore.get(targetHost, targetPort)?.mac
+            ?.takeIf { it.isNotEmpty() && discovered.none { d -> d.host == targetHost && d.port == targetPort } }
+            ?.let { macs ->
+                scope.launch(Dispatchers.IO) { NativeBridge.nativeWakeOnLan(macs.joinToString(","), targetHost) }
+            }
         discovery.stop() // free the Wi-Fi radio before the stream session
         scope.launch {
-            // Advertise HDR only when this device's display can present it (else the host sends a
-            // proper SDR stream rather than PQ the panel would mis-tone-map).
-            val hdrEnabled = displaySupportsHdr(context)
-            // "Automatic" resolves to a concrete pad type from the connected controller's VID/PID
-            // (Android exposes no controller-type enum) — parity with the Linux/Apple clients. An
-            // explicit choice is passed through unchanged.
-            val gamepadPref = Gamepad.resolvePref(settings.gamepad)
-            val handle = withContext(Dispatchers.IO) {
-                NativeBridge.nativeConnect(
-                    targetHost, targetPort, w, h, hz,
-                    id.certPem, id.privateKeyPem, pinHex ?: "",
-                    settings.bitrateKbps, settings.compositor, gamepadPref,
-                    hdrEnabled,
-                )
-            }
+            val handle = connectNative(id, targetHost, targetPort, pinHex ?: "", CONNECT_TIMEOUT_MS)
             connecting = false
             if (handle != 0L) {
                 if (pinHex == null) { // TOFU: pin what we observed (unpaired)
@@ -182,10 +222,57 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
         }
     }
 
-    // Decide pinned-reconnect vs fp-changed vs TOFU vs PIN pairing before connecting. Trust state is
+    // The no-PIN "request access" path (delegated approval): open a normal identified connect that
+    // the host PARKS until the operator clicks Approve in its console/web UI, showing a cancelable
+    // "Waiting for approval…" dialog meanwhile. The SAME connection is admitted on approval (no
+    // reconnect), so on success we record the host as PAIRED — the operator's approval IS the pairing.
+    // The connect can't be aborted, so Cancel returns the UI immediately and a late result is torn
+    // down silently via the per-attempt flag (mirrors the Linux client's request-access flow).
+    fun requestAccess(target: PendingTrust) {
+        val id = identity
+        if (id == null) {
+            status = "Identity not ready yet — try again in a moment"
+            return
+        }
+        val req = RequestAccessState(target)
+        awaiting = req
+        connecting = true
+        status = null
+        discovery.stop() // free the Wi-Fi radio before the (parked) stream session
+        scope.launch {
+            // Pin the advertised fingerprint for a discovered host (defence against an impostor while
+            // we wait); a manually-typed host has none, so trust-on-first-use.
+            val pinHex = target.advertisedFp ?: ""
+            val handle = connectNative(id, target.host, target.port, pinHex, REQUEST_ACCESS_TIMEOUT_MS)
+            // Cancelled while we were parked: tear the (possibly just-approved) session down and
+            // don't touch UI a fresh action may now own.
+            if (req.cancelled.get()) {
+                if (handle != 0L) withContext(Dispatchers.IO) { NativeBridge.nativeClose(handle) }
+                return@launch
+            }
+            awaiting = null
+            connecting = false
+            if (handle != 0L) {
+                // Approved — save the host as PAIRED, pinning the fingerprint it presented, so
+                // future connects are silent (exactly like after a PIN ceremony).
+                val fp = NativeBridge.nativeHostFingerprint(handle)
+                if (fp.isNotEmpty()) {
+                    knownHostStore.save(KnownHost(target.host, target.port, target.name, fp, paired = true))
+                    savedHosts = knownHostStore.all()
+                }
+                onConnected(handle)
+            } else {
+                status = "Request timed out — approve this device in the host's console, then retry."
+                discovery.start()
+            }
+        }
+    }
+
+    // Decide pinned-reconnect vs fp-changed vs TOFU vs pairing before connecting. Trust state is
     // 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.
+    // pair=required host, or a manual/unknown-policy host, must pair — either by no-PIN request
+    // access (approve in the console) or by the SPAKE2 PIN ceremony.
     fun connect(
         targetHost: String,
         targetPort: Int,
@@ -208,13 +295,13 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
             // clearly labeled, alongside PIN pairing). Smart-cast: this branch ⇒ dh != null.
             dh?.pairingRequired == false -> pendingTrust =
                 PendingTrust(targetHost, targetPort, name, dh.fingerprint, PendingTrust.Kind.TRUST_NEW)
-            // pair=required, or a manual/unknown-policy host → PIN pairing is mandatory.
+            // pair=required, or a manual/unknown-policy host → offer the two ways in: a no-PIN
+            // "request access" (approve in the console) or the SPAKE2 PIN ceremony.
             else -> pendingTrust =
-                PendingTrust(targetHost, targetPort, name, adv, PendingTrust.Kind.PAIR)
+                PendingTrust(targetHost, targetPort, name, adv, PendingTrust.Kind.REQUEST_ACCESS)
         }
     }
 
-    val sheetState = rememberModalBottomSheetState()
     var showManualSheet by remember { mutableStateOf(false) }
 
     Box(Modifier.fillMaxSize()) {
@@ -299,6 +386,15 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
                             savedHosts = knownHostStore.all()
                         },
                         onRename = { renameTarget = kh },
+                        // Explicit wake: offered only when the host is offline and we have a MAC to
+                        // target (a tap-to-connect already auto-wakes an offline saved host).
+                        onWake = if (kh.mac.isNotEmpty() &&
+                            discovered.none { it.host == kh.address && it.port == kh.port }
+                        ) {
+                            { scope.launch(Dispatchers.IO) { NativeBridge.nativeWakeOnLan(kh.mac.joinToString(","), kh.address) } }
+                        } else {
+                            null
+                        },
                     )
                 }
             }
@@ -346,226 +442,87 @@ fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
             }
         }
 
-        AnimatedVisibility(
-            visible = true, // Static for now, could be based on scroll if needed
-            enter = scaleIn() + fadeIn(),
-            exit = scaleOut() + fadeOut(),
+        ExtendedFloatingActionButton(
+            onClick = { showManualSheet = true },
+            icon = { Icon(Icons.Filled.Add, contentDescription = null) },
+            text = { Text("Add host") },
+            expanded = !connecting,
             modifier = Modifier
                 .align(Alignment.BottomEnd)
-                .padding(20.dp)
-        ) {
-            ExtendedFloatingActionButton(
-                onClick = { showManualSheet = true },
-                icon = { Icon(Icons.Filled.Add, contentDescription = null) },
-                text = { Text("Add host") },
-                expanded = !connecting,
-            )
-        }
+                .padding(20.dp),
+        )
     }
 
     if (showManualSheet) {
-        ModalBottomSheet(
-            onDismissRequest = { showManualSheet = false },
-            sheetState = sheetState,
-        ) {
-            Column(
-                modifier = Modifier
-                    .fillMaxWidth()
-                    .padding(horizontal = 24.dp)
-                    .padding(bottom = 32.dp),
-            ) {
-                Text("Add a host", style = MaterialTheme.typography.titleLarge)
-                Spacer(Modifier.height(4.dp))
-                Text(
-                    "Enter its address. You'll pair with the host's PIN on first connect.",
-                    style = MaterialTheme.typography.bodyMedium,
-                    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 },
-                    label = { Text("Host") },
-                    singleLine = true,
-                    modifier = Modifier.fillMaxWidth(),
-                )
-                Spacer(Modifier.height(16.dp))
-                OutlinedTextField(
-                    value = port,
-                    onValueChange = { v -> port = v.filter { it.isDigit() }.take(5) },
-                    label = { Text("Port") },
-                    singleLine = true,
-                    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
-                    modifier = Modifier.fillMaxWidth(),
-                )
-                Spacer(Modifier.height(20.dp))
-                Button(
-                    enabled = !connecting && host.isNotBlank() && port.isNotBlank(),
-                    onClick = {
-                        val h = host.trim()
-                        val p = port.toIntOrNull() ?: 9777
-                        val n = hostName
-                        scope.launch { sheetState.hide() }.invokeOnCompletion {
-                            showManualSheet = false
-                            connect(h, p, manualName = n)
-                        }
-                    },
-                    modifier = Modifier.fillMaxWidth(),
-                ) { Text("Connect  ($w×$h@$hz)") }
-            }
-        }
+        AddHostSheet(
+            hostName = hostName,
+            onHostNameChange = { hostName = it },
+            host = host,
+            onHostChange = { host = it },
+            port = port,
+            onPortChange = { port = it },
+            connecting = connecting,
+            modeLabel = "$w×$h@$hz",
+            onDismiss = { showManualSheet = false },
+            onConnect = { h2, p, n -> connect(h2, p, manualName = n) },
+        )
     }
 
     pendingTrust?.let { pt ->
         when (pt.kind) {
-            PendingTrust.Kind.TRUST_NEW -> AlertDialog(
-                onDismissRequest = { pendingTrust = null },
-                title = { Text("Trust this host?") },
-                text = {
-                    Column {
-                        Text("First connection to ${pt.host}:${pt.port}.")
-                        pt.advertisedFp?.let { Text("Fingerprint ${it.take(16)}…") }
-                        Text(
-                            "This host allows trust-on-first-use, but that can't tell an impostor " +
-                                "from the real host. Pairing with a PIN is stronger — it proves both sides.",
-                        )
-                    }
-                },
-                confirmButton = {
-                    TextButton({ pendingTrust = null; doConnect(pt.host, pt.port, pt.name, null) }) {
-                        Text("Trust (TOFU)")
-                    }
-                },
-                dismissButton = {
-                    Row {
-                        TextButton({ pendingTrust = pt.copy(kind = PendingTrust.Kind.PAIR) }) {
-                            Text("Pair with PIN…")
-                        }
-                        TextButton({ pendingTrust = null }) { Text("Cancel") }
-                    }
-                },
+            PendingTrust.Kind.TRUST_NEW -> TrustNewHostDialog(
+                pt = pt,
+                onTrust = { pendingTrust = null; doConnect(pt.host, pt.port, pt.name, null) },
+                onPairInstead = { pendingTrust = pt.copy(kind = PendingTrust.Kind.PAIR) },
+                onDismiss = { pendingTrust = null },
             )
-            PendingTrust.Kind.FP_CHANGED -> AlertDialog(
-                onDismissRequest = { pendingTrust = null },
-                title = { Text("Host identity changed") },
-                text = {
-                    Text(
-                        "The pinned fingerprint for ${pt.host} no longer matches what it now " +
-                            "advertises. This can mean a host reinstall — or an impostor. Re-pair " +
-                            "with the host's PIN to continue.",
-                    )
-                },
-                confirmButton = {
-                    TextButton({ pendingTrust = pt.copy(kind = PendingTrust.Kind.PAIR) }) { Text("Re-pair") }
-                },
-                dismissButton = {
-                    TextButton({ pendingTrust = null }) { Text("Cancel") }
-                },
+            PendingTrust.Kind.FP_CHANGED -> FingerprintChangedDialog(
+                pt = pt,
+                onRepair = { pendingTrust = pt.copy(kind = PendingTrust.Kind.PAIR) },
+                onDismiss = { pendingTrust = null },
+            )
+            PendingTrust.Kind.REQUEST_ACCESS -> RequestAccessDialog(
+                pt = pt,
+                onRequestAccess = { pendingTrust = null; requestAccess(pt) },
+                onUsePin = { pendingTrust = pt.copy(kind = PendingTrust.Kind.PAIR) },
+                onDismiss = { pendingTrust = null },
+            )
+            PendingTrust.Kind.PAIR -> PairPinDialog(
+                pt = pt,
+                identity = identity,
+                onPaired = { fp ->
+                    // Verified host fp — save as a paired known host, then connect pinned.
+                    knownHostStore.save(KnownHost(pt.host, pt.port, pt.name, fp, paired = true))
+                    savedHosts = knownHostStore.all()
+                    pendingTrust = null
+                    doConnect(pt.host, pt.port, pt.name, fp)
+                },
+                onDismiss = { pendingTrust = null },
             )
-            PendingTrust.Kind.PAIR -> {
-                var pin by remember(pt) { mutableStateOf("") }
-                var name by remember(pt) { mutableStateOf(Build.MODEL ?: "Android") }
-                var pairing by remember(pt) { mutableStateOf(false) }
-                var err by remember(pt) { mutableStateOf<String?>(null) }
-                AlertDialog(
-                    onDismissRequest = { if (!pairing) pendingTrust = null },
-                    title = { Text("Pair with PIN") },
-                    text = {
-                        Column {
-                            Text("Enter the 4-digit PIN shown on the host.")
-                            OutlinedTextField(
-                                value = pin,
-                                onValueChange = { v -> pin = v.filter { it.isDigit() }.take(4) },
-                                label = { Text("PIN") },
-                                singleLine = true,
-                                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
-                            )
-                            OutlinedTextField(
-                                value = name,
-                                onValueChange = { name = it },
-                                label = { Text("This device") },
-                                singleLine = true,
-                            )
-                            err?.let { Text(it, color = MaterialTheme.colorScheme.error) }
-                        }
-                    },
-                    confirmButton = {
-                        TextButton(
-                            enabled = !pairing && pin.length == 4 && identity != null,
-                            onClick = {
-                                val id = identity
-                                if (id != null) {
-                                    pairing = true
-                                    err = null
-                                    scope.launch {
-                                        val fp = withContext(Dispatchers.IO) {
-                                            NativeBridge.nativePair(
-                                                pt.host, pt.port, id.certPem, id.privateKeyPem, pin, name,
-                                            )
-                                        }
-                                        pairing = false
-                                        if (fp.isNotEmpty()) {
-                                            // Verified host fp — save as a paired known host.
-                                            knownHostStore.save(
-                                                KnownHost(pt.host, pt.port, pt.name, fp, paired = true),
-                                            )
-                                            savedHosts = knownHostStore.all()
-                                            pendingTrust = null
-                                            doConnect(pt.host, pt.port, pt.name, fp)
-                                        } else {
-                                            err = "Pairing failed — wrong PIN, or the host isn't armed."
-                                        }
-                                    }
-                                }
-                            },
-                        ) { Text(if (pairing) "Pairing…" else "Pair") }
-                    },
-                    dismissButton = {
-                        TextButton(enabled = !pairing, onClick = { pendingTrust = null }) { Text("Cancel") }
-                    },
-                )
-            }
         }
     }
 
-    // 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.
+    awaiting?.let { req ->
+        AwaitingApprovalDialog(
+            hostLabel = req.target.name,
+            onCancel = {
+                req.cancelled.set(true)
+                awaiting = null
+                connecting = false
+                discovery.start() // the request may still be pending on the host; keep scanning
+            },
+        )
+    }
+
     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") }
+        RenameHostDialog(
+            target = kh,
+            onRename = { newName ->
+                knownHostStore.rename(kh.address, kh.port, newName)
+                savedHosts = knownHostStore.all()
+                renameTarget = null
             },
+            onDismiss = { renameTarget = null },
         )
     }
 }

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

@@ -0,0 +1,382 @@
+package io.unom.punktfunk
+
+import android.hardware.input.InputManager
+import android.os.CombinedVibration
+import android.os.Handler
+import android.os.Looper
+import android.os.VibrationEffect
+import android.view.InputDevice
+import android.view.KeyEvent
+import android.view.MotionEvent
+import androidx.activity.compose.BackHandler
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.ColumnScope
+import androidx.compose.foundation.layout.ExperimentalLayoutApi
+import androidx.compose.foundation.layout.FlowRow
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.LinearProgressIndicator
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
+import androidx.compose.material3.OutlinedCard
+import androidx.compose.material3.Switch
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableIntStateOf
+import androidx.compose.runtime.mutableStateMapOf
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.unit.dp
+import io.unom.punktfunk.kit.Gamepad
+import kotlinx.coroutines.delay
+
+/**
+ * Connected-controllers debug view (Settings → Host → Connected controllers): everything the app
+ * can see about attached input devices, plus a live input test. This exists for exactly the support
+ * case where a pad "doesn't work" — adapters and BT-to-USB dongles often enumerate with a different
+ * identity than the physical pad, or not as a gamepad at all, and punktfunk only forwards devices
+ * Android classifies as gamepad/joystick. This screen makes that visible on the device itself.
+ */
+@Composable
+fun ControllersScreen(gamepadSetting: Int, onBack: () -> Unit) {
+    BackHandler(onBack = onBack)
+    val context = LocalContext.current
+    val activity = context as? MainActivity
+
+    // Device list, re-read on every hot-plug event.
+    var generation by remember { mutableIntStateOf(0) }
+    val pads = remember(generation) { Gamepad.pads() }
+    val others = remember(generation) {
+        InputDevice.getDeviceIds()
+            .toList()
+            .mapNotNull { InputDevice.getDevice(it) }
+            .filter { !it.isVirtual && !Gamepad.isPad(it) }
+    }
+    DisposableEffect(Unit) {
+        val im = context.getSystemService(InputManager::class.java)
+        val listener = object : InputManager.InputDeviceListener {
+            override fun onInputDeviceAdded(deviceId: Int) { generation++ }
+            override fun onInputDeviceRemoved(deviceId: Int) { generation++ }
+            override fun onInputDeviceChanged(deviceId: Int) { generation++ }
+        }
+        im.registerInputDeviceListener(listener, Handler(Looper.getMainLooper()))
+        onDispose { im.unregisterInputDeviceListener(listener) }
+    }
+
+    // Live input test. While `testing`, the MainActivity probes consume pad events (so they show up
+    // here instead of driving focus navigation); holding B releases, since the pad can no longer
+    // reach the Switch. Events are observed (not consumed) even when the test is off, so the
+    // "last input" line works while browsing.
+    var testing by remember { mutableStateOf(false) }
+    val held = remember { mutableStateMapOf<Int, Boolean>() }
+    val axes = remember { mutableStateMapOf<String, Float>() }
+    var lastInput by remember { mutableStateOf<String?>(null) }
+    var bHeld by remember { mutableStateOf(false) }
+
+    DisposableEffect(Unit) {
+        activity?.padKeyProbe = probe@{ event ->
+            if (!Gamepad.isPad(event.device)) return@probe false
+            when (event.action) {
+                KeyEvent.ACTION_DOWN -> {
+                    held[event.keyCode] = true
+                    if (event.keyCode == KeyEvent.KEYCODE_BUTTON_B) bHeld = true
+                }
+                KeyEvent.ACTION_UP -> {
+                    held[event.keyCode] = false
+                    if (event.keyCode == KeyEvent.KEYCODE_BUTTON_B) bHeld = false
+                }
+            }
+            lastInput = "${event.device?.name}: ${KeyEvent.keyCodeToString(event.keyCode)}"
+            testing
+        }
+        activity?.padMotionProbe = probe@{ event ->
+            if (!Gamepad.isPad(event.device)) return@probe false
+            axes["LX"] = event.getAxisValue(MotionEvent.AXIS_X)
+            axes["LY"] = event.getAxisValue(MotionEvent.AXIS_Y)
+            axes["RX"] = event.getAxisValue(MotionEvent.AXIS_Z)
+            axes["RY"] = event.getAxisValue(MotionEvent.AXIS_RZ)
+            axes["LT"] = maxOf(
+                event.getAxisValue(MotionEvent.AXIS_LTRIGGER),
+                event.getAxisValue(MotionEvent.AXIS_BRAKE),
+            )
+            axes["RT"] = maxOf(
+                event.getAxisValue(MotionEvent.AXIS_RTRIGGER),
+                event.getAxisValue(MotionEvent.AXIS_GAS),
+            )
+            axes["HX"] = event.getAxisValue(MotionEvent.AXIS_HAT_X)
+            axes["HY"] = event.getAxisValue(MotionEvent.AXIS_HAT_Y)
+            testing
+        }
+        onDispose {
+            activity?.padKeyProbe = null
+            activity?.padMotionProbe = null
+        }
+    }
+    // Hold-B-to-exit: with events consumed, the pad can't reach the Switch — a 1.2 s hold ends the
+    // test instead (touch still works). A short tap cancels the effect before the delay fires.
+    LaunchedEffect(bHeld) {
+        if (bHeld && testing) {
+            delay(1_200)
+            testing = false
+            held.clear()
+        }
+    }
+
+    Column(
+        modifier = Modifier
+            .fillMaxSize()
+            .verticalScroll(rememberScrollState())
+            .padding(horizontal = 20.dp, vertical = 24.dp),
+        verticalArrangement = Arrangement.spacedBy(24.dp),
+    ) {
+        Text("Controllers", style = MaterialTheme.typography.headlineMedium)
+
+        Group("Gamepads") {
+            if (pads.isEmpty()) {
+                Text(
+                    "No controller detected. punktfunk can only forward devices Android " +
+                        "classifies as a gamepad or joystick — a pad connected through an adapter " +
+                        "or hub may show up under \"Other input devices\" below with the adapter's " +
+                        "identity, or not at all.",
+                    style = MaterialTheme.typography.bodyMedium,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+            pads.forEachIndexed { i, dev ->
+                PadRow(dev, forwarded = i == 0, gamepadSetting = gamepadSetting)
+            }
+        }
+
+        Group("Input test") {
+            Row(modifier = Modifier.fillMaxWidth(), verticalAlignment = Alignment.CenterVertically) {
+                Column(Modifier.weight(1f)) {
+                    Text("Test inputs", style = MaterialTheme.typography.bodyLarge)
+                    Text(
+                        if (testing) "Controller input stays on this screen — hold B to finish"
+                        else "Show button presses and stick motion live",
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+                Switch(checked = testing, onCheckedChange = { testing = it; if (!it) held.clear() })
+            }
+            if (testing) {
+                ButtonGrid(held)
+                AXIS_LABELS.forEach { label -> AxisBar(label, axes[label] ?: 0f) }
+            }
+            lastInput?.let {
+                Text(
+                    "Last input — $it",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+        }
+
+        Group("Other input devices") {
+            if (others.isEmpty()) {
+                Text(
+                    "None",
+                    style = MaterialTheme.typography.bodyMedium,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+            others.forEach { dev ->
+                Column {
+                    Text(dev.name, style = MaterialTheme.typography.bodyMedium)
+                    Text(
+                        deviceDetail(dev),
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+            }
+        }
+    }
+}
+
+/** One detected gamepad: identity, what it streams as, and a rumble test. */
+@Composable
+private fun PadRow(dev: InputDevice, forwarded: Boolean, gamepadSetting: Int) {
+    OutlinedCard(modifier = Modifier.fillMaxWidth()) {
+        Column(
+            modifier = Modifier.padding(16.dp),
+            verticalArrangement = Arrangement.spacedBy(6.dp),
+        ) {
+            Row(modifier = Modifier.fillMaxWidth(), verticalAlignment = Alignment.CenterVertically) {
+                Text(dev.name, style = MaterialTheme.typography.bodyLarge, modifier = Modifier.weight(1f))
+                if (forwarded) {
+                    Text(
+                        "forwarded to host",
+                        style = MaterialTheme.typography.labelSmall,
+                        color = MaterialTheme.colorScheme.primary,
+                    )
+                }
+            }
+            Text(
+                deviceDetail(dev),
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+            val resolved = Gamepad.prefFor(dev)
+            Text(
+                if (gamepadSetting == Gamepad.PREF_AUTO) {
+                    "Streams as: ${prefLabel(resolved)} (automatic)"
+                } else {
+                    "Streams as: ${prefLabel(gamepadSetting)} (set in Settings; " +
+                        "automatic would pick ${prefLabel(resolved)})"
+                },
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+            val canRumble = dev.vibratorManager.vibratorIds.isNotEmpty()
+            if (canRumble) {
+                OutlinedButton(onClick = { testRumble(dev) }) { Text("Test rumble") }
+            } else {
+                Text(
+                    "No rumble motors reported — host rumble will be silent",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+        }
+    }
+}
+
+/** The forwarded buttons as chips that light up while held. */
+@OptIn(ExperimentalLayoutApi::class)
+@Composable
+private fun ButtonGrid(held: Map<Int, Boolean>) {
+    FlowRow(
+        horizontalArrangement = Arrangement.spacedBy(6.dp),
+        verticalArrangement = Arrangement.spacedBy(6.dp),
+    ) {
+        TEST_BUTTONS.forEach { (label, keyCode) ->
+            val active = held[keyCode] == true
+            Text(
+                label,
+                style = MaterialTheme.typography.labelMedium,
+                color = if (active) MaterialTheme.colorScheme.onPrimary
+                else MaterialTheme.colorScheme.onSurfaceVariant,
+                modifier = Modifier
+                    .background(
+                        if (active) MaterialTheme.colorScheme.primary
+                        else MaterialTheme.colorScheme.surfaceVariant,
+                        RoundedCornerShape(6.dp),
+                    )
+                    .padding(horizontal = 10.dp, vertical = 6.dp),
+            )
+        }
+    }
+}
+
+/** A labelled live axis bar; sticks/HAT are −1..1 (centre = half), triggers 0..1. */
+@Composable
+private fun AxisBar(label: String, value: Float) {
+    val progress = if (label == "LT" || label == "RT") value else (value + 1f) / 2f
+    Row(modifier = Modifier.fillMaxWidth(), verticalAlignment = Alignment.CenterVertically) {
+        Text(label, style = MaterialTheme.typography.labelMedium, modifier = Modifier.width(32.dp))
+        LinearProgressIndicator(
+            progress = { progress.coerceIn(0f, 1f) },
+            modifier = Modifier.weight(1f),
+        )
+        Text(
+            "%+.2f".format(value),
+            style = MaterialTheme.typography.labelSmall,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+            modifier = Modifier.padding(start = 8.dp),
+        )
+    }
+}
+
+/** A titled section — same look as the Settings groups. */
+@Composable
+private fun Group(title: String, content: @Composable ColumnScope.() -> Unit) {
+    Column(verticalArrangement = Arrangement.spacedBy(10.dp)) {
+        Text(
+            title,
+            style = MaterialTheme.typography.titleSmall,
+            color = MaterialTheme.colorScheme.primary,
+            modifier = Modifier.padding(start = 4.dp),
+        )
+        Column(verticalArrangement = Arrangement.spacedBy(12.dp), content = content)
+    }
+}
+
+private fun testRumble(dev: InputDevice) {
+    val vm = dev.vibratorManager
+    if (vm.vibratorIds.isEmpty()) return
+    runCatching {
+        vm.vibrate(CombinedVibration.createParallel(VibrationEffect.createOneShot(300, 200)))
+    }
+}
+
+/** Identity line: VID:PID + the source classes Android assigned. */
+private fun deviceDetail(dev: InputDevice): String =
+    "%04X:%04X · %s".format(dev.vendorId, dev.productId, sourcesLabel(dev.sources))
+
+private fun sourcesLabel(sources: Int): String {
+    fun has(flag: Int) = sources and flag == flag
+    val names = buildList {
+        if (has(InputDevice.SOURCE_GAMEPAD)) add("gamepad")
+        if (has(InputDevice.SOURCE_JOYSTICK)) add("joystick")
+        if (has(InputDevice.SOURCE_DPAD)) add("dpad")
+        if (has(InputDevice.SOURCE_KEYBOARD)) add("keyboard")
+        if (has(InputDevice.SOURCE_MOUSE)) add("mouse")
+        if (has(InputDevice.SOURCE_TOUCHSCREEN)) add("touchscreen")
+        if (has(InputDevice.SOURCE_TOUCHPAD)) add("touchpad")
+        if (has(InputDevice.SOURCE_STYLUS)) add("stylus")
+        if (has(InputDevice.SOURCE_ROTARY_ENCODER)) add("rotary")
+    }
+    return if (names.isEmpty()) "sources 0x%08X".format(sources) else names.joinToString(" · ")
+}
+
+/** [Gamepad] PREF_* wire byte → user-facing label (mirrors GAMEPAD_OPTIONS, plus the Steam types). */
+private fun prefLabel(pref: Int): String = when (pref) {
+    Gamepad.PREF_XBOX360 -> "Xbox 360"
+    Gamepad.PREF_DUALSENSE -> "DualSense"
+    Gamepad.PREF_XBOXONE -> "Xbox One"
+    Gamepad.PREF_DUALSHOCK4 -> "DualShock 4"
+    Gamepad.PREF_STEAMCONTROLLER -> "Steam Controller"
+    Gamepad.PREF_STEAMDECK -> "Steam Deck"
+    else -> "Automatic"
+}
+
+/** Buttons shown in the test grid (label → Android keycode). */
+private val TEST_BUTTONS = listOf(
+    "A" to KeyEvent.KEYCODE_BUTTON_A,
+    "B" to KeyEvent.KEYCODE_BUTTON_B,
+    "X" to KeyEvent.KEYCODE_BUTTON_X,
+    "Y" to KeyEvent.KEYCODE_BUTTON_Y,
+    "LB" to KeyEvent.KEYCODE_BUTTON_L1,
+    "RB" to KeyEvent.KEYCODE_BUTTON_R1,
+    "L2" to KeyEvent.KEYCODE_BUTTON_L2,
+    "R2" to KeyEvent.KEYCODE_BUTTON_R2,
+    "LS" to KeyEvent.KEYCODE_BUTTON_THUMBL,
+    "RS" to KeyEvent.KEYCODE_BUTTON_THUMBR,
+    "Select" to KeyEvent.KEYCODE_BUTTON_SELECT,
+    "Start" to KeyEvent.KEYCODE_BUTTON_START,
+    "Guide" to KeyEvent.KEYCODE_BUTTON_MODE,
+    "↑" to KeyEvent.KEYCODE_DPAD_UP,
+    "↓" to KeyEvent.KEYCODE_DPAD_DOWN,
+    "←" to KeyEvent.KEYCODE_DPAD_LEFT,
+    "→" to KeyEvent.KEYCODE_DPAD_RIGHT,
+)
+
+/** Axis bars shown in the test view, in display order. */
+private val AXIS_LABELS = listOf("LX", "LY", "RX", "RY", "LT", "RT", "HX", "HY")

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

@@ -0,0 +1,66 @@
+package io.unom.punktfunk
+
+import androidx.activity.compose.BackHandler
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.remember
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.unit.dp
+
+/**
+ * Open-source licenses: punktfunk's own license (MIT OR Apache-2.0) plus the third-party software
+ * notices, read from the bundled `THIRD-PARTY-NOTICES.txt` asset (generated by
+ * scripts/gen-third-party-notices.sh). Reached from [SettingsScreen]; Back returns there.
+ */
+@Composable
+fun LicensesScreen(onBack: () -> Unit) {
+    val context = LocalContext.current
+    BackHandler(onBack = onBack)
+
+    val notices = remember {
+        runCatching {
+            context.assets.open("THIRD-PARTY-NOTICES.txt").bufferedReader().use { it.readText() }
+        }.getOrDefault("Third-party notices unavailable.")
+    }
+    val version = remember {
+        runCatching {
+            @Suppress("DEPRECATION")
+            context.packageManager.getPackageInfo(context.packageName, 0).versionName
+        }.getOrNull()
+    }
+
+    Column(
+        modifier = Modifier
+            .fillMaxSize()
+            .verticalScroll(rememberScrollState())
+            .padding(horizontal = 20.dp, vertical = 24.dp),
+        verticalArrangement = Arrangement.spacedBy(16.dp),
+    ) {
+        Text("Open-source licenses", style = MaterialTheme.typography.headlineMedium)
+        if (version != null) {
+            Text(
+                "punktfunk $version",
+                style = MaterialTheme.typography.bodyMedium,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+        }
+        Text(
+            "punktfunk is licensed under MIT OR Apache-2.0, at your option. It uses the open-source " +
+                "components below, each under its own license.",
+            style = MaterialTheme.typography.bodyMedium,
+        )
+        Text(
+            notices,
+            style = MaterialTheme.typography.bodySmall.copy(fontFamily = FontFamily.Monospace),
+        )
+    }
+}

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

@@ -26,6 +26,14 @@ class MainActivity : ComponentActivity() {
     /** Joystick-axis state mapper for the active session (built/reset by StreamScreen). */
     var axisMapper: Gamepad.AxisMapper? = null
 
+    /**
+     * Input observers for the Controllers debug screen (set while it is shown, like [streamHandle]).
+     * Called for every key/motion event while not streaming; a `true` return consumes the event —
+     * the screen's "test inputs" mode uses that to keep pad input from also driving focus navigation.
+     */
+    var padKeyProbe: ((KeyEvent) -> Boolean)? = null
+    var padMotionProbe: ((MotionEvent) -> Boolean)? = null
+
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
         // Dark, transparent system bars regardless of the system theme — our UI is always dark, so
@@ -72,23 +80,29 @@ class MainActivity : ComponentActivity() {
                         KeyEvent.ACTION_UP -> false
                         else -> return super.dispatchKeyEvent(event)
                     }
-                    val vk = Keymap.toVk(event.keyCode)
+                    // Full-event overload: evdev scancode first (positional under ANY selected
+                    // physical-keyboard layout), keycode fallback — see Keymap docs.
+                    val vk = Keymap.toVk(event)
                     if (vk != 0) {
                         NativeBridge.nativeSendKey(handle, vk, down, 0)
                         return true // consumed — don't let the system also act on it
                     }
                 }
             }
-        } else if (event.isFromSource(InputDevice.SOURCE_GAMEPAD)) {
-            // Not streaming: a game controller drives the Compose UI (TV + phone). Map the face
-            // buttons to the navigation keys the focus system understands; D-pad *keys* already move
-            // focus on their own, so they fall through to super untouched.
-            val mapped = when (event.keyCode) {
-                KeyEvent.KEYCODE_BUTTON_A -> KeyEvent.KEYCODE_DPAD_CENTER // activate focused element
-                KeyEvent.KEYCODE_BUTTON_B -> KeyEvent.KEYCODE_BACK // back / dismiss
-                else -> 0
+        } else {
+            // The Controllers debug screen sees pad events before the navigation remap below.
+            padKeyProbe?.let { if (it(event)) return true }
+            if (event.isFromSource(InputDevice.SOURCE_GAMEPAD)) {
+                // Not streaming: a game controller drives the Compose UI (TV + phone). Map the face
+                // buttons to the navigation keys the focus system understands; D-pad *keys* already
+                // move focus on their own, so they fall through to super untouched.
+                val mapped = when (event.keyCode) {
+                    KeyEvent.KEYCODE_BUTTON_A -> KeyEvent.KEYCODE_DPAD_CENTER // activate focused element
+                    KeyEvent.KEYCODE_BUTTON_B -> KeyEvent.KEYCODE_BACK // back / dismiss
+                    else -> 0
+                }
+                if (mapped != 0) return super.dispatchKeyEvent(KeyEvent(event.action, mapped))
             }
-            if (mapped != 0) return super.dispatchKeyEvent(KeyEvent(event.action, mapped))
         }
         return super.dispatchKeyEvent(event)
     }
@@ -101,6 +115,8 @@ class MainActivity : ComponentActivity() {
             if (axisMapper?.onMotion(event) == true) return true
             return super.dispatchGenericMotionEvent(event)
         }
+        // The Controllers debug screen sees pad motion before the stick→D-pad synthesis below.
+        padMotionProbe?.let { if (it(event)) return true }
         // Not streaming: turn the gamepad HAT / left stick into discrete D-pad focus moves, so a
         // controller navigates the menus even when its D-pad reports as axes (not key events) and
         // for stick-based navigation. Edge-detected so a held direction moves focus exactly once.

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

@@ -14,13 +14,38 @@ data class Settings(
     val height: Int = 0,
     val hz: Int = 0,
     val bitrateKbps: Int = 0,
+    /**
+     * Advertise HDR (10-bit BT.2020 PQ) to the host. Default on, but only *effective* on a panel that
+     * can actually present HDR10 (see [displaySupportsHdr]) — on an SDR display HDR is never
+     * advertised regardless, so the host sends a proper 8-bit BT.709 stream rather than PQ the panel
+     * would mis-tone-map. Turning this off forces SDR even on a capable panel.
+     */
+    val hdrEnabled: Boolean = true,
     val compositor: Int = 0,
     val gamepad: Int = 0,
+    /** Requested audio channel count: 2 (stereo), 6 (5.1) or 8 (7.1). The host clamps to what it
+     * can capture; the resolved count drives the decoder + AAudio layout. */
+    val audioChannels: Int = 2,
+    /** Preferred video codec: `"auto"` (host decides), `"hevc"`, or `"h264"`. A soft preference — the
+     * host emits it when it can, else falls back. AMediaCodec decodes whichever the host resolves. */
+    val codec: String = "auto",
     val micEnabled: Boolean = false,
     /** Show the live stats overlay (FPS / throughput / latency) during a stream. */
     val statsHudEnabled: Boolean = true,
+    /**
+     * Touch input model — how touchscreen fingers drive the host. [TouchMode.TRACKPAD] (default):
+     * the cursor stays put on touch-down and moves by the finger's relative delta (swipe to nudge,
+     * lift and re-swipe to walk it across), tap to click where it is. [TouchMode.POINTER]: the
+     * cursor jumps to the finger (direct pointing). [TouchMode.TOUCH]: real multi-touch
+     * passthrough — every finger reaches the host as a touchscreen contact, for apps/games that
+     * understand touch. Mirrors the Apple client's TouchInputMode.
+     */
+    val touchMode: TouchMode = TouchMode.TRACKPAD,
 )
 
+/** [Settings.touchMode] values; persisted by name. */
+enum class TouchMode { TRACKPAD, POINTER, TOUCH }
+
 /** Loads/saves [Settings] in the app-private `punktfunk_settings` prefs. */
 class SettingsStore(context: Context) {
     private val prefs =
@@ -31,10 +56,17 @@ class SettingsStore(context: Context) {
         height = prefs.getInt(K_H, 0),
         hz = prefs.getInt(K_HZ, 0),
         bitrateKbps = prefs.getInt(K_BITRATE, 0),
+        hdrEnabled = prefs.getBoolean(K_HDR, true),
         compositor = prefs.getInt(K_COMPOSITOR, 0),
         gamepad = prefs.getInt(K_GAMEPAD, 0),
+        audioChannels = prefs.getInt(K_AUDIO_CH, 2),
+        codec = prefs.getString(K_CODEC, "auto") ?: "auto",
         micEnabled = prefs.getBoolean(K_MIC, false),
         statsHudEnabled = prefs.getBoolean(K_HUD, true),
+        touchMode = prefs.getString(K_TOUCH_MODE, null)
+            ?.let { name -> TouchMode.entries.firstOrNull { it.name == name } }
+            // Migration: the pre-enum Boolean "trackpad_mode" (true = trackpad, false = direct).
+            ?: if (prefs.getBoolean(K_TRACKPAD, true)) TouchMode.TRACKPAD else TouchMode.POINTER,
     )
 
     fun save(s: Settings) {
@@ -43,10 +75,14 @@ class SettingsStore(context: Context) {
             .putInt(K_H, s.height)
             .putInt(K_HZ, s.hz)
             .putInt(K_BITRATE, s.bitrateKbps)
+            .putBoolean(K_HDR, s.hdrEnabled)
             .putInt(K_COMPOSITOR, s.compositor)
             .putInt(K_GAMEPAD, s.gamepad)
+            .putInt(K_AUDIO_CH, s.audioChannels)
+            .putString(K_CODEC, s.codec)
             .putBoolean(K_MIC, s.micEnabled)
             .putBoolean(K_HUD, s.statsHudEnabled)
+            .putString(K_TOUCH_MODE, s.touchMode.name)
             .apply()
     }
 
@@ -55,10 +91,17 @@ class SettingsStore(context: Context) {
         const val K_H = "height"
         const val K_HZ = "hz"
         const val K_BITRATE = "bitrate_kbps"
+        const val K_HDR = "hdr_enabled"
         const val K_COMPOSITOR = "compositor"
         const val K_GAMEPAD = "gamepad"
+        const val K_AUDIO_CH = "audio_channels"
+        const val K_CODEC = "codec"
         const val K_MIC = "mic_enabled"
         const val K_HUD = "stats_hud_enabled"
+        const val K_TOUCH_MODE = "touch_mode"
+
+        /** Legacy Boolean the enum replaced — read once as the migration default, never written. */
+        const val K_TRACKPAD = "trackpad_mode"
     }
 }
 
@@ -124,6 +167,28 @@ val REFRESH_OPTIONS = listOf(
     240 to "240 Hz",
 )
 
+/** (channel count, label). 2 = stereo (default), 6 = 5.1, 8 = 7.1. */
+val AUDIO_CHANNEL_OPTIONS = listOf(
+    2 to "Stereo",
+    6 to "5.1 Surround",
+    8 to "7.1 Surround",
+)
+
+/** (stored value, label) for the preferred video codec. `"auto"` = host decides. */
+val CODEC_OPTIONS = listOf(
+    "auto" to "Automatic",
+    "hevc" to "HEVC (H.265)",
+    "h264" to "H.264 (AVC)",
+)
+
+/** The [Settings.codec] string as a `quic::CODEC_*` preference byte (`0` = auto). H264=1, HEVC=2. */
+fun Settings.preferredCodec(): Int = when (codec) {
+    "h264" -> 1
+    "hevc" -> 2
+    "av1" -> 4
+    else -> 0
+}
+
 /** (kbps, label). `0` = host default. */
 val BITRATE_OPTIONS = listOf(
     0 to "Automatic",
@@ -142,6 +207,13 @@ val COMPOSITOR_OPTIONS = listOf(
     "gamescope",
 )
 
+/** (mode, label) for the touch-input model. */
+val TOUCH_MODE_OPTIONS = listOf(
+    TouchMode.TRACKPAD to "Trackpad",
+    TouchMode.POINTER to "Direct pointer",
+    TouchMode.TOUCH to "Touch passthrough",
+)
+
 /** index = GamepadPref wire byte (0=Auto 1=Xbox360 2=DualSense 3=XboxOne 4=DualShock4). */
 val GAMEPAD_OPTIONS = listOf(
     "Automatic",

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

@@ -5,6 +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.clickable
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.ColumnScope
@@ -44,6 +45,8 @@ import androidx.core.content.ContextCompat
 fun SettingsScreen(initial: Settings, onChange: (Settings) -> Unit, onBack: () -> Unit) {
     var s by remember { mutableStateOf(initial) }
     val context = LocalContext.current
+    var showLicenses by remember { mutableStateOf(false) }
+    var showControllers by remember { mutableStateOf(false) }
     fun update(next: Settings) {
         s = next
         onChange(next)
@@ -56,6 +59,15 @@ fun SettingsScreen(initial: Settings, onChange: (Settings) -> Unit, onBack: () -
         ActivityResultContracts.RequestPermission(),
     ) { granted -> update(s.copy(micEnabled = granted)) }
 
+    if (showLicenses) {
+        LicensesScreen(onBack = { showLicenses = false })
+        return
+    }
+    if (showControllers) {
+        ControllersScreen(gamepadSetting = s.gamepad, onBack = { showControllers = false })
+        return
+    }
+
     Column(
         modifier = Modifier
             .fillMaxSize()
@@ -87,6 +99,28 @@ fun SettingsScreen(initial: Settings, onChange: (Settings) -> Unit, onBack: () -
                 options = BITRATE_OPTIONS,
                 selected = s.bitrateKbps,
             ) { kbps -> update(s.copy(bitrateKbps = kbps)) }
+
+            SettingDropdown(
+                label = "Video codec",
+                options = CODEC_OPTIONS,
+                selected = s.codec,
+            ) { c -> update(s.copy(codec = c)) }
+
+            // HDR is only meaningful on a panel that can present HDR10; on an SDR display the toggle
+            // is disabled (and HDR is never advertised regardless) so the host doesn't send PQ the
+            // panel would mis-tone-map. The capability is fixed for the device, so read it once.
+            val hdrCapable = remember { displaySupportsHdr(context) }
+            ToggleRow(
+                title = "HDR",
+                subtitle = if (hdrCapable) {
+                    "Stream 10-bit HDR (BT.2020 PQ) when the host supports it"
+                } else {
+                    "This display can't present HDR10 — streams stay SDR"
+                },
+                checked = s.hdrEnabled && hdrCapable,
+                enabled = hdrCapable,
+                onCheckedChange = { on -> update(s.copy(hdrEnabled = on)) },
+            )
         }
 
         SettingsGroup("Host") {
@@ -101,9 +135,21 @@ fun SettingsScreen(initial: Settings, onChange: (Settings) -> Unit, onBack: () -
                 options = GAMEPAD_OPTIONS.mapIndexed { i, lbl -> i to lbl },
                 selected = s.gamepad,
             ) { g -> update(s.copy(gamepad = g)) }
+
+            ClickableRow(
+                title = "Connected controllers",
+                subtitle = "What the app detects, with a live input test",
+                onClick = { showControllers = true },
+            )
         }
 
         SettingsGroup("Audio") {
+            SettingDropdown(
+                label = "Audio channels",
+                options = AUDIO_CHANNEL_OPTIONS,
+                selected = s.audioChannels,
+            ) { ch -> update(s.copy(audioChannels = ch)) }
+
             ToggleRow(
                 title = "Microphone",
                 subtitle = "Send your mic to the host's virtual microphone",
@@ -119,6 +165,24 @@ fun SettingsScreen(initial: Settings, onChange: (Settings) -> Unit, onBack: () -
             )
         }
 
+        SettingsGroup("Touch input") {
+            SettingDropdown(
+                label = "Touch input",
+                options = TOUCH_MODE_OPTIONS,
+                selected = s.touchMode,
+                onSelect = { mode -> update(s.copy(touchMode = mode)) },
+            )
+            Text(
+                "Trackpad: relative cursor like a laptop touchpad — tap to click, two-finger " +
+                    "tap right-clicks, two fingers scroll, tap-then-drag holds the button. " +
+                    "Direct pointer: the cursor jumps to your finger. Touch passthrough: real " +
+                    "multi-touch reaches the host, for apps that understand touch.",
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                modifier = Modifier.padding(top = 6.dp),
+            )
+        }
+
         SettingsGroup("Overlay") {
             ToggleRow(
                 title = "Stats overlay",
@@ -127,6 +191,14 @@ fun SettingsScreen(initial: Settings, onChange: (Settings) -> Unit, onBack: () -
                 onCheckedChange = { on -> update(s.copy(statsHudEnabled = on)) },
             )
         }
+
+        SettingsGroup("About") {
+            ClickableRow(
+                title = "Open-source licenses",
+                subtitle = "Third-party notices and credits",
+                onClick = { showLicenses = true },
+            )
+        }
     }
 }
 
@@ -150,15 +222,41 @@ private fun SettingsGroup(title: String, content: @Composable ColumnScope.() ->
     }
 }
 
-/** A title + subtitle on the left, a Switch on the right. */
+/** A title + subtitle on the left, a Switch on the right. [enabled] greys out the whole row. */
 @Composable
 private fun ToggleRow(
     title: String,
     subtitle: String,
     checked: Boolean,
     onCheckedChange: (Boolean) -> Unit,
+    enabled: Boolean = true,
 ) {
+    // Dim the labels when disabled so the row reads as inactive (the Switch dims itself).
+    val labelAlpha = if (enabled) 1f else 0.38f
     Row(modifier = Modifier.fillMaxWidth(), verticalAlignment = Alignment.CenterVertically) {
+        Column(Modifier.weight(1f)) {
+            Text(
+                title,
+                style = MaterialTheme.typography.bodyLarge,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = labelAlpha),
+            )
+            Text(
+                subtitle,
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant.copy(alpha = labelAlpha),
+            )
+        }
+        Switch(checked = checked, onCheckedChange = onCheckedChange, enabled = enabled)
+    }
+}
+
+/** A title + subtitle on the left; the whole row is clickable (opens a sub-screen). */
+@Composable
+private fun ClickableRow(title: String, subtitle: String, onClick: () -> Unit) {
+    Row(
+        modifier = Modifier.fillMaxWidth().clickable(onClick = onClick),
+        verticalAlignment = Alignment.CenterVertically,
+    ) {
         Column(Modifier.weight(1f)) {
             Text(title, style = MaterialTheme.typography.bodyLarge)
             Text(
@@ -167,7 +265,6 @@ private fun ToggleRow(
                 color = MaterialTheme.colorScheme.onSurfaceVariant,
             )
         }
-        Switch(checked = checked, onCheckedChange = onCheckedChange)
     }
 }
 

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

@@ -0,0 +1,119 @@
+package io.unom.punktfunk
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+import io.unom.punktfunk.kit.NativeBridge
+import kotlin.math.roundToInt
+
+/**
+ * The live stats overlay — the unified HUD (`design/stats-unification.md`, Android v1: headline is
+ * `capture→decoded`, tiled by `host+network` + `decode`). Reads the 18-double layout from
+ * [NativeBridge.nativeVideoStats]:
+ * `[fps, mbps, e2eP50Ms, e2eP95Ms, latValid, skew, w, h, hz, lost, bitDepth, colorPrimaries,
+ * colorTransfer, chromaFormatIdc, hostNetP50Ms, decodeP50Ms, hostP50Ms, netP50Ms]`. Indexes 10–13
+ * (present on a current native lib) describe the negotiated video feed and render as a
+ * codec/depth/colour/chroma line; 14/15 render as the stage equation — split into
+ * `host + network + decode` when the Phase-2 terms at 16/17 are nonzero (a current host sends
+ * per-AU 0xCF timings; an old host leaves them 0 and the combined `host+network` term stands);
+ * older layouts just omit those lines.
+ */
+@Composable
+internal fun StatsOverlay(s: DoubleArray, modifier: Modifier = Modifier) {
+    if (s.size < 10) return
+    val w = s[6].toInt()
+    val h = s[7].toInt()
+    val hz = s[8].toInt()
+    val latValid = s[4] != 0.0
+    val skew = s[5] != 0.0
+    val lost = s[9].toLong()
+    Column(
+        modifier = modifier
+            .background(Color.Black.copy(alpha = 0.45f), RoundedCornerShape(6.dp))
+            .padding(horizontal = 8.dp, vertical = 4.dp),
+    ) {
+        Text(
+            "$w×$h@$hz   ${s[0].roundToInt()} fps   ${"%.1f".format(s[1])} Mb/s",
+            color = Color.White,
+            fontFamily = FontFamily.Monospace,
+            fontSize = 12.sp,
+        )
+        videoFeedLine(s)?.let { feed ->
+            Text(
+                feed,
+                color = Color.White,
+                fontFamily = FontFamily.Monospace,
+                fontSize = 12.sp,
+            )
+        }
+        if (latValid) {
+            val tag = if (skew) "" else " (same-host clock)"
+            Text(
+                "end-to-end ${"%.1f".format(s[2])} ms p50 · ${"%.1f".format(s[3])} p95 · capture→decoded$tag",
+                color = Color.White,
+                fontFamily = FontFamily.Monospace,
+                fontSize = 12.sp,
+            )
+            if (s.size >= 16) {
+                // Phase-2 split (s[16]/s[17]): render `host + network` separately when the host
+                // reported its share this window; otherwise the combined term (old host / no
+                // matched 0xCF timing).
+                val equation = if (s.size >= 18 && s[16] > 0) {
+                    "= host ${"%.1f".format(s[16])} + network ${"%.1f".format(s[17])} + decode ${"%.1f".format(s[15])}"
+                } else {
+                    "= host+network ${"%.1f".format(s[14])} + decode ${"%.1f".format(s[15])}"
+                }
+                Text(
+                    equation,
+                    color = Color.White,
+                    fontFamily = FontFamily.Monospace,
+                    fontSize = 12.sp,
+                )
+            }
+        }
+        if (lost > 0) {
+            Text(
+                "lost $lost",
+                color = Color(0xFFFFB0B0),
+                fontFamily = FontFamily.Monospace,
+                fontSize = 12.sp,
+            )
+        }
+    }
+}
+
+/**
+ * Format the negotiated video-feed descriptor from the trailing four stats doubles
+ * `[bitDepth, colorPrimaries, colorTransfer, chromaFormatIdc]`, e.g.
+ * `HEVC · 10-bit · HDR (BT.2020 PQ) · 4:2:0`. Returns `null` on a pre-video-feed layout (< 14 doubles)
+ * so the overlay simply omits the line. The codes are CICP / H.273: transfer 16 = PQ, 18 = HLG (else
+ * SDR); primaries 9 = BT.2020, 1 = BT.709; chroma_format_idc 1 = 4:2:0, 2 = 4:2:2, 3 = 4:4:4. The
+ * Android decoder is always HEVC (`video/hevc`).
+ */
+private fun videoFeedLine(s: DoubleArray): String? {
+    if (s.size < 14) return null
+    val bitDepth = s[10].toInt()
+    val primaries = s[11].toInt()
+    val transfer = s[12].toInt()
+    val chromaIdc = s[13].toInt()
+    val depthLabel = if (bitDepth > 0) "$bitDepth-bit" else "8-bit"
+    val (dynamicRange, colorSpace) = when (transfer) {
+        16 -> "HDR" to "BT.2020 PQ"
+        18 -> "HDR" to "BT.2020 HLG"
+        else -> "SDR" to if (primaries == 9) "BT.2020" else "BT.709"
+    }
+    val chromaLabel = when (chromaIdc) {
+        3 -> "4:4:4"
+        2 -> "4:2:2"
+        else -> "4:2:0"
+    }
+    return "HEVC · $depthLabel · $dynamicRange ($colorSpace) · $chromaLabel"
+}

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

@@ -1,20 +1,15 @@
 package io.unom.punktfunk
 
 import android.Manifest
+import android.content.pm.ActivityInfo
 import android.content.pm.PackageManager
 import android.view.SurfaceHolder
 import android.view.SurfaceView
 import android.view.WindowManager
 import androidx.activity.compose.BackHandler
-import androidx.compose.foundation.background
-import androidx.compose.foundation.gestures.awaitEachGesture
-import androidx.compose.foundation.gestures.awaitFirstDown
 import androidx.compose.foundation.layout.Box
-import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.padding
-import androidx.compose.foundation.shape.RoundedCornerShape
-import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.LaunchedEffect
@@ -24,12 +19,9 @@ import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
 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.platform.LocalContext
-import androidx.compose.ui.text.font.FontFamily
 import androidx.compose.ui.unit.dp
-import androidx.compose.ui.unit.sp
 import androidx.compose.ui.viewinterop.AndroidView
 import androidx.core.content.ContextCompat
 import androidx.core.view.WindowCompat
@@ -40,15 +32,6 @@ import io.unom.punktfunk.kit.GamepadFeedback
 import io.unom.punktfunk.kit.NativeBridge
 import java.util.concurrent.atomic.AtomicBoolean
 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) {
@@ -65,15 +48,25 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
         Manifest.permission.RECORD_AUDIO,
     ) == PackageManager.PERMISSION_GRANTED
 
-    // Live decode stats for the HUD. Poll once a second for the whole stream (cheap, and each call
-    // drains+resets the native window so it never grows unbounded even while the overlay is hidden);
-    // `showStats` only gates rendering. A 3-finger tap toggles it live; the default comes from Settings.
+    // Live decode stats for the HUD. `showStats` gates the whole pipeline: the native per-frame
+    // sampling (nativeSetVideoStatsEnabled — hidden HUD costs one atomic load per frame) AND the
+    // 1 s poll loop, which only runs while the overlay is visible. Enabling resets the native
+    // window, so re-showing never renders stale data. A 3-finger tap toggles it live; the default
+    // comes from Settings.
+    val initialSettings = remember { SettingsStore(context).load() }
     var stats by remember { mutableStateOf<DoubleArray?>(null) }
-    var showStats by remember { mutableStateOf(SettingsStore(context).load().statsHudEnabled) }
-    LaunchedEffect(handle) {
-        while (true) {
-            delay(1000)
-            stats = NativeBridge.nativeVideoStats(handle)
+    var showStats by remember { mutableStateOf(initialSettings.statsHudEnabled) }
+    // Touch model is fixed per session (re-keys the gesture handler below if it ever changes).
+    val touchMode = initialSettings.touchMode
+    LaunchedEffect(handle, showStats) {
+        NativeBridge.nativeSetVideoStatsEnabled(handle, showStats)
+        if (showStats) {
+            while (true) {
+                delay(1000)
+                stats = NativeBridge.nativeVideoStats(handle)
+            }
+        } else {
+            stats = null // drop the last snapshot so a re-show never flashes stale numbers
         }
     }
 
@@ -89,6 +82,13 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
             it.systemBarsBehavior = WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE
             it.hide(WindowInsetsCompat.Type.systemBars())
         }
+        // Lock to landscape while streaming — the host streams a landscape desktop, so pin the device
+        // there (either landscape direction is fine) and stop it rotating to portrait mid-session. The
+        // activity declares configChanges=orientation, so this re-lays out the surface in place without
+        // recreating the activity (no stream restart). On TV (fixed landscape) it's a harmless no-op.
+        // The prior request is captured and restored on the way out.
+        val priorOrientation = activity?.requestedOrientation
+        activity?.requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE
         activity?.streamHandle = handle // route hardware keys to this session
         activity?.axisMapper = Gamepad.AxisMapper(handle) // route joystick axes
         // Host→client feedback (rumble + DualSense lightbar/LEDs); poll threads stopped before close.
@@ -101,6 +101,9 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
             activity?.streamHandle = 0L
             controller?.show(WindowInsetsCompat.Type.systemBars())
             window?.clearFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
+            // Release the landscape lock so the rest of the app follows the device/system again.
+            activity?.requestedOrientation =
+                priorOrientation ?: ActivityInfo.SCREEN_ORIENTATION_UNSPECIFIED
             // Leaving the stream: stop the mic + audio + decode threads and tear down the session.
             NativeBridge.nativeStopMic(handle)
             NativeBridge.nativeStopAudio(handle)
@@ -145,156 +148,19 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
         if (showStats) {
             stats?.let { StatsOverlay(it, Modifier.align(Alignment.TopStart).padding(12.dp)) }
         }
-        // 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.
+        // Touch input per the Settings model: trackpad/direct-pointer mouse (the shared gesture
+        // vocabulary) or real multi-touch passthrough — see TouchInput.kt.
         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(
+            Modifier.fillMaxSize().pointerInput(handle, touchMode) {
+                when (touchMode) {
+                    TouchMode.TOUCH -> streamTouchPassthrough(handle)
+                    else -> streamTouchInput(
                         handle,
-                        x.coerceIn(0f, (sw - 1).toFloat()).roundToInt(),
-                        y.coerceIn(0f, (sh - 1).toFloat()).roundToInt(),
-                        sw,
-                        sh,
+                        trackpad = touchMode == TouchMode.TRACKPAD,
+                        onToggleStats = { showStats = !showStats },
                     )
                 }
-                awaitEachGesture {
-                    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 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 (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)
-                                lastTapUp = upTime
-                                lastTapX = startX
-                                lastTapY = startY
-                            }
-                        }
-                    }
-                }
             },
         )
     }
 }
-
-/**
- * The live stats overlay — mirrors the Apple client's HUD. Reads the 10-double layout from
- * [NativeBridge.nativeVideoStats]:
- * `[fps, mbps, latP50Ms, latP95Ms, latValid, skew, w, h, hz, dropped]`.
- */
-@Composable
-private fun StatsOverlay(s: DoubleArray, modifier: Modifier = Modifier) {
-    if (s.size < 10) return
-    val w = s[6].toInt()
-    val h = s[7].toInt()
-    val hz = s[8].toInt()
-    val latValid = s[4] != 0.0
-    val skew = s[5] != 0.0
-    val dropped = s[9].toLong()
-    Column(
-        modifier = modifier
-            .background(Color.Black.copy(alpha = 0.45f), RoundedCornerShape(6.dp))
-            .padding(horizontal = 8.dp, vertical = 4.dp),
-    ) {
-        Text(
-            "$w×$h@$hz   ${s[0].roundToInt()} fps   ${"%.1f".format(s[1])} Mb/s",
-            color = Color.White,
-            fontFamily = FontFamily.Monospace,
-            fontSize = 12.sp,
-        )
-        if (latValid) {
-            val tag = if (skew) "" else " (same-host)"
-            Text(
-                "capture→client ${"%.1f".format(s[2])}/${"%.1f".format(s[3])} ms p50/p95$tag",
-                color = Color.White,
-                fontFamily = FontFamily.Monospace,
-                fontSize = 12.sp,
-            )
-        }
-        if (dropped > 0) {
-            Text(
-                "dropped $dropped",
-                color = Color(0xFFFFB0B0),
-                fontFamily = FontFamily.Monospace,
-                fontSize = 12.sp,
-            )
-        }
-    }
-}

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

@@ -10,7 +10,9 @@ import androidx.compose.ui.platform.LocalContext
 
 // punktfunk brand violets (from the app icon: #6C5BF3 / #A79FF8 / #D2C9FB on a #16132A indigo).
 // Used as the fallback dark scheme on pre-Android-12 devices; on 12+ we defer to Material You.
-private val BrandDark = darkColorScheme(
+// `internal` (not private) so the CI screenshot tests can force the deterministic brand palette —
+// Material You dynamic colour has no wallpaper to seed from under the Robolectric JVM renderer.
+internal val BrandDark = darkColorScheme(
     primary = Color(0xFFA79FF8),
     onPrimary = Color(0xFF1B1442),
     primaryContainer = Color(0xFF4C3FB3),

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

@@ -0,0 +1,236 @@
+package io.unom.punktfunk
+
+import androidx.compose.foundation.gestures.awaitEachGesture
+import androidx.compose.foundation.gestures.awaitFirstDown
+import androidx.compose.ui.input.pointer.PointerId
+import androidx.compose.ui.input.pointer.PointerInputScope
+import androidx.compose.ui.input.pointer.changedToDownIgnoreConsumed
+import androidx.compose.ui.input.pointer.changedToUpIgnoreConsumed
+import androidx.compose.ui.input.pointer.positionChanged
+import io.unom.punktfunk.kit.NativeBridge
+import kotlin.math.abs
+import kotlin.math.hypot
+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
+
+// Trackpad-mode pointer ballistics (relative one-finger motion). POINTER_SENS: base finger-px →
+// host-px gain (~1:1, never twitchy). The rest is mild acceleration so a flick crosses the screen
+// while a slow drag stays precise: above ACCEL_SPEED_FLOOR px/ms the gain ramps by ACCEL_GAIN per
+// px/ms, capped at ACCEL_MAX (so a fast swipe can't fling the cursor uncontrollably).
+private const val POINTER_SENS = 1.3f
+private const val ACCEL_GAIN = 0.6f
+private const val ACCEL_SPEED_FLOOR = 0.3f
+private const val ACCEL_MAX = 3.0f
+
+/**
+ * Touch → mouse, run inside the stream overlay's `pointerInput`. Two models, chosen by the
+ * Trackpad-mode setting:
+ *  * trackpad (default): the cursor STAYS where it is on touch-down and moves by the finger's
+ *    relative delta (MouseMove) with mild pointer acceleration — swipe to nudge, lift and
+ *    re-swipe to walk it across, tap to click where it is. This is what makes the cursor
+ *    reachable on a small screen.
+ *  * direct (opt-out): the cursor jumps to the finger and follows it (MouseMoveAbs,
+ *    host-normalized against the overlay size), the old "direct pointing" behaviour.
+ *
+ * Both share the same gesture vocabulary: 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 = [onToggleStats] (the stats HUD).
+ */
+/**
+ * Real multi-touch passthrough ([TouchMode.TOUCH]): every finger forwards as a host touchscreen
+ * contact (down/move/up with a stable per-finger id), with NO gesture interpretation — taps,
+ * drags and multi-finger input mean whatever the remote app decides. Coordinates are overlay
+ * pixels with the overlay size as the surface, exactly like the absolute-mouse path (the host
+ * normalizes and maps into the output). On teardown (stream leaves composition) every still-held
+ * contact is lifted so nothing stays stuck on the host.
+ */
+internal suspend fun PointerInputScope.streamTouchPassthrough(handle: Long) {
+    val ids = mutableMapOf<PointerId, Int>()
+    fun alloc(p: PointerId): Int {
+        var id = 0
+        while (ids.containsValue(id)) id++
+        ids[p] = id
+        return id
+    }
+    try {
+        awaitPointerEventScope {
+            while (true) {
+                val ev = awaitPointerEvent()
+                val sw = size.width
+                val sh = size.height
+                if (sw <= 0 || sh <= 0) continue
+                for (c in ev.changes) {
+                    val x = c.position.x.roundToInt().coerceIn(0, sw - 1)
+                    val y = c.position.y.roundToInt().coerceIn(0, sh - 1)
+                    when {
+                        c.changedToDownIgnoreConsumed() ->
+                            NativeBridge.nativeSendTouch(handle, alloc(c.id), 0, x, y, sw, sh)
+                        c.changedToUpIgnoreConsumed() ->
+                            ids.remove(c.id)?.let {
+                                NativeBridge.nativeSendTouch(handle, it, 2, 0, 0, sw, sh)
+                            }
+                        c.positionChanged() ->
+                            ids[c.id]?.let {
+                                NativeBridge.nativeSendTouch(handle, it, 1, x, y, sw, sh)
+                            }
+                    }
+                    c.consume()
+                }
+            }
+        }
+    } finally {
+        // Lift anything still down (composition/session teardown mid-touch).
+        ids.values.forEach { NativeBridge.nativeSendTouch(handle, it, 2, 0, 0, 1, 1) }
+    }
+}
+
+internal suspend fun PointerInputScope.streamTouchInput(
+    handle: Long,
+    trackpad: Boolean,
+    onToggleStats: () -> Unit,
+) {
+    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 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
+        // Direct mode jumps the cursor to the finger; trackpad mode leaves it put (the
+        // whole point — you nudge it with swipes instead).
+        if (!trackpad) moveAbs(startX, startY)
+        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
+        // Trackpad relative-motion state: the tracked finger, its last position/time, and
+        // the sub-pixel remainder so a slow drag isn't lost to Int truncation.
+        var trackId = down.id
+        var prevX = startX
+        var prevY = startY
+        var prevT = down.uptimeMillis
+        var accX = 0f
+        var accY = 0f
+
+        while (true) {
+            val ev = awaitPointerEvent()
+            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 (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
+                }
+                if (trackpad) {
+                    // Relative: move by the finger delta × (sensitivity × acceleration),
+                    // carrying the sub-pixel remainder. Re-anchor (zero delta this frame)
+                    // if the tracked finger changed, so lifting one of several fingers
+                    // never jumps the cursor.
+                    if (p.id != trackId) {
+                        trackId = p.id
+                        prevX = p.position.x
+                        prevY = p.position.y
+                        prevT = p.uptimeMillis
+                    }
+                    val dx = p.position.x - prevX
+                    val dy = p.position.y - prevY
+                    val dt = (p.uptimeMillis - prevT).coerceAtLeast(1L)
+                    prevX = p.position.x
+                    prevY = p.position.y
+                    prevT = p.uptimeMillis
+                    val speed = hypot(dx, dy) / dt // finger px per ms
+                    val accel = (1f + ACCEL_GAIN * (speed - ACCEL_SPEED_FLOOR).coerceAtLeast(0f))
+                        .coerceAtMost(ACCEL_MAX)
+                    accX += dx * POINTER_SENS * accel
+                    accY += dy * POINTER_SENS * accel
+                    val outX = accX.toInt() // truncates toward zero → remainder kept w/ sign
+                    val outY = accY.toInt()
+                    if (outX != 0 || outY != 0) {
+                        NativeBridge.nativeSendPointerMove(handle, outX, outY)
+                        accX -= outX
+                        accY -= outY
+                    }
+                } else {
+                    moveAbs(p.position.x, p.position.y) // direct: cursor follows the finger
+                }
+            }
+            ev.changes.forEach { it.consume() }
+        }
+
+        if (isDrag) {
+            NativeBridge.nativeSendPointerButton(handle, 1, false) // end the drag
+        } else if (!moved) {
+            when {
+                maxFingers >= 3 -> onToggleStats() // 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 (at the cursor's current spot), arm tap-drag
+                    NativeBridge.nativeSendPointerButton(handle, 1, true)
+                    NativeBridge.nativeSendPointerButton(handle, 1, false)
+                    lastTapUp = upTime
+                    lastTapX = startX
+                    lastTapY = startY
+                }
+            }
+        }
+    }
+}

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

@@ -60,6 +60,7 @@ fun HostCard(
     onConnect: () -> Unit,
     onForget: (() -> Unit)?,
     onRename: (() -> Unit)? = null,
+    onWake: (() -> 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.
@@ -107,7 +108,7 @@ fun HostCard(
                 StatusPill(status)
             }
 
-            if (onForget != null || onRename != null) {
+            if (onForget != null || onRename != null || onWake != null) {
                 var menu by remember { mutableStateOf(false) }
                 Box(modifier = Modifier.align(Alignment.TopEnd)) {
                     IconButton(enabled = enabled, onClick = { menu = true }) {
@@ -119,6 +120,15 @@ fun HostCard(
                         )
                     }
                     DropdownMenu(expanded = menu, onDismissRequest = { menu = false }) {
+                        if (onWake != null) {
+                            DropdownMenuItem(
+                                text = { Text("Wake host") },
+                                onClick = {
+                                    menu = false
+                                    onWake()
+                                },
+                            )
+                        }
                         if (onRename != null) {
                             DropdownMenuItem(
                                 text = { Text("Rename") },

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

@@ -14,8 +14,10 @@ enum class Tab(val label: String, val icon: ImageVector) {
 /**
  * A trust decision awaiting the user before a connect proceeds. [name] is the label to save the
  * host under. Trust-on-first-use ([Kind.TRUST_NEW]) is only ever offered when the host ADVERTISED
- * pair=optional; a pair=required host or a manually-typed/unknown-policy host goes straight to PIN
- * pairing ([Kind.PAIR]), and a changed fingerprint forces re-pairing — never a silent re-trust.
+ * pair=optional; a pair=required host or a manually-typed/unknown-policy host is offered the
+ * two ways in ([Kind.REQUEST_ACCESS]): a no-PIN "request access" connect the operator approves in
+ * the host's console, or the SPAKE2 PIN ceremony ([Kind.PAIR]). A changed fingerprint forces
+ * re-pairing by PIN ([Kind.FP_CHANGED]) — never a silent re-trust.
  */
 data class PendingTrust(
     val host: String,
@@ -24,7 +26,7 @@ data class PendingTrust(
     val advertisedFp: String?,
     val kind: Kind,
 ) {
-    enum class Kind { TRUST_NEW, FP_CHANGED, PAIR }
+    enum class Kind { TRUST_NEW, FP_CHANGED, PAIR, REQUEST_ACCESS }
 }
 
 /** Trust state of a host, shown as a colored pill on its card. */

clients/android/app/src/test/kotlin/io/unom/punktfunk/screenshots/ScreenshotTest.kt

@@ -0,0 +1,74 @@
+package io.unom.punktfunk.screenshots
+
+import androidx.activity.ComponentActivity
+import androidx.compose.ui.test.junit4.createAndroidComposeRule
+import androidx.compose.ui.test.onRoot
+import com.github.takahirom.roborazzi.captureRoboImage
+import com.github.takahirom.roborazzi.captureScreenRoboImage
+import org.junit.Rule
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+import org.robolectric.annotation.GraphicsMode
+
+/**
+ * App-store / marketing screenshots of the native Android client, rendered on the JVM by Roborazzi
+ * (Robolectric Native Graphics) — no emulator, GPU, host, or JNI core. The scenes (ShotScenes.kt)
+ * render the REAL Compose UI with mock state.
+ *
+ * `sdk = [36]` is mandatory: Robolectric ships android-all jars only up to API 36 (Android 16), and
+ * the app's compileSdk is 37. PNGs land in build/outputs/roborazzi/.
+ */
+@RunWith(RobolectricTestRunner::class)
+@GraphicsMode(GraphicsMode.Mode.NATIVE)
+@Config(sdk = [36], qualifiers = "w360dp-h800dp-xxhdpi")
+class ScreenshotTest {
+    @get:Rule
+    val compose = createAndroidComposeRule<ComponentActivity>()
+
+    private val out = "build/outputs/roborazzi"
+
+    // Pausing the animation clock before composing (then advancing once past the entrance animation
+    // and freezing) is what makes a text-field-bearing scene capturable: a focused field blinks its
+    // cursor via an infinite animation that otherwise keeps Compose perpetually "busy", so
+    // setContent's wait-for-idle never returns. Frozen, the capture is also deterministic.
+
+    /** Full-screen content scenes: the compose root fills the device, so a root capture is the shot. */
+    private fun shootRoot(name: String, content: @androidx.compose.runtime.Composable () -> Unit) {
+        compose.mainClock.autoAdvance = false
+        compose.setContent { ShotTheme(content) }
+        compose.mainClock.advanceTimeBy(800)
+        compose.onRoot().captureRoboImage("$out/phone-$name.png")
+    }
+
+    /** Dialog scenes: the AlertDialog is a separate window, so capture the whole screen (all windows). */
+    private fun shootScreen(name: String, content: @androidx.compose.runtime.Composable () -> Unit) {
+        compose.mainClock.autoAdvance = false
+        compose.setContent { ShotTheme(content) }
+        compose.mainClock.advanceTimeBy(800)
+        captureScreenRoboImage("$out/phone-$name.png")
+    }
+
+    @Test
+    fun hosts() = shootRoot("hosts") { HostsScene() }
+
+    @Test
+    fun settings() = shootRoot("settings") { SettingsScene() }
+
+    @Test
+    @Config(sdk = [36], qualifiers = "w800dp-h360dp-xxhdpi") // landscape — the stream is immersive
+    fun stream() = shootRoot("stream") { StreamScene() }
+
+    @Test
+    fun trust() = shootScreen("trust") {
+        HostsScene()
+        TrustDialog()
+    }
+
+    @Test
+    fun pair() = shootScreen("pair") {
+        HostsScene()
+        PairDialog()
+    }
+}

clients/android/app/src/test/kotlin/io/unom/punktfunk/screenshots/ShotScenes.kt

@@ -0,0 +1,198 @@
+package io.unom.punktfunk.screenshots
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.lazy.grid.GridCells
+import androidx.compose.foundation.lazy.grid.GridItemSpan
+import androidx.compose.foundation.lazy.grid.LazyVerticalGrid
+import androidx.compose.foundation.lazy.grid.items
+import androidx.compose.material3.AlertDialog
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Brush
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.unit.dp
+import io.unom.punktfunk.BrandDark
+import io.unom.punktfunk.Settings
+import io.unom.punktfunk.TouchMode
+import io.unom.punktfunk.SettingsScreen
+import io.unom.punktfunk.StatsOverlay
+import io.unom.punktfunk.components.HostCard
+import io.unom.punktfunk.components.SectionLabel
+import io.unom.punktfunk.models.HostStatus
+
+// The CI screenshot scenes: the REAL app composables, fed embedded mock state, under the forced
+// brand palette (Material You has no wallpaper to seed from on the JVM). The stream-video surface
+// and ConnectScreen/App are intentionally absent — they require the live JNI core / a session.
+
+/** Forces the deterministic punktfunk brand scheme (see Theme.kt) instead of dynamic colour. */
+@Composable
+internal fun ShotTheme(content: @Composable () -> Unit) {
+    MaterialTheme(colorScheme = BrandDark, content = content)
+}
+
+private data class MockHost(val name: String, val address: String, val status: HostStatus)
+
+private val SAVED = listOf(
+    MockHost("Living Room PC", "192.168.1.42:9777", HostStatus.PAIRED),
+    MockHost("Office", "192.168.1.50:9777", HostStatus.TOFU),
+)
+private val DISCOVERED = listOf(
+    MockHost("studio-deck", "192.168.1.61:9777", HostStatus.PAIRING),
+    MockHost("HTPC", "192.168.1.70:9777", HostStatus.TOFU),
+)
+
+/** The connect screen's host grid, reconstructed from the real HostCard/SectionLabel components. */
+@Composable
+internal fun HostsScene() {
+    Surface(Modifier.fillMaxSize(), color = MaterialTheme.colorScheme.background) {
+        LazyVerticalGrid(
+            columns = GridCells.Adaptive(minSize = 160.dp),
+            modifier = Modifier.fillMaxSize(),
+            contentPadding = androidx.compose.foundation.layout.PaddingValues(16.dp),
+            horizontalArrangement = Arrangement.spacedBy(8.dp),
+            verticalArrangement = Arrangement.spacedBy(8.dp),
+        ) {
+            item(span = { GridItemSpan(maxLineSpan) }) {
+                Column(
+                    horizontalAlignment = Alignment.CenterHorizontally,
+                    modifier = Modifier.fillMaxWidth(),
+                ) {
+                    Spacer(Modifier.height(8.dp))
+                    Text("Punktfunk", style = MaterialTheme.typography.headlineLarge)
+                    Text(
+                        "stream a remote desktop",
+                        style = MaterialTheme.typography.bodyMedium,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                    Spacer(Modifier.height(24.dp))
+                }
+            }
+            item(span = { GridItemSpan(maxLineSpan) }) { SectionLabel("Saved hosts") }
+            items(SAVED) { h ->
+                HostCard(h.name, h.address, h.status, enabled = true, onConnect = {}, onForget = {}, onRename = {})
+            }
+            item(span = { GridItemSpan(maxLineSpan) }) {
+                Spacer(Modifier.height(12.dp))
+                SectionLabel("Discovered on the network")
+            }
+            items(DISCOVERED) { h ->
+                HostCard(h.name, h.address, h.status, enabled = true, onConnect = {}, onForget = null)
+            }
+        }
+    }
+}
+
+/** The real SettingsScreen, fed a representative non-default Settings. */
+@Composable
+internal fun SettingsScene() {
+    Surface(Modifier.fillMaxSize(), color = MaterialTheme.colorScheme.background) {
+        SettingsScreen(
+            initial = Settings(
+                width = 1920,
+                height = 1080,
+                hz = 120,
+                bitrateKbps = 50_000,
+                compositor = 1,
+                gamepad = 2,
+                micEnabled = true,
+                statsHudEnabled = true,
+                touchMode = TouchMode.TRACKPAD,
+            ),
+            onChange = {},
+            onBack = {},
+        )
+    }
+}
+
+/** The real TOFU AlertDialog (mirrors ConnectScreen's PendingTrust.Kind.TRUST_NEW), shown over the host grid. */
+@Composable
+internal fun TrustDialog() {
+    AlertDialog(
+        onDismissRequest = {},
+        title = { Text("Trust this host?") },
+        text = {
+            Column {
+                Text("First connection to 192.168.1.61:9777.")
+                Text("Fingerprint 9f8e7d6c5b4a3928…")
+                Text(
+                    "This host allows trust-on-first-use, but that can't tell an impostor " +
+                        "from the real host. Pairing with a PIN is stronger — it proves both sides.",
+                )
+            }
+        },
+        confirmButton = { TextButton({}) { Text("Trust (TOFU)") } },
+        dismissButton = { TextButton({}) { Text("Pair with PIN…") } },
+    )
+}
+
+/** The PIN-pairing AlertDialog (mirrors ConnectScreen's PendingTrust.Kind.PAIR). The live screen
+ *  uses OutlinedTextFields, but a TextField inside a Dialog window never reaches idle under
+ *  Robolectric (its focus/cursor machinery animates forever) — so the PIN is shown as a static
+ *  display here, which also reads better in a marketing shot. */
+@Composable
+internal fun PairDialog() {
+    AlertDialog(
+        onDismissRequest = {},
+        title = { Text("Pair with PIN") },
+        text = {
+            Column {
+                Text("Enter the 4-digit PIN shown on the host.")
+                Spacer(Modifier.height(16.dp))
+                Surface(
+                    color = MaterialTheme.colorScheme.surfaceVariant,
+                    shape = MaterialTheme.shapes.medium,
+                    modifier = Modifier.fillMaxWidth(),
+                ) {
+                    Text(
+                        "4  8  2  7",
+                        style = MaterialTheme.typography.headlineMedium,
+                        textAlign = TextAlign.Center,
+                        modifier = Modifier.fillMaxWidth().padding(vertical = 16.dp),
+                    )
+                }
+                Spacer(Modifier.height(12.dp))
+                Text(
+                    "This device: Pixel 9 Pro",
+                    style = MaterialTheme.typography.bodyMedium,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+        },
+        confirmButton = { TextButton({}) { Text("Pair") } },
+        dismissButton = { TextButton({}) { Text("Cancel") } },
+    )
+}
+
+/** The live stats HUD (the real StatsOverlay) over a synthetic "streamed frame" gradient. */
+@Composable
+internal fun StreamScene() {
+    Box(
+        Modifier
+            .fillMaxSize()
+            .background(
+                Brush.linearGradient(listOf(Color(0xFF2A1E5C), Color(0xFF0E1B3D), Color(0xFF06122B))),
+            ),
+    ) {
+        // [fps, mbps, latP50, latP95, latValid, skew, w, h, hz, dropped,
+        //  bitDepth, colorPrimaries, colorTransfer, chromaFormatIdc] — the last four = a 10-bit
+        //  BT.2020 PQ (HDR) 4:2:0 feed, so the HUD renders its video-feed line.
+        StatsOverlay(
+            doubleArrayOf(238.0, 921.4, 1.3, 2.1, 1.0, 1.0, 5120.0, 1440.0, 240.0, 0.0, 10.0, 9.0, 16.0, 1.0),
+            Modifier.align(Alignment.TopStart).padding(12.dp),
+        )
+    }
+}

clients/android/ci/play-upload.py

@@ -37,13 +37,30 @@ def call(method, url, token=None, data=None, content_type=None, want_json=True):
         headers["Authorization"] = f"Bearer {token}"
     if content_type:
         headers["Content-Type"] = content_type
-    req = urllib.request.Request(url, data=data, method=method, headers=headers)
-    try:
-        with urllib.request.urlopen(req, timeout=300) as r:
-            body = r.read()
-    except urllib.error.HTTPError as e:
-        raise ApiError(e.code, method, url, e.read().decode("utf-8", "replace"))
-    return json.loads(body) if (want_json and body) else body
+    # Transient-fault retries: googleapis.com occasionally drops the TLS session ("EOF
+    # occurred in violation of protocol" — failed two release uploads on 2026-07-02) or
+    # answers 5xx. Retry those with backoff; 4xx raises immediately (a real API error).
+    # The edits API is transactional until commit, so re-sending any of these is safe.
+    last = None
+    for attempt in range(4):
+        if attempt:
+            delay = 3**attempt
+            print(f"transient Play API failure ({last}); retry {attempt}/3 in {delay}s")
+            time.sleep(delay)
+        req = urllib.request.Request(url, data=data, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=300) as r:
+                body = r.read()
+            return json.loads(body) if (want_json and body) else body
+        except urllib.error.HTTPError as e:
+            if e.code >= 500:
+                last = f"HTTP {e.code}"
+                continue
+            raise ApiError(e.code, method, url, e.read().decode("utf-8", "replace"))
+        except urllib.error.URLError as e:
+            last = str(getattr(e, "reason", e))
+            continue
+    sys.exit(f"ERROR: {method} {url} still failing after retries: {last}")
 
 
 def load_sa():

clients/android/kit/build.gradle.kts

@@ -99,6 +99,12 @@ val cargoNdkDebug = registerCargoNdk("cargoNdkDebug", release = false)
 val cargoNdkRelease = registerCargoNdk("cargoNdkRelease", release = true)
 
 afterEvaluate {
-    tasks.named("preDebugBuild").configure { dependsOn(cargoNdkDebug) }
-    tasks.named("preReleaseBuild").configure { dependsOn(cargoNdkRelease) }
+    // `-PskipRustBuild` skips the cargo-ndk native build — for JVM-only tasks (the Roborazzi
+    // screenshot unit tests render Compose on the JVM and never load libpunktfunk_android.so), so
+    // CI/local screenshot runs don't need the Rust toolchain or NDK. The native build stays wired
+    // for every normal APK/AAR build.
+    if (!project.hasProperty("skipRustBuild")) {
+        tasks.named("preDebugBuild").configure { dependsOn(cargoNdkDebug) }
+        tasks.named("preReleaseBuild").configure { dependsOn(cargoNdkRelease) }
+    }
 }

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

@@ -50,15 +50,25 @@ object Gamepad {
     const val PREF_DUALSENSE = 2
     const val PREF_XBOXONE = 3
     const val PREF_DUALSHOCK4 = 4
+    const val PREF_STEAMCONTROLLER = 5
+    const val PREF_STEAMDECK = 6
 
     // USB vendor ids of the controllers we can identify by VID/PID.
     private const val VID_SONY = 0x054C
     private const val VID_MICROSOFT = 0x045E
+    private const val VID_VALVE = 0x28DE
 
     // Sony product ids. DualSense (PS5) and DualShock 4 (PS4) map to distinct host pad types.
     private val PID_DUALSENSE = setOf(0x0CE6, 0x0DF2)
     private val PID_DUALSHOCK4 = setOf(0x05C4, 0x09CC)
 
+    // Valve: Steam Deck built-in controller (0x1205); classic Steam Controller wired (0x1102) /
+    // dongle (0x1142). The host builds the virtual hid-steam pad; rich-input capture (paddles /
+    // trackpads / gyro) is out of scope on Android (no rich-input plane yet), so only the standard
+    // buttons + sticks reach the host for now — parity with the desktop type resolution.
+    private val PID_STEAMDECK = setOf(0x1205)
+    private val PID_STEAMCONTROLLER = setOf(0x1102, 0x1142)
+
     // Microsoft Xbox One / Series product ids (wired + the common Bluetooth/dongle revisions). All
     // behave like Xbox 360 on the host minus the glyph identity, so they share one pref byte.
     private val PID_XBOXONE = setOf(
@@ -82,24 +92,26 @@ object Gamepad {
             vid == VID_SONY && pid in PID_DUALSENSE -> PREF_DUALSENSE
             vid == VID_SONY && pid in PID_DUALSHOCK4 -> PREF_DUALSHOCK4
             vid == VID_MICROSOFT && pid in PID_XBOXONE -> PREF_XBOXONE
+            vid == VID_VALVE && pid in PID_STEAMDECK -> PREF_STEAMDECK
+            vid == VID_VALVE && pid in PID_STEAMCONTROLLER -> PREF_STEAMCONTROLLER
             else -> PREF_XBOX360
         }
     }
 
-    /** First connected gamepad/joystick [InputDevice], or null when none is attached. */
-    fun firstPad(): InputDevice? {
-        for (id in InputDevice.getDeviceIds()) {
-            val d = InputDevice.getDevice(id) ?: continue
-            val s = d.sources
-            if (s and InputDevice.SOURCE_GAMEPAD == InputDevice.SOURCE_GAMEPAD ||
-                s and InputDevice.SOURCE_JOYSTICK == InputDevice.SOURCE_JOYSTICK
-            ) {
-                return d
-            }
-        }
-        return null
+    /** True when [dev]'s source classes include gamepad or joystick. */
+    fun isPad(dev: InputDevice?): Boolean {
+        val s = dev?.sources ?: return false
+        return s and InputDevice.SOURCE_GAMEPAD == InputDevice.SOURCE_GAMEPAD ||
+            s and InputDevice.SOURCE_JOYSTICK == InputDevice.SOURCE_JOYSTICK
     }
 
+    /** All connected gamepad/joystick [InputDevice]s, in system enumeration order. */
+    fun pads(): List<InputDevice> =
+        InputDevice.getDeviceIds().toList().mapNotNull { InputDevice.getDevice(it) }.filter { isPad(it) }
+
+    /** First connected gamepad/joystick [InputDevice], or null when none is attached. */
+    fun firstPad(): InputDevice? = pads().firstOrNull()
+
     /**
      * The [GamepadPref] wire byte to send for the user's [setting] (the persisted gamepad index). A
      * non-Auto setting is passed through unchanged; "Automatic" ([PREF_AUTO]) resolves to a concrete

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

@@ -3,13 +3,79 @@ package io.unom.punktfunk.kit
 import android.view.KeyEvent
 
 /**
- * Android `KEYCODE_*` → Windows Virtual-Key code (the punktfunk wire contract; the host maps VK →
- * evdev via `inject::vk_to_evdev`). The Android analogue of the Linux client's evdev→VK table
- * (`punktfunk-client-linux/src/keymap.rs`) and the Apple client's `hidToVK`. Positional/US-layout —
- * we forward the physical key, not the typed character. Unmapped keys → 0 (the Rust side drops them).
- * Extend this alongside `punktfunk-host/src/inject.rs::vk_to_evdev` (emit only VKs the host knows).
+ * Hardware key → Windows Virtual-Key code (the punktfunk wire contract: **US-positional** — we
+ * forward the physical key, not the typed character; the host maps VK → evdev via
+ * `inject::vk_to_evdev`). The Android analogue of the Linux client's evdev→VK table
+ * (`punktfunk-client-linux/src/keymap.rs`) and the Apple client's `hidToVK`.
+ *
+ * Prefer [toVk] with the full [KeyEvent]: it reads the raw evdev scancode first, because
+ * `KeyEvent.keyCode` is only positional under the stock US key layout — a user-selected physical
+ * keyboard layout (Settings → Physical keyboard) remaps keycodes semantically (AOSP's German .kcm
+ * carries `map key 21 Z` / `map key 44 Y`), which would apply the layout twice: once here, once on
+ * the host (the y↔z / ü-on-ö scramble). Unmapped keys → 0 (the Rust side drops them). Extend this
+ * alongside `punktfunk-host/src/inject.rs::vk_to_evdev` (emit only VKs the host knows).
  */
 object Keymap {
+    /**
+     * Positional wire VK for a hardware key event: the evdev scancode table first (immune to the
+     * selected physical-keyboard layout), falling back to the keycode table for events without a
+     * scancode (soft keyboards, synthetic events) and for everything outside the typing area
+     * (layout-invariant there, incl. gamepad buttons whose scancodes lie outside the table).
+     */
+    fun toVk(event: KeyEvent): Int {
+        val positional = evdevToVk(event.scanCode)
+        return if (positional != 0) positional else toVk(event.keyCode)
+    }
+
+    /**
+     * Linux evdev keycode (`KeyEvent.scanCode`) → US-positional VK for the layout-**variant**
+     * typing area — the same 48-key table as the Linux client's `evdev_to_vk` and the hosts'
+     * fixed tables. Everything else → 0 (the keycode path is already positional for those).
+     */
+    fun evdevToVk(scan: Int): Int = when (scan) {
+        in 2..10 -> 0x31 + (scan - 2) // KEY_1..KEY_9
+        11 -> 0x30 // KEY_0
+        12 -> 0xBD // KEY_MINUS       -_  VK_OEM_MINUS (DE: ß)
+        13 -> 0xBB // KEY_EQUAL       =+  VK_OEM_PLUS
+        16 -> 0x51 // Q
+        17 -> 0x57 // W
+        18 -> 0x45 // E
+        19 -> 0x52 // R
+        20 -> 0x54 // T
+        21 -> 0x59 // KEY_Y — US-Y position (QWERTZ: the Z key)
+        22 -> 0x55 // U
+        23 -> 0x49 // I
+        24 -> 0x4F // O
+        25 -> 0x50 // P
+        26 -> 0xDB // KEY_LEFTBRACE   [{  VK_OEM_4 (DE: ü)
+        27 -> 0xDD // KEY_RIGHTBRACE  ]}  VK_OEM_6
+        30 -> 0x41 // A
+        31 -> 0x53 // S
+        32 -> 0x44 // D
+        33 -> 0x46 // F
+        34 -> 0x47 // G
+        35 -> 0x48 // H
+        36 -> 0x4A // J
+        37 -> 0x4B // K
+        38 -> 0x4C // L
+        39 -> 0xBA // KEY_SEMICOLON   ;:  VK_OEM_1 (DE: ö)
+        40 -> 0xDE // KEY_APOSTROPHE  '"  VK_OEM_7 (DE: ä)
+        41 -> 0xC0 // KEY_GRAVE       `~  VK_OEM_3 (DE: ^)
+        43 -> 0xDC // KEY_BACKSLASH   \|  VK_OEM_5
+        44 -> 0x5A // KEY_Z — US-Z position (QWERTZ: the Y key)
+        45 -> 0x58 // X
+        46 -> 0x43 // C
+        47 -> 0x56 // V
+        48 -> 0x42 // B
+        49 -> 0x4E // N
+        50 -> 0x4D // M
+        51 -> 0xBC // KEY_COMMA       ,<  VK_OEM_COMMA
+        52 -> 0xBE // KEY_DOT         .>  VK_OEM_PERIOD
+        53 -> 0xBF // KEY_SLASH       /?  VK_OEM_2
+        86 -> 0xE2 // KEY_102ND       <>| VK_OEM_102 (ISO)
+        else -> 0
+    }
+
     fun toVk(keyCode: Int): Int = when (keyCode) {
         in KeyEvent.KEYCODE_A..KeyEvent.KEYCODE_Z -> 0x41 + (keyCode - KeyEvent.KEYCODE_A) // A–Z
         in KeyEvent.KEYCODE_0..KeyEvent.KEYCODE_9 -> 0x30 + (keyCode - KeyEvent.KEYCODE_0) // 0–9 row

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

@@ -29,8 +29,10 @@ object NativeBridge {
      * trust-on-first-use — read [nativeHostFingerprint] after; else 64-hex host SHA-256, mismatch →
      * `0`). [width]/[height]/[refreshHz] are the requested virtual-output mode (the host streams at
      * exactly this); [bitrateKbps] 0 = host default; [compositorPref]/[gamepadPref] are the
-     * `CompositorPref`/`GamepadPref` wire bytes (0 = Auto). Returns an opaque session handle, or `0`
-     * on failure. Pair with exactly one [nativeClose].
+     * `CompositorPref`/`GamepadPref` wire bytes (0 = Auto). [timeoutMs] is the handshake budget — the
+     * normal path passes a short value, the no-PIN "request access" path a long one (≥ the host's
+     * approval-park window) so a slow operator approval lands on this same parked connection. Returns
+     * an opaque session handle, or `0` on failure. Pair with exactly one [nativeClose].
      */
     external fun nativeConnect(
         host: String,
@@ -45,6 +47,10 @@ object NativeBridge {
         compositorPref: Int,
         gamepadPref: Int,
         hdrEnabled: Boolean,
+        audioChannels: Int,
+        /** Preferred video codec as a `quic::CODEC_*` bit (`0` = auto). Soft — the host falls back. */
+        preferredCodec: Int,
+        timeoutMs: Int,
     ): Long
 
     /** 64-hex SHA-256 of the cert the host presented on [handle]; valid after a successful connect. */
@@ -80,7 +86,7 @@ object NativeBridge {
 
     /**
      * 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;
+     * `key␟name␟addr␟port␟fp␟pair␟mac` (`␟` = 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
@@ -88,6 +94,15 @@ object NativeBridge {
     /** Stop the browse, shut the mDNS daemon down and join its thread. No-op on `0`. */
     external fun nativeDiscoveryStop(handle: Long)
 
+    /**
+     * Send a Wake-on-LAN magic packet to wake a sleeping host. [macsCsv] is comma-separated MAC
+     * addresses (`aa:bb:..,cc:dd:..`), learned from the host's mDNS `mac` TXT while it was online;
+     * [lastIp] is the host's last-known IPv4 (or empty). Returns true if at least one datagram was
+     * sent. No handle — callable without a live session. Do NOT call on the main thread (it does
+     * blocking socket sends); run it on a background dispatcher.
+     */
+    external fun nativeWakeOnLan(macsCsv: String, lastIp: String): Boolean
+
     /**
      * 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.
@@ -99,12 +114,28 @@ object NativeBridge {
 
     /**
      * Drain ~1 s of live decode stats for the on-stream HUD, or `null` when no decode thread runs.
-     * Returns 10 doubles:
-     * `[fps, mbps, latP50Ms, latP95Ms, latValid, skewCorrected, width, height, refreshHz, framesDropped]`
-     * (the two flags are 1.0/0.0). Poll ~1 Hz; each call resets the measurement window.
+     * Returns 18 doubles (unified stats spec, `design/stats-unification.md`):
+     * `[fps, mbps, e2eP50Ms, e2eP95Ms, latValid, skewCorrected, width, height, refreshHz, framesLost,
+     * bitDepth, colorPrimaries, colorTransfer, chromaFormatIdc, hostNetP50Ms, decodeP50Ms, hostP50Ms,
+     * netP50Ms]`
+     * (the two flags are 1.0/0.0; indexes 2/3 are the end-to-end capture→decoded headline; 10–13
+     * describe the negotiated video feed — bit depth 8/10, CICP primaries/transfer, and the HEVC
+     * chroma_format_idc 1=4:2:0 / 3=4:4:4; 14/15 are the stage p50s tiling the headline —
+     * `host+network` = capture→received, `decode` = received→decoded; 16/17 split the
+     * `host+network` term via the host's per-AU 0xCF timings — `host` = the host's capture→sent,
+     * `network` = the remainder — both 0.0 when no timing matched this window, i.e. an old host).
+     * Poll ~1 Hz; each call resets the measurement window.
      */
     external fun nativeVideoStats(handle: Long): DoubleArray?
 
+    /**
+     * Gate per-frame stats sampling on the HUD being visible: while disabled the decode thread
+     * skips the per-AU clock read + lock, so toggle this with the overlay (and only poll
+     * [nativeVideoStats] while it's on). Enabling resets the measurement window — no stale data.
+     * Sticky for the session (survives video stop/start). No-op on `0`.
+     */
+    external fun nativeSetVideoStatsEnabled(handle: Long, enabled: Boolean)
+
     /**
      * Start host→client audio: Opus decode → jitter ring → AAudio (LowLatency), all in Rust. No-op
      * if already started. Best-effort — a failure leaves video streaming.
@@ -142,6 +173,22 @@ object NativeBridge {
     /** One scroll step. axis: 0=vertical 1=horizontal. delta: signed, 120-scaled, +=up/right. */
     external fun nativeSendScroll(handle: Long, axis: Int, delta: Int)
 
+    /**
+     * One REAL touchscreen transition (the touch-passthrough input mode). [kind]: 0=down 1=move
+     * 2=up. [id] distinguishes fingers and is reusable after up; coordinates are pixels on the
+     * client's touch surface — the host rescales against [surfaceWidth]×[surfaceHeight] and
+     * injects a real touch contact. On up only [id] matters.
+     */
+    external fun nativeSendTouch(
+        handle: Long,
+        id: Int,
+        kind: Int,
+        x: Int,
+        y: Int,
+        surfaceWidth: Int,
+        surfaceHeight: Int,
+    )
+
     /** One key transition. vk: Windows VK (0 = dropped by Rust). mods: VK modifier mask (0 for now). */
     external fun nativeSendKey(handle: Long, vk: Int, down: Boolean, mods: Int)
 

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

@@ -17,15 +17,17 @@ data class DiscoveredHost(
     val port: Int,
     val fingerprint: String? = null, // TXT "fp" (host cert SHA-256, advisory — TOFU still verifies)
     val pairingRequired: Boolean = false,
+    val mac: List<String> = emptyList(), // TXT "mac" (wake-capable NIC MAC(s), for Wake-on-LAN)
 )
 
 /** Field separator the native browse uses inside one record (ASCII Unit Separator). */
 private const val FIELD_SEP = '\u001F'
 
 /**
- * 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.
+ * Parse one record from [NativeBridge.nativeDiscoveryPoll] (`key␟name␟addr␟port␟fp␟pair␟mac`), or
+ * null if it's malformed. `mac` (7th field) is optional — an older host omits it. 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 parseHostRecord(record: String): DiscoveredHost? {
     val f = record.split(FIELD_SEP)
@@ -40,6 +42,8 @@ fun parseHostRecord(record: String): DiscoveredHost? {
         port = port,
         fingerprint = f[4].ifBlank { null },
         pairingRequired = f[5] == "required",
+        mac = if (f.size > 6) f[6].split(",").map { it.trim() }.filter { it.isNotEmpty() }
+        else emptyList(),
     )
 }
 

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

@@ -13,6 +13,11 @@ data class KnownHost(
     val name: String,
     val fpHex: String,
     val paired: Boolean,
+    /**
+     * Wake-on-LAN MAC(s) (`aa:bb:cc:dd:ee:ff`) learned from the host's mDNS `mac` TXT while it was
+     * online, so the client can wake it once it sleeps. Empty until first learned.
+     */
+    val mac: List<String> = emptyList(),
 )
 
 /**
@@ -42,9 +47,22 @@ class KnownHostStore(context: Context) {
             .put("name", host.name)
             .put("fp", host.fpHex.lowercase())
             .put("paired", host.paired)
+            .put("mac", host.mac.joinToString(","))
         prefs.edit().putString(key(host.address, host.port), json.toString()).apply()
     }
 
+    /**
+     * Learn/refresh a saved host's Wake-on-LAN MAC(s) from its live advert (called while online).
+     * No-op when the host isn't saved, the list is empty, or it's unchanged — so it doesn't churn
+     * prefs on every discovery tick.
+     */
+    fun learnMac(address: String, port: Int, mac: List<String>) {
+        if (mac.isEmpty()) return
+        val h = get(address, port) ?: return
+        if (h.mac == mac) return
+        save(h.copy(mac = mac))
+    }
+
     /** Forget [address]:[port] (the next connect re-pairs / re-TOFUs). */
     fun remove(address: String, port: Int) {
         prefs.edit().remove(key(address, port)).apply()
@@ -68,6 +86,7 @@ class KnownHostStore(context: Context) {
             name = j.getString("name"),
             fpHex = j.getString("fp"),
             paired = j.optBoolean("paired", false),
+            mac = j.optString("mac", "").split(",").map { it.trim() }.filter { it.isNotEmpty() },
         )
     }.getOrNull()
 }

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

@@ -0,0 +1,43 @@
+package io.unom.punktfunk.kit
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+/**
+ * Pure JVM test of the positional scancode table (`Keymap.evdevToVk`) — no Android runtime types
+ * (the `KeyEvent` constants in the keycode table are compile-time-inlined ints). Run:
+ * `./gradlew :kit:testDebugUnitTest`.
+ */
+class KeymapTest {
+    /**
+     * The German-scramble regression pins: the physical keys a QWERTZ board labels Z/Y/ö/ü/ä/ß
+     * must leave this client as their US-position VKs, regardless of the user-selected physical
+     * keyboard layout (which remaps `keyCode`, not `scanCode`).
+     */
+    @Test
+    fun positionalPinsForTheQwertzScramble() {
+        assertEquals(0x59, Keymap.evdevToVk(21)) // KEY_Y (QWERTZ: Z key) → VK_Y
+        assertEquals(0x5A, Keymap.evdevToVk(44)) // KEY_Z (QWERTZ: Y key) → VK_Z
+        assertEquals(0xBA, Keymap.evdevToVk(39)) // KEY_SEMICOLON (QWERTZ: ö) → VK_OEM_1
+        assertEquals(0xDB, Keymap.evdevToVk(26)) // KEY_LEFTBRACE (QWERTZ: ü) → VK_OEM_4
+        assertEquals(0xDE, Keymap.evdevToVk(40)) // KEY_APOSTROPHE (QWERTZ: ä) → VK_OEM_7
+        assertEquals(0xBD, Keymap.evdevToVk(12)) // KEY_MINUS (QWERTZ: ß) → VK_OEM_MINUS
+    }
+
+    /**
+     * Exactly the 48 typing-area keys are covered (10 digits + 26 letters + 12 OEM) with unique
+     * VKs; everything else (nav, F-row, modifiers, gamepad buttons at 0x100+) falls through to
+     * the keycode table.
+     */
+    @Test
+    fun tableCoversTheTypingAreaBijectively() {
+        val mapped = (0..0x200).mapNotNull { sc ->
+            Keymap.evdevToVk(sc).takeIf { it != 0 }?.let { sc to it }
+        }
+        assertEquals(48, mapped.size)
+        assertEquals(48, mapped.map { it.second }.toSet().size)
+        assertEquals(0, Keymap.evdevToVk(1)) // KEY_ESC — layout-invariant, keycode path
+        assertEquals(0, Keymap.evdevToVk(59)) // KEY_F1
+        assertEquals(0, Keymap.evdevToVk(304)) // BTN_SOUTH — gamepad, never a typing key
+    }
+}

clients/android/native/Cargo.toml

@@ -27,8 +27,8 @@ log = "0.4"
 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
-# `ndk` and Oboe/Opus audio later) is only pulled in for the real `*-linux-android` targets.
+# compiles this crate (as a host cdylib) — the Android-framework glue (logging, AMediaCodec + AAudio
+# via `ndk`, the Opus codec) is only pulled in for the real `*-linux-android` targets.
 [target.'cfg(target_os = "android")'.dependencies]
 android_logger = "0.14"
 # NDK bindings. "media" = AMediaCodec/ANativeWindow (video); "audio" = AAudio (audio playback).

clients/android/native/src/adpf.rs

@@ -0,0 +1,137 @@
+//! Android Adaptive Performance Framework (ADPF) — CPU performance hints for the decode thread.
+//!
+//! ADPF lets a latency-critical app tell the platform "these threads run a repeating workload with
+//! this per-cycle deadline, and here's how long they *actually* took." The kernel's CPU governor
+//! (on Qualcomm Snapdragon in particular — its ADPF backend is among the most responsive) then keeps
+//! those threads on the fast cores at high clocks instead of migrating them to a little core or
+//! down-clocking between frames. For a stream client the win is on the in-process hot path we
+//! control — the `pf-decode` feed/drain/present loop — *not* the hardware codec itself (that decodes
+//! in the mediacodec service, a separate process we can't hint); keeping our loop from being
+//! scheduled late directly trims the jitter between "AU received" and "buffer released to the
+//! Surface." It complements the codec-side `operating-rate`/`priority` hints, which push the codec's
+//! own clocks.
+//!
+//! The `APerformanceHint_*` API arrived in NDK **API level 33**. minSdk is 31, so we CANNOT link the
+//! symbols directly: a `libpunktfunk_android.so` carrying an unresolved
+//! `APerformanceHint_createSession` import fails to load on API 31/32 devices
+//! (`System.loadLibrary` throws) even if the code path is never taken. Instead we resolve the
+//! entry points from `libandroid.so` with `dlsym` at runtime — absent on < 33 ⇒
+//! [`HintSession::create`] returns `None` and the decode loop simply runs without hints.
+
+use std::ffi::c_void;
+use std::os::raw::c_int;
+
+// `APerformanceHint_*` function-pointer types. The manager/session handles are opaque, so we treat
+// them as `*mut c_void`.
+type GetManagerFn = unsafe extern "C" fn() -> *mut c_void;
+type CreateSessionFn = unsafe extern "C" fn(*mut c_void, *const i32, usize, i64) -> *mut c_void;
+type ReportFn = unsafe extern "C" fn(*mut c_void, i64) -> c_int;
+type UpdateTargetFn = unsafe extern "C" fn(*mut c_void, i64) -> c_int;
+type CloseFn = unsafe extern "C" fn(*mut c_void);
+
+/// The entry points we use, resolved once from `libandroid.so`, plus the process-wide manager.
+struct Api {
+    create_session: CreateSessionFn,
+    report: ReportFn,
+    update_target: UpdateTargetFn,
+    close: CloseFn,
+    manager: *mut c_void,
+}
+
+/// Resolve the ADPF entry points + the process manager, or `None` on API < 33 (symbols absent) or if
+/// the manager is unavailable.
+fn resolve_api() -> Option<Api> {
+    // SAFETY: `dlopen` of an always-present system library with a NUL-terminated name; it returns
+    // null on failure (checked below). `libandroid.so` is already mapped into every app process, so
+    // this only bumps its refcount — we intentionally never `dlclose` (process-lifetime handle).
+    let lib = unsafe { libc::dlopen(c"libandroid.so".as_ptr(), libc::RTLD_NOW) };
+    if lib.is_null() {
+        return None;
+    }
+    // SAFETY: `dlsym` on the valid handle above with NUL-terminated symbol names; each returns null
+    // when the symbol is absent (device API < 33), which we check before transmuting the non-null
+    // pointer to its fn-pointer type (layout-compatible; a resolved symbol is a valid code address).
+    unsafe {
+        let get_manager = libc::dlsym(lib, c"APerformanceHint_getManager".as_ptr());
+        let create_session = libc::dlsym(lib, c"APerformanceHint_createSession".as_ptr());
+        let report = libc::dlsym(lib, c"APerformanceHint_reportActualWorkDuration".as_ptr());
+        let update_target = libc::dlsym(lib, c"APerformanceHint_updateTargetWorkDuration".as_ptr());
+        let close = libc::dlsym(lib, c"APerformanceHint_closeSession".as_ptr());
+        if get_manager.is_null()
+            || create_session.is_null()
+            || report.is_null()
+            || update_target.is_null()
+            || close.is_null()
+        {
+            return None; // device API < 33 — no ADPF
+        }
+        let get_manager = std::mem::transmute::<*mut c_void, GetManagerFn>(get_manager);
+        let manager = get_manager();
+        if manager.is_null() {
+            return None;
+        }
+        Some(Api {
+            create_session: std::mem::transmute::<*mut c_void, CreateSessionFn>(create_session),
+            report: std::mem::transmute::<*mut c_void, ReportFn>(report),
+            update_target: std::mem::transmute::<*mut c_void, UpdateTargetFn>(update_target),
+            close: std::mem::transmute::<*mut c_void, CloseFn>(close),
+            manager,
+        })
+    }
+}
+
+/// A live ADPF hint session bound to a set of thread ids. Dropping it closes the session. Holds raw
+/// handles, so it is `!Send`/`!Sync` — created and used only on the `pf-decode` thread.
+pub struct HintSession {
+    api: Api,
+    session: *mut c_void,
+}
+
+impl HintSession {
+    /// Open a session hinting `tids` with an initial per-frame target of `target_ns` nanoseconds.
+    /// `None` when ADPF is unavailable (device API < 33) or the platform declines — the caller then
+    /// runs unhinted (a no-op, not an error).
+    pub fn create(target_ns: i64, tids: &[i32]) -> Option<Self> {
+        if target_ns <= 0 || tids.is_empty() {
+            return None;
+        }
+        let api = resolve_api()?;
+        // SAFETY: `api.manager` is the live process manager returned above; `tids` is a valid slice
+        // of `len` i32s that `createSession` copies; it returns null on failure (checked).
+        let session =
+            unsafe { (api.create_session)(api.manager, tids.as_ptr(), tids.len(), target_ns) };
+        if session.is_null() {
+            return None;
+        }
+        Some(Self { api, session })
+    }
+
+    /// Report the wall-clock time the hinted thread spent producing the last displayed frame. When
+    /// it exceeds the session target the governor boosts the cores running the thread; when it
+    /// stays under, clocks may relax. No-op on a non-positive duration (the API rejects it).
+    pub fn report_actual(&self, actual_ns: i64) {
+        if actual_ns <= 0 {
+            return;
+        }
+        // SAFETY: `self.session` is a live session for `self`'s lifetime.
+        unsafe { (self.api.report)(self.session, actual_ns) };
+    }
+
+    /// Update the per-frame target (e.g. after a mid-session refresh-rate change). Unused today —
+    /// the decode thread restarts on renegotiation — but kept for that path.
+    #[allow(dead_code)]
+    pub fn update_target(&self, target_ns: i64) {
+        if target_ns <= 0 {
+            return;
+        }
+        // SAFETY: `self.session` is a live session for `self`'s lifetime.
+        unsafe { (self.api.update_target)(self.session, target_ns) };
+    }
+}
+
+impl Drop for HintSession {
+    fn drop(&mut self) {
+        // SAFETY: `self.session` was created by `createSession` and is closed exactly once, here.
+        unsafe { (self.api.close)(self.session) };
+    }
+}

clients/android/native/src/audio.rs

@@ -1,8 +1,21 @@
 //! Android audio playback (android-only): pull Opus packets from the connector, decode to
-//! interleaved f32 stereo, and feed AAudio (LowLatency) via its realtime data callback through a
-//! jitter ring. Mirrors [`crate::decode`]: one thread we own (the Opus decode producer) plus a
-//! shutdown flag; the realtime callback thread is owned by AAudio. Ring logic ported from
-//! `punktfunk-client-linux/src/audio.rs` (prime ~3 quanta, drop-oldest cap, re-prime on drain).
+//! interleaved f32 (stereo or 5.1/7.1 surround), and feed AAudio (LowLatency) via its realtime data
+//! callback through a jitter ring. Mirrors [`crate::decode`]: one thread we own (the Opus decode
+//! producer) plus a shutdown flag; the realtime callback thread is owned by AAudio.
+//!
+//! The layout is the host-RESOLVED channel count (`NativeClient::audio_channels`, negotiated at
+//! connect), so an older/clamping host that can only capture stereo is decoded + played as stereo.
+//! 2 = stereo / 6 = 5.1 / 8 = 7.1, in the canonical wire order FL FR FC LFE RL RR SL SR.
+//!
+//! The ring started as a port of `punktfunk-client-linux/src/audio.rs`, but AAudio — unlike
+//! PipeWire, which adaptively rate-matches the stream and absorbs a shallow buffer — hands us a raw
+//! realtime callback and makes us own the buffer. So this client diverges deliberately to stop the
+//! Android-only crackle: (1) the callback is allocation/free-free — decoded buffers are recycled to
+//! the producer via a free-list instead of being freed on the audio thread (Android's Scudo `free`
+//! has unbounded tail latency); (2) the jitter ring is deeper (~40 ms prime / ~150 ms hard cap) and
+//! decoupled from the tiny LowLatency burst size, with de-prime hysteresis so a transient drain
+//! doesn't manufacture a silence; (3) the AAudio HW buffer is primed above its 2-burst default and
+//! grown on XRuns (Google's anti-glitch technique).
 
 use ndk::audio::{
     AudioCallbackResult, AudioDirection, AudioFormat, AudioPerformanceMode, AudioSharingMode,
@@ -13,16 +26,75 @@ use punktfunk_core::error::PunktfunkError;
 use std::collections::VecDeque;
 use std::ffi::c_void;
 use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
-use std::sync::mpsc::{sync_channel, SyncSender, TrySendError};
+use std::sync::mpsc::{sync_channel, Receiver, SyncSender, TrySendError};
 use std::sync::Arc;
 use std::time::Duration;
 
-const CHANNELS: usize = 2;
 const SAMPLE_RATE: i32 = 48_000;
 /// Decoded-chunk hand-off depth: 64 × 5 ms = 320 ms slack (matches the core's AUDIO_QUEUE).
 const RING_CHUNKS: usize = 64;
-/// Opus decode scratch: worst-case 120 ms stereo frame (5760 samples/ch × 2 ch).
-const PCM_SCRATCH: usize = 5760 * CHANNELS;
+
+// --- Jitter-ring depths, in MILLISECONDS (scaled to interleaved-f32 samples at runtime). --------
+// The channel count is negotiated, not a compile-time const, so these are kept in ms and multiplied
+// by `ms` (interleaved-f32 samples per millisecond at the resolved layout) inside `start`.
+// Unlike the Linux client (PipeWire adaptively rate-matches the stream to the graph clock, masking
+// host↔DAC drift + a shallow ring), AAudio hands us a raw callback and we own the buffer: drift and
+// WiFi power-save bunching land as underruns/overflows = crackle. So Android runs a deliberately
+// deeper, smoothly-managed ring than Linux — keep the two clients' depths intentionally divergent.
+/// Prime/target floor: fill to ~40 ms before playing (and after a sustained drain). Deep enough to
+/// ride out WiFi arrival jitter + clock drift; the dominant Android-only anti-crackle lever.
+const PRIME_FLOOR_MS: usize = 40;
+/// Ceiling for the burst-scaled target (so a large quantum can't push the prime depth too high).
+const PRIME_CEIL_MS: usize = 80;
+/// Drop-oldest headroom above the target before trimming — a ~80 ms band swallows an arrival burst
+/// without overflowing.
+const JITTER_HEADROOM_MS: usize = 80;
+/// Hard latency bound: never let the ring exceed ~150 ms (the only thing that caps added latency).
+const HARD_CAP_MS: usize = 150;
+/// Re-prime (go silent to refill) only after this many CONSECUTIVE empty callbacks, so one transient
+/// drain doesn't manufacture a fresh 40 ms silence (the old `if ring.is_empty()` re-primed instantly).
+const DEPRIME_AFTER_CALLBACKS: u32 = 5;
+/// Throttle the AAudio XRun-driven HW-buffer grow check (cheap, but no need to poll every quantum).
+const XRUN_CHECK_EVERY: u32 = 128;
+
+/// Opus decoder for the audio plane: a plain stereo decoder (the validated path) or a multistream
+/// decoder for 5.1/7.1, both behind one `decode_float`. Built from the host-RESOLVED channel count
+/// via the shared layout table. Mirrors the Linux client's `AudioDec`.
+enum AudioDec {
+    Stereo(opus::Decoder),
+    Surround(opus::MSDecoder),
+}
+
+impl AudioDec {
+    fn new(channels: u8) -> Result<AudioDec, opus::Error> {
+        if channels == 2 {
+            Ok(AudioDec::Stereo(opus::Decoder::new(
+                SAMPLE_RATE as u32,
+                opus::Channels::Stereo,
+            )?))
+        } else {
+            let l = punktfunk_core::audio::layout_for(channels, false);
+            Ok(AudioDec::Surround(opus::MSDecoder::new(
+                SAMPLE_RATE as u32,
+                l.streams,
+                l.coupled,
+                l.mapping,
+            )?))
+        }
+    }
+
+    fn decode_float(
+        &mut self,
+        input: &[u8],
+        out: &mut [f32],
+        fec: bool,
+    ) -> Result<usize, opus::Error> {
+        match self {
+            AudioDec::Stereo(d) => d.decode_float(input, out, fec),
+            AudioDec::Surround(d) => d.decode_float(input, out, fec),
+        }
+    }
+}
 
 /// Diagnostics — written by the decode thread + the realtime callback, logged periodically. The
 /// audio analogue of the video `fed`/`rendered` counters (we can't "screenshot" sound).
@@ -42,86 +114,185 @@ pub struct AudioPlayback {
 }
 
 impl AudioPlayback {
-    /// Open AAudio (LowLatency, 48 kHz/stereo/f32) with a realtime callback draining a jitter ring,
-    /// then spawn the Opus decode thread. `None` on failure (the caller leaves video streaming).
+    /// Open AAudio (LowLatency, 48 kHz/f32, the host-resolved channel layout) with a realtime
+    /// callback draining a jitter ring, then spawn the Opus decode thread. `None` on failure (the
+    /// caller leaves video streaming).
     pub fn start(client: Arc<NativeClient>) -> Option<AudioPlayback> {
+        // Build playback from the host-RESOLVED channel count (never the request): 2 = stereo /
+        // 6 = 5.1 / 8 = 7.1, canonical wire order FL FR FC LFE RL RR SL SR.
+        let channels = punktfunk_core::audio::normalize_channels(client.audio_channels) as usize;
+        // Interleaved f32 samples per millisecond at this layout (48 kHz × channels); the ms-
+        // denominated jitter-ring depths scale by it.
+        let ms = (SAMPLE_RATE as usize / 1000) * channels;
+        let prime_floor = PRIME_FLOOR_MS * ms;
+        let prime_ceil = PRIME_CEIL_MS * ms;
+        let jitter_headroom = JITTER_HEADROOM_MS * ms;
+        let hard_cap_max = HARD_CAP_MS * ms;
         let counters = Arc::new(Counters::default());
-        let (tx, rx) = sync_channel::<Vec<f32>>(RING_CHUNKS);
 
-        // Realtime consumer state, owned by the callback (FnMut) — no lock: AAudio calls it from a
-        // single high-priority thread, and the decode thread only touches `tx`.
-        let cb_counters = counters.clone();
-        let mut ring: VecDeque<f32> = VecDeque::with_capacity(PCM_SCRATCH);
-        let mut primed = false;
-        let callback = move |_s: &AudioStream, data: *mut c_void, num_frames: i32| {
-            let want = num_frames as usize * CHANNELS;
-            // SAFETY: AAudio provides `num_frames * channel_count` F32 slots at `data`.
-            let out = unsafe { std::slice::from_raw_parts_mut(data as *mut f32, want) };
-            while let Ok(chunk) = rx.try_recv() {
-                ring.extend(chunk);
-            }
-            // Prime to ~3 quanta (15 ms; floor 15 ms / ceiling 200 ms); drop OLDEST above the cap.
-            let target = (3 * want).clamp(720 * CHANNELS, 9600 * CHANNELS);
-            while ring.len() > target.max(want) + want {
-                ring.pop_front();
-            }
-            if !primed && ring.len() >= target {
-                primed = true;
-            }
-            if primed {
-                for slot in out.iter_mut() {
-                    *slot = ring.pop_front().unwrap_or(0.0);
+        // One open attempt at a given sharing mode. Everything the realtime callback captures
+        // (channels, ring, prime state) is rebuilt per attempt — `open_stream` consumes the builder
+        // AND the callback, so nothing survives a failed try to reuse.
+        let try_open = |sharing: AudioSharingMode| -> ndk::audio::Result<(
+            AudioStream,
+            SyncSender<Vec<f32>>,
+            Receiver<Vec<f32>>,
+        )> {
+            let (tx, rx) = sync_channel::<Vec<f32>>(RING_CHUNKS);
+            // Recycle free-list: drained PCM buffers go BACK to the decode thread to be refilled, so
+            // the realtime callback never frees heap (Android's Scudo allocator has unbounded free()
+            // tail latency — a free on the audio thread is an XRun = a click) and the decode thread
+            // rarely allocates. Same depth as the data channel.
+            let (free_tx, free_rx) = sync_channel::<Vec<f32>>(RING_CHUNKS);
+
+            // Realtime consumer state, owned by the callback (FnMut) — no lock: AAudio calls it from
+            // a single high-priority thread, and the decode thread only touches `tx`/`free_rx`.
+            let cb_counters = counters.clone();
+            // Pre-reserve the ring so `extend` never reallocates on the realtime thread. Worst
+            // transient before the trim below = the hard cap plus one full channel of 5 ms (480-f32)
+            // frames — the punktfunk protocol always sends 5 ms Opus frames (host `audio_thread`); a
+            // larger frame would force a one-time realloc, asserted (not silently corrupted) in
+            // `decode_loop`.
+            let mut ring: VecDeque<f32> =
+                VecDeque::with_capacity(hard_cap_max + RING_CHUNKS * 5 * ms);
+            let mut primed = false;
+            let mut empties: u32 = 0; // consecutive empty callbacks (de-prime hysteresis)
+            let mut cb_count: u32 = 0; // callbacks since open (throttles the XRun grow check)
+            let mut last_xrun: i32 = 0; // last AAudio XRun count we grew the buffer for
+            let callback = move |s: &AudioStream, data: *mut c_void, num_frames: i32| {
+                let want = num_frames as usize * channels;
+                // SAFETY: AAudio provides `num_frames * channel_count` F32 slots at `data`.
+                let out = unsafe { std::slice::from_raw_parts_mut(data as *mut f32, want) };
+                // Drain decoded chunks into the ring WITHOUT freeing on the RT thread: `drain(..)`
+                // empties each Vec but keeps its capacity, then the empty buffer is handed back for
+                // reuse. The only RT-thread free is the rare case where the recycle channel is
+                // momentarily full.
+                while let Ok(mut chunk) = rx.try_recv() {
+                    ring.extend(chunk.drain(..));
+                    let _ = free_tx.try_send(chunk);
+                }
+                // Jitter buffer: prime to ~40 ms (prime_floor) before playing and after a sustained
+                // drain; drop-oldest only above a wide ~120 ms band. Decoupled from the AAudio burst
+                // `want` (tiny on the LowLatency MMAP path) so the depth doesn't collapse to a single
+                // quantum.
+                let target = (3 * want).clamp(prime_floor, prime_ceil);
+                let hard_cap = (target + jitter_headroom).min(hard_cap_max);
+                while ring.len() > hard_cap {
+                    ring.pop_front();
+                }
+                if !primed && ring.len() >= target {
+                    primed = true;
+                }
+                if primed {
+                    for slot in out.iter_mut() {
+                        *slot = ring.pop_front().unwrap_or(0.0);
+                    }
+                    cb_counters
+                        .pcm_written
+                        .fetch_add(num_frames as u64, Ordering::Relaxed);
+                } else {
+                    out.fill(0.0);
+                    cb_counters.underruns.fetch_add(1, Ordering::Relaxed);
+                }
+                // Re-prime only after a RUN of empty callbacks, not a single transient one —
+                // otherwise every momentary drain costs a fresh 40 ms silence (the old behaviour,
+                // self-inflicted crackle on any jitter spike).
+                if ring.is_empty() {
+                    empties += 1;
+                    if empties >= DEPRIME_AFTER_CALLBACKS {
+                        primed = false;
+                    }
+                } else {
+                    empties = 0;
                 }
                 cb_counters
-                    .pcm_written
-                    .fetch_add(num_frames as u64, Ordering::Relaxed);
-            } else {
-                out.fill(0.0);
-                cb_counters.underruns.fetch_add(1, Ordering::Relaxed);
-            }
-            if ring.is_empty() {
-                primed = false; // re-prime after a genuine drain (avoids sustained crackle on loss)
-            }
-            cb_counters
-                .ring_depth
-                .store(ring.len() as u64, Ordering::Relaxed);
-            AudioCallbackResult::Continue
+                    .ring_depth
+                    .store(ring.len() as u64, Ordering::Relaxed);
+                // Google's AAudio anti-glitch technique: when the device reports new XRuns, grow the
+                // HW buffer by one burst (up to capacity). getXRunCount + setBufferSizeInFrames are
+                // both callback-safe / non-blocking, and set clamps to capacity so it self-limits.
+                // Throttled.
+                cb_count = cb_count.wrapping_add(1);
+                if cb_count % XRUN_CHECK_EVERY == 0 {
+                    let xr = s.x_run_count();
+                    if xr > last_xrun {
+                        last_xrun = xr;
+                        let burst = s.frames_per_burst().max(1);
+                        let grown =
+                            (s.buffer_size_in_frames() + burst).min(s.buffer_capacity_in_frames());
+                        let _ = s.set_buffer_size_in_frames(grown);
+                    }
+                }
+                AudioCallbackResult::Continue
+            };
+
+            let stream = AudioStreamBuilder::new()?
+                .direction(AudioDirection::Output)
+                .sample_rate(SAMPLE_RATE)
+                // The wire order (FL FR FC LFE RL RR SL SR) is the standard AAudio/Android channel
+                // order, so this is an IDENTITY mapping — no permute. AAudio infers the 5.1/7.1 mask
+                // from `channel_count` (the ndk crate's builder exposes no setChannelMask); the host
+                // captures + Opus-encodes in exactly this order.
+                .channel_count(channels as i32)
+                .format(AudioFormat::PCM_Float)
+                .performance_mode(AudioPerformanceMode::LowLatency)
+                .sharing_mode(sharing)
+                .data_callback(Box::new(callback))
+                .error_callback(Box::new(|_s, e| {
+                    log::warn!("audio: AAudio error (device reroute/disconnect?): {e:?}");
+                }))
+                .open_stream()?;
+            Ok((stream, tx, free_rx))
         };
 
-        let stream = AudioStreamBuilder::new()
-            .map_err(|e| log::error!("audio: AudioStreamBuilder::new: {e}"))
-            .ok()?
-            .direction(AudioDirection::Output)
-            .sample_rate(SAMPLE_RATE)
-            .channel_count(CHANNELS as i32)
-            .format(AudioFormat::PCM_Float)
-            .performance_mode(AudioPerformanceMode::LowLatency)
-            .sharing_mode(AudioSharingMode::Shared)
-            .data_callback(Box::new(callback))
-            .error_callback(Box::new(|_s, e| {
-                log::warn!("audio: AAudio error (device reroute/disconnect?): {e:?}");
-            }))
-            .open_stream()
-            .map_err(|e| log::error!("audio: open_stream: {e}"))
-            .ok()?;
+        // Exclusive first — MMAP-exclusive is AAudio's lowest-latency path (once proven on-device it
+        // may also allow lowering the jitter-ring depths above; those stay put pending crackle
+        // testing) — and fall back to Shared when the device refuses (no MMAP, output claimed, …).
+        // The started-log below prints the mode the device actually GRANTED (`share=`): AAudio may
+        // still resolve an Exclusive request to Shared.
+        let (stream, tx, free_rx) = match try_open(AudioSharingMode::Exclusive) {
+            Ok(opened) => opened,
+            Err(e) => {
+                log::info!("audio: Exclusive open failed ({e}) — retrying Shared");
+                match try_open(AudioSharingMode::Shared) {
+                    Ok(opened) => opened,
+                    Err(e) => {
+                        log::error!("audio: open_stream: {e}");
+                        return None;
+                    }
+                }
+            }
+        };
 
         if let Err(e) = stream.request_start() {
             log::error!("audio: request_start: {e}");
             return None;
         }
+        // Lift the AAudio HW buffer off its brittle ~2-burst LowLatency default so a single late
+        // callback doesn't immediately underrun; the in-callback XRun loop grows it further if the
+        // device still glitches. set_buffer_size_in_frames clamps to capacity.
+        let burst = stream.frames_per_burst().max(1);
+        let _ =
+            stream.set_buffer_size_in_frames((burst * 3).min(stream.buffer_capacity_in_frames()));
+        // perf != LowLatency or rate != 48000 means AAudio silently fell to a resampled legacy path
+        // (different burst behaviour) — surface it so the field can tell that apart from plain jitter.
         log::info!(
-            "audio: AAudio started rate={} ch={} fmt={:?} burst={}",
+            "audio: AAudio started rate={} ch={} fmt={:?} perf={:?} share={:?} burst={} buf={}/{}",
             stream.sample_rate(),
             stream.channel_count(),
             stream.format(),
+            stream.performance_mode(),
+            stream.sharing_mode(),
             stream.frames_per_burst(),
+            stream.buffer_size_in_frames(),
+            stream.buffer_capacity_in_frames(),
         );
 
         let shutdown = Arc::new(AtomicBool::new(false));
         let sd = shutdown.clone();
         let join = std::thread::Builder::new()
             .name("pf-audio".into())
-            .spawn(move || decode_loop(client, tx, sd, counters))
+            .spawn(move || decode_loop(client, tx, free_rx, sd, counters, channels))
             .ok();
 
         Some(AudioPlayback {
@@ -143,31 +314,57 @@ impl Drop for AudioPlayback {
 }
 
 /// Producer: `next_audio` → Opus `decode_float` → push interleaved f32 into the ring channel.
+/// Buffers come from (and return to) the realtime callback's recycle free-list so the steady state
+/// is allocation-free on both threads.
 fn decode_loop(
     client: Arc<NativeClient>,
     tx: SyncSender<Vec<f32>>,
+    free_rx: Receiver<Vec<f32>>,
     shutdown: Arc<AtomicBool>,
     counters: Arc<Counters>,
+    channels: usize,
 ) {
-    let mut dec = match opus::Decoder::new(SAMPLE_RATE as u32, opus::Channels::Stereo) {
+    // Fold this Opus→AAudio thread into the client's hot-thread set so the ADPF session the decode
+    // thread opens also keeps audio decode on a fast core (registered before the video pump's first
+    // frame arrives, so it's captured when that session is created). No-op below API 33.
+    client.register_hot_thread();
+    // Interleaved f32 samples per millisecond at this layout — the ring's 5 ms reserve check below.
+    let ms = (SAMPLE_RATE as usize / 1000) * channels;
+    // Opus decode scratch: worst-case 120 ms frame (5760 samples/ch) × channels.
+    let pcm_scratch = 5760 * channels;
+    let mut dec = match AudioDec::new(channels as u8) {
         Ok(d) => d,
         Err(e) => {
             log::error!("audio: opus decoder init: {e} — audio disabled");
             return;
         }
     };
-    let mut pcm = vec![0f32; PCM_SCRATCH];
+    let mut pcm = vec![0f32; pcm_scratch];
     let mut window_peak = 0f32; // loudest |sample| since the last log — tells a tone from silence
     while !shutdown.load(Ordering::Relaxed) {
         match client.next_audio(Duration::from_millis(5)) {
             Ok(pkt) => match dec.decode_float(&pkt.data, &mut pcm, false) {
                 Ok(samples) => {
-                    let n = samples * CHANNELS;
+                    let n = samples * channels;
                     for &s in &pcm[..n] {
                         window_peak = window_peak.max(s.abs());
                     }
+                    // The ring's pre-reservation in `start` assumes the protocol's 5 ms (≤480-f32/ch)
+                    // frames; a larger frame would force a one-time realloc on the RT thread. Catch a
+                    // future host frame-size change here in debug, not as a silent audio glitch.
+                    debug_assert!(
+                        n <= 5 * ms,
+                        "audio frame {n} f32 exceeds the 5 ms ring reserve"
+                    );
                     let count = counters.opus_decoded.fetch_add(1, Ordering::Relaxed) + 1;
-                    match tx.try_send(pcm[..n].to_vec()) {
+                    // Reuse a recycled buffer if the callback handed one back; only allocate when the
+                    // free-list is momentarily empty (startup / after a backpressure drop).
+                    let mut buf = free_rx
+                        .try_recv()
+                        .unwrap_or_else(|_| Vec::with_capacity(pcm_scratch));
+                    buf.clear();
+                    buf.extend_from_slice(&pcm[..n]);
+                    match tx.try_send(buf) {
                         Ok(()) | Err(TrySendError::Full(_)) => {} // drop-newest under backpressure
                         Err(TrySendError::Disconnected(_)) => break,
                     }

clients/android/native/src/decode.rs

@@ -9,15 +9,27 @@
 use ndk::data_space::DataSpace;
 use ndk::media::media_codec::{
     DequeuedInputBufferResult, DequeuedOutputBufferInfoResult, MediaCodec, MediaCodecDirection,
+    OutputBuffer,
 };
 use ndk::media::media_format::MediaFormat;
 use ndk::native_window::{FrameRateCompatibility, NativeWindow};
 use punktfunk_core::client::NativeClient;
 use punktfunk_core::error::PunktfunkError;
+use punktfunk_core::session::Frame;
+use std::collections::VecDeque;
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::Arc;
 use std::time::{Duration, Instant};
 
+/// Cap on the pts→received-timestamp map below: MediaCodec holds only a handful of frames in
+/// flight, so anything beyond this is stale (codec flushed / HUD toggled) and gets evicted.
+const IN_FLIGHT_CAP: usize = 64;
+
+/// Cap on received AUs awaiting their 0xCF host timing (Phase 2 host/network split): the timing
+/// datagram trails its AU by at most the wire, so a match lands within a frame or two — anything
+/// this deep is a lost datagram (or an old host that never sends any) and gets evicted.
+const PENDING_SPLIT_CAP: usize = 256;
+
 /// The decode loop. Runs on the `pf-decode` thread until `shutdown` is set or the session closes.
 pub fn run(
     client: Arc<NativeClient>,
@@ -27,16 +39,23 @@ pub fn run(
 ) {
     boost_thread_priority();
     let mode = client.mode();
-    let codec = match MediaCodec::from_decoder_type("video/hevc") {
+    // The MediaCodec MIME for the codec the host resolved (`Welcome.codec`): HEVC or H.264. AMediaCodec
+    // needs no out-of-band extradata — the in-band VPS/SPS/PPS on every IDR configure it either way.
+    let mime = match client.codec {
+        punktfunk_core::quic::CODEC_H264 => "video/avc",
+        _ => "video/hevc",
+    };
+    let codec = match MediaCodec::from_decoder_type(mime) {
         Some(c) => c,
         None => {
-            log::error!("decode: no HEVC decoder on this device");
+            log::error!("decode: no {mime} decoder on this device");
             return;
         }
     };
+    log::info!("decode: codec mime = {mime}");
 
     let mut format = MediaFormat::new();
-    format.set_str("mime", "video/hevc");
+    format.set_str("mime", mime);
     format.set_i32("width", mode.width as i32);
     format.set_i32("height", mode.height as i32);
     // Generous input buffer so a large keyframe AU is never truncated.
@@ -46,11 +65,21 @@ pub fn run(
     );
     // Ask for the low-latency decode path where the decoder supports it (no reordering buffer).
     format.set_i32("low-latency", 1);
+    // Best-effort vendor twin of the standard key: older Qualcomm decoders only honor their own
+    // extension. Unknown keys are ignored by other vendors' codecs, so this is safe to set blind.
+    format.set_i32("vendor.qti-ext-dec-low-latency.enable", 1);
     // Advisory low-latency hints (KEY_PRIORITY / KEY_OPERATING_RATE), ignored where unsupported:
     // realtime priority + the target frame rate, so vendor decoders (e.g. Qualcomm) run at full
     // clocks instead of a power-saving cadence that adds dequeue latency.
     format.set_i32("priority", 0); // 0 = realtime
-    format.set_i32("operating-rate", mode.refresh_hz as i32);
+                                   // Operating rate = the codec's clock hint. Setting it to the display rate merely asks the
+                                   // decoder to *sustain* that cadence — a Qualcomm decoder can meet 60/120 fps at a power-saving
+                                   // clock that adds a millisecond-plus of decode latency per frame. Setting it to the AOSP
+                                   // "unbounded" sentinel (Short.MAX) instead asks the decoder to run each frame at max clocks and
+                                   // finish ASAP, minimising per-frame decode latency — the right trade for a real-time stream
+                                   // (costs power/heat; the dial to lower if a device thermally throttles over a long session).
+                                   // Ignored where unsupported.
+    format.set_i32("operating-rate", i16::MAX as i32); // 32767 = "as fast as possible"
 
     // HDR static metadata (ST.2086 mastering + content light level): when an HDR session was
     // negotiated, set KEY_HDR_STATIC_INFO so the display tone-maps from the source's real grade.
@@ -93,41 +122,174 @@ pub fn run(
         );
     }
 
+    // ADPF: hint the platform that the whole video pipeline — this pf-decode feed/drain/present
+    // loop, the core's data-plane pump (UDP receive + FEC reassembly), and the audio thread — runs a
+    // per-frame real-time workload, so the CPU governor keeps those threads on fast cores at high
+    // clocks instead of down-clocking between frames or parking them on a little core. Snapdragon's
+    // ADPF backend responds well to this. We register this thread now but create the session lazily
+    // on the first presented frame: by then the pump + audio threads have registered their ids too,
+    // and ADPF `createSession` rejects a set with any not-yet-live/dead tid. No-op below API 33.
+    let frame_period_ns = if mode.refresh_hz > 0 {
+        1_000_000_000i64 / mode.refresh_hz as i64
+    } else {
+        0
+    };
+    client.register_hot_thread(); // this decode thread → the pipeline's hot-thread set
+    let mut hint: Option<crate::adpf::HintSession> = None;
+    let mut hint_tried = false;
+    // Accumulates the loop's productive (feed+drain) time between displayed frames; reported to ADPF
+    // once per rendered frame against the frame-period target.
+    let mut work_accum_ns: i64 = 0;
+
     let mut fed: u64 = 0;
     let mut rendered: u64 = 0;
+    let mut discarded: u64 = 0;
+    // The AU waiting for a free codec input buffer. `feed` is non-blocking; on transient input
+    // pressure the AU stays parked here instead of being dropped (a drop forces a keyframe
+    // round-trip) and we only pop the next one once it's queued.
+    let mut pending: Option<Frame> = None;
     // Loss recovery: watch the host→client unrecoverable-drop count and ask for an IDR when it
     // climbs.
     let mut last_dropped = client.frames_dropped();
     let mut last_kf_req: Option<Instant> = None;
-    // Capture→client-receipt latency uses the negotiated host-minus-client clock offset (0 if the
-    // host didn't answer the skew handshake — then the HUD flags it "same-host").
+    // Skew-corrected latency stats (spec: design/stats-unification.md) use the negotiated
+    // host-minus-client clock offset (0 if the host didn't answer the skew handshake — then the
+    // HUD flags it "(same-host clock)").
     let clock_offset = client.clock_offset_ns;
+    // HUD stage split: receipt timestamps keyed by the pts we queue into the codec, so the decoded
+    // point (output-buffer dequeue — MediaCodec round-trips presentationTimeUs) can be paired back
+    // to its receipt for the `decode` stage. Only fed while the HUD is visible.
+    let mut in_flight: VecDeque<(u64, i128)> = VecDeque::new();
+    // Phase-2 host/network split (design/stats-unification.md): received AUs awaiting their 0xCF
+    // host timing, as (pts_ns, capture→received µs). The timings are drained non-blockingly right
+    // where receipts are recorded and matched by pts; `network = hostnet − host` (saturating).
+    // Only fed while the HUD is visible; an old host never sends a 0xCF, so entries just age out.
+    let mut pending_split: VecDeque<(u64, u64)> = VecDeque::new();
     // The dataspace we've signalled on the Surface so far (None = default/SDR). Set reactively once
     // the decoder reports an HDR stream (see `drain`); avoids re-applying every format event.
     let mut applied_ds: Option<DataSpace> = None;
+    // One thread feeds AND drains: the NDK AMediaCodec wrapper isn't documented thread-safe for
+    // cross-thread feed/drain, so instead of splitting threads the loop decouples the two — input
+    // dequeue is non-blocking (never stalls presentation of already-decoded frames) and the only
+    // blocking wait is a short output dequeue while input is backed up (decoder progress is exactly
+    // what frees the next input buffer).
     while !shutdown.load(Ordering::Relaxed) {
-        match client.next_frame(Duration::from_millis(5)) {
-            Ok(frame) => {
-                if fed == 0 {
-                    let p = &frame.data;
-                    log::info!(
-                        "decode: first AU {} bytes, head {:02x?}",
-                        p.len(),
-                        &p[..p.len().min(6)]
-                    );
+        if pending.is_none() {
+            match client.next_frame(Duration::from_millis(5)) {
+                Ok(frame) => {
+                    if fed == 0 {
+                        let p = &frame.data;
+                        log::info!(
+                            "decode: first AU {} bytes, head {:02x?}",
+                            p.len(),
+                            &p[..p.len().min(6)]
+                        );
+                    }
+                    // HUD stat, `received` point: host+network = client_now + (host−client) −
+                    // capture_pts. Gated on the HUD being visible — `enabled` first so the hidden
+                    // steady state skips the wall-clock read and the lock entirely. The receipt
+                    // stamp is also parked in `in_flight` (keyed by the pts the codec will echo on
+                    // the output buffer) for the decoded-point pairing in `drain`.
+                    if stats.enabled() {
+                        let received_ns = now_realtime_ns();
+                        let lat_ns = received_ns + clock_offset as i128 - frame.pts_ns as i128;
+                        let lat_us = (lat_ns > 0 && lat_ns < 10_000_000_000)
+                            .then_some((lat_ns / 1000) as u64);
+                        stats.note_received(frame.data.len(), lat_us, clock_offset != 0);
+                        in_flight.push_back((frame.pts_ns / 1000, received_ns));
+                        if in_flight.len() > IN_FLIGHT_CAP {
+                            in_flight.pop_front(); // stale — codec never echoed it back
+                        }
+                        // Phase-2 split: park this AU's capture→received sample, then match any
+                        // 0xCF host timings that have arrived — host = the host's own
+                        // capture→sent, network = our capture→received minus it (per-frame
+                        // tiling; saturating in case of clock jitter).
+                        if let Some(hostnet_us) = lat_us {
+                            pending_split.push_back((frame.pts_ns, hostnet_us));
+                            if pending_split.len() > PENDING_SPLIT_CAP {
+                                pending_split.pop_front(); // 0xCF lost / old host — evict
+                            }
+                        }
+                        while let Ok(t) = client.next_host_timing(Duration::ZERO) {
+                            if let Some(i) = pending_split.iter().position(|&(p, _)| p == t.pts_ns)
+                            {
+                                let (_, hostnet_us) = pending_split.remove(i).unwrap();
+                                stats.note_host_split(
+                                    t.host_us as u64,
+                                    hostnet_us.saturating_sub(t.host_us as u64),
+                                );
+                            }
+                        }
+                    }
+                    pending = Some(frame);
                 }
-                fed += 1;
-                // HUD stat: capture→client-receipt latency = client_now + (host−client) − capture_pts.
-                let lat_ns = now_realtime_ns() + clock_offset as i128 - frame.pts_ns as i128;
-                let lat_us =
-                    (lat_ns > 0 && lat_ns < 10_000_000_000).then_some((lat_ns / 1000) as u64);
-                stats.note(frame.data.len(), lat_us, clock_offset != 0);
-                feed(&codec, &frame.data, frame.pts_ns / 1000);
+                Err(PunktfunkError::NoFrame) => {} // timeout — still drain output below
+                Err(_) => break,                   // session closed
             }
-            Err(PunktfunkError::NoFrame) => {} // timeout — still drain output below
-            Err(_) => break,                   // session closed
         }
-        rendered += drain(&codec, &window, &mut applied_ds);
+        // Time the productive work (feed + drain) only — the `next_frame` poll wait above is idle
+        // and excluded, so ADPF sees this thread's real per-frame CPU cost, not the poll timeout.
+        let work_t0 = Instant::now();
+        if let Some(frame) = pending.take() {
+            if feed(&codec, &frame.data, frame.pts_ns / 1000) {
+                fed += 1;
+                if fed % 300 == 0 {
+                    log::info!("decode: fed={fed} rendered={rendered} discarded={discarded}");
+                }
+            } else {
+                // No input buffer free — transient back-pressure. Keep the AU and let `drain` block
+                // briefly below; a released output buffer is what recycles an input slot.
+                pending = Some(frame);
+            }
+        }
+        // Drain every iteration. When input is blocked, wait ~2 ms on output so the loop rides
+        // decoder progress instead of busy-spinning against a full input queue.
+        let wait = if pending.is_some() {
+            Duration::from_millis(2)
+        } else {
+            Duration::ZERO
+        };
+        let (r, d) = drain(
+            &codec,
+            &window,
+            &mut applied_ds,
+            wait,
+            &stats,
+            &mut in_flight,
+            clock_offset,
+        );
+        rendered += r;
+        discarded += d;
+
+        // ADPF: attribute this iteration's feed+drain time to the frame being produced, and report
+        // the accumulated per-frame work once one is actually presented (r > 0). Under back-pressure
+        // the short output-dequeue wait is included in the tally — for a latency-first client,
+        // biasing the governor toward "boost" is the desired behaviour. Cheap when `hint` is None
+        // (one `Instant` diff, no report).
+        work_accum_ns += work_t0.elapsed().as_nanos() as i64;
+        if r > 0 {
+            if !hint_tried {
+                // First presented frame: the pump + audio threads have registered their ids by now.
+                // Build one ADPF session over the whole pipeline's thread set (empty below API 33,
+                // or where the platform declines → `None`, and the loop runs unhinted).
+                hint_tried = true;
+                let tids = client.hot_thread_ids();
+                hint = crate::adpf::HintSession::create(frame_period_ns, &tids);
+                log::info!(
+                    "decode: ADPF hint session {} — {} hot thread(s), target {frame_period_ns} ns",
+                    if hint.is_some() {
+                        "active"
+                    } else {
+                        "unavailable"
+                    },
+                    tids.len(),
+                );
+            }
+            if let Some(h) = &hint {
+                h.report_actual(work_accum_ns);
+            }
+            work_accum_ns = 0;
+        }
 
         // Loss recovery: under infinite GOP the only recovery keyframe is one we request. The
         // reassembler drops unrecoverable AUs (frames_dropped); the decoder then conceals the
@@ -145,14 +307,10 @@ pub fn run(
                 log::debug!("decode: requested keyframe (loss recovery, dropped={dropped})");
             }
         }
-
-        if fed > 0 && fed % 300 == 0 {
-            log::info!("decode: fed={fed} rendered={rendered}");
-        }
     }
 
     let _ = codec.stop();
-    log::info!("decode: stopped (fed={fed} rendered={rendered})");
+    log::info!("decode: stopped (fed={fed} rendered={rendered} discarded={discarded})");
 }
 
 /// Wall-clock now in nanoseconds (CLOCK_REALTIME basis), to compare against the host-stamped
@@ -182,9 +340,12 @@ fn boost_thread_priority() {
     }
 }
 
-/// Copy one access unit into a codec input buffer and queue it.
-fn feed(codec: &MediaCodec, au: &[u8], pts_us: u64) {
-    match codec.dequeue_input_buffer(Duration::from_millis(10)) {
+/// Try to copy one access unit into a codec input buffer and queue it, without blocking. Returns
+/// `false` only on `TryAgainLater` (no input buffer free) — the caller keeps the AU pending and
+/// retries; a hard dequeue/queue error counts as consumed (retrying can't salvage the AU, and
+/// parking it forever would wedge the loop on a broken codec).
+fn feed(codec: &MediaCodec, au: &[u8], pts_us: u64) -> bool {
+    match codec.dequeue_input_buffer(Duration::ZERO) {
         Ok(DequeuedInputBufferResult::Buffer(mut buf)) => {
             let n = {
                 let dst = buf.buffer_mut();
@@ -196,41 +357,74 @@ fn feed(codec: &MediaCodec, au: &[u8], pts_us: u64) {
                         dst.len()
                     );
                 }
-                for (slot, &b) in dst.iter_mut().zip(&au[..n]) {
-                    slot.write(b);
+                // SAFETY: `au` and `dst` are distinct allocations (wire AU vs. codec buffer), both
+                // valid for `n` bytes; `MaybeUninit<u8>` is layout-identical to `u8`, so the cast
+                // write initializes exactly `dst[..n]`.
+                unsafe {
+                    std::ptr::copy_nonoverlapping(au.as_ptr(), dst.as_mut_ptr().cast::<u8>(), n);
                 }
                 n
             };
             if let Err(e) = codec.queue_input_buffer(buf, 0, n, pts_us, 0) {
                 log::warn!("decode: queue_input_buffer: {e}");
             }
+            true
         }
-        Ok(DequeuedInputBufferResult::TryAgainLater) => {
-            // No input buffer free right now; the AU is dropped (FEC/keyframes recover).
+        Ok(DequeuedInputBufferResult::TryAgainLater) => false, // caller keeps the AU pending
+        Err(e) => {
+            log::warn!("decode: dequeue_input_buffer: {e}");
+            true
         }
-        Err(e) => log::warn!("decode: dequeue_input_buffer: {e}"),
     }
 }
 
-/// Release any ready output buffers to the surface (render = true), latency-first. Returns the
-/// number of frames presented. Also reacts to `OutputFormatChanged` to signal HDR on the Surface.
-fn drain(codec: &MediaCodec, window: &NativeWindow, applied_ds: &mut Option<DataSpace>) -> u64 {
-    let mut n = 0;
+/// Dequeue every ready output buffer and present only the NEWEST (render = true), discarding the
+/// rest (render = false) — when decode falls behind, a back-to-back burst of stale frames on glass
+/// is worse than skipping straight to the freshest one (the Apple client's 1-slot newest-ready
+/// ring, ported). `first_wait` is the timeout for the first dequeue only: zero normally, ~2 ms when
+/// the caller's input is blocked so the loop waits on decoder progress instead of busy-spinning.
+/// Returns `(rendered, discarded)`. Also reacts to `OutputFormatChanged` (which can interleave
+/// between buffers — handled without losing the held buffer) to signal HDR on the Surface.
+///
+/// Each dequeued buffer is also the HUD's `decoded` measurement point (rendered or not — the frame
+/// finished decoding either way): end-to-end = decoded + clock_offset − capture pts, and the
+/// `decode` stage pairs the buffer's echoed presentationTimeUs back to the receipt stamp in
+/// `in_flight` (single-clock local difference, no skew involved).
+fn drain(
+    codec: &MediaCodec,
+    window: &NativeWindow,
+    applied_ds: &mut Option<DataSpace>,
+    first_wait: Duration,
+    stats: &crate::stats::VideoStats,
+    in_flight: &mut VecDeque<(u64, i128)>,
+    clock_offset: i64,
+) -> (u64, u64) {
+    let mut held = None; // newest ready buffer so far, presented after the loop
+    let mut discarded: u64 = 0;
+    let mut wait = first_wait;
     loop {
-        match codec.dequeue_output_buffer(Duration::from_millis(0)) {
+        match codec.dequeue_output_buffer(wait) {
             Ok(DequeuedOutputBufferInfoResult::Buffer(buf)) => {
-                if let Err(e) = codec.release_output_buffer(buf, true) {
-                    log::warn!("decode: release_output_buffer: {e}");
-                    break;
+                wait = Duration::ZERO; // only the first dequeue may block
+                if stats.enabled() {
+                    note_decoded(stats, in_flight, clock_offset, &buf);
+                }
+                if let Some(stale) = held.replace(buf) {
+                    // A newer frame is ready — drop the held one without rendering.
+                    if let Err(e) = codec.release_output_buffer(stale, false) {
+                        log::warn!("decode: release_output_buffer(discard): {e}");
+                    }
+                    discarded += 1;
                 }
-                n += 1;
             }
             Ok(DequeuedOutputBufferInfoResult::OutputFormatChanged) => {
                 // The decoder has parsed the SPS and now reports the stream's real colour signalling
                 // (the AMediaCodec analogue of VideoToolbox's format description on the Apple client).
                 // If it's HDR (BT.2020 PQ/HLG), tell the Surface so the compositor/display switch to
                 // HDR; SDR streams leave the default dataspace alone. The decoder itself picks a
-                // Main10 path from the SPS — no profile override needed. Keep looping (buffers follow).
+                // Main10 path from the SPS — no profile override needed. Keep looping (buffers
+                // follow, and any held buffer stays held across this event).
+                wait = Duration::ZERO;
                 if let Some(ds) = hdr_dataspace(codec) {
                     if *applied_ds != Some(ds) {
                         match window.set_buffers_data_space(ds) {
@@ -245,7 +439,7 @@ fn drain(codec: &MediaCodec, window: &NativeWindow, applied_ds: &mut Option<Data
                     }
                 }
             }
-            // TryAgainLater / OutputBuffersChanged — nothing to render now.
+            // TryAgainLater / OutputBuffersChanged — nothing more to dequeue now.
             Ok(_) => break,
             Err(e) => {
                 log::warn!("decode: dequeue_output_buffer: {e}");
@@ -253,7 +447,49 @@ fn drain(codec: &MediaCodec, window: &NativeWindow, applied_ds: &mut Option<Data
             }
         }
     }
-    n
+    // Present the newest ready frame, if any.
+    let mut rendered = 0;
+    if let Some(buf) = held {
+        match codec.release_output_buffer(buf, true) {
+            Ok(()) => rendered = 1,
+            Err(e) => log::warn!("decode: release_output_buffer: {e}"),
+        }
+    }
+    (rendered, discarded)
+}
+
+/// HUD `decoded` point for one dequeued output buffer: build the end-to-end (capture→decoded,
+/// skew-corrected, clamped to (0, 10 s)) and `decode` (received→decoded, single-clock local, ≥ 0)
+/// samples and hand them to [`crate::stats::VideoStats::note_decoded`]. The codec echoes the input
+/// `presentationTimeUs` on the output buffer, which keys the receipt stamp in `in_flight`; entries
+/// older than the echoed pts are evicted (decode order == input order here — low-latency, no
+/// B-frames — so anything before it was dropped inside the codec or stamped before a flush).
+fn note_decoded(
+    stats: &crate::stats::VideoStats,
+    in_flight: &mut VecDeque<(u64, i128)>,
+    clock_offset: i64,
+    buf: &OutputBuffer<'_>,
+) {
+    let pts_us = buf.info().presentation_time_us().max(0) as u64;
+    let decoded_ns = now_realtime_ns();
+    // Pair the echoed pts back to its receipt stamp, evicting stale (older) entries as we go.
+    let mut received_ns = None;
+    while let Some(&(p, r)) = in_flight.front() {
+        if p > pts_us {
+            break; // future frame — leave it for its own output buffer
+        }
+        in_flight.pop_front();
+        if p == pts_us {
+            received_ns = Some(r);
+            break;
+        }
+    }
+    // pts_us is the truncated frame.pts_ns/1000 we queued, so ×1000 re-approximates capture time
+    // to < 1 µs — negligible against the ms-scale figures shown.
+    let e2e_ns = decoded_ns + clock_offset as i128 - pts_us as i128 * 1000;
+    let e2e_us = (e2e_ns > 0 && e2e_ns < 10_000_000_000).then_some((e2e_ns / 1000) as u64);
+    let decode_us = received_ns.map(|r| ((decoded_ns - r).max(0) / 1000) as u64);
+    stats.note_decoded(e2e_us, decode_us);
 }
 
 /// Map the decoder's reported output colour to a BT.2020 HDR dataspace, or `None` for SDR. The

clients/android/native/src/discovery.rs

@@ -31,7 +31,7 @@ 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`]).
+/// One resolved host, serialized to Kotlin as `key␟name␟addr␟port␟fp␟pair␟mac` (`␟` = [`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)]
@@ -42,6 +42,8 @@ struct Host {
     port: u16,
     fp: String,
     pair: String,
+    /// Wake-on-LAN MAC(s) from the mDNS `mac` TXT (comma-separated), for later wake. Empty if absent.
+    mac: String,
 }
 
 impl Host {
@@ -54,13 +56,14 @@ impl Host {
             s.replace(['\n', '\r', FIELD_SEP], "")
         }
         format!(
-            "{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}",
+            "{}{FIELD_SEP}{}{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),
+            clean(&self.mac),
         )
     }
 }
@@ -182,6 +185,7 @@ fn resolve(info: &ResolvedService) -> Option<Host> {
         port: info.get_port(),
         fp: val("fp"),
         pair: val("pair"),
+        mac: val("mac"),
     })
 }
 
@@ -202,7 +206,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoverySt
 }
 
 /// `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 /
+/// newline-joined records of `key␟name␟addr␟port␟fp␟pair␟mac` (`␟` = 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>(
@@ -263,16 +267,18 @@ mod tests {
             port: 9777,
             fp: "ab".repeat(32),
             pair: "required".into(),
+            mac: "aa:bb:cc:dd:ee:ff".into(),
         };
         let encoded = h.encode();
         let fields: Vec<&str> = encoded.split(FIELD_SEP).collect();
-        assert_eq!(fields.len(), 6);
+        assert_eq!(fields.len(), 7);
         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_eq!(fields[6], "aa:bb:cc:dd:ee:ff");
         assert!(
             !encoded.contains('\n'),
             "a record must never contain the record separator"
@@ -282,7 +288,7 @@ mod tests {
     #[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.
+        // them so the snapshot stays exactly one record of exactly seven fields.
         let h = Host {
             key: "k\u{1f}injected".into(),
             name: "evil\nhost\r".into(),
@@ -290,9 +296,14 @@ mod tests {
             port: 9777,
             fp: "ab\u{1f}cd".into(),
             pair: "required\n".into(),
+            mac: "aa:bb\u{1f}cc".into(),
         };
         let encoded = h.encode();
-        assert_eq!(encoded.matches(FIELD_SEP).count(), 5, "exactly six fields");
+        assert_eq!(
+            encoded.matches(FIELD_SEP).count(),
+            6,
+            "exactly seven fields"
+        );
         assert!(!encoded.contains('\n') && !encoded.contains('\r'));
         let fields: Vec<&str> = encoded.split(FIELD_SEP).collect();
         assert_eq!(fields[0], "kinjected");

clients/android/native/src/feedback.rs

@@ -114,6 +114,11 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextHidout(
                 out[2..n].copy_from_slice(&effect);
                 n
             }
+            HidOutput::TrackpadHaptic { .. } => {
+                // Steam Controller trackpad-coil haptics — no Android equivalent; drop it (motor
+                // rumble already rides the universal 0xCA plane).
+                return -1;
+            }
         };
         n as jint
     })

clients/android/native/src/lib.rs

@@ -16,15 +16,17 @@
 //! 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
-//! (`abiVersion`/`coreVersion`) plus the session handle lifecycle in [`session`]; the per-plane
-//! pumps (video → AMediaCodec, audio → Oboe), input, audio, pairing and mode renegotiation are
-//! the next milestone (see the TODOs in [`session`]).
+//! (`clients/android`). The surface: the native-link proof (`abiVersion`/`coreVersion`), mDNS host
+//! discovery ([`discovery`]), and the session lifecycle in [`session`] — connect/pair + the trust
+//! surface, the per-plane pumps (video → AMediaCodec, audio ↔ AAudio, mic uplink), input, and
+//! rumble/HID feedback ([`feedback`]). Mode renegotiation is still TODO (see [`session`]).
 
 use jni::objects::JObject;
 use jni::sys::jint;
 use jni::JNIEnv;
 
+#[cfg(target_os = "android")]
+mod adpf;
 #[cfg(target_os = "android")]
 mod audio;
 #[cfg(target_os = "android")]
@@ -37,6 +39,9 @@ mod feedback;
 mod mic;
 mod session;
 mod stats;
+// Ungated like `discovery`: pure `jni` + `punktfunk_core::wol` (no Android framework), so it links
+// into the host workspace build too. Kotlin only ever calls it on device.
+mod wol;
 
 /// Initialize `android_logger` once when the JVM loads the library. Logs land in logcat under the
 /// `punktfunk` tag. Android-only — there is no JVM (and no logcat) on the host build.

clients/android/native/src/mic.rs

@@ -1,9 +1,12 @@
 //! Android microphone uplink (android-only): capture mic PCM via AAudio (LowLatency **input**),
 //! Opus-encode 20 ms stereo frames, and push them to the host over the connector's mic plane
 //! (`send_mic` → 0xCB datagram). The mirror of [`crate::audio`] in reverse: AAudio's realtime input
-//! callback hands captured interleaved f32 to a channel; a worker thread we own does the Opus encode
-//! + send (encoding is too heavy for the realtime callback, exactly as decode is on the playback
-//! side). Format matches the host decoder + the Linux client: 48 kHz **stereo**, 20 ms, Opus VOIP.
+//! callback hands captured interleaved f32 to a channel; a worker thread we own does the Opus
+//! encode + send (encoding is too heavy for the realtime callback, exactly as decode is on the
+//! playback side). Like the playback path, the realtime callback is allocation-free: captured
+//! bursts are copied into pre-allocated buffers from a recycle free-list (pool empty = drop the
+//! chunk, never allocate on the capture thread). Format matches the host decoder + the Linux
+//! client: 48 kHz **stereo**, 20 ms, Opus VOIP.
 
 use ndk::audio::{
     AudioCallbackResult, AudioDirection, AudioFormat, AudioPerformanceMode, AudioSharingMode,
@@ -13,7 +16,7 @@ use punktfunk_core::client::NativeClient;
 use std::collections::VecDeque;
 use std::ffi::c_void;
 use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
-use std::sync::mpsc::{sync_channel, Receiver, RecvTimeoutError, TrySendError};
+use std::sync::mpsc::{sync_channel, Receiver, RecvTimeoutError, SyncSender, TrySendError};
 use std::sync::Arc;
 use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
@@ -23,6 +26,10 @@ const SAMPLE_RATE: i32 = 48_000;
 const FRAME_SAMPLES: usize = 960;
 /// Captured-chunk hand-off depth (each ~ one burst); drops on overflow (best-effort uplink).
 const RING_CHUNKS: usize = 64;
+/// Free-list buffer capacity, in interleaved f32 samples: comfortably above a LowLatency input
+/// burst (typically ≤ ~480 frames). A device with larger bursts costs each buffer a one-time grow
+/// on the capture thread, after which the steady state is allocation-free again.
+const CHUNK_CAP_SAMPLES: usize = 1920; // 20 ms stereo
 /// Opus VOIP target bitrate (speech; tunable).
 const MIC_BITRATE: i32 = 64_000;
 
@@ -38,56 +45,109 @@ impl MicCapture {
     /// forwards captured PCM to a channel, then spawn the Opus encode + uplink thread. `None` on
     /// failure (the caller leaves the rest of the session streaming).
     pub fn start(client: Arc<NativeClient>) -> Option<MicCapture> {
-        let (tx, rx) = sync_channel::<Vec<f32>>(RING_CHUNKS);
         let captured = Arc::new(AtomicU64::new(0));
-        let cb_captured = captured.clone();
+        // Chunks discarded on the capture thread (free-list empty / encoder lagging); logged
+        // throttled from the encode worker.
+        let dropped = Arc::new(AtomicU64::new(0));
 
-        let callback = move |_s: &AudioStream, data: *mut c_void, num_frames: i32| {
-            let n = num_frames as usize * CHANNELS;
-            // SAFETY: for an input stream AAudio provides `num_frames * channel_count` captured F32
-            // samples at `data` (read-only for us).
-            let inp = unsafe { std::slice::from_raw_parts(data as *const f32, n) };
-            match tx.try_send(inp.to_vec()) {
-                Ok(()) | Err(TrySendError::Full(_)) => {} // drop-newest if the encoder lags
-                Err(TrySendError::Disconnected(_)) => return AudioCallbackResult::Stop,
+        // One open attempt at a given sharing mode (same pattern as [`crate::audio`]: `open_stream`
+        // consumes the builder AND the callback, so each try rebuilds the channels it captures).
+        let try_open = |sharing: AudioSharingMode| -> ndk::audio::Result<(
+            AudioStream,
+            Receiver<Vec<f32>>,
+            SyncSender<Vec<f32>>,
+        )> {
+            let (tx, rx) = sync_channel::<Vec<f32>>(RING_CHUNKS);
+            // Recycle free-list, mirroring the playback path: the realtime capture callback must
+            // not touch the allocator (Android's Scudo has unbounded malloc/free tail latency — an
+            // allocation here is a missed burst), so it pops a pre-allocated buffer, copies the
+            // burst in and sends it; the encode worker returns drained buffers. Pool empty = DROP
+            // the chunk (counted) rather than allocate.
+            let (free_tx, free_rx) = sync_channel::<Vec<f32>>(RING_CHUNKS);
+            for _ in 0..RING_CHUNKS {
+                let _ = free_tx.try_send(Vec::with_capacity(CHUNK_CAP_SAMPLES));
             }
-            cb_captured.fetch_add(num_frames as u64, Ordering::Relaxed);
-            AudioCallbackResult::Continue
+            let cb_captured = captured.clone();
+            let cb_dropped = dropped.clone();
+            let cb_free_tx = free_tx.clone(); // returns the buffer when the data channel is full
+
+            let callback = move |_s: &AudioStream, data: *mut c_void, num_frames: i32| {
+                let n = num_frames as usize * CHANNELS;
+                // SAFETY: for an input stream AAudio provides `num_frames * channel_count` captured
+                // F32 samples at `data` (read-only for us).
+                let inp = unsafe { std::slice::from_raw_parts(data as *const f32, n) };
+                cb_captured.fetch_add(num_frames as u64, Ordering::Relaxed);
+                match free_rx.try_recv() {
+                    Ok(mut buf) => {
+                        buf.clear();
+                        buf.extend_from_slice(inp); // retained capacity — no realloc past the first
+                        match tx.try_send(buf) {
+                            Ok(()) => {}
+                            Err(TrySendError::Full(buf)) => {
+                                // Encoder lagging: drop the chunk, hand the buffer straight back.
+                                let _ = cb_free_tx.try_send(buf);
+                                cb_dropped.fetch_add(1, Ordering::Relaxed);
+                            }
+                            Err(TrySendError::Disconnected(_)) => return AudioCallbackResult::Stop,
+                        }
+                    }
+                    // Pool empty (every buffer in flight): drop, never allocate on this thread.
+                    Err(_) => {
+                        cb_dropped.fetch_add(1, Ordering::Relaxed);
+                    }
+                }
+                AudioCallbackResult::Continue
+            };
+
+            let stream = AudioStreamBuilder::new()?
+                .direction(AudioDirection::Input)
+                .sample_rate(SAMPLE_RATE)
+                .channel_count(CHANNELS as i32)
+                .format(AudioFormat::PCM_Float)
+                .performance_mode(AudioPerformanceMode::LowLatency)
+                .sharing_mode(sharing)
+                .data_callback(Box::new(callback))
+                .error_callback(Box::new(|_s, e| {
+                    log::warn!("mic: AAudio error (device reroute/disconnect?): {e:?}");
+                }))
+                .open_stream()?;
+            Ok((stream, rx, free_tx))
         };
 
-        let stream = AudioStreamBuilder::new()
-            .map_err(|e| log::error!("mic: AudioStreamBuilder::new: {e}"))
-            .ok()?
-            .direction(AudioDirection::Input)
-            .sample_rate(SAMPLE_RATE)
-            .channel_count(CHANNELS as i32)
-            .format(AudioFormat::PCM_Float)
-            .performance_mode(AudioPerformanceMode::LowLatency)
-            .sharing_mode(AudioSharingMode::Shared)
-            .data_callback(Box::new(callback))
-            .error_callback(Box::new(|_s, e| {
-                log::warn!("mic: AAudio error (device reroute/disconnect?): {e:?}");
-            }))
-            .open_stream()
-            .map_err(|e| log::error!("mic: open_stream (RECORD_AUDIO granted?): {e}"))
-            .ok()?;
+        // Exclusive first — MMAP-exclusive is AAudio's lowest-latency path — falling back to Shared
+        // when the device refuses (no MMAP, mic claimed, …). The started-log below prints the mode
+        // the device actually GRANTED (`share=`).
+        let (stream, rx, free_tx) = match try_open(AudioSharingMode::Exclusive) {
+            Ok(opened) => opened,
+            Err(e) => {
+                log::info!("mic: Exclusive open failed ({e}) — retrying Shared");
+                match try_open(AudioSharingMode::Shared) {
+                    Ok(opened) => opened,
+                    Err(e) => {
+                        log::error!("mic: open_stream (RECORD_AUDIO granted?): {e}");
+                        return None;
+                    }
+                }
+            }
+        };
 
         if let Err(e) = stream.request_start() {
             log::error!("mic: request_start: {e}");
             return None;
         }
         log::info!(
-            "mic: AAudio input started rate={} ch={} fmt={:?}",
+            "mic: AAudio input started rate={} ch={} fmt={:?} share={:?}",
             stream.sample_rate(),
             stream.channel_count(),
             stream.format(),
+            stream.sharing_mode(),
         );
 
         let shutdown = Arc::new(AtomicBool::new(false));
         let sd = shutdown.clone();
         let join = std::thread::Builder::new()
             .name("pf-mic".into())
-            .spawn(move || encode_loop(client, rx, sd, captured))
+            .spawn(move || encode_loop(client, rx, free_tx, sd, captured, dropped))
             .ok();
 
         Some(MicCapture {
@@ -109,11 +169,15 @@ impl Drop for MicCapture {
 }
 
 /// Consumer: drain captured f32 → accumulate → Opus `encode_float` 20 ms stereo frames → `send_mic`.
+/// Drained chunk buffers go back to the callback's free-list; the encode scratch is reused across
+/// frames (only the packet Vec handed to `send_mic` is allocated per frame — it's sent away owned).
 fn encode_loop(
     client: Arc<NativeClient>,
     rx: Receiver<Vec<f32>>,
+    free_tx: SyncSender<Vec<f32>>,
     shutdown: Arc<AtomicBool>,
     captured: Arc<AtomicU64>,
+    dropped: Arc<AtomicU64>,
 ) {
     let mut enc = match opus::Encoder::new(
         SAMPLE_RATE as u32,
@@ -130,6 +194,7 @@ fn encode_loop(
 
     let frame = FRAME_SAMPLES * CHANNELS;
     let mut ring: VecDeque<f32> = VecDeque::with_capacity(frame * 4);
+    let mut pcm = vec![0f32; frame]; // reusable encode scratch (one 20 ms frame)
     let mut out = vec![0u8; 4000]; // max Opus packet for a 20 ms frame fits easily
     let mut seq: u32 = 0;
     let mut sent: u64 = 0;
@@ -137,12 +202,19 @@ fn encode_loop(
 
     while !shutdown.load(Ordering::Relaxed) {
         match rx.recv_timeout(Duration::from_millis(100)) {
-            Ok(chunk) => ring.extend(chunk),
+            Ok(mut chunk) => {
+                // `drain(..)` keeps the Vec's capacity; hand the emptied buffer back to the
+                // callback's free-list (dropped only if the pool is momentarily full).
+                ring.extend(chunk.drain(..));
+                let _ = free_tx.try_send(chunk);
+            }
             Err(RecvTimeoutError::Timeout) => continue, // wake to re-check shutdown
             Err(RecvTimeoutError::Disconnected) => break,
         }
         while ring.len() >= frame {
-            let pcm: Vec<f32> = ring.drain(..frame).collect();
+            for (dst, src) in pcm.iter_mut().zip(ring.drain(..frame)) {
+                *dst = src;
+            }
             for &s in &pcm {
                 peak = peak.max(s.abs());
             }
@@ -157,8 +229,9 @@ fn encode_loop(
                     sent += 1;
                     if sent % 250 == 0 {
                         log::info!(
-                            "mic: sent={sent} captured_frames={} peak={peak:.3}",
+                            "mic: sent={sent} captured_frames={} dropped_chunks={} peak={peak:.3}",
                             captured.load(Ordering::Relaxed),
+                            dropped.load(Ordering::Relaxed),
                         );
                         peak = 0.0;
                     }
@@ -168,7 +241,8 @@ fn encode_loop(
         }
     }
     log::info!(
-        "mic: stopped (sent={sent} captured_frames={})",
+        "mic: stopped (sent={sent} captured_frames={} dropped_chunks={})",
         captured.load(Ordering::Relaxed),
+        dropped.load(Ordering::Relaxed),
     );
 }

clients/android/native/src/session.rs

@@ -1,732 +0,0 @@
-//! Session lifecycle + plane wiring over JNI.
-//!
-//! A connected session is a [`SessionHandle`] — an `Arc<NativeClient>` plus the decode thread it
-//! feeds — boxed and handed to Kotlin as an opaque `jlong`. The connector is `Sync`, so the decode
-//! thread pulls the video plane (`next_frame`) directly while Kotlin still holds the handle.
-//!
-//! Wired: connect/close, the video plane (HEVC `next_frame` → NDK AMediaCodec → the SurfaceView's
-//! `ANativeWindow`, see [`crate::decode`]), host→client audio ([`crate::audio`]), input
-//! (`send_input` — mouse/keyboard/gamepad), rumble/DualSense HID feedback ([`crate::feedback`]),
-//! and the trust surface: `nativeGenerateIdentity` (persistent identity, Keystore-wrapped on the
-//! Kotlin side), `nativeConnect` with identity + pin (TOFU / pinned), and `nativePair` (SPAKE2 PIN).
-//!
-//! TODO(M4 Android stage 1): client→host DualSense rich input (`send_rich_input`), mode
-//! renegotiation. Port the remaining orchestration from `clients/linux`.
-
-use jni::objects::{JObject, JString};
-use jni::sys::{jboolean, jdoubleArray, jint, jlong, jsize};
-use jni::JNIEnv;
-use punktfunk_core::client::NativeClient;
-use punktfunk_core::config::{CompositorPref, GamepadPref, Mode};
-use punktfunk_core::input::{InputEvent, InputKind};
-use std::panic::AssertUnwindSafe;
-use std::sync::atomic::{AtomicBool, Ordering};
-use std::sync::{Arc, Mutex};
-use std::thread::JoinHandle;
-use std::time::Duration;
-
-/// Run a JNI body, catching any panic at the FFI boundary and returning `default` instead.
-///
-/// A panic unwinding out of an `extern "system"` function aborts the whole process on Rust ≥ 1.81 —
-/// a hard crash of the embedding Android app with no logcat trace. This mirrors the discipline the C
-/// ABI already enforces (`punktfunk_core::abi` wraps every entry point in `catch_unwind`); the
-/// `panic = "unwind"` profile in the workspace `Cargo.toml` exists precisely so these guards work.
-/// We apply it to the teardown + background-thread shims (the "leaving a stream" path), where an
-/// unexpected panic (e.g. a poisoned `Mutex` during concurrent teardown) must degrade to a logged
-/// no-op rather than kill the app.
-pub(crate) fn jni_guard<T>(default: T, f: impl FnOnce() -> T) -> T {
-    std::panic::catch_unwind(AssertUnwindSafe(f)).unwrap_or_else(|_| {
-        log::error!("punktfunk JNI: caught a panic at the FFI boundary (returning default)");
-        default
-    })
-}
-
-/// A live session behind the `jlong` handle: the connector + the decode thread it feeds.
-pub(crate) struct SessionHandle {
-    // Read only by the android decode path (`nativeStartVideo` → `crate::decode`); on the host
-    // build (CI's workspace clippy/build) those readers are cfg'd out, so it's intentionally unused.
-    #[cfg_attr(not(target_os = "android"), allow(dead_code))]
-    pub client: Arc<NativeClient>,
-    video: Mutex<Option<VideoThread>>,
-    #[cfg(target_os = "android")]
-    audio: Mutex<Option<crate::audio::AudioPlayback>>,
-    #[cfg(target_os = "android")]
-    mic: Mutex<Option<crate::mic::MicCapture>>,
-}
-
-struct VideoThread {
-    shutdown: Arc<AtomicBool>,
-    join: Option<JoinHandle<()>>,
-    /// Live decode stats, written by the decode thread and drained ~1 Hz by `nativeVideoStats`.
-    stats: Arc<crate::stats::VideoStats>,
-}
-
-impl SessionHandle {
-    /// Signal the decode thread to stop and join it. Idempotent.
-    fn stop_video(&self) {
-        if let Some(mut vt) = self.video.lock().unwrap().take() {
-            vt.shutdown.store(true, Ordering::SeqCst);
-            if let Some(j) = vt.join.take() {
-                let _ = j.join();
-            }
-        }
-    }
-
-    /// Stop + close audio playback. Dropping the [`crate::audio::AudioPlayback`] joins its decode
-    /// thread and closes the AAudio stream. Idempotent.
-    #[cfg(target_os = "android")]
-    fn stop_audio(&self) {
-        let _ = self.audio.lock().unwrap().take();
-    }
-
-    /// Stop mic uplink. Dropping the [`crate::mic::MicCapture`] joins its encode thread and closes
-    /// the AAudio input stream. Idempotent.
-    #[cfg(target_os = "android")]
-    fn stop_mic(&self) {
-        let _ = self.mic.lock().unwrap().take();
-    }
-}
-
-impl Drop for SessionHandle {
-    fn drop(&mut self) {
-        self.stop_video();
-        #[cfg(target_os = "android")]
-        self.stop_audio();
-        #[cfg(target_os = "android")]
-        self.stop_mic();
-    }
-}
-
-/// SHA-256 fingerprint → 64 lowercase hex chars (matches the host log + client-rs).
-fn hex32(fp: &[u8; 32]) -> String {
-    use std::fmt::Write;
-    fp.iter().fold(String::with_capacity(64), |mut s, b| {
-        let _ = write!(s, "{b:02x}");
-        s
-    })
-}
-
-/// 64-hex → [u8; 32]; `None` on bad length/char.
-fn parse_hex32(s: &str) -> Option<[u8; 32]> {
-    if s.len() != 64 {
-        return None;
-    }
-    let mut out = [0u8; 32];
-    for (i, b) in out.iter_mut().enumerate() {
-        *b = u8::from_str_radix(&s[2 * i..2 * i + 2], 16).ok()?;
-    }
-    Some(out)
-}
-
-/// `NativeBridge.nativeGenerateIdentity(): String` — mint a fresh persistent self-signed identity.
-/// Returns `"<certPem>\n-----PUNKTFUNK-KEY-----\n<keyPem>"`, or `""` on failure (logged). Kotlin
-/// persists it (Keystore-wrapped) and only calls this again when the store is genuinely empty.
-#[no_mangle]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeGenerateIdentity<'local>(
-    env: JNIEnv<'local>,
-    _this: JObject<'local>,
-) -> jni::sys::jstring {
-    let out = match punktfunk_core::quic::endpoint::generate_identity() {
-        Ok((cert, key)) => format!("{cert}\n-----PUNKTFUNK-KEY-----\n{key}"),
-        Err(e) => {
-            log::error!("nativeGenerateIdentity failed: {e}");
-            String::new()
-        }
-    };
-    match env.new_string(out) {
-        Ok(s) => s.into_raw(),
-        Err(_) => JObject::null().into_raw(),
-    }
-}
-
-/// `NativeBridge.nativeConnect(host, port, w, h, hz, certPem, keyPem, pinHex, bitrateKbps,
-/// compositorPref, gamepadPref): Long`. `certPem`/`keyPem` empty = anonymous, else presented as the
-/// persistent identity. `pinHex` empty = TOFU (read `nativeHostFingerprint` after), else 64-hex
-/// SHA-256 to pin the host (mismatch → 0). `bitrateKbps` 0 = host default. `compositorPref`/
-/// `gamepadPref` are `CompositorPref`/`GamepadPref` wire bytes (0 = Auto; unknown → Auto).
-/// Returns an opaque handle, or 0 on failure (logged).
-#[no_mangle]
-#[allow(clippy::too_many_arguments)]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'local>(
-    mut env: JNIEnv<'local>,
-    _this: JObject<'local>,
-    host: JString<'local>,
-    port: jint,
-    width: jint,
-    height: jint,
-    refresh_hz: jint,
-    cert_pem: JString<'local>,
-    key_pem: JString<'local>,
-    pin_hex: JString<'local>,
-    bitrate_kbps: jint,
-    compositor_pref: jint,
-    gamepad_pref: jint,
-    hdr_enabled: jboolean,
-) -> jlong {
-    let host: String = match env.get_string(&host) {
-        Ok(s) => s.into(),
-        Err(_) => return 0,
-    };
-    let cert: String = env
-        .get_string(&cert_pem)
-        .map(Into::into)
-        .unwrap_or_default();
-    let key: String = env.get_string(&key_pem).map(Into::into).unwrap_or_default();
-    let pin_hex: String = env.get_string(&pin_hex).map(Into::into).unwrap_or_default();
-
-    let identity: Option<(String, String)> = if cert.is_empty() || key.is_empty() {
-        None
-    } else {
-        Some((cert, key))
-    };
-    let pin: Option<[u8; 32]> = if pin_hex.is_empty() {
-        None
-    } else {
-        match parse_hex32(&pin_hex) {
-            Some(fp) => Some(fp),
-            None => {
-                log::error!("nativeConnect: bad pin hex (len {})", pin_hex.len());
-                return 0;
-            }
-        }
-    };
-    let mode = Mode {
-        width: width as u32,
-        height: height as u32,
-        refresh_hz: refresh_hz as u32,
-    };
-    match NativeClient::connect(
-        &host,
-        port as u16,
-        mode,
-        CompositorPref::from_u8(compositor_pref.clamp(0, u8::MAX as jint) as u8),
-        GamepadPref::from_u8(gamepad_pref.clamp(0, u8::MAX as jint) as u8),
-        bitrate_kbps.max(0) as u32, // 0 = host default
-        // Advertise 10-bit + HDR ONLY when this device's display can actually present it (Kotlin
-        // checks Display.getHdrCapabilities() and passes the result): the host (e.g. Windows) then
-        // upgrades to a Main10 / BT.2020 PQ encode. On an SDR display we advertise 0 so the host
-        // sends a proper 8-bit BT.709 stream rather than PQ the panel would mis-tone-map. AMediaCodec
-        // decodes Main10 from the SPS and the decode loop signals the Surface HDR dataspace + static
-        // metadata (see crate::decode).
-        if hdr_enabled != 0 {
-            punktfunk_core::quic::VIDEO_CAP_10BIT | punktfunk_core::quic::VIDEO_CAP_HDR
-        } else {
-            0
-        },
-        None,     // launch: default app
-        pin,      // Some → Crypto on host-fp mismatch
-        identity, // owned (cert, key) PEM, or None (anonymous)
-        Duration::from_secs(10),
-    ) {
-        Ok(client) => {
-            let handle = SessionHandle {
-                client: Arc::new(client),
-                video: Mutex::new(None),
-                #[cfg(target_os = "android")]
-                audio: Mutex::new(None),
-                #[cfg(target_os = "android")]
-                mic: Mutex::new(None),
-            };
-            Box::into_raw(Box::new(handle)) as jlong
-        }
-        Err(e) => {
-            log::error!("nativeConnect to {host}:{port} failed: {e}");
-            0
-        }
-    }
-}
-
-/// `NativeBridge.nativeClose(handle)` — drop the session (stops the decode thread, then RAII-tears
-/// down the connector). No-op on `0`.
-///
-/// # Safety contract
-/// `handle` must be `0` or a live handle from [`Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect`],
-/// closed exactly once and not concurrently with other calls on the same handle (Kotlin owns this).
-#[no_mangle]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClose(
-    _env: JNIEnv,
-    _this: JObject,
-    handle: jlong,
-) {
-    jni_guard((), || {
-        if handle != 0 {
-            // SAFETY: per the contract, `handle` is a live `Box<SessionHandle>` pointer.
-            unsafe { drop(Box::from_raw(handle as *mut SessionHandle)) };
-        }
-    })
-}
-
-/// `NativeBridge.nativeHostFingerprint(handle): String` — the SHA-256 (64-hex) of the cert the host
-/// presented on this connection. Valid after a successful `nativeConnect`; Kotlin pins it on a TOFU
-/// connect. `""` on a `0` handle.
-#[no_mangle]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeHostFingerprint<'local>(
-    env: JNIEnv<'local>,
-    _this: JObject<'local>,
-    handle: jlong,
-) -> jni::sys::jstring {
-    let out = if handle == 0 {
-        String::new()
-    } else {
-        // SAFETY: live handle per the nativeConnect/nativeClose contract.
-        let h = unsafe { &*(handle as *const SessionHandle) };
-        hex32(&h.client.host_fingerprint)
-    };
-    match env.new_string(out) {
-        Ok(s) => s.into_raw(),
-        Err(_) => JObject::null().into_raw(),
-    }
-}
-
-/// `NativeBridge.nativePair(host, port, certPem, keyPem, pin, name): String` — run the SPAKE2 PIN
-/// ceremony, presenting our persistent identity. On success returns the host's verified fingerprint
-/// (64-hex) to persist + pin; on any failure (wrong PIN / MITM / host reject / unreachable) returns
-/// `""` (logged). Blocking — Kotlin calls it off the UI thread.
-#[no_mangle]
-#[allow(clippy::too_many_arguments)]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativePair<'local>(
-    mut env: JNIEnv<'local>,
-    _this: JObject<'local>,
-    host: JString<'local>,
-    port: jint,
-    cert_pem: JString<'local>,
-    key_pem: JString<'local>,
-    pin: JString<'local>,
-    name: JString<'local>,
-) -> jni::sys::jstring {
-    let g = |e: &mut JNIEnv<'local>, j: &JString<'local>| -> String {
-        e.get_string(j).map(Into::into).unwrap_or_default()
-    };
-    let host = g(&mut env, &host);
-    let cert = g(&mut env, &cert_pem);
-    let key = g(&mut env, &key_pem);
-    let pin = g(&mut env, &pin);
-    let name = g(&mut env, &name);
-
-    let out = if host.is_empty() || cert.is_empty() || key.is_empty() {
-        log::error!("nativePair: missing host/identity");
-        String::new()
-    } else {
-        match NativeClient::pair(
-            &host,
-            port as u16,
-            (&cert, &key), // borrowed identity
-            &pin,
-            &name,
-            Duration::from_secs(60),
-        ) {
-            Ok(host_fp) => hex32(&host_fp),
-            Err(e) => {
-                // Crypto error == wrong PIN / MITM; anything else == transport/host reject.
-                log::error!("nativePair to {host}:{port} failed: {e}");
-                String::new()
-            }
-        }
-    };
-    match env.new_string(out) {
-        Ok(s) => s.into_raw(),
-        Err(_) => JObject::null().into_raw(),
-    }
-}
-
-/// `NativeBridge.nativeStartVideo(handle, surface)` — wrap the SurfaceView's `Surface` as an
-/// `ANativeWindow` and start the HEVC decode thread rendering onto it. No-op if already started.
-#[cfg(target_os = "android")]
-#[no_mangle]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
-    env: JNIEnv,
-    _this: JObject,
-    handle: jlong,
-    surface: JObject,
-) {
-    if handle == 0 {
-        return;
-    }
-    // SAFETY: live handle per the nativeConnect/nativeClose contract.
-    let h = unsafe { &*(handle as *const SessionHandle) };
-    let mut guard = h.video.lock().unwrap();
-    if guard.is_some() {
-        return; // already streaming
-    }
-    // SAFETY: `env`/`surface` are valid JNI pointers for this call. `as *mut _` bridges any
-    // jni-sys version skew between the `jni` and `ndk` crates (both are raw `*mut _` pointers).
-    let window = match unsafe {
-        ndk::native_window::NativeWindow::from_surface(
-            env.get_native_interface() as *mut _,
-            surface.as_raw() as *mut _,
-        )
-    } {
-        Some(w) => w,
-        None => {
-            log::error!("nativeStartVideo: no ANativeWindow from Surface");
-            return;
-        }
-    };
-    let shutdown = Arc::new(AtomicBool::new(false));
-    let stats = Arc::new(crate::stats::VideoStats::new());
-    let client = h.client.clone();
-    let sd = shutdown.clone();
-    let st = stats.clone();
-    let join = std::thread::Builder::new()
-        .name("pf-decode".into())
-        .spawn(move || crate::decode::run(client, window, sd, st))
-        .ok();
-    *guard = Some(VideoThread {
-        shutdown,
-        join,
-        stats,
-    });
-}
-
-/// `NativeBridge.nativeStopVideo(handle)` — stop + join the decode thread (without closing the
-/// session). No-op on `0`.
-#[no_mangle]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopVideo(
-    _env: JNIEnv,
-    _this: JObject,
-    handle: jlong,
-) {
-    jni_guard((), || {
-        if handle != 0 {
-            // SAFETY: live handle per the contract.
-            let h = unsafe { &*(handle as *const SessionHandle) };
-            h.stop_video();
-        }
-    })
-}
-
-/// `NativeBridge.nativeVideoStats(handle): DoubleArray?` — drain ~1 s of decode stats for the HUD.
-/// Returns 10 doubles
-/// `[fps, mbps, latP50Ms, latP95Ms, latValid, skewCorrected, width, height, refreshHz, framesDropped]`
-/// (the two flags are 1.0/0.0), or `null` when no decode thread is running. Poll ~1 Hz from the UI;
-/// each call resets the measurement window. Not android-gated — pure `jni` + connector reads, so it
-/// links on the host build too (Kotlin only ever calls it on device).
-#[no_mangle]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoStats(
-    env: JNIEnv,
-    _this: JObject,
-    handle: jlong,
-) -> jdoubleArray {
-    jni_guard(std::ptr::null_mut(), || {
-        if handle == 0 {
-            return std::ptr::null_mut();
-        }
-        // SAFETY: live handle per the nativeConnect/nativeClose contract.
-        let h = unsafe { &*(handle as *const SessionHandle) };
-        let snap = match h.video.lock().unwrap().as_ref() {
-            Some(vt) => vt.stats.drain(),
-            None => return std::ptr::null_mut(), // not streaming → no stats
-        };
-        let mode = h.client.mode();
-        let buf: [f64; 10] = [
-            snap.fps,
-            snap.mbps,
-            snap.lat_p50_ms,
-            snap.lat_p95_ms,
-            if snap.lat_valid { 1.0 } else { 0.0 },
-            if snap.skew_corrected { 1.0 } else { 0.0 },
-            mode.width as f64,
-            mode.height as f64,
-            mode.refresh_hz as f64,
-            h.client.frames_dropped() as f64,
-        ];
-        let arr = match env.new_double_array(buf.len() as jsize) {
-            Ok(a) => a,
-            Err(_) => return std::ptr::null_mut(),
-        };
-        if env.set_double_array_region(&arr, 0, &buf).is_err() {
-            return std::ptr::null_mut();
-        }
-        arr.into_raw()
-    })
-}
-
-/// `NativeBridge.nativeStartAudio(handle)` — start the Opus→AAudio playback thread. No-op if already
-/// started or on a `0` handle. Best-effort: a failure leaves video streaming.
-#[cfg(target_os = "android")]
-#[no_mangle]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartAudio(
-    _env: JNIEnv,
-    _this: JObject,
-    handle: jlong,
-) {
-    if handle == 0 {
-        return;
-    }
-    // SAFETY: live handle per the nativeConnect/nativeClose contract.
-    let h = unsafe { &*(handle as *const SessionHandle) };
-    let mut guard = h.audio.lock().unwrap();
-    if guard.is_some() {
-        return; // already playing
-    }
-    match crate::audio::AudioPlayback::start(h.client.clone()) {
-        Some(p) => *guard = Some(p),
-        None => log::error!("nativeStartAudio: playback init failed (video unaffected)"),
-    }
-}
-
-/// `NativeBridge.nativeStopAudio(handle)` — stop + join the audio thread and close AAudio (without
-/// closing the session). No-op on `0`.
-#[cfg(target_os = "android")]
-#[no_mangle]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopAudio(
-    _env: JNIEnv,
-    _this: JObject,
-    handle: jlong,
-) {
-    jni_guard((), || {
-        if handle != 0 {
-            // SAFETY: live handle per the contract.
-            let h = unsafe { &*(handle as *const SessionHandle) };
-            h.stop_audio();
-        }
-    })
-}
-
-/// `NativeBridge.nativeStartMic(handle)` — start mic capture (AAudio input → Opus → host `send_mic`).
-/// No-op if already running or on a `0` handle. Caller MUST hold RECORD_AUDIO; a failure (e.g. no
-/// permission) leaves the rest of the session streaming.
-#[cfg(target_os = "android")]
-#[no_mangle]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartMic(
-    _env: JNIEnv,
-    _this: JObject,
-    handle: jlong,
-) {
-    if handle == 0 {
-        return;
-    }
-    // SAFETY: live handle per the nativeConnect/nativeClose contract.
-    let h = unsafe { &*(handle as *const SessionHandle) };
-    let mut guard = h.mic.lock().unwrap();
-    if guard.is_some() {
-        return; // already capturing
-    }
-    match crate::mic::MicCapture::start(h.client.clone()) {
-        Some(m) => *guard = Some(m),
-        None => log::error!("nativeStartMic: mic init failed (RECORD_AUDIO? — session unaffected)"),
-    }
-}
-
-/// `NativeBridge.nativeStopMic(handle)` — stop + join the mic thread and close the AAudio input
-/// stream (without closing the session). No-op on `0`.
-#[cfg(target_os = "android")]
-#[no_mangle]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopMic(
-    _env: JNIEnv,
-    _this: JObject,
-    handle: jlong,
-) {
-    jni_guard((), || {
-        if handle != 0 {
-            // SAFETY: live handle per the contract.
-            let h = unsafe { &*(handle as *const SessionHandle) };
-            h.stop_mic();
-        }
-    })
-}
-
-// ---- Input plane: Kotlin capture → NativeClient::send_input ----------------------------------
-// All four are `&self` on the `Sync` connector (send_input is a non-blocking datagram push), safe
-// from the Kotlin UI thread. NOT android-gated — send_input exists on the host build too, so these
-// compile everywhere (parity with nativeConnect/nativeClose). The wire codes are the GameStream
-// conventions: buttons 1=left/2=middle/3=right/4=X1/5=X2; scroll axis 0=vertical/1=horizontal,
-// signed 120-unit delta, +=up/right; keys are Windows VK (mapped from KEYCODE_* on the Kotlin side).
-
-/// `NativeBridge.nativeSendPointerMove(handle, dx, dy)` — relative mouse motion (screen +y down).
-#[no_mangle]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointerMove(
-    _env: JNIEnv,
-    _this: JObject,
-    handle: jlong,
-    dx: jint,
-    dy: jint,
-) {
-    if handle == 0 {
-        return;
-    }
-    // SAFETY: live handle per the nativeConnect/nativeClose contract; send_input is &self.
-    let h = unsafe { &*(handle as *const SessionHandle) };
-    let _ = h.client.send_input(&InputEvent {
-        kind: InputKind::MouseMove,
-        _pad: [0; 3],
-        code: 0,
-        x: dx,
-        y: dy,
-        flags: 0,
-    });
-}
-
-/// `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]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointerButton(
-    _env: JNIEnv,
-    _this: JObject,
-    handle: jlong,
-    button: jint,
-    down: jboolean,
-) {
-    if handle == 0 {
-        return;
-    }
-    // SAFETY: live handle per the contract.
-    let h = unsafe { &*(handle as *const SessionHandle) };
-    let _ = h.client.send_input(&InputEvent {
-        kind: if down != 0 {
-            InputKind::MouseButtonDown
-        } else {
-            InputKind::MouseButtonUp
-        },
-        _pad: [0; 3],
-        code: button as u32,
-        x: 0,
-        y: 0,
-        flags: 0,
-    });
-}
-
-/// `NativeBridge.nativeSendScroll(handle, axis, delta)` — one scroll step. `axis`: 0=vertical,
-/// 1=horizontal. `delta`: signed, WHEEL_DELTA(120)-scaled, +=up/right.
-#[no_mangle]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendScroll(
-    _env: JNIEnv,
-    _this: JObject,
-    handle: jlong,
-    axis: jint,
-    delta: jint,
-) {
-    if handle == 0 {
-        return;
-    }
-    // SAFETY: live handle per the contract.
-    let h = unsafe { &*(handle as *const SessionHandle) };
-    let _ = h.client.send_input(&InputEvent {
-        kind: InputKind::MouseScroll,
-        _pad: [0; 3],
-        code: axis as u32,
-        x: delta,
-        y: 0,
-        flags: 0,
-    });
-}
-
-/// `NativeBridge.nativeSendKey(handle, vk, down, mods)` — one key transition. `vk`: Windows
-/// Virtual-Key code (0 = unmapped → dropped). `down`: 1=press, 0=release. `mods`: VK modifier
-/// bitmask (0 for now — the host folds modifiers from the L/R modifier key events themselves).
-#[no_mangle]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendKey(
-    _env: JNIEnv,
-    _this: JObject,
-    handle: jlong,
-    vk: jint,
-    down: jboolean,
-    mods: jint,
-) {
-    if handle == 0 || vk == 0 {
-        return;
-    }
-    // SAFETY: live handle per the contract.
-    let h = unsafe { &*(handle as *const SessionHandle) };
-    let _ = h.client.send_input(&InputEvent {
-        kind: if down != 0 {
-            InputKind::KeyDown
-        } else {
-            InputKind::KeyUp
-        },
-        _pad: [0; 3],
-        code: vk as u32,
-        x: 0,
-        y: 0,
-        flags: mods as u32,
-    });
-}
-
-// ---- Gamepad: Kotlin captures (KeyEvent/MotionEvent) → NativeClient::send_input ---------------
-// Single-pad model: exactly one controller, forwarded as pad 0 (flags = 0). Buttons carry the
-// gamepad::BTN_* bit in `code` and pressed/released in `x` (1/0); axes carry the gamepad::AXIS_* id
-// in `code` and the value in `x` (sticks i16 −32768..32767, +y = up; triggers 0..255). The host
-// accumulates the incremental events into its virtual xpad. Wire contract: input.rs::gamepad.
-
-/// `NativeBridge.nativeSendGamepadButton(handle, bit, down)` — one gamepad button transition.
-/// `bit`: a `gamepad::BTN_*` bit (e.g. BTN_A = 0x1000). `down`: 1=press, 0=release.
-#[no_mangle]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadButton(
-    _env: JNIEnv,
-    _this: JObject,
-    handle: jlong,
-    bit: jint,
-    down: jboolean,
-) {
-    if handle == 0 {
-        return;
-    }
-    // SAFETY: live handle per the contract.
-    let h = unsafe { &*(handle as *const SessionHandle) };
-    let _ = h.client.send_input(&InputEvent {
-        kind: InputKind::GamepadButton,
-        _pad: [0; 3],
-        code: bit as u32,
-        x: i32::from(down != 0),
-        y: 0,
-        flags: 0, // pad index 0 — single-pad model
-    });
-}
-
-/// `NativeBridge.nativeSendGamepadAxis(handle, axisId, value)` — one gamepad axis update.
-/// `axisId`: a `gamepad::AXIS_*` id (LS_X=0..RT=5). `value`: stick i16 (−32768..32767, +y=up) or
-/// trigger 0..255.
-#[no_mangle]
-pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadAxis(
-    _env: JNIEnv,
-    _this: JObject,
-    handle: jlong,
-    axis_id: jint,
-    value: jint,
-) {
-    if handle == 0 {
-        return;
-    }
-    // SAFETY: live handle per the contract.
-    let h = unsafe { &*(handle as *const SessionHandle) };
-    let _ = h.client.send_input(&InputEvent {
-        kind: InputKind::GamepadAxis,
-        _pad: [0; 3],
-        code: axis_id as u32,
-        x: value,
-        y: 0,
-        flags: 0, // pad index 0 — single-pad model
-    });
-}

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

@@ -0,0 +1,244 @@
+//! Connect lifecycle + the trust surface: identity mint, connect (TOFU / pinned), close,
+//! host-fingerprint read, and the SPAKE2 PIN pairing ceremony.
+
+use jni::objects::{JObject, JString};
+use jni::sys::{jboolean, jint, jlong};
+use jni::JNIEnv;
+use punktfunk_core::client::NativeClient;
+use punktfunk_core::config::{CompositorPref, GamepadPref, Mode};
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+use super::{hex32, jni_guard, parse_hex32, SessionHandle};
+
+/// `NativeBridge.nativeGenerateIdentity(): String` — mint a fresh persistent self-signed identity.
+/// Returns `"<certPem>\n-----PUNKTFUNK-KEY-----\n<keyPem>"`, or `""` on failure (logged). Kotlin
+/// persists it (Keystore-wrapped) and only calls this again when the store is genuinely empty.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeGenerateIdentity<'local>(
+    env: JNIEnv<'local>,
+    _this: JObject<'local>,
+) -> jni::sys::jstring {
+    let out = match punktfunk_core::quic::endpoint::generate_identity() {
+        Ok((cert, key)) => format!("{cert}\n-----PUNKTFUNK-KEY-----\n{key}"),
+        Err(e) => {
+            log::error!("nativeGenerateIdentity failed: {e}");
+            String::new()
+        }
+    };
+    match env.new_string(out) {
+        Ok(s) => s.into_raw(),
+        Err(_) => JObject::null().into_raw(),
+    }
+}
+
+/// `NativeBridge.nativeConnect(host, port, w, h, hz, certPem, keyPem, pinHex, bitrateKbps,
+/// compositorPref, gamepadPref, hdrEnabled, audioChannels, preferredCodec, timeoutMs): Long`.
+/// `certPem`/`keyPem` empty = anonymous, else presented as the persistent identity. `pinHex` empty
+/// = TOFU (read `nativeHostFingerprint` after), else 64-hex SHA-256 to pin the host (mismatch → 0).
+/// `bitrateKbps` 0 = host default. `compositorPref`/`gamepadPref` are `CompositorPref`/`GamepadPref`
+/// wire bytes (0 = Auto; unknown → Auto). `audioChannels` is the requested surround layout (2/6/8;
+/// normalized, anything else → stereo) — the host clamps it and the resolved count drives playback.
+/// `preferredCodec` is the soft codec preference wire byte (0 = Auto). `timeoutMs` is the handshake
+/// budget: the normal path passes a short value, the no-PIN "request access" path a long one (≥ the
+/// host's approval-park window) so a slow operator approval lands on this same parked connection
+/// rather than timing the client out first. Returns an opaque handle, or 0 on failure.
+#[no_mangle]
+#[allow(clippy::too_many_arguments)]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'local>(
+    mut env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    host: JString<'local>,
+    port: jint,
+    width: jint,
+    height: jint,
+    refresh_hz: jint,
+    cert_pem: JString<'local>,
+    key_pem: JString<'local>,
+    pin_hex: JString<'local>,
+    bitrate_kbps: jint,
+    compositor_pref: jint,
+    gamepad_pref: jint,
+    hdr_enabled: jboolean,
+    audio_channels: jint,
+    preferred_codec: jint,
+    timeout_ms: jint,
+) -> jlong {
+    let host: String = match env.get_string(&host) {
+        Ok(s) => s.into(),
+        Err(_) => return 0,
+    };
+    let cert: String = env
+        .get_string(&cert_pem)
+        .map(Into::into)
+        .unwrap_or_default();
+    let key: String = env.get_string(&key_pem).map(Into::into).unwrap_or_default();
+    let pin_hex: String = env.get_string(&pin_hex).map(Into::into).unwrap_or_default();
+
+    let identity: Option<(String, String)> = if cert.is_empty() || key.is_empty() {
+        None
+    } else {
+        Some((cert, key))
+    };
+    let pin: Option<[u8; 32]> = if pin_hex.is_empty() {
+        None
+    } else {
+        match parse_hex32(&pin_hex) {
+            Some(fp) => Some(fp),
+            None => {
+                log::error!("nativeConnect: bad pin hex (len {})", pin_hex.len());
+                return 0;
+            }
+        }
+    };
+    let mode = Mode {
+        width: width as u32,
+        height: height as u32,
+        refresh_hz: refresh_hz as u32,
+    };
+    match NativeClient::connect(
+        &host,
+        port as u16,
+        mode,
+        CompositorPref::from_u8(compositor_pref.clamp(0, u8::MAX as jint) as u8),
+        GamepadPref::from_u8(gamepad_pref.clamp(0, u8::MAX as jint) as u8),
+        bitrate_kbps.max(0) as u32, // 0 = host default
+        // Advertise 10-bit + HDR ONLY when this device's display can actually present it (Kotlin
+        // checks Display.getHdrCapabilities() and passes the result): the host (e.g. Windows) then
+        // upgrades to a Main10 / BT.2020 PQ encode. On an SDR display we advertise 0 so the host
+        // sends a proper 8-bit BT.709 stream rather than PQ the panel would mis-tone-map. AMediaCodec
+        // decodes Main10 from the SPS and the decode loop signals the Surface HDR dataspace + static
+        // metadata (see crate::decode).
+        if hdr_enabled != 0 {
+            punktfunk_core::quic::VIDEO_CAP_10BIT | punktfunk_core::quic::VIDEO_CAP_HDR
+        } else {
+            0
+        },
+        // Requested surround layout (2 = stereo / 6 = 5.1 / 8 = 7.1). The host clamps to what it can
+        // capture and echoes the resolved count in `connector.audio_channels`, which drives the
+        // decoder + AAudio layout (read in `crate::audio::AudioPlayback::start`). Anything else
+        // normalizes to stereo here.
+        punktfunk_core::audio::normalize_channels(audio_channels.clamp(0, u8::MAX as jint) as u8),
+        // Codecs this device can decode — AMediaCodec decodes both HEVC and H.264 (AV1 isn't wired;
+        // hosts don't emit it on the native path yet). The host resolves the emitted codec from these
+        // + the soft `preferred_codec` and echoes it in `connector.codec`, which drives the mime below.
+        punktfunk_core::quic::CODEC_H264 | punktfunk_core::quic::CODEC_HEVC,
+        preferred_codec.clamp(0, u8::MAX as jint) as u8,
+        None,     // launch: default app
+        pin,      // Some → Crypto on host-fp mismatch
+        identity, // owned (cert, key) PEM, or None (anonymous)
+        // Handshake budget from Kotlin: ~10 s for a normal connect, ~185 s for "request access"
+        // (the host parks the connection until the operator approves the device — see ConnectScreen).
+        Duration::from_millis(timeout_ms.max(0) as u64),
+    ) {
+        Ok(client) => {
+            let handle = SessionHandle {
+                client: Arc::new(client),
+                stats: Arc::new(crate::stats::VideoStats::new()),
+                video: Mutex::new(None),
+                #[cfg(target_os = "android")]
+                audio: Mutex::new(None),
+                #[cfg(target_os = "android")]
+                mic: Mutex::new(None),
+            };
+            Box::into_raw(Box::new(handle)) as jlong
+        }
+        Err(e) => {
+            log::error!("nativeConnect to {host}:{port} failed: {e}");
+            0
+        }
+    }
+}
+
+/// `NativeBridge.nativeClose(handle)` — drop the session (stops the decode thread, then RAII-tears
+/// down the connector). No-op on `0`.
+///
+/// # Safety contract
+/// `handle` must be `0` or a live handle from [`Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect`],
+/// closed exactly once and not concurrently with other calls on the same handle (Kotlin owns this).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClose(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    jni_guard((), || {
+        if handle != 0 {
+            // SAFETY: per the contract, `handle` is a live `Box<SessionHandle>` pointer.
+            unsafe { drop(Box::from_raw(handle as *mut SessionHandle)) };
+        }
+    })
+}
+
+/// `NativeBridge.nativeHostFingerprint(handle): String` — the SHA-256 (64-hex) of the cert the host
+/// presented on this connection. Valid after a successful `nativeConnect`; Kotlin pins it on a TOFU
+/// connect. `""` on a `0` handle.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeHostFingerprint<'local>(
+    env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    handle: jlong,
+) -> jni::sys::jstring {
+    let out = if handle == 0 {
+        String::new()
+    } else {
+        // SAFETY: live handle per the nativeConnect/nativeClose contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        hex32(&h.client.host_fingerprint)
+    };
+    match env.new_string(out) {
+        Ok(s) => s.into_raw(),
+        Err(_) => JObject::null().into_raw(),
+    }
+}
+
+/// `NativeBridge.nativePair(host, port, certPem, keyPem, pin, name): String` — run the SPAKE2 PIN
+/// ceremony, presenting our persistent identity. On success returns the host's verified fingerprint
+/// (64-hex) to persist + pin; on any failure (wrong PIN / MITM / host reject / unreachable) returns
+/// `""` (logged). Blocking — Kotlin calls it off the UI thread.
+#[no_mangle]
+#[allow(clippy::too_many_arguments)]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativePair<'local>(
+    mut env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    host: JString<'local>,
+    port: jint,
+    cert_pem: JString<'local>,
+    key_pem: JString<'local>,
+    pin: JString<'local>,
+    name: JString<'local>,
+) -> jni::sys::jstring {
+    let g = |e: &mut JNIEnv<'local>, j: &JString<'local>| -> String {
+        e.get_string(j).map(Into::into).unwrap_or_default()
+    };
+    let host = g(&mut env, &host);
+    let cert = g(&mut env, &cert_pem);
+    let key = g(&mut env, &key_pem);
+    let pin = g(&mut env, &pin);
+    let name = g(&mut env, &name);
+
+    let out = if host.is_empty() || cert.is_empty() || key.is_empty() {
+        log::error!("nativePair: missing host/identity");
+        String::new()
+    } else {
+        match NativeClient::pair(
+            &host,
+            port as u16,
+            (&cert, &key), // borrowed identity
+            &pin,
+            &name,
+            Duration::from_secs(60),
+        ) {
+            Ok(host_fp) => hex32(&host_fp),
+            Err(e) => {
+                // Crypto error == wrong PIN / MITM; anything else == transport/host reject.
+                log::error!("nativePair to {host}:{port} failed: {e}");
+                String::new()
+            }
+        }
+    };
+    match env.new_string(out) {
+        Ok(s) => s.into_raw(),
+        Err(_) => JObject::null().into_raw(),
+    }
+}

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

@@ -0,0 +1,187 @@
+//! Input plane: Kotlin capture → `NativeClient::send_input`.
+//!
+//! All shims are `&self` on the `Sync` connector (send_input is a non-blocking datagram push), safe
+//! from the Kotlin UI thread. NOT android-gated — send_input exists on the host build too, so these
+//! compile everywhere (parity with nativeConnect/nativeClose). The wire codes are the GameStream
+//! conventions: buttons 1=left/2=middle/3=right/4=X1/5=X2; scroll axis 0=vertical/1=horizontal,
+//! signed 120-unit delta, +=up/right; keys are Windows VK (mapped from KEYCODE_* on the Kotlin side).
+
+use jni::objects::JObject;
+use jni::sys::{jboolean, jint, jlong};
+use jni::JNIEnv;
+use punktfunk_core::input::{InputEvent, InputKind};
+
+use super::SessionHandle;
+
+/// Shared shim body: guard against a `0` handle, deref, and push one [`InputEvent`].
+fn send_event(handle: jlong, kind: InputKind, code: u32, x: i32, y: i32, flags: u32) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the nativeConnect/nativeClose contract; send_input is &self.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind,
+        _pad: [0; 3],
+        code,
+        x,
+        y,
+        flags,
+    });
+}
+
+/// `NativeBridge.nativeSendPointerMove(handle, dx, dy)` — relative mouse motion (screen +y down).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointerMove(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    dx: jint,
+    dy: jint,
+) {
+    send_event(handle, InputKind::MouseMove, 0, dx, dy, 0);
+}
+
+/// `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,
+) {
+    let w = (surface_width.max(0) as u32) & 0xffff;
+    let ht = (surface_height.max(0) as u32) & 0xffff;
+    send_event(handle, InputKind::MouseMoveAbs, 0, x, y, (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]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointerButton(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    button: jint,
+    down: jboolean,
+) {
+    let kind = if down != 0 {
+        InputKind::MouseButtonDown
+    } else {
+        InputKind::MouseButtonUp
+    };
+    send_event(handle, kind, button as u32, 0, 0, 0);
+}
+
+/// `NativeBridge.nativeSendScroll(handle, axis, delta)` — one scroll step. `axis`: 0=vertical,
+/// 1=horizontal. `delta`: signed, WHEEL_DELTA(120)-scaled, +=up/right.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendScroll(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    axis: jint,
+    delta: jint,
+) {
+    send_event(handle, InputKind::MouseScroll, axis as u32, delta, 0, 0);
+}
+
+/// `NativeBridge.nativeSendTouch(handle, id, kind, x, y, surfaceWidth, surfaceHeight)` — one REAL
+/// touchscreen transition (`kind`: 0=down 1=move 2=up), for the touch-passthrough input mode. `id`
+/// distinguishes fingers (reusable after up); coordinates are pixels on the client's touch
+/// surface, whose size rides in `flags` so the host can rescale into the output (identical
+/// packing to MouseMoveAbs). On up only the id matters. The host injects a real touch contact
+/// (libei touchscreen / wlroots / SendInput).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendTouch(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    id: jint,
+    kind: jint,
+    x: jint,
+    y: jint,
+    surface_width: jint,
+    surface_height: jint,
+) {
+    let kind = match kind {
+        0 => InputKind::TouchDown,
+        1 => InputKind::TouchMove,
+        _ => InputKind::TouchUp,
+    };
+    let w = (surface_width.max(0) as u32) & 0xffff;
+    let h = (surface_height.max(0) as u32) & 0xffff;
+    send_event(handle, kind, id as u32, x, y, (w << 16) | h);
+}
+
+/// `NativeBridge.nativeSendKey(handle, vk, down, mods)` — one key transition. `vk`: Windows
+/// Virtual-Key code (0 = unmapped → dropped). `down`: 1=press, 0=release. `mods`: VK modifier
+/// bitmask (0 for now — the host folds modifiers from the L/R modifier key events themselves).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendKey(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    vk: jint,
+    down: jboolean,
+    mods: jint,
+) {
+    if vk == 0 {
+        return;
+    }
+    let kind = if down != 0 {
+        InputKind::KeyDown
+    } else {
+        InputKind::KeyUp
+    };
+    send_event(handle, kind, vk as u32, 0, 0, mods as u32);
+}
+
+// ---- Gamepad: Kotlin captures (KeyEvent/MotionEvent) → NativeClient::send_input ---------------
+// Single-pad model: exactly one controller, forwarded as pad 0 (flags = 0). Buttons carry the
+// gamepad::BTN_* bit in `code` and pressed/released in `x` (1/0); axes carry the gamepad::AXIS_* id
+// in `code` and the value in `x` (sticks i16 −32768..32767, +y = up; triggers 0..255). The host
+// accumulates the incremental events into its virtual xpad. Wire contract: input.rs::gamepad.
+
+/// `NativeBridge.nativeSendGamepadButton(handle, bit, down)` — one gamepad button transition.
+/// `bit`: a `gamepad::BTN_*` bit (e.g. BTN_A = 0x1000). `down`: 1=press, 0=release.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadButton(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    bit: jint,
+    down: jboolean,
+) {
+    // flags = 0: pad index 0 — single-pad model.
+    send_event(
+        handle,
+        InputKind::GamepadButton,
+        bit as u32,
+        i32::from(down != 0),
+        0,
+        0,
+    );
+}
+
+/// `NativeBridge.nativeSendGamepadAxis(handle, axisId, value)` — one gamepad axis update.
+/// `axisId`: a `gamepad::AXIS_*` id (LS_X=0..RT=5). `value`: stick i16 (−32768..32767, +y=up) or
+/// trigger 0..255.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadAxis(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    axis_id: jint,
+    value: jint,
+) {
+    // flags = 0: pad index 0 — single-pad model.
+    send_event(handle, InputKind::GamepadAxis, axis_id as u32, value, 0, 0);
+}

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

@@ -0,0 +1,124 @@
+//! Session lifecycle + plane wiring over JNI.
+//!
+//! A connected session is a [`SessionHandle`] — an `Arc<NativeClient>` plus the decode thread it
+//! feeds — boxed and handed to Kotlin as an opaque `jlong`. The connector is `Sync`, so the decode
+//! thread pulls the video plane (`next_frame`) directly while Kotlin still holds the handle.
+//!
+//! Wired: connect/close, the video plane (HEVC `next_frame` → NDK AMediaCodec → the SurfaceView's
+//! `ANativeWindow`, see [`crate::decode`]), host→client audio ([`crate::audio`]), input
+//! (`send_input` — mouse/keyboard/gamepad), rumble/DualSense HID feedback ([`crate::feedback`]),
+//! and the trust surface: `nativeGenerateIdentity` (persistent identity, Keystore-wrapped on the
+//! Kotlin side), `nativeConnect` with identity + pin (TOFU / pinned), and `nativePair` (SPAKE2 PIN).
+//!
+//! Split by concern: [`connect`] (identity + connect/close + the trust surface), [`planes`]
+//! (video/audio/mic start/stop + the stats drain), [`input`] (the input-plane shims). This module
+//! keeps the shared infrastructure they all deref through.
+//!
+//! TODO(M4 Android stage 1): client→host DualSense rich input (`send_rich_input`), mode
+//! renegotiation. Port the remaining orchestration from `clients/linux`.
+
+mod connect;
+mod input;
+mod planes;
+
+use punktfunk_core::client::NativeClient;
+use std::panic::AssertUnwindSafe;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+use std::thread::JoinHandle;
+
+/// Run a JNI body, catching any panic at the FFI boundary and returning `default` instead.
+///
+/// A panic unwinding out of an `extern "system"` function aborts the whole process on Rust ≥ 1.81 —
+/// a hard crash of the embedding Android app with no logcat trace. This mirrors the discipline the C
+/// ABI already enforces (`punktfunk_core::abi` wraps every entry point in `catch_unwind`); the
+/// `panic = "unwind"` profile in the workspace `Cargo.toml` exists precisely so these guards work.
+/// We apply it to the teardown + background-thread shims (the "leaving a stream" path), where an
+/// unexpected panic (e.g. a poisoned `Mutex` during concurrent teardown) must degrade to a logged
+/// no-op rather than kill the app.
+pub(crate) fn jni_guard<T>(default: T, f: impl FnOnce() -> T) -> T {
+    std::panic::catch_unwind(AssertUnwindSafe(f)).unwrap_or_else(|_| {
+        log::error!("punktfunk JNI: caught a panic at the FFI boundary (returning default)");
+        default
+    })
+}
+
+/// A live session behind the `jlong` handle: the connector + the decode thread it feeds.
+pub(crate) struct SessionHandle {
+    // Read only by the android decode path (`nativeStartVideo` → `crate::decode`); on the host
+    // build (CI's workspace clippy/build) those readers are cfg'd out, so it's intentionally unused.
+    #[cfg_attr(not(target_os = "android"), allow(dead_code))]
+    pub client: Arc<NativeClient>,
+    /// Live decode stats, written by the decode thread and drained ~1 Hz by `nativeVideoStats`.
+    /// Session-lifetime (not per `VideoThread`) so the HUD's enable gate set via
+    /// `nativeSetVideoStatsEnabled` survives surface teardown/recreate and can land before
+    /// `nativeStartVideo` — enabling resets the window, so no stale data leaks across restarts.
+    pub stats: Arc<crate::stats::VideoStats>,
+    video: Mutex<Option<VideoThread>>,
+    #[cfg(target_os = "android")]
+    audio: Mutex<Option<crate::audio::AudioPlayback>>,
+    #[cfg(target_os = "android")]
+    mic: Mutex<Option<crate::mic::MicCapture>>,
+}
+
+struct VideoThread {
+    shutdown: Arc<AtomicBool>,
+    join: Option<JoinHandle<()>>,
+}
+
+impl SessionHandle {
+    /// Signal the decode thread to stop and join it. Idempotent.
+    fn stop_video(&self) {
+        if let Some(mut vt) = self.video.lock().unwrap().take() {
+            vt.shutdown.store(true, Ordering::SeqCst);
+            if let Some(j) = vt.join.take() {
+                let _ = j.join();
+            }
+        }
+    }
+
+    /// Stop + close audio playback. Dropping the [`crate::audio::AudioPlayback`] joins its decode
+    /// thread and closes the AAudio stream. Idempotent.
+    #[cfg(target_os = "android")]
+    fn stop_audio(&self) {
+        let _ = self.audio.lock().unwrap().take();
+    }
+
+    /// Stop mic uplink. Dropping the [`crate::mic::MicCapture`] joins its encode thread and closes
+    /// the AAudio input stream. Idempotent.
+    #[cfg(target_os = "android")]
+    fn stop_mic(&self) {
+        let _ = self.mic.lock().unwrap().take();
+    }
+}
+
+impl Drop for SessionHandle {
+    fn drop(&mut self) {
+        self.stop_video();
+        #[cfg(target_os = "android")]
+        self.stop_audio();
+        #[cfg(target_os = "android")]
+        self.stop_mic();
+    }
+}
+
+/// SHA-256 fingerprint → 64 lowercase hex chars (matches the host log + client-rs).
+fn hex32(fp: &[u8; 32]) -> String {
+    use std::fmt::Write;
+    fp.iter().fold(String::with_capacity(64), |mut s, b| {
+        let _ = write!(s, "{b:02x}");
+        s
+    })
+}
+
+/// 64-hex → [u8; 32]; `None` on bad length/char.
+fn parse_hex32(s: &str) -> Option<[u8; 32]> {
+    if s.len() != 64 {
+        return None;
+    }
+    let mut out = [0u8; 32];
+    for (i, b) in out.iter_mut().enumerate() {
+        *b = u8::from_str_radix(&s[2 * i..2 * i + 2], 16).ok()?;
+    }
+    Some(out)
+}

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

@@ -0,0 +1,248 @@
+//! Plane start/stop: video (HEVC decode → Surface), host→client audio, mic uplink — plus the
+//! ~1 Hz decode-stats drain for the HUD.
+
+use jni::objects::JObject;
+use jni::sys::{jboolean, jdoubleArray, jlong, jsize};
+use jni::JNIEnv;
+
+use super::{jni_guard, SessionHandle};
+
+/// `NativeBridge.nativeStartVideo(handle, surface)` — wrap the SurfaceView's `Surface` as an
+/// `ANativeWindow` and start the HEVC decode thread rendering onto it. No-op if already started.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
+    env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    surface: JObject,
+) {
+    use super::VideoThread;
+    use std::sync::atomic::AtomicBool;
+    use std::sync::Arc;
+
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the nativeConnect/nativeClose contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let mut guard = h.video.lock().unwrap();
+    if guard.is_some() {
+        return; // already streaming
+    }
+    // SAFETY: `env`/`surface` are valid JNI pointers for this call. `as *mut _` bridges any
+    // jni-sys version skew between the `jni` and `ndk` crates (both are raw `*mut _` pointers).
+    let window = match unsafe {
+        ndk::native_window::NativeWindow::from_surface(
+            env.get_native_interface() as *mut _,
+            surface.as_raw() as *mut _,
+        )
+    } {
+        Some(w) => w,
+        None => {
+            log::error!("nativeStartVideo: no ANativeWindow from Surface");
+            return;
+        }
+    };
+    let shutdown = Arc::new(AtomicBool::new(false));
+    let client = h.client.clone();
+    let sd = shutdown.clone();
+    let st = h.stats.clone(); // session-lifetime stats (gate survives surface recreate)
+    let join = std::thread::Builder::new()
+        .name("pf-decode".into())
+        .spawn(move || crate::decode::run(client, window, sd, st))
+        .ok();
+    *guard = Some(VideoThread { shutdown, join });
+}
+
+/// `NativeBridge.nativeStopVideo(handle)` — stop + join the decode thread (without closing the
+/// session). No-op on `0`.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopVideo(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    jni_guard((), || {
+        if handle != 0 {
+            // SAFETY: live handle per the contract.
+            let h = unsafe { &*(handle as *const SessionHandle) };
+            h.stop_video();
+        }
+    })
+}
+
+/// `NativeBridge.nativeVideoStats(handle): DoubleArray?` — drain ~1 s of decode stats for the HUD
+/// (unified stats spec, `design/stats-unification.md`). Returns 18 doubles
+/// `[fps, mbps, e2eP50Ms, e2eP95Ms, latValid, skewCorrected, width, height, refreshHz, framesLost,
+/// bitDepth, colorPrimaries, colorTransfer, chromaFormatIdc, hostNetP50Ms, decodeP50Ms, hostP50Ms,
+/// netP50Ms]`
+/// (the two flags are 1.0/0.0; indexes 0–15 match the previous 16-double layout — 0–13 the original
+/// 14-double one with the latency pair re-based to the end-to-end capture→decoded headline, 14/15
+/// the stage p50s tiling it: `host+network` = capture→received, `decode` = received→decoded; 16/17
+/// are the Phase-2 split of the `host+network` term from the per-AU 0xCF host timings — `host` =
+/// the host's capture→sent, `network` = the remainder — both 0.0 when no timing matched this
+/// window, i.e. an old host), or `null` when no decode thread is running. Poll ~1 Hz from the UI; each call
+/// resets the measurement window. Not android-gated — pure `jni` + connector reads, so it links on
+/// the host build too (Kotlin only ever calls it on device).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoStats(
+    env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) -> jdoubleArray {
+    jni_guard(std::ptr::null_mut(), || {
+        if handle == 0 {
+            return std::ptr::null_mut();
+        }
+        // SAFETY: live handle per the nativeConnect/nativeClose contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        if h.video.lock().unwrap().is_none() {
+            return std::ptr::null_mut(); // not streaming → no stats
+        }
+        let snap = h.stats.drain();
+        let mode = h.client.mode();
+        let color = h.client.color;
+        let buf: [f64; 18] = [
+            snap.fps,
+            snap.mbps,
+            snap.e2e_p50_ms,
+            snap.e2e_p95_ms,
+            if snap.lat_valid { 1.0 } else { 0.0 },
+            if snap.skew_corrected { 1.0 } else { 0.0 },
+            mode.width as f64,
+            mode.height as f64,
+            mode.refresh_hz as f64,
+            h.client.frames_dropped() as f64,
+            // Video-feed properties the host resolved at the handshake (Welcome): encode bit depth
+            // (8 / 10), the CICP colour primaries + transfer code points (Kotlin maps these to a
+            // colour-space / HDR label — transfer 16 = PQ, 18 = HLG ⇒ HDR), and the HEVC
+            // chroma_format_idc (1 = 4:2:0, 3 = 4:4:4). Static for the session unless renegotiated.
+            h.client.bit_depth as f64,
+            color.primaries as f64,
+            color.transfer as f64,
+            h.client.chroma_format as f64,
+            // Stage p50s tiling the end-to-end headline (appended to keep 0–13 index-compatible).
+            snap.hostnet_p50_ms,
+            snap.decode_p50_ms,
+            // Phase-2 host/network split of the `host+network` stage (0xCF host timings): 0.0
+            // when no timing matched this window (old host) — the HUD keeps the combined term.
+            snap.host_p50_ms,
+            snap.net_p50_ms,
+        ];
+        let arr = match env.new_double_array(buf.len() as jsize) {
+            Ok(a) => a,
+            Err(_) => return std::ptr::null_mut(),
+        };
+        if env.set_double_array_region(&arr, 0, &buf).is_err() {
+            return std::ptr::null_mut();
+        }
+        arr.into_raw()
+    })
+}
+
+/// `NativeBridge.nativeSetVideoStatsEnabled(handle, enabled)` — gate per-frame stats sampling on the
+/// HUD actually being visible: while disabled the decode thread skips the clock read + lock per AU.
+/// Enabling resets the measurement window so a later show never reports stale data. Sticky for the
+/// session (survives video stop/start across surface recreation). No-op on `0`. Not android-gated —
+/// pure `jni` + an atomic store, so it links on the host build too.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSetVideoStatsEnabled(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    enabled: jboolean,
+) {
+    jni_guard((), || {
+        if handle != 0 {
+            // SAFETY: live handle per the nativeConnect/nativeClose contract.
+            let h = unsafe { &*(handle as *const SessionHandle) };
+            h.stats.set_enabled(enabled != 0);
+        }
+    })
+}
+
+/// `NativeBridge.nativeStartAudio(handle)` — start the Opus→AAudio playback thread. No-op if already
+/// started or on a `0` handle. Best-effort: a failure leaves video streaming.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartAudio(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the nativeConnect/nativeClose contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let mut guard = h.audio.lock().unwrap();
+    if guard.is_some() {
+        return; // already playing
+    }
+    match crate::audio::AudioPlayback::start(h.client.clone()) {
+        Some(p) => *guard = Some(p),
+        None => log::error!("nativeStartAudio: playback init failed (video unaffected)"),
+    }
+}
+
+/// `NativeBridge.nativeStopAudio(handle)` — stop + join the audio thread and close AAudio (without
+/// closing the session). No-op on `0`.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopAudio(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    jni_guard((), || {
+        if handle != 0 {
+            // SAFETY: live handle per the contract.
+            let h = unsafe { &*(handle as *const SessionHandle) };
+            h.stop_audio();
+        }
+    })
+}
+
+/// `NativeBridge.nativeStartMic(handle)` — start mic capture (AAudio input → Opus → host `send_mic`).
+/// No-op if already running or on a `0` handle. Caller MUST hold RECORD_AUDIO; a failure (e.g. no
+/// permission) leaves the rest of the session streaming.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartMic(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the nativeConnect/nativeClose contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let mut guard = h.mic.lock().unwrap();
+    if guard.is_some() {
+        return; // already capturing
+    }
+    match crate::mic::MicCapture::start(h.client.clone()) {
+        Some(m) => *guard = Some(m),
+        None => log::error!("nativeStartMic: mic init failed (RECORD_AUDIO? — session unaffected)"),
+    }
+}
+
+/// `NativeBridge.nativeStopMic(handle)` — stop + join the mic thread and close the AAudio input
+/// stream (without closing the session). No-op on `0`.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopMic(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    jni_guard((), || {
+        if handle != 0 {
+            // SAFETY: live handle per the contract.
+            let h = unsafe { &*(handle as *const SessionHandle) };
+            h.stop_mic();
+        }
+    })
+}

clients/android/native/src/stats.rs

@@ -1,15 +1,27 @@
-//! Live decode stats for the on-stream HUD (mirrors the Apple client's stats overlay): FPS,
-//! receive throughput, and capture→client-receipt latency (p50/p95). The decode thread is the sole
-//! writer (`note` per access unit); the JNI accessor `nativeVideoStats` drains a snapshot ~1 Hz and
-//! resets the window. Pure `std` so it compiles on the host build too (the decode thread is
-//! android-only, but `VideoThread` holds the shared handle unconditionally).
+//! Live decode stats for the on-stream HUD, following the unified stats spec
+//! (`design/stats-unification.md`): FPS, receive throughput, and the Android v1 stage split —
+//! headline `end-to-end` = capture→decoded (p50/p95) tiled by `host+network` = capture→received
+//! and `decode` = received→decoded (stage p50s). When the host emits per-AU 0xCF host timings, the
+//! `host+network` term further splits into `host` + `network` (Phase 2, `note_host_split`); an old
+//! host emits none and the combined term stands. The decode thread is the sole writer
+//! (`note_received` per access unit at receipt, `note_decoded` per decoder output buffer); the JNI
+//! accessor `nativeVideoStats` drains a snapshot ~1 Hz and resets the window. Sampling is gated on
+//! the HUD actually being visible (`set_enabled`, driven by `nativeSetVideoStatsEnabled`) so the
+//! hidden steady state costs one relaxed atomic load per frame.
+//! Pure `std` so it compiles on the host build too (the decode thread is android-only, but
+//! `SessionHandle` holds the shared handle unconditionally).
 
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::Mutex;
 use std::time::Instant;
 
 /// Rolling per-window accumulator. Rates are computed over the actual elapsed wall-time at drain
 /// (robust to poll jitter), so a poll that lands at 0.9 s or 1.1 s still reports the right FPS.
 pub struct VideoStats {
+    /// HUD gate: the samplers run on the per-frame decode path, so while the overlay is hidden
+    /// they (and the caller's latency computation — see `enabled`) early-out on this flag alone.
+    /// Off until Kotlin shows the HUD.
+    enabled: AtomicBool,
     inner: Mutex<Inner>,
 }
 
@@ -17,77 +29,198 @@ struct Inner {
     window_start: Instant,
     frames: u64,
     bytes: u64,
-    /// capture→client-receipt latency samples for this window, in microseconds.
-    lat_us: Vec<u64>,
+    /// `end-to-end` = capture→decoded latency samples for this window, in microseconds
+    /// (skew-corrected clock base).
+    e2e_us: Vec<u64>,
+    /// `host+network` stage = capture→received samples, in microseconds (skew-corrected).
+    hostnet_us: Vec<u64>,
+    /// Phase-2 split of `host+network` (design/stats-unification.md Phase 2), fed only when the
+    /// host emits per-AU 0xCF timings: `host` = the host's own capture→sent duration, µs.
+    host_us: Vec<u64>,
+    /// The matching `network` term, µs: capture→received minus the host's capture→sent
+    /// (wire + reassembly). Always pushed in lockstep with `host_us`.
+    net_us: Vec<u64>,
+    /// `decode` stage = received→decoded samples, in microseconds (client-local, single clock).
+    decode_us: Vec<u64>,
     /// Whether the host answered the clock-skew handshake (latency is cross-machine valid).
     skew_corrected: bool,
 }
 
-/// A drained, computed view of one window. `lat_valid` is false when no in-range latency sample
-/// landed (then p50/p95 are 0 and the HUD hides the latency line, exactly like the Apple client).
+/// A drained, computed view of one window. `lat_valid` is false when no in-range end-to-end sample
+/// landed (then the latency figures are 0 and the HUD hides the latency lines, exactly like the
+/// Apple client).
 pub struct Snapshot {
     pub fps: f64,
     pub mbps: f64,
-    pub lat_p50_ms: f64,
-    pub lat_p95_ms: f64,
+    /// Headline `end-to-end` (capture→decoded) percentiles, ms.
+    pub e2e_p50_ms: f64,
+    pub e2e_p95_ms: f64,
+    /// Stage p50s (ms): `host+network` (capture→received) and `decode` (received→decoded).
+    pub hostnet_p50_ms: f64,
+    pub decode_p50_ms: f64,
+    /// Phase-2 `host` / `network` split p50s (ms) — 0.0 when no 0xCF timing matched this window
+    /// (old host / no samples yet), in which case the HUD keeps the combined `host+network` term.
+    pub host_p50_ms: f64,
+    pub net_p50_ms: f64,
     pub lat_valid: bool,
     pub skew_corrected: bool,
 }
 
+/// Percentile over a sorted-in-place µs sample vec, in ms. 0.0 when empty.
+fn pctl_ms(sorted_us: &[u64], p: f64) -> f64 {
+    if sorted_us.is_empty() {
+        return 0.0;
+    }
+    let n = sorted_us.len();
+    sorted_us[((n as f64 * p) as usize).min(n - 1)] as f64 / 1000.0
+}
+
 impl VideoStats {
-    // `new`/`note` are driven only by the android-only decode thread; `drain` (the JNI accessor) is
-    // ungated, so on the host build these two are unreferenced — that's expected, not dead code.
-    #[cfg_attr(not(target_os = "android"), allow(dead_code))]
     pub fn new() -> VideoStats {
         VideoStats {
+            enabled: AtomicBool::new(false),
             inner: Mutex::new(Inner {
                 window_start: Instant::now(),
                 frames: 0,
                 bytes: 0,
-                lat_us: Vec::with_capacity(256),
+                e2e_us: Vec::with_capacity(256),
+                hostnet_us: Vec::with_capacity(256),
+                host_us: Vec::with_capacity(256),
+                net_us: Vec::with_capacity(256),
+                decode_us: Vec::with_capacity(256),
                 skew_corrected: false,
             }),
         }
     }
 
-    /// Record one decoded access unit: its wire size and (if in range) its capture→client latency.
+    /// Whether the HUD wants samples. The decode thread checks this BEFORE building a latency
+    /// sample, so the per-frame wall-clock reads are skipped too while hidden.
+    // Read only by the android-only decode thread; unreferenced on the host build — expected.
     #[cfg_attr(not(target_os = "android"), allow(dead_code))]
-    pub fn note(&self, bytes: usize, lat_us: Option<u64>, skew_corrected: bool) {
-        let mut g = self.inner.lock().unwrap();
+    pub fn enabled(&self) -> bool {
+        self.enabled.load(Ordering::Relaxed)
+    }
+
+    /// Toggle sampling. Enabling resets the window, so the first HUD poll after a show never mixes
+    /// in counters (or a window start) from before the overlay was visible.
+    pub fn set_enabled(&self, on: bool) {
+        let was = self.enabled.swap(on, Ordering::Relaxed);
+        if on && !was {
+            let mut g = self
+                .inner
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
+            g.window_start = Instant::now();
+            g.frames = 0;
+            g.bytes = 0;
+            g.e2e_us.clear();
+            g.hostnet_us.clear();
+            g.host_us.clear();
+            g.net_us.clear();
+            g.decode_us.clear();
+        }
+    }
+
+    /// Record one received access unit: its wire size and (if in range) its capture→received
+    /// `host+network` stage sample. Receipt is the fps/goodput counting point per the spec.
+    // Driven only by the android-only decode thread; unreferenced on the host build — expected.
+    #[cfg_attr(not(target_os = "android"), allow(dead_code))]
+    pub fn note_received(&self, bytes: usize, hostnet_us: Option<u64>, skew_corrected: bool) {
+        if !self.enabled.load(Ordering::Relaxed) {
+            return; // HUD hidden — skip the lock (the caller already skipped the clock read)
+        }
+        // Poison-proof: this runs per-frame on the decode thread, which has no catch_unwind —
+        // a panic elsewhere must not turn every later lock into a second panic (the counters
+        // stay consistent regardless).
+        let mut g = self
+            .inner
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
         g.frames += 1;
         g.bytes += bytes as u64;
         g.skew_corrected = skew_corrected;
-        if let Some(l) = lat_us {
-            g.lat_us.push(l);
+        if let Some(l) = hostnet_us {
+            g.hostnet_us.push(l);
+        }
+    }
+
+    /// Record one matched host/network split sample (Phase 2): the host's reported capture→sent
+    /// duration and our capture→received minus it, both µs — one pair per AU whose 0xCF host
+    /// timing arrived and matched by pts. An old host emits none, leaving the vecs empty and the
+    /// snapshot p50s at 0 (HUD keeps the combined `host+network` term).
+    // Driven only by the android-only decode thread; unreferenced on the host build — expected.
+    #[cfg_attr(not(target_os = "android"), allow(dead_code))]
+    pub fn note_host_split(&self, host_us: u64, net_us: u64) {
+        if !self.enabled.load(Ordering::Relaxed) {
+            return; // HUD hidden — skip the lock
+        }
+        // Poison-proof for the same reason as `note_received`.
+        let mut g = self
+            .inner
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        g.host_us.push(host_us);
+        g.net_us.push(net_us);
+    }
+
+    /// Record one decoded output frame: its capture→decoded `end-to-end` sample and its
+    /// received→decoded `decode` stage sample (either may be absent — e.g. the receipt stamp for
+    /// this pts predates the HUD being shown).
+    // Driven only by the android-only decode thread; unreferenced on the host build — expected.
+    #[cfg_attr(not(target_os = "android"), allow(dead_code))]
+    pub fn note_decoded(&self, e2e_us: Option<u64>, decode_us: Option<u64>) {
+        if !self.enabled.load(Ordering::Relaxed) {
+            return; // HUD hidden — skip the lock (the caller already skipped the clock read)
+        }
+        // Poison-proof for the same reason as `note_received`.
+        let mut g = self
+            .inner
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if let Some(l) = e2e_us {
+            g.e2e_us.push(l);
+        }
+        if let Some(l) = decode_us {
+            g.decode_us.push(l);
         }
     }
 
     /// Compute the window's rates + latency percentiles, then reset for the next window.
     pub fn drain(&self) -> Snapshot {
-        let mut g = self.inner.lock().unwrap();
+        // Poison-proof for the same reason as `note_received` — a poisoned window still drains
+        // fine.
+        let mut g = self
+            .inner
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
         let elapsed = g.window_start.elapsed().as_secs_f64().max(1e-3);
         let fps = g.frames as f64 / elapsed;
         let mbps = g.bytes as f64 * 8.0 / 1_000_000.0 / elapsed;
-        let (p50, p95, valid) = if g.lat_us.is_empty() {
-            (0.0, 0.0, false)
-        } else {
-            g.lat_us.sort_unstable();
-            let n = g.lat_us.len();
-            let at = |p: f64| g.lat_us[((n as f64 * p) as usize).min(n - 1)] as f64 / 1000.0;
-            (at(0.50), at(0.95), true)
+        g.e2e_us.sort_unstable();
+        g.hostnet_us.sort_unstable();
+        g.host_us.sort_unstable();
+        g.net_us.sort_unstable();
+        g.decode_us.sort_unstable();
+        let snap = Snapshot {
+            fps,
+            mbps,
+            e2e_p50_ms: pctl_ms(&g.e2e_us, 0.50),
+            e2e_p95_ms: pctl_ms(&g.e2e_us, 0.95),
+            hostnet_p50_ms: pctl_ms(&g.hostnet_us, 0.50),
+            decode_p50_ms: pctl_ms(&g.decode_us, 0.50),
+            host_p50_ms: pctl_ms(&g.host_us, 0.50),
+            net_p50_ms: pctl_ms(&g.net_us, 0.50),
+            lat_valid: !g.e2e_us.is_empty(),
+            skew_corrected: g.skew_corrected,
         };
-        let skew = g.skew_corrected;
         g.window_start = Instant::now();
         g.frames = 0;
         g.bytes = 0;
-        g.lat_us.clear();
-        Snapshot {
-            fps,
-            mbps,
-            lat_p50_ms: p50,
-            lat_p95_ms: p95,
-            lat_valid: valid,
-            skew_corrected: skew,
-        }
+        g.e2e_us.clear();
+        g.hostnet_us.clear();
+        g.host_us.clear();
+        g.net_us.clear();
+        g.decode_us.clear();
+        snap
     }
 }

clients/android/native/src/wol.rs

@@ -0,0 +1,40 @@
+//! JNI seam for Wake-on-LAN: parse the stored MAC strings and hand them to the shared core sender
+//! (`punktfunk_core::wol`). Like [`crate::discovery`], this takes no session handle — a sleeping
+//! host has no ARP entry, so the broadcast the core sends is what wakes it, and Kotlin calls this
+//! just before connecting to an offline saved host.
+
+use jni::objects::{JObject, JString};
+use jni::JNIEnv;
+
+/// `NativeBridge.nativeWakeOnLan(macsCsv: String, lastIp: String): Boolean` — send a Wake-on-LAN
+/// magic packet. `macsCsv` is comma-separated MACs (`aa:bb:..,cc:dd:..`, learned from the host's
+/// mDNS `mac` TXT while it was online); `lastIp` is the host's last-known IPv4 (or empty).
+/// Returns true if at least one datagram went out.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeWakeOnLan<'local>(
+    mut env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    macs_csv: JString<'local>,
+    last_ip: JString<'local>,
+) -> jni::sys::jboolean {
+    let macs_csv: String = match env.get_string(&macs_csv) {
+        Ok(s) => s.into(),
+        Err(_) => return 0,
+    };
+    let last_ip: String = env
+        .get_string(&last_ip)
+        .map(Into::<String>::into)
+        .unwrap_or_default();
+    let macs: Vec<[u8; 6]> = macs_csv
+        .split(',')
+        .filter_map(|s| punktfunk_core::wol::parse_mac(s.trim()))
+        .collect();
+    if macs.is_empty() {
+        return 0;
+    }
+    let ip = last_ip.trim().parse::<std::net::Ipv4Addr>().ok();
+    match punktfunk_core::wol::send_magic_packet(&macs, ip) {
+        Ok(()) => 1,
+        Err(_) => 0,
+    }
+}

clients/apple/Config/Info.plist

@@ -16,5 +16,10 @@
 	     compliance question. -->
 	<key>ITSAppUsesNonExemptEncryption</key>
 	<false/>
+	<!-- Allow CADisplayLink above 60 Hz on ProMotion iPhones: without this key the system
+	     silently caps the link at 60 even when SessionPresenter asks for the stream's rate
+	     via preferredFrameRateRange, so a 120 fps stream would present at half rate. -->
+	<key>CADisableMinimumFrameDurationOnPhone</key>
+	<true/>
 </dict>
 </plist>

clients/apple/Config/Punktfunk.entitlements

@@ -11,5 +11,22 @@
 	<array>
 		<string>$(AppIdentifierPrefix)io.unom.punktfunk</string>
 	</array>
+	<!-- Wake-on-LAN needs to send a UDP broadcast magic packet (a sleeping host has no ARP
+	     entry, so unicast can't wake it). Since iOS 14 / tvOS 14 the OS blocks sending to
+	     broadcast/multicast addresses unless the app carries this managed entitlement — it must
+	     be requested from and approved by Apple for the App ID, then enabled in the provisioning
+	     profile. macOS is not gated by this (its App Sandbox network.client/server cover it).
+
+	     GATED pending Apple's approval of the request (form filed) — an unauthorized managed
+	     entitlement breaks iOS/tvOS signing, so it's commented out to keep those apps releasable.
+	     ON APPROVAL: (1) uncomment the two lines below, and (2) flip
+	     PunktfunkConnection.wakeOnLANAvailable (PunktfunkConnection.swift) to enable the iOS/tvOS
+	     wake path + UI. Until then iOS/tvOS Wake-on-LAN is a clean no-op — MACs are still learned
+	     from mDNS so it works immediately once ungated. macOS is unaffected (separate entitlements
+	     file, no multicast entitlement needed). -->
+	<!--
+	<key>com.apple.developer.networking.multicast</key>
+	<true/>
+	-->
 </dict>
 </plist>

clients/apple/Package.swift

@@ -16,6 +16,18 @@ let package = Package(
         .target(
             name: "PunktfunkKit",
             dependencies: ["PunktfunkCore"],
+            // OSS attribution shown by the app's Acknowledgements screen. Bundled here (not in the
+            // app target) so it rides along via Bundle.module in both `swift build` and the Xcode
+            // app, which links the PunktfunkKit product. Refresh with
+            // scripts/gen-third-party-notices.sh (it copies the generated file into Resources/).
+            resources: [
+                .copy("Resources/THIRD-PARTY-NOTICES.txt"),
+                .copy("Resources/LICENSE-MIT.txt"),
+                .copy("Resources/LICENSE-APACHE.txt"),
+                // Geist (SIL OFL 1.1) — the brand typeface, shared with punktfunk-website.
+                // Registered with Core Text at first use; see BrandFont.swift.
+                .copy("Resources/Fonts"),
+            ],
             linkerSettings: [
                 // Rust staticlib system deps.
                 .linkedFramework("Security"),

clients/apple/Punktfunk.xcodeproj/project.pbxproj

@@ -355,7 +355,7 @@
 			buildSettings = {
 				ASSETCATALOG_COMPILER_APPICON_NAME = punktfunk_Logo;
 				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
-				CODE_SIGN_ENTITLEMENTS = Config/Punktfunk-macOS.entitlements;
+				CODE_SIGN_ENTITLEMENTS = "Config/Punktfunk-macOS.entitlements";
 				CODE_SIGN_IDENTITY = "Apple Development";
 				CODE_SIGN_STYLE = Automatic;
 				COMBINE_HIDPI_IMAGES = YES;
@@ -364,7 +364,8 @@
 				ENABLE_HARDENED_RUNTIME = YES;
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_FILE = Config/Info.plist;
-				INFOPLIST_KEY_CFBundleDisplayName = "Punktfunkempfänger";
+				INFOPLIST_KEY_CFBundleDisplayName = Punktfunk;
+				INFOPLIST_KEY_GCSupportsControllerUserInteraction = YES;
 				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.utilities";
 				INFOPLIST_KEY_NSHumanReadableCopyright = "";
 				INFOPLIST_KEY_NSLocalNetworkUsageDescription = "Punktfunk connects directly to your punktfunk host on the local network to stream video, audio, and input.";
@@ -389,7 +390,7 @@
 			buildSettings = {
 				ASSETCATALOG_COMPILER_APPICON_NAME = punktfunk_Logo;
 				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
-				CODE_SIGN_ENTITLEMENTS = Config/Punktfunk-macOS.entitlements;
+				CODE_SIGN_ENTITLEMENTS = "Config/Punktfunk-macOS.entitlements";
 				CODE_SIGN_IDENTITY = "Apple Development";
 				CODE_SIGN_STYLE = Automatic;
 				COMBINE_HIDPI_IMAGES = YES;
@@ -398,7 +399,8 @@
 				ENABLE_HARDENED_RUNTIME = YES;
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_FILE = Config/Info.plist;
-				INFOPLIST_KEY_CFBundleDisplayName = "Punktfunkempfänger";
+				INFOPLIST_KEY_CFBundleDisplayName = Punktfunk;
+				INFOPLIST_KEY_GCSupportsControllerUserInteraction = YES;
 				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.utilities";
 				INFOPLIST_KEY_NSHumanReadableCopyright = "";
 				INFOPLIST_KEY_NSLocalNetworkUsageDescription = "Punktfunk connects directly to your punktfunk host on the local network to stream video, audio, and input.";
@@ -425,11 +427,11 @@
 				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
 				CODE_SIGN_ENTITLEMENTS = Config/Punktfunk.entitlements;
 				CODE_SIGN_STYLE = Automatic;
-				DEVELOPMENT_TEAM = F4H37KF6WC;
 				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = F4H37KF6WC;
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_FILE = Config/Info.plist;
-				INFOPLIST_KEY_CFBundleDisplayName = "Punktfunkempfänger";
+				INFOPLIST_KEY_CFBundleDisplayName = Punktfunk;
 				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.utilities";
 				INFOPLIST_KEY_NSLocalNetworkUsageDescription = "Punktfunk connects directly to your punktfunk host on the local network to stream video, audio, and input.";
 				INFOPLIST_KEY_NSMicrophoneUsageDescription = "Your microphone is streamed to the connected punktfunk host, where it appears as a virtual microphone.";
@@ -464,11 +466,11 @@
 				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
 				CODE_SIGN_ENTITLEMENTS = Config/Punktfunk.entitlements;
 				CODE_SIGN_STYLE = Automatic;
-				DEVELOPMENT_TEAM = F4H37KF6WC;
 				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = F4H37KF6WC;
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_FILE = Config/Info.plist;
-				INFOPLIST_KEY_CFBundleDisplayName = "Punktfunkempfänger";
+				INFOPLIST_KEY_CFBundleDisplayName = Punktfunk;
 				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.utilities";
 				INFOPLIST_KEY_NSLocalNetworkUsageDescription = "Punktfunk connects directly to your punktfunk host on the local network to stream video, audio, and input.";
 				INFOPLIST_KEY_NSMicrophoneUsageDescription = "Your microphone is streamed to the connected punktfunk host, where it appears as a virtual microphone.";
@@ -502,11 +504,11 @@
 				ASSETCATALOG_COMPILER_APPICON_NAME = "App Icon & Top Shelf Image";
 				CODE_SIGN_ENTITLEMENTS = Config/Punktfunk.entitlements;
 				CODE_SIGN_STYLE = Automatic;
-				DEVELOPMENT_TEAM = F4H37KF6WC;
 				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = F4H37KF6WC;
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_FILE = Config/Info.plist;
-				INFOPLIST_KEY_CFBundleDisplayName = "Punktfunkempfänger";
+				INFOPLIST_KEY_CFBundleDisplayName = Punktfunk;
 				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.utilities";
 				INFOPLIST_KEY_NSLocalNetworkUsageDescription = "Punktfunk connects directly to your punktfunk host on the local network to stream video, audio, and input.";
 				INFOPLIST_KEY_UIApplicationSceneManifest_Generation = YES;
@@ -532,11 +534,11 @@
 				ASSETCATALOG_COMPILER_APPICON_NAME = "App Icon & Top Shelf Image";
 				CODE_SIGN_ENTITLEMENTS = Config/Punktfunk.entitlements;
 				CODE_SIGN_STYLE = Automatic;
-				DEVELOPMENT_TEAM = F4H37KF6WC;
 				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = F4H37KF6WC;
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_FILE = Config/Info.plist;
-				INFOPLIST_KEY_CFBundleDisplayName = "Punktfunkempfänger";
+				INFOPLIST_KEY_CFBundleDisplayName = Punktfunk;
 				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.utilities";
 				INFOPLIST_KEY_NSLocalNetworkUsageDescription = "Punktfunk connects directly to your punktfunk host on the local network to stream video, audio, and input.";
 				INFOPLIST_KEY_UIApplicationSceneManifest_Generation = YES;

clients/apple/README.md

@@ -1,364 +1,126 @@
-# punktfunk Apple client (SwiftUI)
+# punktfunk — Apple client (macOS · iOS · iPadOS · tvOS)
 
-The native macOS/iOS client for **`punktfunk/1`** (the post-GameStream protocol). All
-networking/protocol work — QUIC control plane, UDP data plane, GF(2¹⁶) FEC, AES-GCM,
-input datagrams, Opus audio, cert pinning — lives in the shared Rust core (statically
-linked as `PunktfunkCore.xcframework`); this package is the Swift shell: decode
-(VideoToolbox), present (SwiftUI), input capture.
+The native **Apple** app for streaming a punktfunk host to your Mac, iPhone, iPad, or Apple TV. A
+SwiftUI app that finds hosts on your network, pairs with a PIN, and streams at your display's own
+resolution and refresh rate — with VideoToolbox hardware decode and full controller support.
 
-## Status — working client (macOS, with iOS / tvOS in the shared build)
+All the networking and protocol work — QUIC control plane, UDP data plane, GF(2¹⁶) FEC, AES-GCM,
+Opus audio, cert pinning — lives in the shared Rust **`punktfunk-core`** (statically linked as
+`PunktfunkCore.xcframework`). This package is the Swift shell: decode, present, input, and UI.
 
-A full streaming client: VideoToolbox HEVC decode, controllers incl. DualSense feedback, host
-discovery, PIN pairing, and a network speed test. The lower-latency **stage-2 presenter**
-(`VTDecompressionSession` → `CAMetalLayer`) is built and opt-in (Settings → Presenter); see below.
+## Features
 
-First light was achieved 2026-06-10 — validated live, Mac ↔ a Linux host over the LAN: gamescope
-virtual output → NVENC HEVC →
-`punktfunk/1` (GF(2¹⁶) FEC + AES-GCM over UDP, QUIC control) → VideoToolbox →
-`AVSampleBufferDisplayLayer` on glass at 1280×720@60, with mouse/keyboard flowing back as
-QUIC datagrams into the host's gamescope EIS injector (thousands of events injected during
-the session). Headless variant of the same proof: `RemoteFirstLightTests` decoded 60/60
-received AUs spanning 983 ms of host capture clock.
+- **Hardware decode** — VideoToolbox HEVC, with a low-latency **stage-2 presenter**
+  (`VTDecompressionSession` → `CAMetalLayer`, presented off a `CADisplayLink`, ~11 ms p50) as the
+  default and an `AVSampleBufferDisplayLayer` fallback.
+- **HDR & 4:4:4** — PQ passthrough with a correct reference-white anchor, mid-session SDR↔HDR
+  reconfiguration, and hardware-probed 4:4:4 support.
+- **Your display's native mode** — the host builds a virtual output at exactly your WxH@Hz;
+  mid-stream resize renegotiates without reconnecting.
+- **Audio both ways** — Opus playback (CoreAudio, no bundled libopus) with a jitter ring, plus mic
+  uplink; speaker/mic selectable in Settings.
+- **Full controller support** — one selected controller forwarded as pad 0, including **DualSense**
+  feedback (rumble → CoreHaptics, lightbar, player LEDs, adaptive triggers) and touchpad/motion. The
+  virtual pad type auto-resolves from your physical controller.
+- **Mouse & keyboard** — `GCMouse`/`GCKeyboard` capture with click-to-capture and a ⌘⎋ release, plus
+  iPad pointer lock and touch input.
+- **Find hosts automatically** — mDNS discovery (`NWBrowser` over `_punktfunk._udp`); first connect
+  does a one-time **SPAKE2 PIN pairing** (or TOFU on trusted LANs), then reconnects on a pinned,
+  Keychain-stored identity.
+- **Tune the stream** — a fps / Mb·s / **latency** HUD (skew-corrected across machines), a bitrate
+  control, a per-host **network speed test** with a recommended bitrate, and a host-compositor picker.
 
-The connector underneath (`punktfunk_core::client::NativeClient` over the C ABI) carries the
-full session: video AUs, **Opus audio** (`nextAudio()`), **rumble** (`nextRumble()`),
-**DualSense feedback** (`nextHidOutput()` — lightbar, player LEDs, adaptive-trigger
-effects), input incl. gamepads + DualSense touchpad/motion (`sendTouchpad`/`sendMotion`),
-and **cert pinning + TOFU** (`pinSHA256:`/`hostFingerprint`) — see
-`punktfunk1.rs::tests::c_abi_connection_roundtrip` (three sequential sessions: TOFU, pinned
-reconnect, wrong-pin rejection). The host (`punktfunk-host punktfunk1-host`) is a persistent listener:
-reconnect at will during development.
+Runs from one shared codebase across **macOS, iOS, iPadOS, and tvOS**.
 
-What's here, all compiled and tested on macOS (Xcode 26.5 / Swift 6.3):
+## Get it
 
-- **`PunktfunkKit`** (library)
-  - `PunktfunkConnection.swift` — wrapper over the C ABI. AUs/audio are copied into `Data`
-    (the C pointer is only valid until the next call of the same kind). `close()` is safe
-    from any thread: per-plane locks enforce the C contract ("never close with a
-    `next_au`/`next_audio` in flight") instead of leaving it to callers. Pinning + TOFU
-    via `pinSHA256:`/`hostFingerprint`.
-  - `AnnexB.swift` — in-band VPS/SPS/PPS → `CMVideoFormatDescription`; Annex-B → AVCC
-    `CMSampleBuffer` with `DisplayImmediately` set.
-  - `StreamView.swift` — SwiftUI `NSViewRepresentable` over `AVSampleBufferDisplayLayer`
-    (stage-1 presenter: the layer hardware-decodes compressed HEVC itself). One pump
-    thread per view, token-cancelled so reconnects can't double-pump.
-  - `InputCapture.swift` — `GCMouse` raw deltas + `GCKeyboard` HID→VK mapping (the host's
-    `vk_to_evdev` consumes Windows VKs), with fractional-delta accumulation so sub-pixel
-    motion isn't truncated away. Buttons use GameStream ids (1=left … 5=X2). Scroll is
-    WHEEL_DELTA(120)-scaled: macOS via the stream view's `scrollWheel` override, iPad via
-    GCMouse's scroll dpad when pointer-locked and a scroll-only `UIPanGestureRecognizer`
-    otherwise (trackpad gestures never reach GC's scroll dpad).
-  - `GamepadManager.swift` — app-lifetime controller discovery + selection (`.shared`):
-    watches `GCController` connect/disconnect, fingerprints each pad for the Settings UI
-    (name, capabilities, battery), and selects the ONE controller forwarded to the host
-    (user pin via "Use controller", else most recently connected extended gamepad).
-  - `GamepadCapture.swift` — the active controller → wire: snapshot-diff over
-    `GCExtendedGamepad` into incremental `gamepadButton`/`gamepadAxis` events (pad 0),
-    plus DualSense touchpad contacts and ~250 Hz motion samples on the rich-input plane
-    (the GC→DualSense unit conversions live in `GamepadWire`, one place). Held state is
-    released on the wire on controller switch / app deactivation / stop.
-  - `GamepadFeedback.swift` + `DualSenseTriggerEffect.swift` — host feedback → the real
-    controller: one drain thread for `nextRumble()` (→ `CHHapticEngine` per handle
-    locality) and `nextHidOutput()` (lightbar → `GCDeviceLight`, player LEDs →
-    `playerIndex`, adaptive-trigger effect blocks → a total, table-driven parser →
-    `GCDualSenseAdaptiveTrigger`, exact for the 10-zone positional modes).
-  - `HostDiscovery.swift` — LAN auto-discovery: an `NWBrowser` over `_punktfunk._udp`
-    (the host's `crate::discovery` mDNS advert), resolving each service to an IP:port via a
-    throwaway `NWConnection` and parsing the TXT (`fp` advisory cert fingerprint, `pair`,
-    stable `id`). iOS/tvOS need `NSBonjourServices` (`Config/Info.plist`) or the system
-    blocks the browse.
-- **`PunktfunkClient`** (the app): hosts grid (saved in UserDefaults) with an **On this
-  network** section listing mDNS-discovered hosts (tap to save + connect, or pair if the
-  host requires it), "+" toolbar sheet to add hosts manually, stream mode in Settings (⌘,),
-  two trust flows — the
-  trust-on-first-use fingerprint prompt over the live-but-blurred stream, and SPAKE2 PIN
-  pairing (`PairSheet`, from a host card's context menu or the trust prompt;
-  `ClientIdentityStore` keeps the client identity in the Keychain and presents it on
-  every connect) — then pinned reconnects, fps/Mb-s HUD + a **capture→client-receipt latency**
-  line (`LatencyMeter`, p50/p95): the AU `pts_ns` (host capture clock) to the instant the client
-  received it, **skew-corrected** across machines via `PunktfunkConnection.clockOffsetNs` (the
-  connect-time wall-clock handshake, `punktfunk_connection_clock_offset_ns`). It excludes the
-  layer's decode+present (stage-1 `AVSampleBufferDisplayLayer` has no per-frame present callback);
-  the opt-in **stage-2 presenter** (Settings → Presenter) adds a **capture→present**
-  (glass-to-glass) line via explicit decode + a Metal/display-link present. Settings also picks the HOST
-  compositor (KWin/wlroots/Mutter/gamescope, default automatic — the host honors it
-  only if that backend is available there) and has a **Controllers** section: every
-  detected controller (capability glyphs, battery, "In use" badge), which one to forward
-  ("Use controller", default automatic), and the virtual pad type the host creates
-  ("Controller type": Automatic / Xbox 360 / DualSense — Automatic matches the physical
-  pad; resolved at connect time, the host pad is fixed per session). Gamepad capture +
-  feedback run with streaming (`SessionModel` owns them, same trust gate as audio).
-  Settings also sets the **Bitrate** (Automatic toggle = host default; manual is a
-  log-scale slider, 2 Mbps – 3 Gbps, snapped to two significant figures — above 1 Gbps
-  an inline warning says to run a speed test first; tvOS uses a preset picker instead,
-  Slider doesn't exist there; negotiated via the Hello on every connect), and a host
-  card's context menu offers **"Test Network Speed…"** (`SpeedTestSheet`): connects, has
-  the host burst probe filler over the real data plane (up to the host's 3 Gbps probe
-  ceiling for 2 s, roadmap §9),
-  shows measured goodput · loss · a recommended bitrate (≈70% of measured), and applies
-  it in one tap. The streaming **statistics overlay** can be turned off and moved to any
-  corner (Settings → Display → Statistics, `DefaultsKey.hudEnabled`/`hudPlacement`), and
-  toggled live with **⌘⇧S** — a Scene-level **"Stream" menu** (`StreamCommands`) that also
-  carries **Disconnect ⌘D**, so disconnect survives the HUD being hidden (on iOS a small
-  exit chip appears instead; on tvOS the Siri-Remote Menu button still disconnects). The
-  macOS Settings window is a **tabbed preferences pane** (General / Display / Audio /
-  Controllers / Advanced) — the sections are shared with the iOS single-Form layout and the
-  tvOS pushed-picker layout, defined once each.
-- **Tests** (`swift test`): byte-level Annex-B units; a real-codec round trip
-  (VTCompressionSession-encoded HEVC rebuilt as the host's wire shape → `AnnexB` →
-  VTDecompressionSession → pixels); table-driven DualSense trigger-effect parsing
-  (`DualSenseTriggerEffectTests`) and the gamepad wire conversions
-  (`GamepadWireTests`); loopback integration against real local hosts
-  (`test-loopback.sh` — stream round trip incl. gamepad/touchpad/motion sends, a
-  host-scripted feedback burst asserted on the rumble + HID-output planes
-  (`PUNKTFUNK_TEST_FEEDBACK=1`), the bitrate-negotiation echo and a real 20 Mbps
-  bandwidth probe, plus the PIN pairing ceremony and the `--require-pairing` gate
-  against a second, armed host); the remote first-light test above.
+Install from the App Store / TestFlight, or build from source below. Per-device install steps and the
+pairing walkthrough:
+**[docs.punktfunk.unom.io/docs/install-client](https://docs.punktfunk.unom.io/docs/install-client)**.
 
 ## Build / run / test (on a Mac)
 
+Requires Xcode 26.5 / Swift 6.3. First build the Rust core into an xcframework, then build the app:
+
 ```sh
 rustup target add aarch64-apple-darwin x86_64-apple-darwin
-bash scripts/build-xcframework.sh        # → clients/apple/PunktfunkCore.xcframework
-# + BUILD_IOS=1 for the iOS slices (rustup target add aarch64-apple-ios{,-sim} x86_64-apple-ios)
-# + BUILD_TVOS=1 for tvOS — TIER-3 Rust targets, built from source:
-#   rustup toolchain install nightly && rustup component add rust-src --toolchain nightly
+bash scripts/build-xcframework.sh            # → clients/apple/PunktfunkCore.xcframework
+#   BUILD_IOS=1  also builds the iOS slices  (add the ios rustup targets)
+#   BUILD_TVOS=1 also builds tvOS            (tier-3 targets, built from source — see below)
+
 cd clients/apple
-swift build && swift test                # loopback/remote tests self-skip without a host
-swift run PunktfunkClient                # the unbundled dev shell (CLI)
-open Punktfunk.xcodeproj                 # the real app: ⌘R builds + runs Punktfunk.app
+open Punktfunk.xcodeproj                      # the real app: ⌘R builds + runs Punktfunk.app
+swift run PunktfunkClient                     # or the unbundled dev shell (CLI)
+swift build && swift test                     # unit + loopback/remote tests (self-skip w/o a host)
+```
 
-bash test-loopback.sh                    # full loopback proof: builds punktfunk-host
-                                         # (synthetic source — runs on macOS), streams
-                                         # byte-verified frames into the Swift client
+tvOS slices are tier-3 Rust targets, built from source:
+`rustup toolchain install nightly && rustup component add rust-src --toolchain nightly`.
 
-# against the real host (Linux box, see CLAUDE.md "Running on this box") — punktfunk1-host is a
-# persistent listener, reconnect at will:
-#   PUNKTFUNK_COMPOSITOR=gamescope PUNKTFUNK_GAMESCOPE_APP=vkcube PUNKTFUNK_ZEROCOPY=1 \
-#   cargo run -rp punktfunk-host -- punktfunk1-host --source virtual --seconds 60
-PUNKTFUNK_REMOTE_HOST=<box-ip> swift test --filter RemoteFirstLightTests   # headless
-#   (+ PUNKTFUNK_REMOTE_PORT / PUNKTFUNK_REMOTE_COMPOSITOR=gamescope|kwin|… /
-#    PUNKTFUNK_REMOTE_PIN=<arming-pin> for the remote pairing test)
+### Test against a host
+
+```sh
+# full loopback proof — builds punktfunk-host (synthetic source, runs on macOS) and streams
+# byte-verified frames into the Swift client, incl. the PIN pairing ceremony:
+bash test-loopback.sh
+
+# against a real Linux host on the LAN (see the repo README "Running on this box"):
+PUNKTFUNK_REMOTE_HOST=<box-ip> swift test --filter RemoteFirstLightTests            # headless
 PUNKTFUNK_AUTOCONNECT=<box-ip> PUNKTFUNK_MODE=1280x720x60 swift run PunktfunkClient # on glass
 ```
 
-## Xcode project (`Punktfunk.xcodeproj`)
+## Project layout
 
-The app target **Punktfunk** wraps the same sources as the `swift run` shell
-(`Sources/PunktfunkClient`, a synchronized folder — no duplication) plus `App/` (asset
-catalog) and links `PunktfunkKit` from the local package. Generated Info.plist, ad-hoc
-signing, bundle id `io.unom.punktfunk`. Notes:
+- **`PunktfunkKit`** (library) — the reusable pieces:
+  - `PunktfunkConnection` — the wrapper over the C ABI (thread-safe `close()`, per-plane locks,
+    pinning + TOFU).
+  - `AnnexB` / `StreamView` / `VideoDecoder` / `MetalVideoPresenter` — format handling, the stage-1
+    (`AVSampleBufferDisplayLayer`) and stage-2 (`VTDecompressionSession` → `CAMetalLayer`) presenters.
+  - `InputCapture` — `GCMouse`/`GCKeyboard` → host VK/mouse, with fractional-delta accumulation.
+  - `GamepadManager` / `GamepadCapture` / `GamepadFeedback` / `DualSenseTriggerEffect` — controller
+    discovery + selection, capture (buttons/axes/touchpad/motion), and host-feedback rendering.
+  - `HostDiscovery` — `NWBrowser` over `_punktfunk._udp`.
+- **`PunktfunkClient`** (the app) — hosts grid with an *On this network* section, add-host sheet,
+  the two trust flows (TOFU prompt + SPAKE2 `PairSheet`), the stream view with the HUD, a
+  tabbed Settings pane (General / Display / Audio / Controllers / Advanced), and the network speed
+  test. A Scene-level **Stream** menu carries Disconnect (⌘D) and the HUD toggle (⌘⇧S).
+  On iOS/iPadOS **and macOS** a connected controller swaps the whole home for the **gamepad UI**
+  (`Home/Gamepad*`, `Settings/GamepadSettingsView`): a console-style host carousel (A connect · Y
+  library · X settings), a controller-navigable settings screen, an add-host flow with an
+  on-screen controller keyboard (no touch required anywhere), and the coverflow library browser —
+  all driven by the shared `GamepadMenuInput` poller + `GamepadCarousel`/`GamepadMenuList` focus
+  machinery, with dual-channel haptics (device Taptic + controller `MenuHaptics`), over an
+  animated "aurora" backdrop (`GamepadScreenBackground` — TimelineView-driven drifting color
+  blobs; deliberately pure SwiftUI, since a .metal library only reliably bundles in one of the
+  two build systems these sources compile under). macOS presents the settings/add-host screens as
+  sheets (no `fullScreenCover` there); `PUNKTFUNK_FORCE_GAMEPAD_UI=1` forces the mode without a
+  physical pad (dev/screenshots).
+- **Tests** (`swift test`) — Annex-B units, a real-codec VideoToolbox round trip, DualSense
+  trigger-effect and gamepad-wire conversions, loopback integration against real local hosts, and the
+  remote first-light test.
 
-- **Entitlements (sandbox)**: the macOS target uses
-  `Config/Punktfunk-macOS.entitlements`; iOS/tvOS use the shared
-  `Config/Punktfunk.entitlements`. The macOS app is **App-Sandboxed** (mandatory for the Mac
-  App Store/TestFlight, and used for the Developer ID DMG too so the local build matches what
-  ships): `com.apple.security.app-sandbox`, `network.client` + **`network.server`** (the
-  sandbox gates `bind()`; quinn + the raw-UDP plane both bind, so receive breaks without it),
-  `device.audio-input` (mic), `device.bluetooth` + `device.usb` (GameController over BT/USB),
-  and the existing `keychain-access-groups`. `app-sandbox` is macOS-only — keep it OUT of the
-  shared iOS/tvOS file (it fails upload validation there). Verify a build is sandboxed with
-  `codesign -d --entitlements :- <built .app>`. Heads-up: `device.usb` draws some App Review
-  scrutiny — justify it in the review notes ("reads input from USB game controllers").
-- **App icon**: `App/Assets.xcassets` ships an empty `AppIcon` slot. For an Icon Composer
-  `.icon`: add the file to the project (target Punktfunk), set it as the App Icon in the
-  target's General tab, and delete the placeholder `AppIcon.appiconset`. Heads-up: CLI
-  `actool` (Xcode 26.5) crashed compiling `punktfunk_Logo.icon` — if Xcode does the same,
-  suspect the icon bundle (it has a duplicate-named layer, "…Layer-3 2.svg"), not the
-  project.
-- **Tests from Xcode**: the package tests run with `swift test`; to get them on ⌘U, add
-  `PunktfunkKitTests` once via Edit Scheme → Test → + (Xcode persists it into the shared
-  scheme — a hand-written package-test reference doesn't resolve headlessly).
-- `xcodebuild -project Punktfunk.xcodeproj -scheme Punktfunk build` works headlessly;
-  same for `-scheme Punktfunk-iOS -destination 'generic/platform=iOS Simulator'` (run it
-  in a simulator via `xcrun simctl install/launch` — `SIMCTL_CHILD_PUNKTFUNK_AUTOCONNECT=…`
-  passes the dev autoconnect env through).
+## Notes for contributors
 
-## App Store screenshots
+- **Xcode project** (`Punktfunk.xcodeproj`) wraps the same sources as the `swift run` shell (a
+  synchronized folder — no duplication). The macOS target is **App-Sandboxed** (needs
+  `network.server` — the raw-UDP plane and quinn both `bind()`); iOS/tvOS use the shared
+  entitlements file (keep `app-sandbox` **out** of it). Verify with
+  `codesign -d --entitlements :- <built .app>`.
+- **Decode flow**: the host opens every stream with an IDR carrying VPS/SPS/PPS in-band, and recovery
+  keyframes re-send them — refresh the format description on every IDR; there is no out-of-band
+  extradata, ever.
+- **ABI threading**: one video pump thread per connection, one optional audio drain thread, and one
+  optional feedback drain thread (rumble + HID-output). `send()` is enqueue-only and safe alongside
+  all of them. The wrapper's per-plane locks make `close()` safe from anywhere.
+- **DualSense motion scale** (`GamepadWire`) is derived from hid-playstation's math, not yet
+  live-verified — if gyro/accel feel wrong in a game, correct sign/scale there and `evtest` the
+  host's virtual pad.
+- **App Store screenshots** are automated — `tools/screenshots.sh all` renders the real UI at the
+  required pixel sizes via a DEBUG-only shot mode; the `apple` CI workflow captures the iOS sizes on
+  every main push. See the script header for details.
+- Deeper design notes live in [`design/apple-stage2-presenter.md`](../../design/apple-stage2-presenter.md).
 
-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`**.
+## Related
 
-```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
-   C17-compatible header spells `PunktfunkStatus`/`PunktfunkInputKind` as integer typedefs while
-   the enum *constants* import into Swift as a distinct same-named type — bridge with
-   `.rawValue` (see the top of `PunktfunkConnection.swift`). Don't fight the generated header.
-2. **ABI contract**: one video pump thread per connection, plus optionally one *separate*
-   audio drain thread for `nextAudio()` and one feedback drain thread for
-   `nextRumble()`/`nextHidOutput()` (the core keeps per-plane borrow slots, so the planes
-   never alias; rumble + HID-output are two planes drained sequentially by the one
-   feedback thread); `send()` is enqueue-only and safe alongside all of them. The
-   wrapper's per-plane locks make `close()` safe from anywhere (it waits out in-flight
-   polls, ≤ their timeouts).
-3. **Decode flow**: the host opens every stream with an IDR carrying VPS/SPS/PPS in-band
-   and recovery keyframes re-send them — "refresh the format description on every IDR"
-   (what `StreamView` does) is sufficient; there is no out-of-band extradata, ever.
-4. **Stage 2 — built, opt-in (`punktfunk.presenter == "stage2"`, default stage 1).** Explicit
-   `VTDecompressionSession` decode (`VideoDecoder`) → a `CAMetalLayer` + display-link present
-   (`MetalVideoPresenter`/`Stage2Pipeline`), hosted as a sublayer by the same `StreamView`s with
-   input capture + HUD unchanged. It adds a **capture→present** (glass-to-glass, modulo the host
-   render→capture term) HUD line, skew-corrected via `PunktfunkConnection.clockOffsetNs`. The
-   decode half is unit-tested (`testVideoDecoderAsyncCallbackDeliversPixels`); the Metal present
-   is display-bound — **validate live** (flip the Settings "Presenter" picker, watch the HUD
-   number and that the image looks right) before making it the default. 10-bit/HDR + a smoothing
-   pacer are later. Plan: `docs-site/content/docs/apple-stage2-presenter.md`.
-5. **Audio — wired, both directions.** Playback: `SessionAudio` drains `nextAudio()`
-   on its own thread, decodes through CoreAudio's built-in Opus codec (`OpusCodec.swift`
-   — kAudioFormatOpus, no bundled libopus; round-trip unit-tested) into a priming
-   jitter ring feeding an `AVAudioSourceNode`. Mic: a second engine taps the input
-   device, resamples to 48 kHz stereo, Opus-encodes 20 ms chunks and `sendMic()`s them
-   (the host's virtual PipeWire source accepts any frame size ≤ 120 ms). Speaker/mic
-   are chosen in Settings (`AudioDevices.swift` — persisted by UID; "System default"
-   leaves the engines unpinned so they follow macOS device changes), mic on/off toggle
-   included; the app asks for mic permission on first use
-   (NSMicrophoneUsageDescription is in the Xcode target). A/V sync and packet-loss
-   concealment beyond silence-fill are still open (AudioPacket.seq/ptsNs carry what's
-   needed). Decode with libopus or `AVAudioConverter`/`kAudioFormatOpus` into an
-   `AVAudioEngine` source node; conceal gaps (drop/dup) rather than blocking — the Rust
-   side buffers 320 ms and drops the newest packet when the puller lags. Wall-clock
-   `ptsNs` shares the host clock with video AUs for A/V sync. Wiring this into
-   `PunktfunkClient` is the next app-side task.
-6. **Gamepads — wired end to end.** Exactly ONE controller (the `GamepadManager`
-   selection) forwards as pad 0; the host accumulates the incremental events into a
-   virtual pad whose TYPE the client negotiates in the Hello (`gamepad:` connect
-   parameter, echoed resolved in `resolvedGamepad` — Automatic resolves from the physical
-   pad at connect time; host precedence: explicit client choice > host `PUNKTFUNK_GAMEPAD`
-   env > Xbox 360). A DualSense session carries the full feel: adaptive-trigger blocks
-   (`DualSenseTriggerEffect.parse` — mode bytes per the community convention
-   (Nielk1/ds5w/inputtino), total, unknown → `.off`), lightbar, player LEDs, touchpad,
-   motion. **Motion scale constants** (`GamepadWire.gyroLSBPerRadS` = 20 LSB per deg/s,
-   `accelLSBPerG` = 10000) are derived from hid-playstation's math over the host's fixed
-   calibration blob, not yet live-verified — if gyro/accel feel wrong in a real game,
-   correct sign/scale in `GamepadCapture.forwardMotion`/`GamepadWire` and `evtest` the
-   host's virtual pad. Twin identical controllers share a fingerprint base, so a manual
-   pin can swap between them across reconnects (documented in the Settings footer).
-7. **Trust — the full ceremony exists now (SPAKE2).** `generateIdentity()` once (persist
-   both PEMs in the Keychain), then `pair(host:identity:pin:name:)` with the 4-digit PIN
-   the host prints when it ARMS pairing (`--allow-pairing`/`--require-pairing`; one PIN
-   per arming window, surfaced in the host's web console — port 3000 → Pairing — and
-   printed at startup; the user reads it before pairing). Returns the
-   host's VERIFIED fingerprint; persist it and pass `pinSHA256:` + `identity:` to every
-   connect. Pairing is a real PAKE: a wrong PIN gets ONE online guess (no offline
-   dictionary attack), throwing `.wrongPIN`; a wrong-size pin throws `.invalidPin`. `PunktfunkClient` implements both flows:
-   the TOFU fingerprint sheet keeps working against hosts not running
-   `--require-pairing`, and the PIN ceremony is wired in — `ClientIdentityStore`
-   (Keychain) on every connect, `PairSheet` from a host card's context menu or the trust
-   prompt's "Pair with PIN instead…" (the host's accept loop is sequential, so that path
-   drops the live session before pairing). With `--require-pairing` the host now
-   authorizes clients too (the "other direction" is no longer open, opt-in per host);
-   the whole gate is regression-tested in `testPairingCeremonyAndRequirePairingGate`.
-7b. **Resize without reconnect**: `requestMode(width:height:refreshHz:)` mid-stream —
-   the host rebuilds at the new mode in ~90 ms; the first new-mode AU is an IDR with
-   fresh parameter sets (the refresh-on-IDR decode flow handles it untouched) and
-   `currentMode()` reflects the switch. Wire it to window-resize events.
-8. **Input capture** (stage 1): capture is a deliberate, reversible STATE owned by
-   `StreamLayerView`, Moonlight-style. Engaged when the stream starts / trust is
-   confirmed and when the user clicks into the video (that click is suppressed toward
-   the host); released by ⌘⎋ (toggles) or focus loss; NEVER engaged by mere app
-   activation — activating clicks may be title-bar drags or resizes, which used to get
-   their cursor warped away mid-drag. While captured: the local cursor is hidden +
-   frozen mid-view (the host renders its own), all input is forwarded, and the view
-   consumes key events as first responder so unhandled keyDowns don't beep — ⌘-combos
-   still work locally (⌘D disconnect, ⌘Q) *and* reach the host via GC. While released:
-   nothing is forwarded (`InputCapture.forwarding` gates the GC handlers; held
-   keys/buttons are flushed host-side on release so nothing sticks down), the cursor is
-   free, and the HUD shows "Click the stream to capture input". GC handlers only fire
-   while the app has focus, and focus loss also auto-releases everything held. One live capture per process (the GC
-   mouse/keyboard singletons have a single handler slot — ownership is tracked so a stale
-   capture's stop() can't clobber a newer one).
-9. **iOS/iPadOS — ported and first-lit** (iPad simulator ↔ the real host, 60 fps).
-   `BUILD_IOS=1 bash scripts/build-xcframework.sh` builds device + universal-simulator
-   slices; the Xcode project has a second target, **Punktfunk-iOS**, sharing the same
-   synchronized sources. The iOS `StreamView` (StreamViewIOS.swift — same name/signature
-   as the macOS one, so the SwiftUI shell is identical) hosts the shared `StreamPump` in
-   a view controller for `prefersPointerLocked`: with a hardware mouse/trackpad that is
-   the iPadOS cursor capture (system honors it fullscreen-and-frontmost; in Stage
-   Manager it degrades to absolute-mouse forwarding). Input is routed by kind: DIRECT
-   fingers / Pencil are touches (each gets a wire touch id, coordinates mapped through the
-   aspect-fit letterbox into host-mode pixels — surface == host mode, so the host rescale is
-   the identity), while a mouse/trackpad is a MOUSE — pointer-LOCKED it is GCMouse relative
-   deltas; unlocked it is absolute moves + buttons + scroll over the UIKit pointer path
-   (hover + `.indirectPointer` touches), the local cursor staying visible so you can aim. An
-   indirect pointer is never sent as a touch. Touch is gated on trust (not forwarded under
-   the TOFU prompt), and returning to the foreground restores the capture you had on leaving.
-   `InputCapture` is cross-platform (GC works the same on iPadOS; ⌘⎋ is detected from
-   the HID stream there); audio routes via `AVAudioSession` (the Settings device
-   pickers are macOS-only). For the iPad-with-external-display setup: the target
-   enables multiple scenes + indirect input events — on Stage Manager iPads, drag the
-   punktfunk window onto the external screen and the stream runs there with full
-   keyboard/mouse/touch. While streaming the session is immersive (edge-to-edge,
-   status bar + home indicator hidden) and the iPadOS cursor is hidden over the video only
-   while the scene is actually pointer-LOCKED (`UIPointerInteraction` `.hidden()`); when the
-   lock isn't held it stays visible and the mouse forwards as an absolute cursor instead; on
-   iOS first run the stream mode defaults to the device's native screen so the video
-   fills the display. **tvOS** runs the same app (target **Punktfunk-tvOS**, first-lit
-   in the Apple TV simulator at 720p60): playback-only audio (no mic on tvOS),
-   focus-driven UI (`.card` host tiles), no kb/mouse capture yet — input lands with
-   gamepad support, the natural tvOS input anyway. While streaming there is NO focusable
-   control (a focusable Disconnect button would let the focus engine eat the controller's A
-   before the host sees it); the Siri Remote's **Menu** button disconnects (`.onExitCommand`).
-   Core slices are tier-3 Rust targets (see Build above). Known gaps: true pointer LOCK (`prefersPointerLocked`) isn't
-   consulted through UIHostingController, so the hidden cursor can still drift onto a
-   second screen (fixing it means putting the controller into the UIKit presentation
-   chain); and
-   AVAudioSession interruptions (calls, Siri) don't auto-restart the audio engines yet
-   (reconnect recovers).
-
-## Known limitations of the current host (relevant to client UX)
-
-- One session **at a time** (the listener is persistent, but a second concurrent client
-  waits in the accept queue until the current session ends — the virtual output and
-  encoder are single-tenant).
-- 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`).
+- **[Documentation](https://docs.punktfunk.unom.io)** — quick start, pairing, troubleshooting
+- **[Project README](../../README.md)** — the host, the other clients, and how it all fits together

clients/apple/Sources/PunktfunkClient/ContentView.swift

@@ -4,10 +4,12 @@
 // (HomeView/HostCards), the trust prompt (TrustCardView), and the HUD (StreamHUDView) live in
 // their own files.
 //
-// Two ways to establish trust on first contact: the TOFU prompt (host fingerprint over the
-// live-but-blurred stream, compared with the host's log) or the PIN pairing ceremony — pairing
-// verifies both sides at once and is the only way into hosts running --require-pairing. Once
-// pinned, reconnects are silent and a changed host identity refuses to connect.
+// Ways to establish trust on first contact: the TOFU prompt (host fingerprint over the
+// live-but-blurred stream, compared with the host's log; only for a host advertising pair=optional),
+// the PIN pairing ceremony (verifies both sides at once), or — for a host that requires pairing —
+// delegated approval ("Request Access": a plain identified connect the host parks until the operator
+// approves this device in its console, no PIN). Once pinned, reconnects are silent and a changed
+// host identity refuses to connect.
 
 #if os(macOS)
 import AppKit
@@ -25,16 +27,44 @@ struct ContentView: View {
     @AppStorage(DefaultsKey.compositor) private var compositor = 0
     @AppStorage(DefaultsKey.gamepadType) private var gamepadType = 0
     @AppStorage(DefaultsKey.bitrateKbps) private var bitrateKbps = 0
+    @AppStorage(DefaultsKey.audioChannels) private var audioChannels = 2
+    @AppStorage(DefaultsKey.codec) private var codec = "auto"
+    @AppStorage(DefaultsKey.hdrEnabled) private var hdrEnabled = true
     @AppStorage(DefaultsKey.fullscreenWhileStreaming) private var fullscreenWhileStreaming = true
     @AppStorage(DefaultsKey.hudEnabled) private var hudEnabled = true
     @AppStorage(DefaultsKey.hudPlacement) private var hudPlacement = HUDPlacement.topTrailing.rawValue
+    /// The `codec` setting as a `PUNKTFUNK_CODEC_*` soft-preference byte (`0` = auto).
+    private var preferredCodecByte: UInt8 {
+        switch codec {
+        case "h264": return PunktfunkConnection.codecH264
+        case "hevc": return PunktfunkConnection.codecHEVC
+        case "av1": return PunktfunkConnection.codecAV1
+        default: return 0
+        }
+    }
     @State private var showAddHost = false
     @State private var pairingTarget: StoredHost?
+    /// A fresh `pair=required`/unknown host the user tapped: drives the choice between no-PIN
+    /// delegated approval ("Request Access") and the SPAKE2 PIN ceremony (rule 3b).
+    @State private var approvalChoice: ApprovalRequest?
+    /// A delegated-approval connect is in flight (host parks it until the operator approves):
+    /// drives the cancelable "Waiting for approval" prompt and the pin-as-paired on success.
+    @State private var awaitingApproval: ApprovalRequest?
     @State private var speedTestTarget: StoredHost?
     @State private var libraryTarget: StoredHost?
     #if !os(macOS)
     @State private var showSettings = false
     #endif
+    #if os(iOS) || os(macOS)
+    // A connected controller (+ the Settings toggle) swaps the whole home screen for
+    // GamepadHomeView instead of retrofitting HomeView's touch/desktop UI — see `home` below.
+    @ObservedObject private var gamepadManager = GamepadManager.shared
+    @AppStorage(DefaultsKey.gamepadUIEnabled) private var gamepadUIEnabled = true
+    private var gamepadUIActive: Bool {
+        GamepadUIEnvironment.isActive(
+            gamepadConnected: gamepadManager.active != nil, enabledSetting: gamepadUIEnabled)
+    }
+    #endif
 
     var body: some View {
         Group {
@@ -54,10 +84,31 @@ struct ContentView: View {
             autoConnectIfAsked()
         }
         .onChange(of: model.phase) { _, phase in
-            // A session actually started — remember it on the card ("Connected … ago"
-            // plus the accent ring on the most recent host).
-            if case .streaming = phase, let host = model.activeHost {
-                store.markConnected(host.id)
+            switch phase {
+            case .streaming:
+                // A session actually started — remember it on the card ("Connected … ago"
+                // plus the accent ring on the most recent host).
+                guard let host = model.activeHost else { break }
+                // Delegated approval just succeeded: the operator let this device in, so pin the
+                // host's observed fingerprint and remember it as paired — future connects are then
+                // silent (rule 1), exactly like after a PIN/TOFU success. Dismisses the wait prompt.
+                let approvedFingerprint = awaitingApproval?.host.id == host.id
+                    ? model.connection?.hostFingerprint : nil
+                if awaitingApproval?.host.id == host.id { awaitingApproval = nil }
+                // Persist on the next runloop tick: HostStore is an ObservableObject, and mutating
+                // its @Published from inside .onChange (a view-update callback) trips SwiftUI's
+                // "Publishing changes from within view updates". A one-tick delay is imperceptible.
+                let store = store
+                DispatchQueue.main.async {
+                    store.markConnected(host.id)
+                    if let approvedFingerprint { store.pin(host.id, fingerprint: approvedFingerprint) }
+                }
+            case .idle:
+                // The delegated-approval connect failed, timed out, or was cancelled — drop the
+                // wait prompt (SessionModel surfaces any error via `errorMessage`).
+                if awaitingApproval != nil { awaitingApproval = nil }
+            default:
+                break
             }
         }
         .onDisappear { model.disconnect() } // window closed mid-session (Cmd+N spawns more)
@@ -83,22 +134,117 @@ struct ContentView: View {
         .sheet(item: $speedTestTarget) { host in
             SpeedTestSheet(host: host)
         }
+        // The library is a full-screen presentation, not a sheet: on iPad a sheet is a centered page
+        // card, but the gamepad coverflow is meant to be an immersive, full-bleed screen (and the
+        // launcher behind it stops consuming the controller — see GamepadHomeView's `isActive`).
+        // macOS has no `fullScreenCover`, so it keeps the sheet there — with an explicit size: a
+        // macOS sheet takes its content's IDEAL size, and both library layouts are geometry-driven
+        // (the coverflow is a GeometryReader, ideal ≈ zero), so without a frame it collapses to a
+        // tiny panel.
+        #if os(macOS)
         .sheet(item: $libraryTarget) { host in
             NavigationStack {
                 LibraryView(store: store, host: host, onLaunch: { launchTitle(host, $0) })
             }
+            .frame(minWidth: 940, minHeight: 620)
+        }
+        #else
+        .fullScreenCover(item: $libraryTarget) { host in
+            NavigationStack {
+                LibraryView(store: store, host: host, onLaunch: { launchTitle(host, $0) })
+            }
         }
         #endif
+        #endif
+        // Fresh pair=required / unknown host: offer the two ways in. An action sheet (not an
+        // alert) so it never collides with the wait alert below. "Request Access" is the no-PIN
+        // delegated-approval path; "Pair with PIN…" runs the SPAKE2 ceremony. The follow-on
+        // presentation is deferred a tick so this dialog is fully dismissed first.
+        .confirmationDialog(
+            "Pairing required",
+            isPresented: Binding(
+                get: { approvalChoice != nil },
+                set: { if !$0 { approvalChoice = nil } }),
+            titleVisibility: .visible,
+            presenting: approvalChoice
+        ) { req in
+            Button("Request Access") {
+                DispatchQueue.main.async { requestAccess(req) }
+            }
+            Button("Pair with PIN…") {
+                DispatchQueue.main.async { pairingTarget = req.host }
+            }
+            Button("Cancel", role: .cancel) {}
+        } message: { req in
+            Text("\(req.host.displayName) requires pairing. Request access and approve this "
+                + "device in the host's web console (port 3000 → Pairing) — no PIN needed. Or "
+                + "pair with the 4-digit PIN it can display.")
+        }
+        // One "Connection failed" surface for every home screen (touch grid, gamepad launcher) and
+        // platform — SessionModel funnels all connect/session errors into `errorMessage`.
+        .alert(
+            "Connection failed",
+            isPresented: Binding(
+                get: { model.errorMessage != nil },
+                set: { if !$0 { model.errorMessage = nil } })
+        ) {
+            Button("OK", role: .cancel) {}
+        } message: {
+            Text(model.errorMessage ?? "")
+        }
+        // The delegated-approval wait: the host holds the connection open until the operator
+        // approves it. Cancel returns the UI at once; the in-flight connect is left to time out
+        // and its late result is discarded by SessionModel's connect guard (disconnect resets the
+        // phase/host it checks).
+        .alert(
+            "Waiting for approval",
+            isPresented: Binding(
+                get: { awaitingApproval != nil },
+                set: { if !$0 { awaitingApproval = nil } }),
+            presenting: awaitingApproval
+        ) { _ in
+            Button("Cancel", role: .cancel) { model.disconnect() }
+        } message: { req in
+            Text("Approve \u{201C}\(localDeviceName)\u{201D} in \(req.host.displayName)'s web "
+                + "console (port 3000 → Pairing). This device connects automatically once you "
+                + "approve it — no need to reconnect.")
+        }
     }
 
     private var home: some View {
         #if os(macOS)
-        HomeView(
-            store: store, model: model, discovery: discovery,
-            showAddHost: $showAddHost, pairingTarget: $pairingTarget,
-            speedTestTarget: $speedTestTarget, libraryTarget: $libraryTarget,
-            connect: { connect($0) }, connectDiscovered: connectDiscovered,
-            onPaired: handlePaired, onLaunchTitle: launchTitle)
+        Group {
+            if gamepadUIActive {
+                GamepadHomeView(
+                    store: store, model: model, discovery: discovery,
+                    libraryTarget: $libraryTarget,
+                    connect: { connect($0) }, connectDiscovered: connectDiscovered)
+            } else {
+                HomeView(
+                    store: store, model: model, discovery: discovery,
+                    showAddHost: $showAddHost, pairingTarget: $pairingTarget,
+                    speedTestTarget: $speedTestTarget, libraryTarget: $libraryTarget,
+                    connect: { connect($0) }, connectDiscovered: connectDiscovered,
+                    onPaired: handlePaired, onLaunchTitle: launchTitle)
+            }
+        }
+        #elseif os(iOS)
+        Group {
+            if gamepadUIActive {
+                GamepadHomeView(
+                    store: store, model: model, discovery: discovery,
+                    libraryTarget: $libraryTarget,
+                    connect: { connect($0) }, connectDiscovered: connectDiscovered)
+            } else {
+                HomeView(
+                    store: store, model: model, discovery: discovery,
+                    showAddHost: $showAddHost, pairingTarget: $pairingTarget,
+                    speedTestTarget: $speedTestTarget, libraryTarget: $libraryTarget,
+                    showSettings: $showSettings,
+                    connect: { connect($0) }, connectDiscovered: connectDiscovered,
+                    onPaired: handlePaired, onLaunchTitle: launchTitle)
+            }
+        }
         #else
         HomeView(
             store: store, model: model, discovery: discovery,
@@ -180,14 +326,21 @@ struct ContentView: View {
                     onCaptureChange: { [weak model] captured in
                         model?.mouseCaptured = captured
                     },
-                    onFrame: { [meter = model.meter, latency = model.latency, offset = conn.clockOffsetNs] au in
+                    onFrame: { [meter = model.meter, latency = model.latency,
+                                split = model.latencySplit, offset = conn.clockOffsetNs] au in
                         meter.note(byteCount: au.data.count)
                         latency.record(ptsNs: au.ptsNs, offsetNs: offset)
+                        // The same receipt, keyed by pts, awaiting its 0xCF host timing (the
+                        // host/network split — drained by the 1 s stats tick).
+                        split.recordReceipt(
+                            ptsNs: au.ptsNs, receivedNs: au.receivedNs, offsetNs: offset)
                     },
                     onSessionEnd: { [weak model] in
                         Task { @MainActor in model?.sessionEnded() }
                     },
-                    presentMeter: model.presentLatency
+                    endToEndMeter: model.endToEnd,
+                    decodeMeter: model.decodeStage,
+                    displayMeter: model.displayStage
                 )
                 .overlay(alignment: placement.alignment) {
                     if captureEnabled && hudEnabled {
@@ -229,19 +382,33 @@ struct ContentView: View {
         // A pinned host connects on its stored fingerprint; an unpinned host may only TOFU when
         // the host's LIVE advert says `pair=optional` (rule 3a). When the caller doesn't already
         // know the policy (a saved-card tap / manual entry), resolve it from the current mDNS set:
-        // an unpinned host with no matching `pair=optional` advert routes to PIN pairing instead
-        // of silently entering the trust prompt (rules 3b + 4). A pinned host ignores all of this.
+        // an unpinned host with no matching `pair=optional` advert routes to the approval choice
+        // (request access / pair with PIN) instead of silently entering the trust prompt (rules
+        // 3b + 4). A pinned host ignores all of this.
         if host.pinnedSHA256 == nil {
             let tofuOK = allowTofu ?? discovery.hosts.contains {
                 host.matches($0) && $0.allowsTofu
             }
             if !tofuOK {
-                pairingTarget = host
+                // pair=required / unknown policy / manual entry (rule 3b): never a silent
+                // connect — offer no-PIN delegated approval or the PIN ceremony.
+                approvalChoice = ApprovalRequest(
+                    host: host, advertisedFingerprint: advertisedFingerprint(for: host))
                 return
             }
         }
-        // The gamepad-type setting resolves NOW (Automatic → match the active physical
-        // controller): the host's virtual pad backend is fixed per session.
+        startSession(host, launchID: launchID, allowTofu: host.pinnedSHA256 == nil)
+    }
+
+    /// Resolve the @AppStorage stream mode + input prefs and hand off to the session model. The
+    /// gamepad-type setting resolves NOW (Automatic → match the active physical controller): the
+    /// host's virtual pad backend is fixed per session. `requestAccess` opens the no-PIN
+    /// delegated-approval connect (host parks it until the operator approves).
+    private func startSession(
+        _ host: StoredHost, launchID: String? = nil,
+        allowTofu: Bool, requestAccess: Bool = false
+    ) {
+        prepareWake(for: host)
         model.connect(
             to: host,
             width: UInt32(clamping: width), height: UInt32(clamping: height),
@@ -252,8 +419,45 @@ struct ContentView: View {
                 setting: PunktfunkConnection.GamepadType(
                     rawValue: UInt32(clamping: gamepadType)) ?? .auto),
             bitrateKbps: UInt32(clamping: bitrateKbps),
+            audioChannels: UInt8(clamping: audioChannels),
+            hdrEnabled: hdrEnabled,
+            preferredCodec: preferredCodecByte,
             launchID: launchID,
-            allowTofu: host.pinnedSHA256 == nil)
+            allowTofu: allowTofu,
+            requestAccess: requestAccess)
+    }
+
+    /// Learn-while-awake, wake-while-asleep — run just before every connect:
+    ///  • host currently advertising (awake) → refresh its stored Wake-on-LAN MAC(s) from the live
+    ///    advert, so a later wake has an up-to-date target;
+    ///  • host NOT advertising (likely asleep/off) and we have MAC(s) → fire a magic packet first.
+    ///    The connect that follows already retries/times out long enough for a woken host to come
+    ///    up; if it's genuinely off/unreachable the connect fails as before. Best-effort and
+    ///    non-blocking (the send runs off the main thread).
+    private func prepareWake(for host: StoredHost) {
+        if let live = discovery.hosts.first(where: { host.matches($0) }) {
+            store.updateMacs(host.id, macs: live.macAddresses) // learn — on every platform
+        } else if PunktfunkConnection.wakeOnLANAvailable, !host.wakeMacs.isEmpty {
+            let macs = host.wakeMacs
+            let ip = host.address
+            DispatchQueue.global(qos: .userInitiated).async {
+                PunktfunkConnection.wakeOnLAN(macs: macs, lastKnownIP: ip)
+            }
+        }
+    }
+
+    /// The no-PIN delegated-approval flow: open an identified connect the host parks until the
+    /// operator approves it in the console, showing the cancelable "Waiting for approval" prompt
+    /// meanwhile. On success the SAME connection is admitted (no reconnect) and the host is pinned
+    /// as paired (see the `.streaming` branch of `onChange`).
+    private func requestAccess(_ req: ApprovalRequest) {
+        guard !model.isBusy else { return }
+        awaitingApproval = req
+        // Pin the advertised certificate for a discovered host (impostor defence during the long
+        // wait); a manually-typed host has no advertised fingerprint, so trust-on-first-use.
+        var host = req.host
+        host.pinnedSHA256 = req.advertisedFingerprint
+        startSession(host, allowTofu: false, requestAccess: true)
     }
 
     /// Picked a title in the (experimental) library: dismiss the browser and start a session that
@@ -266,16 +470,21 @@ struct ContentView: View {
     /// Tap a discovered host: save it (so the session has a stored identity and the trust pin
     /// persists), then connect or pair per the host's advertised policy. The host is the policy
     /// authority — TOFU is offered ONLY when it explicitly advertised `pair=optional` (rule 3a);
-    /// a `pair=required` host, or one with no/unknown `pair` field, goes straight to the PIN
-    /// pairing ceremony (rule 3b). (A pinned discovered host connects silently inside `connect`.)
+    /// a `pair=required` host, or one with no/unknown `pair` field, gets the approval choice
+    /// (request access / pair with PIN) (rule 3b). (A pinned discovered host connects silently
+    /// inside `connect`.)
     private func connectDiscovered(_ d: DiscoveredHost) {
         guard !model.isBusy else { return }
-        let host = StoredHost(name: d.name, address: d.host, port: d.port)
+        let host = StoredHost(
+            name: d.name, address: d.host, port: d.port,
+            macAddresses: d.macAddresses.isEmpty ? nil : d.macAddresses)
         store.add(host)
         if d.allowsTofu {
             connect(host, allowTofu: true)
         } else {
-            pairingTarget = host
+            // pair=required / unknown policy (rule 3b): offer no-PIN delegated approval or PIN.
+            approvalChoice = ApprovalRequest(
+                host: host, advertisedFingerprint: pinFingerprint(d.fingerprintHex))
         }
     }
 
@@ -289,6 +498,30 @@ struct ContentView: View {
         connect(pinned)
     }
 
+    /// The certificate fingerprint a live mDNS advert carries for this saved host (advisory — see
+    /// `HostDiscovery`), to pin during a delegated-approval wait. nil if the host isn't currently
+    /// advertising or advertised no/invalid `fp`.
+    private func advertisedFingerprint(for host: StoredHost) -> Data? {
+        pinFingerprint(discovery.hosts.first { host.matches($0) }?.fingerprintHex)
+    }
+
+    /// Parse an advertised cert fingerprint (lowercase hex) into the 32-byte pin the connect
+    /// expects; nil unless it's exactly a 32-byte (SHA-256) value, so a malformed advert falls
+    /// back to trust-on-first-use rather than failing the connect closed.
+    private func pinFingerprint(_ hex: String?) -> Data? {
+        guard let hex, let data = Data(hexString: hex), data.count == 32 else { return nil }
+        return data
+    }
+
+    /// How the host lists this device in its approval prompt (matches PairSheet's client name).
+    private var localDeviceName: String {
+        #if os(macOS)
+        Host.current().localizedName ?? "Mac"
+        #else
+        UIDevice.current.name
+        #endif
+    }
+
     // MARK: - First-run + dev hooks
 
     /// First run on iOS: default the stream mode to this device's native screen so the
@@ -351,6 +584,9 @@ struct ContentView: View {
             compositor: pref,
             gamepad: pad,
             bitrateKbps: bitrate,
+            audioChannels: UInt8(clamping: audioChannels),
+            hdrEnabled: hdrEnabled,
+            preferredCodec: preferredCodecByte,
             autoTrust: true)
     }
 }
@@ -375,3 +611,11 @@ private struct FullscreenController: NSViewRepresentable {
     }
 }
 #endif
+
+/// A fresh `pair=required`/unknown host pending a trust decision: drives both the "request access
+/// vs. pair with PIN" choice and the subsequent approval wait. `advertisedFingerprint` is the
+/// discovered host's advertised cert (nil for a manually-typed host → trust-on-first-use).
+private struct ApprovalRequest {
+    let host: StoredHost
+    let advertisedFingerprint: Data?
+}

clients/apple/Sources/PunktfunkClient/Home/AddHostSheet.swift

@@ -81,6 +81,11 @@ struct AddHostSheet: View {
             #if !os(tvOS)
         .formStyle(.grouped)
         #endif
+            #if os(iOS)
+            // The detent below is sized to fit all 3 rows + the action button exactly, so the
+            // Form must NOT scroll/bounce inside it — lock it. (iOS 16+; safe at iOS 17.)
+            .scrollDisabled(true)
+            #endif
             #if os(macOS)
             // macOS: UNCHANGED — Cancel + Spacer + Add in an HStack, both wired to the
             // window's default/cancel keyboard actions. The 380-wide .fixedSize panel below
@@ -120,8 +125,8 @@ struct AddHostSheet: View {
         // Form + the full-width action row, instead of the half-screen .medium it used to rest
         // at. A single fixed detent is enough: the system keeps the content above the keyboard
         // when Address/Port is focused, and on iPadOS this renders as a short bottom sheet (not a
-        // centered formSheet card). If Dynamic Type grows the rows past this height the Form just
-        // scrolls inside the detent — nothing is clipped. (.height(_:) is iOS 16+, safe at iOS 17.)
+        // centered formSheet card). The Form itself is .scrollDisabled (above) so it can't
+        // bounce/scroll inside this fixed detent. (.height(_:) is iOS 16+, safe at iOS 17.)
         .presentationDetents([.height(320)])
         .presentationDragIndicator(.visible)
         #endif

clients/apple/Sources/PunktfunkClient/Home/GamepadAddHostView.swift

@@ -0,0 +1,234 @@
+// The gamepad-driven "Add Host" screen (iOS/iPadOS/macOS) — the controller counterpart of
+// AddHostSheet, reached from the launcher's Add Host tile. Three field rows (name / address /
+// port) plus the Add action, navigated with the same vertical focus list as the gamepad settings;
+// A on a field opens GamepadKeyboard in a bottom tray, so a host can be registered end to end
+// without touching the screen. Field edits are live (the row shows every keystroke); B closes the
+// keyboard first, then cancels the screen — the same "back peels one layer" rule as a console UI.
+
+import PunktfunkKit
+import SwiftUI
+#if os(iOS) || os(macOS)
+
+struct GamepadAddHostView: View {
+    @Environment(\.dismiss) private var dismiss
+    let onAdd: (StoredHost) -> Void
+
+    #if os(iOS)
+    /// `.compact` in a landscape phone window — tighter chrome so the keyboard tray still fits.
+    @Environment(\.verticalSizeClass) private var vSizeClass
+
+    private var compact: Bool { vSizeClass == .compact }
+    #else
+    private let compact = false // no size classes on macOS; the sheet is sized to fit the tray
+    #endif
+    @State private var name = ""
+    @State private var address = ""
+    @State private var port = "9777"
+    @State private var focusID: String?
+    /// The field row the keyboard tray is editing; nil ⇒ the row list owns the controller.
+    @State private var editing: String?
+
+    var body: some View {
+        GamepadMenuList(
+            items: rows,
+            focusID: $focusID,
+            onActivate: { activate(id: $0.id) },
+            onBack: { dismiss() },
+            isActive: editing == nil
+        ) { row, focused in
+            rowView(row, focused: focused)
+                .frame(maxWidth: 620)
+                .padding(.horizontal, 24)
+        }
+        .frame(maxWidth: .infinity)
+        .safeAreaInset(edge: .top, spacing: 0) {
+            VStack(spacing: 4) {
+                Text("Add Host")
+                    .font(.geist(compact ? 20 : 30, .bold, relativeTo: .title))
+                    .foregroundStyle(.white)
+                if !compact {
+                    Text("Hosts on this network appear automatically — add one by address "
+                        + "for everything else.")
+                        .font(.geist(13, relativeTo: .caption))
+                        .foregroundStyle(.white.opacity(0.55))
+                        .multilineTextAlignment(.center)
+                        .frame(maxWidth: 440)
+                }
+            }
+            .padding(.top, gamepadTitleTopPadding(compact: compact))
+            .padding(.bottom, compact ? 4 : 8)
+            .frame(maxWidth: .infinity)
+            .overlay(alignment: .topTrailing) { closeButton.padding(.trailing, 20) }
+            .background { GamepadTrayScrim(edge: .top) }
+        }
+        .safeAreaInset(edge: .bottom, spacing: 0) {
+            bottomTray
+                .padding(.horizontal, 22)
+                .padding(.vertical, compact ? 6 : 10)
+                .background { GamepadTrayScrim(edge: .bottom) }
+        }
+        .background { GamepadScreenBackground() }
+        // A port can't exceed 5 digits — cap while typing so the row can't grow absurd.
+        .onChange(of: port) { _, value in
+            if value.count > 5 { port = String(value.prefix(5)) }
+        }
+    }
+
+    /// The keyboard tray while editing, the controls legend otherwise.
+    @ViewBuilder private var bottomTray: some View {
+        if let editing {
+            VStack(spacing: 10) {
+                GamepadKeyboard(
+                    text: editingBinding(editing),
+                    allowed: allowedCharacters(editing),
+                    onDone: { closeKeyboard() })
+                    // Fresh keyboard per field: a touch user can retarget the tray by tapping
+                    // another field row, and the keyboard's input wiring captured the previous
+                    // binding on appear — new identity forces a rewire to the new field.
+                    .id(editing)
+                GamepadHintBar(hints: [
+                    .init(glyph: buttonGlyph(\.buttonA, fallback: "a.circle"), text: "Type"),
+                    .init(glyph: buttonGlyph(\.buttonX, fallback: "x.circle"), text: "Delete"),
+                    .init(glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Done"),
+                ])
+                .frame(maxWidth: .infinity, alignment: .leading)
+            }
+            .transition(.move(edge: .bottom).combined(with: .opacity))
+        } else {
+            GamepadHintBar(hints: [
+                .init(glyph: buttonGlyph(\.buttonA, fallback: "a.circle"), text: "Select"),
+                .init(glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Cancel"),
+            ])
+            .frame(maxWidth: .infinity, alignment: .leading)
+        }
+    }
+
+    /// Touch/click fallback for closing — the controller path is B, a hardware keyboard's Esc
+    /// rides the cancel action.
+    private var closeButton: some View {
+        Button { dismiss() } label: {
+            Image(systemName: "xmark")
+                .font(.system(size: 14, weight: .semibold))
+                .foregroundStyle(.white)
+                .frame(width: 34, height: 34)
+                .glassBackground(Circle(), interactive: true)
+                .contentShape(Circle())
+        }
+        .buttonStyle(.plain)
+        .keyboardShortcut(.cancelAction)
+        .accessibilityLabel("Cancel")
+    }
+
+    // MARK: - Rows
+
+    private struct Row: Identifiable {
+        let id: String
+        let label: String
+        var value = ""
+        var placeholder = ""
+        var isAction = false
+    }
+
+    private var rows: [Row] {
+        [
+            Row(id: "name", label: "Name", value: name, placeholder: "Optional — e.g. Living Room"),
+            Row(id: "address", label: "Address", value: address, placeholder: "IP or hostname"),
+            Row(id: "port", label: "Port", value: port, placeholder: "9777"),
+            Row(id: "add", label: "Add Host", isAction: true),
+        ]
+    }
+
+    private func rowView(_ row: Row, focused: Bool) -> some View {
+        HStack(spacing: 14) {
+            if row.isAction {
+                Label("Add Host", systemImage: "plus.circle.fill")
+                    .font(.geist(16, .semibold, relativeTo: .body))
+                    .foregroundStyle(canAdd ? Color.brand : .white.opacity(0.35))
+                    .frame(maxWidth: .infinity)
+            } else {
+                Text(row.label)
+                    .font(.geist(16, .semibold, relativeTo: .body))
+                    .foregroundStyle(.white)
+                Spacer(minLength: 12)
+                Text(row.value.isEmpty ? row.placeholder : row.value)
+                    .font(.geistFixed(15, .medium))
+                    .foregroundStyle(row.value.isEmpty ? .white.opacity(0.35) : .white)
+                    .lineLimit(1)
+                    .truncationMode(.head) // keep the end of a long address visible while typing
+                if editing == row.id {
+                    // The live-edit caret: this row is what the keyboard tray is typing into.
+                    Rectangle()
+                        .fill(Color.brand)
+                        .frame(width: 2, height: 18)
+                }
+            }
+        }
+        .padding(.horizontal, 16)
+        .padding(.vertical, 13)
+        .background {
+            RoundedRectangle(cornerRadius: 14, style: .continuous)
+                .fill(.white.opacity(focused || editing == row.id ? 0.1 : 0))
+        }
+        .overlay {
+            RoundedRectangle(cornerRadius: 14, style: .continuous)
+                .strokeBorder(
+                    editing == row.id ? Color.brand.opacity(0.7) : .white.opacity(focused ? 0.22 : 0),
+                    lineWidth: 1)
+        }
+        .scaleEffect(focused ? 1.0 : 0.98)
+        .animation(.smooth(duration: 0.18), value: focused)
+    }
+
+    // MARK: - Actions
+
+    private func activate(id: String) {
+        switch id {
+        case "add":
+            guard canAdd else {
+                // Not addable yet — jump straight to what's missing instead of a dead press.
+                focusID = "address"
+                openKeyboard("address")
+                return
+            }
+            onAdd(StoredHost(
+                name: name.trimmingCharacters(in: .whitespaces),
+                address: address.trimmingCharacters(in: .whitespaces),
+                port: UInt16(port) ?? 9777))
+            dismiss()
+        default:
+            openKeyboard(id)
+        }
+    }
+
+    private var canAdd: Bool {
+        !address.trimmingCharacters(in: .whitespaces).isEmpty
+            && UInt16(port).map { $0 > 0 } == true
+    }
+
+    private func openKeyboard(_ id: String) {
+        withAnimation(.spring(response: 0.32, dampingFraction: 0.86)) { editing = id }
+    }
+
+    private func closeKeyboard() {
+        withAnimation(.spring(response: 0.32, dampingFraction: 0.86)) { editing = nil }
+    }
+
+    private func editingBinding(_ id: String) -> Binding<String> {
+        switch id {
+        case "name": return $name
+        case "port": return $port
+        default: return $address
+        }
+    }
+
+    /// What the keyboard may type per field: a port is digits, an address never contains spaces;
+    /// a name is free-form.
+    private func allowedCharacters(_ id: String) -> CharacterSet? {
+        switch id {
+        case "port": return CharacterSet(charactersIn: "0123456789")
+        case "address": return CharacterSet(charactersIn: " ").inverted
+        default: return nil
+        }
+    }
+}
+#endif

clients/apple/Sources/PunktfunkClient/Home/GamepadCarousel.swift

@@ -0,0 +1,270 @@
+// The one piece of gamepad-menu machinery shared by the host launcher (GamepadHomeView) and the
+// library coverflow (LibraryCoverflowView): a horizontal, center-snapping carousel driven entirely
+// by a controller (iOS/iPadOS/macOS).
+//
+// The scrolling is pure native SwiftUI — `.scrollTargetLayout()` + `.scrollTargetBehavior(.viewAligned)`
+// snap exactly one item to center, and symmetric `.safeAreaPadding(.horizontal)` (sized off the live
+// container width, so it's correct in an iPad split view too) lets the first and last item reach the
+// middle. The CALLER owns each card's look, including its own `.scrollTransition` — this component
+// deliberately applies none, so a screen can chain the VisualEffect-only transition modifiers without
+// the generic wrapper here pushing the type-checker onto an overload it can't satisfy.
+//
+// Navigation authority: an internal `cursor` (an index), NOT the scroll-position binding, is the
+// source of truth for where the gamepad is. `.scrollPosition(id:)` is a two-way binding and the
+// scroll view WRITES intermediate ids into it while a programmatic animation is in flight — so
+// reading the "current" item back out of it to compute the next one desyncs badly on a fast held
+// stick (each move reads a lagging value and the cursor stalls before the last item). Instead a move
+// advances `cursor` synchronously and points the scroll view at `items[cursor]`; scroll read-back is
+// only allowed to move the cursor when the gamepad hasn't driven recently (i.e. a touch drag).
+//
+// Feedback is dual-channel by design: `.sensoryFeedback` ticks the DEVICE Taptic engine (for a
+// handheld/touch user) and `MenuHaptics` ticks the CONTROLLER (for a couch user holding the pad).
+// Both fire on a move, on confirm, and — for a non-wrapping list — a duller bump plus a short visual
+// recoil when a move is refused at either end.
+
+import PunktfunkKit
+import SwiftUI
+#if os(iOS) || os(macOS)
+
+struct GamepadCarousel<Item: Identifiable, Card: View>: View where Item.ID: Hashable {
+    let items: [Item]
+    /// Output only: the carousel WRITES the focused item's id here for the caller's detail panel.
+    /// It is deliberately not what drives the scroll (see the file header).
+    @Binding var selection: Item.ID?
+    /// Every card is laid out at this fixed width so `.viewAligned` snapping + symmetric side
+    /// insets center exactly one at a time.
+    let itemWidth: CGFloat
+    let spacing: CGFloat
+    /// A → activate the centered item.
+    let onActivate: (Item) -> Void
+    /// Y → the screen's secondary action (e.g. open a host's library); nil disables it.
+    var onSecondary: (() -> Void)?
+    /// X → the screen's tertiary action (e.g. open settings); nil disables it.
+    var onTertiary: (() -> Void)?
+    /// B → back/dismiss; nil disables it (e.g. the root launcher has nowhere to go back to).
+    var onBack: (() -> Void)?
+    /// L1/R1 → jump this many items at once (clamped to the ends); 0 disables the shoulders.
+    var shoulderJump: Int = 0
+    /// Whether this carousel currently owns controller input. A presenting screen (e.g. the host
+    /// launcher) stays mounted behind a presented one (e.g. the library), and both carousels would
+    /// otherwise poll the SAME controller at once — driving both. The parent sets this false while
+    /// something is presented on top so only the front-most carousel consumes the gamepad.
+    var isActive: Bool = true
+    @ViewBuilder let card: (Item) -> Card
+
+    @State private var input = GamepadMenuInput(manager: .shared)
+    @State private var haptics = MenuHaptics(manager: .shared)
+    /// Authoritative gamepad cursor (index into `items`). Never assigned from scroll read-back
+    /// while the gamepad is driving — that's the whole desync fix.
+    @State private var cursor = 0
+    /// The id the scroll view is aligned to — its own two-way `.scrollPosition` state.
+    @State private var scrolledID: Item.ID?
+    /// When the gamepad last moved the cursor; gates scroll read-back so a mid-animation write can't
+    /// drag the cursor backward during a fast held direction.
+    @State private var lastNav = Date.distantPast
+    /// True while a programmatic scroll animation is in flight. `.scrollPosition(id:)` DROPS a new
+    /// write that lands mid-animation — the scroll view stays stuck on the old item even though the
+    /// binding updated — so we never issue one until the previous animation reports complete, then
+    /// `commitScroll` re-targets the current cursor (coalescing a fast burst; see `commitScroll`).
+    @State private var isScrolling = false
+    /// A short horizontal recoil when a move is refused at a list end.
+    @State private var bumpOffset: CGFloat = 0
+    /// `.sensoryFeedback` fires on a change of its trigger; counters request a device tick for the
+    /// confirm and end-stop events (moves trigger on `cursor`).
+    @State private var activateTick = 0
+    @State private var boundaryTick = 0
+
+    /// Read-back from a touch drag is honoured only once the gamepad has been quiet this long
+    /// (longer than a move animation, so overlapping held-stick moves never let it through).
+    private let navSettle: TimeInterval = 0.4
+
+    var body: some View {
+        GeometryReader { geo in
+            let inset = max(0, (geo.size.width - itemWidth) / 2)
+            ScrollView(.horizontal) {
+                HStack(spacing: spacing) {
+                    ForEach(items) { item in
+                        card(item)
+                            .frame(width: itemWidth)
+                            .contentShape(Rectangle())
+                            .onTapGesture { tap(item) }
+                    }
+                }
+                .frame(height: geo.size.height) // fill so shorter cards center vertically
+                .scrollTargetLayout()
+            }
+            .scrollPosition(id: $scrolledID)
+            .scrollTargetBehavior(.viewAligned)
+            // .never, not .hidden — macOS's "always show scroll bars" setting overrides .hidden
+            // and paints a scroller across the console strip.
+            .scrollIndicators(.never)
+            .scrollClipDisabled() // let the focused card scale up past the strip bounds
+            .safeAreaPadding(.horizontal, inset)
+            .offset(x: bumpOffset)
+        }
+        .sensoryFeedback(.selection, trigger: cursor)
+        .sensoryFeedback(.impact(weight: .medium), trigger: activateTick)
+        .sensoryFeedback(.impact(flexibility: .rigid, intensity: 0.7), trigger: boundaryTick)
+        .onAppear {
+            reconcile()
+            wire()
+            if isActive { input.start() }
+        }
+        .onDisappear {
+            input.stop()
+            haptics.stop()
+        }
+        // Hand controller input to/from a screen presented on top (see `isActive`): a covered
+        // carousel stops polling so it can't navigate behind the front-most one.
+        .onChange(of: isActive) { _, active in
+            if active {
+                wire()
+                input.start()
+            } else {
+                input.stop()
+                haptics.stop()
+            }
+        }
+        // A touch drag settles the scroll onto a new id: adopt it as the cursor. Ignored while a
+        // programmatic scroll is animating (its own intermediate id write-backs would regress the
+        // cursor) and briefly after a gamepad move (the same reason), so only a genuine touch drag
+        // — which never sets `isScrolling` — moves the cursor here.
+        .onChange(of: scrolledID) { _, newValue in
+            guard !isScrolling, Date().timeIntervalSince(lastNav) > navSettle else { return }
+            guard let idx = index(of: newValue), idx != cursor else { return }
+            cursor = idx
+            selection = newValue
+        }
+        // Re-seed a dropped/changed selection AND re-wire the input callbacks so they capture the
+        // current `items` value (a plain array — unlike an observed object it would otherwise go
+        // stale in the closures stored on `input`).
+        .onChange(of: items.map(\.id)) { _, _ in
+            reconcile()
+            wire()
+        }
+    }
+
+    // MARK: - Input wiring
+
+    private func wire() {
+        input.onMove = { move($0) }
+        input.onConfirm = { activate() }
+        input.onSecondary = onSecondary
+        input.onTertiary = onTertiary
+        input.onBack = onBack
+        input.onShoulder = shoulderJump > 0 ? { shoulder(right: $0) } : nil
+    }
+
+    private func move(_ direction: GamepadMenuInput.Direction) {
+        let forward = direction == .right || direction == .down
+        step(by: forward ? 1 : -1, clampAtEnds: false)
+    }
+
+    private func shoulder(right: Bool) {
+        step(by: right ? shoulderJump : -shoulderJump, clampAtEnds: true)
+    }
+
+    /// Advance the cursor by `delta`. A single move (`clampAtEnds: false`) that would leave the list
+    /// recoils + bumps; a shoulder jump (`clampAtEnds: true`) lands on the end item, bumping only if
+    /// already there. The cursor is the authority — the scroll view is pointed at it, never read for it.
+    private func step(by delta: Int, clampAtEnds: Bool) {
+        guard !items.isEmpty else { return }
+        var target = cursor + delta
+        if target < 0 || target >= items.count {
+            guard clampAtEnds else { return boundaryBump(forward: delta > 0) }
+            target = min(max(target, 0), items.count - 1)
+        }
+        guard target != cursor else { return boundaryBump(forward: delta > 0) }
+        cursor = target
+        lastNav = Date()
+        haptics.move()
+        selection = items[target].id // text/detail updates immediately; the scroll chases
+        commitScroll()
+    }
+
+    private let scrollAnim: TimeInterval = 0.24
+    /// A hair past `scrollAnim` — long enough that the scroll has actually settled before the next
+    /// write, short enough to stay responsive.
+    private var scrollSettle: TimeInterval { scrollAnim + 0.05 }
+
+    /// Drive the scroll toward the current cursor, one honoured write at a time. `.scrollPosition(id:)`
+    /// DROPS a write that lands while a scroll is still animating, so we issue at most one at a time and
+    /// re-target the LATEST cursor once it settles — coalescing a fast burst (hold OR quick flicks) and
+    /// always converging on the final item, instead of getting stuck on the old card.
+    ///
+    /// The settle is timed by a plain timer rather than `withAnimation`'s completion: `scrolledID` is a
+    /// discrete id, not an animatable value, so `withAnimation` has no tracked animation to fire a
+    /// reliable completion against (it can fire early — which is exactly what let quick flicks slip a
+    /// write through mid-scroll and stick). `asyncAfter` always fires, so `isScrolling` can never latch.
+    private func commitScroll() {
+        guard !isScrolling, cursor >= 0, cursor < items.count else { return }
+        let id = items[cursor].id
+        guard scrolledID != id else { return }
+        isScrolling = true
+        withAnimation(.easeOut(duration: scrollAnim)) { scrolledID = id }
+        DispatchQueue.main.asyncAfter(deadline: .now() + scrollSettle) {
+            MainActor.assumeIsolated {
+                isScrolling = false
+                commitScroll() // the cursor may have advanced while this scroll ran — chase it
+            }
+        }
+    }
+
+    private func activate() {
+        guard cursor >= 0, cursor < items.count else { return }
+        activateTick &+= 1
+        haptics.confirm()
+        onActivate(items[cursor])
+    }
+
+    /// Touch fallback matching the rest of the app: tapping the centered card activates it, tapping
+    /// any other re-centers on it.
+    private func tap(_ item: Item) {
+        if let idx = index(of: item.id), idx == cursor {
+            activate()
+        } else if let idx = index(of: item.id) {
+            cursor = idx
+            lastNav = Date()
+            haptics.move()
+            selection = item.id
+            commitScroll()
+        }
+    }
+
+    // MARK: - Selection housekeeping
+
+    private func index(of id: Item.ID?) -> Int? {
+        guard let id else { return nil }
+        return items.firstIndex { $0.id == id }
+    }
+
+    /// Keep `cursor`/`scrolledID`/`selection` consistent with `items`: seed on appear, and on a list
+    /// change keep the same focused item when it survives, else clamp the cursor into range.
+    private func reconcile() {
+        guard !items.isEmpty else {
+            cursor = 0
+            if scrolledID != nil { scrolledID = nil }
+            if selection != nil { selection = nil }
+            return
+        }
+        if let sid = scrolledID, let idx = index(of: sid) {
+            cursor = idx
+            if selection != sid { selection = sid }
+        } else {
+            let idx = min(max(cursor, 0), items.count - 1)
+            cursor = idx
+            let id = items[idx].id
+            scrolledID = id
+            selection = id
+        }
+    }
+
+    private func boundaryBump(forward: Bool) {
+        boundaryTick &+= 1
+        haptics.boundary()
+        let recoil: CGFloat = forward ? -16 : 16
+        withAnimation(.spring(response: 0.16, dampingFraction: 0.42)) { bumpOffset = recoil }
+        withAnimation(.spring(response: 0.34, dampingFraction: 0.7).delay(0.1)) { bumpOffset = 0 }
+    }
+}
+#endif

clients/apple/Sources/PunktfunkClient/Home/GamepadChrome.swift

@@ -0,0 +1,232 @@
+// Chrome shared by the gamepad-driven screens (GamepadHomeView, GamepadSettingsView,
+// GamepadAddHostView, LibraryCoverflowView): the full-bleed console backdrop, the
+// controller-glyph hint bar, and the connected-controller status chip. One look across every
+// screen is what makes the gamepad UI read as a coherent mode rather than a set of themed pages.
+// iOS/iPadOS and macOS (the couch Mac-mini case); tvOS keeps its native focus engine instead.
+
+import PunktfunkKit
+import SwiftUI
+#if os(iOS) || os(macOS)
+import GameController
+
+/// The active controller's real glyph for a button (Xbox "A", DualSense ✕, …) via
+/// `sfSymbolsName`; a generic fallback before a controller profile resolves.
+/// @MainActor: GamepadManager is main-actor-bound (inside a View body this was implicit).
+@MainActor
+func buttonGlyph(
+    _ button: KeyPath<GCExtendedGamepad, GCControllerButtonInput>, fallback: String
+) -> String {
+    GamepadManager.shared.active?.controller.extendedGamepad?[keyPath: button].sfSymbolsName
+        ?? fallback
+}
+
+/// Top padding for a gamepad screen's pinned title. macOS gets extra clearance — the launcher
+/// title sits right under the window titlebar and the settings/add-host sheets have no titlebar
+/// at all, so the iOS value hugs the top edge there.
+func gamepadTitleTopPadding(compact: Bool) -> CGFloat {
+    #if os(macOS)
+    26
+    #else
+    compact ? 4 : 10
+    #endif
+}
+
+/// One glyph + label cell in a hint bar.
+struct GamepadHint: Identifiable {
+    let glyph: String
+    let text: String
+    var id: String { glyph + text }
+}
+
+/// The pinned controls legend every gamepad screen shows bottom-leading (via `.safeAreaInset`).
+/// Same font/spacing everywhere so the legend reads as system chrome, not per-screen decoration.
+struct GamepadHintBar: View {
+    let hints: [GamepadHint]
+
+    var body: some View {
+        HStack(spacing: 18) {
+            ForEach(hints) { hint in
+                HStack(spacing: 7) {
+                    Image(systemName: hint.glyph)
+                        .font(.system(size: 19))
+                        .foregroundStyle(.white)
+                    Text(hint.text)
+                }
+                .fixedSize() // keep glyph + label together; never truncate a hint mid-word
+            }
+        }
+        .font(.geist(14, .semibold, relativeTo: .subheadline))
+        .foregroundStyle(.white.opacity(0.85))
+    }
+}
+
+/// The console backdrop: a living "aurora" field in the brand's violet family — soft color blobs
+/// drifting on slow Lissajous paths over black, in the direction of Apple Music's animated player
+/// background but calmer (long 30–90 s periods, muted opacities, a legibility scrim on top, so it
+/// reads as ambience behind the cards, never as content). Deliberately pure SwiftUI rather than a
+/// .metal shader: these sources are built both by SwiftPM (`swift run`/tests) and by the Xcode
+/// project's synchronized folders, and a compiled metallib is only reliably bundled in one of the
+/// two — radial gradients driven by a TimelineView give the same look with none of that risk.
+///
+/// Applied via `.background { }` — NOT as a ZStack sibling — so the `.ignoresSafeArea()` here
+/// can't inflate the caller's layout past the safe area (see the layout discipline note in
+/// GamepadHomeView's header). Honors Reduce Motion by freezing the field at a fixed phase.
+struct GamepadScreenBackground: View {
+    @Environment(\.accessibilityReduceMotion) private var reduceMotion
+
+    /// One drifting color blob: a base position + drift ellipse (unit coordinates), angular
+    /// speeds (rad/s — periods of 30–90 s), and a radius that slowly breathes.
+    private struct Blob {
+        let color: Color
+        let center: CGPoint
+        let drift: CGSize
+        let speed: (x: Double, y: Double)
+        let phase: (x: Double, y: Double)
+        /// Radius as a fraction of the view's larger dimension (+ breathing amplitude/speed).
+        let radius: CGFloat
+        let breathe: (amount: CGFloat, speed: Double)
+        let opacity: Double
+    }
+
+    /// The brand violet, a deeper indigo, a warmer plum, and a cool blue — related hues so the
+    /// field shifts within one temperature instead of strobing through the rainbow.
+    private static let blobs: [Blob] = [
+        Blob(color: Color(red: 0.53, green: 0.47, blue: 0.96), // brand violet
+             center: CGPoint(x: 0.30, y: 0.24), drift: CGSize(width: 0.16, height: 0.10),
+             speed: (0.111, 0.083), phase: (0.0, 1.9),
+             radius: 0.52, breathe: (0.07, 0.061), opacity: 0.52),
+        Blob(color: Color(red: 0.24, green: 0.20, blue: 0.72), // deep indigo
+             center: CGPoint(x: 0.78, y: 0.66), drift: CGSize(width: 0.13, height: 0.14),
+             speed: (0.071, 0.096), phase: (2.4, 0.7),
+             radius: 0.58, breathe: (0.08, 0.049), opacity: 0.55),
+        Blob(color: Color(red: 0.62, green: 0.30, blue: 0.80), // plum
+             center: CGPoint(x: 0.16, y: 0.82), drift: CGSize(width: 0.12, height: 0.09),
+             speed: (0.089, 0.067), phase: (4.1, 3.2),
+             radius: 0.44, breathe: (0.09, 0.078), opacity: 0.42),
+        Blob(color: Color(red: 0.22, green: 0.38, blue: 0.86), // cool blue
+             center: CGPoint(x: 0.70, y: 0.12), drift: CGSize(width: 0.10, height: 0.08),
+             speed: (0.059, 0.104), phase: (1.2, 5.0),
+             radius: 0.40, breathe: (0.06, 0.055), opacity: 0.38),
+    ]
+
+    var body: some View {
+        Group {
+            if reduceMotion {
+                field(at: 0)
+            } else {
+                // 30 Hz is plenty for centimeters-per-minute drift, and halves the redraw cost
+                // of a battery-fed couch device vs. the default display rate.
+                TimelineView(.animation(minimumInterval: 1.0 / 30.0)) { context in
+                    field(at: context.date.timeIntervalSinceReferenceDate)
+                }
+            }
+        }
+        .ignoresSafeArea()
+    }
+
+    private func field(at t: TimeInterval) -> some View {
+        GeometryReader { geo in
+            let side = max(geo.size.width, geo.size.height)
+            ZStack {
+                Color.black
+                ZStack {
+                    ForEach(Self.blobs.indices, id: \.self) { i in
+                        blobView(Self.blobs[i], at: t, in: geo.size, side: side)
+                    }
+                }
+                // ±10° over ~5 min — the whole field very slowly warms and cools.
+                .hueRotation(.degrees(sin(t * 0.021) * 10))
+                // Composite the additive blobs offscreen once instead of per-layer.
+                .drawingGroup()
+                // Legibility scrim: the title (top) and detail/hints (bottom) always sit on
+                // near-black, whatever the blobs are doing behind them.
+                LinearGradient(
+                    stops: [
+                        .init(color: .black.opacity(0.55), location: 0),
+                        .init(color: .black.opacity(0.15), location: 0.35),
+                        .init(color: .black.opacity(0.20), location: 0.65),
+                        .init(color: .black.opacity(0.60), location: 1),
+                    ],
+                    startPoint: .top, endPoint: .bottom)
+            }
+        }
+    }
+
+    private func blobView(_ blob: Blob, at t: TimeInterval, in size: CGSize, side: CGFloat) -> some View {
+        let x = blob.center.x + blob.drift.width * CGFloat(sin(t * blob.speed.x + blob.phase.x))
+        let y = blob.center.y + blob.drift.height * CGFloat(cos(t * blob.speed.y + blob.phase.y))
+        let r = side * blob.radius
+            * (1 + blob.breathe.amount * CGFloat(sin(t * blob.breathe.speed + blob.phase.x)))
+        return Circle()
+            .fill(RadialGradient(
+                colors: [blob.color, blob.color.opacity(0)],
+                center: .center, startRadius: 0, endRadius: r / 2))
+            .frame(width: r, height: r)
+            .position(x: x * size.width, y: y * size.height)
+            .opacity(blob.opacity)
+            .blendMode(.plusLighter)
+    }
+}
+
+/// A darkening scrim behind a pinned tray (a screen title, the hints/detail bar, the keyboard
+/// tray): scrollable rows pass beneath those insets, so without this the tray text and the row
+/// underneath render interleaved. Fades toward the content so it reads as depth, not a bar.
+struct GamepadTrayScrim: View {
+    let edge: VerticalEdge
+
+    var body: some View {
+        LinearGradient(
+            stops: [
+                .init(color: .black.opacity(0.92), location: 0),
+                .init(color: .black.opacity(0.85), location: 0.55),
+                .init(color: .black.opacity(0), location: 1),
+            ],
+            startPoint: edge == .top ? .top : .bottom,
+            endPoint: edge == .top ? .bottom : .top)
+            // Grow past the tray so the fade-to-clear happens OUTSIDE its bounds — the tray's own
+            // text always sits on the near-opaque part, rows dim before they reach it.
+            .padding(edge == .top ? .bottom : .top, -32)
+            .ignoresSafeArea()
+    }
+}
+
+/// "Which pad is driving this UI" — the active controller's name and battery, worn as a quiet
+/// chip in the launcher's top bar. Callers observe GamepadManager already, so this re-renders
+/// when the pad or its battery state changes.
+struct ControllerStatusChip: View {
+    let controller: GamepadManager.DiscoveredController
+
+    var body: some View {
+        HStack(spacing: 7) {
+            Image(systemName: controller.hasTouchpadAndMotion
+                ? "playstation.logo" : "gamecontroller.fill")
+                .font(.system(size: 12))
+            Text(controller.name)
+                .lineLimit(1)
+            if let level = controller.batteryLevel {
+                Image(systemName: batterySymbol(level))
+                    .font(.system(size: 12))
+                    .foregroundStyle(level <= 0.2 && !controller.isCharging
+                        ? AnyShapeStyle(.red) : AnyShapeStyle(.white.opacity(0.7)))
+            }
+        }
+        .font(.geist(12, .medium, relativeTo: .caption))
+        .foregroundStyle(.white.opacity(0.7))
+        .padding(.horizontal, 12)
+        .padding(.vertical, 7)
+        .background(Capsule().fill(.white.opacity(0.08)))
+        .overlay(Capsule().strokeBorder(.white.opacity(0.12), lineWidth: 1))
+    }
+
+    private func batterySymbol(_ level: Float) -> String {
+        if controller.isCharging { return "battery.100.bolt" }
+        switch level {
+        case ..<0.125: return "battery.0"
+        case ..<0.375: return "battery.25"
+        case ..<0.625: return "battery.50"
+        case ..<0.875: return "battery.75"
+        default: return "battery.100"
+        }
+    }
+}
+#endif

clients/apple/Sources/PunktfunkClient/Home/GamepadHomeView.swift

@@ -0,0 +1,368 @@
+// The gamepad-driven home screen (iOS/iPadOS only): a distinct, "10-foot" console-style host
+// launcher shown INSTEAD of HomeView while GamepadUIEnvironment is active — a separate screen built
+// around a center-snapping carousel of hosts, driven from the couch with a controller. No touch is
+// required anywhere: A connects, Y opens a saved host's library (when the flag is on), X opens the
+// gamepad settings screen, and the carousel always ends in an Add Host tile that opens the
+// controller-keyboard add flow. (A tap still works as a fallback for all of it.)
+//
+// All the scrolling/snapping/navigation/haptics live in GamepadCarousel; this file is the launcher's
+// chrome. Layout discipline (so nothing is EVER clipped, portrait or landscape): the gradient is a
+// `.background` modifier — NOT a ZStack sibling — because an `.ignoresSafeArea()` sibling expands the
+// stack to full-screen and hands the GeometryReader the full height, laying content out under the
+// status bar / home indicator. As a background it draws behind without affecting layout, so the
+// GeometryReader is sized to the safe area. The title and the controller-glyph hints are pinned with
+// `.safeAreaInset` (top / bottom-leading) — guaranteed inside the safe area and out of the carousel's
+// vertical budget — and the card is sized off the remaining height. macOS mounts it too (the
+// couch Mac-mini case) — same screen, with the settings/add-host covers presented as sheets
+// (macOS has no fullScreenCover). tvOS never mounts this view (native focus engine instead).
+
+import PunktfunkKit
+import SwiftUI
+#if os(iOS) || os(macOS)
+import GameController
+
+/// One navigable tile: a saved host, a discovered-but-unsaved one, or the trailing Add Host
+/// action. Hashable so it can be the carousel's scroll-position identity.
+private enum GamepadHomeTarget: Hashable {
+    case saved(UUID)
+    case discovered(String)
+    case addHost
+}
+
+/// A fully-resolved launcher tile — display fields + the activate action, built fresh each render
+/// from the live stores so nothing goes stale.
+private struct HomeTile: Identifiable {
+    let id: GamepadHomeTarget
+    let title: String
+    let subtitle: String
+    var isOnline = false
+    var isPaired = false
+    var isConnecting = false
+    /// Saved (solid monogram) vs. discovered-but-unsaved / action (tinted outline).
+    var filled = false
+    /// Only saved hosts have a library (matches the touch grid's context-menu gate).
+    var hasLibrary = false
+    /// Shows this SF symbol in the badge instead of the title monogram (the Add Host tile).
+    var icon: String?
+    /// Whether the detail panel shows the online/paired pill (hosts yes, actions no).
+    var showsStatus = true
+    let activate: () -> Void
+}
+
+struct GamepadHomeView: View {
+    @ObservedObject var store: HostStore
+    @ObservedObject var model: SessionModel
+    @ObservedObject var discovery: HostDiscovery
+    @Binding var libraryTarget: StoredHost?
+    let connect: (StoredHost) -> Void
+    let connectDiscovered: (DiscoveredHost) -> Void
+
+    /// Same experimental gate the touch grid's "Browse Library…" context-menu item uses.
+    @AppStorage(DefaultsKey.libraryEnabled) private var libraryEnabled = false
+    #if os(iOS)
+    /// `.compact` in a landscape phone window — drives tighter chrome so everything still fits.
+    @Environment(\.verticalSizeClass) private var vSizeClass
+
+    private var compact: Bool { vSizeClass == .compact }
+    #else
+    private let compact = false // no size classes on macOS; the window minimum keeps room
+    #endif
+    @ObservedObject private var gamepads = GamepadManager.shared
+    @State private var selection: GamepadHomeTarget?
+    @State private var showSettings = false
+    @State private var showAddHost = false
+
+    var body: some View {
+        GeometryReader { geo in
+            hero(for: geo.size)
+        }
+        // Pinned inside the safe area, out of the carousel's vertical budget — never clipped.
+        .safeAreaInset(edge: .top, spacing: 0) {
+            titleBar
+                .padding(.top, gamepadTitleTopPadding(compact: compact))
+                .padding(.bottom, compact ? 4 : 8)
+        }
+        .safeAreaInset(edge: .bottom, alignment: .leading, spacing: 0) {
+            GamepadHintBar(hints: hints)
+                .padding(.leading, 22)
+                .padding(.vertical, compact ? 6 : 10)
+        }
+        .background { GamepadScreenBackground() }
+        .onAppear { discovery.start() }
+        .onDisappear { discovery.stop() }
+        // The settings / add-host screens take over the controller (the carousel's `isActive`
+        // gate above). iOS presents them full screen — the immersive console feel; macOS has no
+        // fullScreenCover, so they become generously sized sheets over the dimmed launcher.
+        #if os(macOS)
+        .sheet(isPresented: $showSettings) {
+            GamepadSettingsView()
+                .frame(width: 720, height: 640)
+        }
+        .sheet(isPresented: $showAddHost) {
+            GamepadAddHostView { store.add($0) }
+                .frame(width: 660, height: 620)
+        }
+        .frame(minWidth: 640, minHeight: 420)
+        #else
+        .fullScreenCover(isPresented: $showSettings) { GamepadSettingsView() }
+        .fullScreenCover(isPresented: $showAddHost) {
+            GamepadAddHostView { store.add($0) }
+        }
+        #endif
+    }
+
+    // MARK: - Hero (carousel + detail), sized to fit the space between the pinned title and hints
+
+    @ViewBuilder private func hero(for size: CGSize) -> some View {
+        let cardWidth = min(340, size.width * 0.84)
+        // 96 ≈ the carousel's own vertical breathing (+40) plus the detail line (~54); clamp so
+        // the strip + detail always fit the region the safe-area insets leave.
+        let cardHeight = min(compact ? 170 : 210, max(118, size.height - 96))
+        VStack(spacing: compact ? 8 : 10) {
+            Spacer(minLength: 0)
+            carousel(cardWidth: cardWidth, cardHeight: cardHeight)
+            detailPanel
+            Spacer(minLength: 0)
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+    }
+
+    // MARK: - Chrome
+
+    private var titleBar: some View {
+        Text("Select a Host")
+            .font(.geist(compact ? 20 : 30, .bold, relativeTo: .title))
+            .foregroundStyle(.white)
+            .frame(maxWidth: .infinity)
+            .overlay(alignment: .trailing) {
+                // Which pad is driving this UI (name + battery) — quiet, and only where there's
+                // room; a compact-height phone gives the pixels to the carousel instead.
+                if !compact, let active = gamepads.active {
+                    ControllerStatusChip(controller: active)
+                        .padding(.trailing, 20)
+                }
+            }
+    }
+
+    // MARK: - Carousel
+
+    private func carousel(cardWidth: CGFloat, cardHeight: CGFloat) -> some View {
+        GamepadCarousel(
+            items: tiles,
+            selection: $selection,
+            itemWidth: cardWidth,
+            spacing: 30,
+            onActivate: { $0.activate() },
+            onSecondary: { openLibraryForSelected() },
+            onTertiary: { showSettings = true },
+            // Stop consuming the controller while another screen is presented on top — otherwise
+            // the launcher navigates behind it (invisibly on iPhone, visibly on iPad's page sheet).
+            isActive: libraryTarget == nil && !showSettings && !showAddHost
+        ) { tile in
+            hostCard(tile, size: CGSize(width: cardWidth, height: cardHeight))
+        }
+        .frame(height: cardHeight + 40)
+    }
+
+    /// The host tile plus its focus treatment. Every continuous visual reads the scroll view's own
+    /// per-frame `phase` (real distance-from-centered), so the look always matches what's on screen
+    /// mid-scroll. `.shadow`/`.overlay` aren't part of `VisualEffect`, so the focus pop is scale +
+    /// brightness/saturation + a depth blur on the recessed neighbors.
+    private func hostCard(_ tile: HomeTile, size: CGSize) -> some View {
+        GamepadHostTile(tile: tile, size: size)
+            .scrollTransition { content, phase in
+                let d = CGFloat(min(abs(phase.value), 1))
+                let scale = 1 - d * 0.12
+                let bright = Double(-d * 0.24)
+                let sat = Double(1 - d * 0.42)
+                let soft = d * 3
+                let fade = Double(1 - d * 0.22)
+                return content
+                    .scaleEffect(scale)
+                    .brightness(bright)
+                    .saturation(sat)
+                    .blur(radius: soft)
+                    .opacity(fade)
+            }
+    }
+
+    /// The "now focused" host, spelled out below the strip — empty (not hidden) so the layout
+    /// doesn't jump as the selection changes.
+    @ViewBuilder private var detailPanel: some View {
+        let tile = tiles.first { $0.id == selection }
+        VStack(spacing: 6) {
+            Text(tile?.title ?? " ")
+                .font(.geist(22, .bold, relativeTo: .title2))
+                .foregroundStyle(.white)
+                .lineLimit(1)
+            HStack(spacing: 10) {
+                Text(tile?.subtitle ?? " ")
+                    .font(.geist(13, relativeTo: .caption))
+                    .foregroundStyle(.white.opacity(0.6))
+                if let tile, tile.showsStatus {
+                    statusPill(online: tile.isOnline, paired: tile.isPaired)
+                }
+            }
+        }
+        .frame(maxWidth: .infinity)
+        .padding(.horizontal, 24)
+        .animation(.smooth(duration: 0.25), value: selection)
+    }
+
+    private func statusPill(online: Bool, paired: Bool) -> some View {
+        HStack(spacing: 6) {
+            Circle()
+                .fill(online ? Color.green : Color.white.opacity(0.35))
+                .frame(width: 6, height: 6)
+            Text(online ? "ONLINE" : "OFFLINE")
+            if paired { Text("· PAIRED") }
+        }
+        .font(.geist(11, .medium, relativeTo: .caption2))
+        .tracking(0.8)
+        .foregroundStyle(.white.opacity(0.55))
+    }
+
+    // MARK: - Hint bar (pinned bottom-leading via safeAreaInset)
+
+    private var hints: [GamepadHint] {
+        let selected = tiles.first { $0.id == selection }
+        var hints = [GamepadHint(
+            glyph: buttonGlyph(\.buttonA, fallback: "a.circle"),
+            text: selected?.id == .addHost ? "Add Host" : "Connect")]
+        if libraryEnabled, selected?.hasLibrary == true {
+            hints.append(.init(glyph: buttonGlyph(\.buttonY, fallback: "y.circle"), text: "Library"))
+        }
+        hints.append(.init(glyph: buttonGlyph(\.buttonX, fallback: "x.circle"), text: "Settings"))
+        return hints
+    }
+
+    // MARK: - Data + actions
+
+    /// Built fresh each render from the live stores (no stale value capture) — saved hosts first,
+    /// then discovered-but-unsaved ones, then the Add Host action tile (so the strip is never
+    /// empty and manual entry is always one press away).
+    private var tiles: [HomeTile] {
+        let saved = store.hosts.map { host in
+            HomeTile(
+                id: .saved(host.id),
+                title: host.displayName,
+                subtitle: "\(host.address):\(String(host.port))",
+                isOnline: discovery.advertises(host),
+                isPaired: host.pinnedSHA256 != nil,
+                isConnecting: model.phase == .connecting && model.activeHost?.id == host.id,
+                filled: true,
+                hasLibrary: true,
+                activate: { connect(host) })
+        }
+        let discovered = discovery.unsaved(among: store.hosts).map { d in
+            HomeTile(
+                id: .discovered(d.id),
+                title: d.name,
+                subtitle: "\(d.host):\(String(d.port))",
+                isOnline: true,
+                activate: { connectDiscovered(d) })
+        }
+        let add = HomeTile(
+            id: .addHost,
+            title: "Add Host",
+            subtitle: "Register a host by address",
+            icon: "plus",
+            showsStatus: false,
+            activate: { showAddHost = true })
+        return saved + discovered + [add]
+    }
+
+    /// Only saved hosts have a library — matches the touch grid, where "Browse Library…" is a
+    /// `HostCardView`-only action never offered on `DiscoveredCardView`.
+    private func openLibraryForSelected() {
+        guard libraryEnabled, case .saved(let id) = selection,
+              let host = store.hosts.first(where: { $0.id == id })
+        else { return }
+        libraryTarget = host
+    }
+}
+
+/// One "console tile" in the host carousel — a dark-glass landscape card, bigger and bolder than the
+/// touch grid's `HostCardView`. Renders only its base look; the centered-tile pop is layered on by
+/// the caller's `.scrollTransition` so it always tracks the real scroll position.
+private struct GamepadHostTile: View {
+    let tile: HomeTile
+    let size: CGSize
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 0) {
+            HStack(alignment: .top) {
+                monogramBadge
+                Spacer(minLength: 0)
+                if tile.isOnline {
+                    Circle()
+                        .fill(Color.green)
+                        .frame(width: 9, height: 9)
+                        .shadow(color: .green.opacity(0.7), radius: 5)
+                }
+            }
+            Spacer(minLength: 0)
+            Text(tile.title)
+                .font(.geist(23, .bold, relativeTo: .title2))
+                .foregroundStyle(.white)
+                .lineLimit(1)
+                .minimumScaleFactor(0.7)
+            Text(tile.subtitle)
+                .font(.geist(13, relativeTo: .caption))
+                .foregroundStyle(.white.opacity(0.55))
+                .lineLimit(1)
+                .padding(.top, 2)
+        }
+        .padding(20)
+        .frame(width: size.width, height: size.height, alignment: .leading)
+        .background {
+            RoundedRectangle(cornerRadius: 26, style: .continuous)
+                .fill(.ultraThinMaterial)
+                .environment(\.colorScheme, .dark)
+        }
+        .overlay {
+            RoundedRectangle(cornerRadius: 26, style: .continuous)
+                .strokeBorder(
+                    LinearGradient(
+                        colors: [.white.opacity(0.22), .white.opacity(0.04)],
+                        startPoint: .top, endPoint: .bottom),
+                    style: StrokeStyle(lineWidth: 1, dash: tile.filled ? [] : [6, 5]))
+        }
+        .clipShape(RoundedRectangle(cornerRadius: 26, style: .continuous))
+        .shadow(color: .black.opacity(0.45), radius: 20, y: 14)
+    }
+
+    private var monogramBadge: some View {
+        let shape = RoundedRectangle(cornerRadius: 15, style: .continuous)
+        return ZStack {
+            shape.fill(tile.filled
+                ? AnyShapeStyle(LinearGradient(
+                    colors: [Color.brand, Color.brand.opacity(0.68)],
+                    startPoint: .top, endPoint: .bottom))
+                : AnyShapeStyle(Color.brand.opacity(0.16)))
+            if tile.isConnecting {
+                ProgressView().tint(.white)
+            } else if let icon = tile.icon {
+                Image(systemName: icon)
+                    .font(.system(size: 24, weight: .semibold))
+                    .foregroundStyle(Color.brand)
+            } else {
+                Text(monogram(tile.title))
+                    .font(.geistFixed(25, .bold))
+                    .foregroundStyle(tile.filled ? .white : Color.brand)
+            }
+        }
+        .frame(width: 52, height: 52)
+        .overlay {
+            if !tile.filled {
+                shape.strokeBorder(Color.brand.opacity(0.5), lineWidth: 1)
+            }
+        }
+    }
+
+    private func monogram(_ name: String) -> String {
+        guard let first = name.trimmingCharacters(in: .whitespacesAndNewlines).first else { return "•" }
+        return String(first).uppercased()
+    }
+}
+#endif

clients/apple/Sources/PunktfunkClient/Home/GamepadKeyboard.swift

@@ -0,0 +1,182 @@
+// A controller-driven on-screen keyboard for the gamepad UI's text fields (iOS/iPadOS only) —
+// iOS has no system keyboard a game controller can drive (the tvOS fullscreen entry doesn't
+// exist here), so without this, adding a host from the couch would end with "now touch the
+// screen". Dpad/stick moves a key cursor over a fixed grid, A types, X backspaces, B/Y confirms.
+// Lowercase + digits + the hostname/address punctuation is deliberately the whole character set:
+// these fields hold names, addresses and ports, not prose.
+//
+// Edits are applied to the binding live (the caller's field row shows every keystroke), so
+// closing the keyboard is always "done" — there is no separate cancel/commit step to get wrong.
+// Touch stays a fallback: every keycap is tappable.
+
+import PunktfunkKit
+import SwiftUI
+#if os(iOS) || os(macOS)
+
+struct GamepadKeyboard: View {
+    @Binding var text: String
+    /// Restricts typed characters (e.g. digits for a port field); backspace always works.
+    var allowed: CharacterSet?
+    /// B / Y / the Done key — the binding already holds the final text.
+    let onDone: () -> Void
+
+    @State private var input = GamepadMenuInput(manager: .shared)
+    @State private var haptics = MenuHaptics(manager: .shared)
+    @State private var cursor = GridPos(row: 1, col: 0) // opens on "q"
+    @State private var pressTick = 0
+    @State private var boundaryTick = 0
+    #if os(iOS)
+    /// `.compact` (landscape phone): shorter keycaps so the tray leaves room for the field rows.
+    @Environment(\.verticalSizeClass) private var vSizeClass
+
+    private var compact: Bool { vSizeClass == .compact }
+    #else
+    private let compact = false // no size classes on macOS; the sheet is sized generously
+    #endif
+
+    private struct GridPos: Hashable {
+        var row: Int
+        var col: Int
+    }
+
+    private enum Key: Hashable {
+        case char(Character)
+        case space
+        case backspace
+        case done
+    }
+
+    /// Digits first (addresses/ports), then letters; the last char column carries the
+    /// hostname/address punctuation.
+    private static let rows: [[Key]] = [
+        Array("1234567890").map(Key.char),
+        Array("qwertyuiop").map(Key.char),
+        Array("asdfghjkl-").map(Key.char),
+        Array("zxcvbnm._:").map(Key.char),
+        [.space, .backspace, .done],
+    ]
+
+    var body: some View {
+        VStack(spacing: compact ? 5 : 7) {
+            ForEach(Self.rows.indices, id: \.self) { r in
+                HStack(spacing: compact ? 5 : 7) {
+                    ForEach(Self.rows[r].indices, id: \.self) { c in
+                        keycap(Self.rows[r][c], focused: cursor == GridPos(row: r, col: c))
+                            .onTapGesture {
+                                cursor = GridPos(row: r, col: c)
+                                press(Self.rows[r][c])
+                            }
+                    }
+                }
+            }
+        }
+        .frame(maxWidth: 560)
+        .padding(compact ? 10 : 14)
+        .background {
+            RoundedRectangle(cornerRadius: 22, style: .continuous)
+                .fill(.ultraThinMaterial)
+                .environment(\.colorScheme, .dark)
+        }
+        .overlay {
+            RoundedRectangle(cornerRadius: 22, style: .continuous)
+                .strokeBorder(.white.opacity(0.12), lineWidth: 1)
+        }
+        .sensoryFeedback(.selection, trigger: cursor)
+        .sensoryFeedback(.impact(weight: .light), trigger: pressTick)
+        .sensoryFeedback(.impact(flexibility: .rigid, intensity: 0.7), trigger: boundaryTick)
+        .onAppear {
+            wire()
+            input.start()
+        }
+        .onDisappear {
+            input.stop()
+            haptics.stop()
+        }
+    }
+
+    // MARK: - Keycaps
+
+    @ViewBuilder private func keycap(_ key: Key, focused: Bool) -> some View {
+        Group {
+            switch key {
+            case .char(let c):
+                Text(String(c)).font(.geistFixed(18, .medium))
+            case .space:
+                Image(systemName: "space")
+            case .backspace:
+                Image(systemName: "delete.left")
+            case .done:
+                Label("Done", systemImage: "checkmark")
+                    .font(.geist(15, .semibold, relativeTo: .callout))
+            }
+        }
+        .foregroundStyle(focused ? Color.black : .white)
+        .frame(maxWidth: .infinity, minHeight: compact ? 34 : 42)
+        .background {
+            RoundedRectangle(cornerRadius: 9, style: .continuous)
+                .fill(focused ? AnyShapeStyle(Color.brand) : AnyShapeStyle(.white.opacity(0.08)))
+        }
+        .animation(.smooth(duration: 0.12), value: focused)
+        .contentShape(Rectangle())
+    }
+
+    // MARK: - Input
+
+    private func wire() {
+        input.onMove = { move($0) }
+        input.onConfirm = { press(Self.rows[cursor.row][cursor.col]) }
+        input.onTertiary = { press(.backspace) }
+        input.onSecondary = onDone
+        input.onBack = onDone
+    }
+
+    private func move(_ direction: GamepadMenuInput.Direction) {
+        var next = cursor
+        switch direction {
+        case .left: next.col -= 1
+        case .right: next.col += 1
+        case .up, .down:
+            let row = cursor.row + (direction == .down ? 1 : -1)
+            guard row >= 0, row < Self.rows.count else { return refuse() }
+            // Map the column proportionally between rows of different widths, so e.g. Done
+            // (rightmost of 3) goes up to the rightmost letters, not to "e".
+            let from = max(1, Self.rows[cursor.row].count - 1)
+            let to = Self.rows[row].count - 1
+            next = GridPos(
+                row: row,
+                col: Int((Double(cursor.col) * Double(to) / Double(from)).rounded()))
+        }
+        guard next.row >= 0, next.row < Self.rows.count,
+              next.col >= 0, next.col < Self.rows[next.row].count
+        else { return refuse() }
+        cursor = next
+        haptics.move()
+    }
+
+    private func press(_ key: Key) {
+        switch key {
+        case .char(let c):
+            if let allowed, !c.unicodeScalars.allSatisfy(allowed.contains) { return refuse() }
+            text.append(c)
+        case .space:
+            if let allowed, !allowed.contains(" ") { return refuse() }
+            text.append(" ")
+        case .backspace:
+            guard !text.isEmpty else { return refuse() }
+            text.removeLast()
+        case .done:
+            haptics.confirm()
+            onDone()
+            return
+        }
+        pressTick &+= 1
+        haptics.move()
+    }
+
+    /// Refused input (edge of the grid, a disallowed character, deleting nothing).
+    private func refuse() {
+        boundaryTick &+= 1
+        haptics.boundary()
+    }
+}
+#endif

clients/apple/Sources/PunktfunkClient/Home/GamepadMenuList.swift

@@ -0,0 +1,178 @@
+// The vertical sibling of GamepadCarousel (iOS/iPadOS/macOS): a controller-driven focus list for
+// the gamepad UI's form-like screens (GamepadSettingsView, GamepadAddHostView). Up/down moves a
+// focus bar through the rows, left/right adjusts the focused row's value, A activates it, B backs
+// out. The CALLER owns each row's look (it gets the focused flag); this component owns the focus
+// cursor, controller polling, haptics, and keeping the focused row scrolled into view.
+//
+// Unlike the carousel there is no snapping and no `.scrollPosition` two-way binding to fight: the
+// cursor is plainly authoritative, the scroll view just chases it with `scrollTo`. Touch stays a
+// first-class fallback — tapping a row focuses AND activates it (rows are always fully visible, so
+// the carousel's "first tap re-centers" step would only add friction here), and free finger
+// scrolling is never hijacked back to the focused row until the next controller move.
+//
+// Feedback is dual-channel like the carousel: `.sensoryFeedback` ticks the DEVICE Taptic engine,
+// `MenuHaptics` ticks the CONTROLLER. Moves and value changes get the crisp detent; a refused
+// move at either end gets the dull boundary thud plus a short vertical recoil.
+
+import PunktfunkKit
+import SwiftUI
+#if os(iOS) || os(macOS)
+
+struct GamepadMenuList<Item: Identifiable, Row: View>: View where Item.ID: Hashable {
+    let items: [Item]
+    /// Output only: the list WRITES the focused item's id here (e.g. for a caller's hint bar).
+    @Binding var focusID: Item.ID?
+    /// Left/right on the focused row. Return whether the value actually changed — true plays the
+    /// move detent, false the boundary thud (end of a clamped range, or nothing to adjust).
+    var onAdjust: ((Item, Int) -> Bool)?
+    /// A → activate the focused row (toggle it, open it, run it — the caller decides).
+    let onActivate: (Item) -> Void
+    /// B → back/dismiss; nil disables it.
+    var onBack: (() -> Void)?
+    /// Whether this list currently owns controller input — same handoff contract as
+    /// GamepadCarousel's `isActive` (a covered screen must stop polling the shared pad).
+    var isActive: Bool = true
+    @ViewBuilder let row: (Item, _ focused: Bool) -> Row
+
+    @State private var input = GamepadMenuInput(manager: .shared)
+    @State private var haptics = MenuHaptics(manager: .shared)
+    /// Authoritative focus cursor (index into `items`).
+    @State private var cursor = 0
+    /// A short vertical recoil when a move is refused at a list end.
+    @State private var bumpOffset: CGFloat = 0
+    /// `.sensoryFeedback` counters (see GamepadCarousel): device ticks for activate / value-change
+    /// / end-stop events; moves trigger on `cursor` itself.
+    @State private var activateTick = 0
+    @State private var adjustTick = 0
+    @State private var boundaryTick = 0
+
+    var body: some View {
+        ScrollViewReader { proxy in
+            ScrollView(.vertical) {
+                LazyVStack(spacing: 6) {
+                    ForEach(Array(items.enumerated()), id: \.element.id) { idx, item in
+                        row(item, idx == cursor && isActive)
+                            .contentShape(Rectangle())
+                            .onTapGesture { tap(idx) }
+                            .id(item.id)
+                    }
+                }
+                .padding(.vertical, 10)
+            }
+            // .never, not .hidden — macOS's "always show scroll bars" setting overrides .hidden.
+            .scrollIndicators(.never)
+            .offset(y: bumpOffset)
+            .onChange(of: cursor) { _, newValue in
+                guard newValue >= 0, newValue < items.count else { return }
+                withAnimation(.easeOut(duration: 0.2)) {
+                    proxy.scrollTo(items[newValue].id)
+                }
+            }
+        }
+        .sensoryFeedback(.selection, trigger: cursor)
+        .sensoryFeedback(.selection, trigger: adjustTick)
+        .sensoryFeedback(.impact(weight: .medium), trigger: activateTick)
+        .sensoryFeedback(.impact(flexibility: .rigid, intensity: 0.7), trigger: boundaryTick)
+        .onAppear {
+            reconcile()
+            wire()
+            if isActive { input.start() }
+        }
+        .onDisappear {
+            input.stop()
+            haptics.stop()
+        }
+        .onChange(of: isActive) { _, active in
+            if active {
+                wire()
+                input.start()
+            } else {
+                input.stop()
+                haptics.stop()
+            }
+        }
+        // Re-seed a dropped focus AND re-wire the input callbacks so they capture the current
+        // `items` value (a plain array — it would otherwise go stale in the stored closures).
+        .onChange(of: items.map(\.id)) { _, _ in
+            reconcile()
+            wire()
+        }
+    }
+
+    // MARK: - Input wiring
+
+    private func wire() {
+        input.onMove = { direction in
+            switch direction {
+            case .up: step(by: -1)
+            case .down: step(by: 1)
+            case .left: adjust(by: -1)
+            case .right: adjust(by: 1)
+            }
+        }
+        input.onConfirm = { activate() }
+        input.onBack = onBack
+    }
+
+    private func step(by delta: Int) {
+        guard !items.isEmpty else { return }
+        let target = cursor + delta
+        guard target >= 0, target < items.count else { return boundaryBump(forward: delta > 0) }
+        cursor = target
+        focusID = items[target].id
+        haptics.move()
+    }
+
+    private func adjust(by delta: Int) {
+        guard let onAdjust, cursor >= 0, cursor < items.count else { return }
+        if onAdjust(items[cursor], delta) {
+            adjustTick &+= 1
+            haptics.move()
+        } else {
+            boundaryTick &+= 1
+            haptics.boundary()
+        }
+    }
+
+    private func activate() {
+        guard cursor >= 0, cursor < items.count else { return }
+        activateTick &+= 1
+        haptics.confirm()
+        onActivate(items[cursor])
+    }
+
+    /// Touch fallback: a tap focuses the row and activates it in one go.
+    private func tap(_ idx: Int) {
+        guard idx >= 0, idx < items.count else { return }
+        if cursor != idx {
+            cursor = idx
+            focusID = items[idx].id
+        }
+        activate()
+    }
+
+    /// Keep `cursor`/`focusID` consistent with `items`: seed on appear; on a list change keep the
+    /// same focused item when it survives, else clamp the cursor into range.
+    private func reconcile() {
+        guard !items.isEmpty else {
+            cursor = 0
+            if focusID != nil { focusID = nil }
+            return
+        }
+        if let id = focusID, let idx = items.firstIndex(where: { $0.id == id }) {
+            cursor = idx
+        } else {
+            cursor = min(max(cursor, 0), items.count - 1)
+            focusID = items[cursor].id
+        }
+    }
+
+    private func boundaryBump(forward: Bool) {
+        boundaryTick &+= 1
+        haptics.boundary()
+        let recoil: CGFloat = forward ? -14 : 14
+        withAnimation(.spring(response: 0.16, dampingFraction: 0.42)) { bumpOffset = recoil }
+        withAnimation(.spring(response: 0.34, dampingFraction: 0.7).delay(0.1)) { bumpOffset = 0 }
+    }
+}
+#endif

clients/apple/Sources/PunktfunkClient/Home/HomeView.swift

@@ -127,28 +127,16 @@ struct HomeView: View {
             AddHostSheet { store.add($0) }
         }
         #if os(iOS)
+        // SettingsView owns its own NavigationSplitView (sidebar + detail) and Done button, so it
+        // is presented directly — wrapping it in a NavigationStack here would nest a split view in
+        // a stack (double title bars). `settingsSheetSizing()` widens the sheet on iPad for the
+        // two-column layout.
         .sheet(isPresented: $showSettings) {
-            NavigationStack {
-                SettingsView()
-                    .navigationTitle("Settings")
-                    .toolbar {
-                        Button("Done") { showSettings = false }
-                    }
-            }
+            SettingsView()
+                .settingsSheetSizing()
         }
         #endif
         #endif
-        .alert(
-            "Connection failed",
-            isPresented: Binding(
-                get: { model.errorMessage != nil },
-                set: { if !$0 { model.errorMessage = nil } }
-            )
-        ) {
-            Button("OK", role: .cancel) {}
-        } message: {
-            Text(model.errorMessage ?? "")
-        }
     }
 
     // MARK: - Cards
@@ -157,7 +145,7 @@ struct HomeView: View {
         let onBrowseLibrary: (() -> Void)? = libraryEnabled ? { libraryTarget = host } : nil
         return HostCardView(
             host: host,
-            isOnline: isOnline(host),
+            isOnline: discovery.advertises(host),
             isConnecting: model.phase == .connecting && model.activeHost?.id == host.id,
             isMostRecent: host.id == mostRecentHostID,
             isBusy: model.isBusy,
@@ -166,13 +154,20 @@ struct HomeView: View {
             onSpeedTest: { if !model.isBusy { speedTestTarget = host } },
             onForget: { store.forgetIdentity(host) },
             onRemove: { store.remove(host) },
-            onBrowseLibrary: onBrowseLibrary)
+            onBrowseLibrary: onBrowseLibrary,
+            onWake: {
+                let macs = host.wakeMacs
+                let ip = host.address
+                DispatchQueue.global(qos: .userInitiated).async {
+                    PunktfunkConnection.wakeOnLAN(macs: macs, lastKnownIP: ip)
+                }
+            })
     }
 
     private var discoveredSection: some View {
         VStack(alignment: .leading, spacing: 10) {
             Label("On this network", systemImage: "antenna.radiowaves.left.and.right")
-                .font(.headline)
+                .font(.geist(15, .semibold, relativeTo: .headline))
                 .foregroundStyle(.secondary)
                 .padding(.horizontal)
             LazyVGrid(columns: gridColumns, spacing: gridSpacing) {
@@ -187,18 +182,10 @@ struct HomeView: View {
         .padding(.top, store.hosts.isEmpty ? 0 : 8)
     }
 
-    /// A saved host is "online" iff a live mDNS advert currently matches it (see
-    /// `StoredHost.matches`). Recomputed on every discovery change (the @Published set), so the
-    /// dot tracks hosts appearing/leaving the network live.
-    private func isOnline(_ host: StoredHost) -> Bool {
-        discovery.hosts.contains { host.matches($0) }
-    }
-
-    /// Discovered hosts not already saved — the saved grid shows the rest, so this section only
-    /// surfaces genuinely-new hosts on the network. Same match as the online dot, so a saved host
-    /// whose IP changed (still fingerprint-matched) doesn't also appear here as a stranger.
+    /// Discovered hosts not already saved (see `HostDiscovery.unsaved` — shared with the gamepad
+    /// launcher so both screens classify hosts identically).
     private var discoveredUnsaved: [DiscoveredHost] {
-        discovery.hosts.filter { d in !store.hosts.contains { $0.matches(d) } }
+        discovery.unsaved(among: store.hosts)
     }
 
     /// The host of the most recent session — its card carries the accent ring.
@@ -249,8 +236,10 @@ struct HomeView: View {
     /// the width so the cards stay edge-aligned with the title and bars — sized touch-first: one
     /// column on iPhone portrait, 3–4 generous cards on iPad.
     private var gridColumns: [GridItem] {
+        // Wider than before: the monogram card is a horizontal module (tile + address line), so
+        // it needs room for a monospaced "IP:port" without truncating.
         #if os(macOS)
-        [GridItem(.adaptive(minimum: 180, maximum: 240), spacing: 16)]
+        [GridItem(.adaptive(minimum: 250, maximum: 320), spacing: 16)]
         #elseif os(tvOS)
         [GridItem(.adaptive(minimum: 320), spacing: 48)]
         #else

clients/apple/Sources/PunktfunkClient/Home/HostCards.swift

@@ -0,0 +1,261 @@
+// The host grid's cards: a saved host (tap to connect, context menu) and an mDNS-discovered
+// host (tap to save + connect). Both share the "monogram module" look — a squared brand-purple
+// monogram tile + a left-aligned bold Geist name over monospaced technical metadata
+// (address, status), framed by a hairline panel border. Industrial, not soft.
+
+import PunktfunkKit
+import SwiftUI
+
+/// Shared host-card sizing — touch-first on iOS, compact on macOS, roomy on tvOS.
+private struct CardMetrics {
+    let tile: CGFloat       // monogram tile side
+    let monogram: CGFloat   // monogram letter point size
+    let name: CGFloat       // host-name point size
+    let meta: CGFloat       // address (mono) point size
+    let status: CGFloat     // status-label (mono) point size
+    let padding: CGFloat
+    let spacing: CGFloat    // tile ↔ text gap
+    let radius: CGFloat
+
+    static var current: CardMetrics {
+        #if os(iOS)
+        CardMetrics(tile: 54, monogram: 26, name: 19, meta: 13, status: 11,
+                    padding: 16, spacing: 14, radius: 12)
+        #elseif os(tvOS)
+        CardMetrics(tile: 64, monogram: 32, name: 24, meta: 16, status: 14,
+                    padding: 18, spacing: 18, radius: 14)
+        #else
+        CardMetrics(tile: 44, monogram: 21, name: 15, meta: 12, status: 10.5,
+                    padding: 13, spacing: 12, radius: 10)
+        #endif
+    }
+}
+
+/// First letter of a host name, uppercased — the monogram glyph. Falls back to a bullet.
+private func monogram(_ name: String) -> String {
+    guard let first = name.trimmingCharacters(in: .whitespacesAndNewlines).first else { return "•" }
+    return String(first).uppercased()
+}
+
+/// The squared monogram tile. `filled` = a solid brand-purple chip (saved hosts); otherwise a
+/// tinted outline (discovered hosts). Shows a spinner in place of the glyph while connecting.
+private func monogramTile(_ letter: String, m: CardMetrics, connecting: Bool, filled: Bool) -> some View {
+    let shape = RoundedRectangle(cornerRadius: m.radius - 3, style: .continuous)
+    return ZStack {
+        shape.fill(filled
+            ? AnyShapeStyle(LinearGradient(
+                colors: [Color.brand, Color.brand.opacity(0.72)],
+                startPoint: .top, endPoint: .bottom))
+            : AnyShapeStyle(Color.brand.opacity(0.14)))
+        if connecting {
+            ProgressView().tint(filled ? .white : Color.brand)
+        } else {
+            // Fixed size (not Dynamic Type): the glyph is pinned inside a fixed tile, so it must
+            // not scale up and spill out at large accessibility text sizes. minimumScaleFactor +
+            // the clip below are belt-and-suspenders for an unusually wide glyph.
+            Text(letter)
+                .font(.geistFixed(m.monogram, .bold))
+                .minimumScaleFactor(0.5)
+                .lineLimit(1)
+                .foregroundStyle(filled ? Color.white : Color.brand)
+        }
+    }
+    .frame(width: m.tile, height: m.tile)
+    .clipShape(shape)
+    .overlay {
+        if !filled {
+            shape.strokeBorder(Color.brand.opacity(0.45), lineWidth: 1)
+        }
+    }
+}
+
+/// A saved host. A left accent bar marks the most-recently-connected one; the context menu
+/// pairs / speed-tests / forgets / removes. Disabled while a session is busy.
+struct HostCardView: View {
+    let host: StoredHost
+    /// Currently advertising on the LAN (matched against live mDNS discovery). False means
+    /// "not seen on this network" — off, or a remote/cross-subnet host we can't observe.
+    let isOnline: Bool
+    let isConnecting: Bool
+    let isMostRecent: Bool
+    let isBusy: Bool
+    let onConnect: () -> Void
+    let onPair: () -> Void
+    let onSpeedTest: () -> Void
+    let onForget: () -> Void
+    let onRemove: () -> Void
+    /// Open the experimental library browser — nil (no menu item) unless the feature flag is on.
+    var onBrowseLibrary: (() -> Void)? = nil
+    /// Send a Wake-on-LAN magic packet. Shown only when the host is offline and we have a stored
+    /// MAC to target (a tap-to-connect already auto-wakes; this is the explicit "just wake it").
+    var onWake: (() -> Void)? = nil
+
+    var body: some View {
+        let m = CardMetrics.current
+        return Button(action: onConnect) {
+            HStack(spacing: m.spacing) {
+                monogramTile(monogram(host.displayName), m: m, connecting: isConnecting, filled: true)
+                VStack(alignment: .leading, spacing: 4) {
+                    Text(host.displayName)
+                        .font(.geist(m.name, .bold, relativeTo: .title3))
+                        .foregroundStyle(.primary)
+                        .lineLimit(1)
+                    Text("\(host.address):\(String(host.port))")
+                        .font(.geist(m.meta, relativeTo: .caption))
+                        .foregroundStyle(.secondary)
+                        .lineLimit(1)
+                    statusRow(m)
+                }
+                Spacer(minLength: 0)
+            }
+            .padding(m.padding)
+            .frame(maxWidth: .infinity, alignment: .leading)
+            #if !os(tvOS)
+            // tvOS: the .card button style owns platter + focus motion; extra chrome mutes it.
+            // Elsewhere: a flat material panel with a hairline border (industrial, not a soft blob),
+            // and a brand accent bar down the leading edge for the most-recent host.
+            .background(.regularMaterial)
+            .overlay(alignment: .leading) {
+                if isMostRecent {
+                    Rectangle().fill(Color.brand).frame(width: 3)
+                }
+            }
+            .clipShape(RoundedRectangle(cornerRadius: m.radius, style: .continuous))
+            .overlay {
+                RoundedRectangle(cornerRadius: m.radius, style: .continuous)
+                    .strokeBorder(.quaternary, lineWidth: 1)
+            }
+            #endif
+        }
+        #if os(tvOS)
+        .buttonStyle(.card)
+        #elseif os(iOS)
+        .buttonStyle(HostCardButtonStyle(cornerRadius: m.radius))
+        #else
+        .buttonStyle(.plain)
+        #endif
+        .disabled(isBusy)
+        .contextMenu {
+            Button("Pair with PIN…", action: onPair)
+            Button("Test Network Speed…", action: onSpeedTest)
+            if let onBrowseLibrary {
+                Button("Browse Library…", action: onBrowseLibrary)
+            }
+            if !isOnline, !host.wakeMacs.isEmpty, PunktfunkConnection.wakeOnLANAvailable, let onWake {
+                Button("Wake Host", systemImage: "power", action: onWake)
+            }
+            if host.pinnedSHA256 != nil {
+                // Dropping the pin does NOT downgrade to TOFU: the next connect must re-pair via
+                // PIN (unless the host advertises pair=optional). Wording reflects that.
+                Button("Forget Identity (re-pair to reconnect)", action: onForget)
+            }
+            Button("Remove", role: .destructive, action: onRemove)
+        }
+    }
+
+    /// Technical status line: a square presence pip + monospaced ONLINE/OFFLINE, and PAIRED when a
+    /// certificate is pinned (the lock state, spelled out).
+    @ViewBuilder private func statusRow(_ m: CardMetrics) -> some View {
+        HStack(spacing: 6) {
+            RoundedRectangle(cornerRadius: 1.5)
+                .fill(isOnline ? Color.green : Color.secondary.opacity(0.4))
+                .frame(width: 6, height: 6)
+                // The state is spelled out in the adjacent text, so the pip is decorative —
+                // otherwise VoiceOver reads the status twice ("Online, ONLINE …").
+                .accessibilityHidden(true)
+            Text(isOnline ? "ONLINE" : "OFFLINE")
+            if host.pinnedSHA256 != nil {
+                Text("· PAIRED")
+            }
+        }
+        .font(.geist(m.status, .medium, relativeTo: .caption2))
+        .tracking(0.8)
+        .foregroundStyle(.secondary)
+        .lineLimit(1)
+    }
+}
+
+/// A host found on the LAN but not yet saved. A tinted-outline monogram + dashed panel border
+/// distinguish it from saved cards; tapping saves it and connects (or pairs, if required).
+struct DiscoveredCardView: View {
+    let discovered: DiscoveredHost
+    let isBusy: Bool
+    let onConnect: () -> Void
+
+    var body: some View {
+        let m = CardMetrics.current
+        return Button(action: onConnect) {
+            HStack(spacing: m.spacing) {
+                monogramTile(monogram(discovered.name), m: m, connecting: false, filled: false)
+                VStack(alignment: .leading, spacing: 4) {
+                    Text(discovered.name)
+                        .font(.geist(m.name, .bold, relativeTo: .title3))
+                        .foregroundStyle(.primary)
+                        .lineLimit(1)
+                    Text("\(discovered.host):\(String(discovered.port))")
+                        .font(.geist(m.meta, relativeTo: .caption))
+                        .foregroundStyle(.secondary)
+                        .lineLimit(1)
+                    HStack(spacing: 6) {
+                        Image(systemName: discovered.requiresPairing
+                            ? "lock.fill" : "antenna.radiowaves.left.and.right")
+                            .font(.system(size: m.status))
+                            .accessibilityHidden(true) // decorative; the adjacent text says the state
+                        Text(discovered.requiresPairing ? "PAIRING REQUIRED" : "DISCOVERED")
+                    }
+                    .font(.geist(m.status, .medium, relativeTo: .caption2))
+                    .tracking(0.8)
+                    .foregroundStyle(.secondary)
+                    .lineLimit(1)
+                }
+                Spacer(minLength: 0)
+            }
+            .padding(m.padding)
+            .frame(maxWidth: .infinity, alignment: .leading)
+            #if !os(tvOS)
+            .background(.regularMaterial)
+            .clipShape(RoundedRectangle(cornerRadius: m.radius, style: .continuous))
+            .overlay {
+                RoundedRectangle(cornerRadius: m.radius, style: .continuous)
+                    .strokeBorder(
+                        Color.secondary.opacity(0.3),
+                        style: StrokeStyle(lineWidth: 1, dash: [4, 3]))
+            }
+            #endif
+        }
+        #if os(tvOS)
+        .buttonStyle(.card)
+        #elseif os(iOS)
+        .buttonStyle(HostCardButtonStyle(cornerRadius: m.radius))
+        #else
+        .buttonStyle(.plain)
+        #endif
+        .disabled(isBusy)
+    }
+}
+
+#if os(iOS)
+/// The iOS host-card press/hover treatment, one style for both idioms:
+/// - iPhone: a subtle scale-down on press + a light impact haptic on press-down. (`hoverEffect` is
+///   inert without a pointer.)
+/// - iPad: the system pointer "magnet" — the cursor morphs into a highlight that conforms to the
+///   card's rounded rect on hover. (`sensoryFeedback` is inert without a Taptic Engine, and the
+///   press scale doubles as click feedback.)
+struct HostCardButtonStyle: ButtonStyle {
+    var cornerRadius: CGFloat
+
+    func makeBody(configuration: Configuration) -> some View {
+        configuration.label
+            .scaleEffect(configuration.isPressed ? 0.96 : 1)
+            .animation(.spring(response: 0.3, dampingFraction: 0.65), value: configuration.isPressed)
+            // Conform the pointer highlight to the card's rounded rect, not its square bounds.
+            .contentShape(.hoverEffect, RoundedRectangle(cornerRadius: cornerRadius, style: .continuous))
+            .hoverEffect(.highlight)
+            // Light tap on press-down (nil on release so it fires once, on touch). No haptic
+            // hardware on iPad → silently ignored there.
+            .sensoryFeedback(trigger: configuration.isPressed) { _, pressed in
+                pressed ? .impact(weight: .light) : nil
+            }
+    }
+}
+#endif

clients/apple/Sources/PunktfunkClient/Home/LibraryCoverflowView.swift

@@ -0,0 +1,148 @@
+// The gamepad-driven presentation of the game library (iOS/iPadOS/macOS — see LibraryView's
+// `gamepadUIActive` branch): a classic coverflow instead of the touch grid. All the
+// scrolling/snapping/navigation/haptics live in GamepadCarousel; this file is the coverflow card
+// (poster + the 3D recede treatment via `.scrollTransition`), the "now focused" detail panel, and
+// the controller-glyph hints. A steps through covers, A launches the centered title, B closes, and
+// the shoulders (L1/R1) jump a handful at a time through a long library.
+//
+// Layout discipline (so nothing is EVER clipped, portrait or landscape): the gradient is a
+// `.background` modifier — NOT a ZStack sibling — because an `.ignoresSafeArea()` sibling expands the
+// stack to full-screen and hands the GeometryReader the full height, laying content out under the
+// status bar / home indicator. As a background it draws behind without affecting layout, so the
+// GeometryReader is sized to the safe area, and the controller-glyph hints are pinned inside it with
+// `.safeAreaInset(.bottom, alignment: .leading)`. Cover size is then derived from the height that
+// remains, so a tall 2:3 poster + the detail line always fit.
+
+import PunktfunkKit
+import SwiftUI
+#if os(iOS) || os(macOS)
+import GameController
+
+struct LibraryCoverflowView: View {
+    let games: [GameEntry]
+    let imageSession: URLSession?
+    var onLaunch: ((String) -> Void)?
+    /// Button B (back) — dismisses the library screen. No touch equivalent needed here (the toolbar
+    /// Close button already covers that); this is what makes gamepad-only exit possible.
+    var onDismiss: (() -> Void)?
+
+    #if os(iOS)
+    /// `.compact` in a landscape phone window — drives a tighter poster so everything still fits.
+    @Environment(\.verticalSizeClass) private var vSizeClass
+
+    private var compact: Bool { vSizeClass == .compact }
+    #else
+    private let compact = false // no size classes on macOS
+    #endif
+    @State private var selection: String?
+
+    var body: some View {
+        GeometryReader { geo in
+            content(for: geo.size)
+        }
+        .safeAreaInset(edge: .bottom, alignment: .leading, spacing: 0) {
+            GamepadHintBar(hints: hints)
+                .padding(.leading, 22)
+                .padding(.vertical, compact ? 6 : 10)
+        }
+        .background { GamepadScreenBackground() }
+    }
+
+    @ViewBuilder private func content(for size: CGSize) -> some View {
+        // Fit the tallest poster into the height the detail line + paddings leave (the hints are a
+        // safe-area inset, already out of this budget) — capped so it never dwarfs a large iPad and
+        // clamped by width on a narrow screen.
+        let reserved: CGFloat = compact ? 72 : 96 // detail line + spacers
+        let coverHeight = min(360, min(max(140, size.height - reserved), size.width * 0.9))
+        let coverWidth = coverHeight * 2 / 3
+
+        VStack(spacing: 0) {
+            Spacer(minLength: 4)
+            carousel(coverWidth: coverWidth, coverHeight: coverHeight)
+            detailPanel
+                .padding(.top, 12)
+            Spacer(minLength: 4)
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+    }
+
+    private func carousel(coverWidth: CGFloat, coverHeight: CGFloat) -> some View {
+        GamepadCarousel(
+            items: games,
+            selection: $selection,
+            itemWidth: coverWidth,
+            spacing: 34,
+            onActivate: { onLaunch?($0.id) },
+            onBack: { onDismiss?() },
+            shoulderJump: 5
+        ) { game in
+            cover(game, width: coverWidth, height: coverHeight)
+        }
+        .frame(height: coverHeight + 44)
+    }
+
+    /// One cover + the coverflow recede. Every continuous visual reads the scroll view's own
+    /// per-frame `phase` (real distance-from-centered), so the tilt tracks what's actually on screen
+    /// mid-scroll. `.shadow` isn't a `VisualEffect`, so it's baked constant into the card; the
+    /// scale/rotation/opacity ramp already makes the centered cover prominent.
+    private func cover(_ game: GameEntry, width: CGFloat, height: CGFloat) -> some View {
+        PosterImage(candidates: game.art.posterCandidates, title: game.title, session: imageSession)
+            .frame(width: width, height: height)
+            .clipShape(RoundedRectangle(cornerRadius: 16, style: .continuous))
+            .overlay(alignment: .topLeading) { StoreBadge(isCustom: game.isCustom) }
+            .overlay {
+                RoundedRectangle(cornerRadius: 16, style: .continuous)
+                    .strokeBorder(.white.opacity(0.12), lineWidth: 1)
+            }
+            .shadow(color: .black.opacity(0.5), radius: 16, y: 12)
+            .scrollTransition { content, phase in
+                let v = phase.value
+                let d = CGFloat(min(abs(v), 1))
+                let scale = 1 - d * 0.24
+                let rot = v * -38
+                let anchor: UnitPoint = v < 0 ? .trailing : .leading
+                let bright = Double(-d * 0.22)
+                let fade = Double(1 - d * 0.38)
+                return content
+                    .scaleEffect(scale)
+                    .rotation3DEffect(
+                        .degrees(rot), axis: (x: 0, y: 1, z: 0), anchor: anchor, perspective: 0.55)
+                    .brightness(bright)
+                    .opacity(fade)
+            }
+    }
+
+    /// The centered title + store tag — empty (not hidden) so the layout doesn't jump.
+    @ViewBuilder private var detailPanel: some View {
+        let game = games.first { $0.id == selection }
+        VStack(spacing: 6) {
+            Text(game?.title ?? " ")
+                .font(.geist(compact ? 22 : 25, .bold, relativeTo: .title))
+                .foregroundStyle(.white)
+                .lineLimit(1)
+                .minimumScaleFactor(0.75)
+                .multilineTextAlignment(.center)
+            if let game {
+                Text(game.isCustom ? "CUSTOM" : "STEAM")
+                    .font(.geist(11, .semibold, relativeTo: .caption2))
+                    .tracking(1.2)
+                    .foregroundStyle(.white.opacity(0.5))
+            }
+        }
+        .frame(maxWidth: .infinity)
+        .padding(.horizontal, 24)
+        .animation(.smooth(duration: 0.25), value: selection)
+    }
+
+    // MARK: - Hint bar (pinned bottom-leading via safeAreaInset)
+
+    private var hints: [GamepadHint] {
+        var hints: [GamepadHint] = []
+        if onLaunch != nil {
+            hints.append(.init(glyph: buttonGlyph(\.buttonA, fallback: "a.circle"), text: "Launch"))
+        }
+        hints.append(.init(glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Close"))
+        return hints
+    }
+}
+#endif

clients/apple/Sources/PunktfunkClient/Home/LibraryView.swift

@@ -12,10 +12,25 @@ struct LibraryView: View {
     /// Tapping a title starts a session that asks the host to launch it (the library id is passed
     /// through). `nil` ⇒ browse-only (cards aren't tappable).
     var onLaunch: ((String) -> Void)? = nil
+    @Environment(\.dismiss) private var dismiss
 
     @State private var games: [GameEntry] = []
     @State private var loading = false
     @State private var errorText: String?
+    /// Authenticated session for cover-art fetches (the same paired identity + host pinning as the
+    /// list fetch, reused across every poster in the grid). Built alongside `games` in `load()`;
+    /// torn down on disappear since it isn't one-shot like `LibraryClient.fetch`'s own session.
+    @State private var imageSession: URLSession?
+    #if os(iOS) || os(macOS)
+    // Gamepad-driven browsing (iOS/iPadOS/macOS) — see ContentView's identical gate. tvOS keeps
+    // its existing plain-grid presentation of this same view unchanged.
+    @ObservedObject private var gamepadManager = GamepadManager.shared
+    @AppStorage(DefaultsKey.gamepadUIEnabled) private var gamepadUIEnabled = true
+    private var gamepadUIActive: Bool {
+        GamepadUIEnvironment.isActive(
+            gamepadConnected: gamepadManager.active != nil, enabledSetting: gamepadUIEnabled)
+    }
+    #endif
 
     var body: some View {
         content
@@ -29,8 +44,20 @@ struct LibraryView: View {
                 #else
                 ToolbarItem(placement: .primaryAction) { reloadButton }
                 #endif
+                // A gamepad-only user can't swipe-to-dismiss the sheet this view is presented in
+                // (ContentView's `.sheet(item: $libraryTarget)`) — give it a focusable, dpad-reachable
+                // Close action. tvOS already has its own pushed-navigation back (Menu button).
+                #if !os(tvOS)
+                ToolbarItem(placement: .cancellationAction) {
+                    Button("Close") { dismiss() }
+                }
+                #endif
             }
             .task { await load() }
+            .onDisappear {
+                imageSession?.finishTasksAndInvalidate()
+                imageSession = nil
+            }
     }
 
     @ViewBuilder private var content: some View {
@@ -42,7 +69,17 @@ struct LibraryView: View {
         } else if games.isEmpty {
             emptyState
         } else {
+            #if os(iOS) || os(macOS)
+            if gamepadUIActive {
+                LibraryCoverflowView(
+                    games: games, imageSession: imageSession, onLaunch: onLaunch,
+                    onDismiss: { dismiss() })
+            } else {
+                grid
+            }
+            #else
             grid
+            #endif
         }
     }
 
@@ -51,10 +88,10 @@ struct LibraryView: View {
             LazyVGrid(columns: columns, spacing: 18) {
                 ForEach(games) { game in
                     if let onLaunch {
-                        Button { onLaunch(game.id) } label: { GameCard(game: game) }
+                        Button { onLaunch(game.id) } label: { GameCard(game: game, imageSession: imageSession) }
                             .buttonStyle(.plain)
                     } else {
-                        GameCard(game: game)
+                        GameCard(game: game, imageSession: imageSession)
                     }
                 }
             }
@@ -125,6 +162,13 @@ struct LibraryView: View {
                 certPEM: identity.certPEM,
                 keyPEM: identity.keyPEM,
                 hostFingerprint: current.pinnedSHA256)
+            imageSession?.finishTasksAndInvalidate()
+            imageSession = try LibraryImageLoader.session(
+                address: current.address,
+                port: current.effectiveMgmtPort,
+                certPEM: identity.certPEM,
+                keyPEM: identity.keyPEM,
+                hostFingerprint: current.pinnedSHA256)
         } catch {
             games = []
             errorText = (error as? LibraryError)?.errorDescription ?? error.localizedDescription
@@ -137,66 +181,19 @@ struct LibraryView: View {
 /// (portrait → header → hero) and finally a text placeholder.
 private struct GameCard: View {
     let game: GameEntry
+    let imageSession: URLSession?
 
     var body: some View {
         VStack(alignment: .leading, spacing: 6) {
-            PosterImage(candidates: game.art.posterCandidates, title: game.title)
+            PosterImage(candidates: game.art.posterCandidates, title: game.title, session: imageSession)
                 .aspectRatio(2.0 / 3.0, contentMode: .fit)
                 .frame(maxWidth: .infinity)
                 .clipShape(RoundedRectangle(cornerRadius: 10, style: .continuous))
-                .overlay(alignment: .topLeading) { storeBadge }
+                .overlay(alignment: .topLeading) { StoreBadge(isCustom: game.isCustom) }
             Text(game.title)
-                .font(.caption)
+                .font(.geist(12, relativeTo: .caption))
                 .lineLimit(2)
                 .foregroundStyle(.secondary)
         }
     }
-
-    private var storeBadge: some View {
-        Text(game.isCustom ? "Custom" : "Steam")
-            .font(.caption2.weight(.semibold))
-            .padding(.horizontal, 6)
-            .padding(.vertical, 3)
-            .background(.ultraThinMaterial, in: Capsule())
-            .padding(6)
-    }
-}
-
-/// Sequentially tries cover-art URLs, advancing past any that fail to load, then a placeholder.
-private struct PosterImage: View {
-    let candidates: [URL]
-    let title: String
-    @State private var index = 0
-
-    var body: some View {
-        if index < candidates.count {
-            AsyncImage(url: candidates[index]) { phase in
-                switch phase {
-                case .success(let image):
-                    image.resizable().scaledToFill()
-                case .failure:
-                    // Advance to the next candidate on the next render pass.
-                    Color.clear.onAppear { index += 1 }
-                case .empty:
-                    ZStack { placeholder; ProgressView() }
-                @unknown default:
-                    placeholder
-                }
-            }
-            .id(index) // recreate AsyncImage so it loads the newly-selected URL
-        } else {
-            placeholder
-        }
-    }
-
-    private var placeholder: some View {
-        ZStack {
-            Rectangle().fill(.quaternary)
-            Text(title)
-                .font(.headline)
-                .multilineTextAlignment(.center)
-                .foregroundStyle(.secondary)
-                .padding(8)
-        }
-    }
 }

clients/apple/Sources/PunktfunkClient/Home/LibraryWidgets.swift

@@ -0,0 +1,95 @@
+// Reusable library widgets, shared by the touch grid (LibraryView's `GameCard`) and the gamepad
+// coverflow (LibraryCoverflowView's cover cell).
+
+import PunktfunkKit
+import SwiftUI
+#if canImport(UIKit)
+import UIKit
+#elseif canImport(AppKit)
+import AppKit
+#endif
+
+/// The store-provenance badge (Steam vs. a user-curated custom entry) overlaid on a poster —
+/// shared by the touch grid's `GameCard` and the gamepad coverflow's cover cell.
+struct StoreBadge: View {
+    let isCustom: Bool
+
+    var body: some View {
+        Text(isCustom ? "Custom" : "Steam")
+            .font(.geist(11, .semibold, relativeTo: .caption2))
+            .padding(.horizontal, 6)
+            .padding(.vertical, 3)
+            .background(.ultraThinMaterial, in: Capsule())
+            .padding(6)
+    }
+}
+
+#if canImport(UIKit)
+private typealias PlatformImage = UIImage
+#elseif canImport(AppKit)
+private typealias PlatformImage = NSImage
+#endif
+
+private extension Image {
+    init(platformImage: PlatformImage) {
+        #if canImport(UIKit)
+        self.init(uiImage: platformImage)
+        #elseif canImport(AppKit)
+        self.init(nsImage: platformImage)
+        #endif
+    }
+}
+
+/// Sequentially tries cover-art URLs over `session` (so a paired client can reach the host's own
+/// art proxy, not just public CDNs — see `LibraryImageLoader`), advancing past any that fail to
+/// load, then a placeholder. The loaded image is hard-clipped to fill the card's actual frame
+/// regardless of its own aspect ratio: a portrait capsule fills it as intended, but a fallback
+/// banner (wide hero/header art, used when a title has no portrait capsule) would otherwise report
+/// a much wider intrinsic size than the card and overflow into neighboring cards. Not `private` —
+/// the gamepad coverflow (`LibraryCoverflowView`) reuses it directly rather than re-fetching art.
+struct PosterImage: View {
+    let candidates: [URL]
+    let title: String
+    let session: URLSession?
+    @State private var index = 0
+    @State private var image: PlatformImage?
+
+    var body: some View {
+        Group {
+            if let image {
+                Image(platformImage: image)
+                    .resizable()
+                    .scaledToFill()
+            } else if index < candidates.count {
+                ZStack { placeholder; ProgressView() }
+            } else {
+                placeholder
+            }
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+        .clipped()
+        .task(id: index) { await loadCurrent() }
+    }
+
+    private func loadCurrent() async {
+        guard index < candidates.count else { return }
+        guard let session, let data = try? await session.data(from: candidates[index]).0,
+              let loaded = PlatformImage(data: data)
+        else {
+            index += 1 // advance to the next candidate (or past the end → placeholder)
+            return
+        }
+        image = loaded
+    }
+
+    private var placeholder: some View {
+        ZStack {
+            Rectangle().fill(.quaternary)
+            Text(title)
+                .font(.geist(17, .semibold, relativeTo: .headline))
+                .multilineTextAlignment(.center)
+                .foregroundStyle(.secondary)
+                .padding(8)
+        }
+    }
+}

clients/apple/Sources/PunktfunkClient/Home/SpeedTestSheet.swift

@@ -52,7 +52,7 @@ struct SpeedTestSheet: View {
     var body: some View {
         VStack(spacing: 20) {
             Label("Speed test — \(host.displayName)", systemImage: "gauge.with.needle")
-                .font(.headline)
+                .font(.geist(17, .semibold, relativeTo: .headline))
                 .foregroundStyle(.tint)
 
             switch phase {
@@ -73,7 +73,7 @@ struct SpeedTestSheet: View {
                 resultView(result)
             case .failed(let message):
                 Text(message)
-                    .font(.callout)
+                    .font(.geist(16, relativeTo: .callout))
                     .foregroundStyle(.red)
                     .multilineTextAlignment(.center)
             }
@@ -149,13 +149,13 @@ struct SpeedTestSheet: View {
             if let rec = Self.recommendedKbps(result) {
                 Text("Recommended bitrate: \(Self.mbpsLabel(kbps: rec)) "
                     + "(~70% of measured, headroom for encoder bursts).")
-                    .font(.caption)
+                    .font(.geist(12, relativeTo: .caption))
                     .foregroundStyle(.secondary)
                     .multilineTextAlignment(.center)
             } else {
                 Text("Too little data made it through to recommend a bitrate — "
                     + "check the network and retry.")
-                    .font(.caption)
+                    .font(.geist(12, relativeTo: .caption))
                     .foregroundStyle(.secondary)
                     .multilineTextAlignment(.center)
             }

clients/apple/Sources/PunktfunkClient/HostCards.swift

@@ -1,177 +0,0 @@
-// The host grid's cards: a saved host (tap to connect, context menu) and an mDNS-discovered
-// host (tap to save + connect). Both share the same platform-tuned sizing.
-
-import PunktfunkKit
-import SwiftUI
-
-/// Shared host-card sizing — touch-first on iOS, compact on macOS/tvOS.
-private struct CardMetrics {
-    let iconSize: CGFloat
-    let iconBox: CGFloat
-    let cardPadding: CGFloat
-    let nameFont: Font
-
-    static var current: CardMetrics {
-        #if os(iOS)
-        CardMetrics(iconSize: 56, iconBox: 76, cardPadding: 28, nameFont: .title3.weight(.semibold))
-        #else
-        CardMetrics(iconSize: 42, iconBox: 56, cardPadding: 18, nameFont: .headline)
-        #endif
-    }
-}
-
-/// A saved host. The accent ring marks the most-recently-connected one; the context menu
-/// pairs / speed-tests / forgets / removes. Disabled while a session is busy.
-struct HostCardView: View {
-    let host: StoredHost
-    /// Currently advertising on the LAN (matched against live mDNS discovery). False means
-    /// "not seen on this network" — off, or a remote/cross-subnet host we can't observe.
-    let isOnline: Bool
-    let isConnecting: Bool
-    let isMostRecent: Bool
-    let isBusy: Bool
-    let onConnect: () -> Void
-    let onPair: () -> Void
-    let onSpeedTest: () -> Void
-    let onForget: () -> Void
-    let onRemove: () -> Void
-    /// Open the experimental library browser — nil (no menu item) unless the feature flag is on.
-    var onBrowseLibrary: (() -> Void)? = nil
-
-    var body: some View {
-        let m = CardMetrics.current
-        return Button(action: onConnect) {
-            VStack(spacing: 10) {
-                ZStack {
-                    Image(systemName: "play.display")
-                        .font(.system(size: m.iconSize, weight: .light))
-                        .foregroundStyle(.tint)
-                        .opacity(isConnecting ? 0.3 : 1)
-                    if isConnecting {
-                        ProgressView()
-                    }
-                }
-                .frame(height: m.iconBox)
-                VStack(spacing: 2) {
-                    HStack(spacing: 6) {
-                        // Presence dot: green = advertising on the LAN now; grey = not seen.
-                        Circle()
-                            .fill(isOnline ? Color.green : Color.secondary.opacity(0.35))
-                            .frame(width: 7, height: 7)
-                            .accessibilityLabel(isOnline ? "Online" : "Offline")
-                        Text(host.displayName)
-                            .font(m.nameFont)
-                            .lineLimit(1)
-                    }
-                    HStack(spacing: 4) {
-                        if host.pinnedSHA256 != nil {
-                            Image(systemName: "lock.fill")
-                                .font(.system(size: 9))
-                                .foregroundStyle(.secondary)
-                        }
-                        Text("\(host.address):\(String(host.port))")
-                            .font(.caption)
-                            .foregroundStyle(.secondary)
-                            .lineLimit(1)
-                    }
-                    if let last = host.lastConnected {
-                        Text("Connected \(last, format: .relative(presentation: .named))")
-                            .font(.caption2)
-                            .foregroundStyle(.tertiary)
-                            .lineLimit(1)
-                    }
-                }
-            }
-            .frame(maxWidth: .infinity)
-            .padding(.vertical, m.cardPadding)
-            .padding(.horizontal, 12)
-            #if !os(tvOS)
-            // tvOS: the .card button style owns platter + focus motion — extra chrome
-            // inside it mutes the grow/tilt. Material + accent ring are for pointer UIs.
-            // Deliberately .regularMaterial, not Liquid Glass: HIG keeps glass off content
-            // tiles (it flattens hierarchy over an opaque grid) — see GlassStyle.swift.
-            .background(.regularMaterial, in: RoundedRectangle(cornerRadius: 14))
-            .overlay {
-                if isMostRecent {
-                    RoundedRectangle(cornerRadius: 14)
-                        .strokeBorder(Color.accentColor.opacity(0.35), lineWidth: 1.5)
-                }
-            }
-            #endif
-        }
-        #if os(tvOS)
-        .buttonStyle(.card)
-        #else
-        .buttonStyle(.plain)
-        #endif
-        .disabled(isBusy)
-        .contextMenu {
-            Button("Pair with PIN…", action: onPair)
-            Button("Test Network Speed…", action: onSpeedTest)
-            if let onBrowseLibrary {
-                Button("Browse Library…", action: onBrowseLibrary)
-            }
-            if host.pinnedSHA256 != nil {
-                // Dropping the pin does NOT downgrade to TOFU: the next connect must re-pair via
-                // PIN (unless the host advertises pair=optional). Wording reflects that.
-                Button("Forget Identity (re-pair to reconnect)", action: onForget)
-            }
-            Button("Remove", role: .destructive, action: onRemove)
-        }
-    }
-}
-
-/// A host found on the LAN but not yet saved. A dashed ring distinguishes it from saved cards;
-/// tapping saves it and connects (or pairs, if the host requires it).
-struct DiscoveredCardView: View {
-    let discovered: DiscoveredHost
-    let isBusy: Bool
-    let onConnect: () -> Void
-
-    var body: some View {
-        let m = CardMetrics.current
-        return Button(action: onConnect) {
-            VStack(spacing: 10) {
-                Image(systemName: "play.display")
-                    .font(.system(size: m.iconSize, weight: .light))
-                    .foregroundStyle(.tint)
-                    .frame(height: m.iconBox)
-                VStack(spacing: 2) {
-                    Text(discovered.name)
-                        .font(m.nameFont)
-                        .lineLimit(1)
-                    HStack(spacing: 4) {
-                        Image(systemName: discovered.requiresPairing ? "lock.fill" : "wifi")
-                            .font(.system(size: 9))
-                            .foregroundStyle(.secondary)
-                        Text("\(discovered.host):\(String(discovered.port))")
-                            .font(.caption)
-                            .foregroundStyle(.secondary)
-                            .lineLimit(1)
-                    }
-                    Text(discovered.requiresPairing ? "Pairing required" : "Discovered")
-                        .font(.caption2)
-                        .foregroundStyle(.tertiary)
-                }
-            }
-            .frame(maxWidth: .infinity)
-            .padding(.vertical, m.cardPadding)
-            .padding(.horizontal, 12)
-            #if !os(tvOS)
-            .background(.regularMaterial, in: RoundedRectangle(cornerRadius: 14))
-            .overlay {
-                RoundedRectangle(cornerRadius: 14)
-                    .strokeBorder(
-                        Color.secondary.opacity(0.25),
-                        style: StrokeStyle(lineWidth: 1, dash: [4, 3]))
-            }
-            #endif
-        }
-        #if os(tvOS)
-        .buttonStyle(.card)
-        #else
-        .buttonStyle(.plain)
-        #endif
-        .disabled(isBusy)
-    }
-}

clients/apple/Sources/PunktfunkClient/PunktfunkClientApp.swift

@@ -12,20 +12,36 @@ struct PunktfunkClientApp: App {
     @NSApplicationDelegateAdaptor(AppDelegate.self) private var appDelegate
     #endif
 
+    init() {
+        #if os(iOS)
+        // Put Geist on the navigation titles before any bar is built.
+        BrandTheme.apply()
+        #endif
+    }
+
     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 {
+            // Pin the whole app's tint to the brand purple explicitly — the asset-catalog accent
+            // resolution is environment/timing-sensitive and can fall back to system blue. Wraps the
+            // screenshot harness too, so captured screens are on-brand.
+            Group {
+                #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
             }
-            #else
-            ContentView()
-            #endif
+            .tint(.brand)
+            // Geist Sans is the app's typeface. This sets the default for unstyled text and the
+            // form row labels; views that pick an explicit size/weight use `.geist(…)` directly.
+            .font(.geist(17, relativeTo: .body))
         }
         // The Stream menu (Disconnect ⌘D, Show/Hide Statistics ⌘⇧S) — a real menu bar on
         // macOS, hardware-keyboard shortcuts on iPad. tvOS has neither.
@@ -34,7 +50,10 @@ struct PunktfunkClientApp: App {
         #endif
         #if os(macOS)
         Settings {
+            // A separate scene — `.tint` does not cross scene boundaries, so re-apply the brand
+            // tint here or the Preferences window falls back to the (unreliable) asset accent.
             SettingsView()
+                .tint(.brand)
         }
         #endif
     }

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

@@ -103,11 +103,11 @@ private struct ShotSettings: View {
                 .shadow(radius: 40, y: 16)
         }
         #elseif os(iOS)
-        NavigationStack {
-            SettingsView()
-                .navigationTitle("Settings")
-                .navigationBarTitleDisplayMode(.inline)
-        }
+        // SettingsView owns its NavigationSplitView (sidebar + detail) and Done button, so it is
+        // rendered directly — a wrapping NavigationStack would nest a split view in a stack. Open
+        // on General so the shot lands on real controls (iPad: sidebar + General detail; iPhone:
+        // the General page) instead of the bare category list.
+        SettingsView(initialCategory: .general)
         #else
         NavigationStack { SettingsView() }
         #endif
@@ -170,15 +170,18 @@ private struct ShotHUD: View {
                 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")
+            Text("end-to-end 2.9 ms p50 · 3.8 p95 · capture→on-glass")
+                .font(.system(.caption2, design: .monospaced))
+                .foregroundStyle(.secondary)
+            Text("= host+network 1.3 + decode 0.7 + display 0.9")
                 .font(.system(.caption2, design: .monospaced))
                 .foregroundStyle(.secondary)
             #if os(macOS)
             Text("⌘⎋ releases the mouse")
-                .font(.caption2).foregroundStyle(.secondary)
+                .font(.geist(11, relativeTo: .caption2)).foregroundStyle(.secondary)
             #elseif os(tvOS)
             Text("Press Menu to disconnect")
-                .font(.caption).foregroundStyle(.secondary)
+                .font(.geist(12, relativeTo: .caption)).foregroundStyle(.secondary)
             #endif
         }
         .padding(10)
@@ -259,7 +262,7 @@ private struct ShotDesktopFrame: View {
             HStack(spacing: 8) {
                 Image(systemName: "gamecontroller.fill")
                 Text("Streaming from Battlestation")
-                    .font(.system(.callout, weight: .semibold))
+                    .font(.geist(16, .semibold, relativeTo: .callout))
             }
             .padding(.horizontal, 14).padding(.vertical, 9)
             .glassBackground(Capsule())

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

@@ -0,0 +1,35 @@
+// The HUD-corner model persisted by Settings and read wherever the overlay is placed
+// (ContentView, StreamHUDView).
+
+import SwiftUI
+
+/// Which corner the HUD overlay occupies (persisted as `DefaultsKey.hudPlacement`). The raw
+/// values are stable on disk — rename the cases freely, never the strings.
+enum HUDPlacement: String, CaseIterable, Identifiable {
+    case topLeading, topTrailing, bottomLeading, bottomTrailing
+
+    var id: String { rawValue }
+
+    /// SwiftUI overlay alignment for `.overlay(alignment:)`.
+    var alignment: Alignment {
+        switch self {
+        case .topLeading: return .topLeading
+        case .topTrailing: return .topTrailing
+        case .bottomLeading: return .bottomLeading
+        case .bottomTrailing: return .bottomTrailing
+        }
+    }
+
+    /// The HUD's own stack hugs the screen edge it sits against, so its text aligns outward.
+    var isTrailing: Bool { self == .topTrailing || self == .bottomTrailing }
+
+    /// User-facing corner label.
+    var label: String {
+        switch self {
+        case .topLeading: return "Top Left"
+        case .topTrailing: return "Top Right"
+        case .bottomLeading: return "Bottom Left"
+        case .bottomTrailing: return "Bottom Right"
+        }
+    }
+}

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

@@ -59,29 +59,62 @@ final class SessionModel: ObservableObject {
     @Published var fps = 0
     @Published var mbps = 0.0
     @Published var totalFrames = 0
-    /// Capture→client-receipt latency (ms), skew-corrected across machines via the connect-time
-    /// clock offset — p50/p95 for the HUD. `latencyValid` is false until the first sample drains
-    /// (and whenever no host frames arrived in the last interval). `latencySkewCorrected` = the host
+    /// The unified latency stages (design/stats-unification.md), ms per 1 s window. `host+network`
+    /// = capture→received, skew-corrected across machines via the connect-time clock offset: the
+    /// stage-2 HUD shows its p50 in the equation line; the stage-1 fallback shows p50/p95 as its
+    /// `capture→received` headline. `hostNetworkValid` is false until the first sample drains (and
+    /// whenever no host frames arrived in the last interval). `hostNetworkSkewCorrected` = the host
     /// answered the skew handshake (the number is cross-machine valid, not just same-host).
-    @Published var latencyP50Ms = 0.0
-    @Published var latencyP95Ms = 0.0
-    @Published var latencyValid = false
-    @Published var latencySkewCorrected = false
-    /// Capture→present (glass-to-glass, modulo the host render→capture term) — only the stage-2
-    /// presenter can stamp this (it owns decode + a CAMetalLayer/display-link present). Stays
-    /// invalid under stage-1, where the layer presents internally with no per-frame callback.
-    @Published var presentLatencyP50Ms = 0.0
-    @Published var presentLatencyP95Ms = 0.0
-    @Published var presentLatencyValid = false
-    @Published var presentLatencySkewCorrected = false
+    @Published var hostNetworkP50Ms = 0.0
+    @Published var hostNetworkP95Ms = 0.0
+    @Published var hostNetworkValid = false
+    @Published var hostNetworkSkewCorrected = false
+    /// Phase 2 of the same stage: `host+network` split into its two terms via the host's per-AU
+    /// 0xCF timing reports (host = capture→fully-sent as the host measured it, network = the
+    /// remainder), matched to receipts by pts in `latencySplit`. `splitValid` is false whenever
+    /// no timing matched in the window — an old host that never emits the plane, or heavy 0xCF
+    /// loss — and the HUD then falls back to the combined `host+network` term.
+    @Published var hostP50Ms = 0.0
+    @Published var networkP50Ms = 0.0
+    @Published var splitValid = false
+    /// End-to-end = capture→on-glass, measured directly per frame (never summed from the stages) —
+    /// the HUD headline. Only the stage-2 presenter can stamp it (it owns decode + a
+    /// CAMetalLayer/display-link present); stays invalid under stage-1, where the layer presents
+    /// internally with no per-frame callback.
+    @Published var endToEndP50Ms = 0.0
+    @Published var endToEndP95Ms = 0.0
+    @Published var endToEndValid = false
+    @Published var endToEndSkewCorrected = false
+    /// The client-local stage terms of the HUD's equation line (single clock, no skew; p50 only):
+    /// decode = received→decoded, display = decoded→on-glass (ring wait + render + vsync — the
+    /// term the stage-2 presenter exists to shorten).
+    @Published var decodeP50Ms = 0.0
+    @Published var decodeValid = false
+    @Published var displayP50Ms = 0.0
+    @Published var displayValid = false
+    /// Unrecoverable network frame drops in the last window (FEC couldn't rebuild them) and their
+    /// share of frames offered, `lost/(received+lost)`. The HUD hides the line while zero.
+    @Published var lostFrames = 0
+    @Published var lostPct = 0.0
     /// Mirrors StreamView's capture state (it owns the input capture; this drives the
     /// HUD's "click to capture" / "⌘⎋ releases" hint).
     @Published var mouseCaptured = false
 
     let meter = FrameMeter()
+    /// Capture→received (the host+network stage), fed per AU at receipt by the stream view's
+    /// onFrame — under both presenters.
     let latency = LatencyMeter()
-    /// Fed by the stage-2 presenter's display link (capture→present). Passed to StreamView.
-    let presentLatency = LatencyMeter()
+    /// The host/network split of that same stage: onFrame also records (pts, interval) receipts
+    /// here, and the 1 s stats tick drains the connection's 0xCF host timings into it — under
+    /// both presenters (the receipt path is presenter-independent).
+    let latencySplit = HostNetworkSplitter()
+    /// The stage-2 meters, passed to StreamView: end-to-end (capture→on-glass, stamped at
+    /// present), decode (received→decoded), display (decoded→on-glass).
+    let endToEnd = LatencyMeter()
+    let decodeStage = LatencyMeter()
+    let displayStage = LatencyMeter()
+    /// Cumulative reassembler-drop counter at the last stats drain (per-window `lost` delta).
+    private var lastFramesDropped: UInt64 = 0
     private var statsTimer: Timer?
     private var audio: SessionAudio?
     private var gamepadCapture: GamepadCapture?
@@ -95,14 +128,24 @@ final class SessionModel: ObservableObject {
     /// field — TOFU is forbidden (rule 3b): the connect refuses rather than offering trust, and
     /// the user is routed to PIN pairing by the caller. (A pinned host connects regardless: its
     /// stored fingerprint is the trust decision.)
+    ///
+    /// `requestAccess` is the no-PIN delegated-approval path: open an identified connect the host
+    /// PARKS until the operator clicks Approve in its console, then admits the SAME connection (no
+    /// reconnect). The handshake budget is widened to exceed the host's park window, and a
+    /// successful connect streams directly (the approval IS the trust decision) — the caller pins
+    /// the observed fingerprint as paired. `host.pinnedSHA256`, when set, pins the advertised cert
+    /// for the wait; nil = trust-on-first-use.
     func connect(to host: StoredHost, width: UInt32, height: UInt32, hz: UInt32,
                  compositor: PunktfunkConnection.Compositor = .auto,
                  gamepad: PunktfunkConnection.GamepadType = .auto,
                  bitrateKbps: UInt32 = 0,
+                 audioChannels: UInt8 = 2,
                  hdrEnabled: Bool = true,
+                 preferredCodec: UInt8 = 0,
                  launchID: String? = nil,
                  allowTofu: Bool = false,
-                 autoTrust: Bool = false) {
+                 autoTrust: Bool = false,
+                 requestAccess: Bool = false) {
         guard phase == .idle else { return }
         phase = .connecting
         activeHost = host
@@ -120,6 +163,8 @@ final class SessionModel: ObservableObject {
             #endif
         }()
         let hdrCapable = hdrEnabled && displayHDR
+        // 4:4:4 opt-out (default on); the hardware-decode probe below is the real gate.
+        let want444 = (UserDefaults.standard.object(forKey: DefaultsKey.enable444) as? Bool) ?? true
         Task.detached(priority: .userInitiated) {
             // PunktfunkConnection.init blocks on the QUIC handshake — keep it off the main
             // actor. The persistent identity is presented on every connect so a paired
@@ -129,15 +174,36 @@ final class SessionModel: ObservableObject {
             // Advertise 10-bit + HDR10 when enabled: the host upgrades to a BT.2020 PQ Main10 stream
             // only for actual HDR content (its own gate); the VideoToolbox/Metal present path is
             // HDR-capable (P010 + itur_2100_PQ + EDR). 0 keeps the 8-bit BT.709 SDR stream.
-            let videoCaps: UInt8 = hdrCapable
+            var videoCaps: UInt8 = hdrCapable
                 ? (PunktfunkConnection.videoCap10Bit | PunktfunkConnection.videoCapHDR)
                 : 0
+            // Advertise full-chroma 4:4:4 only when allowed AND this device can HARDWARE-decode it
+            // (software 4:4:4 is too slow for real-time). The host content-gates depth, so an
+            // HDR-advertised session can still receive an 8-bit 4:4:4 stream (SDR content) — require
+            // BOTH depths there. Otherwise a no-op (the host emits 4:4:4 only if it too opted in);
+            // `chromaFormat` on the connection reflects what was actually resolved.
+            let canDecode444 =
+                hdrCapable
+                ? (Stage444Probe.hwDecode444_8bit && Stage444Probe.hwDecode444_10bit)
+                : Stage444Probe.hwDecode444_8bit
+            if want444, canDecode444 {
+                videoCaps |= PunktfunkConnection.videoCap444
+            }
+            // This client's VideoToolbox path decodes H.264 and HEVC (AV1 isn't wired — hosts don't
+            // emit it on the native path yet). The host resolves the emitted codec from these + the
+            // soft `preferredCodec`; `resolvedCodec` reflects what it chose.
+            let videoCodecs = PunktfunkConnection.codecH264 | PunktfunkConnection.codecHEVC
             let result = Result { try PunktfunkConnection(
                 host: host.address, port: host.port,
                 width: width, height: height, refreshHz: hz,
                 pinSHA256: pin, identity: identity, compositor: compositor,
                 gamepad: gamepad, bitrateKbps: bitrateKbps, videoCaps: videoCaps,
-                launchID: launchID) }
+                audioChannels: audioChannels,
+                videoCodecs: videoCodecs, preferredCodec: preferredCodec, launchID: launchID,
+                // Delegated approval: the host holds this connect open until the operator approves
+                // it (~180 s) — outwait that window so a slow approval still lands here. Normal
+                // connects keep the snappy default.
+                timeoutMs: requestAccess ? 185_000 : 10_000) }
             await MainActor.run { [weak self] in
                 guard let self else { return }
                 // The user may have abandoned this attempt (window closed, another host
@@ -151,7 +217,9 @@ final class SessionModel: ObservableObject {
                 }
                 switch result {
                 case .success(let conn):
-                    if pin != nil || autoTrust {
+                    if pin != nil || autoTrust || requestAccess {
+                        // requestAccess: the operator approved this device on the host, so the
+                        // session is trusted — stream directly (the caller pins it as paired).
                         self.connection = conn
                         self.startStatsTimer()
                         self.beginStreaming()
@@ -173,16 +241,25 @@ final class SessionModel: ObservableObject {
                 case .failure:
                     self.phase = .idle
                     self.activeHost = nil
-                    self.errorMessage = pin != nil
-                        ? "Could not connect to \(host.displayName) — host unreachable, "
-                            + "not running, its identity no longer matches the pinned "
-                            + "fingerprint, or it requires pairing and no longer "
-                            + "recognizes this Mac (right-click the host card to pair "
-                            + "again)."
-                        : "Could not connect to \(host.displayName) — is punktfunk-host "
-                            + "running on \(host.address):\(host.port)? If it requires "
-                            + "pairing, right-click the host card and pair with its PIN "
-                            + "first."
+                    if requestAccess {
+                        // The delegated-approval connect ended without being admitted: the
+                        // operator didn't approve it before the host's park window elapsed (or
+                        // the host was unreachable).
+                        self.errorMessage = "\(host.displayName) didn't let this device in. "
+                            + "Approve it in the host's web console (port 3000 → Pairing), then "
+                            + "request access again — the request expires after a few minutes."
+                    } else {
+                        self.errorMessage = pin != nil
+                            ? "Could not connect to \(host.displayName) — host unreachable, "
+                                + "not running, its identity no longer matches the pinned "
+                                + "fingerprint, or it requires pairing and no longer "
+                                + "recognizes this Mac (right-click the host card to pair "
+                                + "again)."
+                            : "Could not connect to \(host.displayName) — is punktfunk-host "
+                                + "running on \(host.address):\(host.port)? If it requires "
+                                + "pairing, right-click the host card and pair with its PIN "
+                                + "first."
+                    }
                 }
             }
         }
@@ -230,7 +307,13 @@ final class SessionModel: ObservableObject {
         phase = .idle
         fps = 0
         mbps = 0
-        latencyValid = false
+        hostNetworkValid = false
+        splitValid = false
+        endToEndValid = false
+        decodeValid = false
+        displayValid = false
+        lostFrames = 0
+        lostPct = 0
         mouseCaptured = false
     }
 
@@ -255,6 +338,7 @@ final class SessionModel: ObservableObject {
         audio.start(
             speakerUID: defaults.string(forKey: DefaultsKey.speakerUID) ?? "",
             micUID: defaults.string(forKey: DefaultsKey.micUID) ?? "",
+            micChannel: defaults.integer(forKey: DefaultsKey.micChannel),
             micEnabled: defaults.object(forKey: DefaultsKey.micEnabled) as? Bool ?? true)
         self.audio = audio
         // Gamepads: forward GamepadManager's active controller as pad 0 and render the
@@ -270,6 +354,8 @@ final class SessionModel: ObservableObject {
     }
 
     private func startStatsTimer() {
+        lastFramesDropped = 0 // a fresh connection's cumulative drop counter starts at 0
+        latencySplit.reset() // no stale receipts/samples from a previous session
         let timer = Timer(timeInterval: 1.0, repeats: true) { [weak self] _ in
             guard let self else { return }
             Task { @MainActor in
@@ -277,21 +363,60 @@ final class SessionModel: ObservableObject {
                 self.fps = frames
                 self.mbps = Double(bytes) * 8 / 1_000_000
                 self.totalFrames = total
+                // Per-window `lost` = the delta of the connector's cumulative reassembler-drop
+                // counter (0 after close — treat a rewind as no loss rather than underflowing).
+                let dropped = self.connection?.framesDropped() ?? 0
+                let lost = dropped >= self.lastFramesDropped
+                    ? Int(dropped - self.lastFramesDropped) : 0
+                self.lastFramesDropped = dropped
+                self.lostFrames = lost
+                self.lostPct = lost > 0 ? Double(lost) / Double(frames + lost) * 100 : 0
                 if let lat = self.latency.drain() {
-                    self.latencyP50Ms = lat.p50Ms
-                    self.latencyP95Ms = lat.p95Ms
-                    self.latencySkewCorrected = lat.skewCorrected
-                    self.latencyValid = true
+                    self.hostNetworkP50Ms = lat.p50Ms
+                    self.hostNetworkP95Ms = lat.p95Ms
+                    self.hostNetworkSkewCorrected = lat.skewCorrected
+                    self.hostNetworkValid = true
                 } else {
-                    self.latencyValid = false
+                    self.hostNetworkValid = false
                 }
-                if let p = self.presentLatency.drain() {
-                    self.presentLatencyP50Ms = p.p50Ms
-                    self.presentLatencyP95Ms = p.p95Ms
-                    self.presentLatencySkewCorrected = p.skewCorrected
-                    self.presentLatencyValid = true
+                // Phase 2: drain the window's per-AU host timings (0xCF) into the splitter —
+                // non-blocking, bounded (a 240 fps window is ~240 reports; the cap only guards
+                // a pathological burst). `try?` flattens (SE-0230); a throw (.closed during
+                // teardown) just ends the drain. An old host never emits any → splitValid stays
+                // false and the HUD keeps the combined host+network term.
+                if let conn = self.connection {
+                    var burst = 0
+                    while burst < 1024, let t = try? conn.nextHostTiming(timeoutMs: 0) {
+                        self.latencySplit.noteHostTiming(ptsNs: t.ptsNs, hostUs: t.hostUs)
+                        burst += 1
+                    }
+                }
+                if let s = self.latencySplit.drain() {
+                    self.hostP50Ms = s.hostP50Ms
+                    self.networkP50Ms = s.networkP50Ms
+                    self.splitValid = true
                 } else {
-                    self.presentLatencyValid = false
+                    self.splitValid = false
+                }
+                if let e = self.endToEnd.drain() {
+                    self.endToEndP50Ms = e.p50Ms
+                    self.endToEndP95Ms = e.p95Ms
+                    self.endToEndSkewCorrected = e.skewCorrected
+                    self.endToEndValid = true
+                } else {
+                    self.endToEndValid = false
+                }
+                if let d = self.decodeStage.drain() {
+                    self.decodeP50Ms = d.p50Ms
+                    self.decodeValid = true
+                } else {
+                    self.decodeValid = false
+                }
+                if let d = self.displayStage.drain() {
+                    self.displayP50Ms = d.p50Ms
+                    self.displayValid = true
+                } else {
+                    self.displayValid = false
                 }
             }
         }

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

@@ -0,0 +1,102 @@
+// The streaming overlay HUD: mode + fps/throughput, the unified latency lines
+// (design/stats-unification.md — end-to-end headline + the stage equation under stage-2, the
+// capture→received headline under the stage-1 fallback), the loss counter, the platform input
+// hint, and disconnect.
+
+import PunktfunkKit
+import SwiftUI
+
+struct StreamHUDView: View {
+    @ObservedObject var model: SessionModel
+    let connection: PunktfunkConnection
+    var placement: HUDPlacement = .topTrailing
+
+    var body: some View {
+        VStack(alignment: placement.isTrailing ? .trailing : .leading, spacing: 4) {
+            HStack(spacing: 6) {
+                Circle()
+                    .fill(Color.accentColor)
+                    .frame(width: 7, height: 7)
+                Text("\(connection.width)×\(connection.height)@\(connection.refreshHz)  \(model.fps) fps  \(model.mbps, specifier: "%.1f") Mb/s")
+                    .font(.system(.caption, design: .monospaced))
+            }
+            if model.endToEndValid {
+                // Stage-2: the end-to-end headline (capture→on-glass, measured directly, skew-
+                // corrected) — "(same-host clock)" when the host didn't answer the skew handshake.
+                Text("end-to-end \(model.endToEndP50Ms, specifier: "%.1f") ms p50 · \(model.endToEndP95Ms, specifier: "%.1f") p95 · capture→on-glass\(model.endToEndSkewCorrected ? "" : " (same-host clock)")")
+                    .font(.system(.caption2, design: .monospaced))
+                    .foregroundStyle(.secondary)
+                // The equation: the stages tiling the headline interval (per-window p50s —
+                // they only approximately sum to the directly-measured total). With a host
+                // that reports per-AU timings (0xCF) the first term splits into host + network
+                // (phase 2); an old host keeps the combined term.
+                if model.hostNetworkValid && model.decodeValid && model.displayValid {
+                    if model.splitValid {
+                        Text("= host \(model.hostP50Ms, specifier: "%.1f") + network \(model.networkP50Ms, specifier: "%.1f") + decode \(model.decodeP50Ms, specifier: "%.1f") + display \(model.displayP50Ms, specifier: "%.1f")")
+                            .font(.system(.caption2, design: .monospaced))
+                            .foregroundStyle(.secondary)
+                    } else {
+                        Text("= host+network \(model.hostNetworkP50Ms, specifier: "%.1f") + decode \(model.decodeP50Ms, specifier: "%.1f") + display \(model.displayP50Ms, specifier: "%.1f")")
+                            .font(.system(.caption2, design: .monospaced))
+                            .foregroundStyle(.secondary)
+                    }
+                }
+            } else if model.hostNetworkValid {
+                // Stage-1 fallback presenter: the layer decodes + presents internally with no
+                // per-frame stamp, so the honest headline ends at receipt. The host/network
+                // split still applies there (receipt is presenter-independent) — it becomes the
+                // only equation line; without it, host+network IS the whole measured interval.
+                Text("capture→received \(model.hostNetworkP50Ms, specifier: "%.1f") ms p50 · \(model.hostNetworkP95Ms, specifier: "%.1f") p95\(model.hostNetworkSkewCorrected ? "" : " (same-host clock)")")
+                    .font(.system(.caption2, design: .monospaced))
+                    .foregroundStyle(.secondary)
+                if model.splitValid {
+                    Text("= host \(model.hostP50Ms, specifier: "%.1f") + network \(model.networkP50Ms, specifier: "%.1f")")
+                        .font(.system(.caption2, design: .monospaced))
+                        .foregroundStyle(.secondary)
+                }
+            }
+            if model.lostFrames > 0 {
+                // Unrecoverable network drops this window; hidden while the link is clean.
+                // String(format:) rather than specifier interpolation: the literal % would
+                // otherwise land in the LocalizedStringKey's format string as a bogus conversion.
+                Text(String(format: "lost %d (%.1f%%)", model.lostFrames, model.lostPct))
+                    .font(.system(.caption2, design: .monospaced))
+                    .foregroundStyle(.secondary)
+            }
+            // While captured the cursor is hidden+frozen, so the button is keyboard-only
+            // (⌘⎋ or Cmd+Tab release the cursor; released, it's clickable again).
+            #if os(macOS)
+            Text(model.mouseCaptured
+                ? "⌘⎋ releases the mouse"
+                : "Click the stream to capture input")
+                .font(.geist(11, relativeTo: .caption2))
+                .foregroundStyle(.secondary)
+            #elseif os(iOS)
+            // Touch always plays directly; ⌘⎋ (hardware keyboard) toggles kb/mouse.
+            Text(model.mouseCaptured
+                ? "⌘⎋ releases keyboard & mouse"
+                : "⌘⎋ captures keyboard & mouse")
+                .font(.geist(11, relativeTo: .caption2))
+                .foregroundStyle(.secondary)
+            #endif
+            #if os(tvOS)
+            // No focusable control during play: a focusable button steals the controller's
+            // A press (the focus engine consumes it before the host sees it). Disconnect is
+            // the Siri Remote's Menu button (.onExitCommand on the stream) — just hint it.
+            Text("Press Menu to disconnect")
+                .font(.geist(12, relativeTo: .caption))
+                .foregroundStyle(.secondary)
+            #else
+            // ⌘D lives on the app's Stream menu (so it still works when the HUD is hidden);
+            // this button is the in-overlay, click-to-disconnect affordance.
+            Button("Disconnect (⌘D)") { model.disconnect() }
+                .font(.geist(12, relativeTo: .caption))
+            #endif
+        }
+        .padding(10)
+        // Floating HUD over live video — the canonical Liquid-Glass overlay surface (26+);
+        // falls back to .regularMaterial below 26 (see GlassStyle).
+        .glassBackground(RoundedRectangle(cornerRadius: 10))
+        .padding(10)
+    }
+}