test(inject): the uhid sweep tests learn the devnode-churn grace

6b0bd59b gave the unplug sweep a 300 ms grace so a mask glitch can't flap PnP devices — and updated pad_slots' own tests, but not the two uhid_manager consumer tests that encode the old immediate-sweep contract (its CI run was cancelled by a superseding push, so the breakage surfaced on later shas). PadSlots gains a #[cfg(test)] expire_grace() that backdates the armed clocks, so consumer tests drive the debounce without wall-clock sleeps. The removal test now also PINS the new hold-inside-grace behavior explicitly. Verified in the amd64 CI-image container: pf-inject 83/83, clippy --all-targets -D warnings clean. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
fix(gamepad): a mask glitch no longer flaps devnodes — the unplug sweep gets a grace
2026-07-31 01:35:51 +02:00 · 2026-07-31 00:59:50 +02:00 · 2026-07-31 00:59:50 +02:00 · 2026-07-31 00:38:31 +02:00 · 2026-07-30 23:44:09 +02:00 · 2026-07-30 23:44:09 +02:00
457 changed files with 42977 additions and 5708 deletions
@@ -4,6 +4,14 @@
 # `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
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  push:
@@ -14,33 +22,27 @@ jobs:
  screenshots:
    if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-24.04
+    # JDK 21 + SDK baked (AGP 9.3 + Robolectric's SDK-36 android-all jar both want 17–21).
+    # The tests are pure JVM (no NDK), but sharing android.yml's image means one image to
+    # keep warm instead of a per-run setup-java + sdkmanager download pair.
+    container:
+      image: 192.168.1.58:5010/punktfunk-android-ci:latest
    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
-        # SHA-pinned for parity with android.yml (third-party action). v3 = 9fc6c4e.
-        uses: android-actions/setup-android@9fc6c4e9069bf8d3d10b2204b1fb8f6ef7065407 # v3
-
-      # No NDK/CMake — the screenshot unit tests are pure JVM. compileSdk 37 auto-downloads via AGP
-      # if the platform channel lacks it (same note as android.yml).
-      - 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-
+          # gradle-wrapper.properties is in the key on purpose: `~/.gradle/wrapper` caches the
+          # Gradle DISTRIBUTION, so a wrapper bump with no .gradle.kts change would otherwise
+          # restore a key that can never hold the new one. Namespace shared with android.yml —
+          # it is the same content; two keys just stored it twice in the central cache.
+          key: gradle-${{ hashFiles('clients/android/**/*.gradle.kts', 'clients/android/gradle/wrapper/gradle-wrapper.properties') }}
+          restore-keys: gradle-

      # 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.
@@ -2,82 +2,112 @@
 # cargo-ndk for all three shipping ABIs and assembles the debug APK (clients/android). Mirrors apple.yml
 # but on a Linux runner — the NDK is cross-platform, so no self-hosted host is needed.
 #
-# Prereq: the runner needs ~6 GB free + internet (it pulls the Android SDK/NDK and the Gradle
-# distribution in-job). If android-actions/setup-android is not mirrored on this Gitea instance,
-# replace that step with a manual cmdline-tools download, or bake an `android-ci` image like
-# ci/rust-ci.Dockerfile. Emulator instrumentation tests are deferred until a KVM-capable runner
-# exists (they self-skip otherwise, like apple.yml's RemoteFirstLightTests).
+# Runs in the punktfunk-android-ci builder image (ci/android-ci.Dockerfile, content-keyed on
+# the LAN registry): JDK 21, the Android SDK/NDK/CMake pins, cargo-ndk and sccache are all
+# baked, so the multi-GB per-run Google downloads this job used to make are gone. Emulator
+# instrumentation tests are deferred until a KVM-capable runner exists (they self-skip
+# otherwise, like apple.yml's RemoteFirstLightTests).
 name: android
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  push:
    branches: [main]
+    # Scope canary builds to what this artifact is built FROM — a docs-only or
+    # web-only push should not light up the whole fleet. Applies to branch pushes;
+    # tag runs are matched by `tags:` (proven by flatpak/windows-msix releases).
+    paths:
+      - 'crates/**'
+      - 'clients/android/**'
+      # The builder image is part of what this artifact is built from — an image
+      # change must exercise its consumer.
+      - 'ci/android-ci.Dockerfile'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+      - 'rust-toolchain.toml'
+      - 'scripts/ci/**'
+      - '.gitea/workflows/android.yml'
    # Single project version: a `vX.Y.Z` tag is THE release (uploads to Play's `alpha` closed
    # track for manual promotion + attaches the .aab/.apk to the unified Gitea Release). A main
    # push is canary (Play `internal`).
    tags: ['v*']
  pull_request:
+    paths:
+      - 'crates/**'
+      - 'clients/android/**'
+      # The builder image is part of what this artifact is built from — an image
+      # change must exercise its consumer.
+      - 'ci/android-ci.Dockerfile'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+      - 'rust-toolchain.toml'
+      - 'scripts/ci/**'
+      - '.gitea/workflows/android.yml'
  workflow_dispatch:

+# Shared compile cache: sccache -> RustFS S3 (storage.unom.io, LAN-pinned via ci-core's
+# unbound). The NDK clang targets get their own key universes automatically (keys embed
+# compiler hash + target), so the three ABI builds share the bucket with everything else.
+env:
+  RUSTC_WRAPPER: sccache
+  SCCACHE_BUCKET: unom-ci-sccache
+  SCCACHE_ENDPOINT: https://storage.unom.io
+  SCCACHE_REGION: home-central
+  AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
+  AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  # sccache and incremental compilation are mutually exclusive; CI wants the shared
+  # cache, dev boxes keep incremental.
+  CARGO_INCREMENTAL: "0"
+
 jobs:
  android:
    runs-on: ubuntu-24.04
+    container:
+      image: 192.168.1.58:5010/punktfunk-android-ci:latest
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v4

-      - name: JDK 21 (AGP 9.2 runs on JDK 17–21, not the host default)
-        uses: actions/setup-java@v4
-        with:
-          distribution: temurin
-          java-version: "21"
+      # Everything below the checkout used to be four download steps (JDK, SDK,
+      # NDK+CMake, cargo-ndk — the flakiest, heaviest part of the job); it is all baked
+      # into the image now. This guard only re-asserts the Android targets so a
+      # rust-toolchain.toml pin bump keeps working against an older image (:latest lags
+      # one image rebuild, same bootstrap note as ci.yml's dep steps).
+      - name: Rust Android targets (no-op unless the toolchain pin outran the image)
+        run: rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android

-      - name: Rust toolchain + Android targets (self-healing on a fresh runner)
-        run: |
-          if ! command -v rustup >/dev/null && [ ! -x "$HOME/.cargo/bin/rustup" ]; then
-            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
-              | sh -s -- -y --no-modify-path --profile minimal
-          fi
-          RUSTUP="$(command -v rustup || echo "$HOME/.cargo/bin/rustup")"
-          dirname "$RUSTUP" >> "$GITHUB_PATH"
-          "$RUSTUP" target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android
-
-      - name: Android SDK
-        # SHA-pinned: this workflow's release job carries the signing keystore + Play service-account
-        # secrets, so a moved tag on a third-party action could exfiltrate them. v3 = 9fc6c4e.
-        uses: android-actions/setup-android@9fc6c4e9069bf8d3d10b2204b1fb8f6ef7065407 # v3
+      # Same key namespace as ci.yml/deb.yml ON PURPOSE: identical Cargo.lock, identical
+      # CARGO_HOME layout (/usr/local/cargo), so the registry/git downloads dedupe with
+      # the rest of the fleet in the central cache. target/ is deliberately NOT cached
+      # anymore — sccache covers recompilation without shipping multi-GB tars per run.
+      - name: Cache (cargo registry)
+        uses: actions/cache@v4
        with:
-          # Only platform-tools — NOT the action's default legacy `tools`, whose dependency chain
-          # drags in the ~250 MB emulator nobody here runs (instrumentation tests are deferred).
-          # That download was the single flakiest piece of this job: the shared runner fleet drops
-          # packets under parallel-job load and sdkmanager's streamed unzip turns a truncated
-          # stream into "Error on ZipFile unknown archive" (observed 2026-07-22, twice).
-          packages: platform-tools
-
-      - name: NDK r30 + platform 36 + build-tools + CMake (libopus cross-build)
-        # cmake;3.22.1 installs cmake + ninja under $ANDROID_SDK/cmake/3.22.1/bin — the exact path
-        # kit/build.gradle.kts prepends to PATH for cargo-ndk's audiopus_sys (libopus) CMake build.
-        # Note: platforms;android-37 is sometimes missing from standard channels; AGP will
-        # auto-download it if needed during the build.
-        # retry.sh: sdkmanager is a single-shot multi-hundred-MB fetch, exactly the class the
-        # helper exists for (fleet-load packet drops truncate the stream mid-unzip); a failed
-        # attempt leaves no partial package behind, so a plain re-invoke is safe.
-        run: bash scripts/ci/retry.sh 4 sdkmanager "platform-tools" "platforms;android-36" "build-tools;37.0.0" "ndk;30.0.14904198" "cmake;3.22.1"
+          path: |
+            /usr/local/cargo/registry
+            /usr/local/cargo/git
+          key: cargo-home-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-home-

-      - name: Caches (cargo + gradle)
+      - name: Cache (gradle)
        uses: actions/cache@v4
        with:
          path: |
-            ~/.cargo/registry
-            ~/.cargo/git
            ~/.gradle/caches
            ~/.gradle/wrapper
-            target
-          key: android-${{ hashFiles('Cargo.lock', 'clients/android/**/*.gradle.kts') }}
-          restore-keys: android-
-
-      - name: cargo-ndk
-        run: command -v cargo-ndk >/dev/null || cargo install cargo-ndk
+          # gradle-wrapper.properties is in the key on purpose: `~/.gradle/wrapper` caches the
+          # Gradle DISTRIBUTION, so a wrapper bump with no .gradle.kts change would otherwise
+          # restore a key that can never hold the new one. Namespace shared with
+          # android-screenshots.yml — same content, one copy in the central store.
+          key: gradle-${{ hashFiles('clients/android/**/*.gradle.kts', 'clients/android/gradle/wrapper/gradle-wrapper.properties') }}
+          restore-keys: gradle-

      - name: assembleDebug (cargo-ndk → jniLibs → APK)
        working-directory: clients/android
@@ -31,6 +31,37 @@ jobs:
    steps:
      - uses: actions/checkout@v4

+      # Publish the SIGNED stable update manifest — the moment every host's update check learns
+      # about this release (planning: host-update-from-web-console.md §3.3). Deliberately here in
+      # announce, not on the tag: the manual "fleet is green, go" gate doubles as the gate for the
+      # fleet-wide "update available". Fails the announce loudly if the key is missing (fail-closed)
+      # or the installer's live bytes don't match their .sha256 sidecar. Pre-release tags are
+      # ALWAYS skipped — an -rc must never enter the stable feed, even with allow_prerelease.
+      - name: Publish the stable update manifest
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+          UPDATE_MANIFEST_KEY: ${{ secrets.UPDATE_MANIFEST_KEY }}
+        run: |
+          set -euo pipefail
+          TAG="${{ inputs.tag }}"
+          case "$TAG" in
+            *-*) echo "pre-release tag $TAG — not publishing to the stable update feed"; exit 0 ;;
+          esac
+          VER="${TAG#v}"
+          URL="https://git.unom.io/unom/punktfunk/releases/download/${TAG}/punktfunk-host-setup-${VER}.exe"
+          # Re-download and re-hash the real bytes; the sidecar is a cross-check, never the truth.
+          curl -fsSL "$URL" -o /tmp/installer.exe
+          curl -fsSL "$URL.sha256" -o /tmp/installer.sha256
+          SHA="$(sha256sum /tmp/installer.exe | awk '{print $1}')"
+          grep -qi "$SHA" /tmp/installer.sha256 || {
+            echo "ERROR: installer sha256 $SHA does not match the release's .sha256 sidecar" >&2
+            exit 1
+          }
+          CHANNEL=stable VERSION="$VER" REQUIRE_KEY=1 \
+            WINDOWS_URL="$URL" WINDOWS_SHA256="$SHA" \
+            NOTES_URL="https://git.unom.io/unom/punktfunk/releases/tag/${TAG}" \
+            bash scripts/ci/publish-update-manifest.sh
+
      - name: Post release announcement to Discord
        env:
          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
@@ -8,13 +8,57 @@
 # them to the run as a single zip artifact (`punktfunk-appstore-screenshots`). It is isolated
 # from the build/test job and best-effort, so a capture gap never reds the core signal.
 name: apple
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  push:
    branches: [main]
+    # Scope canary builds to what this artifact is built FROM — a docs-only or
+    # web-only push should not light up the whole fleet. Applies to branch pushes;
+    # tag runs are matched by `tags:` (proven by flatpak/windows-msix releases).
+    paths:
+      - 'crates/**'
+      - 'clients/apple/**'
+      - 'scripts/build-xcframework.sh'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+      - 'rust-toolchain.toml'
+      - 'scripts/ci/**'
+      - '.gitea/workflows/apple.yml'
  pull_request:
+    paths:
+      - 'crates/**'
+      - 'clients/apple/**'
+      - 'scripts/build-xcframework.sh'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+      - 'rust-toolchain.toml'
+      - 'scripts/ci/**'
+      - '.gitea/workflows/apple.yml'
  workflow_dispatch:

+# Shared compile cache: sccache -> RustFS S3 (storage.unom.io — the mini resolves it via
+# the router, i.e. the hairpin path whose TLS always validated). Covers every cargo/rustc
+# invocation build-xcframework.sh makes, incl. the tvOS -Zbuild-std std builds; the Swift
+# side stays on DerivedData (sccache doesn't cache swiftc).
+env:
+  RUSTC_WRAPPER: sccache
+  SCCACHE_BUCKET: unom-ci-sccache
+  SCCACHE_ENDPOINT: https://storage.unom.io
+  SCCACHE_REGION: home-central
+  AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
+  AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  # sccache and incremental compilation are mutually exclusive; the shared cache makes the
+  # runner's persistent target/ disposable instead of precious.
+  CARGO_INCREMENTAL: "0"
+
 jobs:
  # SECURITY: builds/tests PULL-REQUEST code on the host-mode, persistent `macos-arm64` runner shared
  # with the release-signing job (release.yml, which loads the App Store Connect key). Untrusted PR
@@ -41,6 +85,18 @@ jobs:
          dirname "$RUSTUP" >> "$GITHUB_PATH"
          "$RUSTUP" target add aarch64-apple-darwin x86_64-apple-darwin

+      # Shared compile cache. ~/.local/bin is on the runner daemon's PATH; GITHUB_PATH is
+      # belt-and-braces. bsdtar (macOS) globs by default — no --wildcards.
+      - name: sccache (self-healing install)
+        run: |
+          if ! command -v sccache >/dev/null; then
+            mkdir -p "$HOME/.local/bin"
+            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-aarch64-apple-darwin.tar.gz \
+              | tar -xz --strip-components=1 -C "$HOME/.local/bin" '*/sccache'
+          fi
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          sccache --version
+
      # `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).
@@ -99,6 +155,18 @@ jobs:
          "$RUSTUP" target add aarch64-apple-darwin x86_64-apple-darwin \
            aarch64-apple-ios aarch64-apple-ios-sim x86_64-apple-ios

+      # Shared compile cache. ~/.local/bin is on the runner daemon's PATH; GITHUB_PATH is
+      # belt-and-braces. bsdtar (macOS) globs by default — no --wildcards.
+      - name: sccache (self-healing install)
+        run: |
+          if ! command -v sccache >/dev/null; then
+            mkdir -p "$HOME/.local/bin"
+            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-aarch64-apple-darwin.tar.gz \
+              | tar -xz --strip-components=1 -C "$HOME/.local/bin" '*/sccache'
+          fi
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          sccache --version
+
      # 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: |
@@ -115,6 +183,20 @@ jobs:
          # inherits this from the env during the xcframework build).
          echo "CMAKE_POLICY_VERSION_MINIMUM=3.5" >> "$GITHUB_ENV"

+      - name: Pin + prune DerivedData (same disease release.yml already cures)
+        # screenshots.sh builds into a throwaway mktemp DerivedData per invocation — two
+        # fresh ~1 GB trees per run, zero reuse. Pin one stable root (PF_SHOT_DERIVED_DATA,
+        # honored by the script) so repeat runs are incremental, and GC anything a week old
+        # in the default DerivedData root that no pin owns.
+        run: |
+          DD="$HOME/ci/derived-data/screenshots"
+          mkdir -p "$DD"
+          echo "PF_SHOT_DERIVED_DATA=$DD" >> "$GITHUB_ENV"
+          if [ -d "$HOME/Library/Developer/Xcode/DerivedData" ]; then
+            find "$HOME/Library/Developer/Xcode/DerivedData" -mindepth 1 -maxdepth 1 \
+              -mtime +7 -exec rm -rf {} + 2>/dev/null || true
+          fi
+
      - name: Build PunktfunkCore.xcframework (mac + iOS slices)
        run: BUILD_IOS=1 bash scripts/build-xcframework.sh

@@ -128,6 +210,10 @@ jobs:
          bash tools/screenshots.sh ipad || echo "::warning::iPad 13\" screenshots skipped"
          echo "Produced:"; ls -la screenshots || true

+      - name: Shut the Simulators down (leaked booted sims once piled up 846 deep)
+        if: always()
+        run: xcrun simctl shutdown all || true
+
      - name: Upload screenshots (zip artifact)
        if: always()
        # v3, not v4: Gitea's artifact backend identifies as GHES, which @actions/artifact v2+
@@ -14,10 +14,36 @@
 # 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
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  push:
    branches: [main]
+    # Scope canary builds to what this artifact is built FROM — a docs-only or
+    # web-only push should not light up the whole fleet. Applies to branch pushes;
+    # tag runs are matched by `tags:` (proven by flatpak/windows-msix releases).
+    paths:
+      - 'crates/**'
+      - 'clients/linux/**'
+      - 'clients/session/**'
+      - 'clients/shared/**'
+      - 'clients/cli/**'
+      - 'web/**'
+      - 'sdk/**'
+      - 'packaging/arch/**'
+      - 'packaging/gamescope/**'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+      - 'rust-toolchain.toml'
+      - 'scripts/ci/**'
+      - '.gitea/workflows/arch.yml'
    # 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.
@@ -27,27 +53,41 @@ on:
 env:
  REGISTRY: git.unom.io
  OWNER: unom
+  # Shared compile cache: sccache -> RustFS S3 (storage.unom.io). NOTE: makepkg runs
+  # behind `sudo -u builder env ...`, which strips ambient env — the makepkg step
+  # re-exports these explicitly.
+  RUSTC_WRAPPER: sccache
+  SCCACHE_BUCKET: unom-ci-sccache
+  SCCACHE_ENDPOINT: https://storage.unom.io
+  SCCACHE_REGION: home-central
+  AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
+  AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  CARGO_INCREMENTAL: "0"

 jobs:
  build-publish:
    runs-on: ubuntu-24.04
    container:
-      image: docker.io/library/archlinux:base-devel
+      # Everything the two pacman steps below used to download (~1 GB/run) is baked in,
+      # plus bun, sccache and node (ci/arch-ci.Dockerfile). The steps stay as --needed
+      # no-op guards for the one push where :latest lags an image-content change.
+      image: 192.168.1.58:5010/punktfunk-arch-ci:latest
    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
+      - name: Build + runtime-dev deps (no-op guard — baked into arch-ci)
+        # No -Syu: the image's snapshot IS the build environment (see the Dockerfile's
+        # rolling-release note); with everything installed this resolves locally and
+        # does nothing. It only matters on the push that adds a dep before the image
+        # rebuild lands — same bootstrap note as ci.yml's GTK4 step.
        run: |
-          pacman -Syu --noconfirm --needed \
+          pacman -S --noconfirm --needed \
            git nodejs rust clang cmake ninja nasm pkgconf python vulkan-headers \
            gtk4 libadwaita sdl3 ffmpeg pipewire wayland libxkbcommon opus libei \
-            mesa libglvnd unzip libarchive
-          # bun builds the punktfunk-web console + the punktfunk-scripting runner AND is vendored as
-          # their runtime (PF_WITH_WEB=1 / PF_WITH_SCRIPTING=1); it's AUR-only on Arch, so bootstrap
-          # the official binary.
+            mesa libglvnd unzip libarchive || echo "::warning::pacman guard failed (stale image db?) — proceeding with baked packages"
          command -v bun >/dev/null || {
            curl -fsSL https://bun.sh/install | bash
            install -m0755 "$HOME/.bun/bin/bun" /usr/local/bin/bun
@@ -72,11 +112,26 @@ jobs:
        # 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).
+        #
+        # The run number is ZERO-PADDED to a fixed width, and that padding is load-bearing.
+        # pacman's own vercmp compares numeric segments numerically and gets this right either
+        # way, but Gitea's Arch registry picks the version it advertises in `punktfunk-canary.db`
+        # by STRING order. Unpadded, the run counter crossing a power of ten inverts that order
+        # ("0.9907" > "0.10095" because '9' > '1'), so the db pins itself to the last build
+        # before the rollover and every later canary becomes invisible to `pacman -Syu` — the
+        # packages publish fine, the index just never names them. That is exactly what happened
+        # on 2026-07-29 when run #10000 landed; it cost an evening and needed a manual purge of
+        # every 4-digit `0.22.0-0.9xxx` version to unstick. Padding keeps string order and
+        # numeric order in agreement, so the two can never disagree again.
+        #
+        # Keep the leading `0.` — it is what sorts a canary BELOW the eventual `X.Y.Z-1` stable
+        # release. (A pkgrel is digits+dots only, so `0.` is the only prefix available; raising
+        # it to `1.` would sort canaries ABOVE the release and is not an option.)
        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 ;;
+            *)            V="$PF_BASE";  R="0.$(printf '%08d' "$GITHUB_RUN_NUMBER")";  REPO=punktfunk-canary ;;
          esac
          echo "PF_PKGVER=$V" >> "$GITHUB_ENV"
          echo "PF_PKGREL=$R" >> "$GITHUB_ENV"
@@ -106,9 +161,15 @@ jobs:
          sudo -u builder git config --global --add safe.directory "$PWD"
          mkdir -p dist && chown builder: dist
          cd packaging/arch
+          # sudo env_reset strips the ambient env, so the sccache wiring must cross the
+          # boundary explicitly (same values as the workflow env block).
          sudo -u builder env PF_SRCDIR="$GITHUB_WORKSPACE" PF_WITH_WEB=1 PF_WITH_SCRIPTING=1 \
            PF_PKGVER="$PF_PKGVER" PF_PKGREL="$PF_PKGREL" \
            CARGO_HOME="$CARGO_HOME" PKGDEST="$GITHUB_WORKSPACE/dist" \
+            RUSTC_WRAPPER="$RUSTC_WRAPPER" CARGO_INCREMENTAL="$CARGO_INCREMENTAL" \
+            SCCACHE_BUCKET="$SCCACHE_BUCKET" SCCACHE_ENDPOINT="$SCCACHE_ENDPOINT" \
+            SCCACHE_REGION="$SCCACHE_REGION" \
+            AWS_ACCESS_KEY_ID="$AWS_ACCESS_KEY_ID" AWS_SECRET_ACCESS_KEY="$AWS_SECRET_ACCESS_KEY" \
            makepkg -f -d --holdver
          ls -lh "$GITHUB_WORKSPACE/dist"

@@ -132,6 +193,7 @@ jobs:
        # failure building gamescope must not cost the packages this workflow exists to publish.
        run: |
          set -x
+          # Baked into arch-ci — a no-op guard, like the dep step above.
          pacman -S --noconfirm --needed \
            glslang libcap libdrm libinput libx11 libxcomposite libxdamage libxext \
            libxkbcommon libxmu libxrender libxres libxtst libxxf86vm libavif libdecor \
@@ -1,32 +1,64 @@
-# Supply-chain advisory scan for BOTH dependency trees the project ships to users:
+# Supply-chain advisory scan for EVERY dependency tree the project ships or publishes, plus the
+# license-allowlist gate (CRA Annex I Part II: know your components; catch a bad dep the moment
+# it lands).
 #   * cargo-audit → the (network-facing, crypto-heavy) Rust tree, against the RustSec advisory DB.
-#   * bun audit   → the web management console (Nitro/Bun BFF) — the component that holds the login
-#                   gate, session sealing, and the mgmt bearer token, so its deps matter too.
-# Triggers: weekly (catch newly-disclosed CVEs in pinned deps), on every lockfile change (catch a bad
-# dep the moment it lands), and on demand.
+#   * bun audit   → each Bun-managed tree that ships or publishes: web (the mgmt console BFF —
+#                   login gate, session sealing, mgmt bearer token), sdk (@punktfunk/host),
+#                   plugin-kit (@punktfunk/plugin-kit).
+#   * pnpm audit  → clients/decky (the Steam Deck plugin).
+#   * docs-site   → scanned NON-blocking (continue-on-error): known transitive advisories ride in
+#                   via the CMS/UI chain (@unom/ui → payload → dompurify/monaco) and the nitropack
+#                   build chain (node-tar, brace-expansion); clearing them needs coordinated bumps
+#                   verified against the LIVE site (the docs don't build standalone) — tracked in
+#                   punktfunk-planning design/cra-readiness.md. Flip to blocking once clean.
+#   * cargo-about → license-allowlist gate over BOTH Rust workspaces (about.toml `accepted`);
+#                   fails if any crate carries a license outside the allowlist — the regression
+#                   guard about.toml always promised. (The Android Gradle tree has no lockfile, so
+#                   nothing scans it — see the CRA roadmap.)
+# Triggers: weekly (catch newly-disclosed CVEs in pinned deps), on every lockfile/allowlist
+# change, and on demand.
 # To silence a known-unfixable Rust advisory, add it to `.cargo/audit.toml` ([advisories] ignore=[…]).
 name: audit
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  schedule:
    - cron: '0 6 * * 1'   # Mondays 06:00 UTC
  push:
    branches: [main]
-    paths: ['Cargo.lock', 'web/bun.lock', '.gitea/workflows/audit.yml']
+    paths:
+      - 'Cargo.lock'
+      - 'packaging/windows/drivers/Cargo.lock'
+      - 'web/bun.lock'
+      - 'docs-site/bun.lock'
+      - 'sdk/bun.lock'
+      - 'plugin-kit/bun.lock'
+      - 'clients/decky/pnpm-lock.yaml'
+      - 'about.toml'
+      - '.gitea/workflows/audit.yml'
  workflow_dispatch:

 jobs:
  cargo-audit:
    runs-on: ubuntu-24.04
    container:
-      image: git.unom.io/unom/punktfunk-rust-ci:latest
+      image: 192.168.1.58:5010/punktfunk-rust-ci:latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
      # Cache /usr/local/cargo so the cargo-audit binary (and the advisory DB clone) persist.
      - uses: actions/cache@v4
        with:
-          path: /usr/local/cargo
+          path: |
+            /usr/local/cargo/bin
+            /usr/local/cargo/registry
          key: cargo-audit-${{ hashFiles('Cargo.lock') }}
          restore-keys: cargo-audit-
      - name: cargo audit
@@ -36,13 +68,17 @@ jobs:
          cargo audit

  bun-audit:
+    strategy:
+      fail-fast: false
+      matrix:
+        tree: [web, sdk, plugin-kit]
    runs-on: ubuntu-24.04
    container:
      image: oven/bun:1
    timeout-minutes: 15
    defaults:
      run:
-        working-directory: web
+        working-directory: ${{ matrix.tree }}
    steps:
      # oven/bun's slim base lacks a CA bundle + git — actions/checkout's HTTPS fetch needs them
      # (same preamble as web-screenshots.yml / ci.yml's web job).
@@ -50,9 +86,75 @@ jobs:
        working-directory: /
        run: apt-get update && apt-get install -y --no-install-recommends ca-certificates git
      - uses: actions/checkout@v4
-      # `bun audit` queries the registry advisory DB for the versions pinned in web/bun.lock. No
-      # install/build needed — it reads the manifest + lockfile. Fails the job on any advisory, the
-      # same fail-on-vulnerability stance as cargo-audit above; triage a finding by bumping the dep
-      # (or, if genuinely unfixable + inapplicable, pinning a resolution and noting why here).
+      # `bun audit` queries the registry advisory DB for the versions pinned in the tree's
+      # bun.lock. No install/build needed — it reads the manifest + lockfile. Fails the job on any
+      # advisory, the same fail-on-vulnerability stance as cargo-audit above; triage a finding by
+      # bumping the dep (or, if genuinely unfixable + inapplicable, pinning a resolution and
+      # noting why here).
      - name: bun audit
        run: bun audit
+
+  # Kept OUT of the bun-audit matrix so this tree's known-advisory state can't normalize failure
+  # in a shipping tree. Non-blocking via a step-level `||` (NOT job-level continue-on-error, which
+  # act_runner does not reliably honor — a red job here would take the whole run red). The full
+  # advisory list still lands in the log; the warning marks it wasn't clean.
+  docs-site-audit:
+    runs-on: ubuntu-24.04
+    container:
+      image: oven/bun:1
+    timeout-minutes: 15
+    defaults:
+      run:
+        working-directory: docs-site
+    steps:
+      - name: Install git + CA certs
+        working-directory: /
+        run: apt-get update && apt-get install -y --no-install-recommends ca-certificates git
+      - uses: actions/checkout@v4
+      - name: bun audit (non-blocking)
+        run: bun audit || echo "::warning::docs-site has known advisories (CMS/UI + nitropack chains) — tracked in punktfunk-planning design/cra-readiness.md"
+
+  pnpm-audit:
+    runs-on: ubuntu-24.04
+    container:
+      image: node:22-bookworm
+    timeout-minutes: 15
+    defaults:
+      run:
+        working-directory: clients/decky
+    steps:
+      - uses: actions/checkout@v4
+      # decky is pnpm-managed (pnpm-lock.yaml lockfileVersion 9.0 → pnpm 10 reads it). Like
+      # bun audit, `pnpm audit` needs no install/build — lockfile + registry advisory DB only.
+      # --prod: rollup bundles only the prod deps into the shipped plugin; devDependencies are
+      # build tooling that never leaves CI (auditing them fails on toolchain advisories that
+      # can't reach a user — the docs-site problem in miniature).
+      - name: pnpm audit
+        run: |
+          npm install -g pnpm@10
+          pnpm audit --prod
+
+  # The regression guard about.toml documents: fail if any crate in either Rust workspace carries
+  # a license outside the `accepted` allowlist (e.g. a copyleft dep silently entering the linked
+  # set). cargo-about is version-pinned: the config uses the per-crate `accepted` syntax
+  # validated against exactly this version.
+  license-gate:
+    runs-on: ubuntu-24.04
+    container:
+      image: 192.168.1.58:5010/punktfunk-rust-ci:latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/cache@v4
+        with:
+          path: |
+            /usr/local/cargo/bin
+            /usr/local/cargo/registry
+          key: cargo-about-0.9.1
+          restore-keys: cargo-about-
+      - name: cargo about license gate (host + driver workspaces)
+        run: |
+          git config --global --add safe.directory "$PWD"
+          command -v cargo-about >/dev/null 2>&1 || cargo install --locked cargo-about --version 0.9.1 --features cli
+          cargo about generate about.hbs --fail -o /dev/null
+          cargo about generate -m packaging/windows/drivers/Cargo.toml -c about.toml about.hbs --fail -o /dev/null
@@ -0,0 +1,59 @@
+# Report-only CPU benchmarks, moved out of ci.yml: they never fail the build (shared CI
+# hardware is too noisy to gate on), so running them per-push only occupied a fleet slot
+# during fan-out storms. Nightly + on demand is exactly as much signal at none of the
+# queue cost. The tight regression gate + the real encode/stream path live on the
+# self-hosted GPU runner (Tier 3, bench-gpu.yml).
+name: bench
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  schedule:
+    - cron: '30 4 * * *'
+  workflow_dispatch:
+
+# Shared compile cache: sccache -> RustFS S3 (storage.unom.io, LAN-pinned via ci-core's
+# unbound). Keys include compiler hash + target + flags, so cross-OS/arch entries can
+# never collide; every Rust job on every host feeds and reads one warm cache.
+env:
+  RUSTC_WRAPPER: sccache
+  SCCACHE_BUCKET: unom-ci-sccache
+  SCCACHE_ENDPOINT: https://storage.unom.io
+  SCCACHE_REGION: home-central
+  AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
+  AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  # sccache and incremental compilation are mutually exclusive; CI wants the shared
+  # cache, dev boxes keep incremental.
+  CARGO_INCREMENTAL: "0"
+
+jobs:
+  bench:
+    # Tier-1 (criterion microbenchmarks) + Tier-2 (FEC loss recovery) — GPU-free, so they run here.
+    runs-on: ubuntu-24.04
+    container:
+      image: 192.168.1.58:5010/punktfunk-rust-ci:latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+
+      # Shared compile cache (sccache -> RustFS S3 over the LAN). Baked into the builder
+      # images; this fetch keeps the job green while the running :latest predates the bake.
+      - name: sccache (no-op once the image bakes it)
+        run: |
+          command -v sccache >/dev/null 2>&1 || {
+            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-x86_64-unknown-linux-musl.tar.gz \
+              | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'
+          }
+          sccache --version
+
+      - name: Prep
+        run: |
+          git config --global --add safe.directory "$PWD"
+          command -v python3 >/dev/null || { apt-get update && apt-get install -y --no-install-recommends python3; }
+      - name: Tier-1 microbenchmarks (criterion)
+        run: cargo bench -p punktfunk-core --bench pipeline -- --warm-up-time 1 --measurement-time 3
+      - name: Tier-2 FEC loss recovery (loss-harness)
+        run: cargo run -q -p loss-harness
+      - name: Compare vs baseline (report-only)
+        run: python3 scripts/bench/compare.py --threshold 0.5
@@ -1,23 +1,58 @@
-# CI for punktfunk (Gitea Actions). Linux jobs run on the `ubuntu-latest` runner; the Rust
-# job runs inside the prebuilt builder image (ci/rust-ci.Dockerfile — system FFmpeg 8,
+# CI for punktfunk (Gitea Actions). Linux jobs run on the `ubuntu-24.04` fleet label; the
+# Rust job runs inside the prebuilt builder image (ci/rust-ci.Dockerfile — system FFmpeg 8,
 # PipeWire, GL/GBM, libcuda link stub, pinned-channel rustup) so the workspace links the
-# same libs as the dev boxes. Apple client CI lives in apple.yml (macOS runner).
+# same libs as the dev boxes. Builder images come from the LAN registry on home-ci-core
+# (content-keyed, docker.yml) — never the WAN. Apple client CI lives in apple.yml (macOS
+# runner). The report-only benchmarks moved to bench.yml (nightly + dispatch) so they stop
+# occupying a fleet slot on every push.
 name: ci
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  push:
    branches: [main]
  pull_request:

+# Shared compile cache: sccache -> RustFS S3 (storage.unom.io, LAN-pinned via ci-core's
+# unbound). Keys include compiler hash + target + flags, so cross-OS/arch entries can
+# never collide; every Rust job on every host feeds and reads one warm cache.
+env:
+  RUSTC_WRAPPER: sccache
+  SCCACHE_BUCKET: unom-ci-sccache
+  SCCACHE_ENDPOINT: https://storage.unom.io
+  SCCACHE_REGION: home-central
+  AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
+  AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  # sccache and incremental compilation are mutually exclusive; CI wants the shared
+  # cache, dev boxes keep incremental.
+  CARGO_INCREMENTAL: "0"
+
 jobs:
  rust:
    runs-on: ubuntu-24.04
    container:
-      image: git.unom.io/unom/punktfunk-rust-ci:latest
+      image: 192.168.1.58:5010/punktfunk-rust-ci:latest
    timeout-minutes: 90
    steps:
      - uses: actions/checkout@v4

+      # Shared compile cache (sccache -> RustFS S3 over the LAN). Baked into the builder
+      # images; this fetch keeps the job green while the running :latest predates the bake.
+      - name: sccache (no-op once the image bakes it)
+        run: |
+          command -v sccache >/dev/null 2>&1 || {
+            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-x86_64-unknown-linux-musl.tar.gz \
+              | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'
+          }
+          sccache --version
+
      # punktfunk-client-linux link deps. Also baked into rust-ci.Dockerfile — but ci.yml
      # runs against the image from the PREVIOUS push (docker.yml bootstrap note), so this
      # keeps the job green across image-content changes; a no-op once the image has them.
@@ -125,6 +160,9 @@ jobs:
      - name: C ABI harness (standalone link proof)
        run: bash crates/punktfunk-core/tests/c/run.sh

+      - name: sccache stats (visibility only)
+        run: sccache --show-stats
+
      - name: Verify generated header is committed & up to date
        run: |
          cargo build -p punktfunk-core --locked
@@ -144,11 +182,21 @@ jobs:
  rust-arm64:
    runs-on: ubuntu-24.04
    container:
-      image: git.unom.io/unom/punktfunk-rust-ci-arm64cross:latest
+      image: 192.168.1.58:5010/punktfunk-rust-ci-arm64cross:latest
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v4

+      # Shared compile cache (sccache -> RustFS S3 over the LAN). Baked into the builder
+      # images; this fetch keeps the job green while the running :latest predates the bake.
+      - name: sccache (no-op once the image bakes it)
+        run: |
+          command -v sccache >/dev/null 2>&1 || {
+            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-x86_64-unknown-linux-musl.tar.gz \
+              | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'
+          }
+          sccache --version
+
      - name: Cache keys
        run: echo "rustc=$(rustc --version | cut -d' ' -f2)" >> "$GITHUB_ENV"
      - uses: actions/cache@v4
@@ -227,25 +275,3 @@ jobs:
        run: bun run build
      - name: Typecheck
        run: bun run lint
-
-  bench:
-    # Tier-1 (criterion microbenchmarks) + Tier-2 (FEC loss recovery) — GPU-free, so they run here.
-    # Report-only: prints the numbers + a diff vs the committed baseline to the job summary and never
-    # fails the build (shared CI hardware is too noisy to gate on). The tight regression gate + the
-    # real encode/stream path live on the self-hosted GPU runner (Tier 3, bench-gpu.yml).
-    runs-on: ubuntu-24.04
-    container:
-      image: git.unom.io/unom/punktfunk-rust-ci:latest
-    timeout-minutes: 30
-    steps:
-      - uses: actions/checkout@v4
-      - name: Prep
-        run: |
-          git config --global --add safe.directory "$PWD"
-          command -v python3 >/dev/null || { apt-get update && apt-get install -y --no-install-recommends python3; }
-      - name: Tier-1 microbenchmarks (criterion)
-        run: cargo bench -p punktfunk-core --bench pipeline -- --warm-up-time 1 --measurement-time 3
-      - name: Tier-2 FEC loss recovery (loss-harness)
-        run: cargo run -q -p loss-harness
-      - name: Compare vs baseline (report-only)
-        run: python3 scripts/bench/compare.py --threshold 0.5
@@ -23,10 +23,36 @@
 #
 # REGISTRY_TOKEN: repo Actions secret, a PAT with write:package scope (shared with docker.yml).
 name: deb
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  push:
    branches: [main]
+    # Scope canary builds to what this artifact is built FROM — a docs-only or
+    # web-only push should not light up the whole fleet. Applies to branch pushes;
+    # tag runs are matched by `tags:` (proven by flatpak/windows-msix releases).
+    paths:
+      - 'crates/**'
+      - 'clients/linux/**'
+      - 'clients/session/**'
+      - 'clients/shared/**'
+      - 'clients/cli/**'
+      - 'web/**'
+      - 'sdk/**'
+      - 'packaging/debian/**'
+      - 'packaging/linux/**'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+      - 'rust-toolchain.toml'
+      - 'scripts/ci/**'
+      - '.gitea/workflows/deb.yml'
    # Single project version: a `vX.Y.Z` tag is THE release for every platform (see
    # docs-site channels.md). The old version-shadow (a client tag shipping a host package
    # that outranked rolling builds) is now structurally impossible — main publishes to the
@@ -38,16 +64,35 @@ env:
  REGISTRY: git.unom.io
  OWNER: unom
  COMPONENT: main
+  RUSTC_WRAPPER: sccache
+  SCCACHE_BUCKET: unom-ci-sccache
+  SCCACHE_ENDPOINT: https://storage.unom.io
+  SCCACHE_REGION: home-central
+  AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
+  AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  # sccache and incremental compilation are mutually exclusive; CI wants the shared
+  # cache, dev boxes keep incremental.
+  CARGO_INCREMENTAL: "0"

 jobs:
  build-publish:
    runs-on: ubuntu-24.04
    container:
-      image: git.unom.io/unom/punktfunk-rust-ci:latest
+      image: 192.168.1.58:5010/punktfunk-rust-ci:latest
    timeout-minutes: 90
    steps:
      - uses: actions/checkout@v4

+      # Shared compile cache (sccache -> RustFS S3 over the LAN). Baked into the builder
+      # images; this fetch keeps the job green while the running :latest predates the bake.
+      - name: sccache (no-op once the image bakes it)
+        run: |
+          command -v sccache >/dev/null 2>&1 || {
+            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-x86_64-unknown-linux-musl.tar.gz \
+              | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'
+          }
+          sccache --version
+
      - name: Version + channel
        # vX.Y.Z tag -> X.Y.Z, published to the `stable` apt distribution (a real release).
        # A main push -> <next-minor>~ciN.g<sha>, published to the `canary` distribution: the '~' sorts
@@ -102,10 +147,15 @@ jobs:
          PUNKTFUNK_BUILD_VERSION: ${{ env.VERSION }}   # stamped into the binaries (build.rs)
        run: |
          git config --global --add safe.directory "$PWD"
-          # punktfunk-client-session is the Vulkan/Skia streamer the shell execs for a connect —
-          # both client binaries must ship (build-client-deb.sh installs both). The HOST is built
-          # separately in the build-publish-host job (Ubuntu 24.04 image + bundled FFmpeg 8).
-          cargo build --release --locked -p punktfunk-client-linux -p punktfunk-client-session
+          # THREE binaries ship in the client .deb, so all three are built here: the GTK shell,
+          # punktfunk-client-session (the Vulkan/Skia streamer the shell execs for a connect), and
+          # punktfunk-cli (the headless `punktfunk` front-end). build-client-deb.sh installs all
+          # three; leaving punktfunk-cli out here made it fall over on `install: No such file or
+          # directory`, because its build-if-missing guard only tested the first two and so decided
+          # everything was already built. The HOST is built separately in the build-publish-host
+          # job (Ubuntu 24.04 image + bundled FFmpeg 8).
+          cargo build --release --locked \
+            -p punktfunk-client-linux -p punktfunk-client-session -p punktfunk-cli

      - 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
@@ -184,11 +234,21 @@ jobs:
  build-publish-host:
    runs-on: ubuntu-24.04
    container:
-      image: git.unom.io/unom/punktfunk-rust-ci-noble:latest
+      image: 192.168.1.58:5010/punktfunk-rust-ci-noble:latest
    timeout-minutes: 90
    steps:
      - uses: actions/checkout@v4

+      # Shared compile cache (sccache -> RustFS S3 over the LAN). Baked into the builder
+      # images; this fetch keeps the job green while the running :latest predates the bake.
+      - name: sccache (no-op once the image bakes it)
+        run: |
+          command -v sccache >/dev/null 2>&1 || {
+            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-x86_64-unknown-linux-musl.tar.gz \
+              | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'
+          }
+          sccache --version
+
      - name: Version + channel
        run: |
          git config --global --add safe.directory "$PWD"
@@ -291,11 +351,21 @@ jobs:
  build-publish-client-arm64:
    runs-on: ubuntu-24.04
    container:
-      image: git.unom.io/unom/punktfunk-rust-ci-arm64cross:latest
+      image: 192.168.1.58:5010/punktfunk-rust-ci-arm64cross:latest
    timeout-minutes: 90
    steps:
      - uses: actions/checkout@v4

+      # Shared compile cache (sccache -> RustFS S3 over the LAN). Baked into the builder
+      # images; this fetch keeps the job green while the running :latest predates the bake.
+      - name: sccache (no-op once the image bakes it)
+        run: |
+          command -v sccache >/dev/null 2>&1 || {
+            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-x86_64-unknown-linux-musl.tar.gz \
+              | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'
+          }
+          sccache --version
+
      # Byte-identical to build-publish's version step (pf-version.sh is deterministic per
      # commit), so the arm64 package always shares the amd64 version line.
      - name: Version + channel
@@ -20,10 +20,25 @@
 #
 # REGISTRY_TOKEN: repo Actions secret, a PAT with write:package scope (shared with deb/rpm/docker).
 name: decky
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  push:
    branches: [main]
+    # Scope canary builds to what this artifact is built FROM — a docs-only or
+    # web-only push should not light up the whole fleet. Applies to branch pushes;
+    # tag runs are matched by `tags:` (proven by flatpak/windows-msix releases).
+    paths:
+      - 'clients/decky/**'
+      - 'scripts/ci/**'
+      - '.gitea/workflows/decky.yml'
    tags: ['v*']
  workflow_dispatch:

@@ -1,18 +1,37 @@
-# Build + push the dockerized pieces to the Gitea container registry:
-#   punktfunk-web      — management console (web/Dockerfile, repo-root context)
-#   punktfunk-docs     — documentation site (docs-site/Dockerfile)
-#   punktfunk-rust-ci  — Rust CI builder image consumed by ci.yml
-#   punktfunk-rust-ci-arm64cross — the above + an arm64 sysroot, for the aarch64 client legs
-#   punktfunk-fedora-rpm — Fedora 43 builder image consumed by rpm.yml (Bazzite RPM)
+# Build + push the dockerized pieces.
+#
+# Two very different image families now:
+#
+#   BUILDER images (punktfunk-rust-ci{,-noble,-arm64cross}, punktfunk-fedora{,44}-rpm)
+#     live on the LAN registry (home-ci-core, 192.168.1.58:5010 — unom/infra
+#     runners/ci-core/) and are CONTENT-KEYED: the tag is a hash of what they are built
+#     from (the ci/ tree, + rust-toolchain.toml for the cross image), and a build only
+#     happens when that key has no manifest yet. A push that doesn't touch ci/ costs one
+#     curl per image (~seconds), pushes nothing over the WAN, and mints no per-SHA tag
+#     debris on the runners — the failure mode that filled the fleet's disks. `:latest`
+#     is re-pushed alongside every new key and is what the consuming workflows pin.
+#
+#   APP images (punktfunk-web, punktfunk-docs) are deployables: they keep going to the
+#     Gitea registry (git.unom.io) with :latest + :sha-<8> (+ :vX.Y.Z on tags), because
+#     unom-1 deploys pull from there and releases pin them.
+#
 # Host and clients are intentionally NOT containerized (see CLAUDE.md "What's left").
 #
-# REGISTRY_TOKEN: repo Actions secret, a PAT with write:package scope.
+# REGISTRY_TOKEN: repo Actions secret, a PAT with write:package scope (app images only —
+# the LAN registry is unauthenticated inside the LAN).
 #
-# Bootstrap note: ci.yml's rust job pulls punktfunk-rust-ci:latest from the registry, so
-# this workflow (or a manual push) must have succeeded once before that job can run; on
-# the same push, ci.yml builds against the PREVIOUS image. All three were seeded manually
-# on 2026-06-12.
+# Bootstrap note: consuming workflows pull <LAN>/punktfunk-rust-ci:latest, so the LAN
+# registry must hold a seeded :latest once (done 2026-07-29 from the last Gitea-registry
+# images); after that, this workflow keeps :latest current whenever ci/ changes.
 name: docker
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  push:
@@ -23,9 +42,151 @@ on:
 env:
  REGISTRY: git.unom.io
  OWNER: unom
+  CI_REGISTRY: 192.168.1.58:5010

 jobs:
-  build-push:
+  builders:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 60
+    strategy:
+      matrix:
+        include:
+          - image: punktfunk-rust-ci
+            dockerfile: ci/rust-ci.Dockerfile
+          # Ubuntu 24.04 LTS host builder: same purpose as rust-ci but lowers the host .deb's glibc
+          # floor to 2.39 and bundles a from-source FFmpeg 8, so the package installs on 24.04 LTS
+          # (rust-ci's 26.04 build is uninstallable there). Consumed by deb.yml's build-publish-host job.
+          - image: punktfunk-rust-ci-noble
+            dockerfile: ci/rust-ci-noble.Dockerfile
+          - image: punktfunk-fedora-rpm
+            dockerfile: ci/fedora-rpm.Dockerfile
+          # Fedora 44 builder (Fedora KDE spin): same Dockerfile, newer base → libavcodec.so.62.
+          - image: punktfunk-fedora44-rpm
+            dockerfile: ci/fedora-rpm.Dockerfile
+            buildargs: --build-arg FEDORA_VERSION=44
+            keysuffix: -f44
+          # Android builder (JDK + SDK/NDK + cargo-ndk + sccache) — android.yml and
+          # android-screenshots.yml run in it; ~3 GB of per-run Google downloads became
+          # image layers.
+          - image: punktfunk-android-ci
+            dockerfile: ci/android-ci.Dockerfile
+          # Arch builder (base-devel + both makepkg legs' deps + bun + sccache) —
+          # arch.yml runs in it; ~1 GB of per-run pacman traffic became image layers.
+          - image: punktfunk-arch-ci
+            dockerfile: ci/arch-ci.Dockerfile
+    steps:
+      - uses: actions/checkout@v4
+
+      # The key is the git TREE HASH of ci/ — every byte any of these Dockerfiles can see
+      # (they all use ci/ as build context). One key for the whole family on purpose: a
+      # change to any of them re-keys all four, and a spurious rebuild of a sibling is
+      # cheap, rare, and infinitely better than a stale one.
+      - name: Content key
+        run: |
+          git config --global --add safe.directory "$PWD"
+          echo "KEY=ck-$(git rev-parse HEAD:ci | cut -c1-12)${{ matrix.keysuffix }}" >> "$GITHUB_ENV"
+
+      - name: Check whether this key already exists
+        id: exists
+        run: |
+          ACCEPT='Accept: application/vnd.docker.distribution.manifest.v2+json, application/vnd.oci.image.manifest.v1+json, application/vnd.oci.image.index.v1+json, application/vnd.docker.distribution.manifest.list.v2+json'
+          if curl -sf -o /dev/null -H "$ACCEPT" \
+              "http://$CI_REGISTRY/v2/${{ matrix.image }}/manifests/$KEY"; then
+            echo "hit=true" >> "$GITHUB_OUTPUT"
+            echo "::notice::${{ matrix.image }}:$KEY already in the LAN registry — nothing to build"
+          else
+            echo "hit=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build
+        if: steps.exists.outputs.hit == 'false'
+        # --pull is cheap now: base images come through the ci-core pull-through mirror.
+        run: |
+          docker build --pull ${{ matrix.buildargs }} \
+            -f "${{ matrix.dockerfile }}" \
+            -t "$CI_REGISTRY/${{ matrix.image }}:$KEY" \
+            -t "$CI_REGISTRY/${{ matrix.image }}:latest" \
+            ci
+
+      - name: Push
+        if: steps.exists.outputs.hit == 'false'
+        run: |
+          docker push "$CI_REGISTRY/${{ matrix.image }}:$KEY"
+          docker push "$CI_REGISTRY/${{ matrix.image }}:latest"
+
+      # A release pins reproducible builder images without any rebuild: copy the key's
+      # manifest to a vX.Y.Z tag via the registry API (no image bytes move).
+      - name: Tag for release
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          ACCEPT='Accept: application/vnd.docker.distribution.manifest.v2+json, application/vnd.oci.image.manifest.v1+json, application/vnd.oci.image.index.v1+json, application/vnd.docker.distribution.manifest.list.v2+json'
+          MT=$(curl -sfI -H "$ACCEPT" "http://$CI_REGISTRY/v2/${{ matrix.image }}/manifests/$KEY" \
+            | tr -d '\r' | sed -n 's/^[Cc]ontent-[Tt]ype: //p')
+          curl -sf -H "$ACCEPT" -o /tmp/manifest.json \
+            "http://$CI_REGISTRY/v2/${{ matrix.image }}/manifests/$KEY"
+          curl -sf -X PUT -H "Content-Type: $MT" --data-binary @/tmp/manifest.json \
+            "http://$CI_REGISTRY/v2/${{ matrix.image }}/manifests/$GITHUB_REF_NAME"
+
+  # The aarch64 CROSS builder — a SEPARATE job because it is `FROM punktfunk-rust-ci:latest`
+  # (the LAN copy) and so must not race the matrix entry that publishes that base. Consumed
+  # by the arm64 client legs in ci.yml/deb.yml. Its key also folds in rust-toolchain.toml:
+  # the Dockerfile installs the aarch64 target against the toolchain the workspace pins.
+  builders-arm64cross:
+    runs-on: ubuntu-24.04
+    needs: builders
+    timeout-minutes: 60
+    env:
+      IMAGE: punktfunk-rust-ci-arm64cross
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Content key
+        run: |
+          git config --global --add safe.directory "$PWD"
+          echo "KEY=ck-$(printf '%s%s' "$(git rev-parse HEAD:ci)" "$(git rev-parse HEAD:rust-toolchain.toml)" | sha256sum | cut -c1-12)" >> "$GITHUB_ENV"
+
+      - name: Check whether this key already exists
+        id: exists
+        run: |
+          ACCEPT='Accept: application/vnd.docker.distribution.manifest.v2+json, application/vnd.oci.image.manifest.v1+json, application/vnd.oci.image.index.v1+json, application/vnd.docker.distribution.manifest.list.v2+json'
+          if curl -sf -o /dev/null -H "$ACCEPT" \
+              "http://$CI_REGISTRY/v2/$IMAGE/manifests/$KEY"; then
+            echo "hit=true" >> "$GITHUB_OUTPUT"
+            echo "::notice::$IMAGE:$KEY already in the LAN registry — nothing to build"
+          else
+            echo "hit=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build
+        if: steps.exists.outputs.hit == 'false'
+        # Root context: it needs rust-toolchain.toml to install the target against the
+        # toolchain the workspace actually pins.
+        run: |
+          docker build --pull \
+            -f ci/rust-ci-arm64cross.Dockerfile \
+            -t "$CI_REGISTRY/$IMAGE:$KEY" \
+            -t "$CI_REGISTRY/$IMAGE:latest" \
+            .
+
+      - name: Push
+        if: steps.exists.outputs.hit == 'false'
+        run: |
+          docker push "$CI_REGISTRY/$IMAGE:$KEY"
+          docker push "$CI_REGISTRY/$IMAGE:latest"
+
+      - name: Tag for release
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          ACCEPT='Accept: application/vnd.docker.distribution.manifest.v2+json, application/vnd.oci.image.manifest.v1+json, application/vnd.oci.image.index.v1+json, application/vnd.docker.distribution.manifest.list.v2+json'
+          MT=$(curl -sfI -H "$ACCEPT" "http://$CI_REGISTRY/v2/$IMAGE/manifests/$KEY" \
+            | tr -d '\r' | sed -n 's/^[Cc]ontent-[Tt]ype: //p')
+          curl -sf -H "$ACCEPT" -o /tmp/manifest.json \
+            "http://$CI_REGISTRY/v2/$IMAGE/manifests/$KEY"
+          curl -sf -X PUT -H "Content-Type: $MT" --data-binary @/tmp/manifest.json \
+            "http://$CI_REGISTRY/v2/$IMAGE/manifests/$GITHUB_REF_NAME"
+
+  # Deployable app images — unchanged flow, Gitea registry, per-SHA + release tags.
+  apps:
    runs-on: ubuntu-24.04
    timeout-minutes: 45
    strategy:
@@ -37,23 +198,6 @@ jobs:
          - image: punktfunk-docs
            dockerfile: docs-site/Dockerfile
            context: docs-site
-          - image: punktfunk-rust-ci
-            dockerfile: ci/rust-ci.Dockerfile
-            context: ci
-          # Ubuntu 24.04 LTS host builder: same purpose as rust-ci but lowers the host .deb's glibc
-          # floor to 2.39 and bundles a from-source FFmpeg 8, so the package installs on 24.04 LTS
-          # (rust-ci's 26.04 build is uninstallable there). Consumed by deb.yml's build-publish-host job.
-          - image: punktfunk-rust-ci-noble
-            dockerfile: ci/rust-ci-noble.Dockerfile
-            context: ci
-          - image: punktfunk-fedora-rpm
-            dockerfile: ci/fedora-rpm.Dockerfile
-            context: ci
-          # Fedora 44 builder (Fedora KDE spin): same Dockerfile, newer base → libavcodec.so.62.
-          - image: punktfunk-fedora44-rpm
-            dockerfile: ci/fedora-rpm.Dockerfile
-            context: ci
-            buildargs: --build-arg FEDORA_VERSION=44
    steps:
      - uses: actions/checkout@v4

@@ -68,7 +212,7 @@ jobs:
          # On a release tag, also tag the image vX.Y.Z so a release pins reproducible web/docs images.
          EXTRA=""
          case "$GITHUB_REF" in refs/tags/v*) EXTRA="-t $REGISTRY/$OWNER/${{ matrix.image }}:${GITHUB_REF_NAME}" ;; esac
-          docker build --pull ${{ matrix.buildargs }} \
+          docker build --pull \
            -f "${{ matrix.dockerfile }}" \
            -t "$REGISTRY/$OWNER/${{ matrix.image }}:latest" \
            -t "$REGISTRY/$OWNER/${{ matrix.image }}:sha-${GITHUB_SHA::8}" \
@@ -81,48 +225,13 @@ jobs:
          docker push "$REGISTRY/$OWNER/${{ matrix.image }}:latest"
          case "$GITHUB_REF" in refs/tags/v*) docker push "$REGISTRY/$OWNER/${{ matrix.image }}:${GITHUB_REF_NAME}" ;; esac

-  # The aarch64 CROSS builder — a SEPARATE job because it is `FROM punktfunk-rust-ci:latest`
-  # and so must not race the matrix entry that publishes that base. Consumed by the arm64
-  # client legs in deb.yml/rpm.yml/arch.yml. Root context: it needs rust-toolchain.toml to
-  # install the target against the toolchain the workspace actually pins.
-  build-push-arm64cross:
-    runs-on: ubuntu-24.04
-    needs: build-push
-    timeout-minutes: 45
-    env:
-      IMAGE: punktfunk-rust-ci-arm64cross
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Login to registry
-        run: |
-          echo "${{ secrets.REGISTRY_TOKEN }}" \
-            | docker login "$REGISTRY" -u enricobuehler --password-stdin
-
-      - name: Build
-        run: |
-          EXTRA=""
-          case "$GITHUB_REF" in refs/tags/v*) EXTRA="-t $REGISTRY/$OWNER/$IMAGE:${GITHUB_REF_NAME}" ;; esac
-          docker build --pull \
-            -f ci/rust-ci-arm64cross.Dockerfile \
-            -t "$REGISTRY/$OWNER/$IMAGE:latest" \
-            -t "$REGISTRY/$OWNER/$IMAGE:sha-${GITHUB_SHA::8}" \
-            $EXTRA \
-            .
-
-      - name: Push
-        run: |
-          docker push "$REGISTRY/$OWNER/$IMAGE:sha-${GITHUB_SHA::8}"
-          docker push "$REGISTRY/$OWNER/$IMAGE:latest"
-          case "$GITHUB_REF" in refs/tags/v*) docker push "$REGISTRY/$OWNER/$IMAGE:${GITHUB_REF_NAME}" ;; esac
-
  # Deploy the docs site to unom-1, the DMZ services VM website/cms also deploy to
  # (docs.punktfunk.unom.io via Caddy on home-reverse-proxy-1 -> :3220). Same secret set
  # as unom/website's deploy: DEPLOY_HOST/DEPLOY_USER/DEPLOY_PORT/DEPLOY_SSH_KEY (the
  # unom-ci-deploy key).
  deploy-docs:
    runs-on: ubuntu-24.04
-    needs: build-push
+    needs: apps
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
@@ -19,6 +19,14 @@
 #
 # REGISTRY_TOKEN: repo Actions secret, a PAT with write:package scope (shared with deb/rpm/docker).
 name: flatpak
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  push:
@@ -56,8 +64,19 @@ jobs:
    container:
      # Fedora ships a recent flatpak + flatpak-builder + the kernel userns support.
      # --privileged is required for bubblewrap inside the Docker executor (see header).
+      #
+      # --network host is what finally fixed the years-long "Could not resolve
+      # hostname" on every flathub fetch. MEASURED 2026-07-30 on home-runner-2, all
+      # in ONE container: `getent hosts dl.flathub.org` resolved, `curl` got HTTP
+      # 200 (both auto and -4), and flatpak still failed error [6] — so it was never
+      # DNS config, the resolver, the docker version, or the per-job network. It is
+      # ostree's own resolver refusing to work through Docker's embedded 127.0.0.11
+      # (proven: rewriting resolv.conf to a real nameserver did NOT help, and the
+      # default bridge failed too, while the host netns — no embedded resolver in the
+      # path at all — works every time). Host networking also means this job no
+      # longer needs the nsswitch surgery below to be lucky.
      image: fedora:43
-      options: --privileged
+      options: --privileged --network host
    steps:
      # DNS fix — MUST run before any network step. fedora:43's nsswitch.conf is
      # `hosts: files myhostname resolve [!UNAVAIL=return] dns`: the `resolve`
@@ -127,6 +146,25 @@ jobs:
            https://dl.flathub.org/repo/flathub.flatpakrepo
          git config --global --add safe.directory "$PWD"

+      # This job was the fleet's single heaviest network consumer: every run re-downloaded
+      # the GNOME runtime + SDK + llvm/rust/ffmpeg extensions (multi-GB from Flathub) and
+      # every crate source. Both live in well-defined directories, both are idempotently
+      # verified/extended by the steps below, and the central cache server restores them
+      # at LAN speed — so cache them. Keyed on what actually pins them: the manifest tree
+      # (runtimes/extensions) and manifest+Cargo.lock (crate sources + builder state).
+      - name: Cache Flathub runtimes
+        uses: actions/cache@v4
+        with:
+          path: ~/.local/share/flatpak
+          key: flatpak-runtimes-${{ hashFiles('packaging/flatpak/**') }}
+          restore-keys: flatpak-runtimes-
+      - name: Cache flatpak-builder state (crate sources, ccache)
+        uses: actions/cache@v4
+        with:
+          path: .flatpak-builder
+          key: flatpak-builder-state-${{ hashFiles('Cargo.lock', 'packaging/flatpak/**') }}
+          restore-keys: flatpak-builder-state-
+
      - name: Version + channel
        # Tag vX.Y.Z -> X.Y.Z on the OSTree `stable` branch (a real release); a main push ->
        # <next-minor>-ciN.g<sha> on the `canary` branch (base one minor ahead of the latest stable
@@ -5,23 +5,55 @@
 # 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
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  push:
    tags: ["v*"]
  workflow_dispatch:

+# Shared compile cache: sccache -> RustFS S3 (storage.unom.io, LAN-pinned via ci-core's
+# unbound). Keys include compiler hash + target + flags, so cross-OS/arch entries can
+# never collide; every Rust job on every host feeds and reads one warm cache.
+env:
+  RUSTC_WRAPPER: sccache
+  SCCACHE_BUCKET: unom-ci-sccache
+  SCCACHE_ENDPOINT: https://storage.unom.io
+  SCCACHE_REGION: home-central
+  AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
+  AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  # sccache and incremental compilation are mutually exclusive; CI wants the shared
+  # cache, dev boxes keep incremental.
+  CARGO_INCREMENTAL: "0"
+
 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
+      image: 192.168.1.58:5010/punktfunk-rust-ci:latest
    timeout-minutes: 90
    steps:
      - uses: actions/checkout@v4

+      # Shared compile cache (sccache -> RustFS S3 over the LAN). Baked into the builder
+      # images; this fetch keeps the job green while the running :latest predates the bake.
+      - name: sccache (no-op once the image bakes it)
+        run: |
+          command -v sccache >/dev/null 2>&1 || {
+            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-x86_64-unknown-linux-musl.tar.gz \
+              | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'
+          }
+          sccache --version
+
      # 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
@@ -9,6 +9,14 @@
 #
 # Auth: REGISTRY_TOKEN — the same repo Actions secret sdk-publish.yml uses.
 name: plugin-kit-publish
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  push:
@@ -56,6 +56,14 @@
 # picks the first non-beta /Applications/Xcode*.app and only falls back to a beta with a
 # loud warning.
 name: release
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  push:
@@ -80,6 +88,21 @@ on:
        required: false
        default: "true"

+# Shared compile cache: sccache -> RustFS S3 (storage.unom.io — the mini resolves it via
+# the router, i.e. the hairpin path whose TLS always validated). Covers every cargo/rustc
+# invocation build-xcframework.sh makes, incl. the tvOS -Zbuild-std std builds; the Swift
+# side stays on DerivedData (sccache doesn't cache swiftc).
+env:
+  RUSTC_WRAPPER: sccache
+  SCCACHE_BUCKET: unom-ci-sccache
+  SCCACHE_ENDPOINT: https://storage.unom.io
+  SCCACHE_REGION: home-central
+  AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
+  AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  # sccache and incremental compilation are mutually exclusive; the shared cache makes the
+  # runner's persistent target/ disposable instead of precious.
+  CARGO_INCREMENTAL: "0"
+
 jobs:
  apple:
    runs-on: macos-arm64
@@ -149,6 +172,18 @@ jobs:
          # inherits this from the env during the xcframework build).
          echo "CMAKE_POLICY_VERSION_MINIMUM=3.5" >> "$GITHUB_ENV"

+      # Shared compile cache. ~/.local/bin is on the runner daemon's PATH; GITHUB_PATH is
+      # belt-and-braces. bsdtar (macOS) globs by default — no --wildcards.
+      - name: sccache (self-healing install)
+        run: |
+          if ! command -v sccache >/dev/null; then
+            mkdir -p "$HOME/.local/bin"
+            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-aarch64-apple-darwin.tar.gz \
+              | tar -xz --strip-components=1 -C "$HOME/.local/bin" '*/sccache'
+          fi
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          sccache --version
+
      - name: Pin + prune Xcode DerivedData
        # Without -derivedDataPath, xcodebuild derives its DerivedData directory name from the
        # PROJECT'S ABSOLUTE PATH — and act_runner rotates its workspace
@@ -9,10 +9,33 @@
 #
 # REGISTRY_TOKEN: repo Actions secret, a PAT with write:package scope (shared with docker.yml).
 name: rpm
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  push:
    branches: [main]
+    # Scope canary builds to what this artifact is built FROM — a docs-only or
+    # web-only push should not light up the whole fleet. Applies to branch pushes;
+    # tag runs are matched by `tags:` (proven by flatpak/windows-msix releases).
+    paths:
+      - 'crates/**'
+      - 'web/**'
+      - 'sdk/**'
+      - 'packaging/rpm/**'
+      - 'packaging/gamescope/**'
+      - 'packaging/bazzite/**'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+      - 'rust-toolchain.toml'
+      - 'scripts/ci/**'
+      - '.gitea/workflows/rpm.yml'
    # Single project version: a `vX.Y.Z` tag is THE release. main publishes to the `*-canary` rpm
    # groups, tags to the base groups (`bazzite`/`fedora-44`) — separate repos, so the old
    # version-shadow (a release outranking rolling builds in one group) is structurally gone.
@@ -22,6 +45,15 @@ on:
 env:
  REGISTRY: git.unom.io
  OWNER: unom
+  RUSTC_WRAPPER: sccache
+  SCCACHE_BUCKET: unom-ci-sccache
+  SCCACHE_ENDPOINT: https://storage.unom.io
+  SCCACHE_REGION: home-central
+  AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
+  AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  # sccache and incremental compilation are mutually exclusive; CI wants the shared
+  # cache, dev boxes keep incremental.
+  CARGO_INCREMENTAL: "0"

 jobs:
  build-publish:
@@ -40,13 +72,23 @@ jobs:
            group: fedora-44
            fedver: 44
    container:
-      image: git.unom.io/unom/${{ matrix.image }}:latest
+      image: 192.168.1.58:5010/${{ matrix.image }}:latest
    timeout-minutes: 90
    env:
      CARGO_HOME: /usr/local/cargo
    steps:
      - uses: actions/checkout@v4

+      # Shared compile cache (sccache -> RustFS S3 over the LAN). Baked into the builder
+      # images; this fetch keeps the job green while the running :latest predates the bake.
+      - name: sccache (no-op once the image bakes it)
+        run: |
+          command -v sccache >/dev/null 2>&1 || {
+            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-x86_64-unknown-linux-musl.tar.gz \
+              | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'
+          }
+          sccache --version
+
      # rpmbuild + git archive need the checkout trusted; cache the crates download.
      # The client link deps are also baked into the fedora-rpm image, but this job runs
      # against the image from the PREVIOUS push (docker.yml bootstrap note) — keep it
@@ -75,8 +117,8 @@ jobs:
      - uses: actions/cache@v4
        with:
          path: /usr/local/cargo/registry
-          key: cargo-home-${{ hashFiles('Cargo.lock') }}
-          restore-keys: cargo-home-
+          key: cargo-home-fedora-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-home-fedora-

      - name: Version + channel
        # vX.Y.Z tag -> X.Y.Z-1 in the base group (a real release); main push -> <next-minor>-0.ciN.g<sha>
@@ -102,7 +144,9 @@ jobs:
        # Recommends both). Both need bun (ensured in Prep).
        run: PF_VERSION="$PF_VERSION" PF_RELEASE="$PF_RELEASE" PF_WITH_WEB=1 PF_WITH_SCRIPTING=1 bash packaging/rpm/build-rpm.sh

-      - name: Sign RPMs (dormant until RPM_GPG_PRIVATE_KEY is set — see packaging/rpm/README.md)
+      # Signs with packages@unom.io (org secret) and self-verifies before publish. On a v* tag a
+      # missing key FAILS the build rather than publishing unsigned RPMs into a gpgcheck=1 repo.
+      - name: Sign RPMs
        env:
          RPM_GPG_PRIVATE_KEY: ${{ secrets.RPM_GPG_PRIVATE_KEY }}
          RPM_GPG_PASSPHRASE: ${{ secrets.RPM_GPG_PASSPHRASE }}
@@ -189,16 +233,27 @@ jobs:
            dist/punktfunk-web-"${PF_VERSION}-${PF_RELEASE}"*.rpm \
            dist/punktfunk-scripting-"${PF_VERSION}-${PF_RELEASE}"*.rpm

+      # The feed's SHA256SUMS is OpenPGP-signed with the same packages@unom.io key as the RPMs, and
+      # punktfunk-sysext(8) refuses a feed it can't verify — the checksums alone never proved
+      # anything, sitting on the same registry as the images they describe.
      - name: Publish the sysext feed
        env:
          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+          RPM_GPG_PRIVATE_KEY: ${{ secrets.RPM_GPG_PRIVATE_KEY }}
        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
+            *-canary) FEED="f${{ matrix.fedver }}-canary"; KEEP=6; OTHER="f${{ matrix.fedver }}" ;;
+            *)        FEED="f${{ matrix.fedver }}";        KEEP=0; OTHER="f${{ matrix.fedver }}-canary" ;;
          esac
          KEEP=$KEEP bash packaging/bazzite/publish-sysext-feed.sh "$FEED" \
            "dist-sysext/punktfunk-${PF_VERSION}-${PF_RELEASE}-x86-64.raw"
+          # Re-seal this Fedora major's OTHER channel too. Stable feeds only publish on a tag, so
+          # without this a stable box would sit in front of an unsigned (hence refused) feed until
+          # the next release; canary pushes are frequent, so every live feed gets sealed within a
+          # day of this landing, and a key rotation propagates without rebuilding any image.
+          # Best-effort: a channel that has never published yet has no manifest to seal.
+          bash packaging/bazzite/publish-sysext-feed.sh --seal "$OTHER" \
+            || echo "::warning::could not seal the $OTHER feed (no manifest yet?)"

      # 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
@@ -0,0 +1,68 @@
+# Per-release SBOM (CRA Annex I Part II §1: identify and document the components in the product,
+# in a commonly used machine-readable format — we emit CycloneDX JSON).
+#
+# Tag push → the SBOM is attached to the Gitea release, next to the artifacts it describes.
+# Release assets are never pruned (security updates must stay available ≥10 years, CRA Art. 13),
+# so the SBOM's retention rides on the release's.
+# workflow_dispatch on a non-tag ref → generated and uploaded as a workflow artifact only
+# (pipeline validation / an on-demand snapshot); no release is touched.
+#
+# What goes in: scripts/ci/gen-sbom.sh = syft over the checkout (every lockfile-pinned dep in
+# both Rust workspaces + the JS trees + Swift Package.resolved) merged with
+# compliance/sbom/manual-components.cdx.json (vendored C/C++, bundled DLLs, VB-CABLE, gamescope).
+name: sbom
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+jobs:
+  sbom:
+    runs-on: ubuntu-24.04
+    container:
+      image: 192.168.1.58:5010/punktfunk-rust-ci:latest
+    timeout-minutes: 20
+    steps:
+      # fetch-depth 0: the dispatch path derives the canary base from the tag history
+      # (scripts/ci/pf-version.sh), which a shallow clone cannot see.
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      # Pinned syft (keep in sync with the version validated against this repo; bump deliberately).
+      - name: Install syft
+        run: |
+          curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh \
+            | sh -s -- -b /usr/local/bin v1.49.0
+      - name: Generate SBOM
+        run: |
+          git config --global --add safe.directory "$PWD"
+          case "$GITHUB_REF" in
+            refs/tags/v*) VERSION="${GITHUB_REF_NAME#v}" ;;
+            *) eval "$(bash scripts/ci/pf-version.sh)"; VERSION="${PF_BASE}-snapshot" ;;
+          esac
+          sh scripts/ci/gen-sbom.sh "$VERSION" "punktfunk-${VERSION}.cdx.json"
+          echo "SBOM_FILE=punktfunk-${VERSION}.cdx.json" >> "$GITHUB_ENV"
+      - name: Attach to release
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          . scripts/ci/gitea-release.sh
+          RID=$(ensure_release "$GITHUB_REF_NAME" "$GITHUB_REF_NAME" auto)
+          upsert_asset "$RID" "$SBOM_FILE"
+      # v3, not v4: Gitea's artifact backend rejects upload-artifact@v4 (see release.yml).
+      - name: Upload artifact (non-tag runs)
+        if: "!startsWith(github.ref, 'refs/tags/')"
+        uses: actions/upload-artifact@v3
+        with:
+          name: sbom
+          path: punktfunk-*.cdx.json
@@ -7,6 +7,14 @@
 # Auth: REGISTRY_TOKEN — the same repo Actions secret docker.yml uses (a Gitea PAT with
 # write:package scope). No new secret needed.
 name: sdk-publish
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  push:
@@ -6,6 +6,14 @@
 # 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
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  push:
@@ -11,6 +11,14 @@
 # shell: pwsh deliberately (PowerShell 5.1's Out-File -Encoding utf8 prepends a BOM that corrupts the
 # first GITHUB_ENV line — see windows.yml).
 name: windows-drivers
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  workflow_dispatch:
@@ -22,7 +22,9 @@
 #
 # 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.
+# (import once to LocalMachine\TrustedPublisher). That fallback is for canary/CI ONLY — on a v* tag
+# the pack script FAILS CLOSED rather than ship a release signed by a per-build throwaway cert.
+# See packaging/windows/pack-host-installer.ps1.
 #
 # GPU backends: the host builds with --features nvenc,amf-qsv,qsv = all three vendors in one installer.
 #  - NVENC (NVIDIA, direct SDK): nothing needed at build time — the entry points are resolved at
@@ -38,6 +40,14 @@
 #    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
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  push:
@@ -81,6 +91,15 @@ env:
  REGISTRY: git.unom.io
  OWNER: unom
  PKG: punktfunk-host-windows
+  RUSTC_WRAPPER: sccache
+  SCCACHE_BUCKET: unom-ci-sccache
+  SCCACHE_ENDPOINT: https://storage.unom.io
+  SCCACHE_REGION: home-central
+  AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
+  AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  # sccache and incremental compilation are mutually exclusive; CI wants the shared
+  # cache, dev boxes keep incremental.
+  CARGO_INCREMENTAL: "0"

 jobs:
  package:
@@ -113,10 +132,9 @@ jobs:
        shell: pwsh
        run: |
          # CARGO_TARGET_DIR=C:\t dodges the MAX_PATH wall in the CMake-from-source crates (aws-lc,
-          # opus) the host pulls; CARGO_WORKSPACE_DIR mirrors the client workflows. Both via GITHUB_ENV
-          # (pwsh Out-File utf8 = no BOM, unlike Windows PowerShell 5.1 — keeps the first line clean).
+          # opus) the host pulls; via GITHUB_ENV (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
          # audiopus_sys' vendored opus declares cmake_minimum_required < 3.5, which CMake 4.x
          # refuses outright. Green runs today only survive on the cached configure output — a
          # target-dir purge (the runner's disk-cleanup task) would fail the fresh configure, as
@@ -258,6 +276,18 @@ jobs:
          cargo clippy --release -- -D warnings; if ($LASTEXITCODE) { throw "pf-vkhdr-layer clippy" }
          Pop-Location

+      # The console output is fully self-contained (Nitro noExternals) and most pushes
+      # don't touch web/ or sdk/ — restore it from the central cache and skip the ~2.5 min
+      # bun build+smoke entirely on a hit. First workflow on this runner to use the
+      # actions cache at all (the runner's config.yaml needed cache.external_server —
+      # see unom/infra runners/ci-core/README.md).
+      - name: Cache web console output
+        id: webconsole
+        uses: actions/cache@v4
+        with:
+          path: web/.output
+          key: web-console-win-${{ hashFiles('web/**', 'sdk/**') }}
+
      - name: Fetch portable bun runtime (build tool + bundled to run the console)
        shell: pwsh
        run: |
@@ -277,6 +307,7 @@ jobs:
          & $bun --version

      - name: Build + smoke-boot web console (bun)
+        if: steps.webconsole.outputs.cache-hit != 'true'
        shell: pwsh
        env:
          # PAT with read access to the unom org packages — the @unom npm registry needs auth to BUILD.
@@ -294,7 +325,15 @@ jobs:
            Add-Content -Path $rc -Value "//git.unom.io/api/packages/unom/npm/:_authToken=$env:REGISTRY_TOKEN"
          }
          Push-Location web
-          & $bun install --frozen-lockfile; if ($LASTEXITCODE) { throw "bun install failed ($LASTEXITCODE)" }
+          # `--ignore-scripts` like every other web install in CI (ci.yml, web-screenshots.yml,
+          # sdk/plugin-kit-publish, and the SDK install further down this same file). This step was
+          # the one site that ran lifecycle scripts, and web's `postinstall` is `bun2nix -o bun.nix`
+          # — a NIX codegen step that shells out to `bun` on PATH. CI runs a fetched PORTABLE bun by
+          # absolute path (`$env:BUN_EXE`), so PATH has none, and bun2nix aborted the install:
+          #   error: bun is not installed in %PATH% ... postinstall script exited with 255
+          # Nothing here needs those scripts — `build` re-runs its own `prebuild` codegen — and
+          # bun.nix is a Nix artifact this job neither consumes nor commits.
+          & $bun install --frozen-lockfile --ignore-scripts; if ($LASTEXITCODE) { throw "bun install failed ($LASTEXITCODE)" }
          & $bun run build; if ($LASTEXITCODE) { throw "web build failed ($LASTEXITCODE)" }
          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"
@@ -309,6 +348,21 @@ jobs:
          Stop-Process -Id $p.Id -Force -ErrorAction SilentlyContinue
          Write-Output "web console smoke (bun): /login -> $code"
          if ($code -ne 200) { throw "web console failed to boot under bun" }
+
+      # WEB_OUTPUT_DIR has to be exported whether or not the step above ran. It used to be that step's
+      # last line, so a CACHE HIT skipped it and left the variable unset — and pack-host-installer.ps1
+      # treats an unset WEB_OUTPUT_DIR as "don't bundle the console", silently ("installer built
+      # WITHOUT the web console"). That shipped in 0.22.1 and 0.22.2: no {app}\web, so no web-run.cmd,
+      # so `web setup` bails, so no PunktfunkWeb task and no console at all. It also removed the only
+      # thing that stopped bun before the copy (StopBunRuntimes was #ifdef WithWeb), while bun.exe kept
+      # shipping under WithScripting — which is the "DeleteFile failed; code 5" modal on bun.exe.
+      # The throw is the point: never silently ship a console-less installer again.
+      - name: Export the console output dir (cache hit or fresh build)
+        shell: pwsh
+        run: |
+          if (-not (Test-Path 'web\.output\server\index.mjs')) {
+            throw "web\.output is missing - neither the cache restore nor the build produced it, and the installer must not ship without the console"
+          }
          "WEB_OUTPUT_DIR=$((Resolve-Path 'web\.output').Path)" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8

      - name: Build plugin/script runner bundle (bun)
@@ -329,11 +383,52 @@ jobs:
          }
          "SCRIPTING_BUNDLE=C:\t\scripting\runner-cli.js" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8

+      # NOT cached, and it must stay that way: the UMDF drivers build IN-TREE inside the pack
+      # step (a relocated CARGO_TARGET_DIR breaks wdk-build's manifest walk), and act rotates
+      # the job workspace path (~/.cache/act/<hash>/hostexecutor) between runs. A cargo target
+      # dir restored under a DIFFERENT absolute path brings state that points at the old one:
+      # measured 2026-07-30, `pf-umdf-util` died with 14 × "unable to create file lock (os
+      # error 3)" and took the whole job with it. ~1 min of rebuild is the correct price; the
+      # same rotation is why the other Windows jobs use a fixed C:\t instead of a cached
+      # workspace-relative target.
+      # Every payload this job is SUPPOSED to bundle, asserted before packing. The packer treats each
+      # one as optional — correct for a local debug pack, and the reason 0.22.1/0.22.2 shipped with no
+      # web console: an unset WEB_OUTPUT_DIR omitted it behind a single Write-Host. CI knows it bundles
+      # all of these, so here a missing input is a build failure rather than a quietly smaller
+      # installer. (pack-host-installer.ps1 already does this for VB-CABLE, for the same reason.)
+      - name: Verify every installer payload is present
+        shell: pwsh
+        run: |
+          $need = @(
+            @{ n = 'web console (WEB_OUTPUT_DIR)';    p = $env:WEB_OUTPUT_DIR;   f = 'server\index.mjs' }
+            @{ n = 'bun runtime (BUN_EXE)';           p = $env:BUN_EXE;          f = '' }
+            @{ n = 'plugin runner (SCRIPTING_BUNDLE)';p = $env:SCRIPTING_BUNDLE; f = '' }
+            @{ n = 'FFmpeg DLLs (FFMPEG_DIR\bin)';    p = $env:FFMPEG_DIR;       f = 'bin' }
+            @{ n = 'VB-CABLE (VBCABLE_DIR)';          p = $env:VBCABLE_DIR;      f = 'VBCABLE_Setup_x64.exe' }
+          )
+          $missing = @()
+          foreach ($x in $need) {
+            if (-not $x.p) { $missing += "$($x.n): env var not set"; continue }
+            $full = if ($x.f) { Join-Path $x.p $x.f } else { $x.p }
+            if (-not (Test-Path $full)) { $missing += "$($x.n): missing $full" }
+            else { Write-Output "payload OK - $($x.n) -> $full" }
+          }
+          if ($missing.Count) {
+            $missing | ForEach-Object { Write-Output "MISSING PAYLOAD - $_" }
+            throw "$($missing.Count) installer payload(s) missing - refusing to ship an incomplete installer"
+          }
+
      - name: Pack + sign installer
        shell: pwsh
        env:
          MSIX_CERT_PFX_B64: ${{ secrets.MSIX_CERT_PFX_B64 }}
          MSIX_CERT_PASSWORD: ${{ secrets.MSIX_CERT_PASSWORD }}
+          # The DRIVER cert is separate from the host/MSIX one and reaches the two driver build
+          # scripts through the environment (pack-host-installer.ps1 invokes them, they read
+          # $env:DRIVER_CERT_PFX_B64 themselves). Without it they sign with a per-build throwaway,
+          # which the installer then trusts as a machine root — see packaging/windows/README.md.
+          DRIVER_CERT_PFX_B64: ${{ secrets.DRIVER_CERT_PFX_B64 }}
+          DRIVER_CERT_PASSWORD: ${{ secrets.DRIVER_CERT_PASSWORD }}
        run: |
          & packaging/windows/pack-host-installer.ps1 `
            -Version $env:HOST_VERSION -TargetDir C:\t\release -OutDir C:\t\out
@@ -407,6 +502,36 @@ jobs:
  # A separate Linux job, not another step in `package`: the deploy actions are Docker-based and do
  # not run on a Windows runner. `needs: package` also gives the ordering that matters — build-data
  # reads the manifests from the release, so it must not run before they are attached.
+  # Publish the SIGNED canary update manifest after the canary installer lands (planning:
+  # host-update-from-web-console.md §3.3 — canary rides this workflow because the installer is
+  # the only artifact the manifest references by URL; other canary channels may trail by minutes,
+  # which the per-PM apply path tolerates). A Linux job: the signer is bash+openssl. Skips (with
+  # a warning) when UPDATE_MANIFEST_KEY is absent — a canary build must not fail over it.
+  canary-manifest:
+    needs: package
+    if: gitea.ref == 'refs/heads/main'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Publish the canary update manifest
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+          UPDATE_MANIFEST_KEY: ${{ secrets.UPDATE_MANIFEST_KEY }}
+        run: |
+          set -euo pipefail
+          # Same derivation the package job used: canary = <next-minor base>'s major.minor + run#.
+          eval "$(bash scripts/ci/pf-version.sh)"
+          VER="${PF_MAJOR}.${PF_MINOR}.${GITHUB_RUN_NUMBER}"
+          URL="https://${REGISTRY}/api/packages/${OWNER}/generic/${PKG}/${VER}/punktfunk-host-setup-${VER}.exe"
+          curl -fsSL "$URL" -o /tmp/installer.exe
+          SHA="$(sha256sum /tmp/installer.exe | awk '{print $1}')"
+          CHANNEL=canary VERSION="$VER" CI_RUN="${GITHUB_RUN_NUMBER}" \
+            WINDOWS_URL="$URL" WINDOWS_SHA256="$SHA" \
+            NOTES_URL="https://git.unom.io/unom/punktfunk/releases" \
+            bash scripts/ci/publish-update-manifest.sh
+
  winget-source:
    needs: package
    if: startsWith(gitea.ref, 'refs/tags/v')
@@ -21,12 +21,23 @@
 #                Published to the generic registry + the `canary/` alias.
 # Both arches share the version; artifacts are arch-suffixed (..._x64.msix / ..._arm64.msix).
 #
-# Signing (packaging/pack-msix.ps1): if the MSIX_CERT_PFX_B64 / MSIX_CERT_PASSWORD Actions secrets
-# are set (a real or shared code-signing .pfx whose subject DN == Publisher), the package is signed
-# with them. Otherwise an ephemeral self-signed cert is generated and its public .cer is published
-# next to the .msix (users import it to Trusted People before install). Drop in a real cert later
-# with no workflow change — just add the secrets (+ pass -Publisher if its subject differs).
+# Signing (clients/windows/packaging/pack-msix.ps1): if the MSIX_CERT_PFX_B64 / MSIX_CERT_PASSWORD
+# Actions secrets are set (a real or shared code-signing .pfx whose subject DN == Publisher), the
+# package is signed with them. Otherwise an ephemeral self-signed cert is generated and its public
+# .cer is published next to the .msix (users import it to Trusted People before install).
+#
+# That fallback is for canary/CI ONLY. On a v* tag the pack script FAILS CLOSED — a missing secret
+# aborts the build instead of quietly shipping a release signed by a per-build throwaway cert that
+# no one can pin. Nothing to opt into here: the script reads GITHUB_REF itself.
 name: windows-msix
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  push:
@@ -49,6 +60,15 @@ env:
  REGISTRY: git.unom.io
  OWNER: unom
  PKG: punktfunk-client-windows
+  RUSTC_WRAPPER: sccache
+  SCCACHE_BUCKET: unom-ci-sccache
+  SCCACHE_ENDPOINT: https://storage.unom.io
+  SCCACHE_REGION: home-central
+  AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
+  AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  # sccache and incremental compilation are mutually exclusive; CI wants the shared
+  # cache, dev boxes keep incremental.
+  CARGO_INCREMENTAL: "0"

 jobs:
  package:
@@ -81,11 +101,9 @@ jobs:
      - name: Configure + version
        shell: pwsh
        run: |
-          # windows-reactor's build.rs unwraps CARGO_WORKSPACE_DIR; CARGO_TARGET_DIR (per-arch, short)
-          # dodges the MAX_PATH wall in the CMake-from-source crates (see windows.yml). FFMPEG_DIR
-          # selects the arch's import libs + is read by pack-msix.ps1 for the runtime DLLs. All via
-          # GITHUB_ENV.
-          "CARGO_WORKSPACE_DIR=$env:GITHUB_WORKSPACE" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          # CARGO_TARGET_DIR (per-arch, short) dodges the MAX_PATH wall in the CMake-from-source
+          # crates (see windows.yml). FFMPEG_DIR selects the arch's import libs + is read by
+          # pack-msix.ps1 for the runtime DLLs. All via GITHUB_ENV.
          "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
          # pf-ffvk's bindgen needs Vulkan headers (arch-independent; provisioned alongside FFmpeg).
@@ -109,7 +127,10 @@ jobs:
      # hand-off shim. --no-default-features on ARM64 is a no-op for the shell.
      - name: Build (release)
        shell: pwsh
-        run: cargo build --release -p punktfunk-client-windows -p punktfunk-client-session ${{ matrix.session_flags }} --target ${{ matrix.target }}
+        # punktfunk-cli builds the `punktfunk.exe` the manifest aliases and pack-msix.ps1
+        # requires (bf981027 added the requirement without the build — same gap 90c84ef4
+        # closed for deb).
+        run: cargo build --release -p punktfunk-client-windows -p punktfunk-client-session -p punktfunk-cli ${{ matrix.session_flags }} --target ${{ matrix.target }}

      - name: Pack + sign MSIX
        shell: pwsh
@@ -22,8 +22,6 @@
 # The MSVC/WinUI/FFmpeg toolchain (cargo/rustup on ASCII paths, NASM, CMake, LLVM, the x64 FFmpeg,
 # CARGO_HOME, CMAKE_POLICY_VERSION_MINIMUM, …) is baked into the runner's daemon env. Per-checkout
 # / per-arch vars are set in a step:
-#   - CARGO_WORKSPACE_DIR  windows-reactor's build.rs unwraps it + stages the Win App SDK
-#                          NuGets/winmd under it (from GITHUB_WORKSPACE).
 #   - CARGO_TARGET_DIR=C:\t…  the runner's host workdir is buried deep under
 #                          C:\Windows\System32\config\systemprofile\.cache\act\<hash>\hostexecutor\,
 #                          so the default target\ path blows past Windows' MAX_PATH (260) inside the
@@ -34,10 +32,18 @@
 #   - FFMPEG_DIR           per-arch FFmpeg import libs (x64 vs arm64 tree).
 #
 # Steps use `shell: pwsh` (PowerShell 7) deliberately: Windows PowerShell 5.1's
-# `Out-File -Encoding utf8` prepends a UTF-8 BOM that corrupts the first GITHUB_ENV line (the
-# CARGO_WORKSPACE_DIR var silently never gets set -> reactor build.rs panics). pwsh writes no BOM.
+# `Out-File -Encoding utf8` prepends a UTF-8 BOM that corrupts the first GITHUB_ENV line (that
+# var silently never gets set). pwsh writes no BOM.
 # The runner's daemon wrapper puts C:\Program Files\PowerShell\7 on PATH so the job finds pwsh.
 name: windows
+# One pending run per workflow+ref: a newer push supersedes the queued/running one and cancels
+# it (a canary only needs the latest commit; each release tag is its own ref so tag runs never
+# cancel each other). Keeps a busy push cadence from piling ~10 queued runs per commit onto the
+# runner fleet. Gitea honors this for push triggers (PR triggers: see gitea#35933).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+

 on:
  push:
@@ -67,6 +73,20 @@ on:
      - '.gitea/workflows/windows.yml'
  workflow_dispatch:

+# Shared compile cache: sccache -> RustFS S3 (storage.unom.io, LAN-pinned via ci-core's
+# unbound). Keys include compiler hash + target + flags, so cross-OS/arch entries can
+# never collide; every Rust job on every host feeds and reads one warm cache.
+env:
+  RUSTC_WRAPPER: sccache
+  SCCACHE_BUCKET: unom-ci-sccache
+  SCCACHE_ENDPOINT: https://storage.unom.io
+  SCCACHE_REGION: home-central
+  AWS_ACCESS_KEY_ID: ${{ secrets.SCCACHE_ACCESS_KEY_ID }}
+  AWS_SECRET_ACCESS_KEY: ${{ secrets.SCCACHE_SECRET_ACCESS_KEY }}
+  # sccache and incremental compilation are mutually exclusive; CI wants the shared
+  # cache, dev boxes keep incremental.
+  CARGO_INCREMENTAL: "0"
+
 jobs:
  # SECURITY: this job builds PULL-REQUEST code (attacker-controllable build.rs / cargo build) on the
  # host-mode, persistent `windows-amd64` runner that the release-SIGNING jobs (windows-host.yml /
@@ -97,7 +117,6 @@ jobs:
      - name: Configure + toolchain versions
        shell: pwsh
        run: |
-          "CARGO_WORKSPACE_DIR=$env:GITHUB_WORKSPACE" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
          # 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
@@ -120,16 +139,20 @@ jobs:
      # Both client binaries. ARM64: no skia-binaries prebuilt for the target, so the session
      # drops its `ui` feature there (pf-console-ui excluded; --no-default-features is a no-op
      # for the shell, which has no features).
+      # punktfunk-cli is in every gate: windows-msix.yml ships its `punktfunk.exe` alias, so
+      # a CLI that only the release workflow compiles is a release-day surprise. Its tests
+      # RUN the binary (help contract), as the session's contract_smoke runs the session —
+      # the gate class that catches a compiling-but-wrong binary (the 0.22.0 clobber).
      - name: Build
        shell: pwsh
        run: |
          $sf = @(); if ('${{ matrix.target }}' -eq 'aarch64-pc-windows-msvc') { $sf = @('--no-default-features') }
-          cargo build -p punktfunk-client-windows -p punktfunk-client-session @sf --target ${{ matrix.target }}
+          cargo build -p punktfunk-client-windows -p punktfunk-client-session -p punktfunk-cli @sf --target ${{ matrix.target }}

      - name: Clippy (-D warnings)
        shell: pwsh
        run: |
-          $pkgs = @('-p','punktfunk-client-windows','-p','punktfunk-client-session','-p','pf-client-core','-p','pf-presenter','-p','pf-ffvk')
+          $pkgs = @('-p','punktfunk-client-windows','-p','punktfunk-client-session','-p','punktfunk-cli','-p','pf-client-core','-p','pf-presenter','-p','pf-ffvk')
          $sf = @()
          if ('${{ matrix.target }}' -eq 'aarch64-pc-windows-msvc') { $sf = @('--no-default-features') } else { $pkgs += @('-p','pf-console-ui') }
          cargo clippy @pkgs --all-targets @sf --target ${{ matrix.target }} -- -D warnings
@@ -137,9 +160,9 @@ jobs:
      - name: Rustfmt check
        if: matrix.target == 'x86_64-pc-windows-msvc'
        shell: pwsh
-        run: cargo fmt -p punktfunk-client-windows -p punktfunk-client-session -p pf-client-core -p pf-presenter -p pf-console-ui -p pf-ffvk -- --check
+        run: cargo fmt -p punktfunk-client-windows -p punktfunk-client-session -p punktfunk-cli -p pf-client-core -p pf-presenter -p pf-console-ui -p pf-ffvk -- --check

      - name: Test
        if: matrix.target == 'x86_64-pc-windows-msvc'
        shell: pwsh
-        run: cargo test -p punktfunk-client-windows -p punktfunk-client-session -p pf-client-core -p pf-presenter -p pf-console-ui -p pf-ffvk --target ${{ matrix.target }}
+        run: cargo test -p punktfunk-client-windows -p punktfunk-client-session -p punktfunk-cli -p pf-client-core -p pf-presenter -p pf-console-ui -p pf-ffvk --target ${{ matrix.target }}
@@ -945,6 +945,20 @@ dependencies = [
 "libloading",
 ]

+[[package]]
+name = "cursor-probe"
+version = "0.22.3"
+dependencies = [
+ "anyhow",
+ "pf-capture",
+ "pf-frame",
+ "pf-inject",
+ "pf-vdisplay",
+ "punktfunk-core",
+ "tracing",
+ "tracing-subscriber",
+]
+
 [[package]]
 name = "curve25519-dalek"
 version = "4.1.3"
@@ -1022,7 +1036,7 @@ dependencies = [

 [[package]]
 name = "display-disturb"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "windows 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
@@ -1585,6 +1599,12 @@ dependencies = [
 "smallvec",
 ]

+[[package]]
+name = "glib-build-tools"
+version = "0.22.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f9871f38b67853c358b8190f77b9f878eb27d933a950f1045b244c4559a9f5f0"
+
 [[package]]
 name = "glib-macros"
 version = "0.22.6"
@@ -2201,7 +2221,7 @@ dependencies = [

 [[package]]
 name = "latency-probe"
-version = "0.21.0"
+version = "0.22.3"

 [[package]]
 name = "lazy_static"
@@ -2306,7 +2326,7 @@ dependencies = [

 [[package]]
 name = "libvpl-sys"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "bindgen",
 "cmake",
@@ -2341,7 +2361,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"

 [[package]]
 name = "loss-harness"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "punktfunk-core",
 ]
@@ -2830,7 +2850,7 @@ checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"

 [[package]]
 name = "pf-capture"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "anyhow",
 "ashpd",
@@ -2851,7 +2871,7 @@ dependencies = [

 [[package]]
 name = "pf-client-core"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "anyhow",
 "ash",
@@ -2871,12 +2891,12 @@ dependencies = [
 "tracing",
 "ureq",
 "wasapi",
- "windows 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
+ "windows 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
 ]

 [[package]]
 name = "pf-clipboard"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "anyhow",
 "ashpd",
@@ -2894,7 +2914,7 @@ dependencies = [

 [[package]]
 name = "pf-console-ui"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "anyhow",
 "ash",
@@ -2915,7 +2935,7 @@ dependencies = [

 [[package]]
 name = "pf-encode"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "anyhow",
 "ash",
@@ -2939,7 +2959,7 @@ dependencies = [

 [[package]]
 name = "pf-ffvk"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "ash",
 "bindgen",
@@ -2948,7 +2968,7 @@ dependencies = [

 [[package]]
 name = "pf-frame"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "anyhow",
 "libc",
@@ -2960,7 +2980,7 @@ dependencies = [

 [[package]]
 name = "pf-gpu"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "anyhow",
 "pf-host-config",
@@ -2974,11 +2994,11 @@ dependencies = [

 [[package]]
 name = "pf-host-config"
-version = "0.21.0"
+version = "0.22.3"

 [[package]]
 name = "pf-inject"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "anyhow",
 "ashpd",
@@ -3007,14 +3027,14 @@ dependencies = [

 [[package]]
 name = "pf-paths"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "tracing",
 ]

 [[package]]
 name = "pf-presenter"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "anyhow",
 "ash",
@@ -3027,9 +3047,17 @@ dependencies = [
 "windows-sys 0.61.2",
 ]

+[[package]]
+name = "pf-update"
+version = "0.22.3"
+dependencies = [
+ "serde",
+ "serde_json",
+]
+
 [[package]]
 name = "pf-vdisplay"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "anyhow",
 "ashpd",
@@ -3051,6 +3079,7 @@ dependencies = [
 "sha2",
 "tokio",
 "tracing",
+ "tracing-subscriber",
 "utoipa",
 "wayland-backend",
 "wayland-client",
@@ -3061,7 +3090,7 @@ dependencies = [

 [[package]]
 name = "pf-win-display"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "anyhow",
 "pf-paths",
@@ -3073,7 +3102,7 @@ dependencies = [

 [[package]]
 name = "pf-zerocopy"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "anyhow",
 "ash",
@@ -3279,9 +3308,20 @@ dependencies = [
 "unarray",
 ]

+[[package]]
+name = "punktfunk-cli"
+version = "0.22.3"
+dependencies = [
+ "pf-client-core",
+ "punktfunk-core",
+ "serde_json",
+ "tracing",
+ "tracing-subscriber",
+]
+
 [[package]]
 name = "punktfunk-client-android"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "android_logger",
 "jni",
@@ -3297,10 +3337,11 @@ dependencies = [

 [[package]]
 name = "punktfunk-client-linux"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "anyhow",
 "async-channel",
+ "glib-build-tools",
 "gtk4",
 "libadwaita",
 "pf-client-core",
@@ -3313,7 +3354,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-client-session"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "anyhow",
 "pf-client-core",
@@ -3328,7 +3369,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-client-windows"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "async-channel",
 "ffmpeg-next",
@@ -3337,9 +3378,10 @@ dependencies = [
 "punktfunk-core",
 "serde",
 "serde_json",
+ "test_reactor",
 "tracing",
 "tracing-subscriber",
- "windows 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
+ "windows 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
 "windows-reactor",
 "windows-reactor-setup",
 "winresource",
@@ -3347,7 +3389,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-core"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "aes-gcm",
 "bytes",
@@ -3379,7 +3421,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-host"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "aes",
 "aes-gcm",
@@ -3463,7 +3505,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-probe"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "anyhow",
 "mdns-sd",
@@ -3477,7 +3519,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-tray"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "anyhow",
 "ksni",
@@ -3500,7 +3542,7 @@ checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea"

 [[package]]
 name = "pyrowave-sys"
-version = "0.21.0"
+version = "0.22.3"
 dependencies = [
 "bindgen",
 "cmake",
@@ -4539,6 +4581,18 @@ dependencies = [
 "windows-sys 0.61.2",
 ]

+[[package]]
+name = "test_reactor"
+version = "0.0.0"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"
+dependencies = [
+ "rustc-hash",
+ "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-reactor",
+ "windows-reactor-setup",
+ "windows-reference",
+]
+
 [[package]]
 name = "thiserror"
 version = "1.0.69"
@@ -5383,16 +5437,26 @@ dependencies = [
 [[package]]
 name = "windows"
 version = "0.62.2"
-source = "git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f#a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"
 dependencies = [
- "windows-collections 0.3.2 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
- "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
- "windows-future 0.3.2 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
- "windows-numerics 0.3.1 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
+ "windows-collections 0.3.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-future 0.3.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-numerics 0.3.1 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
 "windows-reference",
 "windows-time",
 ]

+[[package]]
+name = "windows-canvas"
+version = "0.0.0"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"
+dependencies = [
+ "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-numerics 0.3.1 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-window",
+]
+
 [[package]]
 name = "windows-collections"
 version = "0.3.2"
@@ -5405,9 +5469,20 @@ dependencies = [
 [[package]]
 name = "windows-collections"
 version = "0.3.2"
-source = "git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f#a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"
 dependencies = [
- "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
+ "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+]
+
+[[package]]
+name = "windows-composition"
+version = "0.0.0"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"
+dependencies = [
+ "windows-collections 0.3.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-numerics 0.3.1 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-time",
 ]

 [[package]]
@@ -5426,13 +5501,13 @@ dependencies = [
 [[package]]
 name = "windows-core"
 version = "0.62.2"
-source = "git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f#a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"
 dependencies = [
- "windows-implement 0.60.2 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
- "windows-interface 0.59.3 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
- "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
- "windows-result 0.4.1 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
- "windows-strings 0.5.1 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
+ "windows-implement 0.60.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-interface 0.59.3 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-result 0.4.1 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-strings 0.5.1 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
 ]

 [[package]]
@@ -5449,11 +5524,11 @@ dependencies = [
 [[package]]
 name = "windows-future"
 version = "0.3.2"
-source = "git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f#a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"
 dependencies = [
- "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
- "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
- "windows-threading 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
+ "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-threading 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
 ]

 [[package]]
@@ -5470,7 +5545,7 @@ dependencies = [
 [[package]]
 name = "windows-implement"
 version = "0.60.2"
-source = "git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f#a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"
 dependencies = [
 "proc-macro2",
 "quote",
@@ -5491,7 +5566,7 @@ dependencies = [
 [[package]]
 name = "windows-interface"
 version = "0.59.3"
-source = "git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f#a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"
 dependencies = [
 "proc-macro2",
 "quote",
@@ -5507,7 +5582,7 @@ checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
 [[package]]
 name = "windows-link"
 version = "0.2.1"
-source = "git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f#a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"

 [[package]]
 name = "windows-numerics"
@@ -5522,38 +5597,40 @@ dependencies = [
 [[package]]
 name = "windows-numerics"
 version = "0.3.1"
-source = "git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f#a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"
 dependencies = [
- "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
- "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
+ "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
 ]

 [[package]]
 name = "windows-reactor"
 version = "0.0.0"
-source = "git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f#a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"
 dependencies = [
 "rustc-hash",
- "windows-collections 0.3.2 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
- "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
- "windows-future 0.3.2 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
- "windows-numerics 0.3.1 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
+ "windows-canvas",
+ "windows-collections 0.3.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-composition",
+ "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-future 0.3.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-numerics 0.3.1 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
 "windows-reference",
- "windows-threading 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
+ "windows-threading 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
 "windows-time",
 ]

 [[package]]
 name = "windows-reactor-setup"
 version = "0.0.0"
-source = "git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f#a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"

 [[package]]
 name = "windows-reference"
 version = "0.1.0"
-source = "git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f#a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"
 dependencies = [
- "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
+ "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
 "windows-time",
 ]

@@ -5569,9 +5646,9 @@ dependencies = [
 [[package]]
 name = "windows-result"
 version = "0.4.1"
-source = "git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f#a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"
 dependencies = [
- "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
+ "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
 ]

 [[package]]
@@ -5597,9 +5674,9 @@ dependencies = [
 [[package]]
 name = "windows-strings"
 version = "0.5.1"
-source = "git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f#a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"
 dependencies = [
- "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
+ "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
 ]

 [[package]]
@@ -5707,18 +5784,26 @@ dependencies = [
 [[package]]
 name = "windows-threading"
 version = "0.2.1"
-source = "git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f#a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"
 dependencies = [
- "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
+ "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
 ]

 [[package]]
 name = "windows-time"
 version = "0.1.0"
-source = "git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f#a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"
 dependencies = [
- "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
- "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
+ "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+]
+
+[[package]]
+name = "windows-window"
+version = "0.0.0"
+source = "git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc#acb5a1a7441033d9312b16842af02eb0c2b403dc"
+dependencies = [
+ "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
 ]

 [[package]]
@@ -12,6 +12,7 @@ members = [
    "crates/pf-ffvk",
    "crates/pf-driver-proto",
    "crates/pf-paths",
+    "crates/pf-update",
    "crates/pf-host-config",
    "crates/pf-gpu",
    "crates/pf-zerocopy",
@@ -24,10 +25,12 @@ members = [
    "crates/pyrowave-sys",
    "crates/libvpl-sys",
    "clients/probe",
+    "clients/cli",
    "clients/linux",
    "clients/session",
    "clients/windows",
    "clients/android/native",
+    "tools/cursor-probe",
    "tools/display-disturb",
    "tools/latency-probe",
    "tools/loss-harness",
@@ -49,7 +52,7 @@ exclude = [
 ndk = { path = "clients/android/native/vendor/ndk" }

 [workspace.package]
-version = "0.21.0"
+version = "0.22.3"
 edition = "2021"
 rust-version = "1.82"
 license = "MIT OR Apache-2.0"
@@ -56,6 +56,38 @@ https://docs.punktfunk.unom.io/docs/security):

 If you're unsure whether something is in scope, report it anyway — we'd rather hear about it.

+## Verifying what you downloaded
+
+Every distribution path is authenticated. Nothing below needs an account or a network round trip to
+us beyond the download itself.
+
+- **Release-page downloads** (DMG, MSIX, setup.exe, APK, decky zip, .deb/.rpm) each ship a
+  `<file>.sha256` next to them. In your download directory:
+  `sha256sum -c punktfunk-1.2.3.dmg.sha256` (macOS: `shasum -a 256 -c …`).
+- **RPMs** from the dnf repo are OpenPGP-signed with `packages@unom.io` (`AF245C506F4E4763`); the
+  repo file in [`packaging/rpm/README.md`](packaging/rpm/README.md) sets `gpgcheck=1`, so dnf
+  checks every package for you. `rpmkeys --checksig` on a downloaded RPM verifies it by hand.
+- **The Bazzite sysext feed** carries a detached signature over its `SHA256SUMS`, from that same
+  key. `punktfunk-sysext` verifies it before installing and refuses a feed it cannot verify — the
+  public key is baked into the script rather than fetched from the feed.
+- **Windows installers and MSIX packages** are Authenticode-signed; a release build that cannot
+  reach its code-signing certificate fails to build rather than falling back to a self-signed one.
+  Check with `Get-AuthenticodeSignature punktfunk-host-setup-1.2.3.exe`.
+- **The Windows drivers** (virtual display, virtual gamepads) are signed with a stable self-signed
+  certificate, `CN=punktfunk-driver`
+  (SHA-1 `4B8493E7CD565758D335F8F4F05C5A7261A13E02`), also published in
+  [`packaging/windows/README.md`](packaging/windows/README.md). The installer has to add it to the
+  machine's trusted roots for a self-signed driver to install at all, so — unlike the cases above —
+  this signature does **not** authenticate the download: it gives the drivers a stable publisher
+  identity you can compare against the published fingerprint, and it is removed again on uninstall.
+  Verify with `Get-AuthenticodeSignature` on the installed `pf_vdisplay.dll`, or list what is
+  trusted with `Get-ChildItem Cert:\LocalMachine\Root | ? Subject -like '*punktfunk*'`.
+
+A checksum on its own only tells you the download wasn't corrupted in transit — it says nothing
+about who produced the file, since anyone able to replace an artifact can replace its checksum.
+Where that distinction matters (the update feeds, the package repos), the checksums are covered by
+a signature. If a signature check fails, please don't work around it; report it.
+
 ## Safe harbor

 We consider good-faith security research that follows this policy to be authorized, and we won't
@@ -37,13 +37,15 @@ accepted = [
 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"
+# Per-crate license-acceptance additions (cargo-about ≥0.6 syntax; the old `[crate.clarify]`
+# license-only form fails to deserialize under cargo-about 0.9, which now wants checksummed file
+# clarifications — per-crate `accepted` extensions express the same intent without checksums).
+#
+# r-efi is tri-licensed with an LGPL-2.1-or-later arm; cargo-about resolves OR-expressions to an
+# accepted arm on its own (MIT/Apache-2.0 are globally accepted), so it needs no entry. (It is
+# also UEFI-target-gated out of every shipped build.)
+#
+# ring's license is an AND of permissive terms including the OpenSSL license; accept the
+# OpenSSL/ISC parts for this crate only, not globally.
+[ring]
+accepted = ["OpenSSL", "ISC"]
@@ -10,7 +10,7 @@
      "name": "MIT OR Apache-2.0",
      "identifier": "MIT OR Apache-2.0"
    },
-    "version": "0.20.0"
+    "version": "0.22.3"
  },
  "paths": {
    "/api/v1/clients": {
@@ -1558,7 +1558,7 @@
          "host"
        ],
        "summary": "Local status summary for the tray icon",
-        "description": "Non-sensitive status (counts and booleans only — no PIN values, no fingerprints, no device\nnames). Unauthenticated, but served to loopback peers only.",
+        "description": "Non-sensitive status (counts, booleans, and the streaming client's display name — no PIN\nvalues, no fingerprints). Unauthenticated, but served to loopback peers only.",
        "operationId": "getLocalSummary",
        "responses": {
          "200": {
@@ -3432,6 +3432,142 @@
          }
        }
      }
+    },
+    "/api/v1/update/apply": {
+      "post": {
+        "tags": [
+          "update"
+        ],
+        "summary": "Apply the available update",
+        "description": "Starts the one-click apply for install kinds that support it (Windows installer). The\nrequest carries no version or URL — the host installs exactly what its verified manifest\nannounced. Progress is polled via `GET /update/status` (`job`); the host restarts as part\nof the apply, and the outcome lands in `last_result` after it comes back.",
+        "operationId": "applyUpdate",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ApplyRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "202": {
+            "description": "Apply started — poll `GET /update/status`",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UpdateStatus"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Refused: unsupported install kind, apply disabled (PUNKTFUNK_UPDATE_APPLY=0), a job already running, an active streaming session without `force`, or nothing newer to apply",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/update/check": {
+      "post": {
+        "tags": [
+          "update"
+        ],
+        "summary": "Check for updates now",
+        "description": "Forces a manifest fetch + verification and returns the refreshed state. Rate-limited to\none forced check per 30 s.",
+        "operationId": "forceUpdateCheck",
+        "responses": {
+          "200": {
+            "description": "Refreshed update-check state (`last_error` carries a failed check)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UpdateStatus"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Update checks are disabled on this host",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "A forced check ran less than 30 s ago",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/update/status": {
+      "get": {
+        "tags": [
+          "update"
+        ],
+        "summary": "Update-check status",
+        "description": "How this host was installed, which channel it follows, whether a newer release is known,\nand how to update. Reading this may kick a background refresh when the cached check is\nolder than 6 h; the response never blocks on the network.",
+        "operationId": "getUpdateStatus",
+        "responses": {
+          "200": {
+            "description": "Current update-check state",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UpdateStatus"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
    }
  },
  "components": {
@@ -3764,6 +3900,15 @@
          }
        }
      },
+      "ApplyRequest": {
+        "type": "object",
+        "properties": {
+          "force": {
+            "type": "boolean",
+            "description": "Proceed even while a streaming session is live (the stream will drop when the host\nrestarts — the console warns before sending this)."
+          }
+        }
+      },
      "ApprovePending": {
        "type": "object",
        "description": "Approve-pending-device request body. Send `{}` to keep the device's own name.",
@@ -4799,6 +4944,59 @@
              }
            }
          },
+          {
+            "type": "object",
+            "description": "A verified update manifest announced a release newer than the running host. Emitted\nonce per discovered version (a steady-state \"newer exists\" doesn't re-fire on every\nrefresh).",
+            "required": [
+              "version",
+              "channel",
+              "install_kind",
+              "kind"
+            ],
+            "properties": {
+              "channel": {
+                "type": "string",
+                "description": "The channel it was announced on (`stable` | `canary`)."
+              },
+              "install_kind": {
+                "type": "string",
+                "description": "This host's install kind (`apt`, `windows-installer`, …) — lets a hook or the\ntray render the right \"how to update\" hint without a second call."
+              },
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "update.available"
+                ]
+              },
+              "version": {
+                "type": "string",
+                "description": "The newer release's version string."
+              }
+            }
+          },
+          {
+            "type": "object",
+            "description": "A host update completed: emitted by boot-time reconciliation, i.e. by the NEW binary's\nfirst start after a successful apply.",
+            "required": [
+              "from",
+              "to",
+              "kind"
+            ],
+            "properties": {
+              "from": {
+                "type": "string"
+              },
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "update.applied"
+                ]
+              },
+              "to": {
+                "type": "string"
+              }
+            }
+          },
          {
            "type": "object",
            "required": [
@@ -5335,6 +5533,8 @@
          "abi_version",
          "app_version",
          "gfe_version",
+          "os",
+          "os_name",
          "codecs",
          "gamestream",
          "ports"
@@ -5372,6 +5572,16 @@
            "type": "string",
            "description": "Best-effort primary LAN IP."
          },
+          "os": {
+            "type": "string",
+            "description": "OS identity chain, generic → most specific, slash-separated (`windows` | `macos` |\n`linux[/<family>][/<id>]`). A client walks it most-specific-first and shows the first\ntoken it has an icon for, so an unknown distro still degrades to its family's mark.",
+            "example": "linux/fedora/bazzite"
+          },
+          "os_name": {
+            "type": "string",
+            "description": "Human-readable OS name (os-release `PRETTY_NAME`; `\"Windows\"`/`\"macOS\"` elsewhere).",
+            "example": "Bazzite 42 (Kinoite)"
+          },
          "ports": {
            "$ref": "#/components/schemas/PortMap"
          },
@@ -5674,7 +5884,7 @@
      },
      "LocalSummary": {
        "type": "object",
-        "description": "Non-sensitive host status for the local tray icon: counts and booleans only — no PIN values,\nno fingerprints, no device names. Served unauthenticated to LOOPBACK peers only (see\n`require_auth`): the bearer-token file is SYSTEM/Administrators-DACL'd on Windows, so the\nper-user tray process cannot authenticate — this narrow read-only route is its status source.",
+        "description": "Non-sensitive host status for the local tray icon: counts and booleans — no PIN values, no\nfingerprints. The ONE name exposed is `client_name`, the streaming client's display label\n(deliberate loosening for the tray's \"client connected\" toast: it tells the local user who is\non their machine, which is disclosure in the user's favor — and any local process could\nalready infer a session exists from the booleans here). Served unauthenticated to LOOPBACK\npeers only (see `require_auth`): the bearer-token file is SYSTEM/Administrators-DACL'd on\nWindows, so the per-user tray process cannot authenticate — this narrow read-only route is\nits status source.",
        "required": [
          "version",
          "video_streaming",
@@ -5690,6 +5900,13 @@
            "type": "boolean",
            "description": "True while audio is streaming on either plane (same rule as `video_streaming`)."
          },
+          "client_name": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Display name of the (first) streaming native client — the trust store's name for it, else\nthe name the device sent at connect. `null` when idle, for a nameless client, or for a\nGameStream session (that plane carries no device name)."
+          },
          "conflicts": {
            "type": "array",
            "items": {
@@ -5831,7 +6048,8 @@
        "type": "object",
        "description": "The host's physical monitors + which one capture is pinned to.",
        "required": [
-          "monitors"
+          "monitors",
+          "pin_supported"
        ],
        "properties": {
          "compositor": {
@@ -5855,6 +6073,10 @@
            },
            "description": "The heads, ordered left-to-right by desktop position."
          },
+          "pin_supported": {
+            "type": "boolean",
+            "description": "Whether this build can actually STREAM one of these monitors.\n\nEnumeration and capture are separate capabilities, and on Windows only the first exists: the\nheads below are real and worth showing (they explain the topology, and `/display/state`\ncross-references them), but `pf-capture`'s sole Windows entry point is `open_idd_push` — a\nframe channel pushed by our OWN IddCx virtual display. There is no desktop-duplication\ncapturer to point at a chosen head (DXGI Desktop Duplication was deliberately removed), so\n`vdisplay::open` has no mirror arm outside Linux and a pin could not be honored.\n\nThe console renders the picker read-only on `false`. Reported as a capability rather than\nsniffed client-side from the OS so the answer comes from the build that would have to honor\nit — when a Windows mirror backend lands, this flips and the UI needs no change."
+          },
          "pinned": {
            "type": [
              "string",
@@ -7016,6 +7238,228 @@
            "type": "string"
          }
        }
+      },
+      "UpdateJobInfo": {
+        "type": "object",
+        "description": "A running apply job (or a spawned installer that hasn't resolved yet).",
+        "required": [
+          "target_version",
+          "stage",
+          "received_bytes",
+          "started_unix"
+        ],
+        "properties": {
+          "received_bytes": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0
+          },
+          "stage": {
+            "type": "string",
+            "description": "`downloading` | `verifying` | `applying` | `restarting`."
+          },
+          "started_unix": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0
+          },
+          "target_version": {
+            "type": "string",
+            "description": "The version being installed."
+          },
+          "total_bytes": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int64",
+            "minimum": 0
+          }
+        }
+      },
+      "UpdateManifestInfo": {
+        "type": "object",
+        "description": "One channel's manifest facts, as much as the console renders.",
+        "required": [
+          "version",
+          "serial",
+          "published_at",
+          "notes_url",
+          "stale"
+        ],
+        "properties": {
+          "notes_url": {
+            "type": "string",
+            "description": "Release-notes link (pinned to our forge by the manifest validator)."
+          },
+          "published_at": {
+            "type": "string",
+            "description": "RFC-3339 publish time (display only)."
+          },
+          "serial": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Publish serial (unix seconds) — monotonic per channel.",
+            "minimum": 0
+          },
+          "stale": {
+            "type": "boolean",
+            "description": "The last verified manifest is suspiciously old (>45 days) — the freeze/stale hint."
+          },
+          "version": {
+            "type": "string",
+            "description": "The released version this manifest announces."
+          }
+        }
+      },
+      "UpdateResultInfo": {
+        "type": "object",
+        "description": "Durable outcome of the most recent apply attempt (survives the host's own restart).",
+        "required": [
+          "ok",
+          "from",
+          "to",
+          "finished_unix"
+        ],
+        "properties": {
+          "error": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "finished_unix": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0
+          },
+          "from": {
+            "type": "string"
+          },
+          "log_path": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "The installer's own log file on this host, for diagnosis."
+          },
+          "ok": {
+            "type": "boolean"
+          },
+          "stage": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "The stage that failed; absent on success."
+          },
+          "staged": {
+            "type": "boolean",
+            "description": "Applied but activates on the next reboot (rpm-ostree)."
+          },
+          "to": {
+            "type": "string"
+          }
+        }
+      },
+      "UpdateStatus": {
+        "type": "object",
+        "description": "The full update-check state for this host.",
+        "required": [
+          "install_kind",
+          "channel",
+          "current_version",
+          "apply",
+          "channel_hint",
+          "check_disabled",
+          "available"
+        ],
+        "properties": {
+          "apply": {
+            "type": "string",
+            "description": "What the console may offer for this install: `notify` (show the command) — later\nphases add `full` (one-click apply) and `staged` (apply + reboot to finish)."
+          },
+          "available": {
+            "type": "boolean",
+            "description": "A newer release than `current_version` exists for this channel (definitive\ncomparisons only — an unparseable version pair never flags)."
+          },
+          "channel": {
+            "type": "string",
+            "description": "Release channel this install follows: `stable` | `canary`."
+          },
+          "channel_hint": {
+            "type": "string",
+            "description": "The copy-pastable update command for this install kind."
+          },
+          "check_disabled": {
+            "type": "boolean",
+            "description": "Update checks are disabled on this host (`PUNKTFUNK_UPDATE_CHECK=0`)."
+          },
+          "current_version": {
+            "type": "string",
+            "description": "The running host version."
+          },
+          "install_kind": {
+            "type": "string",
+            "description": "How this host was installed: `windows-installer` | `sysext` | `rpm-ostree` | `apt` |\n`dnf` | `pacman` | `steamos-source` | `nix` | `source`."
+          },
+          "job": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/UpdateJobInfo",
+                "description": "The apply in flight, if any."
+              }
+            ]
+          },
+          "last_checked_unix": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int64",
+            "description": "When the last successful check happened (unix seconds).",
+            "minimum": 0
+          },
+          "last_error": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Why the last check failed, verbatim, if it did."
+          },
+          "last_result": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/UpdateResultInfo",
+                "description": "Outcome of the most recent apply attempt."
+              }
+            ]
+          },
+          "manifest": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/UpdateManifestInfo",
+                "description": "The last verified manifest, if any check has succeeded."
+              }
+            ]
+          },
+          "opt_in_hint": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "This install could one-click apply, but the operator hasn't opted in yet — the\ncommand to run (Linux: join the `punktfunk-update` group)."
+          }
+        }
      }
    },
    "securitySchemes": {
@@ -7086,6 +7530,10 @@
    {
      "name": "store",
      "description": "Plugin store: browse signed catalogs (verified first-party entries, attributed third-party sources), install/uninstall as tracked jobs, and switch the plugin runner on"
+    },
+    {
+      "name": "update",
+      "description": "Host update check: install kind + channel, the last verified release manifest, and whether a newer host exists (admin lane only)"
    }
  ]
 }
@@ -0,0 +1,17 @@
+Font Awesome Free — brand icons (windows, apple, linux, steam, ubuntu, fedora,
+opensuse in assets/os-icons/) are from Font Awesome Free.
+
+Copyright (c) Fonticons, Inc. (https://fontawesome.com)
+
+Font Awesome Free icons are licensed under the Creative Commons Attribution 4.0
+International license (CC BY 4.0), https://creativecommons.org/licenses/by/4.0/.
+The icons are redistributed here as monochrome SVG path data with no
+modifications beyond color normalization (fill="currentColor").
+
+Per the Font Awesome Free license (https://fontawesome.com/license/free):
+"Font Awesome Free is free, open source, and GPL friendly. You can use it for
+commercial projects, open source projects, or really almost whatever you want.
+Attribution is required by MIT, SIL OFL, and CC BY licenses."
+
+Brand icons are trademarks of their respective owners and are used for
+identification purposes only; their use does not imply endorsement.
@@ -0,0 +1,10 @@
+Simple Icons — brand icons (arch, nixos, debian in assets/os-icons/) are from
+Simple Icons (https://simpleicons.org, https://github.com/simple-icons/simple-icons).
+
+The Simple Icons SVG path data is released under CC0 1.0 Universal (public domain
+dedication), https://creativecommons.org/publicdomain/zero/1.0/ — no attribution
+required; this notice is provided for provenance.
+
+Brand icons are trademarks of their respective owners and are used for
+identification purposes only; their use does not imply endorsement. See
+https://github.com/simple-icons/simple-icons/blob/develop/DISCLAIMER.md.
@@ -0,0 +1,30 @@
+# OS icon masters
+
+The canonical OS/distro brand marks every client derives its host-card OS icon from
+(web console inline SVGs, GTK symbolic icons, Windows PNGs, Apple template imagesets,
+Android `ImageVector`s). One file per **icon token** of the host's OS-identity chain
+(see `crates/punktfunk-host/src/osinfo.rs` and `crates/pf-client-core/src/os.rs`):
+
+| token | mark | source |
+|---|---|---|
+| `windows` | Windows | Font Awesome Free brands (CC BY 4.0) |
+| `apple` | Apple (also `macos` via alias) | Font Awesome Free brands (CC BY 4.0) |
+| `linux` | Tux | Font Awesome Free brands (CC BY 4.0) |
+| `steam` | Steam (also `steamos` via alias) | Font Awesome Free brands (CC BY 4.0) |
+| `ubuntu` | Ubuntu | Font Awesome Free brands (CC BY 4.0) |
+| `fedora` | Fedora | Font Awesome Free brands (CC BY 4.0) |
+| `opensuse` | SUSE | Font Awesome Free brands (CC BY 4.0) |
+| `arch` | Arch Linux | Simple Icons (CC0 1.0) |
+| `nixos` | NixOS | Simple Icons (CC0 1.0) |
+| `debian` | Debian | Simple Icons (CC0 1.0) |
+
+Distros with no file here (Bazzite, CachyOS, Nobara, Pop!_OS, Mint, …) are intentional:
+the host advertises the full chain (`linux/fedora/bazzite`), and clients walk it
+most-specific-first, so they degrade to the family mark and finally to Tux.
+
+All files are monochrome (`fill="currentColor"`), original per-icon viewBoxes preserved.
+Licensing: attribution notices live in `LICENSES/` and are folded into
+`THIRD-PARTY-NOTICES.txt` by `scripts/gen-third-party-notices.py`. The marks are
+trademarks of their respective owners; they are used here nominatively — to *identify*
+the operating system a host runs, the standard practice in this ecosystem — and imply no
+affiliation or endorsement.
@@ -0,0 +1,2 @@
+<!-- apple — from Font Awesome Free 5 brands (CC BY 4.0), via react-icons FaApple. See README.md. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 384 512" fill="currentColor"><path d="M318.7 268.7c-.2-36.7 16.4-64.4 50-84.8-18.8-26.9-47.2-41.7-84.7-44.6-35.5-2.8-74.3 20.7-88.5 20.7-15 0-49.4-19.7-76.4-19.7C63.3 141.2 4 184.8 4 273.5q0 39.3 14.4 81.2c12.8 36.7 59 126.7 107.2 125.2 25.2-.6 43-17.9 75.8-17.9 31.8 0 48.3 17.9 76.4 17.9 48.6-.7 90.4-82.5 102.6-119.3-65.2-30.7-61.7-90-61.7-91.9zm-56.6-164.2c27.3-32.4 24.8-61.9 24-72.5-24.1 1.4-52 16.4-67.9 34.9-17.5 19.8-27.8 44.3-25.6 71.9 26.1 2 49.9-11.4 69.5-34.3z"/></svg>
@@ -0,0 +1,2 @@
+<!-- arch — from Simple Icons (CC0 1.0), via react-icons SiArchlinux. See README.md. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor"><path d="M11.39.605C10.376 3.092 9.764 4.72 8.635 7.132c.693.734 1.543 1.589 2.923 2.554-1.484-.61-2.496-1.224-3.252-1.86C6.86 10.842 4.596 15.138 0 23.395c3.612-2.085 6.412-3.37 9.021-3.862a6.61 6.61 0 01-.171-1.547l.003-.115c.058-2.315 1.261-4.095 2.687-3.973 1.426.12 2.534 2.096 2.478 4.409a6.52 6.52 0 01-.146 1.243c2.58.505 5.352 1.787 8.914 3.844-.702-1.293-1.33-2.459-1.929-3.57-.943-.73-1.926-1.682-3.933-2.713 1.38.359 2.367.772 3.137 1.234-6.09-11.334-6.582-12.84-8.67-17.74zM22.898 21.36v-.623h-.234v-.084h.562v.084h-.234v.623h.331v-.707h.142l.167.5.034.107a2.26 2.26 0 01.038-.114l.17-.493H24v.707h-.091v-.593l-.206.593h-.084l-.205-.602v.602h-.091"/></svg>
@@ -0,0 +1,2 @@
+<!-- debian — from Simple Icons (CC0 1.0), via react-icons SiDebian. See README.md. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor"><path d="M13.88 12.685c-.4 0 .08.2.601.28.14-.1.27-.22.39-.33a3.001 3.001 0 01-.99.05m2.14-.53c.23-.33.4-.69.47-1.06-.06.27-.2.5-.33.73-.75.47-.07-.27 0-.56-.8 1.01-.11.6-.14.89m.781-2.05c.05-.721-.14-.501-.2-.221.07.04.13.5.2.22M12.38.31c.2.04.45.07.42.12.23-.05.28-.1-.43-.12m.43.12l-.15.03.14-.01V.43m6.633 9.944c.02.64-.2.95-.38 1.5l-.35.181c-.28.54.03.35-.17.78-.44.39-1.34 1.22-1.62 1.301-.201 0 .14-.25.19-.34-.591.4-.481.6-1.371.85l-.03-.06c-2.221 1.04-5.303-1.02-5.253-3.842-.03.17-.07.13-.12.2a3.551 3.552 0 012.001-3.501 3.361 3.362 0 013.732.48 3.341 3.342 0 00-2.721-1.3c-1.18.01-2.281.76-2.651 1.57-.6.38-.67 1.47-.93 1.661-.361 2.601.66 3.722 2.38 5.042.27.19.08.21.12.35a4.702 4.702 0 01-1.53-1.16c.23.33.47.66.8.91-.55-.18-1.27-1.3-1.48-1.35.93 1.66 3.78 2.921 5.261 2.3a6.203 6.203 0 01-2.33-.28c-.33-.16-.77-.51-.7-.57a5.802 5.803 0 005.902-.84c.44-.35.93-.94 1.07-.95-.2.32.04.16-.12.44.44-.72-.2-.3.46-1.24l.24.33c-.09-.6.74-1.321.66-2.262.19-.3.2.3 0 .97.29-.74.08-.85.15-1.46.08.2.18.42.23.63-.18-.7.2-1.2.28-1.6-.09-.05-.28.3-.32-.53 0-.37.1-.2.14-.28-.08-.05-.26-.32-.38-.861.08-.13.22.33.34.34-.08-.42-.2-.75-.2-1.08-.34-.68-.12.1-.4-.3-.34-1.091.3-.25.34-.74.54.77.84 1.96.981 2.46-.1-.6-.28-1.2-.49-1.76.16.07-.26-1.241.21-.37A7.823 7.824 0 0017.702 1.6c.18.17.42.39.33.42-.75-.45-.62-.48-.73-.67-.61-.25-.65.02-1.06 0C15.082.73 14.862.8 13.8.4l.05.23c-.77-.25-.9.1-1.73 0-.05-.04.27-.14.53-.18-.741.1-.701-.14-1.431.03.17-.13.36-.21.55-.32-.6.04-1.44.35-1.18.07C9.6.68 7.847 1.3 6.867 2.22L6.838 2c-.45.54-1.96 1.611-2.08 2.311l-.131.03c-.23.4-.38.85-.57 1.261-.3.52-.45.2-.4.28-.6 1.22-.9 2.251-1.16 3.102.18.27 0 1.65.07 2.76-.3 5.463 3.84 10.776 8.363 12.006.67.23 1.65.23 2.49.25-.99-.28-1.12-.15-2.08-.49-.7-.32-.85-.7-1.34-1.13l.2.35c-.971-.34-.57-.42-1.361-.67l.21-.27c-.31-.03-.83-.53-.97-.81l-.34.01c-.41-.501-.63-.871-.61-1.161l-.111.2c-.13-.21-1.52-1.901-.8-1.511-.13-.12-.31-.2-.5-.55l.14-.17c-.35-.44-.64-1.02-.62-1.2.2.24.32.3.45.33-.88-2.172-.93-.12-1.601-2.202l.15-.02c-.1-.16-.18-.34-.26-.51l.06-.6c-.63-.74-.18-3.102-.09-4.402.07-.54.53-1.1.88-1.981l-.21-.04c.4-.71 2.341-2.872 3.241-2.761.43-.55-.09 0-.18-.14.96-.991 1.26-.7 1.901-.88.7-.401-.6.16-.27-.151 1.2-.3.85-.7 2.421-.85.16.1-.39.14-.52.26 1-.49 3.151-.37 4.562.27 1.63.77 3.461 3.011 3.531 5.132l.08.02c-.04.85.13 1.821-.17 2.711l.2-.42M9.54 13.236l-.05.28c.26.35.47.73.8 1.01-.24-.47-.42-.66-.75-1.3m.62-.02c-.14-.15-.22-.34-.31-.52.08.32.26.6.43.88l-.12-.36m10.945-2.382l-.07.15c-.1.76-.34 1.511-.69 2.212.4-.73.65-1.541.75-2.362M12.45.12c.27-.1.66-.05.95-.12-.37.03-.74.05-1.1.1l.15.02M3.006 5.142c.07.57-.43.8.11.42.3-.66-.11-.18-.1-.42m-.64 2.661c.12-.39.15-.62.2-.84-.35.44-.17.53-.2.83"/></svg>
@@ -0,0 +1,2 @@
+<!-- fedora — from Font Awesome Free 5 brands (CC BY 4.0), via react-icons FaFedora. See README.md. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512" fill="currentColor"><path d="M225 32C101.3 31.7.8 131.7.4 255.4L0 425.7a53.6 53.6 0 0 0 53.6 53.9l170.2.4c123.7.3 224.3-99.7 224.6-223.4S348.7 32.3 225 32zm169.8 157.2L333 126.6c2.3-4.7 3.8-9.2 3.8-14.3v-1.6l55.2 56.1a101 101 0 0 1 2.8 22.4zM331 94.3a106.06 106.06 0 0 1 58.5 63.8l-54.3-54.6a26.48 26.48 0 0 0-4.2-9.2zM118.1 247.2a49.66 49.66 0 0 0-7.7 11.4l-8.5-8.5a85.78 85.78 0 0 1 16.2-2.9zM97 251.4l11.8 11.9-.9 8a34.74 34.74 0 0 0 2.4 12.5l-27-27.2a80.6 80.6 0 0 1 13.7-5.2zm-18.2 7.4l38.2 38.4a53.17 53.17 0 0 0-14.1 4.7L67.6 266a107 107 0 0 1 11.2-7.2zm-15.2 9.8l35.3 35.5a67.25 67.25 0 0 0-10.5 8.5L53.5 278a64.33 64.33 0 0 1 10.1-9.4zm-13.3 12.3l34.9 35a56.84 56.84 0 0 0-7.7 11.4l-35.8-35.9c2.8-3.8 5.7-7.2 8.6-10.5zm-11 14.3l36.4 36.6a48.29 48.29 0 0 0-3.6 15.2l-39.5-39.8a99.81 99.81 0 0 1 6.7-12zm-8.8 16.3l41.3 41.8a63.47 63.47 0 0 0 6.7 26.2L25.8 326c1.4-4.9 2.9-9.6 4.7-14.5zm-7.9 43l61.9 62.2a31.24 31.24 0 0 0-3.6 14.3v1.1l-55.4-55.7a88.27 88.27 0 0 1-2.9-21.9zm5.3 30.7l54.3 54.6a28.44 28.44 0 0 0 4.2 9.2 106.32 106.32 0 0 1-58.5-63.8zm-5.3-37a80.69 80.69 0 0 1 2.1-17l72.2 72.5a37.59 37.59 0 0 0-9.9 8.7zm253.3-51.8l-42.6-.1-.1 56c-.2 69.3-64.4 115.8-125.7 102.9-5.7 0-19.9-8.7-19.9-24.2a24.89 24.89 0 0 1 24.5-24.6c6.3 0 6.3 1.6 15.7 1.6a55.91 55.91 0 0 0 56.1-55.9l.1-47c0-4.5-4.5-9-8.9-9l-33.6-.1c-32.6-.1-32.5-49.4.1-49.3l42.6.1.1-56a105.18 105.18 0 0 1 105.6-105 86.35 86.35 0 0 1 20.2 2.3c11.2 1.8 19.9 11.9 19.9 24 0 15.5-14.9 27.8-30.3 23.9-27.4-5.9-65.9 14.4-66 54.9l-.1 47a8.94 8.94 0 0 0 8.9 9l33.6.1c32.5.2 32.4 49.5-.2 49.4zm23.5-.3a35.58 35.58 0 0 0 7.6-11.4l8.5 8.5a102 102 0 0 1-16.1 2.9zm21-4.2L308.6 280l.9-8.1a34.74 34.74 0 0 0-2.4-12.5l27 27.2a74.89 74.89 0 0 1-13.7 5.3zm18-7.4l-38-38.4c4.9-1.1 9.6-2.4 13.7-4.7l36.2 35.9c-3.8 2.5-7.9 5-11.9 7.2zm15.5-9.8l-35.3-35.5a61.06 61.06 0 0 0 10.5-8.5l34.9 35a124.56 124.56 0 0 1-10.1 9zm13.2-12.3l-34.9-35a63.18 63.18 0 0 0 7.7-11.4l35.8 35.9a130.28 130.28 0 0 1-8.6 10.5zm11-14.3l-36.4-36.6a48.29 48.29 0 0 0 3.6-15.2l39.5 39.8a87.72 87.72 0 0 1-6.7 12zm13.5-30.9a140.63 140.63 0 0 1-4.7 14.3L345.6 190a58.19 58.19 0 0 0-7.1-26.2zm1-5.6l-71.9-72.1a32 32 0 0 0 9.9-9.2l64.3 64.7a90.93 90.93 0 0 1-2.3 16.6z"/></svg>
@@ -0,0 +1,2 @@
+<!-- linux — from Font Awesome Free 5 brands (CC BY 4.0), via react-icons FaLinux. See README.md. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512" fill="currentColor"><path d="M220.8 123.3c1 .5 1.8 1.7 3 1.7 1.1 0 2.8-.4 2.9-1.5.2-1.4-1.9-2.3-3.2-2.9-1.7-.7-3.9-1-5.5-.1-.4.2-.8.7-.6 1.1.3 1.3 2.3 1.1 3.4 1.7zm-21.9 1.7c1.2 0 2-1.2 3-1.7 1.1-.6 3.1-.4 3.5-1.6.2-.4-.2-.9-.6-1.1-1.6-.9-3.8-.6-5.5.1-1.3.6-3.4 1.5-3.2 2.9.1 1 1.8 1.5 2.8 1.4zM420 403.8c-3.6-4-5.3-11.6-7.2-19.7-1.8-8.1-3.9-16.8-10.5-22.4-1.3-1.1-2.6-2.1-4-2.9-1.3-.8-2.7-1.5-4.1-2 9.2-27.3 5.6-54.5-3.7-79.1-11.4-30.1-31.3-56.4-46.5-74.4-17.1-21.5-33.7-41.9-33.4-72C311.1 85.4 315.7.1 234.8 0 132.4-.2 158 103.4 156.9 135.2c-1.7 23.4-6.4 41.8-22.5 64.7-18.9 22.5-45.5 58.8-58.1 96.7-6 17.9-8.8 36.1-6.2 53.3-6.5 5.8-11.4 14.7-16.6 20.2-4.2 4.3-10.3 5.9-17 8.3s-14 6-18.5 14.5c-2.1 3.9-2.8 8.1-2.8 12.4 0 3.9.6 7.9 1.2 11.8 1.2 8.1 2.5 15.7.8 20.8-5.2 14.4-5.9 24.4-2.2 31.7 3.8 7.3 11.4 10.5 20.1 12.3 17.3 3.6 40.8 2.7 59.3 12.5 19.8 10.4 39.9 14.1 55.9 10.4 11.6-2.6 21.1-9.6 25.9-20.2 12.5-.1 26.3-5.4 48.3-6.6 14.9-1.2 33.6 5.3 55.1 4.1.6 2.3 1.4 4.6 2.5 6.7v.1c8.3 16.7 23.8 24.3 40.3 23 16.6-1.3 34.1-11 48.3-27.9 13.6-16.4 36-23.2 50.9-32.2 7.4-4.5 13.4-10.1 13.9-18.3.4-8.2-4.4-17.3-15.5-29.7zM223.7 87.3c9.8-22.2 34.2-21.8 44-.4 6.5 14.2 3.6 30.9-4.3 40.4-1.6-.8-5.9-2.6-12.6-4.9 1.1-1.2 3.1-2.7 3.9-4.6 4.8-11.8-.2-27-9.1-27.3-7.3-.5-13.9 10.8-11.8 23-4.1-2-9.4-3.5-13-4.4-1-6.9-.3-14.6 2.9-21.8zM183 75.8c10.1 0 20.8 14.2 19.1 33.5-3.5 1-7.1 2.5-10.2 4.6 1.2-8.9-3.3-20.1-9.6-19.6-8.4.7-9.8 21.2-1.8 28.1 1 .8 1.9-.2-5.9 5.5-15.6-14.6-10.5-52.1 8.4-52.1zm-13.6 60.7c6.2-4.6 13.6-10 14.1-10.5 4.7-4.4 13.5-14.2 27.9-14.2 7.1 0 15.6 2.3 25.9 8.9 6.3 4.1 11.3 4.4 22.6 9.3 8.4 3.5 13.7 9.7 10.5 18.2-2.6 7.1-11 14.4-22.7 18.1-11.1 3.6-19.8 16-38.2 14.9-3.9-.2-7-1-9.6-2.1-8-3.5-12.2-10.4-20-15-8.6-4.8-13.2-10.4-14.7-15.3-1.4-4.9 0-9 4.2-12.3zm3.3 334c-2.7 35.1-43.9 34.4-75.3 18-29.9-15.8-68.6-6.5-76.5-21.9-2.4-4.7-2.4-12.7 2.6-26.4v-.2c2.4-7.6.6-16-.6-23.9-1.2-7.8-1.8-15 .9-20 3.5-6.7 8.5-9.1 14.8-11.3 10.3-3.7 11.8-3.4 19.6-9.9 5.5-5.7 9.5-12.9 14.3-18 5.1-5.5 10-8.1 17.7-6.9 8.1 1.2 15.1 6.8 21.9 16l19.6 35.6c9.5 19.9 43.1 48.4 41 68.9zm-1.4-25.9c-4.1-6.6-9.6-13.6-14.4-19.6 7.1 0 14.2-2.2 16.7-8.9 2.3-6.2 0-14.9-7.4-24.9-13.5-18.2-38.3-32.5-38.3-32.5-13.5-8.4-21.1-18.7-24.6-29.9s-3-23.3-.3-35.2c5.2-22.9 18.6-45.2 27.2-59.2 2.3-1.7.8 3.2-8.7 20.8-8.5 16.1-24.4 53.3-2.6 82.4.6-20.7 5.5-41.8 13.8-61.5 12-27.4 37.3-74.9 39.3-112.7 1.1.8 4.6 3.2 6.2 4.1 4.6 2.7 8.1 6.7 12.6 10.3 12.4 10 28.5 9.2 42.4 1.2 6.2-3.5 11.2-7.5 15.9-9 9.9-3.1 17.8-8.6 22.3-15 7.7 30.4 25.7 74.3 37.2 95.7 6.1 11.4 18.3 35.5 23.6 64.6 3.3-.1 7 .4 10.9 1.4 13.8-35.7-11.7-74.2-23.3-84.9-4.7-4.6-4.9-6.6-2.6-6.5 12.6 11.2 29.2 33.7 35.2 59 2.8 11.6 3.3 23.7.4 35.7 16.4 6.8 35.9 17.9 30.7 34.8-2.2-.1-3.2 0-4.2 0 3.2-10.1-3.9-17.6-22.8-26.1-19.6-8.6-36-8.6-38.3 12.5-12.1 4.2-18.3 14.7-21.4 27.3-2.8 11.2-3.6 24.7-4.4 39.9-.5 7.7-3.6 18-6.8 29-32.1 22.9-76.7 32.9-114.3 7.2zm257.4-11.5c-.9 16.8-41.2 19.9-63.2 46.5-13.2 15.7-29.4 24.4-43.6 25.5s-26.5-4.8-33.7-19.3c-4.7-11.1-2.4-23.1 1.1-36.3 3.7-14.2 9.2-28.8 9.9-40.6.8-15.2 1.7-28.5 4.2-38.7 2.6-10.3 6.6-17.2 13.7-21.1.3-.2.7-.3 1-.5.8 13.2 7.3 26.6 18.8 29.5 12.6 3.3 30.7-7.5 38.4-16.3 9-.3 15.7-.9 22.6 5.1 9.9 8.5 7.1 30.3 17.1 41.6 10.6 11.6 14 19.5 13.7 24.6zM173.3 148.7c2 1.9 4.7 4.5 8 7.1 6.6 5.2 15.8 10.6 27.3 10.6 11.6 0 22.5-5.9 31.8-10.8 4.9-2.6 10.9-7 14.8-10.4s5.9-6.3 3.1-6.6-2.6 2.6-6 5.1c-4.4 3.2-9.7 7.4-13.9 9.8-7.4 4.2-19.5 10.2-29.9 10.2s-18.7-4.8-24.9-9.7c-3.1-2.5-5.7-5-7.7-6.9-1.5-1.4-1.9-4.6-4.3-4.9-1.4-.1-1.8 3.7 1.7 6.5z"/></svg>
@@ -0,0 +1,2 @@
+<!-- nixos — from Simple Icons (CC0 1.0), via react-icons SiNixos. See README.md. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor"><path d="M7.352 1.592l-1.364.002L5.32 2.75l1.557 2.713-3.137-.008-1.32 2.34H14.11l-1.353-2.332-3.192-.006-2.214-3.865zm6.175 0l-2.687.025 5.846 10.127 1.341-2.34-1.59-2.765 2.24-3.85-.683-1.182h-1.336l-1.57 2.705-1.56-2.72zm6.887 4.195l-5.846 10.125 2.696-.008 1.601-2.76 4.453.016.682-1.183-.666-1.157-3.13-.008L21.778 8.1l-1.365-2.313zM9.432 8.086l-2.696.008-1.601 2.76-4.453-.016L0 12.02l.666 1.157 3.13.008-1.575 2.71 1.365 2.315L9.432 8.086zM7.33 12.25l-.006.01-.002-.004-1.342 2.34 1.59 2.765-2.24 3.85.684 1.182H7.35l.004-.006h.001l1.567-2.698 1.558 2.72 2.688-.026-.004-.006h.01L7.33 12.25zm2.55 3.93l1.354 2.332 3.192.006 2.215 3.865 1.363-.002.668-1.156-1.557-2.713 3.137.008 1.32-2.34H9.881Z"/></svg>
@@ -0,0 +1,2 @@
+<!-- opensuse — from Font Awesome Free 5 brands (CC BY 4.0), via react-icons FaSuse. See README.md. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 512" fill="currentColor"><path d="M471.08 102.66s-.3 18.3-.3 20.3c-9.1-3-74.4-24.1-135.7-26.3-51.9-1.8-122.8-4.3-223 57.3-19.4 12.4-73.9 46.1-99.6 109.7C7 277-.12 307 7 335.06a111 111 0 0 0 16.5 35.7c17.4 25 46.6 41.6 78.1 44.4 44.4 3.9 78.1-16 90-53.3 8.2-25.8 0-63.6-31.5-82.9-25.6-15.7-53.3-12.1-69.2-1.6-13.9 9.2-21.8 23.5-21.6 39.2.3 27.8 24.3 42.6 41.5 42.6a49 49 0 0 0 15.8-2.7c6.5-1.8 13.3-6.5 13.3-14.9 0-12.1-11.6-14.8-16.8-13.9-2.9.5-4.5 2-11.8 2.4-2-.2-12-3.1-12-14V316c.2-12.3 13.2-18 25.5-16.9 32.3 2.8 47.7 40.7 28.5 65.7-18.3 23.7-76.6 23.2-99.7-20.4-26-49.2 12.7-111.2 87-98.4 33.2 5.7 83.6 35.5 102.4 104.3h45.9c-5.7-17.6-8.9-68.3 42.7-68.3 56.7 0 63.9 39.9 79.8 68.3H460c-12.8-18.3-21.7-38.7-18.9-55.8 5.6-33.8 39.7-18.4 82.4-17.4 66.5.4 102.1-27 103.1-28 3.7-3.1 6.5-15.8 7-17.7 1.3-5.1-3.2-2.4-3.2-2.4-8.7 5.2-30.5 15.2-50.9 15.6-25.3.5-76.2-25.4-81.6-28.2-.3-.4.1 1.2-11-25.5 88.4 58.3 118.3 40.5 145.2 21.7.8-.6 4.3-2.9 3.6-5.7-13.8-48.1-22.4-62.7-34.5-69.6-37-21.6-125-34.7-129.2-35.3.1-.1-.9-.3-.9.7zm60.4 72.8a37.54 37.54 0 0 1 38.9-36.3c33.4 1.2 48.8 42.3 24.4 65.2-24.2 22.7-64.4 4.6-63.3-28.9zm38.6-25.3a26.27 26.27 0 1 0 25.4 27.2 26.19 26.19 0 0 0-25.4-27.2zm4.3 28.8c-15.4 0-15.4-15.6 0-15.6s15.4 15.64 0 15.64z"/></svg>
@@ -0,0 +1,2 @@
+<!-- steam — from Font Awesome Free 5 brands (CC BY 4.0), via react-icons FaSteam. See README.md. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512" fill="currentColor"><path d="M496 256c0 137-111.2 248-248.4 248-113.8 0-209.6-76.3-239-180.4l95.2 39.3c6.4 32.1 34.9 56.4 68.9 56.4 39.2 0 71.9-32.4 70.2-73.5l84.5-60.2c52.1 1.3 95.8-40.9 95.8-93.5 0-51.6-42-93.5-93.7-93.5s-93.7 42-93.7 93.5v1.2L176.6 279c-15.5-.9-30.7 3.4-43.5 12.1L0 236.1C10.2 108.4 117.1 8 247.6 8 384.8 8 496 119 496 256zM155.7 384.3l-30.5-12.6a52.79 52.79 0 0 0 27.2 25.8c26.9 11.2 57.8-1.6 69-28.4 5.4-13 5.5-27.3.1-40.3-5.4-13-15.5-23.2-28.5-28.6-12.9-5.4-26.7-5.2-38.9-.6l31.5 13c19.8 8.2 29.2 30.9 20.9 50.7-8.3 19.9-31 29.2-50.8 21zm173.8-129.9c-34.4 0-62.4-28-62.4-62.3s28-62.3 62.4-62.3 62.4 28 62.4 62.3-27.9 62.3-62.4 62.3zm.1-15.6c25.9 0 46.9-21 46.9-46.8 0-25.9-21-46.8-46.9-46.8s-46.9 21-46.9 46.8c.1 25.8 21.1 46.8 46.9 46.8z"/></svg>
@@ -0,0 +1,2 @@
+<!-- ubuntu — from Font Awesome Free 5 brands (CC BY 4.0), via react-icons FaUbuntu. See README.md. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512" fill="currentColor"><path d="M248 8C111 8 0 119 0 256s111 248 248 248 248-111 248-248S385 8 248 8zm52.7 93c8.8-15.2 28.3-20.5 43.5-11.7 15.3 8.8 20.5 28.3 11.7 43.6-8.8 15.2-28.3 20.5-43.5 11.7-15.3-8.9-20.5-28.4-11.7-43.6zM87.4 287.9c-17.6 0-31.9-14.3-31.9-31.9 0-17.6 14.3-31.9 31.9-31.9 17.6 0 31.9 14.3 31.9 31.9 0 17.6-14.3 31.9-31.9 31.9zm28.1 3.1c22.3-17.9 22.4-51.9 0-69.9 8.6-32.8 29.1-60.7 56.5-79.1l23.7 39.6c-51.5 36.3-51.5 112.5 0 148.8L172 370c-27.4-18.3-47.8-46.3-56.5-79zm228.7 131.7c-15.3 8.8-34.7 3.6-43.5-11.7-8.8-15.3-3.6-34.8 11.7-43.6 15.2-8.8 34.7-3.6 43.5 11.7 8.8 15.3 3.6 34.8-11.7 43.6zm.3-69.5c-26.7-10.3-56.1 6.6-60.5 35-5.2 1.4-48.9 14.3-96.7-9.4l22.5-40.3c57 26.5 123.4-11.7 128.9-74.4l46.1.7c-2.3 34.5-17.3 65.5-40.3 88.4zm-5.9-105.3c-5.4-62-71.3-101.2-128.9-74.4l-22.5-40.3c47.9-23.7 91.5-10.8 96.7-9.4 4.4 28.3 33.8 45.3 60.5 35 23.1 22.9 38 53.9 40.2 88.5l-46 .6z"/></svg>
@@ -0,0 +1,2 @@
+<!-- windows — from Font Awesome Free 5 brands (CC BY 4.0), via react-icons FaWindows. See README.md. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512" fill="currentColor"><path d="M0 93.7l183.6-25.3v177.4H0V93.7zm0 324.6l183.6 25.3V268.4H0v149.9zm203.8 28L448 480V268.4H203.8v177.9zm0-380.6v180.1H448V32L203.8 65.7z"/></svg>
@@ -0,0 +1,67 @@
+# Android CI builder: JDK 21 + Android SDK/NDK/CMake + pinned Rust with the three shipping
+# Android targets + cargo-ndk + sccache. Everything android.yml used to download per run
+# (~3 GB of NDK + SDK packages from Google, plus a from-source cargo-ndk build) is baked
+# here instead; the image is content-keyed and rebuilt only when the ci/ tree changes
+# (docker.yml `builders`).
+#
+#   docker build -f ci/android-ci.Dockerfile -t punktfunk-android-ci ci
+#
+# Version pins mirror what android.yml installed via sdkmanager: AGP 9.3 wants JDK 17–21;
+# cmake;3.22.1 because kit/build.gradle.kts prepends $ANDROID_SDK/cmake/3.22.1/bin to PATH
+# for cargo-ndk's audiopus_sys (libopus) CMake build; platforms;android-37 is deliberately
+# absent (AGP auto-downloads it if a build ever needs it — same note as the old workflow).
+FROM ubuntu:26.04
+
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        ca-certificates curl git unzip zip python3 openjdk-21-jdk-headless \
+        build-essential pkg-config \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
+
+# Android SDK: cmdline-tools must land under cmdline-tools/latest for sdkmanager to
+# find its own root.
+ENV ANDROID_HOME=/opt/android-sdk \
+    ANDROID_SDK_ROOT=/opt/android-sdk
+ARG CMDLINE_TOOLS=13114758
+RUN mkdir -p "$ANDROID_HOME/cmdline-tools" \
+    && curl -fsSL -o /tmp/clt.zip "https://dl.google.com/android/repository/commandlinetools-linux-${CMDLINE_TOOLS}_latest.zip" \
+    && unzip -q /tmp/clt.zip -d "$ANDROID_HOME/cmdline-tools" \
+    && mv "$ANDROID_HOME/cmdline-tools/cmdline-tools" "$ANDROID_HOME/cmdline-tools/latest" \
+    && rm /tmp/clt.zip
+ENV PATH=$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$PATH
+RUN yes | sdkmanager --licenses >/dev/null \
+    && sdkmanager "platform-tools" "platforms;android-36" "build-tools;37.0.0" \
+        "ndk;30.0.14904198" "cmake;3.22.1" \
+    && chmod -R a+rX "$ANDROID_HOME"
+
+# Toolchain shared across CI users (jobs may run as different uids) — same shape as
+# rust-ci.Dockerfile, plus the Android cross targets and cargo-ndk. The registry/git
+# download caches are stripped after the cargo-ndk install: jobs restore those from the
+# shared actions cache, and baking them would only bloat every pull.
+ENV RUSTUP_HOME=/usr/local/rustup \
+    CARGO_HOME=/usr/local/cargo \
+    PATH=/usr/local/cargo/bin:$PATH
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
+    | sh -s -- -y --no-modify-path --profile minimal \
+    && rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android \
+    && cargo install cargo-ndk --locked \
+    && rm -rf "$CARGO_HOME/registry" "$CARGO_HOME/git" \
+    && chmod -R a+w "$RUSTUP_HOME" "$CARGO_HOME" \
+    && rustc --version && cargo ndk --version
+
+# Shared compile cache: jobs set RUSTC_WRAPPER=sccache (backend = RustFS S3 on the LAN,
+# see .gitea/workflows — the env lives there so dev use of this image stays uncached).
+ARG SCCACHE_VERSION=0.10.0
+RUN curl -fsSL "https://github.com/mozilla/sccache/releases/download/v${SCCACHE_VERSION}/sccache-v${SCCACHE_VERSION}-x86_64-unknown-linux-musl.tar.gz" \
+    | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache' \
+    && sccache --version
+
+# actions/checkout (and every other JS action: cache, upload-artifact) execs `node` INSIDE
+# the job container — no node, no checkout (exit 127; same lesson flatpak.yml documents for
+# fedora:43). A separate trailing layer on purpose: appending here keeps the fat SDK/NDK
+# layers above cache-valid instead of invalidating the whole build.
+RUN apt-get update && apt-get install -y --no-install-recommends nodejs \
+    && rm -rf /var/lib/apt/lists/* \
+    && node --version
@@ -0,0 +1,42 @@
+# Arch CI builder: base-devel + every dependency arch.yml's two makepkg legs used to
+# pacman-install per run (~1 GB of mirror traffic each time) + bun + sccache + nodejs
+# (JS actions exec node INSIDE the job container — the same lesson as android-ci).
+# Content-keyed and rebuilt only when the ci/ tree changes (docker.yml `builders`).
+#
+#   docker build -f ci/arch-ci.Dockerfile -t punktfunk-arch-ci ci
+#
+# ROLLING-RELEASE TRADEOFF, on purpose: packages now build against the Arch snapshot
+# from the last image rebuild instead of a fresh -Syu per run. That is the same staleness
+# the gamescope cache already embraces ("a stale binary against newer system libs is the
+# same risk the distro's own package carries between rebuilds"), and any ci/ edit — or
+# bumping the date in this line (refreshed: 2026-07-29) — re-keys and re-snapshots it.
+FROM docker.io/library/archlinux:base-devel
+
+# One transaction: the main build/runtime deps (first list) + the gamescope companion's
+# deps (second list) — both copied verbatim from what arch.yml installed in-job, where
+# they now no-op as `--needed` guards.
+RUN pacman -Syu --noconfirm --needed \
+        git nodejs rust clang cmake ninja nasm pkgconf python vulkan-headers \
+        gtk4 libadwaita sdl3 ffmpeg pipewire wayland libxkbcommon opus libei \
+        mesa libglvnd unzip libarchive \
+        glslang libcap libdrm libinput libx11 libxcomposite libxdamage libxext \
+        libxmu libxrender libxres libxtst libxxf86vm libavif libdecor \
+        hwdata luajit seatd sdl2-compat vulkan-icd-loader \
+        xcb-util-errors xcb-util-wm xorg-xwayland \
+        meson glm wayland-protocols benchmark libxcursor \
+    && pacman -Scc --noconfirm
+
+# bun builds the punktfunk-web console + the punktfunk-scripting runner AND is vendored
+# as their runtime (PF_WITH_WEB=1 / PF_WITH_SCRIPTING=1); it's AUR-only on Arch, so
+# bootstrap the official binary — once, here, instead of per run.
+RUN curl -fsSL https://bun.sh/install | bash \
+    && install -m0755 /root/.bun/bin/bun /usr/local/bin/bun \
+    && rm -rf /root/.bun \
+    && bun --version
+
+# Shared compile cache: jobs set RUSTC_WRAPPER=sccache (backend = RustFS S3 on the LAN,
+# see .gitea/workflows — the env lives there so dev use of this image stays uncached).
+ARG SCCACHE_VERSION=0.10.0
+RUN curl -fsSL "https://github.com/mozilla/sccache/releases/download/v${SCCACHE_VERSION}/sccache-v${SCCACHE_VERSION}-x86_64-unknown-linux-musl.tar.gz" \
+    | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache' \
+    && sccache --version
@@ -66,3 +66,11 @@ RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
    | sh -s -- -y --no-modify-path --profile minimal \
    && chmod -R a+w "$RUSTUP_HOME" "$CARGO_HOME" \
    && rustc --version && cargo --version
+
+# Shared compile cache: jobs set RUSTC_WRAPPER=sccache (backend = RustFS S3 on the LAN,
+# see .gitea/workflows — the env lives there so dev use of this image stays uncached).
+# musl build: one static binary serves the Ubuntu and Fedora images alike.
+ARG SCCACHE_VERSION=0.10.0
+RUN curl -fsSL "https://github.com/mozilla/sccache/releases/download/v${SCCACHE_VERSION}/sccache-v${SCCACHE_VERSION}-x86_64-unknown-linux-musl.tar.gz" \
+    | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache' \
+    && sccache --version
@@ -16,7 +16,7 @@
 # explicit `Architectures:` or apt tries to fetch arm64 from the amd64 mirror and 404s.
 #
 # Built from the REPO ROOT context (not ci/) — see the rust-toolchain.toml copy below.
-FROM git.unom.io/unom/punktfunk-rust-ci:latest
+FROM 192.168.1.58:5010/punktfunk-rust-ci:latest

 ENV DEBIAN_FRONTEND=noninteractive

@@ -83,3 +83,11 @@ RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
        --component rustfmt,clippy \
    && chmod -R a+w "$RUSTUP_HOME" "$CARGO_HOME" \
    && rustc --version && cargo clippy --version && cargo fmt --version
+
+# Shared compile cache: jobs set RUSTC_WRAPPER=sccache (backend = RustFS S3 on the LAN,
+# see .gitea/workflows — the env lives there so dev use of this image stays uncached).
+# musl build: one static binary serves the Ubuntu and Fedora images alike.
+ARG SCCACHE_VERSION=0.10.0
+RUN curl -fsSL "https://github.com/mozilla/sccache/releases/download/v${SCCACHE_VERSION}/sccache-v${SCCACHE_VERSION}-x86_64-unknown-linux-musl.tar.gz" \
+    | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache' \
+    && sccache --version
@@ -50,3 +50,11 @@ RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
        --component rustfmt,clippy \
    && chmod -R a+w "$RUSTUP_HOME" "$CARGO_HOME" \
    && rustc --version && cargo clippy --version && cargo fmt --version
+
+# Shared compile cache: jobs set RUSTC_WRAPPER=sccache (backend = RustFS S3 on the LAN,
+# see .gitea/workflows — the env lives there so dev use of this image stays uncached).
+# musl build: one static binary serves the Ubuntu and Fedora images alike.
+ARG SCCACHE_VERSION=0.10.0
+RUN curl -fsSL "https://github.com/mozilla/sccache/releases/download/v${SCCACHE_VERSION}/sccache-v${SCCACHE_VERSION}-x86_64-unknown-linux-musl.tar.gz" \
+    | tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache' \
+    && sccache --version
@@ -90,6 +90,21 @@
                <!-- TV launcher entry. -->
                <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
            </intent-filter>
+            <!-- punktfunk:// deep links (design/client-deep-links.md §2): an external tool, an OS
+                 shortcut or a wiki page opens a stream on a host this device already trusts. The
+                 URL carries only REFERENCES to things that exist here (a host record, a settings
+                 profile, a library id) — never resolution/bitrate/codec values, and never a
+                 pairing route; MainActivity's router enforces the rest. BROWSABLE is what lets a
+                 browser hand it over (behind its own "Open Punktfunk?" prompt).
+                 NOTE: launchMode deliberately stays `standard` and the configChanges set above is
+                 untouched — its `keyboard` entry is what keeps an SC2 claim from killing a running
+                 stream, and neither has anything to gain from this filter. -->
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="punktfunk" />
+            </intent-filter>
        </activity>
    </application>
 </manifest>
@@ -31,8 +31,9 @@ import androidx.compose.material3.Scaffold
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.CompositionLocalProvider
+import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
-import androidx.compose.runtime.mutableLongStateOf
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
@@ -42,14 +43,23 @@ import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.platform.LocalDensity
 import androidx.compose.ui.unit.Density
 import androidx.compose.ui.unit.dp
+import android.widget.Toast
+import io.unom.punktfunk.kit.link.DeepLinkResult
+import io.unom.punktfunk.kit.link.DeepLinks
+import io.unom.punktfunk.kit.link.HostResolution
+import io.unom.punktfunk.kit.security.KnownHostStore
+import io.unom.punktfunk.models.ActiveSession
 import io.unom.punktfunk.models.Tab

@Composable
 fun App(forceGamepadUi: Boolean = false) {
    val context = LocalContext.current
+    val activity = context as? MainActivity
    val settingsStore = remember { SettingsStore(context) }
    var settings by remember { mutableStateOf(settingsStore.load()) }
-    var streamHandle by remember { mutableLongStateOf(0L) } // 0 = not streaming
+    // The active session (null = not streaming). It carries the settings the connect resolved,
+    // so the stream screen never re-reads the store behind its own connect's back.
+    var session by remember { mutableStateOf<ActiveSession?>(null) }
    var tab by remember { mutableStateOf(Tab.Connect) }

    // Console (gamepad) mode mirrors the Apple client: the setting AND (a pad is attached OR this is
@@ -58,21 +68,53 @@ fun App(forceGamepadUi: Boolean = false) {
    val controllerConnected by rememberControllerConnected()
    val gamepadUi = gamepadUiActive(settings.gamepadUiEnabled, controllerConnected, tv, forceGamepadUi)

+    // Publish the live session process-wide, so a `punktfunk://` link that arrives as a SECOND
+    // activity instance (the normal case under `launchMode = standard`) can refuse it before that
+    // instance is ever resumed — see MainActivity.onCreate. Cleared on dispose, so an activity
+    // destroyed mid-stream doesn't leave a ghost that blocks every future link.
+    DisposableEffect(session) {
+        MainActivity.liveStream = session?.let { MainActivity.LiveStream(it.hostId) }
+        onDispose { MainActivity.liveStream = null }
+    }
+
+    // The same rule for the rare in-instance case (a caller that set FLAG_ACTIVITY_SINGLE_TOP, so
+    // the link reached `onNewIntent` on the streaming activity itself). Pointing at the host
+    // already being streamed is the one exception, and its right answer is to do nothing — the
+    // intent has already brought the app forward, which is exactly what "focus it" means here.
+    val pendingLink = activity?.pendingDeepLink
+    LaunchedEffect(pendingLink, session) {
+        val url = pendingLink ?: return@LaunchedEffect
+        val live = session ?: return@LaunchedEffect // not streaming: ConnectScreen routes it
+        activity.pendingDeepLink = null
+        val parsed = DeepLinks.parse(url) as? DeepLinkResult.Parsed ?: return@LaunchedEffect
+        val target = DeepLinks.resolveHost(parsed.link, KnownHostStore(context).all())
+        val sameHost = target is HostResolution.Known && target.host.id == live.hostId
+        if (!sameHost) {
+            Toast.makeText(
+                context,
+                "Already streaming — end this session first.",
+                Toast.LENGTH_LONG,
+            ).show()
+        }
+    }
+
    AnimatedContent(
-        targetState = streamHandle != 0L,
+        targetState = session,
        transitionSpec = {
            fadeIn() togetherWith fadeOut()
        },
        label = "StreamTransition"
-    ) { isStreaming ->
-        if (isStreaming) {
+    ) { active ->
+        if (active != null) {
            // Immersive: the stream takes the whole screen, no bottom bar.
-            StreamScreen(streamHandle, micEnabled = settings.micEnabled, onDisconnect = { streamHandle = 0L })
+            StreamScreen(active, onDisconnect = { session = null })
        } else if (gamepadUi) {
            GamepadShell(
                settings = settings,
                onSettingsChange = { settings = it; settingsStore.save(it) },
-                onConnected = { streamHandle = it },
+                onConnected = { session = it },
+                deepLink = pendingLink,
+                onDeepLinkHandled = { activity?.pendingDeepLink = null },
            )
        } else {
            // Adaptive nav: a bottom bar on phones; on tablets / large windows a side NavigationRail
@@ -103,7 +145,13 @@ fun App(forceGamepadUi: Boolean = false) {
                    label = "TabTransition"
                ) { targetTab ->
                    when (targetTab) {
-                        Tab.Connect -> ConnectScreen(settings = settings, onConnected = { streamHandle = it })
+                        Tab.Connect -> ConnectScreen(
+                            settings = settings,
+                            onConnected = { session = it },
+                            onSettingsChange = { settings = it; settingsStore.save(it) },
+                            deepLink = pendingLink,
+                            onDeepLinkHandled = { activity?.pendingDeepLink = null },
+                        )
                        Tab.Settings -> SettingsScreen(
                            initial = settings,
                            onChange = { settings = it; settingsStore.save(it) },
@@ -167,7 +215,9 @@ private enum class GamepadScreen { Home, Settings, Library }
 fun GamepadShell(
    settings: Settings,
    onSettingsChange: (Settings) -> Unit,
-    onConnected: (Long) -> Unit,
+    onConnected: (ActiveSession) -> Unit,
+    deepLink: String? = null,
+    onDeepLinkHandled: () -> Unit = {},
 ) {
    val context = LocalContext.current
    var screen by remember { mutableStateOf(GamepadScreen.Home) }
@@ -194,6 +244,9 @@ fun GamepadShell(
            GamepadScreen.Home -> ConnectScreen(
                settings = settings,
                onConnected = onConnected,
+                onSettingsChange = onSettingsChange,
+                deepLink = deepLink,
+                onDeepLinkHandled = onDeepLinkHandled,
                gamepadUi = true,
                onOpenSettings = { screen = GamepadScreen.Settings },
                onOpenLibrary = { host -> libraryHost = host; screen = GamepadScreen.Library },
@@ -19,6 +19,7 @@ import androidx.compose.material3.ExperimentalMaterial3Api
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.ModalBottomSheet
 import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Switch
 import androidx.compose.material3.Text
 import androidx.compose.material3.TextButton
 import androidx.compose.material3.rememberModalBottomSheetState
@@ -353,16 +354,18 @@ internal fun AwaitingApprovalDialog(hostLabel: String, onCancel: () -> Unit) {
 }

 /**
- * Edit a saved host: name, address, port, and the Wake-on-LAN MAC. The MAC is auto-learned from the
- * host's mDNS advert while it's online, but this is where you can enter or correct it (e.g. to wake a
- * host you've only ever reached by address). [suggestedMacs] prefills the field from the live advert
- * when nothing's been learned yet. Keyed by the host so reopening resets the fields. Mirrors the
- * Apple client's edit form.
+ * Edit a saved host: name, address, port, the Wake-on-LAN MAC, and the per-host settings the record
+ * owns — shared clipboard (a trust decision about THIS machine, so it was never really a global).
+ * The MAC is auto-learned from the host's mDNS advert while it's online, but this is where you can
+ * enter or correct it (e.g. to wake a host you've only ever reached by address). [suggestedMacs]
+ * prefills the field from the live advert when nothing's been learned yet. Keyed by the host so
+ * reopening resets the fields. Mirrors the Apple client's edit form.
 */
@Composable
 internal fun EditHostDialog(
    target: KnownHost,
    suggestedMacs: List<String>,
+    profiles: List<StreamProfile>,
    onSave: (KnownHost) -> Unit,
    onDismiss: () -> Unit,
 ) {
@@ -372,6 +375,13 @@ internal fun EditHostDialog(
    var mac by remember(target) {
        mutableStateOf(target.mac.ifEmpty { suggestedMacs }.joinToString(", "))
    }
+    var clipboard by remember(target) { mutableStateOf(target.clipboardSync) }
+    // A binding whose profile was deleted reads as "Default settings" (which is what it already
+    // resolves to) and is cleaned off the record on the next save — never an error state.
+    var boundId by remember(target, profiles) {
+        mutableStateOf(target.profileId?.takeIf { id -> profiles.any { it.id == id } })
+    }
+    var pins by remember(target) { mutableStateOf(target.pinnedProfileIds) }
    AlertDialog(
        onDismissRequest = onDismiss,
        title = { Text("Edit host") },
@@ -407,6 +417,31 @@ internal fun EditHostDialog(
                    placeholder = { Text("auto-filled when the host is seen") },
                    singleLine = true,
                )
+                Row(
+                    modifier = Modifier.fillMaxWidth(),
+                    verticalAlignment = Alignment.CenterVertically,
+                ) {
+                    Column(Modifier.weight(1f)) {
+                        Text("Shared clipboard", style = MaterialTheme.typography.bodyLarge)
+                        Text(
+                            "Text copied here pastes on this host and vice versa",
+                            style = MaterialTheme.typography.bodySmall,
+                            color = MaterialTheme.colorScheme.onSurfaceVariant,
+                        )
+                    }
+                    Switch(checked = clipboard, onCheckedChange = { clipboard = it })
+                }
+                if (profiles.isNotEmpty()) {
+                    HostProfileBinding(
+                        profiles = profiles,
+                        boundId = boundId,
+                        onBind = { boundId = it },
+                        pins = pins,
+                        onTogglePin = { id ->
+                            pins = if (id in pins) pins - id else pins + id
+                        },
+                    )
+                }
            }
        },
        confirmButton = {
@@ -419,6 +454,9 @@ internal fun EditHostDialog(
                            address = address.trim(),
                            port = port.toIntOrNull() ?: target.port,
                            mac = KnownHostStore.parseMacs(mac),
+                            clipboardSync = clipboard,
+                            profileId = boundId,
+                            pinnedProfileIds = pins,
                        ),
                    )
                },
@@ -429,3 +467,103 @@ internal fun EditHostDialog(
        },
    )
 }
+
+/**
+ * The network speed test, as a dialog: it narrates while it measures, then offers to apply the
+ * recommendation to the layer the tested host actually reads bitrate from — see [SpeedTestTarget]
+ * for why that is the interesting part. The apply buttons name their destination, so the write is
+ * never a surprise.
+ */
+@Composable
+internal fun SpeedTestDialog(
+    hostName: String,
+    target: SpeedTestTarget,
+    phase: SpeedTestPhase,
+    onApply: (toProfile: Boolean) -> Unit,
+    onDismiss: () -> Unit,
+) {
+    val done = phase as? SpeedTestPhase.Done
+    AlertDialog(
+        // Measuring can't be cancelled mid-burst (the host is already sending), so a stray tap
+        // outside shouldn't look like it did something.
+        onDismissRequest = { if (done != null || phase is SpeedTestPhase.Failed) onDismiss() },
+        title = { Text("Network speed test") },
+        text = {
+            Column(verticalArrangement = Arrangement.spacedBy(12.dp)) {
+                Text(hostName, style = MaterialTheme.typography.titleMedium)
+                when (phase) {
+                    SpeedTestPhase.Connecting, SpeedTestPhase.Measuring -> Row(
+                        verticalAlignment = Alignment.CenterVertically,
+                        horizontalArrangement = Arrangement.spacedBy(12.dp),
+                    ) {
+                        CircularProgressIndicator(modifier = Modifier.size(20.dp), strokeWidth = 2.dp)
+                        Text(
+                            if (phase == SpeedTestPhase.Connecting) {
+                                "Connecting…"
+                            } else {
+                                "Measuring — the host is bursting test traffic for two seconds."
+                            },
+                        )
+                    }
+                    is SpeedTestPhase.Failed -> Text(
+                        phase.message,
+                        color = MaterialTheme.colorScheme.error,
+                    )
+                    is SpeedTestPhase.Done -> Column(verticalArrangement = Arrangement.spacedBy(4.dp)) {
+                        Text(
+                            "%.0f Mbit/s measured · %.1f %% loss".format(
+                                phase.measuredMbps,
+                                phase.lossPct,
+                            ),
+                            style = MaterialTheme.typography.bodyLarge,
+                        )
+                        Text(
+                            "Recommended bitrate: %.0f Mbit/s".format(phase.recommendedMbps),
+                            style = MaterialTheme.typography.bodyLarge,
+                        )
+                        Text(
+                            speedTestTargetNote(target),
+                            style = MaterialTheme.typography.bodySmall,
+                            color = MaterialTheme.colorScheme.onSurfaceVariant,
+                        )
+                    }
+                }
+            }
+        },
+        confirmButton = {
+            if (done != null) {
+                TextButton(onClick = { onApply(true) }) {
+                    Text(
+                        when (target) {
+                            SpeedTestTarget.Global -> "Apply"
+                            is SpeedTestTarget.Profile -> "Apply to “${target.profile.name}”"
+                            is SpeedTestTarget.Ask -> "Set in “${target.profile.name}”"
+                        },
+                    )
+                }
+            }
+        },
+        dismissButton = {
+            Row {
+                // The both-are-defensible case: the user picks the layer, we don't guess.
+                if (done != null && target is SpeedTestTarget.Ask) {
+                    TextButton(onClick = { onApply(false) }) { Text("Set as default") }
+                }
+                TextButton(onClick = onDismiss) { Text("Close") }
+            }
+        },
+    )
+}
+
+/** One line saying which layer an Apply will write to, and why that one. */
+private fun speedTestTargetNote(target: SpeedTestTarget): String = when (target) {
+    SpeedTestTarget.Global ->
+        "This host uses the default settings, so the bitrate goes there."
+    is SpeedTestTarget.Profile ->
+        "This host streams with “${target.profile.name}”, which sets its own bitrate — " +
+            "that override is what it actually reads."
+    is SpeedTestTarget.Ask ->
+        "This host streams with “${target.profile.name}”, which currently inherits the default " +
+            "bitrate. Setting it in the profile affects only this host's profile; setting it as " +
+            "the default affects everything that inherits it."
+}
@@ -53,16 +53,23 @@ import androidx.lifecycle.LifecycleEventObserver
 import androidx.lifecycle.LifecycleOwner
 import io.unom.punktfunk.components.EmptyHostsState
 import io.unom.punktfunk.components.HostCard
+import io.unom.punktfunk.components.HostMenuItem
 import io.unom.punktfunk.components.SectionLabel
 import io.unom.punktfunk.kit.Gamepad
 import io.unom.punktfunk.kit.NativeBridge
 import io.unom.punktfunk.kit.discovery.DiscoveredHost
 import io.unom.punktfunk.kit.discovery.HostDiscovery
+import io.unom.punktfunk.kit.link.DeepLinkResult
+import io.unom.punktfunk.kit.link.DeepLinks
+import io.unom.punktfunk.kit.link.HostResolution
+import io.unom.punktfunk.kit.link.LinkError
+import io.unom.punktfunk.kit.link.LinkRoute
 import io.unom.punktfunk.kit.security.ClientIdentity
 import io.unom.punktfunk.kit.security.IdentityStore
 import io.unom.punktfunk.kit.security.KnownHost
 import io.unom.punktfunk.kit.security.KnownHostStore
 import io.unom.punktfunk.kit.security.obtainIdentity
+import io.unom.punktfunk.models.ActiveSession
 import io.unom.punktfunk.models.HostStatus
 import io.unom.punktfunk.models.PendingTrust
 import java.util.concurrent.atomic.AtomicBoolean
@@ -101,7 +108,10 @@ private class ConnectAttempt(val hostName: String) {
@Composable
 fun ConnectScreen(
    settings: Settings,
-    onConnected: (Long) -> Unit,
+    onConnected: (ActiveSession) -> Unit,
+    // Writes the global defaults back. Only the speed test uses it — that is the one action on this
+    // screen that can land in the defaults layer (design/client-settings-profiles.md §5.3).
+    onSettingsChange: (Settings) -> Unit = {},
    // Console (gamepad) mode: render the host carousel instead of the touch grid, sharing all of this
    // screen's connect/trust/discovery logic. [onOpenSettings]/[onOpenLibrary] are the X/Y actions the
    // gamepad shell owns (the touch UI reaches Settings via the bottom bar and has no library button).
@@ -109,6 +119,11 @@ fun ConnectScreen(
    onOpenSettings: () -> Unit = {},
    onOpenLibrary: (KnownHost) -> Unit = {},
    navGate: Boolean = true, // false while the console home is cross-fading out
+    // A `punktfunk://` URL to route (design/client-deep-links.md §3). This screen owns it because
+    // it owns the connect path — trust decisions, the local-network grant, wake-and-retry — and a
+    // link must go through all of them, not around them.
+    deepLink: String? = null,
+    onDeepLinkHandled: () -> Unit = {},
 ) {
    val scope = rememberCoroutineScope()
    val context = LocalContext.current
@@ -117,6 +132,10 @@ fun ConnectScreen(
    var port by remember { mutableStateOf("9777") }
    var connecting by remember { mutableStateOf(false) }
    var status by remember { mutableStateOf<String?>(null) }
+    // A confirmation, as opposed to [status]'s failures — "75 Mbit/s set in “Travel”". Separate
+    // state because the two read completely differently: an error banner is red on purpose, and a
+    // successful write dressed as one is a small lie every time it appears.
+    var notice by remember { mutableStateOf<String?>(null) }
    // A plain dial in flight (drives the "Connecting…" phase of the full-screen ConnectOverlay); null
    // when idle or when the request-access / wake flows own the screen instead.
    var attempt by remember { mutableStateOf<ConnectAttempt?>(null) }
@@ -195,6 +214,11 @@ fun ConnectScreen(
    val identityStore = remember { IdentityStore(context) }
    val knownHostStore = remember { KnownHostStore(context) }
    var savedHosts by remember { mutableStateOf(knownHostStore.all()) }
+    // The settings-profile catalog. Read here (not in the settings screen's copy) because this is
+    // where profiles are USED: to resolve what a tap connects with, to offer the one-offs, and to
+    // render the pinned cards. Re-read on entry, since Settings may have changed it in between.
+    val profileStore = remember { ProfileStore(context) }
+    var profiles by remember { mutableStateOf(profileStore.all()) }
    // Wakes a sleeping saved host and waits for it to reappear on mDNS before dialing (its overlay
    // rides over both the touch and console home). Fire-and-forget WoL isn't enough — a cold boot can
    // take a minute-plus to advertise again.
@@ -213,6 +237,13 @@ fun ConnectScreen(
                    knownHostStore.learnMac(dh.host, dh.port, dh.mac)
                    any = true
                }
+                // Same for the OS-identity chain, so the card's icon survives the host sleeping.
+                if (dh.os.isNotEmpty() &&
+                    knownHostStore.get(dh.host, dh.port)?.let { it.os != dh.os } == true
+                ) {
+                    knownHostStore.learnOs(dh.host, dh.port, dh.os)
+                    any = true
+                }
            }
            any
        }
@@ -258,7 +289,7 @@ fun ConnectScreen(
    var editTarget by remember { mutableStateOf<KnownHost?>(null) }
    // A saved host whose console options menu (Wake / Edit / Forget) is open — reached with Up on the
    // carousel (the console counterpart of the touch host card's overflow menu).
-    var optionsTarget by remember { mutableStateOf<KnownHost?>(null) }
+    var optionsTarget by remember { mutableStateOf<HostCardEntry?>(null) }

    // Discovered hosts not already saved — a saved host (paired or TOFU) belongs in "Saved hosts",
    // not also in "Discovered", so we hide the overlap (matched by fingerprint when both carry it, so
@@ -267,15 +298,44 @@ fun ConnectScreen(

    // Issue the native connect (shared by the normal connect and the request-access path). A plain
    // desktop connect (no library launch) — the library launcher calls [connectToHost] with an id.
-    suspend fun connectNative(id: ClientIdentity, targetHost: String, targetPort: Int, pinHex: String, timeoutMs: Int): Long =
-        connectToHost(context, settings, id, targetHost, targetPort, pinHex, launch = null, timeoutMs = timeoutMs)
+    suspend fun connectNative(
+        id: ClientIdentity,
+        targetHost: String,
+        targetPort: Int,
+        pinHex: String,
+        timeoutMs: Int,
+        profile: StreamProfile?,
+        launch: String?,
+    ): Long = connectToHost(
+        context, settings.effectiveFor(profile), id, targetHost, targetPort, pinHex,
+        launch = launch, timeoutMs = timeoutMs,
+    )
+
+    // What the stream screen is handed: the settings this connect actually used, plus the HOST's
+    // clipboard decision (a property of the record, not a global). A host we never saved — a
+    // connect that failed to pin — falls back to the on default the setting always had.
+    fun session(handle: Long, record: KnownHost?, profile: StreamProfile?) = ActiveSession(
+        handle,
+        settings.effectiveFor(profile),
+        clipboardSync = record?.clipboardSync ?: true,
+        profileName = profile?.name,
+        hostId = record?.id,
+    )

    // The actual dial (identity already ready). On a TOFU connect (pinHex null), pin the fingerprint
    // the host presented (as an unpaired known host) so the next connect goes straight through and it
    // appears in the saved-hosts list. [onFailure], when set, takes over a failed dial (the wake-wait
    // fallback) instead of the error status line — discovery is already restarted when it runs, so
    // the wait can observe the host reappear.
-    fun doConnectDirect(targetHost: String, targetPort: Int, name: String, pinHex: String?, onFailure: (() -> Unit)? = null) {
+    fun doConnectDirect(
+        targetHost: String,
+        targetPort: Int,
+        name: String,
+        pinHex: String?,
+        profile: StreamProfile?,
+        launch: String? = null,
+        onFailure: (() -> Unit)? = null,
+    ) {
        val id = identity ?: run {
            status = "Identity not ready yet — try again in a moment"
            return
@@ -284,9 +344,11 @@ fun ConnectScreen(
        attempt = thisAttempt // shows the ConnectOverlay's "Connecting…" phase immediately
        connecting = true
        status = null
+        notice = null
        discovery.stop() // free the Wi-Fi radio before the stream session
        scope.launch {
-            val handle = connectNative(id, targetHost, targetPort, pinHex ?: "", CONNECT_TIMEOUT_MS)
+            val handle =
+                connectNative(id, targetHost, targetPort, pinHex ?: "", CONNECT_TIMEOUT_MS, profile, launch)
            // Cancelled mid-dial: the UI's already been returned (and discovery restarted) by
            // cancelConnect — drop the just-opened session silently rather than navigating into it.
            if (thisAttempt.cancelled.get()) {
@@ -296,13 +358,14 @@ fun ConnectScreen(
            attempt = null
            connecting = false
            if (handle != 0L) {
+                var record = knownHostStore.get(targetHost, targetPort)
                if (pinHex == null) { // TOFU: pin what we observed (unpaired)
                    val fp = NativeBridge.nativeHostFingerprint(handle)
                    if (fp.isNotEmpty()) {
-                        knownHostStore.save(KnownHost(targetHost, targetPort, name, fp, paired = false))
+                        record = knownHostStore.trust(targetHost, targetPort, name, fp, paired = false)
                    }
                }
-                onConnected(handle)
+                onConnected(session(handle, record, profile))
            } else {
                discovery.start()
                val token = NativeBridge.nativeTakeLastError()
@@ -339,12 +402,22 @@ fun ConnectScreen(
    // only a FAILED dial falls into the wake-and-WAIT-for-mDNS flow (WakeController's "Waking…"
    // overlay), which redials once the host reappears. Otherwise (auto-wake off, no MAC, or already
    // seen live) dial straight through.
-    fun doConnect(targetHost: String, targetPort: Int, name: String, pinHex: String?) {
+    fun doConnect(
+        targetHost: String,
+        targetPort: Int,
+        name: String,
+        pinHex: String?,
+        oneOffProfile: String?,
+        launch: String? = null,
+    ) {
        if (identity == null) {
            status = "Identity not ready yet — try again in a moment"
            return
        }
        val kh = knownHostStore.get(targetHost, targetPort)
+        // Latched here, not per dial attempt: a wake-and-redial must stream with the same profile
+        // the user asked for, and the "applies from the next session" footers stay truthful.
+        val profile = profileStore.resolveFor(kh, oneOffProfile)
        val macs = kh?.mac ?: emptyList()
        // "Up" = a live advert that is THIS host — matched by fingerprint first (so it survives a DHCP
        // address change on a cold boot), else by address:port. Returns the CURRENT advert so we can
@@ -355,7 +428,7 @@ fun ConnectScreen(
        if (settings.autoWakeEnabled && macs.isNotEmpty() && liveAdvert() == null) {
            // Fire-and-forget first packet (harmless if it's awake), then dial-first.
            scope.launch(Dispatchers.IO) { NativeBridge.nativeWakeOnLan(macs.joinToString(","), targetHost) }
-            doConnectDirect(targetHost, targetPort, name, pinHex, onFailure = {
+            doConnectDirect(targetHost, targetPort, name, pinHex, profile, launch, onFailure = {
                waker.start(
                    hostName = name,
                    connectsAfter = true,
@@ -368,15 +441,18 @@ fun ConnectScreen(
                        // connects) point at the live one, then dial there (no fallback on this
                        // redial — a second failure surfaces as the plain error).
                        if (live != null && kh != null && (live.host != kh.address || live.port != kh.port)) {
-                            knownHostStore.update(kh.address, kh.port, kh.copy(address = live.host, port = live.port))
+                            knownHostStore.save(kh.copy(address = live.host, port = live.port))
                            savedHosts = knownHostStore.all()
                        }
-                        doConnectDirect(live?.host ?: targetHost, live?.port ?: targetPort, name, pinHex)
+                        doConnectDirect(
+                            live?.host ?: targetHost, live?.port ?: targetPort, name, pinHex,
+                            profile, launch,
+                        )
                    },
                )
            })
        } else {
-            doConnectDirect(targetHost, targetPort, name, pinHex)
+            doConnectDirect(targetHost, targetPort, name, pinHex, profile, launch)
        }
    }

@@ -401,7 +477,12 @@ fun ConnectScreen(
            // 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)
+            // A host being trusted for the first time can't have a binding yet, so this is always
+            // the plain defaults — a profile only ever enters via a later, deliberate choice.
+            val handle = connectNative(
+                id, target.host, target.port, pinHex, REQUEST_ACCESS_TIMEOUT_MS,
+                profile = null, launch = target.launch,
+            )
            // 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()) {
@@ -414,11 +495,12 @@ fun ConnectScreen(
                // 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)
+                var record = knownHostStore.get(target.host, target.port)
                if (fp.isNotEmpty()) {
-                    knownHostStore.save(KnownHost(target.host, target.port, target.name, fp, paired = true))
+                    record = knownHostStore.trust(target.host, target.port, target.name, fp, paired = true)
                    savedHosts = knownHostStore.all()
                }
-                onConnected(handle)
+                onConnected(session(handle, record, profile = null))
            } else {
                // Cause-specific: an operator denial, an approval timeout, and a request that
                // never reached the host are different problems with different fixes.
@@ -441,6 +523,12 @@ fun ConnectScreen(
        targetPort: Int,
        dh: DiscoveredHost? = null,
        manualName: String? = null,
+        // A one-off "Connect with ▸" pick. `null` = follow the host's binding (a plain tap);
+        // `""` = force the global defaults, which is a real choice on a bound host and must
+        // therefore survive as a value rather than collapsing into "unset". NEVER rebinds.
+        oneOffProfile: String? = null,
+        // A library id the host should boot straight into (`launch=` on a link).
+        launch: String? = null,
    ) {
        // Every dial/pair path funnels through here — with local network access denied the connect
        // can only EPERM its way to a 10 s timeout, so ask instead of pretending to try.
@@ -456,18 +544,195 @@ fun ConnectScreen(
        when {
            // Known host whose advertised fp still matches the pin → silent pinned reconnect.
            known != null && (adv == null || adv == known.fpHex) ->
-                doConnect(targetHost, targetPort, known.name, known.fpHex)
+                doConnect(targetHost, targetPort, known.name, known.fpHex, oneOffProfile, launch)
            // Known host whose fp changed → force re-pairing (no silent re-trust shortcut).
-            known != null -> pendingTrust =
-                PendingTrust(targetHost, targetPort, known.name, adv, PendingTrust.Kind.FP_CHANGED)
+            known != null -> pendingTrust = PendingTrust(
+                targetHost, targetPort, known.name, adv, PendingTrust.Kind.FP_CHANGED,
+                oneOffProfile, launch,
+            )
            // Host explicitly advertised pair=optional → trust-on-first-use is permitted (offer it,
            // 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)
+            dh?.pairingRequired == false -> pendingTrust = PendingTrust(
+                targetHost, targetPort, name, dh.fingerprint, PendingTrust.Kind.TRUST_NEW,
+                oneOffProfile, launch,
+            )
            // 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.REQUEST_ACCESS)
+            else -> pendingTrust = PendingTrust(
+                targetHost, targetPort, name, adv, PendingTrust.Kind.REQUEST_ACCESS,
+                oneOffProfile, launch,
+            )
+        }
+    }
+
+    // A speed test in flight: which host+profile it is measuring, and how far it has got. The
+    // measurement is over a real connect, so it takes the same `connecting` gate every dial does.
+    var speedTest by remember { mutableStateOf<HostCardEntry?>(null) }
+    var speedTestPhase by remember { mutableStateOf<SpeedTestPhase>(SpeedTestPhase.Connecting) }
+
+    fun startSpeedTest(entry: HostCardEntry) {
+        val id = identity ?: run {
+            status = "Identity not ready yet — try again in a moment"
+            return
+        }
+        // The magic packet isn't the only thing LNP blocks: without the grant this would EPERM its
+        // way to a timeout and report a dead link on a perfectly good one.
+        if (!lnpGranted) {
+            lnpPrompt = true
+            return
+        }
+        speedTest = entry
+        speedTestPhase = SpeedTestPhase.Connecting
+        notice = null
+        connecting = true
+        discovery.stop() // a browse running through the burst would measure itself
+        scope.launch {
+            runSpeedTest(context, id, entry.host.address, entry.host.port, entry.host.fpHex) { p ->
+                // A dismissed dialog abandons the run; don't drag it back onto the screen.
+                if (speedTest != null) speedTestPhase = p
+            }
+            connecting = false
+            discovery.start()
+        }
+    }
+
+    // Toggle a host+profile pin. Presentation only: it never touches the profile itself and never
+    // changes the host's default binding.
+    fun togglePin(kh: KnownHost, profile: StreamProfile) {
+        val pins = if (profile.id in kh.pinnedProfileIds) {
+            kh.pinnedProfileIds - profile.id
+        } else {
+            kh.pinnedProfileIds + profile.id
+        }
+        knownHostStore.save(kh.copy(pinnedProfileIds = pins))
+        savedHosts = knownHostStore.all()
+    }
+
+    // The profile rows a card's overflow menu grows. With no profiles at all it stays empty — a
+    // user who never wants this feature sees no new clutter anywhere but the settings scope chips.
+    // "Connect with" is a ONE-OFF on every card: it never rebinds the host, which is why rebinding
+    // lives in the Edit sheet instead.
+    fun hostMenu(kh: KnownHost, pin: StreamProfile?): List<HostMenuItem> = buildList {
+        if (pin == null) {
+            add(HostMenuItem("Network speed test") { startSpeedTest(HostCardEntry(kh, null)) })
+        }
+        if (profiles.isEmpty()) return@buildList
+        if (pin != null) {
+            add(HostMenuItem("Unpin card", startsSection = true) { togglePin(kh, pin) })
+        }
+        add(
+            HostMenuItem("Connect with: Default settings", startsSection = true) {
+                // The empty reference is "force the defaults", not "unset" — on a bound host that
+                // is a real, different action from a plain tap.
+                connect(kh.address, kh.port, oneOffProfile = "")
+            },
+        )
+        profiles.forEach { p ->
+            add(HostMenuItem("Connect with: ${p.name}") { connect(kh.address, kh.port, oneOffProfile = p.id) })
+        }
+        if (pin == null) {
+            profiles.forEachIndexed { i, p ->
+                val pinned = p.id in kh.pinnedProfileIds
+                add(
+                    HostMenuItem(
+                        if (pinned) "Unpin card: ${p.name}" else "Pin as card: ${p.name}",
+                        startsSection = i == 0,
+                    ) { togglePin(kh, p) },
+                )
+            }
+        }
+    }
+
+    // The saved-hosts grid: each host's own card, then one card per profile it has pinned, so a
+    // pinned combination is a plain one-click connect instead of a trip through a menu.
+    val savedCards = savedHosts.flatMap { kh ->
+        listOf(HostCardEntry(kh, null)) + profileStore.pinsFor(kh).map { HostCardEntry(kh, it) }
+    }
+    // Cards in one grid row must be the same height (the grid won't stretch them), so as soon as
+    // ANY saved card carries a profile chip, they all reserve its space. Nobody who doesn't use
+    // profiles ever sees the gap.
+    val anyProfileChip = savedCards.any { it.pin != null || it.host.profileId != null }
+
+    // ---- punktfunk:// routing (design/client-deep-links.md §3) --------------------------------
+    //
+    // The invariant: a URL may only ever do what a click on an existing card could do, MINUS trust
+    // decisions. So it never pairs, never trusts on its own, and carries references rather than
+    // values. Everything below is either "do exactly what the card does" or "refuse and say why" —
+    // a shortcut that can't honour its reference must say so, because streaming with the wrong
+    // settings is worse than an explanatory notice.
+    LaunchedEffect(deepLink, identity, savedHosts) {
+        val url = deepLink ?: return@LaunchedEffect
+        // Wait for the identity rather than refusing: it arrives a beat after first composition and
+        // the effect re-runs when it does.
+        if (identity == null) return@LaunchedEffect
+        onDeepLinkHandled()
+        val parsed = DeepLinks.parse(url)
+        if (parsed is DeepLinkResult.Refused) {
+            // A link for someone else's scheme is not our business to complain about.
+            if (parsed.error != LinkError.NOT_OUR_SCHEME) status = parsed.message()
+            return@LaunchedEffect
+        }
+        val link = (parsed as DeepLinkResult.Parsed).link
+        if (link.route != LinkRoute.CONNECT) {
+            // `wake` and `browse` are reserved in the grammar and parse today; a front-end that
+            // hasn't implemented them refuses with a notice rather than silently connecting.
+            status = "Punktfunk on Android can't do “${link.route.word}” links yet."
+            return@LaunchedEffect
+        }
+        // A profile reference that can't be honoured refuses: a "Work" shortcut streaming with the
+        // wrong settings is worse than an error naming what failed.
+        val profileRef = link.profile
+        if (profileRef != null) {
+            val (_, resolution) = profileStore.resolve(profileRef)
+            if (resolution != ProfileResolution.FOUND) {
+                status = if (resolution == ProfileResolution.AMBIGUOUS) {
+                    "More than one profile is called “$profileRef” — rename one and try again."
+                } else {
+                    "That link asks for a profile called “$profileRef”, which isn't on this device."
+                }
+                return@LaunchedEffect
+            }
+        }
+        when (val resolved = DeepLinks.resolveHost(link, savedHosts)) {
+            // Known AND pinned is the one-click contract: do exactly what tapping its card does.
+            is HostResolution.Known -> {
+                // A pin that contradicts the stored one is the link being stale or lying. Hard
+                // refusal: this is the one case where doing what the card does would be wrong.
+                if (link.pinConflict(resolved.host)) {
+                    status = "That link's fingerprint doesn't match the one pinned for " +
+                        "${resolved.host.name} — it's out of date, or it isn't that host."
+                    return@LaunchedEffect
+                }
+                if (resolved.host.fpHex.isEmpty()) {
+                    // Saved but never pinned (nothing writes such a record today, but the rule is
+                    // absolute): a link may not establish trust, so this is a confirmation.
+                    pendingTrust = PendingTrust(
+                        resolved.host.address, resolved.host.port, resolved.host.name,
+                        link.fp, PendingTrust.Kind.REQUEST_ACCESS, profileRef, link.launch,
+                    )
+                    return@LaunchedEffect
+                }
+                connect(
+                    resolved.host.address, resolved.host.port,
+                    oneOffProfile = profileRef, launch = link.launch,
+                )
+            }
+            // Unknown, or known only by address: the confirmation sheet, from which the normal
+            // pairing flow proceeds under the user's eyes. Never a silent trust.
+            is HostResolution.Unknown -> pendingTrust = PendingTrust(
+                resolved.address,
+                resolved.port,
+                link.name ?: resolved.address,
+                resolved.fp,
+                PendingTrust.Kind.REQUEST_ACCESS,
+                profileRef,
+                link.launch,
+            )
+            HostResolution.Ambiguous ->
+                status = "More than one saved host is called “${link.hostRef}” — " +
+                    "rename one, or use its address."
+            HostResolution.Unresolvable ->
+                status = "That link points at a host this device doesn't know."
        }
    }

@@ -478,11 +743,15 @@ fun ConnectScreen(
        // every action above; the trailing Add Host tile opens the same manual-entry sheet.
        val tiles = buildList {
            savedHosts.forEach { kh ->
+                val bound = kh.profileId?.let { id -> profiles.firstOrNull { it.id == id } }
                add(
                    HomeTile(
-                        id = "saved-${kh.address}:${kh.port}",
+                        id = "saved-${kh.id}",
                        title = kh.name,
-                        subtitle = "${kh.address}:${kh.port}",
+                        // The binding is what a press will actually do, so the tile says so — the
+                        // console can't edit profiles, but it must never lie about which one it uses.
+                        subtitle = bound?.let { "${kh.address}:${kh.port} · ${it.name}" }
+                            ?: "${kh.address}:${kh.port}",
                        filled = true,
                        online = kh.isOnline(discovered, reachable),
                        paired = kh.paired,
@@ -490,6 +759,23 @@ fun ConnectScreen(
                        activate = { connect(kh.address, kh.port) },
                    ),
                )
+                // Pinned host+profile combinations, right after their host: one focus-and-press
+                // each, which is the affordance a controller surface does well (menus are not).
+                profileStore.pinsFor(kh).forEach { p ->
+                    add(
+                        HomeTile(
+                            id = "pin-${kh.id}-${p.id}",
+                            title = kh.name,
+                            subtitle = p.name,
+                            filled = true,
+                            online = kh.isOnline(discovered, reachable),
+                            paired = kh.paired,
+                            knownHost = kh,
+                            pinnedProfileId = p.id,
+                            activate = { connect(kh.address, kh.port, oneOffProfile = p.id) },
+                        ),
+                    )
+                }
            }
            discoveredUnsaved.forEach { dh ->
                add(
@@ -526,7 +812,11 @@ fun ConnectScreen(
            onActivate = { it.activate() },
            onOpenLibrary = { it.knownHost?.let(onOpenLibrary) },
            onOpenSettings = onOpenSettings,
-            onOptions = { it.knownHost?.let { kh -> optionsTarget = kh } },
+            onOptions = { tile ->
+                tile.knownHost?.let { kh ->
+                    optionsTarget = HostCardEntry(kh, tile.pinnedProfileId?.let(profileStore::byId))
+                }
+            },
        )
    } else {
        Box(Modifier.fillMaxSize()) {
@@ -548,6 +838,23 @@ fun ConnectScreen(
                    )
                    Spacer(Modifier.height(24.dp))

+                    notice?.let {
+                        Surface(
+                            color = MaterialTheme.colorScheme.secondaryContainer,
+                            shape = MaterialTheme.shapes.medium,
+                            modifier = Modifier.fillMaxWidth(),
+                        ) {
+                            Text(
+                                it,
+                                style = MaterialTheme.typography.bodyMedium,
+                                color = MaterialTheme.colorScheme.onSecondaryContainer,
+                                textAlign = TextAlign.Center,
+                                modifier = Modifier.padding(horizontal = 16.dp, vertical = 12.dp),
+                            )
+                        }
+                        Spacer(Modifier.height(16.dp))
+                    }
+
                    status?.let {
                        // In-flight progress (connecting / waking) is the full-screen ConnectOverlay's
                        // job now, so `status` only ever carries a result/error here — a filled error
@@ -612,24 +919,45 @@ fun ConnectScreen(
                item(span = { GridItemSpan(maxLineSpan) }) {
                    SectionLabel("Saved hosts")
                }
-                items(savedHosts, key = { "saved-${it.address}-${it.port}" }) { kh ->
+                items(savedCards, key = { it.key }) { entry ->
+                    val kh = entry.host
+                    val pin = entry.pin
+                    val bound = kh.profileId?.let { id -> profiles.firstOrNull { it.id == id } }
                    HostCard(
                        name = kh.name,
                        address = "${kh.address}:${kh.port}",
                        status = if (kh.paired) HostStatus.PAIRED else HostStatus.TOFU,
                        online = kh.isOnline(discovered, reachable),
+                        // Live advert preferred (the store lags a discovery tick), else stored.
+                        os = discovered.firstOrNull { kh.matches(it) && it.os.isNotEmpty() }?.os
+                            ?: kh.os,
                        enabled = !connecting,
-                        onConnect = { connect(kh.address, kh.port) },
-                        onForget = {
-                            knownHostStore.remove(kh.address, kh.port)
-                            savedHosts = knownHostStore.all()
+                        // A pinned card connects with ITS profile; the host's own card follows the
+                        // binding, which is exactly what its chip says it will do.
+                        onConnect = {
+                            if (pin != null) {
+                                connect(kh.address, kh.port, oneOffProfile = pin.id)
+                            } else {
+                                connect(kh.address, kh.port)
+                            }
                        },
-                        onEdit = { editTarget = kh },
+                        // Edit / Forget / Wake live on the host's own card only: a pinned card is a
+                        // shortcut, not a second host, and offering destructive host actions on it
+                        // would blur exactly that.
+                        onForget = if (pin != null) {
+                            null
+                        } else {
+                            {
+                                knownHostStore.remove(kh)
+                                savedHosts = knownHostStore.all()
+                            }
+                        },
+                        onEdit = if (pin != null) null else ({ editTarget = kh }),
                        // Explicit wake-only: offered when the host is offline and we have a MAC. Runs
                        // through the WakeController so it shows the "Waking…" overlay and waits for
                        // the host to come online (matched by fingerprint, so a new DHCP address on a
                        // cold boot still counts as "up") rather than firing a single silent packet.
-                        onWake = if (kh.mac.isNotEmpty() && !kh.isOnline(discovered, reachable)) {
+                        onWake = if (pin == null && kh.mac.isNotEmpty() && !kh.isOnline(discovered, reachable)) {
                            {
                                // The magic packet is UDP broadcast — LNP-blocked like everything else.
                                if (!lnpGranted) {
@@ -648,6 +976,11 @@ fun ConnectScreen(
                        } else {
                            null
                        },
+                        profileLabel = pin?.name ?: bound?.name,
+                        profileProminent = pin != null,
+                        accent = accentColor(pin?.accent ?: bound?.accent),
+                        menuItems = hostMenu(kh, pin),
+                        reserveProfileSlot = anyProfileChip,
                    )
                }
            }
@@ -663,6 +996,7 @@ fun ConnectScreen(
                        address = "${dh.host}:${dh.port}",
                        status = if (dh.pairingRequired) HostStatus.PAIRING else HostStatus.TOFU,
                        online = true, // in the discovered list ⇒ live on mDNS right now
+                        os = dh.os,
                        enabled = !connecting,
                        onConnect = { connect(dh.host, dh.port, dh) },
                        onForget = null,
@@ -741,15 +1075,15 @@ fun ConnectScreen(
        // Same trust/pairing logic, console-styled + controller-navigable in gamepad mode.
        val onPair = { pendingTrust = pt.copy(kind = PendingTrust.Kind.PAIR) }
        val onSavePaired = { fp: String ->
-            knownHostStore.save(KnownHost(pt.host, pt.port, pt.name, fp, paired = true))
+            knownHostStore.trust(pt.host, pt.port, pt.name, fp, paired = true)
            savedHosts = knownHostStore.all()
            pendingTrust = null
-            doConnect(pt.host, pt.port, pt.name, fp)
+            doConnect(pt.host, pt.port, pt.name, fp, pt.profile, pt.launch)
        }
        when (pt.kind) {
            PendingTrust.Kind.TRUST_NEW ->
-                if (gamepadUi) GamepadTrustNewDialog(pt, { pendingTrust = null; doConnect(pt.host, pt.port, pt.name, null) }, onPair, { pendingTrust = null })
-                else TrustNewHostDialog(pt, { pendingTrust = null; doConnect(pt.host, pt.port, pt.name, null) }, onPair, { pendingTrust = null })
+                if (gamepadUi) GamepadTrustNewDialog(pt, { pendingTrust = null; doConnect(pt.host, pt.port, pt.name, null, pt.profile, pt.launch) }, onPair, { pendingTrust = null })
+                else TrustNewHostDialog(pt, { pendingTrust = null; doConnect(pt.host, pt.port, pt.name, null, pt.profile, pt.launch) }, onPair, { pendingTrust = null })
            PendingTrust.Kind.FP_CHANGED ->
                if (gamepadUi) GamepadFingerprintChangedDialog(pt, onPair, { pendingTrust = null })
                else FingerprintChangedDialog(pt, onPair, { pendingTrust = null })
@@ -774,7 +1108,9 @@ fun ConnectScreen(
    }

    // Console host options (Up on a saved carousel tile): Wake / Edit / Forget.
-    optionsTarget?.let { kh ->
+    optionsTarget?.let { entry ->
+        val kh = entry.host
+        val pin = entry.pin
        val offline = !kh.isOnline(discovered, reachable)
        GamepadHostOptionsDialog(
            hostName = kh.name,
@@ -794,27 +1130,56 @@ fun ConnectScreen(
            },
            // A saved host always has a library (it's a knownHost) → offer it when the setting's on,
            // so a TV remote reaches the library here instead of via the Y face button.
-            onLibrary = if (settings.libraryEnabled) {
+            onLibrary = if (settings.libraryEnabled && pin == null) {
                { optionsTarget = null; onOpenLibrary(kh) }
            } else {
                null
            },
+            onSpeedTest = if (pin == null) {
+                { optionsTarget = null; startSpeedTest(HostCardEntry(kh, null)) }
+            } else {
+                null
+            },
            onEdit = { optionsTarget = null; editTarget = kh },
            onForget = {
-                knownHostStore.remove(kh.address, kh.port)
+                knownHostStore.remove(kh)
                savedHosts = knownHostStore.all()
                optionsTarget = null
            },
            onDismiss = { optionsTarget = null },
+            // A pin's only action: unpinning touches neither the host nor the profile.
+            onUnpin = pin?.let { p -> { togglePin(kh, p); optionsTarget = null } },
+            profileName = pin?.name,
        )
    }

+    speedTest?.let { entry ->
+        val target = SpeedTestTarget.resolve(entry.host, entry.pin?.id, profileStore)
+        val dismiss = { speedTest = null }
+        val apply: (Boolean) -> Unit = { toProfile ->
+            val done = speedTestPhase as? SpeedTestPhase.Done
+            if (done != null) {
+                val where = applySpeedTestResult(
+                    done.recommendedKbps, target, toProfile, profileStore, settings, onSettingsChange,
+                )
+                profiles = profileStore.all()
+                notice = "%.0f Mbit/s set in %s".format(done.recommendedMbps, where)
+            }
+            speedTest = null
+        }
+        if (gamepadUi) {
+            GamepadSpeedTestDialog(entry.host.name, target, speedTestPhase, apply, dismiss)
+        } else {
+            SpeedTestDialog(entry.host.name, target, speedTestPhase, apply, dismiss)
+        }
+    }
+
    editTarget?.let { kh ->
        // Prefill a not-yet-learned MAC from the host's live advert, mirroring Apple's
        // `discovery.hosts.first { host.matches($0) }?.macAddresses`.
        val suggested = discovered.firstOrNull { kh.matches(it) }?.mac ?: emptyList()
        val onSaveHost: (KnownHost) -> Unit = { updated ->
-            knownHostStore.update(kh.address, kh.port, updated)
+            knownHostStore.save(updated)
            savedHosts = knownHostStore.all()
            editTarget = null
        }
@@ -832,6 +1197,7 @@ fun ConnectScreen(
            EditHostDialog(
                target = kh,
                suggestedMacs = suggested,
+                profiles = profiles,
                onSave = onSaveHost,
                onDismiss = { editTarget = null },
            )
@@ -872,6 +1238,15 @@ fun ConnectScreen(
    )
 }

+/**
+ * One entry in the saved-hosts grid: a host's own card ([pin] null), or one of its pinned
+ * host+profile cards. Pins are additive presentation state on the host record — never duplicated
+ * host entries, which would fork pairing, trust and renames (design §5.2a).
+ */
+private data class HostCardEntry(val host: KnownHost, val pin: StreamProfile?) {
+    val key: String get() = "card-${host.id}-${pin?.id ?: "primary"}"
+}
+
 /**
 * Whether NEARBY_WIFI_DEVICES is held (API 33+; not applicable below). We request it opportunistically
 * as a multicast-reception hedge on OEMs that filter multicast without it, but discovery (raw mDNS via
@@ -44,6 +44,7 @@ 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.DsDevice
 import io.unom.punktfunk.kit.Gamepad
 import io.unom.punktfunk.kit.Sc2Capture
 import kotlinx.coroutines.delay
@@ -149,13 +150,14 @@ fun ControllersScreen(gamepadSetting: Int, onBack: () -> Unit) {
    ) {
        Text("Controllers", style = MaterialTheme.typography.headlineMedium)

-        // Steam Controller 2 detection: never an InputDevice (lizard mode is kb/mouse; the
-        // capture claims even those away), so it's enumerated on the capture side — USB device
-        // list + bonded BLE — and re-checked on USB hot-plug.
-        var sc2Generation by remember { mutableIntStateOf(0) }
+        // Capture-side detection, re-checked on USB hot-plug. The SC2 is never an InputDevice
+        // (lizard mode is kb/mouse; the capture claims even those away) so it's enumerated from
+        // the USB device list + bonded BLE; a Sony pad IS an InputDevice until claimed, so its
+        // row supplements the PadRow below with the capture status + the USB grant.
+        var usbGeneration by remember { mutableIntStateOf(0) }
        DisposableEffect(Unit) {
            val receiver = object : android.content.BroadcastReceiver() {
-                override fun onReceive(c: Context?, i: android.content.Intent?) { sc2Generation++ }
+                override fun onReceive(c: Context?, i: android.content.Intent?) { usbGeneration++ }
            }
            val filter = android.content.IntentFilter().apply {
                addAction(android.hardware.usb.UsbManager.ACTION_USB_DEVICE_ATTACHED)
@@ -170,16 +172,23 @@ fun ControllersScreen(gamepadSetting: Int, onBack: () -> Unit) {
            onDispose { runCatching { context.unregisterReceiver(receiver) } }
        }
        val sc2Probe = remember { Sc2Capture(context) }
-        val sc2Usb = remember(sc2Generation) { sc2Probe.findUsbDevice() }
-        val sc2Ble = remember(sc2Generation) {
+        val sc2Usb = remember(usbGeneration) { sc2Probe.findUsbDevice() }
+        val sc2Ble = remember(usbGeneration) {
            if (context.checkSelfPermission(android.Manifest.permission.BLUETOOTH_CONNECT) ==
                android.content.pm.PackageManager.PERMISSION_GRANTED
            ) sc2Probe.pairedBleAddress() else null
        }
        val sc2Present = sc2Usb != null || sc2Ble != null
+        val dsUsb = remember(usbGeneration) {
+            (context.getSystemService(Context.USB_SERVICE) as android.hardware.usb.UsbManager)
+                .deviceList.values.firstOrNull {
+                    it.vendorId == DsDevice.VID_SONY && it.productId in DsDevice.USB_PIDS
+                }
+        }

        Group("Gamepads") {
            if (sc2Present) Sc2Row(sc2Usb, activity)
+            dsUsb?.let { DsRow(it) }
            if (pads.isEmpty() && !sc2Present) {
                Text(
                    "No controller detected. punktfunk can only forward devices Android " +
@@ -319,6 +328,104 @@ private fun Sc2Row(usbDev: android.hardware.usb.UsbDevice?, activity: MainActivi
    }
 }

+/**
+ * Broadcast action for the Sony-pad USB grants — fired by both the menu-time auto-ask
+ * ([MainActivity.maybeAskDsPermission]) and [DsRow]'s explicit button, so an open card
+ * refreshes whichever dialog was answered.
+ */
+internal const val DS_USB_PERMISSION_ACTION = "io.unom.punktfunk.DS_CONTROLLERS_USB_PERMISSION"
+
+/**
+ * The Sony USB pad card — capture status + the USB grant. The grant normally arrives via the
+ * menu-time auto-ask the moment the pad attaches ([MainActivity.maybeAskDsPermission]); the
+ * button here is the recovery path after a deny (the auto-ask fires once per attach). Shown
+ * ALONGSIDE the pad's ordinary [PadRow] (unclaimed it is still an InputDevice); the capture
+ * itself only runs inside a stream, so at menu time this card is pure status.
+ */
+@Composable
+private fun DsRow(usbDev: android.hardware.usb.UsbDevice) {
+    val context = LocalContext.current
+    val settingOn = remember { SettingsStore(context).load().dsCapture }
+    val usbManager = context.getSystemService(Context.USB_SERVICE) as android.hardware.usb.UsbManager
+    var permitted by remember(usbDev) { mutableStateOf(usbManager.hasPermission(usbDev)) }
+    val model = DsDevice.modelFor(usbDev.productId)
+    val label = when (model) {
+        DsDevice.Model.DUALSENSE -> "DualSense"
+        DsDevice.Model.DUALSENSE_EDGE -> "DualSense Edge"
+        DsDevice.Model.DUALSHOCK4 -> "DualShock 4"
+        null -> return
+    }
+    // Refresh `permitted` when the grant dialog answers (the grant itself is system-recorded;
+    // this receiver only updates the card).
+    val action = DS_USB_PERMISSION_ACTION
+    DisposableEffect(usbDev) {
+        val receiver = object : android.content.BroadcastReceiver() {
+            override fun onReceive(c: Context?, i: android.content.Intent?) {
+                if (i?.action == action) permitted = usbManager.hasPermission(usbDev)
+            }
+        }
+        androidx.core.content.ContextCompat.registerReceiver(
+            context,
+            receiver,
+            android.content.IntentFilter(action),
+            androidx.core.content.ContextCompat.RECEIVER_NOT_EXPORTED,
+        )
+        onDispose { runCatching { context.unregisterReceiver(receiver) } }
+    }
+    OutlinedCard(modifier = Modifier.fillMaxWidth()) {
+        Column(
+            modifier = Modifier.padding(16.dp),
+            verticalArrangement = Arrangement.spacedBy(6.dp),
+        ) {
+            Text("$label passthrough", style = MaterialTheme.typography.bodyLarge)
+            Text(
+                "Wired (USB)",
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+            when {
+                !settingOn -> Text(
+                    "Passthrough is disabled in Settings — enable \"DualSense / DualShock " +
+                        "passthrough (USB)\" to capture it.",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+                !permitted -> {
+                    Text(
+                        "Needs USB access — grant it now and streams capture the pad silently.",
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                    OutlinedButton(onClick = {
+                        usbManager.requestPermission(
+                            usbDev,
+                            android.app.PendingIntent.getBroadcast(
+                                context, 3, // requestCode 3 — 0/1/2 are the SC2/stream grants
+                                android.content.Intent(action).setPackage(context.packageName),
+                                // MUTABLE: the USB stack appends the grant extras to this intent.
+                                android.app.PendingIntent.FLAG_MUTABLE,
+                            ),
+                        )
+                    }) {
+                        Text("Grant USB access")
+                    }
+                }
+                else -> Text(
+                    if (model == DsDevice.Model.DUALSHOCK4) {
+                        "Ready — captured at stream start: rumble, lightbar and gyro are " +
+                            "driven directly."
+                    } else {
+                        "Ready — captured at stream start: rumble, adaptive triggers, lightbar " +
+                            "and gyro are driven directly."
+                    },
+                    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) {
@@ -213,19 +213,92 @@ fun GamepadHostOptionsDialog(
    onEdit: () -> Unit,
    onForget: () -> Unit,
    onDismiss: () -> Unit,
+    onSpeedTest: (() -> Unit)? = null,
+    /**
+     * Non-null when this is a PINNED host+profile tile, whose only action is to unpin. A pin is a
+     * shortcut, not a second host — offering the host's destructive actions on it would blur
+     * exactly that, and the touch grid withholds them for the same reason.
+     */
+    onUnpin: (() -> Unit)? = null,
+    profileName: String? = null,
 ) {
    GamepadDialog(
-        title = hostName,
+        title = if (profileName != null) "$hostName · $profileName" else hostName,
        onDismiss = onDismiss,
        actions = buildList {
+            if (onUnpin != null) {
+                add(DialogAction("Unpin card", primary = true, onClick = onUnpin))
+                add(DialogAction("Cancel", onClick = onDismiss))
+                return@buildList
+            }
            if (onLibrary != null) add(DialogAction("Library", primary = true, onClick = onLibrary))
            if (canWake) add(DialogAction("Wake host", onClick = onWake))
+            if (onSpeedTest != null) add(DialogAction("Network speed test", onClick = onSpeedTest))
            add(DialogAction("Edit…", primary = onLibrary == null, onClick = onEdit))
            add(DialogAction("Forget", onClick = onForget))
            add(DialogAction("Cancel", onClick = onDismiss))
        },
    ) {
-        DialogText("Manage this saved host.")
+        DialogText(
+            if (onUnpin != null) {
+                "This card is a shortcut to this host with one profile. Unpinning it changes " +
+                    "nothing about the host or the profile."
+            } else {
+                "Manage this saved host."
+            },
+        )
+    }
+}
+
+/**
+ * Console counterpart of [SpeedTestDialog]. Same measurement, same targeting rule — a TV box on a
+ * powerline adapter is exactly the machine whose link is worth measuring, so this belongs on the
+ * couch surface too, even though profile EDITING doesn't.
+ */
+@Composable
+fun GamepadSpeedTestDialog(
+    hostName: String,
+    target: SpeedTestTarget,
+    phase: SpeedTestPhase,
+    onApply: (toProfile: Boolean) -> Unit,
+    onDismiss: () -> Unit,
+) {
+    val done = phase as? SpeedTestPhase.Done
+    GamepadDialog(
+        title = "Network speed test",
+        onDismiss = onDismiss,
+        actions = buildList {
+            if (done != null) {
+                add(
+                    DialogAction(
+                        when (target) {
+                            SpeedTestTarget.Global -> "Apply"
+                            is SpeedTestTarget.Profile -> "Apply to “${target.profile.name}”"
+                            is SpeedTestTarget.Ask -> "Set in “${target.profile.name}”"
+                        },
+                        primary = true,
+                    ) { onApply(true) },
+                )
+                if (target is SpeedTestTarget.Ask) {
+                    add(DialogAction("Set as default") { onApply(false) })
+                }
+            }
+            add(DialogAction("Close", primary = done == null, onClick = onDismiss))
+        },
+    ) {
+        DialogText(hostName)
+        when (phase) {
+            SpeedTestPhase.Connecting -> DialogText("Connecting…")
+            SpeedTestPhase.Measuring ->
+                DialogText("Measuring — the host is bursting test traffic for two seconds.")
+            is SpeedTestPhase.Failed -> DialogText(phase.message)
+            is SpeedTestPhase.Done -> {
+                DialogText(
+                    "%.0f Mbit/s measured · %.1f %% loss".format(phase.measuredMbps, phase.lossPct),
+                )
+                DialogText("Recommended bitrate: %.0f Mbit/s".format(phase.recommendedMbps))
+            }
+        }
    }
 }

@@ -73,11 +73,17 @@ class HomeTile(
    val connecting: Boolean = false,
    val isAdd: Boolean = false,      // the trailing Add Host tile (plus icon, not a monogram)
    val knownHost: KnownHost? = null, // set for saved hosts → enables the library (Y)
+    /**
+     * Set when this tile is a PINNED host+profile combination rather than the host's own tile.
+     * A pin is a shortcut, not a second host: the host-level actions (wake, edit, forget, library)
+     * belong to the host's own tile, and this one offers only Unpin.
+     */
+    val pinnedProfileId: String? = null,
    val activate: () -> Unit,
 ) {
    // Any SAVED host offers the library (matches Apple) — the fetch itself returns a clear "pair
    // first" message if the host hasn't authorized this device for its management API.
-    val hasLibrary: Boolean get() = knownHost != null
+    val hasLibrary: Boolean get() = knownHost != null && pinnedProfileId == null
 }

 /**
@@ -87,7 +87,9 @@ fun GamepadSettingsScreen(
    val context = LocalContext.current
    // Gates the "Rumble on this phone" row — a TV box has no body vibrator to mirror onto.
    val hasBodyVibrator = remember { deviceBodyVibrator(context) != null }
-    val rows = buildSettingsRows(s, hasBodyVibrator, ::update)
+    // Gates the AV1 codec row the same way the touch settings do (see `codecOptionsFor`).
+    val av1Capable = remember { io.unom.punktfunk.kit.VideoDecoders.pickDecoder("video/av01") != null }
+    val rows = buildSettingsRows(s, hasBodyVibrator, av1Capable, ::update)
    var focus by remember { mutableIntStateOf(0) }
    if (focus > rows.lastIndex) focus = rows.lastIndex
    // The direction the focused value last stepped (+1 forward / -1 back) — drives which way the
@@ -139,7 +141,10 @@ fun GamepadSettingsScreen(
                verticalArrangement = Arrangement.spacedBy(6.dp),
            ) {
            item(key = "__title") {
-                ConsoleHeader("Settings", horizontalInset = false)
+                // "Default settings", not "Settings": this screen edits the base layer only. The
+                // console honours a host's profile but doesn't edit profiles (design §5.4), so a
+                // bare "Settings" would quietly imply it changes whatever that host streams with.
+                ConsoleHeader("Default settings", horizontalInset = false)
            }
            itemsIndexed(rows, key = { _, r -> r.id }) { index, row ->
                SettingRowView(row, focused = index == focus, adjustDir = adjustDir, onClick = {
@@ -263,10 +268,12 @@ private fun SettingRowView(row: GpRow, focused: Boolean, adjustDir: Int, onClick
 }

 /** Build the console settings rows from the current [Settings], writing through [update].
- * [hasBodyVibrator] gates the "Rumble on this phone" row (absent on TVs). */
+ * [hasBodyVibrator] gates the "Rumble on this phone" row (absent on TVs); [av1Capable] gates the
+ * AV1 codec entry (see `codecOptionsFor`). */
 private fun buildSettingsRows(
    s: Settings,
    hasBodyVibrator: Boolean,
+    av1Capable: Boolean,
    update: (Settings) -> Unit,
 ): List<GpRow> {
    fun <T> choice(
@@ -304,9 +311,36 @@ private fun buildSettingsRows(
        toggled = value,
    )

+    // Grouped and ordered by the cross-client category map (General / Display / Audio /
+    // Controllers), with the same sub-section names the touch settings and the desktop clients use,
+    // so a setting sits in the same place whichever surface you found it on. The ROWS stay the
+    // couch-relevant subset: a pad can't drive a touch-input picker, and adding one for the sake of
+    // symmetry would be parity in name only.
    return listOf(
        choice(
-            "resolution", "Stream", "Resolution",
+            "hud", "General · Statistics", "Statistics overlay",
+            "How much the overlay shows: Compact (one line) → Normal → Detailed (full HUD). " +
+                "A 3-finger tap cycles the tiers live.",
+            STATS_VERBOSITY_OPTIONS, s.statsVerbosity,
+        ) { update(s.copy(statsVerbosity = it)) },
+        toggle(
+            "autoWake", "General · Session", "Auto-wake on connect",
+            "Wake a saved host with Wake-on-LAN when it isn't seen on the network, then connect.",
+            s.autoWakeEnabled,
+        ) { update(s.copy(autoWakeEnabled = it)) },
+        toggle(
+            "library", "General · Library", "Game library",
+            "Browse a paired host's games with Y (experimental).",
+            s.libraryEnabled,
+        ) { update(s.copy(libraryEnabled = it)) },
+        toggle(
+            "gamepadUI", "General · Interface", "Controller-optimized UI",
+            "Turn off to use the touch interface even with a controller connected.",
+            s.gamepadUiEnabled,
+        ) { update(s.copy(gamepadUiEnabled = it)) },
+
+        choice(
+            "resolution", "Display · Resolution", "Resolution",
            "The host creates a virtual display at exactly this size — no scaling. " +
                "Custom sizes are typed in the touch settings.",
            // A custom size (typed in the touch settings) leads the list so it stays visible and
@@ -323,33 +357,36 @@ private fun buildSettingsRows(
            "refresh", null, "Refresh rate", "Frame rate the host renders and streams at.",
            REFRESH_OPTIONS, s.hz,
        ) { update(s.copy(hz = it)) },
+
        choice(
-            "bitrate", null, "Bitrate",
-            "Automatic uses the host's default. Run a speed test from the touch UI for an informed value.",
+            "bitrate", "Display · Quality", "Bitrate",
+            "Automatic uses the host's default. A host's options (Up on its tile) can measure the " +
+                "link and set an informed value.",
            BITRATE_OPTIONS, s.bitrateKbps,
        ) { update(s.copy(bitrateKbps = it)) },
        choice(
-            "compositor", null, "Compositor",
-            "Which compositor drives the virtual output — honored only if available on the host.",
-            COMPOSITOR_OPTIONS.mapIndexed { i, lbl -> i to lbl }, s.compositor,
-        ) { update(s.copy(compositor = it)) },
-
-        choice(
-            "codec", "Video", "Video codec",
+            "codec", null, "Video codec",
            "A preference — the host falls back if it can't encode this one.",
-            CODEC_OPTIONS, s.codec,
+            codecOptionsFor(s.codec, av1Capable), s.codec,
        ) { update(s.copy(codec = it)) },
        toggle(
            "hdr", null, "10-bit HDR",
            "HDR10 — engages when the host sends HDR content and this display supports it.",
            s.hdrEnabled,
        ) { update(s.copy(hdrEnabled = it)) },
+
        toggle(
-            "lowLatency", null, "Low-latency mode",
+            "lowLatency", "Display · Decoding", "Low-latency mode",
            "The fast pipeline (async decode + system tuning). On by default — turn off to fall back if the stream stutters or glitches.",
            s.lowLatencyMode,
        ) { update(s.copy(lowLatencyMode = it)) },

+        choice(
+            "compositor", "Display · Host output", "Compositor",
+            "Which compositor drives the virtual output — honored only if available on the host.",
+            COMPOSITOR_OPTIONS.mapIndexed { i, lbl -> i to lbl }, s.compositor,
+        ) { update(s.copy(compositor = it)) },
+
        choice(
            "audio", "Audio", "Audio channels", "The speaker layout requested from the host.",
            AUDIO_CHANNEL_OPTIONS, s.audioChannels,
@@ -360,9 +397,9 @@ private fun buildSettingsRows(
        ) { update(s.copy(micEnabled = it)) },

        choice(
-            "padType", "Controller", "Controller type",
+            "padType", "Controllers", "Controller type",
            "The virtual pad the host creates — Automatic matches this controller.",
-            GAMEPAD_OPTIONS.mapIndexed { i, lbl -> i to lbl }, s.gamepad,
+            GAMEPAD_OPTIONS, s.gamepad,
        ) { update(s.copy(gamepad = it)) },
    ) + listOfNotNull(
        if (hasBodyVibrator) {
@@ -376,26 +413,13 @@ private fun buildSettingsRows(
            null
        },
    ) + listOf(
-        choice(
-            "hud", "Interface", "Statistics overlay",
-            "How much the overlay shows: Compact (one line) → Normal → Detailed (full HUD). " +
-                "A 3-finger tap cycles the tiers live.",
-            STATS_VERBOSITY_OPTIONS, s.statsVerbosity,
-        ) { update(s.copy(statsVerbosity = it)) },
+        // NOT gated on the vibrator (the bug A2 fixed in the touch settings): an SC2 capture has
+        // nothing to do with this device's motor, and a TV box is where it matters most.
        toggle(
-            "library", null, "Game library",
-            "Browse a paired host's games with Y (experimental).",
-            s.libraryEnabled,
-        ) { update(s.copy(libraryEnabled = it)) },
-        toggle(
-            "autoWake", null, "Auto-wake on connect",
-            "Wake a saved host with Wake-on-LAN when it isn't seen on the network, then connect.",
-            s.autoWakeEnabled,
-        ) { update(s.copy(autoWakeEnabled = it)) },
-        toggle(
-            "gamepadUI", null, "Controller-optimized UI",
-            "Turn off to use the touch interface even with a controller connected.",
-            s.gamepadUiEnabled,
-        ) { update(s.copy(gamepadUiEnabled = it)) },
+            "sc2", null, "Steam Controller 2 passthrough",
+            "Capture a Steam Controller 2 (wired, Puck dongle, or paired Bluetooth) and stream " +
+                "it as-is — Steam on the host drives it like the physical pad.",
+            s.sc2Capture,
+        ) { update(s.copy(sc2Capture = it)) },
    )
 }
@@ -1,6 +1,7 @@
 package io.unom.punktfunk

 import android.content.Context
+import android.os.Build
 import io.unom.punktfunk.kit.Gamepad
 import io.unom.punktfunk.kit.NativeBridge
 import io.unom.punktfunk.kit.VideoDecoders
@@ -53,6 +54,9 @@ suspend fun connectToHost(
            // the user's soft codec preference — the host resolves the emitted codec from both.
            VideoDecoders.decodableCodecBits(), settings.preferredCodec(), timeoutMs,
            launch,
+            // The host's approval-list / trust-store label for this device — the same
+            // Build.MODEL convention the pairing dialogs use for nativePair.
+            Build.MODEL ?: "Android",
        )
    }
 }
@@ -63,6 +63,7 @@ import io.unom.punktfunk.kit.security.ClientIdentity
 import io.unom.punktfunk.kit.security.IdentityStore
 import io.unom.punktfunk.kit.security.KnownHost
 import io.unom.punktfunk.kit.security.obtainIdentity
+import io.unom.punktfunk.models.ActiveSession
 import kotlin.math.PI
 import kotlin.math.absoluteValue
 import kotlin.math.cos
@@ -85,7 +86,7 @@ private sealed class LibState {
 fun LibraryScreen(
    host: KnownHost,
    settings: Settings,
-    onLaunched: (Long) -> Unit,
+    onLaunched: (ActiveSession) -> Unit,
    onBack: () -> Unit,
    navActive: Boolean = true,
 ) {
@@ -142,7 +143,11 @@ fun LibraryScreen(
                                        host.address, host.port, host.fpHex, launch = game.id,
                                    )
                                    launching = false
-                                    if (handle != 0L) onLaunched(handle)
+                                    if (handle != 0L) {
+                                        onLaunched(
+                                            ActiveSession(handle, settings, host.clipboardSync),
+                                        )
+                                    }
                                    else Toast.makeText(
                                        context,
                                        "Launch failed — check the host and try again.",
@@ -13,24 +13,70 @@ import android.view.InputDevice
 import android.view.KeyCharacterMap
 import android.view.KeyEvent
 import android.view.MotionEvent
+import android.widget.Toast
 import androidx.activity.ComponentActivity
 import androidx.activity.SystemBarStyle
 import androidx.activity.compose.setContent
 import androidx.activity.enableEdgeToEdge
+import androidx.compose.foundation.layout.WindowInsets
 import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.systemBars
 import androidx.compose.material3.Surface
+import androidx.compose.runtime.Composable
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
+import io.unom.punktfunk.kit.DsDevice
 import io.unom.punktfunk.kit.Gamepad
 import io.unom.punktfunk.kit.GamepadRouter
 import io.unom.punktfunk.kit.Keymap
 import io.unom.punktfunk.kit.NativeBridge
+import io.unom.punktfunk.kit.link.DeepLinkResult
+import io.unom.punktfunk.kit.link.DeepLinks
+import io.unom.punktfunk.kit.link.HostResolution
+import io.unom.punktfunk.kit.security.KnownHostStore

 /** Broadcast action for the menu-time SC2 USB-permission grant (see [MainActivity.startSc2MenuNav]). */
 private const val SC2_MENU_PERMISSION = "io.unom.punktfunk.SC2_MENU_USB_PERMISSION"

+/**
+ * Keeps ONE window-insets reader alive for as long as the app's UI exists — the fix for the menus
+ * coming back from a stream laid out against the WRONG safe area.
+ *
+ * Compose attaches its `OnApplyWindowInsets` and `WindowInsetsAnimation` callbacks when the first
+ * composable reads an inset, and removes them again when the last reader goes away
+ * (`WindowInsetsHolder.increment/decrementAccessors`). [StreamScreen] reads no insets at all — it's
+ * a bare full-screen surface — so a stream drops the reader count to zero for its whole duration.
+ *
+ * That alone is survivable; what isn't is a session that ends while the app is BACKGROUNDED, which
+ * is the common case (leaving the app ends the session — see StreamScreen's ON_STOP observer). The
+ * whole window restore — `show(systemBars())`, releasing the landscape lock — then runs on a stopped
+ * activity, and the corrected insets that follow arrive while Compose has no listener attached. When
+ * the menus recompose, `incrementAccessors` re-attaches and asks for a fresh pass, but a stopped
+ * window produces no dispatch, and on resume nothing has *changed* any more, so none ever comes.
+ * Compose keeps serving what it last saw: the landscape, bars-hidden values.
+ *
+ * That's exactly what the reporter's phone showed (on-glass 2026-07-29, verified by dump): the
+ * platform reported `bars=[0,162,0,72] cutout=[0,162,0,0]` for the window while the layout was still
+ * using the landscape immersive set — cutout `left=162` (Material3 lays out against
+ * `systemBars.union(displayCutout)`), bars all zero. Content shoved right by the landscape cutout,
+ * nothing kept clear of the status bar or the gesture pill, and no rotation or IME animation could
+ * shake it loose. A/B'd over eight runs of the real teardown sequence: 3 of 4 wrong without this,
+ * 4 of 4 correct with it.
+ *
+ * Reading an inset here holds the count above zero for the activity's whole life, so the listeners
+ * survive the stream and every dispatch lands. It subscribes to no inset VALUE (only the holder
+ * object), so it triggers no recomposition — the cost is one DisposableEffect.
+ */
+@Composable
+private fun HoldWindowInsetsListeners() {
+    // The read itself IS the registration (the accessor is scoped to this composable, which never
+    // leaves the composition); `remember` is only what keeps it from being a value nobody uses.
+    remember(WindowInsets.systemBars) {}
+}
+
 class MainActivity : ComponentActivity() {
    /**
     * The active stream session handle (0 = not streaming). Set by [StreamScreen] while it's shown.
@@ -96,6 +142,17 @@ class MainActivity : ComponentActivity() {
    var lastPadStyle by mutableStateOf(Gamepad.PadStyle.GENERIC)
        private set

+    /**
+     * A `punktfunk://` URL waiting to be routed — set from the VIEW intent that started (or
+     * re-entered) this activity, cleared by whoever handles it. Compose observes it.
+     *
+     * Read in BOTH [onCreate] and [onNewIntent] on purpose: `launchMode` is `standard`, so a second
+     * link usually arrives as a fresh activity instance (onCreate) and only sometimes as a new
+     * intent on this one (a caller that set `FLAG_ACTIVITY_SINGLE_TOP`). A link arriving while an
+     * earlier one is still unhandled replaces it — the user's latest intent is the live one.
+     */
+    var pendingDeepLink by mutableStateOf<String?>(null)
+
    /** The panel's highest-refresh display mode (0 = unknown/unsupported), resolved once at startup. */
    private var highRefreshModeId = 0

@@ -113,6 +170,10 @@ class MainActivity : ComponentActivity() {
    private var sc2Receiver: BroadcastReceiver? = null
    private var sc2PermissionAsked = false

+    /** Sony-pad USB grant asked this attach — a deny doesn't re-nag until a fresh attach (or the
+     *  Controllers screen's explicit button). */
+    private var dsPermissionAsked = false
+
    /**
     * Compose focus hook for the SC2's synthetic D-pad (set by [onCreate]'s composition). A
     * synthetic KeyEvent dispatched from OUTSIDE the real input pipeline never reaches
@@ -125,6 +186,28 @@ class MainActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
+        // A URL may never preempt a live session (design/client-deep-links.md §3.2). With
+        // `launchMode = standard` a link normally arrives as a NEW activity instance in a new task
+        // — the streaming one gets backgrounded, and backgrounding ends a session — so the refusal
+        // has to happen HERE, before this instance is resumed, not inside the composition (which
+        // only ever sees the rare `onNewIntent` case). Finishing now leaves the streaming task in
+        // front, untouched.
+        val live = liveStream
+        if (live != null && deepLinkFrom(intent) != null) {
+            // Pointing at the host already being streamed is the one exception, and its right
+            // answer is to do nothing: the intent has already brought the app forward, which is
+            // what "focus it" means here.
+            if (!targetsHost(intent, live)) {
+                Toast.makeText(
+                    this,
+                    "Already streaming — end this session first.",
+                    Toast.LENGTH_LONG,
+                ).show()
+            }
+            finish()
+            return
+        }
+        pendingDeepLink = deepLinkFrom(intent)
        lastPadIsGamepad = !isTvDevice(this)
        lastPadStyle = Gamepad.styleFor(Gamepad.firstPad())
        resolveHighRefreshMode()
@@ -147,6 +230,8 @@ class MainActivity : ComponentActivity() {
                    UsbManager.ACTION_USB_DEVICE_ATTACHED -> {
                        sc2PermissionAsked = false // a fresh attach may ask once again
                        startSc2MenuNav()
+                        dsPermissionAsked = false
+                        maybeAskDsPermission()
                    }
                    SC2_MENU_PERMISSION -> {
                        if (intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)) {
@@ -169,6 +254,7 @@ class MainActivity : ComponentActivity() {
        }
        setContent {
            PunktfunkTheme {
+                HoldWindowInsetsListeners()
                // Focus hook for the SC2's synthetic navigation (see [sc2MoveFocus]). `Next` is
                // the bootstrap: directional moves need an already-focused node, while one-
                // dimensional traversal assigns initial focus when there is none.
@@ -185,9 +271,24 @@ class MainActivity : ComponentActivity() {
        }
    }

+    override fun onNewIntent(intent: Intent) {
+        super.onNewIntent(intent)
+        // Keep `getIntent()` truthful for anything that reads it later (the gamepad-UI dev flag).
+        setIntent(intent)
+        deepLinkFrom(intent)?.let { pendingDeepLink = it }
+    }
+
+    /**
+     * The `punktfunk://` URL of a VIEW intent, or null. Only VIEW: the launcher's MAIN intent
+     * carries no data, and nothing else may inject a URL into the router.
+     */
+    private fun deepLinkFrom(intent: Intent?): String? =
+        intent?.takeIf { it.action == Intent.ACTION_VIEW }?.data?.toString()
+
    override fun onResume() {
        super.onResume()
        startSc2MenuNav()
+        maybeAskDsPermission()
    }

    override fun onPause() {
@@ -248,6 +349,37 @@ class MainActivity : ComponentActivity() {
        sc2MenuActive = false
    }

+    /**
+     * Ask for USB access to an attached Sony pad the moment it appears — a fresh attach while
+     * the app is open, or the app coming to the foreground with one already plugged in — at most
+     * once per attach, so the stream-mode capture ([io.unom.punktfunk.kit.DsCapture]) engages
+     * silently instead of interrupting stream start with the dialog. Unlike the SC2's menu flow
+     * there is nothing to START on the grant: an uncaptured Sony pad is an ordinary InputDevice
+     * at menu time, so the grant is simply recorded (Android keeps it while the pad stays
+     * attached). The broadcast only refreshes the Controllers screen's card if it happens to be
+     * open; a deny leaves that card's explicit button as the re-ask.
+     */
+    private fun maybeAskDsPermission() {
+        if (streamHandle != 0L) return // StreamScreen owns its own permission flow while streaming
+        if (dsPermissionAsked) return
+        if (!SettingsStore(this).load().dsCapture) return
+        val usbManager = getSystemService(Context.USB_SERVICE) as UsbManager
+        val dev = usbManager.deviceList.values.firstOrNull {
+            it.vendorId == DsDevice.VID_SONY && it.productId in DsDevice.USB_PIDS
+        } ?: return
+        if (usbManager.hasPermission(dev)) return
+        dsPermissionAsked = true
+        usbManager.requestPermission(
+            dev,
+            PendingIntent.getBroadcast(
+                this, 4, // requestCode 4 — 0..3 are the SC2 stream/menu + DS stream/card grants
+                Intent(DS_USB_PERMISSION_ACTION).setPackage(packageName),
+                // MUTABLE: the USB stack appends the grant extras to this intent.
+                PendingIntent.FLAG_MUTABLE,
+            ),
+        )
+    }
+
    /**
     * One SC2 navigation key transition from the menu-time capture (main thread) — routed the
     * same way [dispatchKeyEvent]'s not-streaming branch routes a real pad's buttons: B backs,
@@ -312,8 +444,8 @@ class MainActivity : ComponentActivity() {
    /**
     * Opt the CONSOLE UI into the panel's highest refresh mode. Some OEMs (Nothing OS among them) pin
     * third-party apps to 60Hz unless they explicitly ask for more, which halves the smoothness of the
-     * UI's scrolling/animation on a 120/144Hz panel. [StreamScreen] turns this OFF while streaming so
-     * its own `ANativeWindow_setFrameRate` (matched to the video) governs the panel instead.
+     * UI's scrolling/animation on a 120/144Hz panel. [StreamScreen] replaces this with
+     * [setStreamDisplayMode] while streaming (matched to the video, not to the panel maximum).
     */
    fun setConsoleHighRefreshRate(high: Boolean) {
        if (highRefreshModeId == 0) return
@@ -322,6 +454,64 @@ class MainActivity : ComponentActivity() {
        }
    }

+    /**
+     * Pin the panel to a display mode matching the STREAM's refresh for the session's duration —
+     * exact rate first, else the smallest integer multiple (120 for a 60 stream: judder-free 2:1
+     * pulldown), else the highest available. Same-resolution modes only.
+     *
+     * The window-level mode pin is the belt to the decoder's `ANativeWindow_setFrameRate` braces:
+     * the surface hint alone is advisory, and several OEM refresh governors (Nothing OS's LTPO
+     * logic among them) ignore it entirely for third-party apps — leaving a 120 Hz session
+     * presenting on a 60/90 Hz panel, which reads as judder + a refresh of extra latency. The
+     * preferredDisplayModeId is the one signal they all honor. [hz] ≤ 0 falls back to releasing
+     * the pin (the pre-pin behaviour).
+     */
+    fun setStreamDisplayMode(hz: Int) {
+        if (hz <= 0) {
+            setConsoleHighRefreshRate(false)
+            return
+        }
+        val target = streamModeFor(hz) ?: return
+        window.attributes = window.attributes.apply { preferredDisplayModeId = target.modeId }
+    }
+
+    /**
+     * The panel refresh rate a [hz] stream runs against — [streamModeFor]'s pick, from the mode
+     * TABLE rather than `display.refreshRate`. The distinction matters: under a per-uid frame
+     * rate override (games get a 60 fps default on Android 15+) `refreshRate` reports the
+     * override, not the panel — observed on-glass as a 120 Hz panel reading back as 60. The
+     * supported-modes list is not override-filtered. `0` when unresolvable.
+     */
+    fun streamPanelFps(hz: Int): Int =
+        streamModeFor(hz)?.refreshRate?.let { kotlin.math.round(it).toInt() } ?: 0
+
+    /** The same-resolution display mode [setStreamDisplayMode] pins for a [hz] stream. */
+    private fun streamModeFor(hz: Int): android.view.Display.Mode? {
+        if (hz <= 0) return null
+        @Suppress("DEPRECATION")
+        val disp = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) display else windowManager.defaultDisplay
+        val current = disp?.mode ?: return null
+        val sameRes = disp.supportedModes.filter {
+            it.physicalWidth == current.physicalWidth && it.physicalHeight == current.physicalHeight
+        }
+        fun multiple(rate: Float): Int {
+            val k = (rate / hz).toInt()
+            return if (k >= 2 && kotlin.math.abs(rate - hz * k) < 1f) k else 0
+        }
+        return sameRes.minWithOrNull(
+            compareBy(
+                {
+                    when {
+                        kotlin.math.abs(it.refreshRate - hz) < 1f -> 0 // exact
+                        multiple(it.refreshRate) > 0 -> 1 // integer multiple — prefer smallest
+                        else -> 2 // no relation — prefer highest so at least nothing is halved
+                    }
+                },
+                { if (multiple(it.refreshRate) > 0) it.refreshRate else -it.refreshRate },
+            ),
+        )
+    }
+
    override fun dispatchKeyEvent(event: KeyEvent): Boolean {
        val handle = streamHandle
        if (handle != 0L) {
@@ -541,4 +731,29 @@ class MainActivity : ComponentActivity() {
        -> true
        else -> KeyEvent.isGamepadButton(kc)
    }
+
+    /** Does [intent]'s link resolve to the host [live] is already streaming? */
+    private fun targetsHost(intent: Intent?, live: LiveStream): Boolean {
+        val url = deepLinkFrom(intent) ?: return false
+        val parsed = DeepLinks.parse(url) as? DeepLinkResult.Parsed ?: return false
+        val target = DeepLinks.resolveHost(parsed.link, KnownHostStore(this).all())
+        return target is HostResolution.Known && target.host.id == live.hostId
+    }
+
+    /** The host a live stream is on — see [liveStream]. */
+    data class LiveStream(val hostId: String?)
+
+    companion object {
+        /**
+         * The live stream, PROCESS-wide (null = not streaming), published by the composition that
+         * owns it.
+         *
+         * Deliberately not per-instance state: `launchMode` is `standard`, so a `punktfunk://`
+         * link arrives as a second activity instance that knows nothing about the first — and the
+         * one thing it must know is that a session is already running. Static state is what
+         * crosses that gap; the process dying resets it, which is also correct.
+         */
+        @Volatile
+        var liveStream: LiveStream? = null
+    }
 }
@@ -32,7 +32,13 @@ class MouseForwarder(
    private val handle: Long,
    private val invertScroll: Boolean,
    private val captureWanted: Boolean,
-    private val surfaceSize: () -> Pair<Int, Int>,
+    /**
+     * The picture's rect in WINDOW coordinates — where the letterboxed video actually sits, which is
+     * the frame absolute positions must be measured against. Events arrive from the activity's
+     * dispatch overrides in window coordinates, so a stream narrower than the panel needs the origin
+     * subtracted as well as the size divided; `null` while the surface isn't laid out yet.
+     */
+    private val videoRect: () -> android.graphics.Rect?,
 ) {
    /** Capture plumbing, owned by StreamScreen (the focusable capture view). */
    var onRequestCapture: (() -> Unit)? = null
@@ -152,12 +158,16 @@ class MouseForwarder(
    }

    private fun sendAbs(ev: MotionEvent) {
-        val (w, h) = surfaceSize()
+        val r = videoRect() ?: return
+        val w = r.width()
+        val h = r.height()
        if (w <= 0 || h <= 0) return
+        // Clamped into the picture: a pointer out on a letterbox bar has no host position of its
+        // own, and the edge is the honest answer for it.
        NativeBridge.nativeSendPointerAbs(
            handle,
-            ev.x.roundToInt().coerceIn(0, w - 1),
-            ev.y.roundToInt().coerceIn(0, h - 1),
+            (ev.x - r.left).roundToInt().coerceIn(0, w - 1),
+            (ev.y - r.top).roundToInt().coerceIn(0, h - 1),
            w,
            h,
        )
@@ -0,0 +1,495 @@
+package io.unom.punktfunk
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.horizontalScroll
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.ExperimentalLayoutApi
+import androidx.compose.foundation.layout.FlowRow
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.aspectRatio
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Add
+import androidx.compose.material.icons.filled.ArrowDropDown
+import androidx.compose.material.icons.filled.Check
+import androidx.compose.material3.AlertDialog
+import androidx.compose.material3.AssistChip
+import androidx.compose.material3.AssistChipDefaults
+import androidx.compose.material3.Checkbox
+import androidx.compose.material3.DropdownMenu
+import androidx.compose.material3.DropdownMenuItem
+import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.ExposedDropdownMenuAnchorType
+import androidx.compose.material3.ExposedDropdownMenuBox
+import androidx.compose.material3.ExposedDropdownMenuDefaults
+import androidx.compose.material3.FilterChip
+import androidx.compose.material3.Icon
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+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.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.semantics.contentDescription
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.unit.dp
+
+/**
+ * The scope switcher: the one new settings concept. Selecting a profile puts the WHOLE settings
+ * surface into that profile's scope — there is one settings UI, never a second parallel editor
+ * that drifts from it. "Default settings" is the base layer every profile inherits from.
+ *
+ * A chips row rather than a menu, because on touch the scopes are worth seeing at a glance and
+ * there are rarely more than a handful. Managing a profile lives ON its chip: the selected one
+ * grows a chevron, and tapping it again opens Edit / Duplicate / Delete anchored under it. That
+ * replaced a lone overflow button parked after the LAST chip — which meant scrolling past every
+ * profile to reach an action that applied to one of them, with nothing on screen saying which.
+ *
+ * With no profiles at all the row is just "Default settings" and a "New profile" chip, which is
+ * all the clutter a user who never wants this feature ever sees.
+ */
+@Composable
+internal fun ProfileScopeChips(
+    profiles: List<StreamProfile>,
+    selectedId: String?,
+    onSelect: (String?) -> Unit,
+    onNew: () -> Unit,
+    onEdit: (StreamProfile) -> Unit,
+    onDuplicate: (StreamProfile) -> Unit,
+    onDelete: (StreamProfile) -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    // Which chip's menu is open — one at a time, and it closes itself when the scope changes.
+    var menuFor by remember { mutableStateOf<String?>(null) }
+    Row(
+        modifier = modifier.horizontalScroll(rememberScrollState()).padding(horizontal = 12.dp),
+        horizontalArrangement = Arrangement.spacedBy(8.dp),
+        verticalAlignment = Alignment.CenterVertically,
+    ) {
+        FilterChip(
+            selected = selectedId == null,
+            onClick = { onSelect(null) },
+            label = { Text("Default settings") },
+        )
+        profiles.forEach { p ->
+            val isSelected = selectedId == p.id
+            Box {
+                FilterChip(
+                    selected = isSelected,
+                    // Tap to select; tap the selected one — the one wearing the chevron — to manage
+                    // it. The action is on the object it acts on, which is the whole point.
+                    onClick = { if (isSelected) menuFor = p.id else onSelect(p.id) },
+                    // The dot and the chevron ride INSIDE the label, not in the `leadingIcon` /
+                    // `trailingIcon` slots: those reserve an 18dp icon and shrink the chip's padding
+                    // to suit, so a chip with an accent (or with the chevron) would sit differently
+                    // from "Default settings" beside it. In the label every chip keeps the same
+                    // padding and the spacing is ours to set.
+                    label = {
+                        Row(verticalAlignment = Alignment.CenterVertically) {
+                            accentColor(p.accent)?.let { dot ->
+                                AccentDot(dot, size = 8)
+                                Spacer(Modifier.width(8.dp))
+                            }
+                            Text(p.name)
+                            if (isSelected) {
+                                Spacer(Modifier.width(2.dp))
+                                Icon(
+                                    Icons.Filled.ArrowDropDown,
+                                    contentDescription = "Manage “${p.name}”",
+                                    modifier = Modifier.size(18.dp),
+                                )
+                            }
+                        }
+                    },
+                )
+                DropdownMenu(expanded = menuFor == p.id, onDismissRequest = { menuFor = null }) {
+                    DropdownMenuItem(text = { Text("Edit…") }, onClick = { menuFor = null; onEdit(p) })
+                    DropdownMenuItem(
+                        text = { Text("Duplicate") },
+                        onClick = { menuFor = null; onDuplicate(p) },
+                    )
+                    DropdownMenuItem(text = { Text("Delete…") }, onClick = { menuFor = null; onDelete(p) })
+                }
+            }
+        }
+        AssistChip(
+            onClick = onNew,
+            label = { Text("New profile") },
+            leadingIcon = {
+                Icon(Icons.Filled.Add, contentDescription = null, Modifier.size(AssistChipDefaults.IconSize))
+            },
+        )
+    }
+}
+
+/**
+ * Create or edit a profile: its name and its colour, decided together. They were two flows —
+ * a name dialog at creation, "Change colour…" afterwards — which meant every profile started
+ * colourless-looking until the user went hunting for a menu item, and the accent is exactly the
+ * signal that has to be there from the first moment (it is all a bound host card's chip and a
+ * pinned card's tint have to go on).
+ *
+ * Names must be unique case-insensitively: two "Work" chips in a menu are ambiguous, and a
+ * `punktfunk://…?profile=Work` link would have to refuse rather than guess. [taken] is the live
+ * duplicate check, which lets an edit keep its own name (and change only its case).
+ */
+@Composable
+internal fun ProfileEditorDialog(
+    title: String,
+    confirmLabel: String,
+    initialName: String,
+    initialAccent: String?,
+    creating: Boolean,
+    taken: (String) -> Boolean,
+    onConfirm: (name: String, accent: String?) -> Unit,
+    onDismiss: () -> Unit,
+) {
+    var name by remember { mutableStateOf(initialName) }
+    var accent by remember { mutableStateOf(initialAccent) }
+    val trimmed = name.trim()
+    val duplicate = trimmed.isNotEmpty() && taken(trimmed)
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        title = { Text(title) },
+        text = {
+            ProfileEditorFields(
+                name = name,
+                accent = accent,
+                duplicate = duplicate,
+                creating = creating,
+                onNameChange = { name = it },
+                onAccentChange = { accent = it },
+            )
+        },
+        confirmButton = {
+            TextButton(
+                enabled = trimmed.isNotEmpty() && !duplicate,
+                onClick = { onConfirm(trimmed, accent) },
+            ) { Text(confirmLabel) }
+        },
+        dismissButton = { TextButton(onClick = onDismiss) { Text("Cancel") } },
+    )
+}
+
+/**
+ * The editor's body. Extracted from [ProfileEditorDialog] so the screenshot harness can render
+ * exactly these — a focused text field inside a Dialog window never reaches idle under Robolectric,
+ * so the dialog itself is uncapturable, and an eyeballed-only layout is how this shipped once with
+ * the field and its caption touching.
+ */
+@OptIn(ExperimentalLayoutApi::class)
+@Composable
+internal fun ProfileEditorFields(
+    name: String,
+    accent: String?,
+    duplicate: Boolean,
+    creating: Boolean,
+    onNameChange: (String) -> Unit,
+    onAccentChange: (String?) -> Unit,
+) {
+    Column(verticalArrangement = Arrangement.spacedBy(10.dp)) {
+        OutlinedTextField(
+            value = name,
+            onValueChange = onNameChange,
+            label = { Text("Name") },
+            placeholder = { Text("e.g. Game, Work, Travel") },
+            singleLine = true,
+            isError = duplicate,
+        )
+        Text(
+            when {
+                duplicate -> "A profile called “${name.trim()}” already exists."
+                creating -> "A profile starts out inheriting every default setting. Whatever you " +
+                    "change while it's selected becomes an override."
+                else -> "The colour marks this profile on host cards, where its name doesn't fit."
+            },
+            style = MaterialTheme.typography.bodySmall,
+            color = if (duplicate) {
+                MaterialTheme.colorScheme.error
+            } else {
+                MaterialTheme.colorScheme.onSurfaceVariant
+            },
+        )
+        Text(
+            "Colour",
+            style = MaterialTheme.typography.labelLarge,
+            modifier = Modifier.padding(top = 4.dp),
+        )
+        // A fixed 4×2 grid rather than a flow: eight colours wrapping to whatever fits the dialog
+        // landed 6-then-2, which reads as a mistake. Two even rows read as a palette. The order is
+        // the hue sweep from PROFILE_ACCENTS, so it looks like a spectrum rather than a bag.
+        //
+        // Each row FILLS the width, its swatches sharing it equally, so the palette's edges line up
+        // with the name field above it and every row is the same length. A fixed swatch size left
+        // the rows short of the dialog's edge and wrapped unevenly, which read as the grid having
+        // run out rather than as a deliberate block.
+        Column(
+            verticalArrangement = Arrangement.spacedBy(SWATCH_GAP),
+            modifier = Modifier.fillMaxWidth(),
+        ) {
+            PROFILE_ACCENTS.chunked(SWATCHES_PER_ROW).forEach { row ->
+                Row(
+                    modifier = Modifier.fillMaxWidth(),
+                    horizontalArrangement = Arrangement.spacedBy(SWATCH_GAP),
+                ) {
+                    row.forEach { hex ->
+                        Swatch(
+                            colour = accentColor(hex),
+                            selected = accent?.equals(hex, ignoreCase = true) == true,
+                            onClick = { onAccentChange(hex) },
+                            modifier = Modifier.weight(1f),
+                        )
+                    }
+                }
+            }
+        }
+        // "No colour" is a real choice, not only an initial state — the chip then falls back to the
+        // theme's own accent, which is what a profile made before colours existed shows. It sits
+        // apart from the grid and says so in words, rather than hiding as a ninth, colourless
+        // circle that breaks the palette's rhythm.
+        Row(
+            verticalAlignment = Alignment.CenterVertically,
+            modifier = Modifier
+                .fillMaxWidth()
+                .clip(RoundedCornerShape(10.dp))
+                .clickable { onAccentChange(null) }
+                .padding(vertical = 4.dp),
+        ) {
+            Swatch(colour = null, selected = accent == null, onClick = { onAccentChange(null) })
+            Text(
+                "No colour",
+                style = MaterialTheme.typography.bodyMedium,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                modifier = Modifier.padding(start = 12.dp),
+            )
+        }
+    }
+}
+
+/**
+ * One colour choice. The selected one keeps its size and grows a ring OUTSIDE the disc with a gap
+ * between the two, plus a check — a border drawn on the disc's own edge reads as a heavier circle
+ * rather than as a selection, and colour-plus-check survives a reader who can't tell two of these
+ * hues apart. The ring's space is always reserved, so picking never nudges the grid.
+ *
+ * `null` is "no colour": the surface's own variant, outlined so it reads as an empty slot rather
+ * than a dark swatch.
+ */
+@Composable
+internal fun Swatch(
+    colour: Color?,
+    selected: Boolean,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier.size(SWATCH_TOTAL),
+) {
+    val fill = colour ?: MaterialTheme.colorScheme.surfaceVariant
+    Box(
+        modifier = modifier
+            .aspectRatio(1f)
+            .clip(CircleShape)
+            .then(
+                if (selected) {
+                    Modifier.border(2.dp, MaterialTheme.colorScheme.onSurface, CircleShape)
+                } else {
+                    Modifier
+                },
+            )
+            .clickable(onClick = onClick)
+            .semantics { contentDescription = if (colour == null) "No colour" else "Colour" },
+        contentAlignment = Alignment.Center,
+    ) {
+        Box(
+            Modifier
+                // Padding, not a fixed size: the disc has to scale with a swatch that shares its
+                // row's width, while the gap that makes the selection ring read stays constant.
+                .fillMaxSize()
+                .padding(RING_GAP)
+                .clip(CircleShape)
+                .background(fill)
+                .then(
+                    if (colour == null) {
+                        Modifier.border(1.dp, MaterialTheme.colorScheme.outline, CircleShape)
+                    } else {
+                        Modifier
+                    },
+                ),
+            contentAlignment = Alignment.Center,
+        ) {
+            if (selected) {
+                Icon(
+                    Icons.Filled.Check,
+                    contentDescription = null,
+                    modifier = Modifier.size(18.dp),
+                    // These hues are all light enough that a near-black check is the readable one;
+                    // the empty slot is dark, so it takes the surface's foreground instead.
+                    tint = if (colour == null) {
+                        MaterialTheme.colorScheme.onSurfaceVariant
+                    } else {
+                        Color(0xFF1B1633)
+                    },
+                )
+            }
+        }
+    }
+}
+
+/**
+ * The palette's geometry. [SWATCHES_PER_ROW] divides [PROFILE_ACCENTS] exactly — that is the whole
+ * reason the palette has ten colours — so both rows are full. [SWATCH_TOTAL] is only the fallback
+ * footprint for a swatch outside the grid (the "no colour" one); in the grid a swatch takes an
+ * equal share of the row instead.
+ */
+private const val SWATCHES_PER_ROW = 5
+private val SWATCH_TOTAL = 44.dp
+private val RING_GAP = 5.dp
+private val SWATCH_GAP = 10.dp
+
+/**
+ * Deleting a profile is not destructive to anything but the profile — a host bound to it falls
+ * back to the default settings and a card pinned to it disappears, neither of which is an error.
+ * The warning counts both so the consequence is stated rather than discovered.
+ */
+@Composable
+internal fun DeleteProfileDialog(
+    profile: StreamProfile,
+    boundHosts: Int,
+    pinnedCards: Int,
+    onConfirm: () -> Unit,
+    onDismiss: () -> Unit,
+) {
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        title = { Text("Delete “${profile.name}”?") },
+        text = {
+            Column(verticalArrangement = Arrangement.spacedBy(8.dp)) {
+                val consequences = buildList {
+                    if (boundHosts > 0) {
+                        add("$boundHosts ${plural(boundHosts, "host", "hosts")} will fall back to the default settings")
+                    }
+                    if (pinnedCards > 0) {
+                        add("$pinnedCards pinned ${plural(pinnedCards, "card", "cards")} will disappear")
+                    }
+                }
+                Text(
+                    if (consequences.isEmpty()) {
+                        "Nothing uses this profile."
+                    } else {
+                        consequences.joinToString(", and ") + "."
+                    },
+                )
+                Text(
+                    "The settings it overrides aren't lost anywhere else — the defaults stay " +
+                        "exactly as they are.",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+        },
+        confirmButton = { TextButton(onClick = onConfirm) { Text("Delete") } },
+        dismissButton = { TextButton(onClick = onDismiss) { Text("Cancel") } },
+    )
+}
+
+private fun plural(n: Int, one: String, many: String) = if (n == 1) one else many
+
+/**
+ * The per-host half of profiles, inside the host's Edit sheet: which profile a plain tap uses
+ * (the binding — the one thing that IS sticky; "Connect with ▸" on a card never rebinds), and which
+ * profiles get their own card in the host list.
+ */
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+internal fun HostProfileBinding(
+    profiles: List<StreamProfile>,
+    boundId: String?,
+    onBind: (String?) -> Unit,
+    pins: List<String>,
+    onTogglePin: (String) -> Unit,
+) {
+    var expanded by remember { mutableStateOf(false) }
+    val bound = profiles.firstOrNull { it.id == boundId }
+    Column(verticalArrangement = Arrangement.spacedBy(4.dp)) {
+        ExposedDropdownMenuBox(expanded = expanded, onExpandedChange = { expanded = it }) {
+            OutlinedTextField(
+                value = bound?.name ?: "Default settings",
+                onValueChange = {},
+                readOnly = true,
+                label = { Text("Profile") },
+                trailingIcon = { ExposedDropdownMenuDefaults.TrailingIcon(expanded = expanded) },
+                modifier = Modifier
+                    .menuAnchor(ExposedDropdownMenuAnchorType.PrimaryNotEditable)
+                    .fillMaxWidth(),
+            )
+            ExposedDropdownMenu(expanded = expanded, onDismissRequest = { expanded = false }) {
+                DropdownMenuItem(
+                    text = { Text("Default settings") },
+                    onClick = { onBind(null); expanded = false },
+                )
+                profiles.forEach { p ->
+                    DropdownMenuItem(
+                        text = { Text(p.name) },
+                        onClick = { onBind(p.id); expanded = false },
+                    )
+                }
+            }
+        }
+        Text(
+            "What a tap on this host connects with.",
+            style = MaterialTheme.typography.bodySmall,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+        )
+        Text(
+            "Pinned cards",
+            style = MaterialTheme.typography.labelLarge,
+            modifier = Modifier.padding(top = 8.dp),
+        )
+        Text(
+            "A pinned profile gets its own card beside this host — one tap instead of a menu. " +
+                "Pinning changes nothing about which profile is the default.",
+            style = MaterialTheme.typography.bodySmall,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+        )
+        profiles.forEach { p ->
+            Row(
+                modifier = Modifier.fillMaxWidth(),
+                verticalAlignment = Alignment.CenterVertically,
+            ) {
+                Text(p.name, modifier = Modifier.weight(1f))
+                Checkbox(checked = p.id in pins, onCheckedChange = { onTogglePin(p.id) })
+            }
+        }
+    }
+}
+
+/** The accent marker a profile's chip and its pinned cards wear. */
+@Composable
+internal fun AccentDot(color: Color, size: Int = 10) {
+    Box(Modifier.size(size.dp).clip(CircleShape).background(color))
+}
+
+/** `#RRGGBB` → a Compose colour, or null when the stored string isn't one (never a crash). */
+internal fun accentColor(hex: String?): Color? {
+    val h = hex?.removePrefix("#") ?: return null
+    if (h.length != 6 || !h.all { it.isDigit() || it.lowercaseChar() in 'a'..'f' }) return null
+    return runCatching { Color(h.toLong(16) or 0xFF000000L) }.getOrNull()
+}
@@ -0,0 +1,407 @@
+package io.unom.punktfunk
+
+import android.content.Context
+import io.unom.punktfunk.kit.security.KnownHost
+import java.security.SecureRandom
+import org.json.JSONObject
+
+/**
+ * Client settings profiles — named bundles of setting overrides applied on top of the global
+ * [Settings] (design/client-settings-profiles.md §4). The Kotlin mirror of
+ * `crates/pf-client-core/src/profiles.rs`; the model is the same on every client, so get it right
+ * here rather than re-deciding it.
+ *
+ * A profile overrides only the fields the user touched; everything else keeps following the global
+ * defaults **live**, so fixing a global once fixes it everywhere. That is why an overlay is sparse
+ * nullable fields rather than a snapshot copy, and why a value is written on touch and cleared only
+ * on an explicit "reset to default" — never by diffing against the current global at save time. A
+ * stored value that happens to equal today's global is a legitimate *pin*: the profile keeps it
+ * when the global later moves.
+ *
+ * Only tier-P settings are here. Device facts (which pad this device forwards, whether its console
+ * UI is on) and host facts (clipboard sync, which lives on the host record) are deliberately absent
+ * — see the design's §3 curation.
+ *
+ * Values are stored exactly as [SettingsStore] persists them — ints for the compositor/gamepad wire
+ * bytes, enum names for the rest — so there is one encoding of a setting on this platform rather
+ * than two. The catalog is client-local (v1 has no profile sync or export), so nothing else reads
+ * it.
+ */
+data class SettingsOverlay(
+    val width: Int? = null,
+    val height: Int? = null,
+    val hz: Int? = null,
+    val bitrateKbps: Int? = null,
+    val renderScale: Double? = null,
+    val codec: String? = null,
+    val hdrEnabled: Boolean? = null,
+    val compositor: Int? = null,
+    val audioChannels: Int? = null,
+    val micEnabled: Boolean? = null,
+    val touchMode: TouchMode? = null,
+    val mouseMode: MouseMode? = null,
+    val invertScroll: Boolean? = null,
+    val gamepad: Int? = null,
+    val statsVerbosity: StatsVerbosity? = null,
+    /**
+     * Android-only tier-P addition (design §3): the decode pipeline is a device fact everywhere
+     * else, but here it is the one knob a marginal link wants turned off per host.
+     */
+    val lowLatencyMode: Boolean? = null,
+    /** The timeline presenter's intent pair — cross-client keys, see [Settings.presentPriority]. */
+    val presentPriority: String? = null,
+    val smoothBuffer: Int? = null,
+    /**
+     * Overlay keys a newer build wrote and this one doesn't model — carried through a load→save
+     * round-trip untouched. The don't-clobber rule: opening and saving a profile on an older client
+     * must not erase what a newer one stored.
+     */
+    val extra: Map<String, Any> = emptyMap(),
+) {
+    /** The one resolution seam: this overlay on top of [base]. Pure, so it is fully testable. */
+    fun apply(base: Settings): Settings = base.copy(
+        width = width ?: base.width,
+        height = height ?: base.height,
+        hz = hz ?: base.hz,
+        bitrateKbps = bitrateKbps ?: base.bitrateKbps,
+        renderScale = renderScale ?: base.renderScale,
+        codec = codec ?: base.codec,
+        hdrEnabled = hdrEnabled ?: base.hdrEnabled,
+        compositor = compositor ?: base.compositor,
+        audioChannels = audioChannels ?: base.audioChannels,
+        micEnabled = micEnabled ?: base.micEnabled,
+        touchMode = touchMode ?: base.touchMode,
+        mouseMode = mouseMode ?: base.mouseMode,
+        invertScroll = invertScroll ?: base.invertScroll,
+        gamepad = gamepad ?: base.gamepad,
+        statsVerbosity = statsVerbosity ?: base.statsVerbosity,
+        lowLatencyMode = lowLatencyMode ?: base.lowLatencyMode,
+        presentPriority = presentPriority ?: base.presentPriority,
+        smoothBuffer = smoothBuffer ?: base.smoothBuffer,
+    )
+
+    /**
+     * Record, as overrides, every tier-P field that differs between two settings snapshots.
+     *
+     * The settings UI commits a whole `Settings` per control (`update(s.copy(codec = …))`), so it
+     * can't hand over a list of touched fields — it hands over "what the control was showing" and
+     * "what it shows now", and the only field that can differ is the one the user just touched.
+     *
+     * This is NOT the diff-on-save the design rejects: the comparison is against the EFFECTIVE
+     * settings the control was displaying, not against the globals, so setting a value back to
+     * whatever the global happens to be still records an override — the pin. It only ever adds
+     * overrides; removing one is [clear], a different, explicit operation.
+     */
+    fun absorb(before: Settings, after: Settings): SettingsOverlay = copy(
+        width = if (after.width != before.width) after.width else width,
+        height = if (after.height != before.height) after.height else height,
+        hz = if (after.hz != before.hz) after.hz else hz,
+        bitrateKbps = if (after.bitrateKbps != before.bitrateKbps) after.bitrateKbps else bitrateKbps,
+        renderScale = if (after.renderScale != before.renderScale) after.renderScale else renderScale,
+        codec = if (after.codec != before.codec) after.codec else codec,
+        hdrEnabled = if (after.hdrEnabled != before.hdrEnabled) after.hdrEnabled else hdrEnabled,
+        compositor = if (after.compositor != before.compositor) after.compositor else compositor,
+        audioChannels = if (after.audioChannels != before.audioChannels) after.audioChannels else audioChannels,
+        micEnabled = if (after.micEnabled != before.micEnabled) after.micEnabled else micEnabled,
+        touchMode = if (after.touchMode != before.touchMode) after.touchMode else touchMode,
+        mouseMode = if (after.mouseMode != before.mouseMode) after.mouseMode else mouseMode,
+        invertScroll = if (after.invertScroll != before.invertScroll) after.invertScroll else invertScroll,
+        gamepad = if (after.gamepad != before.gamepad) after.gamepad else gamepad,
+        statsVerbosity = if (after.statsVerbosity != before.statsVerbosity) after.statsVerbosity else statsVerbosity,
+        lowLatencyMode = if (after.lowLatencyMode != before.lowLatencyMode) after.lowLatencyMode else lowLatencyMode,
+        presentPriority = if (after.presentPriority != before.presentPriority) after.presentPriority else presentPriority,
+        smoothBuffer = if (after.smoothBuffer != before.smoothBuffer) after.smoothBuffer else smoothBuffer,
+    )
+
+    /**
+     * Drop one override by its field name, putting the row back to inheriting. [FIELD_RESOLUTION]
+     * is the one alias, covering the width/height pair a single control drives. An unknown name is
+     * a no-op.
+     */
+    fun clear(field: String): SettingsOverlay = when (field) {
+        FIELD_RESOLUTION -> copy(width = null, height = null)
+        "refresh_hz" -> copy(hz = null)
+        "bitrate_kbps" -> copy(bitrateKbps = null)
+        "render_scale" -> copy(renderScale = null)
+        "codec" -> copy(codec = null)
+        "hdr_enabled" -> copy(hdrEnabled = null)
+        "compositor" -> copy(compositor = null)
+        "audio_channels" -> copy(audioChannels = null)
+        "mic_enabled" -> copy(micEnabled = null)
+        "touch_mode" -> copy(touchMode = null)
+        "mouse_mode" -> copy(mouseMode = null)
+        "invert_scroll" -> copy(invertScroll = null)
+        "gamepad" -> copy(gamepad = null)
+        "stats_verbosity" -> copy(statsVerbosity = null)
+        "low_latency_mode" -> copy(lowLatencyMode = null)
+        "present_priority" -> copy(presentPriority = null)
+        "smooth_buffer" -> copy(smoothBuffer = null)
+        else -> this
+    }
+
+    /** The field names this overlay overrides — what the settings rows draw their markers from. */
+    fun overridden(): Set<String> = buildSet {
+        if (width != null || height != null) add(FIELD_RESOLUTION)
+        if (hz != null) add("refresh_hz")
+        if (bitrateKbps != null) add("bitrate_kbps")
+        if (renderScale != null) add("render_scale")
+        if (codec != null) add("codec")
+        if (hdrEnabled != null) add("hdr_enabled")
+        if (compositor != null) add("compositor")
+        if (audioChannels != null) add("audio_channels")
+        if (micEnabled != null) add("mic_enabled")
+        if (touchMode != null) add("touch_mode")
+        if (mouseMode != null) add("mouse_mode")
+        if (invertScroll != null) add("invert_scroll")
+        if (gamepad != null) add("gamepad")
+        if (statsVerbosity != null) add("stats_verbosity")
+        if (lowLatencyMode != null) add("low_latency_mode")
+        if (presentPriority != null) add("present_priority")
+        if (smoothBuffer != null) add("smooth_buffer")
+    }
+
+    /**
+     * True when the profile overrides nothing — "inherits everything", the state a freshly created
+     * profile starts in. A profile holding only a newer build's field is NOT empty.
+     */
+    fun isEmpty(): Boolean = overridden().isEmpty() && extra.isEmpty()
+
+    internal fun toJson(): JSONObject {
+        val j = JSONObject()
+        // Unknown keys first, so a modelled field always wins over a stale carried-through one.
+        extra.forEach { (k, v) -> j.put(k, v) }
+        width?.let { j.put("width", it) }
+        height?.let { j.put("height", it) }
+        hz?.let { j.put("refresh_hz", it) }
+        bitrateKbps?.let { j.put("bitrate_kbps", it) }
+        renderScale?.let { j.put("render_scale", it) }
+        codec?.let { j.put("codec", it) }
+        hdrEnabled?.let { j.put("hdr_enabled", it) }
+        compositor?.let { j.put("compositor", it) }
+        audioChannels?.let { j.put("audio_channels", it) }
+        micEnabled?.let { j.put("mic_enabled", it) }
+        touchMode?.let { j.put("touch_mode", it.name) }
+        mouseMode?.let { j.put("mouse_mode", it.storedName) }
+        invertScroll?.let { j.put("invert_scroll", it) }
+        gamepad?.let { j.put("gamepad", it) }
+        statsVerbosity?.let { j.put("stats_verbosity", it.name) }
+        lowLatencyMode?.let { j.put("low_latency_mode", it) }
+        presentPriority?.let { j.put("present_priority", it) }
+        smoothBuffer?.let { j.put("smooth_buffer", it) }
+        return j
+    }
+
+    companion object {
+        /** The width/height pair, which one control drives — the reset alias, as on every client. */
+        const val FIELD_RESOLUTION = "resolution"
+
+        /** Keys this build models; everything else in a stored overlay is carried through. */
+        private val KNOWN = setOf(
+            "width", "height", "refresh_hz", "bitrate_kbps", "render_scale", "codec",
+            "hdr_enabled", "compositor", "audio_channels", "mic_enabled", "touch_mode",
+            "mouse_mode", "invert_scroll", "gamepad", "stats_verbosity", "low_latency_mode",
+            "present_priority", "smooth_buffer",
+        )
+
+        internal fun fromJson(j: JSONObject): SettingsOverlay = SettingsOverlay(
+            width = j.optIntOrNull("width"),
+            height = j.optIntOrNull("height"),
+            hz = j.optIntOrNull("refresh_hz"),
+            bitrateKbps = j.optIntOrNull("bitrate_kbps"),
+            renderScale = if (j.has("render_scale")) j.optDouble("render_scale") else null,
+            codec = j.optStringOrNull("codec"),
+            hdrEnabled = j.optBooleanOrNull("hdr_enabled"),
+            compositor = j.optIntOrNull("compositor"),
+            audioChannels = j.optIntOrNull("audio_channels"),
+            micEnabled = j.optBooleanOrNull("mic_enabled"),
+            touchMode = j.optStringOrNull("touch_mode")
+                ?.let { n -> TouchMode.entries.firstOrNull { it.name == n } },
+            mouseMode = j.optStringOrNull("mouse_mode")
+                ?.let { n -> MouseMode.entries.firstOrNull { it.storedName == n } },
+            invertScroll = j.optBooleanOrNull("invert_scroll"),
+            gamepad = j.optIntOrNull("gamepad"),
+            statsVerbosity = j.optStringOrNull("stats_verbosity")
+                ?.let { n -> StatsVerbosity.entries.firstOrNull { it.name == n } },
+            lowLatencyMode = j.optBooleanOrNull("low_latency_mode"),
+            presentPriority = j.optStringOrNull("present_priority"),
+            smoothBuffer = j.optIntOrNull("smooth_buffer"),
+            extra = j.keys().asSequence().filter { it !in KNOWN }.associateWith { j.get(it) },
+        )
+    }
+}
+
+/**
+ * One named bundle of overrides. [id] is stable across renames — host bindings, pinned cards and
+ * `punktfunk://` links all point at it, never at the name.
+ */
+data class StreamProfile(
+    val id: String,
+    /** User-facing and editable; unique case-insensitively (menus are ambiguous otherwise). */
+    val name: String,
+    /** `#RRGGBB` chip colour. Reserved by the schema; pinned cards tint their subtitle with it. */
+    val accent: String? = null,
+    val overrides: SettingsOverlay = SettingsOverlay(),
+    /** Profile keys a newer build wrote — preserved across a load→save round-trip. */
+    val extra: Map<String, Any> = emptyMap(),
+)
+
+/** What a `profile=` / one-off reference resolved to. Ambiguity is reported, never guessed. */
+enum class ProfileResolution { FOUND, NOT_FOUND, AMBIGUOUS }
+
+/**
+ * The profile catalog — client-wide, not per host: "Work" applied to three hosts is one profile,
+ * and the per-host part is only the binding on the host record ([KnownHost.profileId]).
+ *
+ * Stored one JSON string per profile keyed by id in its own `punktfunk_profiles` prefs file — the
+ * `KnownHostStore` pattern, and deliberately not inside the settings file, which is rewritten
+ * wholesale by several writers.
+ */
+class ProfileStore(context: Context) {
+    private val prefs =
+        context.applicationContext.getSharedPreferences("punktfunk_profiles", Context.MODE_PRIVATE)
+
+    /** Every profile, name-sorted — the order the scope switcher and the menus show. */
+    fun all(): List<StreamProfile> = prefs.all.values
+        .mapNotNull { (it as? String)?.let(::parse) }
+        .sortedBy { it.name.lowercase() }
+
+    fun byId(id: String): StreamProfile? = prefs.getString(id, null)?.let(::parse)
+
+    fun save(profile: StreamProfile) {
+        prefs.edit().putString(profile.id, encode(profile)).apply()
+    }
+
+    fun delete(id: String) {
+        prefs.edit().remove(id).apply()
+    }
+
+    /**
+     * Resolve a reference the way every surface must: exact id first, then a unique
+     * case-insensitive name. Two profiles sharing a name resolve to [ProfileResolution.AMBIGUOUS]
+     * — a link or a flag naming two profiles must refuse, not pick whichever came first.
+     */
+    fun resolve(reference: String): Pair<StreamProfile?, ProfileResolution> {
+        if (reference.isEmpty()) return null to ProfileResolution.NOT_FOUND
+        byId(reference)?.let { return it to ProfileResolution.FOUND }
+        val hits = all().filter { it.name.equals(reference, ignoreCase = true) }
+        return when (hits.size) {
+            1 -> hits[0] to ProfileResolution.FOUND
+            0 -> null to ProfileResolution.NOT_FOUND
+            else -> null to ProfileResolution.AMBIGUOUS
+        }
+    }
+
+    /**
+     * Is this name already used (case-insensitively) by a *different* profile? The create/rename
+     * guard — [except] is the profile being renamed, so renaming "Work" to "work" is allowed.
+     */
+    fun nameTaken(name: String, except: String? = null): Boolean =
+        all().any { it.name.equals(name, ignoreCase = true) && it.id != except }
+
+    /**
+     * The profile a connect to [host] should use: the one-off pick, else the host's binding, else
+     * none. [oneOff] is a reference (id or unique name); the empty string means "force the global
+     * defaults" — a real choice ("Connect with ▸ Default settings" on a bound host), not "unset",
+     * which is why it must survive as a value all the way down here. A binding whose profile was
+     * deleted resolves as none: never an error, never a blocked connect.
+     */
+    fun resolveFor(host: KnownHost?, oneOff: String?): StreamProfile? = when {
+        oneOff != null -> resolve(oneOff).first
+        else -> host?.profileId?.let(::byId)
+    }
+
+    /** [host]'s pinned profiles, in card order, with duplicates and deleted profiles dropped. */
+    fun pinsFor(host: KnownHost): List<StreamProfile> =
+        host.pinnedProfileIds.distinct().mapNotNull(::byId)
+
+    private fun parse(s: String): StreamProfile? = runCatching {
+        val j = JSONObject(s)
+        StreamProfile(
+            id = j.getString("id"),
+            name = j.getString("name"),
+            accent = j.optStringOrNull("accent"),
+            overrides = SettingsOverlay.fromJson(j.optJSONObject("overrides") ?: JSONObject()),
+            extra = j.keys().asSequence()
+                .filter { it !in setOf("id", "name", "accent", "overrides") }
+                .associateWith { j.get(it) },
+        )
+    }.getOrNull()
+
+    private fun encode(p: StreamProfile): String {
+        val j = JSONObject()
+        p.extra.forEach { (k, v) -> j.put(k, v) }
+        j.put("id", p.id)
+        j.put("name", p.name)
+        p.accent?.let { j.put("accent", it) }
+        j.put("overrides", p.overrides.toJson())
+        return j.toString()
+    }
+}
+
+/**
+ * Chip colours a profile can wear. Chosen to stay legible on a dark surface and to be
+ * distinguishable from each other at the size they are actually used — a 6dp dot on a chip and a
+ * tint on a pinned card — and held at one saturation and lightness so no single swatch shouts
+ * over its neighbours. Deliberately NOT the presence green ([HostCard]'s online dot), which means
+ * something else entirely.
+ *
+ * **Ordered by hue**, so the picker reads as one sweep of the colour wheel rather than a bag of
+ * colours; the degrees are in the comments to keep it that way when one is swapped out. That order
+ * is also the order [nextAccent] hands them out in, so a user creating profiles one after another
+ * walks the spectrum instead of getting an arbitrary sequence.
+ */
+val PROFILE_ACCENTS = listOf(
+    "#FF8A4C", // orange   21°
+    "#FBBF24", // amber    45°
+    "#A3E635", // lime     82°
+    "#34D399", // green   160°
+    "#22D3EE", // cyan    187°
+    "#60A5FA", // blue    213°
+    "#818CF8", // indigo  239°
+    "#A78BFA", // violet  258°
+    "#F472B6", // pink    330°
+    "#FB7185", // rose    350°
+)
+
+/** The first accent no existing profile is using, so two profiles don't look alike by accident. */
+fun nextAccent(existing: List<StreamProfile>): String {
+    val taken = existing.mapNotNull { it.accent?.lowercase() }.toSet()
+    return PROFILE_ACCENTS.firstOrNull { it.lowercase() !in taken } ?: PROFILE_ACCENTS.first()
+}
+
+/**
+ * A new, empty profile: it inherits everything, which is the right creation default under
+ * inherit-by-exception (Duplicate covers "start from that other profile"). The id is 12 lowercase
+ * hex characters — the shape the Rust `new_profile_id` mints.
+ *
+ * [accent] is presentation, not a setting, so it does NOT inherit — a profile with no colour would
+ * be indistinguishable from the defaults everywhere the accent is the whole signal (a bound card's
+ * chip, a pinned card's tint). Callers creating a profile from the UI pass [nextAccent].
+ */
+fun newProfile(name: String, accent: String? = null): StreamProfile =
+    StreamProfile(id = newProfileId(), name = name, accent = accent)
+
+private val PROFILE_ID_RNG = SecureRandom()
+
+fun newProfileId(): String {
+    val b = ByteArray(6)
+    PROFILE_ID_RNG.nextBytes(b)
+    return b.joinToString("") { "%02x".format(it) }
+}
+
+/**
+ * The settings a connect to [host] should use: the resolved profile's overrides on top of these
+ * globals, resolved ONCE per connect (matching the latch-at-connect model the "applies from the
+ * next session" footers promise). See [ProfileStore.resolveFor] for the precedence.
+ */
+fun Settings.effectiveFor(profile: StreamProfile?): Settings =
+    profile?.overrides?.apply(this) ?: this
+
+// ---- org.json null-vs-absent helpers (optInt and friends can't tell 0 from "not there") ---------
+
+private fun JSONObject.optIntOrNull(key: String): Int? = if (has(key)) optInt(key) else null
+private fun JSONObject.optBooleanOrNull(key: String): Boolean? =
+    if (has(key)) optBoolean(key) else null
+
+private fun JSONObject.optStringOrNull(key: String): String? =
+    if (has(key)) optString(key).ifEmpty { null } else null
@@ -83,6 +83,19 @@ data class Settings(
     * feeds a queue that only grows.
     */
    val lowLatencyMode: Boolean = true,
+    /**
+     * The timeline presenter's intent — the cross-client `present_priority` pair (the Apple
+     * client's "Prioritize" picker, same stored values): `"latency"` (default) = newest-wins,
+     * a frame reaches glass the instant the glass budget opens; `"smooth"` = a small FIFO
+     * drained one frame per vsync, absorbing network/decode jitter at one refresh of added
+     * display latency per buffered frame. Anything unrecognized resolves to latency.
+     */
+    val presentPriority: String = "latency",
+    /**
+     * The smoothness buffer depth (`smooth_buffer`): 0 = Automatic (2 frames), else 1..3.
+     * Only meaningful when [presentPriority] is `"smooth"`.
+     */
+    val smoothBuffer: Int = 0,
    /**
     * Wake-on-LAN a saved host before connecting when it isn't currently seen on mDNS. On (default):
     * a connect to a host with a learned MAC that isn't advertising sends a magic packet and waits
@@ -111,30 +124,53 @@ data class Settings(
    val sc2Capture: Boolean = true,

    /**
-     * Lock a physical mouse to the stream ([android.view.View.requestPointerCapture]) and forward
-     * raw relative motion — FPS mouse-look, the iPad "Capture pointer for games" twin. Engages at
-     * stream start and on a click into the stream; Ctrl+Alt+Shift+Q toggles it live (the chord
-     * works even with this off). Off (default): a mouse points absolutely, desktop-style.
+     * Capture a USB-connected Sony controller (DualSense / DualSense Edge / DualShock 4) and
+     * drive it directly: the app claims the pad's HID interface and renders the host's feedback
+     * by writing USB output reports — rumble works on every phone (no kernel force-feedback
+     * driver needed), and adaptive triggers + lightbar + player LEDs work at all (Android has no
+     * platform API for any of them). ON by default — it engages only when such a pad is attached
+     * over USB at stream start; uncaptured (toggle off / no permission / Bluetooth) the pad stays
+     * on the ordinary InputDevice path. USB only: Android exposes no raw path to a Bluetooth
+     * Classic pad, which is also why Sony's own Remote Play has no Android trigger support.
     */
-    val pointerCapture: Boolean = false,
+    val dsCapture: Boolean = true,
+
+    /**
+     * How a physical mouse drives the host — the cross-client mouse model (see [MouseMode]).
+     * [MouseMode.DESKTOP] (default here) points absolutely; [MouseMode.CAPTURE] locks the pointer
+     * to the stream ([android.view.View.requestPointerCapture]) and forwards raw relative motion.
+     * Read once per session by StreamScreen; Ctrl+Alt+Shift+Q flips the capture live either way.
+     */
+    val mouseMode: MouseMode = MouseMode.DESKTOP,

    /**
     * Flip scroll direction — the mouse wheel and the two-finger touch scroll both. Parity with
     * the Apple/GTK clients' "Invert scroll direction".
     */
    val invertScroll: Boolean = false,
-
-    /**
-     * Sync text copied on this device to the host and vice versa while streaming (the desktop
-     * clients' shared clipboard, text-only here). Only effective when the host advertises the
-     * clipboard capability; the protocol is opt-in per session either way.
-     */
-    val clipboardSync: Boolean = true,
+    // NOTE: clipboard sync is NOT here. It is a decision about a HOST, not about this device or
+    // this stream (design/client-settings-profiles.md §3, tier H), so it lives on the host record
+    // — see `KnownHost.clipboardSync`. It used to be a global here; `KnownHostStore.migrate`
+    // copied that value onto every saved host and retired the key.
 )

 /** [Settings.touchMode] values; persisted by name. */
 enum class TouchMode { TRACKPAD, POINTER, TOUCH }

+/**
+ * How a physical mouse drives the host — the cross-client mouse model (the Rust `MouseMode`,
+ * persisted as the same lowercase names). Only meaningful with a mouse attached.
+ * - [CAPTURE] — pointer lock: relative deltas, the local cursor hidden, the host's cursor the only
+ *   one you see. The game model, and the desktop clients' default.
+ * - [DESKTOP] — uncaptured absolute pointing: the cursor enters and leaves the stream freely. The
+ *   remote-desktop model, and Android's default (a phone/TV is far more often driven by touch or a
+ *   pad than by a locked mouse, and this is what the platform did before the setting existed).
+ */
+enum class MouseMode(val storedName: String, val label: String) {
+    CAPTURE("capture", "Capture (games)"),
+    DESKTOP("desktop", "Desktop (absolute)"),
+}
+
 /**
 * Stats-overlay detail tiers, in cycling order (persisted by name). Each tier is a strict superset
 * of the previous one, so toning down never hides a number a lower tier keeps:
@@ -190,12 +226,19 @@ class SettingsStore(context: Context) {
        gamepadUiEnabled = prefs.getBoolean(K_GAMEPAD_UI, true),
        libraryEnabled = prefs.getBoolean(K_LIBRARY, true),
        lowLatencyMode = prefs.getBoolean(K_LOW_LATENCY, true),
+        presentPriority = prefs.getString(K_PRESENT_PRIORITY, "latency") ?: "latency",
+        smoothBuffer = prefs.getInt(K_SMOOTH_BUFFER, 0),
        autoWakeEnabled = prefs.getBoolean(K_AUTO_WAKE, true),
        rumbleOnPhone = prefs.getBoolean(K_RUMBLE_ON_PHONE, false),
        sc2Capture = prefs.getBoolean(K_SC2_CAPTURE, true),
-        pointerCapture = prefs.getBoolean(K_POINTER_CAPTURE, false),
+        dsCapture = prefs.getBoolean(K_DS_CAPTURE, true),
+        mouseMode = prefs.getString(K_MOUSE_MODE, null)
+            ?.let { name -> MouseMode.entries.firstOrNull { it.storedName == name } }
+            // Migration: the pre-enum Boolean "pointer_capture" (true = lock the pointer). Its
+            // default was false, which IS `desktop` — so an install that never touched the toggle
+            // lands where it already was.
+            ?: if (prefs.getBoolean(K_POINTER_CAPTURE, false)) MouseMode.CAPTURE else MouseMode.DESKTOP,
        invertScroll = prefs.getBoolean(K_INVERT_SCROLL, false),
-        clipboardSync = prefs.getBoolean(K_CLIPBOARD_SYNC, true),
    )

    fun save(s: Settings) {
@@ -216,12 +259,14 @@ class SettingsStore(context: Context) {
            .putBoolean(K_GAMEPAD_UI, s.gamepadUiEnabled)
            .putBoolean(K_LIBRARY, s.libraryEnabled)
            .putBoolean(K_LOW_LATENCY, s.lowLatencyMode)
+            .putString(K_PRESENT_PRIORITY, s.presentPriority)
+            .putInt(K_SMOOTH_BUFFER, s.smoothBuffer)
            .putBoolean(K_AUTO_WAKE, s.autoWakeEnabled)
            .putBoolean(K_RUMBLE_ON_PHONE, s.rumbleOnPhone)
            .putBoolean(K_SC2_CAPTURE, s.sc2Capture)
-            .putBoolean(K_POINTER_CAPTURE, s.pointerCapture)
+            .putBoolean(K_DS_CAPTURE, s.dsCapture)
+            .putString(K_MOUSE_MODE, s.mouseMode.storedName)
            .putBoolean(K_INVERT_SCROLL, s.invertScroll)
-            .putBoolean(K_CLIPBOARD_SYNC, s.clipboardSync)
            .apply()
    }

@@ -257,12 +302,17 @@ class SettingsStore(context: Context) {
         * on; both stale keys are abandoned unread. The toggle stays as a per-device escape hatch.
         */
        const val K_LOW_LATENCY = "low_latency_mode_v2"
+        const val K_PRESENT_PRIORITY = "present_priority"
+        const val K_SMOOTH_BUFFER = "smooth_buffer"
        const val K_AUTO_WAKE = "auto_wake_enabled"
        const val K_RUMBLE_ON_PHONE = "rumble_on_phone"
        const val K_SC2_CAPTURE = "sc2_capture"
+        const val K_DS_CAPTURE = "ds_capture"
+        const val K_MOUSE_MODE = "mouse_mode"
+
+        /** Legacy Boolean the [K_MOUSE_MODE] enum replaced — read once for migration, never written. */
        const val K_POINTER_CAPTURE = "pointer_capture"
        const val K_INVERT_SCROLL = "invert_scroll"
-        const val K_CLIPBOARD_SYNC = "clipboard_sync"

        /** Legacy Boolean the enum replaced — read once as the migration default, never written. */
        const val K_TRACKPAD = "trackpad_mode"
@@ -406,21 +456,47 @@ val AUDIO_CHANNEL_OPTIONS = listOf(
    8 to "7.1 Surround",
 )

-/** (stored value, label) for the preferred video codec. `"auto"` = host decides. The `"av1"` row
- * only makes sense on a device with a real AV1 decoder — SettingsScreen filters it out otherwise. */
+/**
+ * (stored value, label) for the preferred video codec — the cross-client table (the Rust
+ * `CODECS`), so a value another client or a profile stored is always representable here.
+ * `"auto"` = host decides.
+ *
+ * Two rows are capability-gated by [codecOptionsFor] rather than dropped from the table: `"av1"`
+ * needs a real `video/av01` decoder on this device, and `"pyrowave"` needs a PyroWave decoder,
+ * which this platform does not have at all (it is a Vulkan-compute codec living in `pf-presenter`;
+ * the JNI client decodes through MediaCodec and never advertises the bit, so preferring it would
+ * be a dead setting that silently resolves to HEVC).
+ */
 val CODEC_OPTIONS = listOf(
    "auto" to "Automatic",
    "hevc" to "HEVC (H.265)",
    "h264" to "H.264 (AVC)",
    "av1" to "AV1",
+    "pyrowave" to "PyroWave (wired LAN)",
 )

+/**
+ * [CODEC_OPTIONS] minus the rows this device can't decode — a preference the client never
+ * advertises is a setting that does nothing. [stored] is the currently persisted value, which is
+ * always kept selectable so the selection can be rendered (the don't-clobber rule: a codec chosen
+ * on another device, or by a newer build, must survive being looked at here).
+ */
+fun codecOptionsFor(stored: String, av1Capable: Boolean): List<Pair<String, String>> =
+    CODEC_OPTIONS.filter { (v, _) ->
+        when (v) {
+            "av1" -> av1Capable || stored == "av1"
+            "pyrowave" -> stored == "pyrowave" // no PyroWave decoder on Android — see above
+            else -> true
+        }
+    }
+
 /** The [Settings.codec] string as a `quic::CODEC_*` preference byte (`0` = auto). H264=1, HEVC=2,
- * AV1=4. */
+ * AV1=4, PyroWave=8 (never decodable here, but the byte is the shared contract). */
 fun Settings.preferredCodec(): Int = when (codec) {
    "h264" -> 1
    "hevc" -> 2
    "av1" -> 4
+    "pyrowave" -> 8
    else -> 0
 }

@@ -449,6 +525,29 @@ val COMPOSITOR_OPTIONS = listOf(
 /** (verbosity, label) for the stats-overlay detail picker. Order = the live 3-finger-tap cycle. */
 val STATS_VERBOSITY_OPTIONS = StatsVerbosity.entries.map { it to it.label }

+/** [Settings.presentPriority] as the wire int `nativeStartVideo` takes (0 = latency, 1 = smooth).
+ * Unrecognized values resolve to latency — same rule as the Apple client. */
+fun Settings.presentPriorityWire(): Int = if (presentPriority == "smooth") 1 else 0
+
+/** (stored value, label) for the presenter-intent picker — the Apple client's table verbatim. */
+val PRESENT_PRIORITY_OPTIONS = listOf(
+    "latency" to "Lowest latency",
+    "smooth" to "Smoothness",
+)
+
+/** (frames, label) for the smoothness-buffer picker; each buffered frame ≈ one refresh interval
+ * of jitter absorbed for one interval of added display latency ([hz] labels the cost). */
+fun smoothBufferOptions(hz: Int): List<Pair<Int, String>> {
+    val periodMs = 1000.0 / maxOf(24, hz)
+    fun cost(frames: Int) = "+%.0f ms".format(periodMs * frames)
+    return listOf(
+        0 to "Automatic",
+        1 to "1 frame (${cost(1)})",
+        2 to "2 frames (${cost(2)})",
+        3 to "3 frames (${cost(3)})",
+    )
+}
+
 /** (mode, label) for the touch-input model. */
 val TOUCH_MODE_OPTIONS = listOf(
    TouchMode.TRACKPAD to "Trackpad",
@@ -456,11 +555,20 @@ val TOUCH_MODE_OPTIONS = listOf(
    TouchMode.TOUCH to "Touch passthrough",
 )

-/** index = GamepadPref wire byte (0=Auto 1=Xbox360 2=DualSense 3=XboxOne 4=DualShock4). */
+/** (mode, label) for the physical-mouse model. */
+val MOUSE_MODE_OPTIONS = MouseMode.entries.map { it to it.label }
+
+/**
+ * (GamepadPref wire byte, label) for the emulated pad the host creates. NOT positional: the wire
+ * bytes are `punktfunk_core::config::GamepadPref` (see `Gamepad.PREF_*`), and Steam Deck is `6`
+ * with `5` (the classic Steam Controller) deliberately not offered — the same subset the desktop
+ * clients' picker shows.
+ */
 val GAMEPAD_OPTIONS = listOf(
-    "Automatic",
-    "Xbox 360",
-    "DualSense",
-    "Xbox One",
-    "DualShock 4",
+    io.unom.punktfunk.kit.Gamepad.PREF_AUTO to "Automatic",
+    io.unom.punktfunk.kit.Gamepad.PREF_XBOX360 to "Xbox 360",
+    io.unom.punktfunk.kit.Gamepad.PREF_DUALSENSE to "DualSense",
+    io.unom.punktfunk.kit.Gamepad.PREF_XBOXONE to "Xbox One",
+    io.unom.punktfunk.kit.Gamepad.PREF_DUALSHOCK4 to "DualShock 4",
+    io.unom.punktfunk.kit.Gamepad.PREF_STEAMDECK to "Steam Deck",
 )
@@ -0,0 +1,187 @@
+package io.unom.punktfunk
+
+import android.content.Context
+import io.unom.punktfunk.kit.NativeBridge
+import io.unom.punktfunk.kit.security.ClientIdentity
+import io.unom.punktfunk.kit.security.KnownHost
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.withContext
+
+/**
+ * The network speed test: measure the path to a host **over the real data plane** — connect, ask
+ * the host to burst filler for two seconds, report goodput and loss, and offer to apply a
+ * recommended bitrate in one tap.
+ *
+ * The measurement is the easy half. The half that was wrong everywhere for a long time is *where
+ * the answer goes*: a measured bitrate belongs in the layer the tested host actually resolves
+ * bitrate from (design/client-settings-profiles.md §5.3). Writing it to the global — the
+ * long-standing behaviour — meant measuring the slow retro box downstairs quietly re-tuned the
+ * desktop too. [SpeedTestTarget] is that decision, and because it depends only on the host it is
+ * known *before* the result lands, so the button can say where it will write.
+ */
+sealed interface SpeedTestTarget {
+    /** No profile in play — the global default, i.e. what has always happened. */
+    data object Global : SpeedTestTarget
+
+    /** The profile this host uses already overrides bitrate, so that override is what it reads. */
+    data class Profile(val profile: StreamProfile) : SpeedTestTarget
+
+    /**
+     * The host uses a profile, but that profile inherits bitrate. Writing either layer is
+     * defensible, so the user gets both buttons rather than us guessing which they meant.
+     */
+    data class Ask(val profile: StreamProfile) : SpeedTestTarget
+
+    companion object {
+        /**
+         * Resolved exactly the way a connect resolves it (see [ProfileStore.resolveFor]): the
+         * one-off pick this test was started from — a pinned card carries one — else the host's
+         * binding. A dangling binding resolves as no profile here too.
+         */
+        fun resolve(
+            host: KnownHost?,
+            oneOffProfile: String?,
+            profiles: ProfileStore,
+        ): SpeedTestTarget {
+            val profile = profiles.resolveFor(host, oneOffProfile) ?: return Global
+            return if (profile.overrides.bitrateKbps != null) Profile(profile) else Ask(profile)
+        }
+    }
+}
+
+/** Where the speed test is: it connects, it measures, then it has an answer or a reason. */
+sealed interface SpeedTestPhase {
+    data object Connecting : SpeedTestPhase
+    data object Measuring : SpeedTestPhase
+    data class Failed(val message: String) : SpeedTestPhase
+
+    /**
+     * [recommendedKbps] is 70 % of the measured throughput — headroom for the FEC overhead and for
+     * the loss a real stream will meet, the same margin the desktop clients apply.
+     */
+    data class Done(
+        val throughputKbps: Int,
+        val lossPct: Double,
+        val recommendedKbps: Int,
+    ) : SpeedTestPhase {
+        val measuredMbps: Double get() = throughputKbps / 1000.0
+        val recommendedMbps: Double get() = recommendedKbps / 1000.0
+    }
+}
+
+/**
+ * Connect to [host]:[port], run one burst, and report. Blocking-ish (it suspends on IO) — call
+ * from a coroutine; [onPhase] is invoked as it progresses so the dialog can narrate.
+ *
+ * The connect is deliberately minimal: 1280×720@60, no launch, host-default bitrate. Nothing here
+ * presents a frame, and asking a host to spin up a 4K encode for a three-second measurement would
+ * be rude to it and slower for us.
+ */
+suspend fun runSpeedTest(
+    context: Context,
+    identity: ClientIdentity,
+    host: String,
+    port: Int,
+    pinHex: String,
+    onPhase: (SpeedTestPhase) -> Unit,
+) {
+    onPhase(SpeedTestPhase.Connecting)
+    val probeSettings = Settings(
+        width = 1280,
+        height = 720,
+        hz = 60,
+        bitrateKbps = 0, // the host's default: this measures the link, not an encoder setting
+        hdrEnabled = false,
+        audioChannels = 2,
+    )
+    val handle = connectToHost(
+        context, probeSettings, identity, host, port, pinHex,
+        launch = null, timeoutMs = SPEED_TEST_CONNECT_TIMEOUT_MS,
+    )
+    if (handle == 0L) {
+        onPhase(
+            SpeedTestPhase.Failed(
+                ConnectErrors.connectMessage(NativeBridge.nativeTakeLastError(), requestAccess = false),
+            ),
+        )
+        return
+    }
+    try {
+        onPhase(SpeedTestPhase.Measuring)
+        if (!NativeBridge.nativeSpeedTest(handle, TARGET_KBPS, BURST_MS)) {
+            onPhase(SpeedTestPhase.Failed("The host wouldn't start a measurement."))
+            return
+        }
+        var waited = 0
+        while (waited < POLL_BUDGET_MS) {
+            delay(POLL_INTERVAL_MS.toLong())
+            waited += POLL_INTERVAL_MS
+            val r = NativeBridge.nativeProbeResult(handle)
+            if (r == null || r.size < 3) {
+                onPhase(SpeedTestPhase.Failed("The session ended before the measurement finished."))
+                return
+            }
+            if (r[0] == 0.0) continue
+            // Let the last UDP shards land before tearing the session down, or the tail of the
+            // burst is counted as loss that never happened.
+            delay(SETTLE_MS)
+            val settled = NativeBridge.nativeProbeResult(handle) ?: r
+            val kbps = settled[1].toInt()
+            onPhase(
+                SpeedTestPhase.Done(
+                    throughputKbps = kbps,
+                    lossPct = settled[2],
+                    // Integer arithmetic in this order (not `* 0.7`) so the recommendation matches
+                    // the desktop clients' to the kilobit.
+                    recommendedKbps = kbps / 10 * 7,
+                ),
+            )
+            return
+        }
+        onPhase(SpeedTestPhase.Failed("The measurement timed out."))
+    } finally {
+        withContext(Dispatchers.IO) { NativeBridge.nativeClose(handle) }
+    }
+}
+
+/**
+ * Write a measured bitrate into the layer [target] names. [toProfile] picks the side of a
+ * [SpeedTestTarget.Ask]; it is ignored for the other targets, which have only one answer. Returns
+ * a human phrase naming where it went, for the confirmation.
+ */
+fun applySpeedTestResult(
+    kbps: Int,
+    target: SpeedTestTarget,
+    toProfile: Boolean,
+    profiles: ProfileStore,
+    settings: Settings,
+    onGlobalChange: (Settings) -> Unit,
+): String {
+    val profile = when (target) {
+        is SpeedTestTarget.Profile -> target.profile
+        is SpeedTestTarget.Ask -> target.profile.takeIf { toProfile }
+        SpeedTestTarget.Global -> null
+    }
+    return if (profile == null) {
+        onGlobalChange(settings.copy(bitrateKbps = kbps))
+        "the default bitrate"
+    } else {
+        // Only the bitrate moves — a speed test has nothing to say about the rest of the profile.
+        // Re-read rather than trusting the copy this dialog was opened with, so a rename or another
+        // edit in between isn't clobbered.
+        val live = profiles.byId(profile.id) ?: profile
+        profiles.save(live.copy(overrides = live.overrides.copy(bitrateKbps = kbps)))
+        "“${live.name}”"
+    }
+}
+
+/** Ask for far more than any real link can carry, so the link is what limits the answer. */
+private const val TARGET_KBPS = 3_000_000
+
+/** Long enough to fill the pipe and settle, short enough not to interrupt anyone for long. */
+private const val BURST_MS = 2_000
+private const val POLL_INTERVAL_MS = 250
+private const val POLL_BUDGET_MS = 10_000
+private const val SETTLE_MS = 400L
+private const val SPEED_TEST_CONNECT_TIMEOUT_MS = 15_000
@@ -40,12 +40,26 @@ internal fun StatsOverlay(
    verbosity: StatsVerbosity,
    decoderLabel: String = "",
    codecLabel: String = "",
+    /**
+     * The settings profile this session resolved, appended to the first line when there is one —
+     * the in-stream answer to "which profile am I on?", as on the other clients. Absent (the
+     * common case: no profile) the line is exactly what it always was.
+     */
+    profileName: String? = null,
+    /**
+     * The panel's live refresh rate (0 = unknown). Shown as a warning on the first line whenever
+     * it sits below the stream rate — the "an OEM governor ignored the mode pin" tell, which
+     * otherwise reads as inexplicable judder and an extra refresh of latency.
+     */
+    panelHz: Float = 0f,
    modifier: Modifier = Modifier,
 ) {
    if (verbosity == StatsVerbosity.OFF || s.size < 10) return
    val w = s[6].toInt()
    val h = s[7].toInt()
    val hz = s[8].toInt()
+    val panelBelowStream = panelHz > 0f && hz > 0 && panelHz + 1f < hz.toFloat()
+    val panelTag = if (panelBelowStream) "   ⚠ panel ${panelHz.roundToInt()} Hz" else ""
    val latValid = s[4] != 0.0
    val skew = s[5] != 0.0
    val lost = s[9].toLong()
@@ -56,13 +70,17 @@ internal fun StatsOverlay(
            .background(Color.Black.copy(alpha = 0.45f), RoundedCornerShape(6.dp))
            .padding(horizontal = 8.dp, vertical = 4.dp),
    ) {
+        val profileTag = profileName?.let { "   · $it" }.orEmpty()
        // Compact: everything the glance-value needs on one line, nothing else.
        if (verbosity == StatsVerbosity.COMPACT) {
-            statLine(compactLine(s, latValid), Color.White)
+            statLine(compactLine(s, latValid) + profileTag + panelTag, Color.White)
            return@Column
        }

-        statLine("$w×$h@$hz   ${s[0].roundToInt()} fps   ${"%.1f".format(s[1])} Mb/s", Color.White)
+        statLine(
+            "$w×$h@$hz   ${s[0].roundToInt()} fps   ${"%.1f".format(s[1])} Mb/s$profileTag$panelTag",
+            Color.White,
+        )
        if (detailed && decoderLabel.isNotEmpty()) {
            statLine(decoderLabel, Color(0xFFB0D0FF))
        }
@@ -94,8 +112,27 @@ internal fun StatsOverlay(
                } else {
                    "host+network ${"%.1f".format(s[14])}"
                }
-                val displayTerm = if (dispValid) " + display ${"%.1f".format(s[23])}" else ""
-                statLine("= $hostTerms + decode ${"%.1f".format(s[15])}$displayTerm", Color.White)
+                // Timeline-presenter split (s[26]/s[27], when s[29] flags it active): the display
+                // term decomposes into pace (store + glass budget) + latch (SurfaceFlinger), and
+                // s[28] is the on-glass confirm count — presents ≪ fps means the presenter is
+                // dropping/serializing, an fps deficit is upstream.
+                val split = s.size >= 30 && s[29] != 0.0 && (s[26] > 0 || s[27] > 0)
+                val displayTerm = when {
+                    dispValid && split ->
+                        " + display ${"%.1f".format(s[23])} " +
+                            "(pace ${"%.1f".format(s[26])} + latch ${"%.1f".format(s[27])})"
+                    dispValid -> " + display ${"%.1f".format(s[23])}"
+                    else -> ""
+                }
+                val presents = if (s.size >= 30 && s[29] != 0.0) {
+                    "   · presents ${s[28].toInt()}"
+                } else {
+                    ""
+                }
+                statLine(
+                    "= $hostTerms + decode ${"%.1f".format(s[15])}$displayTerm$presents",
+                    Color.White,
+                )
            }
        }
        counterLine(s, lost)?.let { statLine(it, Color(0xFFFFB0B0)) }
@@ -26,6 +26,7 @@ import android.widget.Toast
 import androidx.activity.compose.BackHandler
 import androidx.compose.foundation.background
 import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.aspectRatio
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
@@ -53,20 +54,39 @@ import androidx.core.view.WindowInsetsControllerCompat
 import androidx.lifecycle.Lifecycle
 import androidx.lifecycle.LifecycleEventObserver
 import androidx.lifecycle.LifecycleOwner
+import io.unom.punktfunk.kit.DsCapture
 import io.unom.punktfunk.kit.GamepadFeedback
 import io.unom.punktfunk.kit.GamepadRouter
 import io.unom.punktfunk.kit.deviceBodyVibrator
 import io.unom.punktfunk.kit.NativeBridge
 import io.unom.punktfunk.kit.Sc2Capture
 import io.unom.punktfunk.kit.VideoDecoders
+import io.unom.punktfunk.models.ActiveSession
 import java.util.concurrent.atomic.AtomicBoolean
+import kotlin.math.roundToInt
 import kotlinx.coroutines.delay

+/**
+ * The immersive stream. Everything it reads about the session comes from [session] — the settings
+ * the connect actually resolved (globals, or a profile's overrides on top of them) and the HOST's
+ * clipboard decision — rather than from a fresh `SettingsStore` load, which could disagree with
+ * the connect that produced this handle.
+ */
@Composable
-fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
+fun StreamScreen(session: ActiveSession, onDisconnect: () -> Unit) {
+    val handle = session.handle
+    val initialSettings = session.settings
+    val micEnabled = initialSettings.micEnabled
    val context = LocalContext.current
    val activity = context as? MainActivity
+    // The View hosting this composition — the one that receives the stream's touch/pointer events
+    // (the gesture Box below is a Compose node inside it), so it is where unbuffered dispatch is
+    // requested.
+    val composeView = androidx.compose.ui.platform.LocalView.current
    val window = activity?.window
+    // The negotiated stream refresh, known from the handshake (0 = unknown / older native lib) —
+    // drives the panel mode pin, the render-rate vote, and the presenter's latch grid.
+    val streamHz = remember(handle) { NativeBridge.nativeVideoSize(handle)?.getOrNull(2) ?: 0 }
    val controller = remember(window) {
        window?.let { WindowCompat.getInsetsController(it, it.decorView) }
    }
@@ -85,10 +105,12 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
    // Settings. The tier only changes how many lines `StatsOverlay` draws — switching between the
    // visible tiers keeps sampling running (the effect keys on `statsOn`, not the tier) so it never
    // blanks the numbers for a poll interval.
-    val initialSettings = remember { SettingsStore(context).load() }
    var stats by remember { mutableStateOf<DoubleArray?>(null) }
    var decoderLabel by remember { mutableStateOf("") }
    var codecLabel by remember { mutableStateOf("") }
+    // The panel's LIVE refresh rate, re-read each poll — the HUD flags a session whose panel sits
+    // below the stream rate (an OEM governor that ignored both the mode pin and the surface hint).
+    var panelHz by remember { mutableStateOf(0f) }
    var statsVerbosity by remember { mutableStateOf(initialSettings.statsVerbosity) }
    val statsOn = statsVerbosity != StatsVerbosity.OFF
    // Touch model is fixed per session (re-keys the gesture handler below if it ever changes).
@@ -110,6 +132,7 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
            while (true) {
                delay(1000)
                stats = NativeBridge.nativeVideoStats(handle)
+                panelHz = runCatching { context.display }.getOrNull()?.refreshRate ?: 0f
                // The decoder is fixed for the session; fetch its label once it's resolved.
                if (decoderLabel.isEmpty()) decoderLabel = NativeBridge.nativeVideoDecoderLabel(handle)
            }
@@ -188,6 +211,11 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
    // below so the capture callbacks can reach the view once it exists.
    var keyCapture by remember { mutableStateOf<KeyCaptureView?>(null) }

+    // The video SurfaceView, hoisted for the same reason: the pointer paths built below map WINDOW
+    // coordinates onto the picture, and with a letterboxed stream that rect is the video's, not the
+    // panel's. Set when the view is created.
+    var videoView by remember { mutableStateOf<SurfaceView?>(null) }
+
    DisposableEffect(handle) {
        window?.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
        wifiLocks.forEach { lock ->
@@ -211,13 +239,39 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
        val priorSoftInput = window?.attributes?.softInputMode
            ?: WindowManager.LayoutParams.SOFT_INPUT_ADJUST_UNSPECIFIED
        window?.setSoftInputMode(WindowManager.LayoutParams.SOFT_INPUT_ADJUST_NOTHING)
+        // Draw under the display cutout, explicitly. Android 15's SDK-35 edge-to-edge enforcement
+        // makes ALWAYS the immersive default, but pre-15 devices letterbox the notch as a dead
+        // black bar unless asked — and the stream's own letterbox is black anyway, so the cutout
+        // region can never show anything wrong. Captured + restored like the rest of the window
+        // state so the menus keep their platform-default behaviour.
+        val priorCutout = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            window?.attributes?.layoutInDisplayCutoutMode
+        } else {
+            null
+        }
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            window?.let { w ->
+                w.attributes = w.attributes.apply {
+                    layoutInDisplayCutoutMode =
+                        WindowManager.LayoutParams.LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS
+                }
+            }
+        }
        // 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.
+        //
+        // COMPACT devices only (sw < 600 dp): on tablets/foldables/desktop windows the lock is a
+        // large-display anti-pattern (Play flags it; Android 16+ ignores it there outright), and the
+        // stream doesn't need it — the aspect-ratio letterbox renders correctly in any orientation,
+        // the lock is purely a phone-ergonomics choice.
+        val compactDevice = context.resources.configuration.smallestScreenWidthDp < 600
        val priorOrientation = activity?.requestedOrientation
-        activity?.requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE
+        if (compactDevice) {
+            activity?.requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE
+        }
        activity?.streamHandle = handle // route hardware keys to this session
        // Multi-controller router: a stable wire pad index per connected controller, per-device axis
        // state, Arrival/Remove on hot-plug, and feedback routed back by pad index. Forwards every
@@ -246,8 +300,16 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
        val mouse = MouseForwarder(
            handle,
            invertScroll = initialSettings.invertScroll,
-            captureWanted = initialSettings.pointerCapture,
-            surfaceSize = { (decor?.width ?: 0) to (decor?.height ?: 0) },
+            captureWanted = initialSettings.mouseMode == MouseMode.CAPTURE,
+            // The picture's rect in window coordinates (see MouseForwarder.videoRect) — read live,
+            // so it is right from the frame the SurfaceView is first laid out.
+            videoRect = {
+                videoView?.takeIf { it.width > 0 && it.height > 0 }?.let { v ->
+                    val loc = IntArray(2)
+                    v.getLocationInWindow(loc)
+                    android.graphics.Rect(loc[0], loc[1], loc[0] + v.width, loc[1] + v.height)
+                }
+            },
        )
        mouse.onRequestCapture = {
            // The grab needs the (focusable) capture view: focus it, then ask. Posted so a
@@ -266,7 +328,7 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
        val remote = if (isTv) {
            RemotePointer(
                handle,
-                surfaceWidth = { decor?.width ?: 1920 },
+                surfaceWidth = { videoView?.width?.takeIf { it > 0 } ?: decor?.width ?: 1920 },
                onActiveChanged = { on -> remotePointerOn = on },
                onKeyboardToggle = { keyCapture?.let { it.setImeVisible(!it.imeShown) } },
            )
@@ -276,12 +338,35 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
        activity?.remotePointer = remote
        // Shared clipboard (text v1): only when the user setting is on AND the host has a
        // working clipboard service. Protocol-level opt-in + the poll thread live in the sync.
-        val clip = if (initialSettings.clipboardSync && NativeBridge.nativeClipSupported(handle)) {
+        val clip = if (session.clipboardSync && NativeBridge.nativeClipSupported(handle)) {
            ClipboardSync(context, handle).also { it.start() }
        } else {
            null
        }
-        activity?.setConsoleHighRefreshRate(false) // let the decoder's setFrameRate pick the panel rate
+        // Pin the panel to the stream's refresh (exact / multiple) for the session. The decoder's
+        // own ANativeWindow_setFrameRate hint still aligns vsync, but it is advisory — some OEM
+        // refresh governors ignore it outright and would leave a 120 Hz session on a 60/90 Hz
+        // panel. TV boxes skip the pin: the native side actively drives the HDMI mode there.
+        if (isTv) {
+            activity?.setConsoleHighRefreshRate(false) // the decoder's HDMI mode switch governs
+        } else {
+            activity?.setStreamDisplayMode(streamHz)
+        }
+        // Touch/pointer events are vsync-batched by default — up to a frame of input latency the
+        // stream shouldn't pay. Unbuffered dispatch delivers them the moment the kernel does.
+        // Undone by passing 0 on the way out (API 30+).
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            composeView.requestUnbufferedDispatch(android.view.InputDevice.SOURCE_CLASS_POINTER)
+        }
+        // Vote the app's RENDER rate up to the stream's (API 35+). The mode pin above governs the
+        // panel, but the platform separately down-rates a quiet app's choreographer stream
+        // (frame-rate categories: a non-animating UI reads as "normal" = 60) — observed on-glass
+        // as 16.6 ms vsync callbacks on a 120 Hz panel, which would pace the presenter at half
+        // rate. The native side also subdivides onto the panel grid, so this vote is the belt to
+        // that braces. Reset to no-preference on the way out.
+        if (Build.VERSION.SDK_INT >= 35 && streamHz > 0) {
+            composeView.requestedFrameRate = streamHz.toFloat()
+        }
        // Host→client feedback (rumble + DualSense lightbar/LEDs), routed to each controller by pad
        // index via the router; poll threads stopped + joined before the router is released and the
        // session closed. "Rumble on this phone" (opt-in) additionally mirrors controller 1's
@@ -344,13 +429,59 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
                }
            }
        }
+        // Sony pad capture (DualSense / Edge / DualShock 4, opt-out): claim a USB-connected
+        // pad's HID interface and drive it directly — rumble without a kernel force-feedback
+        // driver, plus adaptive triggers, lightbar, player LEDs and gyro/touchpad, none of which
+        // the InputDevice path can render (no platform API for any of them). Uncaptured (toggle
+        // off / permission denied / Bluetooth) the pad stays on the ordinary InputDevice path —
+        // the automatic fallback. Host feedback routes back through feedback.sink; the claim
+        // frees the pad's InputDevice slot itself (see DsCapture.startUsb), so the wire index
+        // hands over deterministically.
+        val ds = if (initialSettings.dsCapture) DsCapture(context, router) else null
+        var dsUsbReceiver: BroadcastReceiver? = null
+        if (ds != null) {
+            feedback.sink = ds
+            val usbManager = context.getSystemService(Context.USB_SERVICE) as UsbManager
+            val usbDev = ds.findUsbDevice()
+            when {
+                usbDev != null && usbManager.hasPermission(usbDev) -> ds.startUsb(usbDev)
+                usbDev != null -> {
+                    // One-time system dialog; capture engages on grant (Android remembers the
+                    // grant for as long as the device stays attached).
+                    val action = "io.unom.punktfunk.DS_USB_PERMISSION"
+                    val receiver = object : BroadcastReceiver() {
+                        override fun onReceive(c: Context?, intent: Intent?) {
+                            if (intent?.action != action) return
+                            val ok = intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)
+                            if (ok) ds.startUsb(usbDev) else Log.i("punktfunk", "Sony pad USB permission denied")
+                        }
+                    }
+                    dsUsbReceiver = receiver
+                    ContextCompat.registerReceiver(
+                        context, receiver, IntentFilter(action), ContextCompat.RECEIVER_NOT_EXPORTED,
+                    )
+                    usbManager.requestPermission(
+                        usbDev,
+                        PendingIntent.getBroadcast(
+                            context, 2, // requestCode 2 — 0/1 are the SC2 stream/menu grants
+                            Intent(action).setPackage(context.packageName),
+                            // MUTABLE: the USB stack appends the grant extras to this intent.
+                            PendingIntent.FLAG_MUTABLE,
+                        ),
+                    )
+                }
+            }
+        }
        onDispose {
            closed.set(true) // from here the handle gets freed; surfaceDestroyed must not touch it
            clip?.stop() // stop + join the clipboard poll thread BEFORE the handle is freed
            feedback.onHidRaw = null
+            feedback.sink = null
            feedback.stop() // stop + join the poll threads BEFORE the router is released / handle freed
            sc2UsbReceiver?.let { runCatching { context.unregisterReceiver(it) } }
            sc2?.stop() // release the USB/BLE link + free the wire slot (host tears the pad down)
+            dsUsbReceiver?.let { runCatching { context.unregisterReceiver(it) } }
+            ds?.stop() // rumble-stop on the physical pad + release the USB link + free the wire slot
            router.onExitArmed = null // don't poke Compose state from release()'s disarm while tearing down
            router.release() // flush every slot (nothing sticks host-side) + drop the hot-plug listener
            activity?.gamepadRouter = null
@@ -365,8 +496,19 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
            // Back in the menus: the SC2 (if present) resumes driving the console UI.
            activity?.startSc2MenuNav()
            activity?.setConsoleHighRefreshRate(true) // back to the console UI's max refresh
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+                composeView.requestUnbufferedDispatch(0) // back to ordinary batched dispatch
+            }
+            if (Build.VERSION.SDK_INT >= 35) {
+                composeView.requestedFrameRate = View.REQUESTED_FRAME_RATE_CATEGORY_DEFAULT
+            }
            controller?.hide(WindowInsetsCompat.Type.ime()) // drop any keyboard left showing
            window?.setSoftInputMode(priorSoftInput)
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R && priorCutout != null) {
+                window?.let { w ->
+                    w.attributes = w.attributes.apply { layoutInDisplayCutoutMode = priorCutout }
+                }
+            }
            controller?.show(WindowInsetsCompat.Type.systemBars())
            window?.clearFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
            if (lowLatencyMode && Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
@@ -414,11 +556,33 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
        activity?.mouseForwarder?.engageFromStart()
    }

-    Box(modifier = Modifier.fillMaxSize()) {
+    // Fit the picture to the stream's own aspect, letterboxing the rest in black. MediaCodec scales
+    // whatever it decodes to fill the Surface it renders into, so a 16:9 stream on a 20:9 panel came
+    // out stretched — the surface has to carry the aspect, because nothing downstream of it can.
+    // The mode is the negotiated one (known from the handshake, before the first frame); 0/absent —
+    // an older native lib — falls back to filling, i.e. exactly the previous behaviour.
+    val videoAspect = remember(handle) {
+        val size = NativeBridge.nativeVideoSize(handle)
+        val w = size?.getOrNull(0) ?: 0
+        val h = size?.getOrNull(1) ?: 0
+        if (w > 0 && h > 0) w.toFloat() / h.toFloat() else 0f
+    }
+    Box(modifier = Modifier.fillMaxSize().background(Color.Black)) {
+        // One rect for the picture AND for the input that lands on it. Every absolute mapping —
+        // direct-pointer touch, multi-touch passthrough, the pen lane — measures against the size of
+        // the node it sits on, so putting the gesture layer on this same rect keeps all three correct
+        // by construction rather than by threading an offset through each of them. The cost is that
+        // trackpad swipes starting inside a letterbox bar don't register; the picture is the surface.
+        val videoFit = if (videoAspect > 0f) {
+            Modifier.align(Alignment.Center).aspectRatio(videoAspect)
+        } else {
+            Modifier.fillMaxSize()
+        }
        AndroidView(
-            modifier = Modifier.fillMaxSize(),
+            modifier = videoFit,
            factory = { ctx ->
                SurfaceView(ctx).apply {
+                    videoView = this
                    holder.addCallback(object : SurfaceHolder.Callback {
                        override fun surfaceCreated(holder: SurfaceHolder) {
                            // Low-latency mode: rank MediaCodecList decoders for the negotiated
@@ -435,6 +599,14 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
                                lowLatencyMode,
                                choice?.lowLatencyFeature ?: false,
                                isTv,
+                                initialSettings.presentPriorityWire(),
+                                initialSettings.smoothBuffer,
+                                // The panel's own refresh — from the mode TABLE (streamPanelFps),
+                                // because display.refreshRate reports a per-uid override, not the
+                                // panel. Fallback: the (possibly lying) live rate.
+                                activity?.streamPanelFps(streamHz)?.takeIf { it > 0 }
+                                    ?: (runCatching { context.display }.getOrNull()?.refreshRate ?: 0f)
+                                        .roundToInt(),
                            )
                            NativeBridge.nativeStartAudio(handle, lowLatencyMode)
                            if (micWanted) NativeBridge.nativeStartMic(handle)
@@ -461,7 +633,11 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
        // BEFORE the transparent gesture layer below, so it shows through and never eats touches.
        if (statsOn) {
            stats?.let {
-                StatsOverlay(it, statsVerbosity, decoderLabel, codecLabel, Modifier.align(Alignment.TopStart).padding(12.dp))
+                StatsOverlay(
+                    it, statsVerbosity, decoderLabel, codecLabel, session.profileName,
+                    panelHz,
+                    Modifier.align(Alignment.TopStart).padding(12.dp),
+                )
            }
        }
        // "Hold to quit" hint while the gamepad exit chord is armed — the exit debounces on a ~1 s
@@ -505,7 +681,7 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
            LaunchedEffect(stylus) { stylus.heartbeatLoop() }
        }
        Box(
-            Modifier.fillMaxSize().pointerInput(handle, touchMode) {
+            videoFit.pointerInput(handle, touchMode) {
                when (touchMode) {
                    TouchMode.TOUCH -> streamTouchPassthrough(handle, stylus)
                    else -> streamTouchInput(
@@ -9,16 +9,22 @@ 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.heightIn
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
 import androidx.compose.foundation.layout.width
 import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.foundation.shape.RoundedCornerShape
 import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Key
+import androidx.compose.material.icons.filled.Lock
+import androidx.compose.material.icons.filled.LockOpen
 import androidx.compose.material.icons.filled.MoreVert
 import androidx.compose.material3.CardDefaults
 import androidx.compose.material3.DropdownMenu
 import androidx.compose.material3.DropdownMenuItem
 import androidx.compose.material3.ElevatedCard
+import androidx.compose.material3.HorizontalDivider
 import androidx.compose.material3.Icon
 import androidx.compose.material3.IconButton
 import androidx.compose.material3.MaterialTheme
@@ -32,6 +38,9 @@ import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.clip
 import androidx.compose.ui.focus.onFocusChanged
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.semantics.contentDescription
+import androidx.compose.ui.semantics.semantics
 import androidx.compose.ui.text.style.TextAlign
 import androidx.compose.ui.text.style.TextOverflow
 import androidx.compose.ui.unit.dp
@@ -49,8 +58,25 @@ fun SectionLabel(text: String) {
 }

 /**
- * A host as an Apple-style card: a colored letter-avatar, name + address, a trust pill, and (for
- * saved hosts) an overflow menu with Rename / Forget. Tapping the card connects.
+ * One row of a host card's overflow menu. [startsSection] draws a divider above it, which is how
+ * the profile actions ("Connect with: …", "Pin as card: …") stay legible next to the host actions
+ * in one flat menu — Compose has no submenus, and the Windows client made the same call.
+ */
+data class HostMenuItem(
+    val label: String,
+    val startsSection: Boolean = false,
+    val onClick: () -> Unit,
+)
+
+/**
+ * A host as an Apple-style card: a colored avatar carrying the host's OS mark (its initial when we
+ * don't know the OS), name + address, a trust pill, and (for saved hosts) an overflow menu with
+ * Wake / Edit / Forget plus whatever [menuItems] adds. Tapping the card connects.
+ *
+ * [profileLabel] names the settings profile this card connects with. On a host's own card that is
+ * its default binding, drawn as a quiet chip — the card says what a tap will do. On a **pinned
+ * card** ([profileProminent]) the host name is still the title, but the profile is the loud part,
+ * because the pin exists to make that one combination a single tap.
 */
@Composable
 fun HostCard(
@@ -58,11 +84,25 @@ fun HostCard(
    address: String,
    status: HostStatus,
    online: Boolean = false,
+    /** OS-identity chain (mDNS `os` TXT / stored), drawn as the avatar's mark. "" = the initial. */
+    os: String = "",
    enabled: Boolean,
    onConnect: () -> Unit,
    onForget: (() -> Unit)?,
    onEdit: (() -> Unit)? = null,
    onWake: (() -> Unit)? = null,
+    profileLabel: String? = null,
+    profileProminent: Boolean = false,
+    accent: Color? = null,
+    menuItems: List<HostMenuItem> = emptyList(),
+    /**
+     * Keep the profile chip's space even on a card that has no profile. `LazyVerticalGrid` sizes a
+     * row to its tallest item but does NOT stretch the others, so a card that grew a chip would
+     * leave its neighbour visibly short — a row of cards stepping up and down reads as broken
+     * layout. The caller passes true when ANY card in that section carries a chip, so a user with
+     * no profiles never pays for the slot.
+     */
+    reserveProfileSlot: Boolean = false,
 ) {
    // 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.
@@ -89,8 +129,8 @@ fun HostCard(
                    .padding(16.dp),
                horizontalAlignment = Alignment.CenterHorizontally,
            ) {
-                HostAvatar(name)
-                Spacer(Modifier.height(12.dp))
+                HostAvatar(name, online, os)
+                Spacer(Modifier.height(10.dp))
                Text(
                    name,
                    style = MaterialTheme.typography.titleMedium,
@@ -106,17 +146,27 @@ fun HostCard(
                    overflow = TextOverflow.Ellipsis,
                    textAlign = TextAlign.Center,
                )
-                Spacer(Modifier.height(12.dp))
-                Row(
-                    verticalAlignment = Alignment.CenterVertically,
-                    horizontalArrangement = Arrangement.spacedBy(12.dp),
-                ) {
-                    PresencePill(online)
-                    StatusPill(status)
+                if (profileLabel != null || reserveProfileSlot) {
+                    Spacer(Modifier.height(10.dp))
+                    Box(
+                        Modifier.heightIn(min = PROFILE_CHIP_SLOT),
+                        contentAlignment = Alignment.Center,
+                    ) {
+                        if (profileLabel != null) {
+                            ProfileChip(profileLabel, accent, prominent = profileProminent)
+                        }
+                    }
                }
            }

-            if (onForget != null || onEdit != null || onWake != null) {
+            // Trust state lives in the free top-left corner, mirroring the overflow on the right —
+            // it costs no height, and it is a state you glance at rather than read. The label is
+            // still there for TalkBack, and the trust DECISION is made in a dialog that spells all
+            // of this out; on the card it only has to say "this one is settled" vs "this one will
+            // ask something of you".
+            TrustBadge(status, Modifier.align(Alignment.TopStart))
+
+            if (onForget != null || onEdit != null || onWake != null || menuItems.isNotEmpty()) {
                var menu by remember { mutableStateOf(false) }
                Box(modifier = Modifier.align(Alignment.TopEnd)) {
                    IconButton(enabled = enabled, onClick = { menu = true }) {
@@ -155,6 +205,16 @@ fun HostCard(
                                },
                            )
                        }
+                        menuItems.forEach { item ->
+                            if (item.startsSection) HorizontalDivider()
+                            DropdownMenuItem(
+                                text = { Text(item.label) },
+                                onClick = {
+                                    menu = false
+                                    item.onClick()
+                                },
+                            )
+                        }
                    }
                }
            }
@@ -162,59 +222,136 @@ fun HostCard(
    }
 }

-/** A circular avatar with the host's first letter (Apple-contact style). */
+/**
+ * The profile a card connects with. Quiet on a bound host's own card (it is a note about what a tap
+ * does); filled and tinted on a pinned card, where the profile IS the reason the card exists — the
+ * accent field the schema reserves earns its keep here.
+ */
@Composable
-fun HostAvatar(name: String) {
-    val letter = name.trim().firstOrNull()?.uppercaseChar()?.toString() ?: "?"
-    Box(
+private fun ProfileChip(label: String, accent: Color?, prominent: Boolean) {
+    val tint = accent ?: MaterialTheme.colorScheme.primary
+    Row(
        modifier = Modifier
-            .size(44.dp)
-            .clip(CircleShape)
-            .background(MaterialTheme.colorScheme.primaryContainer),
-        contentAlignment = Alignment.Center,
+            .clip(RoundedCornerShape(50))
+            .background(tint.copy(alpha = if (prominent) 0.24f else 0.12f))
+            .padding(horizontal = 10.dp, vertical = 4.dp),
+        verticalAlignment = Alignment.CenterVertically,
    ) {
+        Box(Modifier.size(7.dp).clip(CircleShape).background(tint))
+        Spacer(Modifier.width(6.dp))
        Text(
-            letter,
-            style = MaterialTheme.typography.titleMedium,
-            color = MaterialTheme.colorScheme.onPrimaryContainer,
+            label,
+            style = if (prominent) {
+                MaterialTheme.typography.labelLarge
+            } else {
+                MaterialTheme.typography.labelMedium
+            },
+            color = tint,
+            maxLines = 1,
+            overflow = TextOverflow.Ellipsis,
        )
    }
 }

 /**
- * A small dot + label for live presence: green Online when the host advertises on mDNS OR answers
- * the reachability probe (so a routed/VPN host that never advertises still reads Online), dimmed
- * Offline otherwise.
+ * Reserved height for the profile chip — the one part of a card that varies. `LazyVerticalGrid`
+ * sizes a row to its tallest item and does NOT stretch the others, so a card that grew a chip its
+ * neighbour lacks would leave the row stepping up and down.
+ *
+ * `heightIn(min =)`, not a fixed height: at a large accessibility font scale the chip must be
+ * allowed to grow rather than clip, and the reservation is sized with room to spare because the
+ * equal-height guarantee only holds while every card fits INSIDE it.
+ */
+private val PROFILE_CHIP_SLOT = 26.dp
+
+/** Live presence, on any dynamic scheme: green reads as "up" to everyone, and Material You's
+ * primary might be any hue at all — including a green that would then mean nothing. */
+private val PRESENCE_ONLINE = Color(0xFF4ADE80)
+
+/**
+ * The host's avatar (Apple-contact style) with its presence as a dot on the corner — the idiom
+ * every contact list already uses, and one fewer labelled badge on a small card. It carries the
+ * host's OS mark when [os] resolves to one we ship, and the host's initial otherwise.
+ *
+ * [online] is true when the host advertises on mDNS OR answers the reachability probe, so a
+ * routed/VPN host that never advertises still reads as up. Online is a FILLED green dot, offline a
+ * hollow grey ring: the difference is a shape as well as a colour, so it survives both a
+ * colour-blind reader and a screenshot in greyscale. TalkBack gets the word either way.
 */
@Composable
-fun PresencePill(online: Boolean) {
-    val color =
-        if (online) MaterialTheme.colorScheme.primary
-        else MaterialTheme.colorScheme.onSurfaceVariant
-    Row(verticalAlignment = Alignment.CenterVertically) {
-        Box(Modifier.size(8.dp).clip(CircleShape).background(color))
-        Spacer(Modifier.width(6.dp))
-        Text(
-            if (online) "Online" else "Offline",
-            style = MaterialTheme.typography.labelMedium,
-            color = color,
+fun HostAvatar(name: String, online: Boolean = false, os: String = "") {
+    val letter = name.trim().firstOrNull()?.uppercaseChar()?.toString() ?: "?"
+    val cardColor = CardDefaults.elevatedCardColors().containerColor
+    val osIcon = resolveOsIcon(os)
+    Box {
+        Box(
+            modifier = Modifier
+                .size(44.dp)
+                .clip(CircleShape)
+                .background(MaterialTheme.colorScheme.primaryContainer),
+            contentAlignment = Alignment.Center,
+        ) {
+            // The OS mark IS the avatar when we know the OS — it identifies the machine better than
+            // the initial ever did, and it's the same circle, so a card whose host advertises no OS
+            // (or one we ship no mark for) keeps the letter and the row still reads as one set.
+            if (osIcon != null) {
+                Icon(
+                    osIcon,
+                    contentDescription = os,
+                    modifier = Modifier.size(24.dp),
+                    tint = MaterialTheme.colorScheme.onPrimaryContainer,
+                )
+            } else {
+                Text(
+                    letter,
+                    style = MaterialTheme.typography.titleMedium,
+                    color = MaterialTheme.colorScheme.onPrimaryContainer,
+                )
+            }
+        }
+        Box(
+            modifier = Modifier
+                .align(Alignment.BottomEnd)
+                .size(13.dp)
+                .clip(CircleShape)
+                // A ring in the card's own colour is what makes the dot read as sitting ON the
+                // avatar rather than beside it.
+                .background(cardColor)
+                .padding(2.dp)
+                .clip(CircleShape)
+                .then(
+                    if (online) {
+                        Modifier.background(PRESENCE_ONLINE)
+                    } else {
+                        Modifier
+                            .background(cardColor)
+                            .border(1.5.dp, MaterialTheme.colorScheme.onSurfaceVariant, CircleShape)
+                    },
+                )
+                .semantics { contentDescription = if (online) "Online" else "Offline" },
        )
    }
 }

-/** A small colored dot + label for the host's trust state. */
+/**
+ * The host's trust state as a corner glyph: locked (paired — nothing more to do), a key (this host
+ * will ask for a PIN), or an open lock (trust-on-first-use, the weakest of the three). The full
+ * label rides along as the content description, and the dialogs that actually make the decision
+ * spell it out in sentences.
+ */
@Composable
-fun StatusPill(status: HostStatus) {
-    val color = when (status) {
-        HostStatus.PAIRED -> MaterialTheme.colorScheme.primary
-        HostStatus.PAIRING -> MaterialTheme.colorScheme.tertiary
-        HostStatus.TOFU -> MaterialTheme.colorScheme.onSurfaceVariant
-    }
-    Row(verticalAlignment = Alignment.CenterVertically) {
-        Box(Modifier.size(8.dp).clip(CircleShape).background(color))
-        Spacer(Modifier.width(6.dp))
-        Text(status.label, style = MaterialTheme.typography.labelMedium, color = color)
+private fun TrustBadge(status: HostStatus, modifier: Modifier = Modifier) {
+    val (icon, tint) = when (status) {
+        HostStatus.PAIRED -> Icons.Filled.Lock to MaterialTheme.colorScheme.primary
+        HostStatus.PAIRING -> Icons.Filled.Key to MaterialTheme.colorScheme.tertiary
+        HostStatus.TOFU -> Icons.Filled.LockOpen to MaterialTheme.colorScheme.onSurfaceVariant
    }
+    Icon(
+        icon,
+        contentDescription = status.label,
+        tint = tint.copy(alpha = 0.85f),
+        modifier = modifier.padding(14.dp).size(18.dp),
+    )
 }

 /** Shown when there are no saved or discovered hosts. */
@@ -0,0 +1,98 @@
+package io.unom.punktfunk.components
+
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.SolidColor
+import androidx.compose.ui.graphics.vector.ImageVector
+import androidx.compose.ui.graphics.vector.PathParser
+import androidx.compose.ui.unit.dp
+import io.unom.punktfunk.kit.discovery.osIconTokens
+
+/**
+ * The host card's OS marks, resolved from the host's OS-identity chain (mDNS `os` TXT,
+ * e.g. "linux/fedora/bazzite"): [resolveOsIcon] walks the chain most-specific-first
+ * (kit's [osIconTokens] — the shared order + brand aliases) and returns the first mark we
+ * ship, so an unknown distro degrades to its family's mark and finally to Tux; null means
+ * "no icon", rendering the card exactly as before the field existed.
+ *
+ * Path data is vendored from the assets/os-icons masters (Font Awesome Free brands
+ * CC BY 4.0 + Simple Icons CC0 — provenance in that directory's README); Material ships
+ * no brand icons. Hand-kept as raw SVG path strings (one line each) rather than
+ * transcribed ImageVector DSL — [PathParser] builds the vector once, then it's cached.
+ */
+private class OsGlyph(val viewportWidth: Float, val viewportHeight: Float, val d: String)
+
+private val GLYPHS: Map<String, OsGlyph> = mapOf(
+    "windows" to OsGlyph(
+        viewportWidth = 448f,
+        viewportHeight = 512f,
+        d = "M0 93.7l183.6-25.3v177.4H0V93.7zm0 324.6l183.6 25.3V268.4H0v149.9zm203.8 28L448 480V268.4H203.8v177.9zm0-380.6v180.1H448V32L203.8 65.7z",
+    ),
+    "apple" to OsGlyph(
+        viewportWidth = 384f,
+        viewportHeight = 512f,
+        d = "M318.7 268.7c-.2-36.7 16.4-64.4 50-84.8-18.8-26.9-47.2-41.7-84.7-44.6-35.5-2.8-74.3 20.7-88.5 20.7-15 0-49.4-19.7-76.4-19.7C63.3 141.2 4 184.8 4 273.5q0 39.3 14.4 81.2c12.8 36.7 59 126.7 107.2 125.2 25.2-.6 43-17.9 75.8-17.9 31.8 0 48.3 17.9 76.4 17.9 48.6-.7 90.4-82.5 102.6-119.3-65.2-30.7-61.7-90-61.7-91.9zm-56.6-164.2c27.3-32.4 24.8-61.9 24-72.5-24.1 1.4-52 16.4-67.9 34.9-17.5 19.8-27.8 44.3-25.6 71.9 26.1 2 49.9-11.4 69.5-34.3z",
+    ),
+    "linux" to OsGlyph(
+        viewportWidth = 448f,
+        viewportHeight = 512f,
+        d = "M220.8 123.3c1 .5 1.8 1.7 3 1.7 1.1 0 2.8-.4 2.9-1.5.2-1.4-1.9-2.3-3.2-2.9-1.7-.7-3.9-1-5.5-.1-.4.2-.8.7-.6 1.1.3 1.3 2.3 1.1 3.4 1.7zm-21.9 1.7c1.2 0 2-1.2 3-1.7 1.1-.6 3.1-.4 3.5-1.6.2-.4-.2-.9-.6-1.1-1.6-.9-3.8-.6-5.5.1-1.3.6-3.4 1.5-3.2 2.9.1 1 1.8 1.5 2.8 1.4zM420 403.8c-3.6-4-5.3-11.6-7.2-19.7-1.8-8.1-3.9-16.8-10.5-22.4-1.3-1.1-2.6-2.1-4-2.9-1.3-.8-2.7-1.5-4.1-2 9.2-27.3 5.6-54.5-3.7-79.1-11.4-30.1-31.3-56.4-46.5-74.4-17.1-21.5-33.7-41.9-33.4-72C311.1 85.4 315.7.1 234.8 0 132.4-.2 158 103.4 156.9 135.2c-1.7 23.4-6.4 41.8-22.5 64.7-18.9 22.5-45.5 58.8-58.1 96.7-6 17.9-8.8 36.1-6.2 53.3-6.5 5.8-11.4 14.7-16.6 20.2-4.2 4.3-10.3 5.9-17 8.3s-14 6-18.5 14.5c-2.1 3.9-2.8 8.1-2.8 12.4 0 3.9.6 7.9 1.2 11.8 1.2 8.1 2.5 15.7.8 20.8-5.2 14.4-5.9 24.4-2.2 31.7 3.8 7.3 11.4 10.5 20.1 12.3 17.3 3.6 40.8 2.7 59.3 12.5 19.8 10.4 39.9 14.1 55.9 10.4 11.6-2.6 21.1-9.6 25.9-20.2 12.5-.1 26.3-5.4 48.3-6.6 14.9-1.2 33.6 5.3 55.1 4.1.6 2.3 1.4 4.6 2.5 6.7v.1c8.3 16.7 23.8 24.3 40.3 23 16.6-1.3 34.1-11 48.3-27.9 13.6-16.4 36-23.2 50.9-32.2 7.4-4.5 13.4-10.1 13.9-18.3.4-8.2-4.4-17.3-15.5-29.7zM223.7 87.3c9.8-22.2 34.2-21.8 44-.4 6.5 14.2 3.6 30.9-4.3 40.4-1.6-.8-5.9-2.6-12.6-4.9 1.1-1.2 3.1-2.7 3.9-4.6 4.8-11.8-.2-27-9.1-27.3-7.3-.5-13.9 10.8-11.8 23-4.1-2-9.4-3.5-13-4.4-1-6.9-.3-14.6 2.9-21.8zM183 75.8c10.1 0 20.8 14.2 19.1 33.5-3.5 1-7.1 2.5-10.2 4.6 1.2-8.9-3.3-20.1-9.6-19.6-8.4.7-9.8 21.2-1.8 28.1 1 .8 1.9-.2-5.9 5.5-15.6-14.6-10.5-52.1 8.4-52.1zm-13.6 60.7c6.2-4.6 13.6-10 14.1-10.5 4.7-4.4 13.5-14.2 27.9-14.2 7.1 0 15.6 2.3 25.9 8.9 6.3 4.1 11.3 4.4 22.6 9.3 8.4 3.5 13.7 9.7 10.5 18.2-2.6 7.1-11 14.4-22.7 18.1-11.1 3.6-19.8 16-38.2 14.9-3.9-.2-7-1-9.6-2.1-8-3.5-12.2-10.4-20-15-8.6-4.8-13.2-10.4-14.7-15.3-1.4-4.9 0-9 4.2-12.3zm3.3 334c-2.7 35.1-43.9 34.4-75.3 18-29.9-15.8-68.6-6.5-76.5-21.9-2.4-4.7-2.4-12.7 2.6-26.4v-.2c2.4-7.6.6-16-.6-23.9-1.2-7.8-1.8-15 .9-20 3.5-6.7 8.5-9.1 14.8-11.3 10.3-3.7 11.8-3.4 19.6-9.9 5.5-5.7 9.5-12.9 14.3-18 5.1-5.5 10-8.1 17.7-6.9 8.1 1.2 15.1 6.8 21.9 16l19.6 35.6c9.5 19.9 43.1 48.4 41 68.9zm-1.4-25.9c-4.1-6.6-9.6-13.6-14.4-19.6 7.1 0 14.2-2.2 16.7-8.9 2.3-6.2 0-14.9-7.4-24.9-13.5-18.2-38.3-32.5-38.3-32.5-13.5-8.4-21.1-18.7-24.6-29.9s-3-23.3-.3-35.2c5.2-22.9 18.6-45.2 27.2-59.2 2.3-1.7.8 3.2-8.7 20.8-8.5 16.1-24.4 53.3-2.6 82.4.6-20.7 5.5-41.8 13.8-61.5 12-27.4 37.3-74.9 39.3-112.7 1.1.8 4.6 3.2 6.2 4.1 4.6 2.7 8.1 6.7 12.6 10.3 12.4 10 28.5 9.2 42.4 1.2 6.2-3.5 11.2-7.5 15.9-9 9.9-3.1 17.8-8.6 22.3-15 7.7 30.4 25.7 74.3 37.2 95.7 6.1 11.4 18.3 35.5 23.6 64.6 3.3-.1 7 .4 10.9 1.4 13.8-35.7-11.7-74.2-23.3-84.9-4.7-4.6-4.9-6.6-2.6-6.5 12.6 11.2 29.2 33.7 35.2 59 2.8 11.6 3.3 23.7.4 35.7 16.4 6.8 35.9 17.9 30.7 34.8-2.2-.1-3.2 0-4.2 0 3.2-10.1-3.9-17.6-22.8-26.1-19.6-8.6-36-8.6-38.3 12.5-12.1 4.2-18.3 14.7-21.4 27.3-2.8 11.2-3.6 24.7-4.4 39.9-.5 7.7-3.6 18-6.8 29-32.1 22.9-76.7 32.9-114.3 7.2zm257.4-11.5c-.9 16.8-41.2 19.9-63.2 46.5-13.2 15.7-29.4 24.4-43.6 25.5s-26.5-4.8-33.7-19.3c-4.7-11.1-2.4-23.1 1.1-36.3 3.7-14.2 9.2-28.8 9.9-40.6.8-15.2 1.7-28.5 4.2-38.7 2.6-10.3 6.6-17.2 13.7-21.1.3-.2.7-.3 1-.5.8 13.2 7.3 26.6 18.8 29.5 12.6 3.3 30.7-7.5 38.4-16.3 9-.3 15.7-.9 22.6 5.1 9.9 8.5 7.1 30.3 17.1 41.6 10.6 11.6 14 19.5 13.7 24.6zM173.3 148.7c2 1.9 4.7 4.5 8 7.1 6.6 5.2 15.8 10.6 27.3 10.6 11.6 0 22.5-5.9 31.8-10.8 4.9-2.6 10.9-7 14.8-10.4s5.9-6.3 3.1-6.6-2.6 2.6-6 5.1c-4.4 3.2-9.7 7.4-13.9 9.8-7.4 4.2-19.5 10.2-29.9 10.2s-18.7-4.8-24.9-9.7c-3.1-2.5-5.7-5-7.7-6.9-1.5-1.4-1.9-4.6-4.3-4.9-1.4-.1-1.8 3.7 1.7 6.5z",
+    ),
+    "steam" to OsGlyph(
+        viewportWidth = 496f,
+        viewportHeight = 512f,
+        d = "M496 256c0 137-111.2 248-248.4 248-113.8 0-209.6-76.3-239-180.4l95.2 39.3c6.4 32.1 34.9 56.4 68.9 56.4 39.2 0 71.9-32.4 70.2-73.5l84.5-60.2c52.1 1.3 95.8-40.9 95.8-93.5 0-51.6-42-93.5-93.7-93.5s-93.7 42-93.7 93.5v1.2L176.6 279c-15.5-.9-30.7 3.4-43.5 12.1L0 236.1C10.2 108.4 117.1 8 247.6 8 384.8 8 496 119 496 256zM155.7 384.3l-30.5-12.6a52.79 52.79 0 0 0 27.2 25.8c26.9 11.2 57.8-1.6 69-28.4 5.4-13 5.5-27.3.1-40.3-5.4-13-15.5-23.2-28.5-28.6-12.9-5.4-26.7-5.2-38.9-.6l31.5 13c19.8 8.2 29.2 30.9 20.9 50.7-8.3 19.9-31 29.2-50.8 21zm173.8-129.9c-34.4 0-62.4-28-62.4-62.3s28-62.3 62.4-62.3 62.4 28 62.4 62.3-27.9 62.3-62.4 62.3zm.1-15.6c25.9 0 46.9-21 46.9-46.8 0-25.9-21-46.8-46.9-46.8s-46.9 21-46.9 46.8c.1 25.8 21.1 46.8 46.9 46.8z",
+    ),
+    "ubuntu" to OsGlyph(
+        viewportWidth = 496f,
+        viewportHeight = 512f,
+        d = "M248 8C111 8 0 119 0 256s111 248 248 248 248-111 248-248S385 8 248 8zm52.7 93c8.8-15.2 28.3-20.5 43.5-11.7 15.3 8.8 20.5 28.3 11.7 43.6-8.8 15.2-28.3 20.5-43.5 11.7-15.3-8.9-20.5-28.4-11.7-43.6zM87.4 287.9c-17.6 0-31.9-14.3-31.9-31.9 0-17.6 14.3-31.9 31.9-31.9 17.6 0 31.9 14.3 31.9 31.9 0 17.6-14.3 31.9-31.9 31.9zm28.1 3.1c22.3-17.9 22.4-51.9 0-69.9 8.6-32.8 29.1-60.7 56.5-79.1l23.7 39.6c-51.5 36.3-51.5 112.5 0 148.8L172 370c-27.4-18.3-47.8-46.3-56.5-79zm228.7 131.7c-15.3 8.8-34.7 3.6-43.5-11.7-8.8-15.3-3.6-34.8 11.7-43.6 15.2-8.8 34.7-3.6 43.5 11.7 8.8 15.3 3.6 34.8-11.7 43.6zm.3-69.5c-26.7-10.3-56.1 6.6-60.5 35-5.2 1.4-48.9 14.3-96.7-9.4l22.5-40.3c57 26.5 123.4-11.7 128.9-74.4l46.1.7c-2.3 34.5-17.3 65.5-40.3 88.4zm-5.9-105.3c-5.4-62-71.3-101.2-128.9-74.4l-22.5-40.3c47.9-23.7 91.5-10.8 96.7-9.4 4.4 28.3 33.8 45.3 60.5 35 23.1 22.9 38 53.9 40.2 88.5l-46 .6z",
+    ),
+    "fedora" to OsGlyph(
+        viewportWidth = 448f,
+        viewportHeight = 512f,
+        d = "M225 32C101.3 31.7.8 131.7.4 255.4L0 425.7a53.6 53.6 0 0 0 53.6 53.9l170.2.4c123.7.3 224.3-99.7 224.6-223.4S348.7 32.3 225 32zm169.8 157.2L333 126.6c2.3-4.7 3.8-9.2 3.8-14.3v-1.6l55.2 56.1a101 101 0 0 1 2.8 22.4zM331 94.3a106.06 106.06 0 0 1 58.5 63.8l-54.3-54.6a26.48 26.48 0 0 0-4.2-9.2zM118.1 247.2a49.66 49.66 0 0 0-7.7 11.4l-8.5-8.5a85.78 85.78 0 0 1 16.2-2.9zM97 251.4l11.8 11.9-.9 8a34.74 34.74 0 0 0 2.4 12.5l-27-27.2a80.6 80.6 0 0 1 13.7-5.2zm-18.2 7.4l38.2 38.4a53.17 53.17 0 0 0-14.1 4.7L67.6 266a107 107 0 0 1 11.2-7.2zm-15.2 9.8l35.3 35.5a67.25 67.25 0 0 0-10.5 8.5L53.5 278a64.33 64.33 0 0 1 10.1-9.4zm-13.3 12.3l34.9 35a56.84 56.84 0 0 0-7.7 11.4l-35.8-35.9c2.8-3.8 5.7-7.2 8.6-10.5zm-11 14.3l36.4 36.6a48.29 48.29 0 0 0-3.6 15.2l-39.5-39.8a99.81 99.81 0 0 1 6.7-12zm-8.8 16.3l41.3 41.8a63.47 63.47 0 0 0 6.7 26.2L25.8 326c1.4-4.9 2.9-9.6 4.7-14.5zm-7.9 43l61.9 62.2a31.24 31.24 0 0 0-3.6 14.3v1.1l-55.4-55.7a88.27 88.27 0 0 1-2.9-21.9zm5.3 30.7l54.3 54.6a28.44 28.44 0 0 0 4.2 9.2 106.32 106.32 0 0 1-58.5-63.8zm-5.3-37a80.69 80.69 0 0 1 2.1-17l72.2 72.5a37.59 37.59 0 0 0-9.9 8.7zm253.3-51.8l-42.6-.1-.1 56c-.2 69.3-64.4 115.8-125.7 102.9-5.7 0-19.9-8.7-19.9-24.2a24.89 24.89 0 0 1 24.5-24.6c6.3 0 6.3 1.6 15.7 1.6a55.91 55.91 0 0 0 56.1-55.9l.1-47c0-4.5-4.5-9-8.9-9l-33.6-.1c-32.6-.1-32.5-49.4.1-49.3l42.6.1.1-56a105.18 105.18 0 0 1 105.6-105 86.35 86.35 0 0 1 20.2 2.3c11.2 1.8 19.9 11.9 19.9 24 0 15.5-14.9 27.8-30.3 23.9-27.4-5.9-65.9 14.4-66 54.9l-.1 47a8.94 8.94 0 0 0 8.9 9l33.6.1c32.5.2 32.4 49.5-.2 49.4zm23.5-.3a35.58 35.58 0 0 0 7.6-11.4l8.5 8.5a102 102 0 0 1-16.1 2.9zm21-4.2L308.6 280l.9-8.1a34.74 34.74 0 0 0-2.4-12.5l27 27.2a74.89 74.89 0 0 1-13.7 5.3zm18-7.4l-38-38.4c4.9-1.1 9.6-2.4 13.7-4.7l36.2 35.9c-3.8 2.5-7.9 5-11.9 7.2zm15.5-9.8l-35.3-35.5a61.06 61.06 0 0 0 10.5-8.5l34.9 35a124.56 124.56 0 0 1-10.1 9zm13.2-12.3l-34.9-35a63.18 63.18 0 0 0 7.7-11.4l35.8 35.9a130.28 130.28 0 0 1-8.6 10.5zm11-14.3l-36.4-36.6a48.29 48.29 0 0 0 3.6-15.2l39.5 39.8a87.72 87.72 0 0 1-6.7 12zm13.5-30.9a140.63 140.63 0 0 1-4.7 14.3L345.6 190a58.19 58.19 0 0 0-7.1-26.2zm1-5.6l-71.9-72.1a32 32 0 0 0 9.9-9.2l64.3 64.7a90.93 90.93 0 0 1-2.3 16.6z",
+    ),
+    "arch" to OsGlyph(
+        viewportWidth = 24f,
+        viewportHeight = 24f,
+        d = "M11.39.605C10.376 3.092 9.764 4.72 8.635 7.132c.693.734 1.543 1.589 2.923 2.554-1.484-.61-2.496-1.224-3.252-1.86C6.86 10.842 4.596 15.138 0 23.395c3.612-2.085 6.412-3.37 9.021-3.862a6.61 6.61 0 01-.171-1.547l.003-.115c.058-2.315 1.261-4.095 2.687-3.973 1.426.12 2.534 2.096 2.478 4.409a6.52 6.52 0 01-.146 1.243c2.58.505 5.352 1.787 8.914 3.844-.702-1.293-1.33-2.459-1.929-3.57-.943-.73-1.926-1.682-3.933-2.713 1.38.359 2.367.772 3.137 1.234-6.09-11.334-6.582-12.84-8.67-17.74zM22.898 21.36v-.623h-.234v-.084h.562v.084h-.234v.623h.331v-.707h.142l.167.5.034.107a2.26 2.26 0 01.038-.114l.17-.493H24v.707h-.091v-.593l-.206.593h-.084l-.205-.602v.602h-.091",
+    ),
+    "debian" to OsGlyph(
+        viewportWidth = 24f,
+        viewportHeight = 24f,
+        d = "M13.88 12.685c-.4 0 .08.2.601.28.14-.1.27-.22.39-.33a3.001 3.001 0 01-.99.05m2.14-.53c.23-.33.4-.69.47-1.06-.06.27-.2.5-.33.73-.75.47-.07-.27 0-.56-.8 1.01-.11.6-.14.89m.781-2.05c.05-.721-.14-.501-.2-.221.07.04.13.5.2.22M12.38.31c.2.04.45.07.42.12.23-.05.28-.1-.43-.12m.43.12l-.15.03.14-.01V.43m6.633 9.944c.02.64-.2.95-.38 1.5l-.35.181c-.28.54.03.35-.17.78-.44.39-1.34 1.22-1.62 1.301-.201 0 .14-.25.19-.34-.591.4-.481.6-1.371.85l-.03-.06c-2.221 1.04-5.303-1.02-5.253-3.842-.03.17-.07.13-.12.2a3.551 3.552 0 012.001-3.501 3.361 3.362 0 013.732.48 3.341 3.342 0 00-2.721-1.3c-1.18.01-2.281.76-2.651 1.57-.6.38-.67 1.47-.93 1.661-.361 2.601.66 3.722 2.38 5.042.27.19.08.21.12.35a4.702 4.702 0 01-1.53-1.16c.23.33.47.66.8.91-.55-.18-1.27-1.3-1.48-1.35.93 1.66 3.78 2.921 5.261 2.3a6.203 6.203 0 01-2.33-.28c-.33-.16-.77-.51-.7-.57a5.802 5.803 0 005.902-.84c.44-.35.93-.94 1.07-.95-.2.32.04.16-.12.44.44-.72-.2-.3.46-1.24l.24.33c-.09-.6.74-1.321.66-2.262.19-.3.2.3 0 .97.29-.74.08-.85.15-1.46.08.2.18.42.23.63-.18-.7.2-1.2.28-1.6-.09-.05-.28.3-.32-.53 0-.37.1-.2.14-.28-.08-.05-.26-.32-.38-.861.08-.13.22.33.34.34-.08-.42-.2-.75-.2-1.08-.34-.68-.12.1-.4-.3-.34-1.091.3-.25.34-.74.54.77.84 1.96.981 2.46-.1-.6-.28-1.2-.49-1.76.16.07-.26-1.241.21-.37A7.823 7.824 0 0017.702 1.6c.18.17.42.39.33.42-.75-.45-.62-.48-.73-.67-.61-.25-.65.02-1.06 0C15.082.73 14.862.8 13.8.4l.05.23c-.77-.25-.9.1-1.73 0-.05-.04.27-.14.53-.18-.741.1-.701-.14-1.431.03.17-.13.36-.21.55-.32-.6.04-1.44.35-1.18.07C9.6.68 7.847 1.3 6.867 2.22L6.838 2c-.45.54-1.96 1.611-2.08 2.311l-.131.03c-.23.4-.38.85-.57 1.261-.3.52-.45.2-.4.28-.6 1.22-.9 2.251-1.16 3.102.18.27 0 1.65.07 2.76-.3 5.463 3.84 10.776 8.363 12.006.67.23 1.65.23 2.49.25-.99-.28-1.12-.15-2.08-.49-.7-.32-.85-.7-1.34-1.13l.2.35c-.971-.34-.57-.42-1.361-.67l.21-.27c-.31-.03-.83-.53-.97-.81l-.34.01c-.41-.501-.63-.871-.61-1.161l-.111.2c-.13-.21-1.52-1.901-.8-1.511-.13-.12-.31-.2-.5-.55l.14-.17c-.35-.44-.64-1.02-.62-1.2.2.24.32.3.45.33-.88-2.172-.93-.12-1.601-2.202l.15-.02c-.1-.16-.18-.34-.26-.51l.06-.6c-.63-.74-.18-3.102-.09-4.402.07-.54.53-1.1.88-1.981l-.21-.04c.4-.71 2.341-2.872 3.241-2.761.43-.55-.09 0-.18-.14.96-.991 1.26-.7 1.901-.88.7-.401-.6.16-.27-.151 1.2-.3.85-.7 2.421-.85.16.1-.39.14-.52.26 1-.49 3.151-.37 4.562.27 1.63.77 3.461 3.011 3.531 5.132l.08.02c-.04.85.13 1.821-.17 2.711l.2-.42M9.54 13.236l-.05.28c.26.35.47.73.8 1.01-.24-.47-.42-.66-.75-1.3m.62-.02c-.14-.15-.22-.34-.31-.52.08.32.26.6.43.88l-.12-.36m10.945-2.382l-.07.15c-.1.76-.34 1.511-.69 2.212.4-.73.65-1.541.75-2.362M12.45.12c.27-.1.66-.05.95-.12-.37.03-.74.05-1.1.1l.15.02M3.006 5.142c.07.57-.43.8.11.42.3-.66-.11-.18-.1-.42m-.64 2.661c.12-.39.15-.62.2-.84-.35.44-.17.53-.2.83",
+    ),
+    "nixos" to OsGlyph(
+        viewportWidth = 24f,
+        viewportHeight = 24f,
+        d = "M7.352 1.592l-1.364.002L5.32 2.75l1.557 2.713-3.137-.008-1.32 2.34H14.11l-1.353-2.332-3.192-.006-2.214-3.865zm6.175 0l-2.687.025 5.846 10.127 1.341-2.34-1.59-2.765 2.24-3.85-.683-1.182h-1.336l-1.57 2.705-1.56-2.72zm6.887 4.195l-5.846 10.125 2.696-.008 1.601-2.76 4.453.016.682-1.183-.666-1.157-3.13-.008L21.778 8.1l-1.365-2.313zM9.432 8.086l-2.696.008-1.601 2.76-4.453-.016L0 12.02l.666 1.157 3.13.008-1.575 2.71 1.365 2.315L9.432 8.086zM7.33 12.25l-.006.01-.002-.004-1.342 2.34 1.59 2.765-2.24 3.85.684 1.182H7.35l.004-.006h.001l1.567-2.698 1.558 2.72 2.688-.026-.004-.006h.01L7.33 12.25zm2.55 3.93l1.354 2.332 3.192.006 2.215 3.865 1.363-.002.668-1.156-1.557-2.713 3.137.008 1.32-2.34H9.881Z",
+    ),
+    "opensuse" to OsGlyph(
+        viewportWidth = 640f,
+        viewportHeight = 512f,
+        d = "M471.08 102.66s-.3 18.3-.3 20.3c-9.1-3-74.4-24.1-135.7-26.3-51.9-1.8-122.8-4.3-223 57.3-19.4 12.4-73.9 46.1-99.6 109.7C7 277-.12 307 7 335.06a111 111 0 0 0 16.5 35.7c17.4 25 46.6 41.6 78.1 44.4 44.4 3.9 78.1-16 90-53.3 8.2-25.8 0-63.6-31.5-82.9-25.6-15.7-53.3-12.1-69.2-1.6-13.9 9.2-21.8 23.5-21.6 39.2.3 27.8 24.3 42.6 41.5 42.6a49 49 0 0 0 15.8-2.7c6.5-1.8 13.3-6.5 13.3-14.9 0-12.1-11.6-14.8-16.8-13.9-2.9.5-4.5 2-11.8 2.4-2-.2-12-3.1-12-14V316c.2-12.3 13.2-18 25.5-16.9 32.3 2.8 47.7 40.7 28.5 65.7-18.3 23.7-76.6 23.2-99.7-20.4-26-49.2 12.7-111.2 87-98.4 33.2 5.7 83.6 35.5 102.4 104.3h45.9c-5.7-17.6-8.9-68.3 42.7-68.3 56.7 0 63.9 39.9 79.8 68.3H460c-12.8-18.3-21.7-38.7-18.9-55.8 5.6-33.8 39.7-18.4 82.4-17.4 66.5.4 102.1-27 103.1-28 3.7-3.1 6.5-15.8 7-17.7 1.3-5.1-3.2-2.4-3.2-2.4-8.7 5.2-30.5 15.2-50.9 15.6-25.3.5-76.2-25.4-81.6-28.2-.3-.4.1 1.2-11-25.5 88.4 58.3 118.3 40.5 145.2 21.7.8-.6 4.3-2.9 3.6-5.7-13.8-48.1-22.4-62.7-34.5-69.6-37-21.6-125-34.7-129.2-35.3.1-.1-.9-.3-.9.7zm60.4 72.8a37.54 37.54 0 0 1 38.9-36.3c33.4 1.2 48.8 42.3 24.4 65.2-24.2 22.7-64.4 4.6-63.3-28.9zm38.6-25.3a26.27 26.27 0 1 0 25.4 27.2 26.19 26.19 0 0 0-25.4-27.2zm4.3 28.8c-15.4 0-15.4-15.6 0-15.6s15.4 15.64 0 15.64z",
+    ),
+)
+
+private val built = mutableMapOf<String, ImageVector>()
+
+/** The mark for a chain, or null (no icon). Vectors build lazily and cache per token. */
+fun resolveOsIcon(chain: String): ImageVector? =
+    osIconTokens(chain).firstNotNullOfOrNull { token ->
+        GLYPHS[token]?.let { glyph -> built.getOrPut(token) { glyph.build(token) } }
+    }
+
+private fun OsGlyph.build(token: String): ImageVector =
+    ImageVector.Builder(
+        name = "OsIcon.$token",
+        defaultWidth = 24.dp,
+        defaultHeight = 24.dp,
+        viewportWidth = viewportWidth,
+        viewportHeight = viewportHeight,
+    ).apply {
+        // Fill colour is irrelevant — Icon() tints via LocalContentColor, like Material icons.
+        addPath(
+            pathData = PathParser().parsePathString(d).toNodes(),
+            fill = SolidColor(Color.Black),
+        )
+    }.build()
@@ -25,10 +25,44 @@ data class PendingTrust(
    val name: String,
    val advertisedFp: String?,
    val kind: Kind,
+    /**
+     * What the connect on the far side of this decision should carry — a `punktfunk://` link's
+     * one-off profile and library id. A link to an unknown host goes through the confirmation
+     * first, and the user's stated intent must survive that detour rather than being silently
+     * dropped on the way to a plain desktop session.
+     */
+    val profile: String? = null,
+    val launch: String? = null,
 ) {
    enum class Kind { TRUST_NEW, FP_CHANGED, PAIR, REQUEST_ACCESS }
 }

+/**
+ * A stream session that just opened, and the state the stream screen needs about it.
+ *
+ * [settings] is the settings the connect ACTUALLY used, resolved once at connect time — not
+ * "whatever the settings store says now". Every post-connect read (the stats tier, the touch and
+ * mouse models, the low-latency pipeline, rumble, SC2 capture) takes it, so the stream can never
+ * disagree with the connect that produced it. [clipboardSync] comes from the host record, because
+ * clipboard sync is a decision about that host rather than about this device.
+ */
+data class ActiveSession(
+    val handle: Long,
+    val settings: io.unom.punktfunk.Settings,
+    val clipboardSync: Boolean,
+    /**
+     * The settings profile this session resolved, if any — shown on the stats overlay's first line
+     * so "which profile am I on?" is answerable from inside the stream, as on the other clients.
+     */
+    val profileName: String? = null,
+    /**
+     * The stable id of the host being streamed, when it is a saved one — so a `punktfunk://` link
+     * that arrives mid-stream can tell "this same host" (a no-op; the intent already focused us)
+     * from "a different host" (a notice; a URL may never preempt a live session).
+     */
+    val hostId: String? = null,
+)
+
 /** Trust state of a host, shown as a colored pill on its card. */
 enum class HostStatus(val label: String) {
    PAIRED("Paired"),
@@ -0,0 +1,247 @@
+package io.unom.punktfunk
+
+import io.unom.punktfunk.kit.security.KnownHost
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.RuntimeEnvironment
+import org.robolectric.annotation.Config
+
+/**
+ * The profile model — the part of this feature that is wrong-or-right rather than pretty-or-ugly.
+ * A profile is a named bundle of OVERRIDES, not a snapshot: an untouched field keeps following the
+ * global live, a touched one is recorded even when it equals today's global (a pin), and the only
+ * way back to inheriting is an explicit reset. These tests are the Kotlin twin of the Rust
+ * `profiles.rs` suite, so the two can't drift.
+ *
+ * `sdk = [36]` for the same reason the screenshot tests pin it: Robolectric ships android-all jars
+ * only up to API 36 while the app compiles against 37.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [36])
+class ProfilesTest {
+    private val base = Settings(
+        width = 1920,
+        height = 1080,
+        bitrateKbps = 20_000,
+        codec = "hevc",
+        touchMode = TouchMode.TRACKPAD,
+        mouseMode = MouseMode.DESKTOP,
+    )
+
+    @Test
+    fun overlayAppliesOnlyWhatItOverrides() {
+        val empty = SettingsOverlay()
+        assertTrue(empty.isEmpty())
+        assertEquals(base, empty.apply(base))
+
+        val overlay = SettingsOverlay(
+            width = 3840,
+            height = 2160,
+            hz = 120,
+            bitrateKbps = 80_000,
+            renderScale = 1.5,
+            codec = "av1",
+            hdrEnabled = false,
+            compositor = 4,
+            audioChannels = 6,
+            micEnabled = true,
+            touchMode = TouchMode.POINTER,
+            mouseMode = MouseMode.CAPTURE,
+            invertScroll = true,
+            gamepad = 6,
+            statsVerbosity = StatsVerbosity.DETAILED,
+            lowLatencyMode = false,
+        )
+        assertFalse(overlay.isEmpty())
+        val out = overlay.apply(base)
+        assertEquals(Triple(3840, 2160, 120), Triple(out.width, out.height, out.hz))
+        assertEquals(80_000, out.bitrateKbps)
+        assertEquals(1.5, out.renderScale, 0.0)
+        assertEquals("av1", out.codec)
+        assertFalse(out.hdrEnabled)
+        assertEquals(4, out.compositor)
+        assertEquals(6, out.audioChannels)
+        assertTrue(out.micEnabled)
+        assertEquals(TouchMode.POINTER, out.touchMode)
+        assertEquals(MouseMode.CAPTURE, out.mouseMode)
+        assertTrue(out.invertScroll)
+        assertEquals(6, out.gamepad)
+        assertEquals(StatsVerbosity.DETAILED, out.statsVerbosity)
+        assertFalse(out.lowLatencyMode)
+
+        // Device-scope settings are not in the overlay at all, so no profile can move them.
+        assertEquals(base.gamepadUiEnabled, out.gamepadUiEnabled)
+        assertEquals(base.libraryEnabled, out.libraryEnabled)
+        assertEquals(base.autoWakeEnabled, out.autoWakeEnabled)
+        assertEquals(base.sc2Capture, out.sc2Capture)
+    }
+
+    @Test
+    fun anOverrideEqualToTheGlobalIsAPinThatSurvivesTheGlobalMoving() {
+        val pin = SettingsOverlay(bitrateKbps = 20_000) // exactly what `base` says today
+        assertFalse(pin.isEmpty())
+        assertEquals(20_000, pin.apply(base.copy(bitrateKbps = 50_000)).bitrateKbps)
+    }
+
+    @Test
+    fun absorbRecordsTheTouchedFieldOnly() {
+        var o = SettingsOverlay()
+
+        // One control fires: before = what it was showing, after = what the user picked.
+        var before = o.apply(base)
+        o = o.absorb(before, before.copy(codec = "av1"))
+        assertEquals("av1", o.codec)
+        assertNull("nothing else may be recorded", o.bitrateKbps)
+
+        // Setting it BACK to the global's value is still an override — the pin case, and the whole
+        // difference between this and diffing against the globals at save time.
+        before = o.apply(base)
+        o = o.absorb(before, before.copy(codec = "hevc"))
+        assertEquals("hevc", o.codec)
+        assertEquals("hevc", o.apply(base.copy(codec = "h264")).codec)
+
+        // Identical snapshots record nothing.
+        before = o.apply(base)
+        assertEquals(o, o.absorb(before, before))
+    }
+
+    @Test
+    fun clearDropsOneOverride() {
+        val o = SettingsOverlay(width = 3840, height = 2160, codec = "av1")
+        assertEquals(setOf(SettingsOverlay.FIELD_RESOLUTION, "codec"), o.overridden())
+        assertNull(o.clear("codec").codec)
+        // Width and height are one control, so they reset together.
+        val reset = o.clear(SettingsOverlay.FIELD_RESOLUTION)
+        assertNull(reset.width)
+        assertNull(reset.height)
+        assertEquals(o, o.clear("no_such_field")) // unknown names are a no-op, never a crash
+    }
+
+    @Test
+    fun catalogRoundTripsAndPreservesWhatItCannotRepresent() {
+        val store = ProfileStore(RuntimeEnvironment.getApplication())
+        val game = newProfile("Game").copy(
+            accent = "#ff8800",
+            overrides = SettingsOverlay(
+                width = 3840,
+                height = 2160,
+                hz = 120,
+                // A codec string this build's picker can't show is still stored and still applied:
+                // the host is the component that decides what it can encode.
+                codec = "vvc-from-the-future",
+                extra = mapOf("some_new_axis" to 7),
+            ),
+            extra = mapOf("future_profile_key" to "kept"),
+        )
+        store.save(game)
+        store.save(newProfile("Work"))
+
+        val loaded = store.byId(game.id)!!
+        assertEquals("Game", loaded.name)
+        assertEquals("#ff8800", loaded.accent)
+        assertEquals("vvc-from-the-future", loaded.overrides.codec)
+        assertEquals(3840, loaded.overrides.width)
+        // The don't-clobber rule: an older build must not erase a newer one's keys by opening it.
+        assertEquals(mapOf<String, Any>("some_new_axis" to 7), loaded.overrides.extra)
+        assertEquals(mapOf<String, Any>("future_profile_key" to "kept"), loaded.extra)
+        assertEquals("vvc-from-the-future", loaded.overrides.apply(base).codec)
+
+        // A profile that overrides nothing is the "inherits everything" one a create starts at.
+        assertTrue(store.all().first { it.name == "Work" }.overrides.isEmpty())
+        assertEquals(listOf("Game", "Work"), store.all().map { it.name })
+    }
+
+    @Test
+    fun resolvePrefersIdsAndRefusesAmbiguity() {
+        val store = ProfileStore(RuntimeEnvironment.getApplication())
+        val work = newProfile("Work")
+        val work2 = newProfile("work") // saved directly: the UI's name guard is what prevents this
+        val game = newProfile("Game")
+        listOf(work, work2, game).forEach(store::save)
+
+        assertEquals(ProfileResolution.FOUND, store.resolve(work.id).second)
+        assertEquals(work.id, store.resolve(work.id).first!!.id)
+        // Two profiles carry this name — refuse rather than pick whichever came first.
+        assertEquals(ProfileResolution.AMBIGUOUS, store.resolve("Work").second)
+        assertNull(store.resolve("Work").first)
+        assertEquals(game.id, store.resolve("GAME").first!!.id) // names match case-insensitively
+        assertEquals(ProfileResolution.NOT_FOUND, store.resolve("nope").second)
+        assertEquals(ProfileResolution.NOT_FOUND, store.resolve("").second)
+
+        assertTrue(store.nameTaken("GAME"))
+        assertFalse(store.nameTaken("GAME", except = game.id)) // renaming in place is allowed
+        assertFalse(store.nameTaken("Travel"))
+    }
+
+    @Test
+    fun profilePrecedenceIsOneOffThenBindingThenNone() {
+        val store = ProfileStore(RuntimeEnvironment.getApplication())
+        val work = newProfile("Work")
+        val game = newProfile("Game")
+        listOf(work, game).forEach(store::save)
+        val bound = host().copy(profileId = work.id)
+
+        // A plain tap follows the binding…
+        assertEquals(work.id, store.resolveFor(bound, oneOff = null)!!.id)
+        // …a one-off wins over it, by id or by unique name, and never rebinds anything…
+        assertEquals(game.id, store.resolveFor(bound, oneOff = game.id)!!.id)
+        assertEquals(game.id, store.resolveFor(bound, oneOff = "game")!!.id)
+        assertEquals(work.id, store.resolveFor(bound, oneOff = null)!!.id)
+        // …and the empty reference is a real choice — "force the global defaults" — not "unset".
+        assertNull(store.resolveFor(bound, oneOff = ""))
+        // An unbound host is today's behaviour: the globals.
+        assertNull(store.resolveFor(host(), oneOff = null))
+        assertNull(store.resolveFor(null, oneOff = null))
+    }
+
+    @Test
+    fun aDeletedProfileLeavesNoErrorBehind() {
+        val store = ProfileStore(RuntimeEnvironment.getApplication())
+        val work = newProfile("Work")
+        store.save(work)
+        val h = host().copy(profileId = work.id, pinnedProfileIds = listOf(work.id, work.id))
+        assertEquals(1, store.pinsFor(h).size) // a duplicate pin is one card, not two
+
+        store.delete(work.id)
+        // A dangling binding resolves as "no profile" — never an error, never a blocked connect —
+        // and its pinned card simply stops rendering.
+        assertNull(store.resolveFor(h, oneOff = null))
+        assertTrue(store.pinsFor(h).isEmpty())
+        assertEquals(base, base.effectiveFor(store.resolveFor(h, oneOff = null)))
+    }
+
+    /**
+     * A profile created from the UI gets a colour, and a distinct one — the accent is the WHOLE
+     * signal on a bound host card's chip and a pinned card's tint, so two profiles sharing it (or
+     * having none) makes those surfaces say less than they look like they're saying.
+     */
+    @Test
+    fun creationHandsOutADistinctColour() {
+        val made = mutableListOf<StreamProfile>()
+        repeat(PROFILE_ACCENTS.size) { made += newProfile("p$it", nextAccent(made)) }
+        assertEquals(PROFILE_ACCENTS, made.map { it.accent })
+        // Past the palette it wraps rather than handing out nothing — a duplicate colour beats an
+        // invisible chip, and the picker is right there.
+        assertEquals(PROFILE_ACCENTS.first(), nextAccent(made))
+        // A gap is reused before wrapping.
+        assertEquals(PROFILE_ACCENTS[2], nextAccent(made.filter { it.accent != PROFILE_ACCENTS[2] }))
+        // The colour is presentation, so it never reaches the resolved settings.
+        assertEquals(base, made.first().overrides.apply(base))
+    }
+
+    @Test
+    fun mintedIdsAreWellFormed() {
+        val id = newProfileId()
+        assertEquals(12, id.length)
+        assertTrue(id.all { it.isDigit() || it in 'a'..'f' })
+        assertNotEquals(id, newProfileId())
+    }
+
+    private fun host() = KnownHost("192.168.1.42", 9777, "Desk", "a".repeat(64), paired = true)
+}
@@ -0,0 +1,127 @@
+package io.unom.punktfunk
+
+import android.content.Context
+import androidx.activity.ComponentActivity
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.test.isToggleable
+import androidx.compose.ui.test.junit4.createAndroidComposeRule
+import androidx.compose.ui.test.onNodeWithText
+import androidx.compose.ui.test.performClick
+import androidx.test.core.app.ApplicationProvider
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Rule
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.GraphicsMode
+import org.robolectric.annotation.Config
+
+/**
+ * An edit must land in the scope the chips say is selected — the one thing the two-layer settings
+ * surface can get wrong without looking wrong.
+ *
+ * The regression this pins: `update` reached the rows as `::update`, and two callable references
+ * compare EQUAL however different the scope they captured, so Compose skipped the whole detail page
+ * on a scope switch that moved nothing on screen (the ordinary case — a profile inherits the globals
+ * until it overrides something). Each edit then wrote to the scope the user had just left: change a
+ * default, switch to a profile, change the same row — the globals moved again and the profile
+ * recorded nothing — and back on the defaults the next edit went into the profile, which reads as
+ * "the default settings can't be changed any more". It needs the real Compose runtime to catch, so
+ * this drives the actual screen rather than the model underneath it.
+ *
+ * `sdk = [36]` for the reason every Robolectric test here pins it: android-all jars stop at 36 while
+ * the app compiles against 37.
+ */
+@RunWith(RobolectricTestRunner::class)
+@GraphicsMode(GraphicsMode.Mode.NATIVE)
+@Config(sdk = [36], qualifiers = "w360dp-h800dp-xxhdpi")
+class SettingsScopeTest {
+    @get:Rule
+    val compose = createAndroidComposeRule<ComponentActivity>()
+
+    private val context: Context get() = ApplicationProvider.getApplicationContext()
+
+    /**
+     * "Invert scroll direction" is the row under test: Input is profileable end to end, and that
+     * toggle is the only toggleable node on the page, so a click needs no fragile lookup.
+     */
+    private fun toggleTheRow() {
+        compose.onNode(isToggleable()).performClick()
+        compose.waitForIdle()
+    }
+
+    private fun selectScope(chip: String) {
+        compose.onNodeWithText(chip).performClick()
+        compose.waitForIdle()
+    }
+
+    @Test
+    fun editsFollowTheSelectedScope() {
+        val profiles = ProfileStore(context)
+        profiles.save(newProfile("Work", PROFILE_ACCENTS.first()))
+
+        // Mirrors App.kt: the screen is fed from state the host recomposes it with.
+        var saved = Settings()
+        compose.setContent {
+            var settings by remember { mutableStateOf(saved) }
+            SettingsScreen(
+                initial = settings,
+                onChange = { settings = it; saved = it },
+                onBack = {},
+                initialCategory = SettingsCategory.Input,
+            )
+        }
+
+        // 1. On the defaults, the globals move and no profile records anything.
+        toggleTheRow()
+        assertEquals(true, saved.invertScroll)
+        assertNull(profiles.all().single().overrides.invertScroll)
+
+        // 2. In profile scope the SAME row — untouched by the profile, so it still shows the global
+        //    value and nothing on the page changed — must record an override and leave the globals
+        //    alone. This is the step that used to write straight through to the globals.
+        selectScope("Work")
+        toggleTheRow()
+        assertEquals("the globals must not move while a profile is selected", true, saved.invertScroll)
+        assertEquals(false, profiles.all().single().overrides.invertScroll)
+
+        // 3. Back on the defaults the row is editable again, and the profile keeps its override.
+        selectScope("Default settings")
+        toggleTheRow()
+        assertEquals(false, saved.invertScroll)
+        assertEquals(
+            "the profile's override must survive an edit made on the defaults",
+            false,
+            profiles.all().single().overrides.invertScroll,
+        )
+    }
+
+    /** A reset puts the row back to inheriting — and, like an edit, it must obey the live scope. */
+    @Test
+    fun resetClearsTheSelectedProfilesOverride() {
+        val profiles = ProfileStore(context)
+        profiles.save(newProfile("Work", PROFILE_ACCENTS.first()))
+
+        compose.setContent {
+            var settings by remember { mutableStateOf(Settings()) }
+            SettingsScreen(
+                initial = settings,
+                onChange = { settings = it },
+                onBack = {},
+                initialCategory = SettingsCategory.Input,
+                initialProfileId = profiles.all().single().id,
+            )
+        }
+
+        toggleTheRow()
+        assertEquals(true, profiles.all().single().overrides.invertScroll)
+
+        compose.onNodeWithText("Reset").performClick()
+        compose.waitForIdle()
+        assertNull(profiles.all().single().overrides.invertScroll)
+    }
+}
@@ -0,0 +1,131 @@
+package io.unom.punktfunk
+
+import io.unom.punktfunk.kit.security.KnownHost
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.RuntimeEnvironment
+import org.robolectric.annotation.Config
+
+/**
+ * Where a measured bitrate lands. The measurement itself is the host's job; the decision this code
+ * makes is which layer to write — and the long-standing wrong answer (always the global) is exactly
+ * what made measuring the slow box downstairs re-tune the desktop too
+ * (design/client-settings-profiles.md §5.3).
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [36])
+class SpeedTestTest {
+    private val store get() = ProfileStore(RuntimeEnvironment.getApplication())
+    private fun host() = KnownHost("192.168.1.42", 9777, "Desk", "a".repeat(64), paired = true)
+
+    @Test
+    fun anUnboundHostTargetsTheGlobalDefault() {
+        assertEquals(SpeedTestTarget.Global, SpeedTestTarget.resolve(host(), null, store))
+        assertEquals(SpeedTestTarget.Global, SpeedTestTarget.resolve(null, null, store))
+    }
+
+    @Test
+    fun aProfileThatSetsBitrateIsTheLayerThatHostReads() {
+        val s = store
+        val game = newProfile("Game").copy(overrides = SettingsOverlay(bitrateKbps = 50_000))
+        s.save(game)
+        val target = SpeedTestTarget.resolve(host().copy(profileId = game.id), null, s)
+        assertEquals(game.id, (target as SpeedTestTarget.Profile).profile.id)
+    }
+
+    @Test
+    fun aProfileThatInheritsBitrateAsksWhichLayer() {
+        val s = store
+        val work = newProfile("Work") // overrides nothing
+        s.save(work)
+        val target = SpeedTestTarget.resolve(host().copy(profileId = work.id), null, s)
+        // Both layers are defensible here, so the user picks — we don't guess.
+        assertEquals(work.id, (target as SpeedTestTarget.Ask).profile.id)
+    }
+
+    @Test
+    fun theOneOffPickWinsAndTheEmptyOneForcesTheDefaults() {
+        val s = store
+        val game = newProfile("Game").copy(overrides = SettingsOverlay(bitrateKbps = 50_000))
+        val work = newProfile("Work")
+        listOf(game, work).forEach(s::save)
+        val bound = host().copy(profileId = work.id)
+
+        // Testing from a pinned card measures — and writes — that card's profile.
+        assertEquals(game.id, (SpeedTestTarget.resolve(bound, game.id, s) as SpeedTestTarget.Profile).profile.id)
+        // "Connect with: Default settings" is a real choice, so its speed test targets the global.
+        assertEquals(SpeedTestTarget.Global, SpeedTestTarget.resolve(bound, "", s))
+        // A dangling binding resolves as no profile everywhere else; here too.
+        assertEquals(SpeedTestTarget.Global, SpeedTestTarget.resolve(host().copy(profileId = "gone"), null, s))
+    }
+
+    @Test
+    fun applyingWritesOnlyTheBitrate_andOnlyToTheChosenLayer() {
+        val s = store
+        val game = newProfile("Game").copy(
+            overrides = SettingsOverlay(bitrateKbps = 50_000, width = 3840, height = 2160),
+        )
+        s.save(game)
+        val globals = Settings(bitrateKbps = 20_000, codec = "hevc")
+        var savedGlobals: Settings? = null
+
+        val where = applySpeedTestResult(
+            kbps = 84_000,
+            target = SpeedTestTarget.Profile(game),
+            toProfile = true,
+            profiles = s,
+            settings = globals,
+            onGlobalChange = { savedGlobals = it },
+        )
+        assertEquals("“Game”", where)
+        assertNull("the global must not move when a profile was the target", savedGlobals)
+        val after = s.byId(game.id)!!.overrides
+        assertEquals(84_000, after.bitrateKbps)
+        // Nothing else in the overlay is a speed test's business.
+        assertEquals(3840, after.width)
+        assertEquals(2160, after.height)
+    }
+
+    @Test
+    fun theAskCaseHonoursWhichButtonWasPressed() {
+        val s = store
+        val work = newProfile("Work")
+        s.save(work)
+        val globals = Settings(bitrateKbps = 20_000)
+        var savedGlobals: Settings? = null
+
+        // "Set as default" writes the global and leaves the profile inheriting.
+        val whereGlobal = applySpeedTestResult(
+            42_000, SpeedTestTarget.Ask(work), toProfile = false, profiles = s,
+            settings = globals, onGlobalChange = { savedGlobals = it },
+        )
+        assertEquals("the default bitrate", whereGlobal)
+        assertEquals(42_000, savedGlobals!!.bitrateKbps)
+        assertNull(s.byId(work.id)!!.overrides.bitrateKbps)
+
+        // "Set in Work" records the override instead — and now that profile stops inheriting.
+        savedGlobals = null
+        val whereProfile = applySpeedTestResult(
+            42_000, SpeedTestTarget.Ask(work), toProfile = true, profiles = s,
+            settings = globals, onGlobalChange = { savedGlobals = it },
+        )
+        assertEquals("“Work”", whereProfile)
+        assertNull(savedGlobals)
+        assertEquals(42_000, s.byId(work.id)!!.overrides.bitrateKbps)
+    }
+
+    @Test
+    fun theRecommendationLeavesHeadroom() {
+        // 70 % of measured, in the desktop clients' integer order — a stream needs room for the
+        // FEC overhead and for the loss a burst measurement doesn't see.
+        val done = SpeedTestPhase.Done(throughputKbps = 100_000, lossPct = 0.4, recommendedKbps = 100_000 / 10 * 7)
+        assertEquals(70_000, done.recommendedKbps)
+        assertEquals(100.0, done.measuredMbps, 0.001)
+        assertEquals(70.0, done.recommendedMbps, 0.001)
+        assertTrue(done.recommendedKbps < done.throughputKbps)
+    }
+}
@@ -56,6 +56,21 @@ class ScreenshotTest {
    @Test
    fun settings() = shootRoot("settings") { SettingsScene() }

+    // One category page per shot: the sub-section headers, the caption-under-control fields and
+    // the "applies from the next session" footers live inside a category, not on the root list.
+    @Test
+    fun settingsDisplay() = shootRoot("settings-display") {
+        SettingsCategoryScene(io.unom.punktfunk.SettingsCategory.Display)
+    }
+
+    @Test
+    fun settingsInput() = shootRoot("settings-input") {
+        SettingsCategoryScene(io.unom.punktfunk.SettingsCategory.Input)
+    }
+
+    @Test
+    fun settingsProfile() = shootRoot("settings-profile") { SettingsProfileScene() }
+
    @Test
    @Config(sdk = [36], qualifiers = "w800dp-h360dp-xxhdpi") // landscape — the stream is immersive
    fun stream() = shootRoot("stream") { StreamScene(io.unom.punktfunk.StatsVerbosity.DETAILED) }
@@ -97,6 +112,15 @@ class ScreenshotTest {
        TrustDialog()
    }

+    @Test
+    fun newProfile() = shootRoot("new-profile") { NewProfileScene() }
+
+    @Test
+    fun speedTest() = shootScreen("speed-test") {
+        HostsScene()
+        SpeedTestScene()
+    }
+
    @Test
    fun pair() = shootScreen("pair") {
        HostsScene()
@@ -19,10 +19,12 @@ import androidx.compose.material3.Surface
 import androidx.compose.material3.Text
 import androidx.compose.material3.TextButton
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.remember
 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.platform.LocalContext
 import androidx.compose.ui.text.style.TextAlign
 import androidx.compose.ui.unit.dp
 import io.unom.punktfunk.BrandDark
@@ -31,11 +33,20 @@ import io.unom.punktfunk.ConnectPhase
 import io.unom.punktfunk.ConnectTakeover
 import io.unom.punktfunk.Settings
 import io.unom.punktfunk.TouchMode
+import io.unom.punktfunk.SettingsCategory
 import io.unom.punktfunk.SettingsScreen
 import io.unom.punktfunk.StatsOverlay
 import io.unom.punktfunk.StatsVerbosity
+import io.unom.punktfunk.ProfileEditorFields
+import io.unom.punktfunk.ProfileStore
+import io.unom.punktfunk.SettingsOverlay
+import io.unom.punktfunk.SpeedTestDialog
+import io.unom.punktfunk.SpeedTestPhase
+import io.unom.punktfunk.SpeedTestTarget
 import io.unom.punktfunk.components.HostCard
+import io.unom.punktfunk.components.HostMenuItem
 import io.unom.punktfunk.components.SectionLabel
+import io.unom.punktfunk.newProfile
 import io.unom.punktfunk.models.HostStatus

 // The CI screenshot scenes: the REAL app composables, fed embedded mock state, under the forced
@@ -48,15 +59,31 @@ 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 data class MockHost(
+    val name: String,
+    val address: String,
+    val status: HostStatus,
+    val profile: String? = null,
+    val pin: String? = null,
+    val accent: Color? = null,
+    val online: Boolean = false,
+)

+// Ordered so an UNCHIPPED card sits beside a CHIPPED one in the same grid row, and a long trust
+// label ("Trust on first use") beside a short one ("Paired"). Both are what used to make cards in a
+// row step up and down — the grid sizes a row to its tallest item and doesn't stretch the rest — so
+// this arrangement is the regression net for it.
 private val SAVED = listOf(
-    MockHost("Living Room PC", "192.168.1.42:9777", HostStatus.PAIRED),
    MockHost("Office", "192.168.1.50:9777", HostStatus.TOFU),
+    MockHost(
+        "Living Room PC", "192.168.1.42:9777", HostStatus.PAIRED,
+        profile = "Game", pin = "Work", accent = Color(0xFFFF8A4C), online = true,
+    ),
 )
 private val DISCOVERED = listOf(
-    MockHost("studio-deck", "192.168.1.61:9777", HostStatus.PAIRING),
-    MockHost("HTPC", "192.168.1.70:9777", HostStatus.TOFU),
+    // Discovered ⇒ advertising right now, so both are online.
+    MockHost("studio-deck", "192.168.1.61:9777", HostStatus.PAIRING, online = true),
+    MockHost("HTPC", "192.168.1.70:9777", HostStatus.TOFU, online = true),
 )

 /** The connect screen's host grid, reconstructed from the real HostCard/SectionLabel components. */
@@ -86,42 +113,170 @@ internal fun HostsScene() {
                }
            }
            item(span = { GridItemSpan(maxLineSpan) }) { SectionLabel("Saved hosts") }
-            items(SAVED) { h ->
-                HostCard(h.name, h.address, h.status, enabled = true, onConnect = {}, onForget = {}, onEdit = {})
+            // A pinned card is its OWN grid cell right after its host — the same flat list the
+            // connect screen builds, not a second card crammed into the host's cell.
+            SAVED.forEach { h ->
+                item {
+                    HostCard(
+                        h.name, h.address, h.status, online = h.online, enabled = true,
+                        onConnect = {}, onForget = {}, onEdit = {},
+                        // The bound profile is a quiet chip: the card says what a tap will do.
+                        profileLabel = h.profile,
+                        accent = h.accent,
+                        menuItems = listOf(
+                            HostMenuItem("Connect with: Default settings", startsSection = true) {},
+                            HostMenuItem("Connect with: Game") {},
+                        ),
+                        // One card in this section has a chip, so every card reserves its space —
+                        // the shot is here to catch a row that steps.
+                        reserveProfileSlot = true,
+                    )
+                }
+                if (h.pin != null) {
+                    item {
+                        HostCard(
+                            h.name, h.address, h.status, online = h.online, enabled = true,
+                            onConnect = {}, onForget = null,
+                            profileLabel = h.pin, profileProminent = true, accent = h.accent,
+                            menuItems = listOf(HostMenuItem("Unpin card", startsSection = true) {}),
+                            reserveProfileSlot = true,
+                        )
+                    }
+                }
            }
            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)
+                HostCard(
+                    h.name, h.address, h.status, online = h.online,
+                    enabled = true, onConnect = {}, onForget = null,
+                )
            }
        }
    }
 }

-/** The real SettingsScreen, fed a representative non-default Settings. */
+/** A representative non-default settings state, shared by the settings scenes. */
+private val SHOT_SETTINGS = Settings(
+    width = 1920,
+    height = 1080,
+    hz = 120,
+    bitrateKbps = 50_000,
+    compositor = 1,
+    gamepad = 2,
+    micEnabled = true,
+    statsVerbosity = StatsVerbosity.DETAILED,
+    touchMode = TouchMode.TRACKPAD,
+)
+
+/**
+ * The real SettingsScreen at its root — the shared category map (General / Display / Input /
+ * Audio / Controllers / About) every client now presents.
+ */
@Composable
 internal fun SettingsScene() {
+    Surface(Modifier.fillMaxSize(), color = MaterialTheme.colorScheme.background) {
+        SettingsScreen(initial = SHOT_SETTINGS, onChange = {}, onBack = {})
+    }
+}
+
+/**
+ * One category page, seeded through `initialCategory` — the sub-section headers, the
+ * caption-under-control fields and the "applies from the next session" footer only exist inside a
+ * category, so the root shot alone can't regress-catch them. Display is the richest page.
+ */
+@Composable
+internal fun SettingsCategoryScene(category: SettingsCategory) {
    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,
-                statsVerbosity = StatsVerbosity.DETAILED,
-                touchMode = TouchMode.TRACKPAD,
-            ),
+            initial = SHOT_SETTINGS,
            onChange = {},
            onBack = {},
+            initialCategory = category,
        )
    }
 }

+/**
+ * The same settings surface in a PROFILE's scope: the scope chips with "Game" selected, only
+ * profileable rows, every row showing the effective value, and the overridden ones carrying their
+ * marker and reset. One settings UI, two layers — this shot is what proves it stayed one.
+ */
+@Composable
+internal fun SettingsProfileScene() {
+    val store = ProfileStore(LocalContext.current)
+    val profile = remember {
+        val p = newProfile("Game").copy(
+            accent = "#FF8A4C",
+            // A representative mix: a resolution and refresh the profile pins, and a codec — the
+            // rest of the page keeps following the defaults, visibly unmarked.
+            overrides = SettingsOverlay(width = 3840, height = 2160, hz = 120, codec = "h264"),
+        )
+        store.save(p)
+        store.save(newProfile("Work"))
+        p
+    }
+    Surface(Modifier.fillMaxSize(), color = MaterialTheme.colorScheme.background) {
+        SettingsScreen(
+            initial = SHOT_SETTINGS,
+            onChange = {},
+            onBack = {},
+            initialCategory = SettingsCategory.Display,
+            initialProfileId = profile.id,
+        )
+    }
+}
+
+/**
+ * The speed test's result, in its most interesting shape: a host bound to a profile that INHERITS
+ * bitrate, so both layers are defensible and both buttons are offered. The note under the numbers
+ * is what stops "Apply" from being a write in an unknown direction.
+ */
+@Composable
+internal fun SpeedTestScene() {
+    SpeedTestDialog(
+        hostName = "Living Room PC",
+        target = SpeedTestTarget.Ask(newProfile("Game")),
+        phase = SpeedTestPhase.Done(throughputKbps = 412_000, lossPct = 0.3, recommendedKbps = 288_400),
+        onApply = {},
+        onDismiss = {},
+    )
+}
+
+/**
+ * Creating a profile. Small, but it is the first thing a user meets when they reach for this
+ * feature — and dialogs only get a shot each because a layout slip inside one is invisible from
+ * every other scene (this one shipped with the field and its caption touching).
+ */
+@Composable
+internal fun NewProfileScene() {
+    Surface(Modifier.fillMaxSize(), color = MaterialTheme.colorScheme.background) {
+        Column(Modifier.padding(24.dp), verticalArrangement = Arrangement.spacedBy(16.dp)) {
+            Text("New profile", style = MaterialTheme.typography.headlineSmall)
+            // The dialog's own body, not a rebuild of it — the layout under test is the real one.
+            ProfileEditorFields(
+                name = "Travel",
+                accent = "#60A5FA",
+                duplicate = false,
+                creating = true,
+                onNameChange = {},
+                onAccentChange = {},
+            )
+            Text("Duplicate name", style = MaterialTheme.typography.headlineSmall)
+            ProfileEditorFields(
+                name = "Game",
+                accent = "#FF8A4C",
+                duplicate = true,
+                creating = false,
+                onNameChange = {},
+                onAccentChange = {},
+            )
+        }
+    }
+}
+
 /** The real TOFU AlertDialog (mirrors ConnectScreen's PendingTrust.Kind.TRUST_NEW), shown over the host grid. */
@Composable
 internal fun TrustDialog() {
@@ -211,6 +366,8 @@ internal fun StreamScene(verbosity: StatsVerbosity = StatsVerbosity.DETAILED) {
                10.0, 9.0, 16.0, 1.0, 0.9, 0.4, 0.6, 0.3,
                2.0, 1.0, 5.0, 238.0,
                1.0, 0.5, 1.8, 2.6,
+                // Timeline-presenter split: pace + latch tile the display term; presents ≈ fps.
+                0.2, 0.3, 236.0, 1.0,
            ),
            verbosity = verbosity,
            decoderLabel = "c2.qti.hevc.decoder · low-latency",
@@ -2,10 +2,10 @@
 // org.jetbrains.kotlin.android (it's an error under AGP 9). The Compose compiler plugin is declared
 // here (version + apply false) so modules can apply it version-less; its version pins the build's
 // Kotlin (compose-compiler and Kotlin release in lockstep), keeping them matched.
-// Toolchain: AGP 9.2.0 · Gradle 9.4.1 · Kotlin/Compose-compiler 2.3.21 · JDK 21 · Compose BOM
+// Toolchain: AGP 9.3.1 · Gradle 9.5.0 · Kotlin/Compose-compiler 2.3.21 · JDK 21 · Compose BOM
 // 2026.05.01 · compileSdk 37 · targetSdk 37 · minSdk 28.
 plugins {
-    id("com.android.application") version "9.2.1" apply false
-    id("com.android.library") version "9.2.1" apply false
+    id("com.android.application") version "9.3.1" apply false
+    id("com.android.library") version "9.3.1" apply false
    id("org.jetbrains.kotlin.plugin.compose") version "2.3.21" apply false
 }
@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-9.4.1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.5.0-bin.zip
 networkTimeout=10000
 retries=0
 retryBackOffMs=500
@@ -33,7 +33,11 @@ dependencies {
    // mTLS HTTPS client for the host's management API (the game-library fetch + cover-art loads).
    // OkHttp lets us present the paired client cert and pin the host's self-signed cert by SHA-256.
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
-    testImplementation("junit:junit:4.13.2") // JVM unit test for the pure TXT parser
+    testImplementation("junit:junit:4.13.2") // JVM unit tests for the pure parsers/migrations
+    // A REAL org.json on the unit-test classpath. android.jar's org.json is stubs that throw
+    // "Stub!", so the host-store migration test — which asserts over the very JSON blobs the store
+    // reads and writes — cannot run without it. Explicit test deps precede the mockable android.jar.
+    testImplementation("org.json:json:20250107")
 }

 // ------------------------------------------------------------------------------------------------
@@ -43,7 +47,11 @@ dependencies {
 // /README.md): `cargo install cargo-ndk` + `rustup target add aarch64-linux-android x86_64-linux-android`.
 // ------------------------------------------------------------------------------------------------
 val repoRoot = rootDir.parentFile.parentFile // clients/android -> clients -> repo root
-val cargoBin = "${System.getProperty("user.home")}/.cargo/bin"
+// CARGO_HOME first: rustup puts every binary in $CARGO_HOME/bin, and the CI image
+// (ci/android-ci.Dockerfile) installs the shared toolchain at /usr/local/cargo — the
+// historical ~/.cargo fallback is what a GUI Android Studio launch (no env) still needs.
+val cargoBin = System.getenv("CARGO_HOME")?.let { "$it/bin" }
+    ?: "${System.getProperty("user.home")}/.cargo/bin"

 // SDK location without depending on AGP's DSL (sdkDirectory isn't in AGP 9's library extension):
 // env first (set by Android Studio and by our CLI shell), then local.properties, then the default.
@@ -0,0 +1,301 @@
+package io.unom.punktfunk.kit
+
+import android.content.Context
+import android.hardware.usb.UsbDevice
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import android.view.InputDevice
+
+/**
+ * One captured Sony pad (DualSense / DualSense Edge / DualShock 4) over USB — stream mode only.
+ * The capture exists to fix what the InputDevice path structurally can't: rumble depends on the
+ * phone's kernel exposing force feedback (many don't), and adaptive triggers / lightbar / player
+ * LEDs have NO platform API at all. Claiming the pad's HID interface makes all of it work on any
+ * phone, plus gyro + touchpad the standard path never captured.
+ *
+ * Unlike [Sc2Capture] there is no raw passthrough — the host's DualSense/DS4 backends consume
+ * only typed events — and no UI mode: an UNcaptured Sony pad is a perfectly good InputDevice, so
+ * outside a stream the ordinary path drives the console UI and this class isn't constructed.
+ * That also makes the InputDevice path the automatic fallback whenever the capture doesn't
+ * engage (toggle off, permission denied, Bluetooth).
+ *
+ * Input: parse ([DsDevice.parseState]) → typed mirror on an [GamepadRouter.ExternalPad] (buttons
+ * diffed, axes on-change — the exit chord participates like any pad) + the rich plane (touch
+ * normalized to the wire's 0..65535 screen space on-change; motion forwarded per report in raw
+ * device units, the wire's contract). The wire slot is claimed lazily on the FIRST parsed report
+ * and freed on unplug/[stop], so indices never leak.
+ *
+ * Feedback: implements [GamepadFeedback.PadFeedbackSink] — rumble / trigger / lightbar / player
+ * LED events addressed to this pad's wire index become USB output reports on the physical pad
+ * ([DsDevice] builders). Rendering runs on the feedback poll threads; [HidUsbLink.writeRaw] is
+ * thread-safe (bounded newest-wins queue, submitted by the reader thread). A USB pad holds its
+ * rumble level until written zero, so a backstop timer re-arms per command and writes the stop
+ * itself if the poll thread stalls — the engine's explicit zeros remain the real stop mechanism.
+ */
+class DsCapture(
+    context: Context,
+    private val router: GamepadRouter,
+) : GamepadFeedback.PadFeedbackSink {
+    private val usb = HidUsbLink(
+        context,
+        HidUsbLink.Config(
+            tag = TAG,
+            threadName = "pf-ds-usb",
+            deviceMatch = { it.vendorId == DsDevice.VID_SONY && it.productId in DsDevice.USB_PIDS },
+            // No ifaceFilter: the pad's audio interfaces are not HID class, so the link's built-in
+            // class check already leaves them (and the pad's headset routing) to Android; the
+            // single HID interface is the only claim.
+        ),
+        ::onReport,
+        ::onLinkClosed,
+    )
+
+    @Volatile private var model: DsDevice.Model? = null
+    @Volatile private var pad: GamepadRouter.ExternalPad? = null
+
+    // Typed-mirror diff state (wire units) + rich-plane on-change mirrors. Link thread only.
+    private val state = DsDevice.State()
+    private var wireButtons = 0
+    private val lastAxis = IntArray(6) { Int.MIN_VALUE }
+    private val lastTouchActive = BooleanArray(2)
+    private val lastTouchX = IntArray(2) { -1 }
+    private val lastTouchY = IntArray(2) { -1 }
+
+    // DS4 composed feedback (its writes are full-state — see DsDevice.ds4Report). Feedback threads.
+    // The lightbar starts at hid-sony's player-1 blue so the first composed write (usually a
+    // rumble, before any host Led lands) doesn't black the bar out.
+    @Volatile private var ds4Low = 0
+    @Volatile private var ds4High = 0
+    @Volatile private var ds4Rgb = 0x000040
+
+    // Rumble backstop: a USB pad holds its level until told zero, so a stalled poll thread would
+    // leave the motors running — re-armed per command, cancelled by an explicit (0,0).
+    private val mainHandler = Handler(Looper.getMainLooper())
+    @Volatile private var backstop: Runnable? = null
+
+    /** Fired (link thread) when the capture engages or drops — the Controllers screen's status. */
+    @Volatile
+    var onActiveChanged: ((active: Boolean) -> Unit)? = null
+
+    val isActive: Boolean get() = model != null
+
+    /** First attached Sony USB pad, for the permission flow. Needs no permission to enumerate. */
+    fun findUsbDevice(): UsbDevice? = usb.findDevice()
+
+    /**
+     * Start capturing [dev] (permission already granted). Claims the HID interface — the kernel
+     * driver detaches and the pad's InputDevice node vanishes; its router slot (if the router
+     * already opened one from the pre-claim InputDevice) is released HERE, at claim time, rather
+     * than waiting for the system's removal callback — so the freed wire index is deterministic
+     * for this capture's ExternalPad instead of racing the first report against the callback. A
+     * released sibling that still exists as an InputDevice (a same-model Bluetooth pad) lazily
+     * reopens a slot on its next input event, so over-matching self-heals.
+     */
+    fun startUsb(dev: UsbDevice): Boolean {
+        if (model != null) return false
+        val m = DsDevice.modelFor(dev.productId) ?: return false
+        if (!usb.start(dev)) return false
+        model = m
+        for (id in InputDevice.getDeviceIds()) {
+            val d = InputDevice.getDevice(id) ?: continue
+            if (d.vendorId == dev.vendorId && d.productId == dev.productId) router.releaseDevice(id)
+        }
+        // Release the firmware's lightbar animation once so host lightbar writes take effect
+        // (the same init hid-playstation/SDL send on open).
+        if (m != DsDevice.Model.DUALSHOCK4) usb.writeRaw(0, DsDevice.ds5InitReport(m))
+        Log.i(TAG, "Sony pad captured over USB: PID=0x%04x model=%s".format(dev.productId, m))
+        onActiveChanged?.invoke(true)
+        return true
+    }
+
+    /** Stop the link and free the wire slot (host tears the virtual pad down). Idempotent. */
+    fun stop() {
+        val m = model
+        if (m != null) {
+            // The interfaces are about to release with the kernel driver still detached — a
+            // mid-rumble teardown would leave the motors running with nobody to stop them.
+            // EP0-direct (the reader thread is stopping; the queue would never drain).
+            usb.writeControl(stopReport(m))
+        }
+        disarmBackstop()
+        usb.stop()
+        val wasActive = model != null
+        model = null
+        releaseSlot()
+        if (wasActive) onActiveChanged?.invoke(false)
+    }
+
+    // ---- link callbacks (link thread) ----
+
+    private fun onReport(report: ByteArray, len: Int) {
+        val m = model ?: return
+        if (!DsDevice.parseState(m, report, len, state)) return
+        val p = pad ?: router.openExternal(m.pref)?.also {
+            pad = it
+            Log.i(TAG, "captured $m → wire pad ${it.index}")
+        } ?: return // all 16 wire indices taken — drop until one frees
+        mirrorTyped(p)
+        mirrorRich(p, m)
+    }
+
+    private fun onLinkClosed() {
+        Log.i(TAG, "Sony USB link closed (unplug)")
+        disarmBackstop()
+        val wasActive = model != null
+        model = null
+        releaseSlot()
+        if (wasActive) onActiveChanged?.invoke(false)
+    }
+
+    /** Diff the parsed state onto the per-transition plane (buttons + axes, on change only). */
+    private fun mirrorTyped(p: GamepadRouter.ExternalPad) {
+        var changed = state.buttons xor wireButtons
+        while (changed != 0) {
+            val bit = changed and -changed // lowest changed bit
+            p.button(bit, state.buttons and bit != 0)
+            changed = changed and bit.inv()
+        }
+        wireButtons = state.buttons
+        axis(p, Gamepad.AXIS_LS_X, state.lsX)
+        axis(p, Gamepad.AXIS_LS_Y, state.lsY)
+        axis(p, Gamepad.AXIS_RS_X, state.rsX)
+        axis(p, Gamepad.AXIS_RS_Y, state.rsY)
+        axis(p, Gamepad.AXIS_LT, state.lt)
+        axis(p, Gamepad.AXIS_RT, state.rt)
+    }
+
+    private fun axis(p: GamepadRouter.ExternalPad, id: Int, v: Int) {
+        if (lastAxis[id] == v) return
+        lastAxis[id] = v
+        p.axis(id, v)
+    }
+
+    /**
+     * The rich plane: touch contacts normalized to the wire's 0..65535 screen space, forwarded
+     * on change per slot; motion forwarded every report (raw device units — the wire is a unit
+     * passthrough into the host's virtual pad, and sensor noise makes per-report dedup pointless).
+     */
+    private fun mirrorRich(p: GamepadRouter.ExternalPad, m: DsDevice.Model) {
+        for (f in 0 until 2) {
+            if (state.touchActive[f]) {
+                val x = (state.touchX[f].coerceIn(0, m.touchW - 1) * 65535) / (m.touchW - 1)
+                val y = (state.touchY[f].coerceIn(0, m.touchH - 1) * 65535) / (m.touchH - 1)
+                if (!lastTouchActive[f] || x != lastTouchX[f] || y != lastTouchY[f]) {
+                    p.touch(f, true, x, y)
+                    lastTouchActive[f] = true
+                    lastTouchX[f] = x
+                    lastTouchY[f] = y
+                }
+            } else if (lastTouchActive[f]) {
+                p.touch(f, false, lastTouchX[f], lastTouchY[f])
+                lastTouchActive[f] = false
+            }
+        }
+        p.motion(state.gyro, state.accel)
+    }
+
+    private fun releaseSlot() {
+        // Lift any still-touching finger so the host's virtual touchpad doesn't hold a contact.
+        val p = pad
+        if (p != null) {
+            for (f in 0 until 2) if (lastTouchActive[f]) p.touch(f, false, lastTouchX[f], lastTouchY[f])
+        }
+        p?.close()
+        pad = null
+        wireButtons = 0
+        lastAxis.fill(Int.MIN_VALUE)
+        lastTouchActive.fill(false)
+        lastTouchX.fill(-1)
+        lastTouchY.fill(-1)
+    }
+
+    // ---- PadFeedbackSink (feedback poll threads) ----
+
+    override fun ownsPad(pad: Int): Boolean = pad == this.pad?.index
+
+    override fun rumble(pad: Int, low: Int, high: Int, backstopMs: Long) {
+        val m = model ?: return
+        if (low == 0 && high == 0) {
+            disarmBackstop()
+        } else {
+            armBackstop(backstopMs)
+        }
+        if (m == DsDevice.Model.DUALSHOCK4) {
+            ds4Low = low
+            ds4High = high
+            writeDs4()
+        } else {
+            usb.writeRaw(0, DsDevice.ds5RumbleReport(m, low, high))
+        }
+    }
+
+    override fun led(pad: Int, r: Int, g: Int, b: Int) {
+        val m = model ?: return
+        if (m == DsDevice.Model.DUALSHOCK4) {
+            ds4Rgb = (r shl 16) or (g shl 8) or b
+            writeDs4()
+        } else {
+            usb.writeRaw(0, DsDevice.ds5LightbarReport(m, r, g, b))
+        }
+    }
+
+    override fun playerLeds(pad: Int, bits: Int) {
+        val m = model ?: return
+        if (m == DsDevice.Model.DUALSHOCK4) return // no player LEDs on a DS4 (host never sends any)
+        usb.writeRaw(0, DsDevice.ds5PlayerLedsReport(m, bits))
+    }
+
+    override fun trigger(pad: Int, which: Int, effect: ByteArray) {
+        val m = model ?: return
+        if (m == DsDevice.Model.DUALSHOCK4) return // no adaptive triggers on a DS4
+        usb.writeRaw(0, DsDevice.ds5TriggerReport(m, which, effect))
+    }
+
+    private fun writeDs4() = usb.writeRaw(
+        0,
+        DsDevice.ds4Report(
+            ds4Low,
+            ds4High,
+            (ds4Rgb shr 16) and 0xFF,
+            (ds4Rgb shr 8) and 0xFF,
+            ds4Rgb and 0xFF,
+        ),
+    )
+
+    /** The report that stops the motors. The DS4's is a full-state write, so it zeroes the
+     *  composed motor state and carries the current lightbar rather than blacking it out. */
+    private fun stopReport(m: DsDevice.Model): ByteArray = if (m == DsDevice.Model.DUALSHOCK4) {
+        ds4Low = 0
+        ds4High = 0
+        DsDevice.ds4Report(
+            0,
+            0,
+            (ds4Rgb shr 16) and 0xFF,
+            (ds4Rgb shr 8) and 0xFF,
+            ds4Rgb and 0xFF,
+        )
+    } else {
+        DsDevice.ds5RumbleReport(m, 0, 0)
+    }
+
+    /** (Re)arm the stalled-poll-thread net: write a rumble stop at the command's backstop. */
+    private fun armBackstop(ms: Long) {
+        backstop?.let { mainHandler.removeCallbacks(it) }
+        val r = Runnable {
+            backstop = null
+            model?.let { usb.writeRaw(0, stopReport(it)) }
+        }
+        backstop = r
+        mainHandler.postDelayed(r, ms.coerceAtLeast(1))
+    }
+
+    private fun disarmBackstop() {
+        backstop?.let { mainHandler.removeCallbacks(it) }
+        backstop = null
+    }
+
+    private companion object {
+        const val TAG = "DsCapture"
+    }
+}
@@ -0,0 +1,340 @@
+package io.unom.punktfunk.kit
+
+/**
+ * Sony DualSense / DualSense Edge / DualShock 4 **USB** protocol constants: the input-report
+ * parser and the output-report builders the capture link ([DsCapture]) needs. Unlike the SC2's
+ * as-is passthrough, nothing rides the wire raw here — the host's DualSense/DS4 backends consume
+ * only typed events (`dualsense_proto.rs` discards `RichInput::HidReport`), so the client parses
+ * the pad's input reports into the ordinary button/axis wire + the rich touch/motion plane, and
+ * renders the host's feedback (rumble / adaptive triggers / lightbar / player LEDs) by composing
+ * USB output reports itself.
+ *
+ * Protocol ground truth: the Linux kernel's `hid-playstation` / `hid-sony` structs, SDL's
+ * `SDL_hidapi_ps5.c` / `SDL_hidapi_ps4.c`, mirrored host-side in `punktfunk-host`'s
+ * `dualsense_proto.rs` / `dualshock4_proto.rs` — this file is the byte-exact inverse of those
+ * serializers (offsets cross-referenced below). USB only: over Bluetooth the reports shift
+ * (`0x31` + CRC32) AND Android exposes no raw path to a Classic pad anyway, so the BT case never
+ * reaches this code — an uncaptured pad stays on the ordinary InputDevice path.
+ */
+object DsDevice {
+    const val VID_SONY = 0x054C
+    const val PID_DUALSENSE = 0x0CE6
+    const val PID_DUALSENSE_EDGE = 0x0DF2
+    const val PID_DUALSHOCK4_V1 = 0x05C4
+    const val PID_DUALSHOCK4_V2 = 0x09CC
+
+    val USB_PIDS = setOf(PID_DUALSENSE, PID_DUALSENSE_EDGE, PID_DUALSHOCK4_V1, PID_DUALSHOCK4_V2)
+
+    /**
+     * One captured model: its `GamepadPref` wire byte (the virtual pad the host builds — matching
+     * the physical one), its output-report size (the descriptor-declared size the firmware
+     * expects: DS5 48 = id + 47, Edge 64 = id + 63, DS4 32 = id + 31), and its touchpad extent
+     * (`dualsense_proto::DS_TOUCH_W/H`, `dualshock4_proto::DS4_TOUCH_*`) for normalizing touches
+     * onto the wire's 0..65535 space.
+     */
+    enum class Model(val pref: Int, val outputSize: Int, val touchW: Int, val touchH: Int) {
+        DUALSENSE(Gamepad.PREF_DUALSENSE, 48, 1920, 1080),
+        DUALSENSE_EDGE(Gamepad.PREF_DUALSENSEEDGE, 64, 1920, 1080),
+        DUALSHOCK4(Gamepad.PREF_DUALSHOCK4, 32, 1920, 942),
+    }
+
+    /** The captured [Model] for a USB PID, or null for anything we don't capture. */
+    fun modelFor(pid: Int): Model? = when (pid) {
+        PID_DUALSENSE -> Model.DUALSENSE
+        PID_DUALSENSE_EDGE -> Model.DUALSENSE_EDGE
+        PID_DUALSHOCK4_V1, PID_DUALSHOCK4_V2 -> Model.DUALSHOCK4
+        else -> null
+    }
+
+    /**
+     * The client-consumed fields of one input report. `buttons` is already the WIRE bitmask
+     * (`Gamepad.BTN_*`) — the parse maps device bits straight to the wire, the exact inverse of
+     * the host's `DsState::from_gamepad` (BTN_A ↔ cross, BTN_B ↔ circle, BTN_X ↔ square,
+     * BTN_Y ↔ triangle; positional, not glyph-order). Gyro/accel stay in raw device units — the
+     * wire's `Motion` is a unit passthrough into the virtual pad's report. Touch coordinates stay
+     * device-raw here; [DsCapture] normalizes against the model's extent when forwarding.
+     */
+    class State {
+        var buttons = 0
+        var lsX = 0; var lsY = 0 // wire i16, +y = up (device is +y down — inverted in the parse)
+        var rsX = 0; var rsY = 0
+        var lt = 0; var rt = 0 // 0..255
+        val gyro = IntArray(3) // raw i16 units (pitch/yaw/roll)
+        val accel = IntArray(3)
+        val touchActive = BooleanArray(2)
+        val touchX = IntArray(2) // raw device coords (0..touchW-1 / 0..touchH-1)
+        val touchY = IntArray(2)
+    }
+
+    // DS5 USB input report 0x01 (64 B) — offsets mirror the host serializer
+    // (`dualsense_proto.rs::serialize_state`): [1..7) sticks + triggers, [8] hat|face,
+    // [9]/[10] buttons, [16..28) gyro+accel, [33..41) two 4-byte touch points.
+    private const val DS5_INPUT_ID = 0x01
+    // report[8] high nibble (`dualsense_proto::btn0`).
+    private const val DS5_SQUARE = 0x10
+    private const val DS5_CROSS = 0x20
+    private const val DS5_CIRCLE = 0x40
+    private const val DS5_TRIANGLE = 0x80
+    // report[9] (`btn1`).
+    private const val DS5_L1 = 0x01
+    private const val DS5_R1 = 0x02
+    private const val DS5_CREATE = 0x10
+    private const val DS5_OPTIONS = 0x20
+    private const val DS5_L3 = 0x40
+    private const val DS5_R3 = 0x80
+    // report[10] (`btn2`); the FN/BACK bits exist only on the Edge.
+    private const val DS5_PS = 0x01
+    private const val DS5_TOUCHPAD = 0x02
+    private const val DS5_MUTE = 0x04
+    private const val EDGE_FN_LEFT = 0x10
+    private const val EDGE_FN_RIGHT = 0x20
+    private const val EDGE_BACK_LEFT = 0x40
+    private const val EDGE_BACK_RIGHT = 0x80
+
+    // DS4 USB input report 0x01 (64 B) — offsets mirror `dualshock4_proto.rs::serialize_state`:
+    // [1..5) sticks, [5] hat|face, [6]/[7] buttons, [8]/[9] triggers, [13..25) gyro+accel,
+    // [35..43) two touch points (same 4-byte packing as the DS5).
+    private const val DS4_L1 = 0x01
+    private const val DS4_R1 = 0x02
+    private const val DS4_SHARE = 0x10
+    private const val DS4_OPTIONS = 0x20
+    private const val DS4_L3 = 0x40
+    private const val DS4_R3 = 0x80
+    private const val DS4_PS = 0x01
+    private const val DS4_TOUCHPAD = 0x02
+
+    /**
+     * Parse one USB input report (`0x01`) into [out]. Returns false for any other report id or a
+     * short read (the pad also emits `0x09`-family getMAC responses etc. on EP0 — those never hit
+     * the interrupt endpoint, but be defensive). Motion/touch fields update only when the report
+     * is long enough to carry them (it always is on glass — 64-byte interrupt transfers).
+     */
+    fun parseState(model: Model, report: ByteArray, len: Int, out: State): Boolean =
+        if (model == Model.DUALSHOCK4) {
+            parseDs4(report, len, out)
+        } else {
+            parseDs5(model, report, len, out)
+        }
+
+    private fun parseDs5(model: Model, r: ByteArray, len: Int, out: State): Boolean {
+        if (len < 11 || (r[0].toInt() and 0xFF) != DS5_INPUT_ID) return false
+        out.lsX = stickX(u8(r, 1))
+        out.lsY = stickY(u8(r, 2))
+        out.rsX = stickX(u8(r, 3))
+        out.rsY = stickY(u8(r, 4))
+        out.lt = u8(r, 5)
+        out.rt = u8(r, 6)
+        val b8 = u8(r, 8)
+        val b9 = u8(r, 9)
+        val b10 = u8(r, 10)
+        var w = hatBits(b8 and 0x0F)
+        if (b8 and DS5_CROSS != 0) w = w or Gamepad.BTN_A
+        if (b8 and DS5_CIRCLE != 0) w = w or Gamepad.BTN_B
+        if (b8 and DS5_SQUARE != 0) w = w or Gamepad.BTN_X
+        if (b8 and DS5_TRIANGLE != 0) w = w or Gamepad.BTN_Y
+        if (b9 and DS5_L1 != 0) w = w or Gamepad.BTN_LB
+        if (b9 and DS5_R1 != 0) w = w or Gamepad.BTN_RB
+        // L2/R2 digital bits ride the analog axes instead (wire convention).
+        if (b9 and DS5_CREATE != 0) w = w or Gamepad.BTN_BACK
+        if (b9 and DS5_OPTIONS != 0) w = w or Gamepad.BTN_START
+        if (b9 and DS5_L3 != 0) w = w or Gamepad.BTN_LS_CLICK
+        if (b9 and DS5_R3 != 0) w = w or Gamepad.BTN_RS_CLICK
+        if (b10 and DS5_PS != 0) w = w or Gamepad.BTN_GUIDE
+        if (b10 and DS5_TOUCHPAD != 0) w = w or Gamepad.BTN_TOUCHPAD
+        if (b10 and DS5_MUTE != 0) w = w or Gamepad.BTN_MISC1
+        if (model == Model.DUALSENSE_EDGE) {
+            // Wire paddle order matches the host's `edge_paddle_bits` inverse: PADDLE1/2 =
+            // right/left BACK (the primary pair, Steam R4/L4 convention), PADDLE3/4 = right/left Fn.
+            if (b10 and EDGE_BACK_RIGHT != 0) w = w or Gamepad.BTN_PADDLE1
+            if (b10 and EDGE_BACK_LEFT != 0) w = w or Gamepad.BTN_PADDLE2
+            if (b10 and EDGE_FN_RIGHT != 0) w = w or Gamepad.BTN_PADDLE3
+            if (b10 and EDGE_FN_LEFT != 0) w = w or Gamepad.BTN_PADDLE4
+        }
+        out.buttons = w
+        if (len >= 28) {
+            for (i in 0 until 3) out.gyro[i] = i16(r, 16 + 2 * i)
+            for (i in 0 until 3) out.accel[i] = i16(r, 22 + 2 * i)
+        }
+        if (len >= 41) {
+            unpackTouch(r, 33, out, 0)
+            unpackTouch(r, 37, out, 1)
+        }
+        return true
+    }
+
+    private fun parseDs4(r: ByteArray, len: Int, out: State): Boolean {
+        if (len < 10 || (r[0].toInt() and 0xFF) != DS5_INPUT_ID) return false // DS4 shares id 0x01
+        out.lsX = stickX(u8(r, 1))
+        out.lsY = stickY(u8(r, 2))
+        out.rsX = stickX(u8(r, 3))
+        out.rsY = stickY(u8(r, 4))
+        val b5 = u8(r, 5)
+        val b6 = u8(r, 6)
+        val b7 = u8(r, 7)
+        out.lt = u8(r, 8)
+        out.rt = u8(r, 9)
+        var w = hatBits(b5 and 0x0F)
+        if (b5 and DS5_CROSS != 0) w = w or Gamepad.BTN_A
+        if (b5 and DS5_CIRCLE != 0) w = w or Gamepad.BTN_B
+        if (b5 and DS5_SQUARE != 0) w = w or Gamepad.BTN_X
+        if (b5 and DS5_TRIANGLE != 0) w = w or Gamepad.BTN_Y
+        if (b6 and DS4_L1 != 0) w = w or Gamepad.BTN_LB
+        if (b6 and DS4_R1 != 0) w = w or Gamepad.BTN_RB
+        if (b6 and DS4_SHARE != 0) w = w or Gamepad.BTN_BACK
+        if (b6 and DS4_OPTIONS != 0) w = w or Gamepad.BTN_START
+        if (b6 and DS4_L3 != 0) w = w or Gamepad.BTN_LS_CLICK
+        if (b6 and DS4_R3 != 0) w = w or Gamepad.BTN_RS_CLICK
+        if (b7 and DS4_PS != 0) w = w or Gamepad.BTN_GUIDE
+        if (b7 and DS4_TOUCHPAD != 0) w = w or Gamepad.BTN_TOUCHPAD
+        out.buttons = w
+        if (len >= 25) {
+            for (i in 0 until 3) out.gyro[i] = i16(r, 13 + 2 * i)
+            for (i in 0 until 3) out.accel[i] = i16(r, 19 + 2 * i)
+        }
+        if (len >= 43) {
+            unpackTouch(r, 35, out, 0)
+            unpackTouch(r, 39, out, 1)
+        }
+        return true
+    }
+
+    /** hat nibble (0=N … 7=NW, 8+=neutral) → wire dpad bits — inverse of the host's `hat()`. */
+    private fun hatBits(h: Int): Int = when (h) {
+        0 -> Gamepad.BTN_DPAD_UP
+        1 -> Gamepad.BTN_DPAD_UP or Gamepad.BTN_DPAD_RIGHT
+        2 -> Gamepad.BTN_DPAD_RIGHT
+        3 -> Gamepad.BTN_DPAD_DOWN or Gamepad.BTN_DPAD_RIGHT
+        4 -> Gamepad.BTN_DPAD_DOWN
+        5 -> Gamepad.BTN_DPAD_DOWN or Gamepad.BTN_DPAD_LEFT
+        6 -> Gamepad.BTN_DPAD_LEFT
+        7 -> Gamepad.BTN_DPAD_UP or Gamepad.BTN_DPAD_LEFT
+        else -> 0
+    }
+
+    /**
+     * One 4-byte touch point (shared DS5/DS4 packing — `dualsense_proto::pack_touch`): byte0
+     * bit7 = NOT active + contact id in bits 0..6; 12-bit x/y split across bytes 1..3.
+     */
+    private fun unpackTouch(r: ByteArray, o: Int, out: State, slot: Int) {
+        val b0 = u8(r, o)
+        out.touchActive[slot] = b0 and 0x80 == 0
+        out.touchX[slot] = u8(r, o + 1) or ((u8(r, o + 2) and 0x0F) shl 8)
+        out.touchY[slot] = (u8(r, o + 2) shr 4) or (u8(r, o + 3) shl 4)
+    }
+
+    private fun u8(r: ByteArray, o: Int): Int = r[o].toInt() and 0xFF
+
+    private fun i16(r: ByteArray, o: Int): Int =
+        ((r[o + 1].toInt() shl 8) or (r[o].toInt() and 0xFF)).toShort().toInt()
+
+    // Device stick byte (0..255, centre 0x80, +y down) → wire i16 (+y up) — the exact inverse of
+    // the host's `to_u8` mapping (`lx = to_u8(x)`, `ly = 255 - to_u8(y)`).
+    private fun stickX(raw: Int): Int = raw * 257 - 32768
+
+    private fun stickY(raw: Int): Int = (255 - raw) * 257 - 32768
+
+    // ---- Output reports ----
+    //
+    // Every write is valid-flag-selective: only the flagged channel applies, the firmware keeps
+    // the rest (the same contract the host's `parse_ds_output` mirrors — an unflagged parse would
+    // turn every rumble into a lightbar-off). The DS4 is the exception: its builder writes the
+    // full composed motors+LED state each time with both flags, SDL's proven-on-hardware shape.
+
+    // DS5 output report 0x02, report-relative offsets (`dualsense_proto::parse_ds_output`):
+    // [1] valid_flag0 (bit0 compat vibration, bit1 haptics select, bit2 R2 block, bit3 L2 block),
+    // [2] valid_flag1 (bit2 lightbar, bit4 player LEDs), [3]/[4] motors, [11..22) R2 effect,
+    // [22..33) L2 effect, [39] valid_flag2 (bit1 lightbar-setup enable, bit2 vibration2),
+    // [42] lightbar_setup, [44] player LEDs, [45..48) RGB.
+    private const val DS5_FLAG0_COMPAT_VIBRATION = 0x01
+    private const val DS5_FLAG0_HAPTICS_SELECT = 0x02
+    private const val DS5_FLAG0_R2_EFFECT = 0x04
+    private const val DS5_FLAG0_L2_EFFECT = 0x08
+    private const val DS5_FLAG1_LIGHTBAR = 0x04
+    private const val DS5_FLAG1_PLAYER_LEDS = 0x10
+    private const val DS5_FLAG2_LIGHTBAR_SETUP = 0x02
+    private const val DS5_FLAG2_VIBRATION2 = 0x04
+    private const val DS5_LIGHTBAR_SETUP_LIGHT_OUT = 0x02
+
+    /** The 11-byte adaptive-trigger effect block length (mode byte + 10 parameters). */
+    const val TRIGGER_EFFECT_LEN = 11
+
+    private fun newDs5(model: Model): ByteArray = ByteArray(model.outputSize).also { it[0] = 0x02 }
+
+    /**
+     * One-time capture-start report (DS5/Edge): release the firmware's lightbar animation
+     * (`LIGHTBAR_SETUP_LIGHT_OUT`) so subsequent host lightbar writes take effect — the same
+     * init both hid-playstation and SDL send on open. No-op fields otherwise.
+     */
+    fun ds5InitReport(model: Model): ByteArray = newDs5(model).also {
+        it[39] = DS5_FLAG2_LIGHTBAR_SETUP.toByte()
+        it[42] = DS5_LIGHTBAR_SETUP_LIGHT_OUT.toByte()
+    }
+
+    /**
+     * DS5/Edge rumble at the wire's u16 amplitudes ([low] = heavy/left motor, [high] =
+     * light/right — the host parses `[3]` as high and `[4]` as low, mirrored here). Flags both
+     * the classic compat-vibration path AND `VIBRATION2` (firmware ≥ 2.24's full-range replot;
+     * older firmware ignores the unknown flag2 bit) — the host parser accepts either.
+     */
+    fun ds5RumbleReport(model: Model, low: Int, high: Int): ByteArray = newDs5(model).also {
+        it[1] = (DS5_FLAG0_COMPAT_VIBRATION or DS5_FLAG0_HAPTICS_SELECT).toByte()
+        it[39] = DS5_FLAG2_VIBRATION2.toByte()
+        it[3] = amp8(high).toByte()
+        it[4] = amp8(low).toByte()
+    }
+
+    /**
+     * DS5/Edge adaptive-trigger effect: [which] 0 = L2, 1 = R2; [effect] is the raw 11-byte
+     * trigger block from the wire (`HidOutput::Trigger` — the game's bytes verbatim), copied to
+     * the same offsets the host parsed it from ([11..22) R2 / [22..33) L2).
+     */
+    fun ds5TriggerReport(model: Model, which: Int, effect: ByteArray): ByteArray = newDs5(model).also {
+        val at = if (which == 1) 11 else 22
+        it[1] = (if (which == 1) DS5_FLAG0_R2_EFFECT else DS5_FLAG0_L2_EFFECT).toByte()
+        val n = effect.size.coerceAtMost(TRIGGER_EFFECT_LEN)
+        System.arraycopy(effect, 0, it, at, n)
+    }
+
+    /** DS5/Edge lightbar RGB. */
+    fun ds5LightbarReport(model: Model, r: Int, g: Int, b: Int): ByteArray = newDs5(model).also {
+        it[2] = DS5_FLAG1_LIGHTBAR.toByte()
+        it[45] = r.toByte()
+        it[46] = g.toByte()
+        it[47] = b.toByte()
+    }
+
+    /** DS5/Edge player-indicator LEDs (low 5 bits, hid-playstation pattern). */
+    fun ds5PlayerLedsReport(model: Model, bits: Int): ByteArray = newDs5(model).also {
+        it[2] = DS5_FLAG1_PLAYER_LEDS.toByte()
+        it[44] = (bits and 0x1F).toByte()
+    }
+
+    // DS4 output report 0x05 (32 B), report-relative (`dualshock4_proto::parse_ds4_output`):
+    // [1] valid_flag0 (bit0 motors, bit1 LED, bit2 blink), [4] weak/right motor, [5] strong/left,
+    // [6..9) RGB, [9]/[10] blink on/off.
+    private const val DS4_FLAG0_MOTORS = 0x01
+    private const val DS4_FLAG0_LED = 0x02
+
+    /**
+     * One full-state DS4 write: motors + lightbar together, both flags set — the composed-state
+     * shape SDL uses against real hardware (per-channel selective writes are unproven on DS4
+     * firmware, unlike the DS5's). [DsCapture] holds the composition. Blink stays untouched.
+     */
+    fun ds4Report(low: Int, high: Int, r: Int, g: Int, b: Int): ByteArray =
+        ByteArray(Model.DUALSHOCK4.outputSize).also {
+            it[0] = 0x05
+            it[1] = (DS4_FLAG0_MOTORS or DS4_FLAG0_LED).toByte()
+            it[4] = amp8(high).toByte()
+            it[5] = amp8(low).toByte()
+            it[6] = r.toByte()
+            it[7] = g.toByte()
+            it[8] = b.toByte()
+        }
+
+    // Wire u16 amplitude → motor byte; a nonzero command never collapses to 0 (parity with the
+    // vibrator path's toAmplitude).
+    private fun amp8(v16: Int): Int {
+        val a = (v16 ushr 8) and 0xFF
+        return if (v16 != 0 && a == 0) 1 else a
+    }
+}
@@ -46,6 +46,42 @@ class GamepadFeedback(
    private val router: GamepadRouter?,
    private val deviceVibrator: Vibrator? = null,
 ) {
+    /**
+     * A capture link's feedback renderer for the wire pads it owns, consulted BEFORE the
+     * InputDevice vibrator/lights paths. A captured controller has no [android.view.InputDevice]
+     * (its slot is an [GamepadRouter.ExternalPad] on a synthetic id, so [GamepadRouter.deviceForPad]
+     * resolves null and the platform paths no-op) — the link renders instead, by composing USB
+     * output reports on the physical pad. This is also the ONLY route to adaptive triggers:
+     * Android has no platform API for them, so without a sink a Trigger event is log-and-drop.
+     * Invoked on the feedback poll threads; implementations must be thread-safe.
+     */
+    interface PadFeedbackSink {
+        /** True when this sink renders feedback for wire pad [pad]; the render methods are only
+         *  invoked while true. Racing a pad close is fine — a late render is a harmless no-op. */
+        fun ownsPad(pad: Int): Boolean
+
+        /** One effective rumble command (`(0,0)` = stop now; else a one-shot at this level with
+         *  [backstopMs] as the self-termination net — see [GamepadFeedback.renderRumble]). */
+        fun rumble(pad: Int, low: Int, high: Int, backstopMs: Long)
+
+        /** Lightbar RGB. */
+        fun led(pad: Int, r: Int, g: Int, b: Int)
+
+        /** Player-indicator LED bitmask (low 5 bits, hid-playstation layout). */
+        fun playerLeds(pad: Int, bits: Int)
+
+        /** One adaptive-trigger effect: [which] 0 = L2, 1 = R2; [effect] = the raw DS5 trigger
+         *  block (mode byte + parameters) exactly as the game wrote it host-side. */
+        fun trigger(pad: Int, which: Int, effect: ByteArray)
+    }
+
+    /**
+     * The active capture link's sink (a [DsCapture]), or null. Wired by StreamScreen alongside
+     * [onHidRaw]; cleared before the poll threads stop.
+     */
+    @Volatile
+    var sink: PadFeedbackSink? = null
+
    private companion object {
        const val TAG = "pf.feedback"
        const val TAG_LED: Byte = 0x01
@@ -221,6 +257,12 @@ class GamepadFeedback(
        // controller 1 unconditionally rather than only motor-less pads — capability probing
        // already decided the bind, and the user opted in.
        if (pad == 0) renderDeviceRumble(low, high, durationMs)
+        // A captured pad's link renders on the physical controller itself (its slot has no
+        // InputDevice, so the vibrator bind below would resolve null and drop the command).
+        sink?.takeIf { it.ownsPad(pad) }?.let {
+            it.rumble(pad, low, high, durationMs)
+            return
+        }
        val bind = rumbleBindFor(pad) ?: return
        val lo = toAmplitude(low)
        val hi = toAmplitude(high)
@@ -313,23 +355,36 @@ class GamepadFeedback(
                val g = buf.get().toInt() and 0xFF
                val b = buf.get().toInt() and 0xFF
                Log.i(TAG, "hidout pad=$pad Led r=$r g=$g b=$b") // verification line
-                if (Build.VERSION.SDK_INT >= 33) setLightbar(pad, Color.rgb(r, g, b))
+                val s = sink?.takeIf { it.ownsPad(pad) }
+                if (s != null) s.led(pad, r, g, b)
+                else if (Build.VERSION.SDK_INT >= 33) setLightbar(pad, Color.rgb(r, g, b))
            }
            TAG_PLAYER_LEDS -> {
                val bits = buf.get().toInt() and 0x1F
                val player = playerIndexForBits(bits)
                Log.i(TAG, "hidout pad=$pad PlayerLeds bits=$bits player=$player") // verification line
-                if (Build.VERSION.SDK_INT >= 33) setPlayerId(pad, player)
+                val s = sink?.takeIf { it.ownsPad(pad) }
+                if (s != null) s.playerLeds(pad, bits)
+                else if (Build.VERSION.SDK_INT >= 33) setPlayerId(pad, player)
            }
            TAG_TRIGGER -> {
                val which = buf.get().toInt() and 0xFF // 0 = L2, 1 = R2
                val effLen = n - 3 // [pad][kind][which] header, then the effect block
-                val mode = if (effLen > 0) buf.get().toInt() and 0xFF else 0
-                // No public adaptive-trigger API on Android — parse-validate the mode + log only.
-                Log.i(
-                    TAG,
-                    "hidout pad=$pad Trigger which=$which effLen=$effLen mode=0x%02x (adaptive triggers unsupported on Android)".format(mode),
-                )
+                val s = sink?.takeIf { it.ownsPad(pad) }
+                if (s != null && effLen > 0) {
+                    // A captured DualSense: the raw trigger block replays onto the physical pad.
+                    val effect = ByteArray(effLen)
+                    buf.get(effect)
+                    Log.i(TAG, "hidout pad=$pad Trigger which=$which effLen=$effLen → captured pad") // verification line
+                    s.trigger(pad, which, effect)
+                } else {
+                    val mode = if (effLen > 0) buf.get().toInt() and 0xFF else 0
+                    // No platform adaptive-trigger API — parse-validate the mode + log only.
+                    Log.i(
+                        TAG,
+                        "hidout pad=$pad Trigger which=$which effLen=$effLen mode=0x%02x (no adaptive-trigger renderer for this pad)".format(mode),
+                    )
+                }
            }
            TAG_HID_RAW -> {
                // As-is SC2 passthrough: a raw report the host's Steam wrote to the virtual pad —
@@ -210,6 +210,24 @@ class GamepadRouter(context: Context, private val handle: Long, private val sett
            if (slot != null) NativeBridge.nativeSendPadHidReport(handle, index, buf, len)
        }

+        /** One touchpad contact on the rich plane: [finger] 0/1, x/y normalized 0..65535 in
+         *  SCREEN convention (+y down); `active = false` lifts the finger. On-change only. */
+        fun touch(finger: Int, active: Boolean, x: Int, y: Int) {
+            if (slot != null) NativeBridge.nativeSendPadTouch(handle, index, finger, active, x, y)
+        }
+
+        /** One motion sample on the rich plane (gyro pitch/yaw/roll + accel, raw device i16
+         *  units — the host passes them straight into the virtual pad's report). Per report. */
+        fun motion(gyro: IntArray, accel: IntArray) {
+            if (slot != null) {
+                NativeBridge.nativeSendPadMotion(
+                    handle, index,
+                    gyro[0], gyro[1], gyro[2],
+                    accel[0], accel[1], accel[2],
+                )
+            }
+        }
+
        /** Flush held state, signal the removal, and free the wire index. Idempotent. */
        fun close() = closeSlot(syntheticId)
    }
@@ -228,6 +246,16 @@ class GamepadRouter(context: Context, private val handle: Long, private val sett
        return ExternalPad(syntheticId, index)
    }

+    /**
+     * Close the slot (if any) for a physical controller a capture link just claimed. The claim
+     * detaches the kernel driver, so the system's own removal callback would close it moments
+     * later anyway — doing it at claim time makes the freed wire index deterministic for the
+     * link's [ExternalPad] instead of racing the link's first report against that callback. Safe
+     * to over-match (a same-VID/PID sibling that still exists as an InputDevice lazily reopens a
+     * slot on its next input event). Main thread, like the hot-plug callbacks.
+     */
+    fun releaseDevice(deviceId: Int) = closeSlot(deviceId)
+
    /**
     * Flush + drop every slot and unregister the hot-plug listener. Call on session teardown, AFTER
     * the feedback poll threads are joined (they read [deviceForPad]).
@@ -0,0 +1,399 @@
+package io.unom.punktfunk.kit
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.hardware.usb.UsbConstants
+import android.hardware.usb.UsbDevice
+import android.hardware.usb.UsbDeviceConnection
+import android.hardware.usb.UsbEndpoint
+import android.hardware.usb.UsbInterface
+import android.hardware.usb.UsbManager
+import android.hardware.usb.UsbRequest
+import android.os.Build
+import android.util.Log
+import java.nio.ByteBuffer
+import java.util.concurrent.ConcurrentLinkedQueue
+import java.util.concurrent.TimeoutException
+
+/**
+ * Generic USB transport for a client-captured HID controller — the device-agnostic half of what
+ * [Sc2UsbLink] pioneered, now shared with the Sony capture ([DsCapture]). Claims the controller
+ * interface(s) — `force = true` detaches the kernel/OS driver, so a captured pad can't
+ * double-drive the ordinary InputDevice path — runs a multiplexed [UsbRequest] read loop, and
+ * writes the host/capture's reports back to the device (interrupt-OUT when the interface has one,
+ * else EP0 `SET_REPORT`).
+ *
+ * Everything device-specific is [Config]: which attached device to pick, which of its interfaces
+ * to claim, and an optional keep-alive (feature reports re-sent on a firmware-watchdog cadence —
+ * the SC2's lizard-mode refresh; a DualSense needs none).
+ *
+ * **Unplug is signalled, never inferred from silence:** a quiet controller is not a missing one
+ * (an SC2 on-glass round tripped exactly this — a 5 s silence heuristic firing on an idle pad).
+ * The real signals are [UsbManager.ACTION_USB_DEVICE_DETACHED] for this device, or `requestWait`
+ * returning sustained hard errors (every transfer fails instantly once the fd is dead).
+ */
+class HidUsbLink(
+    private val context: Context,
+    private val config: Config,
+    private val onReport: (report: ByteArray, len: Int) -> Unit,
+    private val onClosed: () -> Unit,
+) {
+    /**
+     * The per-device knowledge this transport is parameterized by. [ifaceFilter] narrows WHICH
+     * HID/vendor-class interfaces get claimed (the class check itself is built in) — e.g. the SC2
+     * Puck's controller slots, or the DualSense's single HID interface among its audio siblings.
+     * [keepAliveFeatures] are full feature reports (id byte first) re-sent to the streaming
+     * interface every [keepAliveMs] AND once at claim time; empty = no keep-alive.
+     */
+    class Config(
+        val tag: String,
+        val threadName: String,
+        val deviceMatch: (UsbDevice) -> Boolean,
+        val ifaceFilter: (UsbDevice, UsbInterface) -> Boolean = { _, _ -> true },
+        val keepAliveFeatures: List<ByteArray> = emptyList(),
+        val keepAliveMs: Long = 0,
+    )
+
+    private val usb = context.getSystemService(Context.USB_SERVICE) as UsbManager
+
+    /** One claimed interface: its endpoints + the read state the reader thread owns. */
+    private class Claim(
+        val iface: UsbInterface,
+        val epIn: UsbEndpoint,
+        val epOut: UsbEndpoint?,
+    ) {
+        val inBuf: ByteBuffer = ByteBuffer.allocate(64)
+        var inReq: UsbRequest? = null
+        var outReq: UsbRequest? = null
+        var outBusy = false
+        var reports = 0L
+    }
+
+    private var connection: UsbDeviceConnection? = null
+    private var device: UsbDevice? = null
+    private var claims: List<Claim> = emptyList()
+
+    /** The claim whose IN endpoint last produced data — where output/feature writes go.
+     *  Written by the reader thread, read by the feedback thread (feature control transfers). */
+    @Volatile private var activeClaim: Claim? = null
+
+    /** Pending OUT reports, submitted by the reader thread — only one thread may drive a
+     *  connection's [UsbRequest]s ([UsbDeviceConnection.requestWait] returns ANY completed
+     *  request; a second waiter would steal the reader's completions). */
+    private val outQueue = ConcurrentLinkedQueue<ByteArray>()
+
+    private var reader: Thread? = null
+    private var detachReceiver: BroadcastReceiver? = null
+
+    @Volatile private var running = false
+
+    /** First attached matching device, or null. Does not need USB permission to enumerate. */
+    fun findDevice(): UsbDevice? = usb.deviceList.values.firstOrNull(config.deviceMatch)
+
+    /**
+     * Claim [dev]'s controller interface(s) and start the read loop. The caller has already
+     * obtained USB permission. Returns false when nothing could be claimed.
+     */
+    fun start(dev: UsbDevice): Boolean {
+        if (!usb.hasPermission(dev)) {
+            Log.e(config.tag, "no USB permission for ${dev.deviceName}")
+            return false
+        }
+        val conn = usb.openDevice(dev) ?: run {
+            Log.e(config.tag, "openDevice failed for ${dev.deviceName}")
+            return false
+        }
+        val claimed = claimControllerInterfaces(dev, conn)
+        if (claimed.isEmpty()) {
+            Log.e(config.tag, "no claimable interface on ${dev.deviceName} (PID=0x%04x)".format(dev.productId))
+            conn.close()
+            return false
+        }
+        connection = conn
+        device = dev
+        claims = claimed
+        running = true
+        Log.i(
+            config.tag,
+            "USB link up: PID=0x%04x ifaces=%s".format(
+                dev.productId,
+                claimed.joinToString {
+                    "%d(in=0x%02x out=%s)".format(
+                        it.iface.id, it.epIn.address,
+                        it.epOut?.let { e -> "0x%02x".format(e.address) } ?: "-",
+                    )
+                },
+            ),
+        )
+        // The REAL unplug signal — silence never is (an idle pad may simply stop streaming).
+        val receiver = object : BroadcastReceiver() {
+            override fun onReceive(c: Context?, intent: Intent?) {
+                if (intent?.action != UsbManager.ACTION_USB_DEVICE_DETACHED) return
+                val gone: UsbDevice? = intent.getParcelableExtra(UsbManager.EXTRA_DEVICE)
+                if (gone?.deviceName == dev.deviceName) {
+                    Log.i(config.tag, "USB detached (${dev.deviceName})")
+                    if (running) {
+                        running = false
+                        onClosed()
+                    }
+                }
+            }
+        }
+        detachReceiver = receiver
+        val filter = IntentFilter(UsbManager.ACTION_USB_DEVICE_DETACHED)
+        if (Build.VERSION.SDK_INT >= 33) {
+            context.registerReceiver(receiver, filter, Context.RECEIVER_NOT_EXPORTED)
+        } else {
+            @Suppress("UnspecifiedRegisterReceiverFlag")
+            context.registerReceiver(receiver, filter)
+        }
+        if (config.keepAliveFeatures.isNotEmpty()) {
+            claimed.forEach { sendKeepAlive(conn, it.iface.id) }
+        }
+        reader = Thread({ readLoop(conn, claimed) }, config.threadName).apply {
+            isDaemon = true
+            start()
+        }
+        return true
+    }
+
+    /**
+     * Claim every candidate controller interface: HID (or vendor-class) interfaces that pass the
+     * config's [Config.ifaceFilter], with an INT/BULK IN endpoint (OUT optional — the fallback is
+     * EP0 `SET_REPORT`). `force = true` detaches the kernel/OS driver, so the pad also vanishes
+     * from Android's own input stack while captured.
+     */
+    private fun claimControllerInterfaces(dev: UsbDevice, conn: UsbDeviceConnection): List<Claim> {
+        val out = mutableListOf<Claim>()
+        for (i in 0 until dev.interfaceCount) {
+            val iface = dev.getInterface(i)
+            if (!config.ifaceFilter(dev, iface)) continue
+            val hidOrVendor = iface.interfaceClass == UsbConstants.USB_CLASS_HID ||
+                iface.interfaceClass == 0xFF
+            if (!hidOrVendor) continue
+            var inEp: UsbEndpoint? = null
+            var outEp: UsbEndpoint? = null
+            for (e in 0 until iface.endpointCount) {
+                val ep = iface.getEndpoint(e)
+                val usable = ep.type == UsbConstants.USB_ENDPOINT_XFER_INT ||
+                    ep.type == UsbConstants.USB_ENDPOINT_XFER_BULK
+                if (!usable) continue
+                if (ep.direction == UsbConstants.USB_DIR_IN && inEp == null) inEp = ep
+                if (ep.direction == UsbConstants.USB_DIR_OUT && outEp == null) outEp = ep
+            }
+            if (inEp == null) continue
+            if (conn.claimInterface(iface, true)) {
+                out.add(Claim(iface, inEp, outEp))
+            } else {
+                Log.w(config.tag, "could not claim iface ${iface.id}")
+            }
+        }
+        return out
+    }
+
+    /**
+     * The multiplexed read loop: one IN request queued per claimed interface at all times, OUT
+     * writes submitted from [outQueue], completions routed via [UsbRequest.getClientData].
+     */
+    private fun readLoop(conn: UsbDeviceConnection, claims: List<Claim>) {
+        val live = claims.filter { c ->
+            val req = UsbRequest()
+            if (!req.initialize(conn, c.epIn)) {
+                Log.w(config.tag, "UsbRequest.initialize(IN, iface ${c.iface.id}) failed")
+                return@filter false
+            }
+            req.clientData = c
+            c.inReq = req
+            c.epOut?.let { ep ->
+                val o = UsbRequest()
+                if (o.initialize(conn, ep)) {
+                    o.clientData = c
+                    c.outReq = o
+                } else {
+                    Log.w(config.tag, "UsbRequest.initialize(OUT, iface ${c.iface.id}) failed — output reports via EP0")
+                }
+            }
+            c.inBuf.clear()
+            req.queue(c.inBuf)
+        }
+        if (live.isEmpty()) {
+            Log.e(config.tag, "no IN request could be queued")
+            finishReader(claims)
+            return
+        }
+        val scratch = ByteArray(64)
+        var lastKeepAlive = android.os.SystemClock.elapsedRealtime()
+        var errorsSince = 0L // elapsedRealtime of the first hard error in the current streak
+        try {
+            while (running) {
+                val now = android.os.SystemClock.elapsedRealtime()
+                if (config.keepAliveFeatures.isNotEmpty() && config.keepAliveMs > 0 &&
+                    now - lastKeepAlive >= config.keepAliveMs
+                ) {
+                    // Refresh the firmware settings on the streaming interface (else every live
+                    // one, before a streaming interface is known) — replaying also repairs state
+                    // some other consumer changed after capture started.
+                    val target = activeClaim
+                    if (target != null) sendKeepAlive(conn, target.iface.id)
+                    else live.forEach { sendKeepAlive(conn, it.iface.id) }
+                    lastKeepAlive = now
+                }
+                // Submit the next pending OUT report on the active (else first) interface.
+                val outTarget = (activeClaim ?: live.first()).takeIf { it.outReq != null && !it.outBusy }
+                if (outTarget != null) {
+                    outQueue.poll()?.let { data ->
+                        if (outTarget.outReq!!.queue(ByteBuffer.wrap(data))) outTarget.outBusy = true
+                    }
+                }
+                val done = try {
+                    conn.requestWait(READ_TIMEOUT_MS)
+                } catch (_: TimeoutException) {
+                    // A quiet controller is NOT an unplug — keep listening indefinitely; the
+                    // detach broadcast is the real signal.
+                    errorsSince = 0L
+                    continue
+                }
+                if (done == null) {
+                    // Hard error. On a real unplug these storm continuously (the detach
+                    // broadcast usually beats us to it); tolerate transient ones.
+                    if (errorsSince == 0L) errorsSince = now
+                    if (now - errorsSince >= ERROR_UNPLUG_MS) {
+                        Log.i(config.tag, "USB request errors persisting ${now - errorsSince} ms — treating as unplug")
+                        break
+                    }
+                    continue
+                }
+                errorsSince = 0L
+                val claim = done.clientData as? Claim ?: continue
+                if (done === claim.inReq) {
+                    val n = claim.inBuf.position()
+                    if (n > 0) {
+                        claim.inBuf.flip()
+                        claim.inBuf.get(scratch, 0, n)
+                        if (claim.reports++ == 0L) {
+                            Log.i(
+                                config.tag,
+                                "first report on iface %d: id=0x%02x len=%d".format(
+                                    claim.iface.id, scratch[0].toInt() and 0xFF, n,
+                                ),
+                            )
+                        }
+                        activeClaim = claim
+                        onReport(scratch, n)
+                    }
+                    claim.inBuf.clear()
+                    if (!claim.inReq!!.queue(claim.inBuf)) {
+                        Log.i(config.tag, "re-queue(IN, iface ${claim.iface.id}) failed — treating as unplug")
+                        break
+                    }
+                } else if (done === claim.outReq) {
+                    claim.outBusy = false
+                }
+            }
+        } finally {
+            finishReader(claims)
+        }
+        if (running) {
+            running = false
+            onClosed()
+        }
+    }
+
+    private fun finishReader(claims: List<Claim>) {
+        for (c in claims) {
+            runCatching { c.inReq?.cancel(); c.inReq?.close() }
+            runCatching { c.outReq?.cancel(); c.outReq?.close() }
+            c.inReq = null
+            c.outReq = null
+        }
+    }
+
+    /**
+     * Write one raw report to the device: kind 0 = output report (the active interface's
+     * interrupt-OUT, else a `SET_REPORT(Output)` control transfer), kind 1 = feature report
+     * (`SET_REPORT(Feature)`). [data] is the full report, id byte first, hidapi framing.
+     */
+    fun writeRaw(kind: Int, data: ByteArray) {
+        if (data.isEmpty()) return
+        when (kind) {
+            0 -> {
+                if ((activeClaim ?: claims.firstOrNull())?.outReq != null) {
+                    // Interrupt-OUT rides UsbRequests submitted by the reader thread. Bounded,
+                    // newest-wins: these are level-styled commands the sender re-sends anyway.
+                    while (outQueue.size >= 32) outQueue.poll()
+                    outQueue.offer(data)
+                } else {
+                    setReport(REPORT_TYPE_OUTPUT, data)
+                }
+            }
+            1 -> setReport(REPORT_TYPE_FEATURE, data)
+        }
+    }
+
+    private fun setReport(type: Int, data: ByteArray) {
+        val conn = connection ?: return
+        val ifId = (activeClaim ?: claims.firstOrNull())?.iface?.id ?: return
+        sendReport(conn, ifId, type, data)
+    }
+
+    /**
+     * Write one output report EP0-direct (`SET_REPORT(Output)`), bypassing the interrupt-OUT
+     * queue — for a teardown write that must land while the reader thread is stopping and the
+     * queue would never drain (e.g. a rumble stop before the interfaces release). Safe from any
+     * thread: EP0 control transfers are independent of the reader's `requestWait`.
+     */
+    fun writeControl(data: ByteArray) {
+        if (data.isNotEmpty()) setReport(REPORT_TYPE_OUTPUT, data)
+    }
+
+    private fun sendKeepAlive(conn: UsbDeviceConnection, ifaceId: Int) {
+        for (f in config.keepAliveFeatures) sendReport(conn, ifaceId, REPORT_TYPE_FEATURE, f)
+    }
+
+    /**
+     * HID `SET_REPORT` control transfer with hidapi's report-id framing: a non-zero leading byte
+     * is the report id (sent in wValue AND kept in the payload); a zero leading byte means
+     * "unnumbered" (id 0 in wValue, id byte stripped from the payload). EP0 is independent of
+     * the interrupt endpoints, so this is safe alongside the reader thread's requestWait.
+     */
+    private fun sendReport(conn: UsbDeviceConnection, ifaceId: Int, type: Int, data: ByteArray) {
+        val id = data[0].toInt() and 0xFF
+        val payload = if (id == 0) data.copyOfRange(1, data.size) else data
+        conn.controlTransfer(
+            0x21, // host→device, class, interface
+            0x09, // SET_REPORT
+            (type shl 8) or id,
+            ifaceId,
+            payload,
+            payload.size,
+            WRITE_TIMEOUT_MS,
+        )
+    }
+
+    /** Stop the read loop and release the interfaces. Idempotent; does not fire [onClosed]. */
+    fun stop() {
+        running = false
+        detachReceiver?.let { runCatching { context.unregisterReceiver(it) } }
+        detachReceiver = null
+        runCatching { reader?.join(1000) }
+        reader = null
+        outQueue.clear()
+        activeClaim = null
+        for (c in claims) runCatching { connection?.releaseInterface(c.iface) }
+        claims = emptyList()
+        runCatching { connection?.close() }
+        connection = null
+        device = null
+    }
+
+    private companion object {
+        const val READ_TIMEOUT_MS = 100L
+        const val WRITE_TIMEOUT_MS = 250
+        /** Hard `requestWait` ERRORS (not timeouts) persisting this long = the fd is dead. */
+        const val ERROR_UNPLUG_MS = 2000L
+        const val REPORT_TYPE_OUTPUT = 0x02
+        const val REPORT_TYPE_FEATURE = 0x03
+    }
+}
@@ -57,6 +57,10 @@ object NativeBridge {
        /** Store-qualified library id (`steam:<appid>` / `custom:<id>`) to boot straight into a game,
         *  or `null`/empty for a plain desktop connect. Rides the Hello as `launch`. */
        launch: String?,
+        /** This device's display name (rides the Hello as `name`) — what the host's pending-approval
+         *  list and trust store show for it, same convention as [nativePair]'s `name`. `null`/blank ⇒
+         *  the host falls back to a fingerprint-derived "device abcd1234" label. */
+        deviceName: String?,
    ): Long

    /** 64-hex SHA-256 of the cert the host presented on [handle]; valid after a successful connect. */
@@ -145,6 +149,24 @@ object NativeBridge {
     */
    external fun nativeProbe(host: String, port: Int, timeoutMs: Int): Boolean

+    /**
+     * Start a bandwidth speed test on [handle]: the host bursts filler over the real data plane at
+     * [targetKbps] of goodput for [durationMs] (each clamped host-side to ≤ 3 Gbps / ≤ 5 s),
+     * **briefly pausing video**. Measuring over the stream's own path is the point — the answer is
+     * about the link this host's stream will take, not about generic throughput.
+     *
+     * Non-blocking: poll [nativeProbeResult] until it reports done. Starting a probe resets any
+     * prior measurement. Returns false on a dead handle. Cheap; safe on the main thread.
+     */
+    external fun nativeSpeedTest(handle: Long, targetKbps: Int, durationMs: Int): Boolean
+
+    /**
+     * The current speed-test measurement, partial until `[0] != 0.0`:
+     * `[done, throughputKbps, lossPct, hostDropPct, elapsedMs, recvBytes]`. Zeros before any
+     * probe, null on a dead handle. Cheap (one lock + a copy); safe to poll on the main thread.
+     */
+    external fun nativeProbeResult(handle: Long): DoubleArray?
+
    /**
     * Apply the user's "Low-latency mode (experimental)" toggle to the process-wide transport
     * defaults — today just DSCP/QoS marking on the media sockets. Must be called BEFORE
@@ -161,6 +183,16 @@ object NativeBridge {
     */
    external fun nativeVideoMime(handle: Long): String

+    /**
+     * The negotiated video mode as `[width, height, refreshHz]`, or `null` on a `0` handle.
+     * Resolved at the handshake, so it is known before the first frame — the stream view sizes
+     * itself to THIS aspect rather than stretching the picture to the panel's, and pins the
+     * panel's display mode to the stream refresh. The trailing `refreshHz` was appended later
+     * (an older native lib returns only `[width, height]` — index defensively). Fixed for the
+     * session; read once. Cheap; UI-safe.
+     */
+    external fun nativeVideoSize(handle: Long): IntArray?
+
    /**
     * A short human label for the codec the host resolved (`"H.264"` / `"HEVC"` / `"AV1"` /
     * `"PyroWave"`), for the stats HUD's video-feed line, or `""` on a `0` handle. Distinct from
@@ -174,11 +206,13 @@ object NativeBridge {
     * entirely in Rust (NDK AMediaCodec → ANativeWindow) — no per-frame JNI. [decoderName] is the
     * decoder Kotlin ranked from `MediaCodecList` (`""` = let the platform resolve the default for
     * the MIME — what the pre-overhaul client always did); [lowLatencyMode] is the user's
-     * "Low-latency mode (experimental)" toggle (off, the default, runs the original decode
-     * pipeline; on, the aggressive per-SoC tuning + async loop); [lowLatencyFeature] is whether
+     * "Low-latency mode" master toggle (ON by default: async loop + per-SoC tuning; off runs the
+     * original synchronous pipeline as the per-device escape hatch); [lowLatencyFeature] is whether
     * [decoderName] advertised `FEATURE_LowLatency` (HUD label only). [isTv] drives an active HDMI
     * mode switch to the stream refresh on TV boxes when the toggle is on (vs. the softer seamless
-     * hint otherwise). No-op if already started.
+     * hint otherwise). [presentPriority]/[smoothBuffer] are the timeline presenter's intent
+     * (0 = lowest latency / 1 = smoothness; buffer 0 = automatic, else 1..3 frames) — the Apple
+     * client's `present_priority`/`smooth_buffer` pair. No-op if already started.
     */
    external fun nativeStartVideo(
        handle: Long,
@@ -187,6 +221,11 @@ object NativeBridge {
        lowLatencyMode: Boolean,
        lowLatencyFeature: Boolean,
        isTv: Boolean,
+        presentPriority: Int,
+        smoothBuffer: Int,
+        /** The display mode's own refresh rate (0 = unknown) — the latch grid the presenter
+         *  subdivides onto when the platform down-rates the app's choreographer stream. */
+        panelFps: Int,
    )

    /** Stop + join the decode thread without closing the session. No-op on `0`. */
@@ -201,11 +240,11 @@ object NativeBridge {

    /**
     * Drain ~1 s of live decode stats for the on-stream HUD, or `null` when no decode thread runs.
-     * Returns 26 doubles (unified stats spec, `design/stats-unification.md`):
+     * Returns 30 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, lostWindow, skippedWindow, fecWindow, framesWindow, dispValid, displayP50Ms,
-     * e2eDispP50Ms, e2eDispP95Ms]`
+     * e2eDispP50Ms, e2eDispP95Ms, paceP50Ms, latchP50Ms, presentsWindow, presenterActive]`
     * (the 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 —
@@ -377,6 +416,30 @@ object NativeBridge {
     */
    external fun nativeSendPadHidReport(handle: Long, pad: Int, buf: java.nio.ByteBuffer, len: Int)

+    /**
+     * One touchpad contact from a client-captured controller (the Sony USB capture), forwarded on
+     * the rich-input plane (`RichInput::Touchpad`). [finger] is the contact slot (0/1); [x]/[y]
+     * are normalized 0..65535 in SCREEN convention (+y down — the wire's fixed meaning); active
+     * false lifts the finger. Send on change only — the host holds per-slot state.
+     */
+    external fun nativeSendPadTouch(handle: Long, pad: Int, finger: Int, active: Boolean, x: Int, y: Int)
+
+    /**
+     * One motion-sensor sample from a client-captured controller (`RichInput::Motion`): gyro
+     * pitch/yaw/roll + accel, each a raw signed-16 value in the pad's own units — the host passes
+     * them straight into the virtual DualSense report. Called at the pad's report rate.
+     */
+    external fun nativeSendPadMotion(
+        handle: Long,
+        pad: Int,
+        gyroPitch: Int,
+        gyroYaw: Int,
+        gyroRoll: Int,
+        accelX: Int,
+        accelY: Int,
+        accelZ: Int,
+    )
+
    // ---- Host→client gamepad feedback: Rust pulls block ~100ms, Kotlin renders (see GamepadFeedback) ----

    /**
@@ -1,28 +1,13 @@
 package io.unom.punktfunk.kit

-import android.content.BroadcastReceiver
 import android.content.Context
-import android.content.Intent
-import android.content.IntentFilter
-import android.hardware.usb.UsbConstants
 import android.hardware.usb.UsbDevice
-import android.hardware.usb.UsbDeviceConnection
-import android.hardware.usb.UsbEndpoint
-import android.hardware.usb.UsbInterface
-import android.hardware.usb.UsbManager
-import android.hardware.usb.UsbRequest
-import android.os.Build
-import android.util.Log
-import java.nio.ByteBuffer
-import java.util.concurrent.ConcurrentLinkedQueue
-import java.util.concurrent.TimeoutException

 /**
 * USB transport for a Steam Controller 2 — wired (`28DE:1302`) or through the wireless Puck
- * dongle (`1304`/`1305`). Claims the controller interface(s) — detaching the OS input stack, so
- * the pad can't double-drive the ordinary InputDevice path — runs a multiplexed [UsbRequest]
- * read loop, keeps lizard mode off on the firmware watchdog cadence, and replays the host's raw
- * writes (Steam's rumble output reports / settings feature reports) back to the device.
+ * dongle (`1304`/`1305`). The SC2 specialization of the shared [HidUsbLink] transport (which owns
+ * the claim, read loop, write queue, and unplug handling); this class contributes only what is
+ * SC2-specific:
 *
 * **The Puck claims ALL controller interfaces (2..5):** the dongle hosts up to four pads, one
 * HID interface each, and there is no way to know which slot a controller bonded to — claiming
@@ -30,350 +15,50 @@ import java.util.concurrent.TimeoutException
 * on-glass symptom: the pad surfaced as a generic InputDevice → Xbox360). Whichever interface
 * streams state becomes the write target for rumble/settings.
 *
- * **Unplug is signalled, never inferred from silence:** a quiet controller is not a missing one
- * (round 2's wired disconnect was the 5 s silence heuristic firing on an idle pad). The real
- * signals are [UsbManager.ACTION_USB_DEVICE_DETACHED] for this device, or `requestWait`
- * returning sustained hard errors (every transfer fails instantly once the fd is dead).
+ * **Lizard keep-alive:** the firmware watchdog re-enables lizard mode (built-in kb/mouse
+ * emulation) after a few seconds of silence, so [Sc2Device.DISABLE_LIZARD] +
+ * [Sc2Device.NORMALIZE_JOYSTICKS] are re-sent on SDL's cadence — the generic link's keep-alive.
 */
 class Sc2UsbLink(
-    private val context: Context,
-    private val onReport: (report: ByteArray, len: Int) -> Unit,
-    private val onClosed: () -> Unit,
+    context: Context,
+    onReport: (report: ByteArray, len: Int) -> Unit,
+    onClosed: () -> Unit,
 ) {
-    private val usb = context.getSystemService(Context.USB_SERVICE) as UsbManager
-
-    /** One claimed interface: its endpoints + the read state the reader thread owns. */
-    private class Claim(
-        val iface: UsbInterface,
-        val epIn: UsbEndpoint,
-        val epOut: UsbEndpoint?,
-    ) {
-        val inBuf: ByteBuffer = ByteBuffer.allocate(64)
-        var inReq: UsbRequest? = null
-        var outReq: UsbRequest? = null
-        var outBusy = false
-        var reports = 0L
-    }
-
-    private var connection: UsbDeviceConnection? = null
-    private var device: UsbDevice? = null
-    private var claims: List<Claim> = emptyList()
-
-    /** The claim whose IN endpoint last produced data — where rumble/settings writes go.
-     *  Written by the reader thread, read by the feedback thread (feature control transfers). */
-    @Volatile private var activeClaim: Claim? = null
-
-    /** Pending OUT reports (Steam's forwarded haptics), submitted by the reader thread — only
-     *  one thread may drive a connection's [UsbRequest]s ([UsbDeviceConnection.requestWait]
-     *  returns ANY completed request; a second waiter would steal the reader's completions). */
-    private val outQueue = ConcurrentLinkedQueue<ByteArray>()
-
-    private var reader: Thread? = null
-    private var detachReceiver: BroadcastReceiver? = null
-
-    @Volatile private var running = false
+    private val link = HidUsbLink(
+        context,
+        HidUsbLink.Config(
+            tag = "Sc2UsbLink",
+            threadName = "pf-sc2-usb",
+            deviceMatch = {
+                it.vendorId == Sc2Device.VID_VALVE && it.productId in Sc2Device.USB_PIDS
+            },
+            // Wired: every HID/vendor interface; dongle: only the controller slots 2..5.
+            ifaceFilter = { dev, iface ->
+                dev.productId == Sc2Device.PID_WIRED || iface.id in Sc2Device.DONGLE_IFACES
+            },
+            keepAliveFeatures = listOf(Sc2Device.DISABLE_LIZARD, Sc2Device.NORMALIZE_JOYSTICKS),
+            keepAliveMs = Sc2Device.LIZARD_REFRESH_MS,
+        ),
+        onReport,
+        onClosed,
+    )

    /** First attached SC2 (wired or Puck), or null. Does not need USB permission to enumerate. */
-    fun findDevice(): UsbDevice? = usb.deviceList.values.firstOrNull {
-        it.vendorId == Sc2Device.VID_VALVE && it.productId in Sc2Device.USB_PIDS
-    }
+    fun findDevice(): UsbDevice? = link.findDevice()

    /**
     * Claim [dev]'s controller interface(s) and start the read loop. The caller has already
     * obtained USB permission. Returns false when nothing could be claimed.
     */
-    fun start(dev: UsbDevice): Boolean {
-        if (!usb.hasPermission(dev)) {
-            Log.e(TAG, "no USB permission for ${dev.deviceName}")
-            return false
-        }
-        val conn = usb.openDevice(dev) ?: run {
-            Log.e(TAG, "openDevice failed for ${dev.deviceName}")
-            return false
-        }
-        val claimed = claimControllerInterfaces(dev, conn)
-        if (claimed.isEmpty()) {
-            Log.e(TAG, "no claimable SC2 interface on ${dev.deviceName} (PID=0x%04x)".format(dev.productId))
-            conn.close()
-            return false
-        }
-        connection = conn
-        device = dev
-        claims = claimed
-        running = true
-        Log.i(
-            TAG,
-            "SC2 USB link up: PID=0x%04x ifaces=%s".format(
-                dev.productId,
-                claimed.joinToString {
-                    "%d(in=0x%02x out=%s)".format(
-                        it.iface.id, it.epIn.address,
-                        it.epOut?.let { e -> "0x%02x".format(e.address) } ?: "-",
-                    )
-                },
-            ),
-        )
-        // The REAL unplug signal — silence never is (an idle pad may simply stop streaming).
-        val receiver = object : BroadcastReceiver() {
-            override fun onReceive(c: Context?, intent: Intent?) {
-                if (intent?.action != UsbManager.ACTION_USB_DEVICE_DETACHED) return
-                val gone: UsbDevice? = intent.getParcelableExtra(UsbManager.EXTRA_DEVICE)
-                if (gone?.deviceName == dev.deviceName) {
-                    Log.i(TAG, "SC2 USB detached (${dev.deviceName})")
-                    if (running) {
-                        running = false
-                        onClosed()
-                    }
-                }
-            }
-        }
-        detachReceiver = receiver
-        val filter = IntentFilter(UsbManager.ACTION_USB_DEVICE_DETACHED)
-        if (Build.VERSION.SDK_INT >= 33) {
-            context.registerReceiver(receiver, filter, Context.RECEIVER_NOT_EXPORTED)
-        } else {
-            @Suppress("UnspecifiedRegisterReceiverFlag")
-            context.registerReceiver(receiver, filter)
-        }
-        claimed.forEach { configureInputMode(conn, it.iface.id) }
-        reader = Thread({ readLoop(conn, claimed) }, "pf-sc2-usb").apply {
-            isDaemon = true
-            start()
-        }
-        return true
-    }
-
-    /**
-     * Claim every candidate controller interface: the wired pad's single HID interface, or ALL
-     * of a Puck's controller slots (interfaces 2..5 — the controller may be bonded to any of
-     * them). `force = true` detaches the kernel/OS driver, so the pad also vanishes from
-     * Android's own input stack while captured.
-     */
-    private fun claimControllerInterfaces(dev: UsbDevice, conn: UsbDeviceConnection): List<Claim> {
-        val dongle = dev.productId != Sc2Device.PID_WIRED
-        val out = mutableListOf<Claim>()
-        for (i in 0 until dev.interfaceCount) {
-            val iface = dev.getInterface(i)
-            if (dongle && iface.id !in Sc2Device.DONGLE_IFACES) continue
-            val hidOrVendor = iface.interfaceClass == UsbConstants.USB_CLASS_HID ||
-                iface.interfaceClass == 0xFF
-            if (!hidOrVendor) continue
-            var inEp: UsbEndpoint? = null
-            var outEp: UsbEndpoint? = null
-            for (e in 0 until iface.endpointCount) {
-                val ep = iface.getEndpoint(e)
-                val usable = ep.type == UsbConstants.USB_ENDPOINT_XFER_INT ||
-                    ep.type == UsbConstants.USB_ENDPOINT_XFER_BULK
-                if (!usable) continue
-                if (ep.direction == UsbConstants.USB_DIR_IN && inEp == null) inEp = ep
-                if (ep.direction == UsbConstants.USB_DIR_OUT && outEp == null) outEp = ep
-            }
-            if (inEp == null) continue
-            if (conn.claimInterface(iface, true)) {
-                out.add(Claim(iface, inEp, outEp))
-            } else {
-                Log.w(TAG, "could not claim iface ${iface.id}")
-            }
-        }
-        return out
-    }
-
-    /**
-     * The multiplexed read loop: one IN request queued per claimed interface at all times, OUT
-     * writes submitted from [outQueue], completions routed via [UsbRequest.getClientData].
-     */
-    private fun readLoop(conn: UsbDeviceConnection, claims: List<Claim>) {
-        val live = claims.filter { c ->
-            val req = UsbRequest()
-            if (!req.initialize(conn, c.epIn)) {
-                Log.w(TAG, "UsbRequest.initialize(IN, iface ${c.iface.id}) failed")
-                return@filter false
-            }
-            req.clientData = c
-            c.inReq = req
-            c.epOut?.let { ep ->
-                val o = UsbRequest()
-                if (o.initialize(conn, ep)) {
-                    o.clientData = c
-                    c.outReq = o
-                } else {
-                    Log.w(TAG, "UsbRequest.initialize(OUT, iface ${c.iface.id}) failed — output reports via EP0")
-                }
-            }
-            c.inBuf.clear()
-            req.queue(c.inBuf)
-        }
-        if (live.isEmpty()) {
-            Log.e(TAG, "no IN request could be queued")
-            finishReader(claims)
-            return
-        }
-        val scratch = ByteArray(64)
-        var lastLizard = android.os.SystemClock.elapsedRealtime()
-        var errorsSince = 0L // elapsedRealtime of the first hard error in the current streak
-        try {
-            while (running) {
-                val now = android.os.SystemClock.elapsedRealtime()
-                if (now - lastLizard >= Sc2Device.LIZARD_REFRESH_MS) {
-                    // Refresh both required firmware modes. The raw-joystick setting is normally
-                    // persistent, but replaying it also repairs a host/driver that enabled ADC
-                    // coordinates after capture started.
-                    val target = activeClaim
-                    if (target != null) configureInputMode(conn, target.iface.id)
-                    else live.forEach { configureInputMode(conn, it.iface.id) }
-                    lastLizard = now
-                }
-                // Submit the next pending OUT report on the active (else first) interface.
-                val outTarget = (activeClaim ?: live.first()).takeIf { it.outReq != null && !it.outBusy }
-                if (outTarget != null) {
-                    outQueue.poll()?.let { data ->
-                        if (outTarget.outReq!!.queue(ByteBuffer.wrap(data))) outTarget.outBusy = true
-                    }
-                }
-                val done = try {
-                    conn.requestWait(READ_TIMEOUT_MS)
-                } catch (_: TimeoutException) {
-                    // A quiet controller is NOT an unplug — keep listening indefinitely; the
-                    // detach broadcast is the real signal.
-                    errorsSince = 0L
-                    continue
-                }
-                if (done == null) {
-                    // Hard error. On a real unplug these storm continuously (the detach
-                    // broadcast usually beats us to it); tolerate transient ones.
-                    if (errorsSince == 0L) errorsSince = now
-                    if (now - errorsSince >= ERROR_UNPLUG_MS) {
-                        Log.i(TAG, "SC2 USB request errors persisting ${now - errorsSince} ms — treating as unplug")
-                        break
-                    }
-                    continue
-                }
-                errorsSince = 0L
-                val claim = done.clientData as? Claim ?: continue
-                if (done === claim.inReq) {
-                    val n = claim.inBuf.position()
-                    if (n > 0) {
-                        claim.inBuf.flip()
-                        claim.inBuf.get(scratch, 0, n)
-                        if (claim.reports++ == 0L) {
-                            Log.i(
-                                TAG,
-                                "SC2 first report on iface %d: id=0x%02x len=%d".format(
-                                    claim.iface.id, scratch[0].toInt() and 0xFF, n,
-                                ),
-                            )
-                        }
-                        activeClaim = claim
-                        onReport(scratch, n)
-                    }
-                    claim.inBuf.clear()
-                    if (!claim.inReq!!.queue(claim.inBuf)) {
-                        Log.i(TAG, "re-queue(IN, iface ${claim.iface.id}) failed — treating as unplug")
-                        break
-                    }
-                } else if (done === claim.outReq) {
-                    claim.outBusy = false
-                }
-            }
-        } finally {
-            finishReader(claims)
-        }
-        if (running) {
-            running = false
-            onClosed()
-        }
-    }
-
-    private fun finishReader(claims: List<Claim>) {
-        for (c in claims) {
-            runCatching { c.inReq?.cancel(); c.inReq?.close() }
-            runCatching { c.outReq?.cancel(); c.outReq?.close() }
-            c.inReq = null
-            c.outReq = null
-        }
-    }
+    fun start(dev: UsbDevice): Boolean = link.start(dev)

    /**
     * Replay one raw report from the host on the device: kind 0 = output report (Steam's `0x80`
-     * rumble & friends — the active interface's interrupt-OUT, else a `SET_REPORT(Output)`
-     * control transfer), kind 1 = feature report (`SET_REPORT(Feature)`). [data] is the full
-     * report, id byte first, exactly as hidapi framed it host-side.
+     * rumble & friends), kind 1 = feature report. [data] is the full report, id byte first,
+     * exactly as hidapi framed it host-side.
     */
-    fun writeRaw(kind: Int, data: ByteArray) {
-        if (data.isEmpty()) return
-        when (kind) {
-            0 -> {
-                if ((activeClaim ?: claims.firstOrNull())?.outReq != null) {
-                    // Interrupt-OUT rides UsbRequests submitted by the reader thread. Bounded,
-                    // newest-wins: these are level-styled commands the host re-sends anyway.
-                    while (outQueue.size >= 32) outQueue.poll()
-                    outQueue.offer(data)
-                } else {
-                    setReport(REPORT_TYPE_OUTPUT, data)
-                }
-            }
-            1 -> setReport(REPORT_TYPE_FEATURE, data)
-        }
-    }
+    fun writeRaw(kind: Int, data: ByteArray) = link.writeRaw(kind, data)

-    private fun setReport(type: Int, data: ByteArray) {
-        val conn = connection ?: return
-        val ifId = (activeClaim ?: claims.firstOrNull())?.iface?.id ?: return
-        sendReport(conn, ifId, type, data)
-    }
-
-    private fun configureInputMode(conn: UsbDeviceConnection, ifaceId: Int) {
-        sendFeature(conn, ifaceId, Sc2Device.DISABLE_LIZARD)
-        sendFeature(conn, ifaceId, Sc2Device.NORMALIZE_JOYSTICKS)
-    }
-
-    private fun sendFeature(conn: UsbDeviceConnection, ifaceId: Int, data: ByteArray) {
-        sendReport(conn, ifaceId, REPORT_TYPE_FEATURE, data)
-    }
-
-    /**
-     * HID `SET_REPORT` control transfer with hidapi's report-id framing: a non-zero leading byte
-     * is the report id (sent in wValue AND kept in the payload); a zero leading byte means
-     * "unnumbered" (id 0 in wValue, id byte stripped from the payload). EP0 is independent of
-     * the interrupt endpoints, so this is safe alongside the reader thread's requestWait.
-     */
-    private fun sendReport(conn: UsbDeviceConnection, ifaceId: Int, type: Int, data: ByteArray) {
-        val id = data[0].toInt() and 0xFF
-        val payload = if (id == 0) data.copyOfRange(1, data.size) else data
-        conn.controlTransfer(
-            0x21, // host→device, class, interface
-            0x09, // SET_REPORT
-            (type shl 8) or id,
-            ifaceId,
-            payload,
-            payload.size,
-            WRITE_TIMEOUT_MS,
-        )
-    }
-
-    /** Stop the read loop and release the interfaces. Idempotent; does not fire [onClosed]. */
-    fun stop() {
-        running = false
-        detachReceiver?.let { runCatching { context.unregisterReceiver(it) } }
-        detachReceiver = null
-        runCatching { reader?.join(1000) }
-        reader = null
-        outQueue.clear()
-        activeClaim = null
-        for (c in claims) runCatching { connection?.releaseInterface(c.iface) }
-        claims = emptyList()
-        runCatching { connection?.close() }
-        connection = null
-        device = null
-    }
-
-    private companion object {
-        const val TAG = "Sc2UsbLink"
-        const val READ_TIMEOUT_MS = 100L
-        const val WRITE_TIMEOUT_MS = 250
-        /** Hard `requestWait` ERRORS (not timeouts) persisting this long = the fd is dead. */
-        const val ERROR_UNPLUG_MS = 2000L
-        const val REPORT_TYPE_OUTPUT = 0x02
-        const val REPORT_TYPE_FEATURE = 0x03
-    }
+    /** Stop the read loop and release the interfaces. Idempotent; does not fire the closed callback. */
+    fun stop() = link.stop()
 }
@@ -18,16 +18,17 @@ data class DiscoveredHost(
    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)
+    val os: String = "", // TXT "os" (OS-identity chain, e.g. "linux/fedora/bazzite"); "" on older hosts
 )

 /** 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␟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.
+ * Parse one record from [NativeBridge.nativeDiscoveryPoll] (`key␟name␟addr␟port␟fp␟pair␟mac␟os`),
+ * or null if it's malformed. Fields past the 6th are optional — an older native lib omits them
+ * (`mac` 7th, `os` 8th). 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)
@@ -44,9 +45,41 @@ fun parseHostRecord(record: String): DiscoveredHost? {
        pairingRequired = f[5] == "required",
        mac = if (f.size > 6) f[6].split(",").map { it.trim() }.filter { it.isNotEmpty() }
        else emptyList(),
+        os = if (f.size > 7) sanitizeOsChain(f[7]) else "",
    )
 }

+/**
+ * Reduce a raw `os` TXT value to the trusted grammar (pf-client-core's `sanitize_os`, mirrored):
+ * lowercase slash-separated tokens of `[a-z0-9._-]`, each ≤ 32 chars, at most 5. mDNS is
+ * unauthenticated input; a value that sanitizes to nothing becomes "" (no icon, like an older host).
+ */
+fun sanitizeOsChain(raw: String): String =
+    raw.lowercase()
+        .split('/')
+        .map { token -> token.filter { it in 'a'..'z' || it in '0'..'9' || it in "._-" }.take(32) }
+        .filter { it.isNotEmpty() }
+        .take(5)
+        .joinToString("/")
+
+/**
+ * The icon-lookup order for a chain: sanitized tokens most-specific-first, brand aliases applied
+ * (`macos` → `apple` art, `steamos` → `steam` art) — pf-client-core's `os_icon_tokens`, mirrored.
+ * The UI takes the first token it has art for; empty means "no OS icon" (older host / garbage).
+ */
+fun osIconTokens(chain: String): List<String> =
+    sanitizeOsChain(chain)
+        .split('/')
+        .filter { it.isNotEmpty() }
+        .reversed()
+        .map {
+            when (it) {
+                "macos" -> "apple"
+                "steamos" -> "steam"
+                else -> it
+            }
+        }
+
 /**
 * Browses `_punktfunk._udp` for punktfunk/1 hosts via the native `mdns-sd` core (the same browse the
 * Linux/Windows clients use), exposed over JNI — *not* `NsdManager`, whose per-OEM system daemon
@@ -0,0 +1,451 @@
+package io.unom.punktfunk.kit.link
+
+import io.unom.punktfunk.kit.security.KnownHost
+import java.nio.ByteBuffer
+import java.nio.charset.CodingErrorAction
+import java.nio.charset.StandardCharsets
+
+/**
+ * The `punktfunk://` URL grammar (design/client-deep-links.md §2). A **port**, not a new design:
+ * the Rust `crates/pf-client-core/src/deeplink.rs` is the reference, Swift keeps a third copy, and
+ * all three are held together by `clients/shared/deeplink-vectors.json`, which each language's test
+ * suite runs verbatim — so the three parsers cannot drift into three different security postures.
+ *
+ * ```text
+ * punktfunk://connect/<host-ref>[?fp=<64-hex>][&host=<addr[:port]>][&launch=<id>]
+ *                               [&profile=<ref>][&name=<label>]
+ * ```
+ *
+ * The invariant the grammar exists to keep: **a URL may only ever do what a click on an existing
+ * card could do, minus trust decisions.** So it carries *references* to things that already exist
+ * on this device — a host record, a settings profile, a library id — and never values: no
+ * resolution, no bitrate, no codec. A web page must not be able to shape a session beyond picking
+ * among the user's own configurations. `pair` is deliberately not a route and never will be;
+ * pairing stays an interactive ceremony.
+ *
+ * `pf://` parses as an alias so a hand-typed or legacy link still works, but nothing ever *emits*
+ * or registers it.
+ */
+object DeepLinks {
+    /** Hostile-input caps. Generous for a real link, small enough that a pasted megabyte stops here. */
+    const val MAX_URL_LEN = 2048
+    const val MAX_HOST_REF_LEN = 128
+    const val MAX_LAUNCH_LEN = 128
+    const val MAX_PROFILE_LEN = 64
+    const val MAX_NAME_LEN = 64
+
+    /** The default native port, as everywhere else in the clients. */
+    const val DEFAULT_PORT = 9777
+
+    /**
+     * Parse a `punktfunk://` (or `pf://`) URL. Everything hostile is rejected here, once: over-long
+     * input, malformed escapes, control characters, out-of-charset launch ids and fingerprints that
+     * aren't fingerprints. What the caller still has to do is *resolve* — the references may name
+     * things that don't exist on this device (see [resolveHost]).
+     */
+    fun parse(url: String): DeepLinkResult {
+        if (url.length > MAX_URL_LEN) return DeepLinkResult.Refused(LinkError.TOO_LONG)
+        val sep = url.indexOf("://")
+        if (sep < 0) return DeepLinkResult.Refused(LinkError.NOT_OUR_SCHEME)
+        val scheme = url.substring(0, sep)
+        if (!scheme.equals("punktfunk", ignoreCase = true) && !scheme.equals("pf", ignoreCase = true)) {
+            return DeepLinkResult.Refused(LinkError.NOT_OUR_SCHEME)
+        }
+        // A fragment is never part of this grammar; drop it rather than folding it into the last
+        // parameter, where it would smuggle unvalidated text past the caps.
+        val rest = url.substring(sep + 3).substringBefore('#')
+        val path = rest.substringBefore('?').trimEnd('/')
+        val query = if (rest.contains('?')) rest.substringAfter('?') else ""
+
+        val slash = path.indexOf('/')
+        val routeWord: String
+        val hostRefRaw: String
+        when {
+            slash >= 0 -> {
+                routeWord = path.substring(0, slash)
+                hostRefRaw = path.substring(slash + 1)
+            }
+            // A single segment: Apple's shipped links are always `connect/<uuid>`, but a bare
+            // reference is unambiguous as long as it isn't one of the route words — those stay
+            // routes (with a missing reference), so `punktfunk://pair` refuses instead of hunting
+            // for a host called "pair".
+            isRouteWord(path) -> {
+                routeWord = path
+                hostRefRaw = ""
+            }
+            else -> {
+                routeWord = "connect"
+                hostRefRaw = path
+            }
+        }
+        val route = when (routeWord.lowercase()) {
+            "connect" -> LinkRoute.CONNECT
+            "wake" -> LinkRoute.WAKE
+            "browse" -> LinkRoute.BROWSE
+            "pair" -> return DeepLinkResult.Refused(LinkError.PAIR_REFUSED)
+            else -> return DeepLinkResult.Refused(LinkError.UNKNOWN_ROUTE, routeWord)
+        }
+
+        val hostRef = when (val d = decode(hostRefRaw)) {
+            is Decoded.Err -> return DeepLinkResult.Refused(d.error)
+            is Decoded.Ok -> d.text
+        }
+        if (hostRef.isEmpty()) return DeepLinkResult.Refused(LinkError.MISSING_HOST_REF)
+        if (scalarCount(hostRef) > MAX_HOST_REF_LEN) {
+            return DeepLinkResult.Refused(LinkError.PARAM_TOO_LONG, "host-ref")
+        }
+
+        var fp: String? = null
+        var host: Pair<String, Int>? = null
+        var launch: String? = null
+        var profile: String? = null
+        var name: String? = null
+        for (pair in query.split('&')) {
+            if (pair.isEmpty()) continue
+            val eq = pair.indexOf('=')
+            val rawKey = if (eq >= 0) pair.substring(0, eq) else pair
+            val rawValue = if (eq >= 0) pair.substring(eq + 1) else ""
+            val key = when (val d = decode(rawKey)) {
+                is Decoded.Err -> return DeepLinkResult.Refused(d.error)
+                is Decoded.Ok -> d.text.lowercase()
+            }
+            val value = when (val d = decode(rawValue)) {
+                is Decoded.Err -> return DeepLinkResult.Refused(d.error)
+                is Decoded.Ok -> d.text
+            }
+            // `?launch=` with nothing after it is "not given", not an error.
+            if (value.isEmpty()) continue
+            // First occurrence wins, and unknown keys are ignored: a newer emitter's parameter must
+            // not turn an otherwise valid link into a refusal, and appending a second `fp=` must
+            // not be able to override the first.
+            when {
+                key == "fp" && fp == null -> {
+                    val hex = value.lowercase()
+                    if (hex.length != 64 || !hex.all { it.isDigit() || it in 'a'..'f' }) {
+                        return DeepLinkResult.Refused(LinkError.BAD_FINGERPRINT)
+                    }
+                    fp = hex
+                }
+                key == "host" && host == null ->
+                    host = parseAddrPort(value) ?: return DeepLinkResult.Refused(LinkError.BAD_HOST_PARAM)
+                key == "launch" && launch == null -> {
+                    if (value.toByteArray(StandardCharsets.UTF_8).size > MAX_LAUNCH_LEN) {
+                        return DeepLinkResult.Refused(LinkError.PARAM_TOO_LONG, "launch")
+                    }
+                    if (!isSafeLaunchId(value)) return DeepLinkResult.Refused(LinkError.BAD_LAUNCH_ID)
+                    launch = value
+                }
+                key == "profile" && profile == null -> {
+                    if (scalarCount(value) > MAX_PROFILE_LEN) {
+                        return DeepLinkResult.Refused(LinkError.PARAM_TOO_LONG, "profile")
+                    }
+                    profile = value
+                }
+                key == "name" && name == null -> {
+                    if (scalarCount(value) > MAX_NAME_LEN) {
+                        return DeepLinkResult.Refused(LinkError.PARAM_TOO_LONG, "name")
+                    }
+                    name = value
+                }
+            }
+        }
+        return DeepLinkResult.Parsed(DeepLink(route, hostRef, fp, host, launch, profile, name))
+    }
+
+    /**
+     * Resolve a link's host reference against the local store, in the documented order: stable
+     * record id → unique case-insensitive name → `addr[:port]` literal. The `host=` parameter is
+     * the recovery path — a self-emitted shortcut that outlived the record it was written from
+     * still lands on the right box (degraded to the confirmation sheet).
+     */
+    fun resolveHost(link: DeepLink, hosts: List<KnownHost>): HostResolution {
+        hosts.firstOrNull { it.id == link.hostRef }?.let { return HostResolution.Known(it) }
+        val byName = hosts.filter { it.name.equals(link.hostRef, ignoreCase = true) }
+        when (byName.size) {
+            1 -> return HostResolution.Known(byName[0])
+            0 -> Unit
+            else -> return HostResolution.Ambiguous
+        }
+        // `addr[:port]` literal, then the `host=` recovery parameter — both matched the way every
+        // other per-host lookup matches. The literal is only considered when the reference COULD be
+        // an address: a stale record id must fall through to `host=` (or to a refusal), never be
+        // offered as a box to dial.
+        val literal = if (looksLikeAddress(link.hostRef)) parseAddrPort(link.hostRef) else null
+        for ((addr, port) in listOfNotNull(literal, link.host)) {
+            hosts.firstOrNull { it.address == addr && it.port == port }
+                ?.let { return HostResolution.Known(it) }
+        }
+        val fallback = literal ?: link.host ?: return HostResolution.Unresolvable
+        return HostResolution.Unknown(fallback.first, fallback.second, link.name, link.fp)
+    }
+
+    /**
+     * The self-emitted form for a saved host: id first (address-independent), with the address and
+     * pin alongside so the link degrades to a confirmation sheet instead of a dead click when the
+     * record is gone.
+     */
+    fun forHost(host: KnownHost, launch: String? = null, profile: String? = null) = DeepLink(
+        route = LinkRoute.CONNECT,
+        hostRef = host.id,
+        fp = host.fpHex.ifEmpty { null },
+        host = host.address to host.port,
+        launch = launch,
+        profile = profile,
+    )
+
+    /** The reserved first path segments — plus `pair`, reserved precisely so it can be refused. */
+    private fun isRouteWord(s: String) = s.lowercase() in setOf("connect", "wake", "browse", "pair")
+
+    /**
+     * Could this reference be a network address (an IP literal or a host name) rather than a record
+     * id or a display name? Only then may an unmatched reference become "an unknown host at this
+     * address". A stale record id is NOT an address: offering to dial a UUID as a hostname would
+     * turn a wiped store into a confusing dead end instead of the `host=`-driven recovery.
+     */
+    private fun looksLikeAddress(s: String): Boolean {
+        val uuidShaped = s.length == 36 && s.withIndex().all { (i, c) ->
+            if (i in setOf(8, 13, 18, 23)) c == '-' else isHex(c)
+        }
+        return !uuidShaped && s.isNotEmpty() &&
+            s.all { it.isLetterOrDigit() && it.code < 128 || it in ".-_:[]" }
+    }
+
+    /**
+     * `addr`, `addr:port`, `[v6]`, `[v6]:port` — null when the port isn't a number. A bare IPv6
+     * literal (`::1`) keeps its colons and takes the default port; anything else splits at the last
+     * colon, like every other host-parsing site in the clients.
+     */
+    private fun parseAddrPort(s: String): Pair<String, Int>? {
+        if (s.isEmpty()) return null
+        if (s.startsWith("[")) {
+            val close = s.indexOf(']', 1)
+            if (close < 0) return null
+            val addr = s.substring(1, close)
+            if (addr.isEmpty()) return null
+            val tail = s.substring(close + 1)
+            if (tail.isEmpty()) return addr to DEFAULT_PORT
+            if (!tail.startsWith(":")) return null
+            return addr to (tail.substring(1).toIntOrNull()?.takeIf { it in 1..65535 } ?: return null)
+        }
+        val lastColon = s.lastIndexOf(':')
+        if (lastColon < 0) return s to DEFAULT_PORT
+        val head = s.substring(0, lastColon)
+        // `::1` and friends: the head still has a colon, so this isn't a port separator.
+        if (head.contains(':')) return s to DEFAULT_PORT
+        if (head.isEmpty()) return null
+        val port = s.substring(lastColon + 1).toIntOrNull()?.takeIf { it in 1..65535 } ?: return null
+        return head to port
+    }
+
+    /**
+     * The launch-id charset the whole product already agrees on: printable, non-space ASCII with no
+     * shell metacharacters (Decky rides ids through Steam launch options as an env token, so a
+     * quote or a backtick genuinely breaks something downstream). Validation only — the id is
+     * opaque and the host matches it verbatim against its own library.
+     */
+    private fun isSafeLaunchId(id: String): Boolean =
+        id.isNotEmpty() && id.toByteArray(StandardCharsets.UTF_8)
+            .all { it in 0x21..0x7e && it.toInt().toChar() !in "\"'\\$`" }
+
+    /**
+     * Strict percent-decoding: `%` must be followed by exactly two hex digits, the result must be
+     * UTF-8, and no control character may survive. Lenient decoders are how `%00`, a stray newline
+     * or a half-escape end up inside a filename or a log line.
+     */
+    private fun decode(s: String): Decoded {
+        val bytes = s.toByteArray(StandardCharsets.UTF_8)
+        val out = java.io.ByteArrayOutputStream(bytes.size)
+        var i = 0
+        while (i < bytes.size) {
+            val b = bytes[i]
+            if (b == '%'.code.toByte()) {
+                if (i + 2 >= bytes.size) return Decoded.Err(LinkError.BAD_ESCAPE)
+                val hi = hexValue(bytes[i + 1].toInt().toChar())
+                val lo = hexValue(bytes[i + 2].toInt().toChar())
+                if (hi < 0 || lo < 0) return Decoded.Err(LinkError.BAD_ESCAPE)
+                out.write(hi * 16 + lo)
+                i += 3
+            } else {
+                out.write(b.toInt())
+                i += 1
+            }
+        }
+        // REPORT, not the default REPLACE: `%FF` must be a refusal, never a U+FFFD that survives.
+        val decoder = StandardCharsets.UTF_8.newDecoder()
+            .onMalformedInput(CodingErrorAction.REPORT)
+            .onUnmappableCharacter(CodingErrorAction.REPORT)
+        val text = runCatching { decoder.decode(ByteBuffer.wrap(out.toByteArray())).toString() }
+            .getOrNull() ?: return Decoded.Err(LinkError.BAD_ESCAPE)
+        // `Char.isISOControl` is exactly Unicode's Cc category (C0 + DEL + C1), which is what the
+        // Rust side rejects.
+        if (text.any { it.isISOControl() }) return Decoded.Err(LinkError.CONTROL_CHAR)
+        return Decoded.Ok(text)
+    }
+
+    /** [decode]'s outcome — the decoded text, or which refusal it is. */
+    private sealed interface Decoded {
+        data class Ok(val text: String) : Decoded
+        data class Err(val error: LinkError) : Decoded
+    }
+
+    private fun hexValue(c: Char): Int = when (c) {
+        in '0'..'9' -> c - '0'
+        in 'a'..'f' -> c - 'a' + 10
+        in 'A'..'F' -> c - 'A' + 10
+        else -> -1
+    }
+
+    private fun isHex(c: Char) = hexValue(c) >= 0
+
+    /** Unicode scalars, matching the Rust caps (which count `chars()`, not UTF-16 units). */
+    private fun scalarCount(s: String) = s.codePointCount(0, s.length)
+
+    /**
+     * Percent-encode for emission: unreserved characters plus `:` (legal in a query value and left
+     * alone by Apple's `URLComponents`, so the three emitters agree on `steam:570`).
+     */
+    internal fun encode(s: String): String {
+        val out = StringBuilder(s.length)
+        for (b in s.toByteArray(StandardCharsets.UTF_8)) {
+            val c = b.toInt().toChar()
+            if (c in 'A'..'Z' || c in 'a'..'z' || c in '0'..'9' || c in "-._~:") {
+                out.append(c)
+            } else {
+                out.append('%').append("%02X".format(b.toInt() and 0xFF))
+            }
+        }
+        return out.toString()
+    }
+}
+
+/** What the URL asks for. `WAKE`/`BROWSE` are reserved in the grammar and parse today. */
+enum class LinkRoute(val word: String) {
+    CONNECT("connect"),
+    WAKE("wake"),
+    BROWSE("browse"),
+}
+
+/**
+ * Why a URL was rejected. The [code] strings are the cross-language contract — the vector file names
+ * them, and Swift and Rust report the same code for the same input.
+ */
+enum class LinkError(val code: String) {
+    /** Not a `punktfunk://` (or `pf://`) URL at all — ignore it, don't warn. */
+    NOT_OUR_SCHEME("not-our-scheme"),
+    TOO_LONG("too-long"),
+    UNKNOWN_ROUTE("unknown-route"),
+
+    /** `punktfunk://pair/…` — pairing is an interactive ceremony, never a link. */
+    PAIR_REFUSED("pair-refused"),
+    MISSING_HOST_REF("missing-host-ref"),
+
+    /** A `%` escape that isn't two hex digits, or a decode that isn't UTF-8. */
+    BAD_ESCAPE("bad-escape"),
+
+    /** A control character survived decoding — no legitimate field contains one. */
+    CONTROL_CHAR("control-char"),
+    PARAM_TOO_LONG("param-too-long"),
+    BAD_FINGERPRINT("bad-fingerprint"),
+    BAD_HOST_PARAM("bad-host-param"),
+    BAD_LAUNCH_ID("bad-launch-id"),
+}
+
+/**
+ * A parsed, validated link. Every field is already length- and charset-checked, so a consumer never
+ * has to re-validate hostile input.
+ */
+data class DeepLink(
+    val route: LinkRoute = LinkRoute.CONNECT,
+    /** The host reference as written: a stable record id, a host name, or `addr[:port]`. */
+    val hostRef: String,
+    /** Expected host certificate fingerprint, lowercase hex (64 chars). */
+    val fp: String? = null,
+    /** Recovery address for a stable id that no longer resolves (store wiped, reinstall). */
+    val host: Pair<String, Int>? = null,
+    /** A store-qualified library id (`steam:570`) for the host to launch on arrival. */
+    val launch: String? = null,
+    /** A settings-profile reference (id, or a unique name) — one-off, never rebinding. */
+    val profile: String? = null,
+    /** Display label for the unknown-host confirmation sheet (external emitters). */
+    val name: String? = null,
+) {
+    /** The canonical URL for this link — always `punktfunk://`, never the `pf://` alias. */
+    fun toUrl(): String {
+        val sb = StringBuilder("punktfunk://${route.word}/${DeepLinks.encode(hostRef)}")
+        var sep = '?'
+        fun push(key: String, value: String) {
+            sb.append(sep).append(key).append('=').append(DeepLinks.encode(value))
+            sep = '&'
+        }
+        fp?.let { push("fp", it) }
+        host?.let { (addr, port) ->
+            push(
+                "host",
+                when {
+                    port == DeepLinks.DEFAULT_PORT -> addr
+                    addr.contains(':') -> "[$addr]:$port" // literal IPv6 needs its brackets back
+                    else -> "$addr:$port"
+                },
+            )
+        }
+        launch?.let { push("launch", it) }
+        profile?.let { push("profile", it) }
+        name?.let { push("name", it) }
+        return sb.toString()
+    }
+
+    /**
+     * True when this link's `fp` contradicts what we have pinned for that host — the link is stale
+     * or lying, and the only safe answer is a hard refusal.
+     */
+    fun pinConflict(host: KnownHost): Boolean =
+        fp != null && host.fpHex.isNotEmpty() && !fp.equals(host.fpHex, ignoreCase = true)
+}
+
+/** A parse outcome: a link, or a refusal carrying the shared code. */
+sealed interface DeepLinkResult {
+    data class Parsed(val link: DeepLink) : DeepLinkResult
+
+    data class Refused(val error: LinkError, val detail: String? = null) : DeepLinkResult {
+        /**
+         * A sentence for the notice a refusing front-end shows. Deliberately names what failed: a
+         * shortcut that can't honour its reference says so instead of streaming with the wrong one.
+         */
+        fun message(): String = when (error) {
+            LinkError.NOT_OUR_SCHEME -> "That isn't a Punktfunk link."
+            LinkError.TOO_LONG -> "That link is too long to be genuine."
+            LinkError.UNKNOWN_ROUTE -> "Punktfunk links can't do “$detail”."
+            LinkError.PAIR_REFUSED ->
+                "Pairing can't be done from a link — pair the host in Punktfunk first."
+            LinkError.MISSING_HOST_REF -> "That link doesn't say which host to use."
+            LinkError.BAD_ESCAPE, LinkError.CONTROL_CHAR -> "That link is malformed and was ignored."
+            LinkError.PARAM_TOO_LONG -> "That link's “$detail” value is too long."
+            LinkError.BAD_FINGERPRINT -> "That link's host fingerprint isn't a valid one."
+            LinkError.BAD_HOST_PARAM -> "That link's host address isn't valid."
+            LinkError.BAD_LAUNCH_ID -> "That link's game id isn't a valid one."
+        }
+    }
+}
+
+/** What the local host store made of a link's references. */
+sealed interface HostResolution {
+    /** A record we already trust (subject to [DeepLink.pinConflict]). */
+    data class Known(val host: KnownHost) : HostResolution
+
+    /**
+     * No record, but the link says where to dial: the confirmation sheet's input, from which the
+     * normal pairing/TOFU flow proceeds under the user's eyes. Never an auto-connect.
+     */
+    data class Unknown(
+        val address: String,
+        val port: Int,
+        val name: String?,
+        val fp: String?,
+    ) : HostResolution
+
+    /** The name matched more than one saved host — refuse with a notice, never guess. */
+    data object Ambiguous : HostResolution
+
+    /** A reference that resolves to nothing and carries no address to fall back on. */
+    data object Unresolvable : HostResolution
+}
@@ -1,11 +1,19 @@
 package io.unom.punktfunk.kit.security

 import android.content.Context
+import java.util.UUID
+import org.json.JSONArray
 import org.json.JSONObject

 /**
 * A host the user has trusted (pinned). [fpHex] is the pinned host-cert SHA-256 (64-hex); [paired]
 * is true when trust was established via the SPAKE2 PIN ceremony (vs trust-on-first-use).
+ *
+ * [id] is the record's **stable identity** — minted once, never changed, and the key this record is
+ * stored under. Everything that needs to point AT a host (a settings-profile binding, a pinned
+ * card, a `punktfunk://` link) points at the id, so renaming a host or moving it to a new address
+ * doesn't strand those references. Mirrors the Apple client's `StoredHost.id` and the Rust
+ * `KnownHost.id`; the shape is a lowercase UUID v4, one grammar on every platform.
 */
 data class KnownHost(
    val address: String,
@@ -18,37 +26,85 @@ data class KnownHost(
     * online, so the client can wake it once it sleeps. Empty until first learned.
     */
    val mac: List<String> = emptyList(),
+    /**
+     * The host's OS-identity chain (`windows` | `linux/<family>/<id>`, ...) learned from its mDNS
+     * `os` TXT while online, so the card's OS icon survives the host going to sleep. Empty until
+     * first learned (or forever, against an older host).
+     */
+    val os: String = "",
+    /** Stable record identity — see the class doc. Minted here for a genuinely new record. */
+    val id: String = newRecordId(),
+    /**
+     * Sync text copied on this device to this host and back while streaming. **A property of the
+     * host, not of the stream** (design/client-settings-profiles.md §3, tier H): it is a trust
+     * decision about that machine, so it is never in a settings profile and never global — the
+     * work box and the couch box get their own answers. Only effective when the host advertises
+     * the clipboard capability; the protocol is opt-in per session either way.
+     */
+    val clipboardSync: Boolean = true,
+    /**
+     * The settings profile a plain tap on this host connects with — `null` (or an id whose profile
+     * was deleted) means the global defaults, i.e. today's behaviour. A dangling id is never an
+     * error and never blocks a connect.
+     */
+    val profileId: String? = null,
+    /**
+     * Profiles pinned as their own cards for this host (design §5.2a). Presentation only: order is
+     * card order, and this is NOT the default binding ([profileId] is). Duplicates and profiles
+     * that no longer exist are dropped when the cards are rendered.
+     */
+    val pinnedProfileIds: List<String> = emptyList(),
 )

 /**
 * Persists trusted hosts — the pinned-fingerprint store *and* the saved-hosts list — keyed by
- * `address:port`. Replaces the old fp-only PinStore so a discovered and a manually-typed connection
- * to the same host share one trust record (and so saved hosts can be listed + reconnected). Plain
- * `SharedPreferences` in app-private storage: pinned fingerprints are public host identities, not
- * secrets; the property we need is integrity, which app sandboxing provides.
+ * [KnownHost.id]. Plain `SharedPreferences` in app-private storage: pinned fingerprints are public
+ * host identities, not secrets; the property we need is integrity, which app sandboxing provides.
+ *
+ * Records used to be keyed by `"address:port"`, which meant editing a host's address had to
+ * re-key its record (delete + write) or leave a ghost behind, and meant nothing could hold a
+ * durable reference to a host. Keying by the minted stable id retires both. [migrate] moves an
+ * existing store over in one pass — see its doc for what else rides along.
 */
 class KnownHostStore(context: Context) {
    private val prefs =
-        context.applicationContext.getSharedPreferences("punktfunk_hosts", Context.MODE_PRIVATE)
+        context.applicationContext.getSharedPreferences(PREFS_HOSTS, Context.MODE_PRIVATE)

-    // The pref key is just a unique id; address/port are also stored in the value so an IPv6
-    // address (which contains colons) round-trips without parsing the key.
-    private fun key(address: String, port: Int) = "$address:$port"
+    init {
+        migrateIfNeeded(context)
+    }

    /** The trusted record for [address]:[port], or `null` if this host has never been trusted. */
    fun get(address: String, port: Int): KnownHost? =
-        prefs.getString(key(address, port), null)?.let(::parse)
+        all().firstOrNull { it.address == address && it.port == port }

-    /** Pin (or update) a trusted host — upsert by `address:port`. */
+    /** The trusted record with this stable [id], or `null` — the lookup a binding or link uses. */
+    fun byId(id: String): KnownHost? = prefs.getString(id, null)?.let(::parse)
+
+    /**
+     * Pin (or update) a trusted host — upsert by [KnownHost.id]. An edit that moves the address or
+     * port is a plain save now: the key is the identity, not the address.
+     */
    fun save(host: KnownHost) {
-        val json = JSONObject()
-            .put("addr", host.address)
-            .put("port", host.port)
-            .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()
+        prefs.edit().putString(host.id, encode(host)).apply()
+    }
+
+    /**
+     * Trust (or re-trust) the host at [address]:[port] with the fingerprint it presented.
+     *
+     * When a record already exists there — a re-pair after the host's identity changed, an
+     * approval that upgrades a TOFU record to paired — it keeps its identity and everything the
+     * user set on it: the stable [KnownHost.id] (so profile bindings, pinned cards and any
+     * `punktfunk://` shortcut still point at it), the per-host clipboard decision, the binding,
+     * the pins and the learned MACs. Only the name, pin and paired flag are refreshed. Returns the
+     * stored record.
+     */
+    fun trust(address: String, port: Int, name: String, fpHex: String, paired: Boolean): KnownHost {
+        val existing = get(address, port)
+        val host = existing?.copy(name = name, fpHex = fpHex, paired = paired)
+            ?: KnownHost(address, port, name, fpHex, paired)
+        save(host)
+        return host
    }

    /**
@@ -63,30 +119,56 @@ class KnownHostStore(context: Context) {
        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()
-    }
-
-    /** Set a saved host's display name, keeping its pin + paired flag. No-op if not saved. */
-    fun rename(address: String, port: Int, newName: String) {
-        val h = get(address, port) ?: return
-        save(h.copy(name = newName))
-    }
-
    /**
-     * Edit a saved host, RE-KEYING if the address or port changed (the pref key IS `address:port`, so
-     * a plain [save] would otherwise leave a stale record under the old key). The caller passes an
-     * [updated] copy that preserves `fpHex`/`paired` (and sets `mac` from the edit form).
+     * Learn/refresh a saved host's OS-identity chain from its live advert — same contract as
+     * [learnMac]: no-op when unsaved, empty, or unchanged.
     */
-    fun update(oldAddress: String, oldPort: Int, updated: KnownHost) {
-        if (oldAddress != updated.address || oldPort != updated.port) remove(oldAddress, oldPort)
-        save(updated)
+    fun learnOs(address: String, port: Int, os: String) {
+        if (os.isEmpty()) return
+        val h = get(address, port) ?: return
+        if (h.os == os) return
+        save(h.copy(os = os))
+    }
+
+    /** Forget [host] (the next connect re-pairs / re-TOFUs). */
+    fun remove(host: KnownHost) {
+        prefs.edit().remove(host.id).apply()
    }

    /** All trusted hosts, name-sorted — backs the saved-hosts list. */
-    fun all(): List<KnownHost> =
-        prefs.all.values.mapNotNull { (it as? String)?.let(::parse) }.sortedBy { it.name.lowercase() }
+    fun all(): List<KnownHost> = prefs.all
+        .filterKeys { it != K_SCHEMA }
+        .values
+        .mapNotNull { (it as? String)?.let(::parse) }
+        .sortedBy { it.name.lowercase() }
+
+    /**
+     * One-time move from the `"address:port"`-keyed schema to id-keyed records, run on first
+     * construction after the upgrade and never again ([K_SCHEMA] records that it happened).
+     *
+     * It is deliberately ONE pass, not three: the store is being rewritten anyway, and every extra
+     * migration pass is another chance to strand somebody's hosts. So the same pass mints the
+     * stable id, re-keys the record onto it, and copies the retiring GLOBAL clipboard-sync setting
+     * onto every host — behaviour-preserving, since every host was following that one value.
+     */
+    private fun migrateIfNeeded(context: Context) {
+        if (prefs.getInt(K_SCHEMA, 0) >= SCHEMA_VERSION) return
+        val settings =
+            context.applicationContext.getSharedPreferences(PREFS_SETTINGS, Context.MODE_PRIVATE)
+        val result = migrate(prefs.all, settings.getBoolean(K_GLOBAL_CLIPBOARD_SYNC, true))
+        // `commit`, not `apply`: the re-keyed records and the schema flag are one atomic write to
+        // disk, and the global below is only retired once that write has landed. With `apply` a
+        // process death in between could drop the old global while the hosts that were supposed to
+        // inherit it were still only in memory. Once, on one small file, on an upgrade.
+        val written = prefs.edit().apply {
+            result.removals.forEach(::remove)
+            result.writes.forEach { (k, v) -> putString(k, v) }
+            putInt(K_SCHEMA, SCHEMA_VERSION)
+        }.commit()
+        if (written && settings.contains(K_GLOBAL_CLIPBOARD_SYNC)) {
+            settings.edit().remove(K_GLOBAL_CLIPBOARD_SYNC).apply()
+        }
+    }

    private fun parse(s: String): KnownHost? = runCatching {
        val j = JSONObject(s)
@@ -97,10 +179,67 @@ class KnownHostStore(context: Context) {
            fpHex = j.getString("fp"),
            paired = j.optBoolean("paired", false),
            mac = j.optString("mac", "").split(",").map { it.trim() }.filter { it.isNotEmpty() },
+            os = j.optString("os", ""),
+            // A record without an id can only be one this build wrote before the migration ran, or
+            // a hand-edited file; minting here keeps the parse total rather than dropping a host.
+            id = j.optString("id", "").ifEmpty { newRecordId() },
+            clipboardSync = j.optBoolean("clip", true),
+            profileId = j.optString("profile", "").ifEmpty { null },
+            pinnedProfileIds = stringList(j.optJSONArray("pins")),
        )
    }.getOrNull()

    companion object {
+        /** The prefs file holding the host records. */
+        private const val PREFS_HOSTS = "punktfunk_hosts"
+
+        /** The app's settings file — read once by [migrate] for the retiring global. */
+        private const val PREFS_SETTINGS = "punktfunk_settings"
+
+        /**
+         * The global clipboard-sync key this migration retires. Clipboard sync is a decision about
+         * a HOST (design §3, tier H), so it lives on the record now; the global is read once, to
+         * seed every host, and then deleted.
+         */
+        private const val K_GLOBAL_CLIPBOARD_SYNC = "clipboard_sync"
+
+        /** Schema marker inside the hosts file. Reserved — never a host record. */
+        private const val K_SCHEMA = "__schema"
+
+        /** 1 = id-keyed records with per-host clipboard sync, profile binding and pins. */
+        private const val SCHEMA_VERSION = 1
+
+        /** What [migrate] decided: entries to write, and (old) keys to drop. */
+        data class Migration(val writes: Map<String, String>, val removals: Set<String>)
+
+        /**
+         * The pure half of the store migration, over a raw prefs snapshot ([entries] as returned by
+         * `SharedPreferences.all`) — so it can be tested against a real pre-migration blob without
+         * an Android runtime.
+         *
+         * Every host record survives with its address, port, name, pin, paired flag and MACs
+         * intact, gains a minted [KnownHost.id], moves to that key, and takes
+         * [globalClipboardSync] as its own [KnownHost.clipboardSync]. Entries that aren't parsable
+         * host records are left alone: they were already invisible (`all()` skipped them), and
+         * deleting things we don't understand is not this pass's job.
+         */
+        fun migrate(entries: Map<String, Any?>, globalClipboardSync: Boolean): Migration {
+            val writes = mutableMapOf<String, String>()
+            val removals = mutableSetOf<String>()
+            for ((key, raw) in entries) {
+                if (key == K_SCHEMA) continue
+                val json = (raw as? String)?.let { runCatching { JSONObject(it) }.getOrNull() }
+                    ?: continue
+                if (!json.has("addr") || !json.has("port")) continue
+                val id = json.optString("id", "").ifEmpty { newRecordId() }
+                json.put("id", id)
+                json.put("clip", json.optBoolean("clip", globalClipboardSync))
+                writes[id] = json.toString()
+                if (key != id) removals += key
+            }
+            return Migration(writes, removals)
+        }
+
        /**
         * Parse a free-typed Wake-on-LAN field into normalized `aa:bb:cc:dd:ee:ff` entries (comma /
         * space / newline separated). Anything that isn't six colon-separated hex octets is dropped;
@@ -116,5 +255,32 @@ class KnownHostStore(context: Context) {
                    o.size == 6 && o.all { it.length == 2 && it.all { c -> c in '0'..'9' || c in 'a'..'f' } }
                }
            }
+
+        /** The stored JSON for one record — also the shape [migrate] upgrades into. */
+        internal fun encode(host: KnownHost): String = JSONObject()
+            .put("id", host.id)
+            .put("addr", host.address)
+            .put("port", host.port)
+            .put("name", host.name)
+            .put("fp", host.fpHex.lowercase())
+            .put("paired", host.paired)
+            .put("mac", host.mac.joinToString(","))
+            .put("os", host.os)
+            .put("clip", host.clipboardSync)
+            .put("profile", host.profileId ?: "")
+            .put("pins", JSONArray(host.pinnedProfileIds))
+            .toString()
+
+        private fun stringList(a: JSONArray?): List<String> {
+            if (a == null) return emptyList()
+            return (0 until a.length()).mapNotNull { a.optString(it, "").ifEmpty { null } }
+        }
    }
 }
+
+/**
+ * A fresh stable record identity: a lowercase UUID v4, the shape the Apple client's `StoredHost.id`
+ * and the Rust `KnownHost.id` already use, so a `punktfunk://` host reference is one grammar
+ * everywhere.
+ */
+fun newRecordId(): String = UUID.randomUUID().toString()
@@ -0,0 +1,224 @@
+package io.unom.punktfunk.kit
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Pure JVM tests of the Sony USB report codec ([DsDevice]) — the byte-exact inverse of the
+ * host's `dualsense_proto.rs` / `dualshock4_proto.rs` serializers (offsets cross-checked against
+ * those files' own tests). No Android runtime types ([Gamepad]'s BTN_* are compile-time ints).
+ * Run: `./gradlew :kit:testDebugUnitTest`.
+ */
+class DsDeviceTest {
+    private fun ds5Report(mutate: (ByteArray) -> Unit = {}): ByteArray =
+        ByteArray(64).also {
+            it[0] = 0x01
+            // Sticks centred, hat neutral (8).
+            it[1] = 0x80.toByte(); it[2] = 0x80.toByte(); it[3] = 0x80.toByte(); it[4] = 0x80.toByte()
+            it[8] = 0x08
+            // Touch points inactive (bit7 set).
+            it[33] = 0x80.toByte(); it[37] = 0x80.toByte()
+            mutate(it)
+        }
+
+    private fun ds4Report(mutate: (ByteArray) -> Unit = {}): ByteArray =
+        ByteArray(64).also {
+            it[0] = 0x01
+            it[1] = 0x80.toByte(); it[2] = 0x80.toByte(); it[3] = 0x80.toByte(); it[4] = 0x80.toByte()
+            it[5] = 0x08
+            it[35] = 0x80.toByte(); it[39] = 0x80.toByte()
+            mutate(it)
+        }
+
+    // ---- input parse ----
+
+    @Test
+    fun ds5ButtonsMapPositionally() {
+        val s = DsDevice.State()
+        // cross+triangle, hat NE, L1+create+L3, PS+touchpad+mute.
+        val r = ds5Report {
+            it[8] = (0x20 or 0x80 or 0x01).toByte() // cross | triangle | hat=1 (NE)
+            it[9] = (0x01 or 0x10 or 0x40).toByte() // L1 | create | L3
+            it[10] = (0x01 or 0x02 or 0x04).toByte() // PS | touchpad | mute
+        }
+        assertTrue(DsDevice.parseState(DsDevice.Model.DUALSENSE, r, 64, s))
+        val expected = Gamepad.BTN_A or Gamepad.BTN_Y or
+            Gamepad.BTN_DPAD_UP or Gamepad.BTN_DPAD_RIGHT or
+            Gamepad.BTN_LB or Gamepad.BTN_BACK or Gamepad.BTN_LS_CLICK or
+            Gamepad.BTN_GUIDE or Gamepad.BTN_TOUCHPAD or Gamepad.BTN_MISC1
+        assertEquals(expected, s.buttons)
+    }
+
+    @Test
+    fun ds5SticksInvertYAndCoverTheFullRange() {
+        val s = DsDevice.State()
+        // Device +y down; wire +y up. Left stick fully up-left, right stick fully down-right.
+        val r = ds5Report {
+            it[1] = 0x00; it[2] = 0x00 // lx min, ly min (up)
+            it[3] = 0xFF.toByte(); it[4] = 0xFF.toByte() // rx max, ry max (down)
+            it[5] = 0x40; it[6] = 0xFF.toByte()
+        }
+        assertTrue(DsDevice.parseState(DsDevice.Model.DUALSENSE, r, 64, s))
+        assertEquals(-32768, s.lsX)
+        assertEquals(32767, s.lsY) // device up → wire +32767
+        assertEquals(32767, s.rsX)
+        assertEquals(-32768, s.rsY) // device down → wire −32768
+        assertEquals(0x40, s.lt)
+        assertEquals(0xFF, s.rt)
+        // Centre stays (near) centre: 0x80 → 128 wire units of bias, the u8 grid's own offset.
+        val c = DsDevice.State()
+        assertTrue(DsDevice.parseState(DsDevice.Model.DUALSENSE, ds5Report(), 64, c))
+        assertEquals(128, c.lsX)
+        assertEquals(-129, c.lsY)
+    }
+
+    @Test
+    fun ds5MotionAndTouchUnpack() {
+        val s = DsDevice.State()
+        val r = ds5Report {
+            // gyro pitch = 0x0102, accel z = -2 (LE i16s at 16.. / 22..).
+            it[16] = 0x02; it[17] = 0x01
+            it[26] = 0xFE.toByte(); it[27] = 0xFF.toByte()
+            // Touch 0 active, id 5, x=1919 (0x77F), y=1079 (0x437):
+            // b0=0x05, b1=0x7F, b2=(x>>8)|((y&0xF)<<4)=0x77, y>>4=0x43.
+            it[33] = 0x05
+            it[34] = 0x7F
+            it[35] = (0x07 or (0x07 shl 4)).toByte()
+            it[36] = 0x43
+        }
+        assertTrue(DsDevice.parseState(DsDevice.Model.DUALSENSE, r, 64, s))
+        assertEquals(0x0102, s.gyro[0])
+        assertEquals(-2, s.accel[2])
+        assertTrue(s.touchActive[0])
+        assertEquals(1919, s.touchX[0])
+        assertEquals(1079, s.touchY[0])
+        assertFalse(s.touchActive[1])
+    }
+
+    @Test
+    fun edgePaddlesParseOnlyOnTheEdge() {
+        val r = ds5Report { it[10] = 0xF0.toByte() } // all four FN/BACK bits
+        val edge = DsDevice.State()
+        assertTrue(DsDevice.parseState(DsDevice.Model.DUALSENSE_EDGE, r, 64, edge))
+        // Host inverse (`edge_paddle_bits`): PADDLE1/2 = right/left BACK, PADDLE3/4 = right/left Fn.
+        assertEquals(
+            Gamepad.BTN_PADDLE1 or Gamepad.BTN_PADDLE2 or Gamepad.BTN_PADDLE3 or Gamepad.BTN_PADDLE4,
+            edge.buttons,
+        )
+        val plain = DsDevice.State()
+        assertTrue(DsDevice.parseState(DsDevice.Model.DUALSENSE, r, 64, plain))
+        assertEquals(0, plain.buttons) // a non-Edge never reports phantom paddles
+    }
+
+    @Test
+    fun ds4LayoutDiffersWhereItShould() {
+        val s = DsDevice.State()
+        val r = ds4Report {
+            it[5] = (0x10 or 0x04).toByte() // square | hat=4 (down)
+            it[6] = (0x10 or 0x20).toByte() // share | options
+            it[7] = 0x03 // PS | touchpad click
+            it[8] = 0x11 // L2 analog
+            it[9] = 0x99.toByte() // R2 analog
+            // gyro yaw at 15.. (second i16 of 13..19).
+            it[15] = 0x34; it[16] = 0x12
+            // Touch 0 active id 3 at x=100 (0x064), y=941 (0x3AD): b1=0x64, b2=0xD0, b3=0x3A.
+            it[35] = 0x03
+            it[36] = 0x64
+            it[37] = 0xD0.toByte()
+            it[38] = 0x3A
+        }
+        assertTrue(DsDevice.parseState(DsDevice.Model.DUALSHOCK4, r, 64, s))
+        assertEquals(
+            Gamepad.BTN_X or Gamepad.BTN_DPAD_DOWN or Gamepad.BTN_BACK or Gamepad.BTN_START or
+                Gamepad.BTN_GUIDE or Gamepad.BTN_TOUCHPAD,
+            s.buttons,
+        )
+        assertEquals(0x11, s.lt)
+        assertEquals(0x99, s.rt)
+        assertEquals(0x1234, s.gyro[1])
+        assertTrue(s.touchActive[0])
+        assertEquals(100, s.touchX[0])
+        assertEquals(941, s.touchY[0])
+    }
+
+    @Test
+    fun rejectsForeignAndShortReports() {
+        val s = DsDevice.State()
+        assertFalse(DsDevice.parseState(DsDevice.Model.DUALSENSE, ds5Report { it[0] = 0x31 }, 64, s))
+        assertFalse(DsDevice.parseState(DsDevice.Model.DUALSENSE, ds5Report(), 8, s))
+        assertFalse(DsDevice.parseState(DsDevice.Model.DUALSHOCK4, ds4Report(), 8, s))
+    }
+
+    // ---- output builders (offsets = the host parser's: `parse_ds_output` / `parse_ds4_output`) ----
+
+    @Test
+    fun ds5RumbleReportFlagsAndMotors() {
+        val r = DsDevice.ds5RumbleReport(DsDevice.Model.DUALSENSE, low = 0xFF00, high = 0x1200)
+        assertEquals(48, r.size)
+        assertEquals(0x02, r[0].toInt())
+        assertEquals(0x03, r[1].toInt()) // compat vibration | haptics select
+        assertEquals(0x04, r[39].toInt()) // VIBRATION2 (fw ≥ 2.24)
+        assertEquals(0x12, r[3].toInt() and 0xFF) // high = right/small at [3]
+        assertEquals(0xFF, r[4].toInt() and 0xFF) // low = left/big at [4]
+        // A nonzero amplitude never collapses to motor 0.
+        assertEquals(1, DsDevice.ds5RumbleReport(DsDevice.Model.DUALSENSE, 0x00FF, 0)[4].toInt())
+        // The Edge's output report is the 64-byte variant.
+        assertEquals(64, DsDevice.ds5RumbleReport(DsDevice.Model.DUALSENSE_EDGE, 0, 0).size)
+    }
+
+    @Test
+    fun ds5TriggerReportPlacesTheBlockPerSide() {
+        val effect = ByteArray(11) { (it + 1).toByte() }
+        val r2 = DsDevice.ds5TriggerReport(DsDevice.Model.DUALSENSE, which = 1, effect = effect)
+        assertEquals(0x04, r2[1].toInt()) // R2 valid flag
+        assertEquals(1, r2[11].toInt()) // block at [11..22)
+        assertEquals(11, r2[21].toInt())
+        assertEquals(0, r2[22].toInt())
+        val l2 = DsDevice.ds5TriggerReport(DsDevice.Model.DUALSENSE, which = 0, effect = effect)
+        assertEquals(0x08, l2[1].toInt()) // L2 valid flag
+        assertEquals(1, l2[22].toInt()) // block at [22..33)
+        assertEquals(11, l2[32].toInt())
+        // Oversized wire effects clamp to the 11-byte hardware block.
+        val big = DsDevice.ds5TriggerReport(DsDevice.Model.DUALSENSE, 1, ByteArray(20) { 0x7F })
+        assertEquals(0, big[22].toInt())
+    }
+
+    @Test
+    fun ds5LightbarPlayerLedsAndInit() {
+        val led = DsDevice.ds5LightbarReport(DsDevice.Model.DUALSENSE, 1, 2, 3)
+        assertEquals(0x04, led[2].toInt()) // lightbar valid flag
+        assertEquals(1, led[45].toInt()); assertEquals(2, led[46].toInt()); assertEquals(3, led[47].toInt())
+        val pl = DsDevice.ds5PlayerLedsReport(DsDevice.Model.DUALSENSE, 0xFF)
+        assertEquals(0x10, pl[2].toInt()) // player-LED valid flag
+        assertEquals(0x1F, pl[44].toInt()) // masked to the 5 LEDs
+        val init = DsDevice.ds5InitReport(DsDevice.Model.DUALSENSE)
+        assertEquals(0x02, init[39].toInt()) // lightbar-setup enable
+        assertEquals(0x02, init[42].toInt()) // LIGHT_OUT — releases the firmware animation
+    }
+
+    @Test
+    fun ds4ReportIsAFullStateWrite() {
+        val r = DsDevice.ds4Report(low = 0xAB00, high = 0x0100, r = 9, g = 8, b = 7)
+        assertEquals(32, r.size)
+        assertEquals(0x05, r[0].toInt())
+        assertEquals(0x03, r[1].toInt()) // motors | LED, both — composed state
+        assertEquals(0x01, r[4].toInt()) // high = weak/right at [4]
+        assertEquals(0xAB, r[5].toInt() and 0xFF) // low = strong/left at [5]
+        assertEquals(9, r[6].toInt()); assertEquals(8, r[7].toInt()); assertEquals(7, r[8].toInt())
+        assertEquals(0, r[9].toInt()) // blink untouched
+    }
+
+    @Test
+    fun modelResolution() {
+        assertEquals(DsDevice.Model.DUALSENSE, DsDevice.modelFor(0x0CE6))
+        assertEquals(DsDevice.Model.DUALSENSE_EDGE, DsDevice.modelFor(0x0DF2))
+        assertEquals(DsDevice.Model.DUALSHOCK4, DsDevice.modelFor(0x05C4))
+        assertEquals(DsDevice.Model.DUALSHOCK4, DsDevice.modelFor(0x09CC))
+        assertEquals(null, DsDevice.modelFor(0x1234))
+        assertEquals(Gamepad.PREF_DUALSENSE, DsDevice.Model.DUALSENSE.pref)
+        assertEquals(Gamepad.PREF_DUALSENSEEDGE, DsDevice.Model.DUALSENSE_EDGE.pref)
+        assertEquals(Gamepad.PREF_DUALSHOCK4, DsDevice.Model.DUALSHOCK4.pref)
+    }
+}
@@ -33,6 +33,39 @@ class ParseRecordTest {
        assertEquals(false, h.pairingRequired)
    }

+    @Test
+    fun sevenFieldRecordHasNoOs() {
+        // A native lib predating the 8th field: `os` defaults empty, everything else parses.
+        val h = parseHostRecord(rec("k", "n", "10.0.0.5", "9777", "", "optional", "aa:bb:cc:dd:ee:ff"))!!
+        assertEquals(listOf("aa:bb:cc:dd:ee:ff"), h.mac)
+        assertEquals("", h.os)
+    }
+
+    @Test
+    fun eighthFieldCarriesTheOsChain() {
+        val h = parseHostRecord(
+            rec("k", "n", "10.0.0.5", "9777", "", "optional", "", "linux/fedora/bazzite"),
+        )!!
+        assertEquals("linux/fedora/bazzite", h.os)
+    }
+
+    @Test
+    fun osChainIsSanitizedAsUntrustedInput() {
+        // mDNS is unauthenticated: junk is dropped, case folds, token/count caps apply.
+        val h = parseHostRecord(rec("k", "n", "10.0.0.5", "9777", "", "optional", "", "Linux/Fe do!ra"))!!
+        assertEquals("linux/fedora", h.os)
+        assertEquals("", sanitizeOsChain("///!!!"))
+        assertEquals("a/b/c/d/e", sanitizeOsChain("a/b/c/d/e/f/g"))
+    }
+
+    @Test
+    fun iconWalkIsMostSpecificFirstWithAliases() {
+        assertEquals(listOf("bazzite", "fedora", "linux"), osIconTokens("linux/fedora/bazzite"))
+        assertEquals(listOf("steam", "arch", "linux"), osIconTokens("linux/arch/steamos"))
+        assertEquals(listOf("apple"), osIconTokens("macos"))
+        assertTrue(osIconTokens("").isEmpty())
+    }
+
    @Test
    fun emptyKeyFallsBackToAddrPort() {
        // Host advertised no `id` TXT → the native side leaves the key blank; we synthesize addr:port.
@@ -0,0 +1,160 @@
+package io.unom.punktfunk.kit.link
+
+import io.unom.punktfunk.kit.security.KnownHost
+import java.io.File
+import org.json.JSONObject
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * **The cross-language contract.** `clients/shared/deeplink-vectors.json` is consumed verbatim by
+ * the Rust, Swift and Kotlin suites, so the three parsers cannot drift into three different
+ * security postures — a URL that Rust refuses as a control-character smuggle must not quietly
+ * parse here. Any new case belongs in that file, not in this one.
+ */
+class DeepLinkVectorTest {
+    private val vectors: JSONObject by lazy {
+        // Gradle runs a unit test with the module directory as its working directory, so the shared
+        // file is two levels up (clients/android/kit → clients/shared). Resolved rather than
+        // copied: a copy would be a fourth contract, free to go stale.
+        val file = File("../../shared/deeplink-vectors.json")
+        assertTrue(
+            "the shared vector file must be reachable at ${file.absolutePath}",
+            file.isFile,
+        )
+        JSONObject(file.readText())
+    }
+
+    @Test
+    fun everySharedVectorAgrees() {
+        val cases = vectors.getJSONArray("cases")
+        assertTrue("the vector file is the contract; keep it rich", cases.length() > 20)
+        for (i in 0 until cases.length()) {
+            val case = cases.getJSONObject(i)
+            val name = case.getString("name")
+            val result = DeepLinks.parse(case.getString("url"))
+            if (case.has("error")) {
+                val refusal = result as? DeepLinkResult.Refused
+                    ?: throw AssertionError("$name: expected ${case.getString("error")}, parsed ok")
+                assertEquals(name, case.getString("error"), refusal.error.code)
+                assertTrue("$name: a refusal must be explainable", refusal.message().isNotEmpty())
+                continue
+            }
+            val link = (result as? DeepLinkResult.Parsed)?.link
+                ?: throw AssertionError("$name: refused, expected a parse — $result")
+            val want = case.getJSONObject("expect")
+            assertEquals(name, want.getString("route"), link.route.word)
+            assertEquals(name, want.getString("host_ref"), link.hostRef)
+            assertEquals("$name fp", want.optStringOrNull("fp"), link.fp)
+            assertEquals("$name launch", want.optStringOrNull("launch"), link.launch)
+            assertEquals("$name profile", want.optStringOrNull("profile"), link.profile)
+            assertEquals("$name name", want.optStringOrNull("name"), link.name)
+            assertEquals("$name host_addr", want.optStringOrNull("host_addr"), link.host?.first)
+            assertEquals(
+                "$name host_port",
+                if (want.has("host_port")) want.getInt("host_port") else null,
+                link.host?.second,
+            )
+            if (case.has("emit")) assertEquals("$name emit", case.getString("emit"), link.toUrl())
+        }
+    }
+
+    private fun JSONObject.optStringOrNull(key: String): String? =
+        if (has(key)) getString(key) else null
+}
+
+/**
+ * Resolution and emission — the half the vector file can't cover, because it depends on what is in
+ * THIS device's host store. The rules are the one-click contract in resolution form: an id beats a
+ * name beats an address, an ambiguous name refuses rather than guesses, and a link whose record is
+ * gone still lands on the confirmation sheet via `host=`+`fp=` instead of dying.
+ */
+class DeepLinkResolutionTest {
+    private val fp = "a".repeat(64)
+    private val desk = host("Desk", "192.168.1.50", "11111111-2222-4333-8444-555555555555", fp)
+    private val hosts = listOf(
+        desk,
+        host("Couch", "192.168.1.60", "66666666-7777-4888-8999-aaaaaaaaaaaa", ""),
+        host("Couch", "192.168.1.61", "bbbbbbbb-cccc-4ddd-8eee-ffffffffffff", ""),
+    )
+
+    private fun resolve(url: String) =
+        DeepLinks.resolveHost((DeepLinks.parse(url) as DeepLinkResult.Parsed).link, hosts)
+
+    @Test
+    fun idBeatsNameBeatsAddress() {
+        assertEquals(desk, (resolve("punktfunk://connect/${desk.id}") as HostResolution.Known).host)
+        assertEquals(desk, (resolve("punktfunk://connect/desk") as HostResolution.Known).host)
+        assertEquals(desk, (resolve("punktfunk://connect/192.168.1.50") as HostResolution.Known).host)
+        assertEquals(desk, (resolve("punktfunk://connect/192.168.1.50:9777") as HostResolution.Known).host)
+        // Two hosts answer to "Couch" — refuse with a notice, never pick one.
+        assertEquals(HostResolution.Ambiguous, resolve("punktfunk://connect/couch"))
+    }
+
+    @Test
+    fun aStaleIdRecoversThroughTheHostParameter() {
+        val stale = "00000000-0000-4000-8000-000000000000"
+        assertEquals(
+            desk,
+            (resolve("punktfunk://connect/$stale?host=192.168.1.50") as HostResolution.Known).host,
+        )
+        // …but a stale id is NOT a hostname: dialing "00000000-…" would be a confusing dead end
+        // rather than the recovery the grammar specifies.
+        assertEquals(HostResolution.Unresolvable, resolve("punktfunk://connect/$stale"))
+        // Neither is a display name that can't be an address.
+        assertEquals(HostResolution.Unresolvable, resolve("punktfunk://connect/Basement%20PC"))
+    }
+
+    @Test
+    fun anUnknownHostBecomesTheConfirmationSheetsInput() {
+        val r = resolve("punktfunk://connect/10.0.0.9:7000?name=Studio&fp=$fp")
+        assertEquals(HostResolution.Unknown("10.0.0.9", 7000, "Studio", fp), r)
+        // An mDNS/DNS name we've never saved is offered the same way — the sheet, never a connect.
+        assertEquals(
+            HostResolution.Unknown("nas.local", DeepLinks.DEFAULT_PORT, null, null),
+            resolve("punktfunk://connect/nas.local"),
+        )
+    }
+
+    @Test
+    fun aPinThatContradictsTheStoredOneIsTheLinkLying() {
+        fun link(url: String) = (DeepLinks.parse(url) as DeepLinkResult.Parsed).link
+        assertTrue(link("punktfunk://connect/desk?fp=${"b".repeat(64)}").pinConflict(desk))
+        assertFalse(link("punktfunk://connect/desk?fp=$fp").pinConflict(desk))
+        // No pin stored (an address-only record) → nothing to contradict; the trust flow runs.
+        assertFalse(link("punktfunk://connect/desk?fp=${"b".repeat(64)}").pinConflict(hosts[1]))
+    }
+
+    @Test
+    fun selfEmittedLinksRoundTripAndSurviveAWipedStore() {
+        val h = desk.copy(port = 7777)
+        val link = DeepLinks.forHost(h, launch = "steam:570", profile = "aaaaaaaaaaaa")
+        val url = link.toUrl()
+        assertEquals(
+            "punktfunk://connect/${h.id}?fp=$fp&host=192.168.1.50:7777" +
+                "&launch=steam:570&profile=aaaaaaaaaaaa",
+            url,
+        )
+        assertEquals(link, (DeepLinks.parse(url) as DeepLinkResult.Parsed).link)
+
+        // Names with spaces and non-ASCII survive the round trip.
+        val labelled = DeepLink(hostRef = "Wohnzimmer PC", name = "Büro · Mac")
+        assertTrue(labelled.toUrl().startsWith("punktfunk://connect/Wohnzimmer%20PC?"))
+        assertEquals(labelled, (DeepLinks.parse(labelled.toUrl()) as DeepLinkResult.Parsed).link)
+
+        // An emitted IPv6 host parameter comes back bracketed, so it parses again.
+        val v6 = DeepLink(hostRef = "x", host = "::1" to 1234)
+        assertEquals(v6.host, (DeepLinks.parse(v6.toUrl()) as DeepLinkResult.Parsed).link.host)
+    }
+
+    @Test
+    fun aHostWithNoPinEmitsNoFingerprint() {
+        assertNull(DeepLinks.forHost(hosts[1]).fp)
+    }
+
+    private fun host(name: String, addr: String, id: String, fp: String) =
+        KnownHost(addr, DeepLinks.DEFAULT_PORT, name, fp, paired = true, id = id)
+}
@@ -1,6 +1,10 @@
 package io.unom.punktfunk.kit.security

+import org.json.JSONObject
 import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotEquals
+import org.junit.Assert.assertTrue
 import org.junit.Test

 /** Unit tests for the pure MAC-parsing helper backing the host edit form. */
@@ -30,4 +34,119 @@ class KnownHostStoreTest {
        assertEquals(emptyList<String>(), KnownHostStore.parseMacs("+a:-b:+c:-d:+e:-f")) // signed octets
        assertEquals(listOf("aa:bb:cc:dd:ee:ff"), KnownHostStore.parseMacs("junk, aa:bb:cc:dd:ee:ff"))
    }
+
+    @Test
+    fun encodedRecordCarriesTheOsChainAndLegacyRecordsReadBackEmpty() {
+        val h = KnownHost("10.0.0.5", 9777, "HTPC", "a".repeat(64), true, os = "linux/fedora/bazzite")
+        val j = JSONObject(KnownHostStore.encode(h))
+        assertEquals("linux/fedora/bazzite", j.getString("os"))
+        // A record written before the field existed has no "os" key; the parse contract
+        // (optString) reads it back as empty — same additive rule as every late field.
+        val legacy = JSONObject().put("addr", "10.0.0.5").put("port", 9777).toString()
+        assertEquals("", JSONObject(legacy).optString("os", ""))
+    }
+}
+
+/**
+ * The store migration, run against a REAL pre-migration prefs blob — records exactly as the
+ * `"address:port"`-keyed store wrote them, IPv6 and all. It runs once against live user data on
+ * every upgraded install, so the property under test is blunt: **every host survives**, with its
+ * trust intact and the retiring global clipboard setting carried onto it.
+ */
+class KnownHostMigrationTest {
+    /** Verbatim shape of the old writer: no `id`, no `clip`, MACs as a comma-joined string. */
+    private fun legacy(addr: String, port: Int, name: String, fp: String, paired: Boolean, mac: String) =
+        JSONObject()
+            .put("addr", addr)
+            .put("port", port)
+            .put("name", name)
+            .put("fp", fp)
+            .put("paired", paired)
+            .put("mac", mac)
+            .toString()
+
+    private val preMigration: Map<String, Any?> = mapOf(
+        "192.168.1.42:9777" to legacy("192.168.1.42", 9777, "Living Room PC", "a".repeat(64), true, "aa:bb:cc:dd:ee:ff"),
+        "192.168.1.50:9777" to legacy("192.168.1.50", 9777, "Office", "b".repeat(64), false, ""),
+        // An IPv6 host: the old key contains colons of its own, which is exactly why the record
+        // always carried its address in the VALUE rather than parsing it back out of the key.
+        "fd00::1:9777" to legacy("fd00::1", 9777, "Basement", "c".repeat(64), true, ""),
+    )
+
+    private fun migrated(globalClipboard: Boolean): List<JSONObject> =
+        KnownHostStore.migrate(preMigration, globalClipboard).writes.values.map { JSONObject(it) }
+
+    @Test
+    fun everyHostSurvivesWithItsTrustIntact() {
+        val result = KnownHostStore.migrate(preMigration, globalClipboardSync = true)
+        assertEquals(3, result.writes.size)
+        // Every old key is dropped — none of them is a valid new key (they aren't ids).
+        assertEquals(preMigration.keys, result.removals)
+
+        val byName = result.writes.values.map { JSONObject(it) }.associateBy { it.getString("name") }
+        assertEquals(setOf("Living Room PC", "Office", "Basement"), byName.keys)
+
+        val living = byName.getValue("Living Room PC")
+        assertEquals("192.168.1.42", living.getString("addr"))
+        assertEquals(9777, living.getInt("port"))
+        assertEquals("a".repeat(64), living.getString("fp"))
+        assertTrue(living.getBoolean("paired"))
+        assertEquals("aa:bb:cc:dd:ee:ff", living.getString("mac"))
+
+        // The IPv6 address round-trips out of the value, untouched by the key rewrite.
+        assertEquals("fd00::1", byName.getValue("Basement").getString("addr"))
+        assertFalse(byName.getValue("Office").getBoolean("paired"))
+    }
+
+    @Test
+    fun eachRecordIsRekeyedOntoItsOwnMintedId() {
+        val result = KnownHostStore.migrate(preMigration, globalClipboardSync = true)
+        // The key IS the record's id, and the ids are distinct — two hosts must never collide onto
+        // one record (which would silently lose one of them).
+        result.writes.forEach { (key, json) -> assertEquals(key, JSONObject(json).getString("id")) }
+        assertEquals(3, result.writes.keys.size)
+        // The minted shape is the cross-platform one: a lowercase UUID.
+        result.writes.keys.forEach { id ->
+            assertEquals(36, id.length)
+            assertEquals(id.lowercase(), id)
+            assertEquals(listOf(8, 4, 4, 4, 12), id.split("-").map { it.length })
+        }
+        assertNotEquals(newRecordId(), newRecordId())
+    }
+
+    /**
+     * The behaviour-preserving half: clipboard sync was one global that every host followed, so
+     * after the migration every host must still be following the value that global held — on or
+     * off. This is the assertion that would catch a migration silently defaulting everyone to on.
+     */
+    @Test
+    fun theRetiringGlobalClipboardSettingLandsOnEveryHost() {
+        migrated(globalClipboard = true).forEach { assertTrue(it.getBoolean("clip")) }
+        migrated(globalClipboard = false).forEach { assertFalse(it.getBoolean("clip")) }
+    }
+
+    @Test
+    fun migrationIsIdempotentOverItsOwnOutput() {
+        val once = KnownHostStore.migrate(preMigration, globalClipboardSync = false)
+        val twice = KnownHostStore.migrate(once.writes, globalClipboardSync = true)
+        // Already-keyed records keep their ids and their per-host value: a second pass (a downgrade
+        // then re-upgrade, a schema flag lost) must not re-mint ids that bindings point at, and must
+        // not resurrect the global over a per-host answer the user has since changed.
+        assertEquals(once.writes, twice.writes)
+        assertTrue(twice.removals.isEmpty())
+    }
+
+    @Test
+    fun entriesThatArentHostRecordsAreLeftAlone() {
+        val junk = mapOf(
+            "some_unrelated_flag" to true,
+            "half_a_record" to JSONObject().put("name", "no address").toString(),
+            "not_even_json" to "{{{",
+        )
+        val result = KnownHostStore.migrate(junk, globalClipboardSync = true)
+        // They were already invisible to `all()`; deleting what we don't understand isn't this
+        // pass's job, and writing them as hosts would invent records out of nothing.
+        assertTrue(result.writes.isEmpty())
+        assertTrue(result.removals.isEmpty())
+    }
 }
@@ -17,11 +17,16 @@ use super::display::{
    apply_hdr_dataspace, install_render_callback, release_render_callback, DisplayTracker,
 };
 use super::latency::{note_decoded_pts, now_realtime_ns, take_flags};
+use super::presenter::{presenter_disabled_by_sysprop, PresentMeter, PresentPriority, Presenter};
 use super::setup::{
    android_hdr_static_info, boost_hot_threads, boost_thread_priority, codec_mime,
    configure_low_latency, create_codec, try_set_frame_rate,
 };
-use super::{DecodeOptions, FRAME_PARK_CAP, IN_FLIGHT_CAP, PENDING_SPLIT_CAP};
+use super::vsync::{now_monotonic_ns, VsyncClock};
+use super::{
+    DecodeOptions, FRAME_PARK_CAP, IN_FLIGHT_CAP, NO_OUTPUT_PATIENCE, NO_VIDEO_PATIENCE,
+    NO_VIDEO_RETRY, PENDING_SPLIT_CAP,
+};

 /// One decoded output buffer ready to release: its codec buffer index + the pts the codec echoed
 /// (from the output callback's `BufferInfo`), used to pair the `decode` HUD stat, and the
@@ -52,6 +57,8 @@ enum DecodeEvent {
    },
    /// The output format changed — re-check the stream's colour signalling (HDR DataSpace).
    FormatChanged,
+    /// A panel vsync (from the [`VsyncClock`] thread) — the presenter's retry/pacing tick.
+    Vsync,
    /// The codec reported an error; `fatal` when neither recoverable nor transient.
    Error { fatal: bool },
 }
@@ -75,6 +82,9 @@ pub(super) fn run_async(
        ll_feature,
        low_latency_mode,
        is_tv,
+        present_priority,
+        smooth_buffer,
+        panel_hz,
    } = opts;
    boost_thread_priority();
    let mode = client.mode();
@@ -193,9 +203,33 @@ pub(super) fn run_async(
    // parked in the tracker at release; the OnFrameRendered callback pairs it with
    // SurfaceFlinger's render timestamp. `render_cb` is the callback's leaked Arc refcount,
    // reclaimed after the codec is dropped below.
-    let tracker = DisplayTracker::new(stats.clone(), clock_offset.clone());
+    let meter = Arc::new(PresentMeter::new());
+    let tracker = DisplayTracker::new(stats.clone(), clock_offset.clone(), meter.clone());
    let render_cb = install_render_callback(&codec, &tracker);

+    // The timeline presenter (see `presenter.rs`): newest-wins / smoothing store, one-in-flight
+    // glass budget, timeline-timed release. `debug.punktfunk.presenter = arrival` selects the
+    // legacy release-immediately path for a rebuild-free on-device A/B.
+    let mut presenter = if presenter_disabled_by_sysprop() {
+        log::info!("decode: presenter = arrival (sysprop) — legacy immediate release");
+        None
+    } else {
+        let priority = PresentPriority::resolve(present_priority, smooth_buffer);
+        log::info!(
+            "decode: presenter = timeline ({})",
+            match priority {
+                PresentPriority::Latency => "lowest latency".to_string(),
+                PresentPriority::Smooth { buffer } => format!("smoothness, buffer {buffer}"),
+            }
+        );
+        Some(Presenter::new(priority))
+    };
+    stats.set_presenter_active(presenter.is_some());
+    // The vsync clock, started LAZILY on the first decoded frame (see `vsync.rs`); its ticks ride
+    // the same event channel. The Sender parks here until that moment.
+    let mut vsync: Option<VsyncClock> = None;
+    let mut vsync_tx = presenter.is_some().then(|| ev_tx.clone());
+
    // Feeder thread: block on the network so this loop doesn't (an AU's arrival becomes an event that
    // wakes us immediately, with no input-side poll latency). It also records the `received` HUD stat.
    let feeder = {
@@ -253,6 +287,16 @@ pub(super) fn run_async(
    // presented. The blocking event wait is excluded (idle, not work) — same accounting as the sync loop.
    let mut work_accum_ns: i64 = 0;
    let mut fatal = false;
+    // No-output backstop (see [`NO_OUTPUT_PATIENCE`]): the last time the decoder handed us a frame,
+    // and how many AUs it had been fed by then. Silence only counts while AUs are actually going in,
+    // so an idle stream never asks for anything. Seeded at start so a decoder that never produces a
+    // first frame — the missed opening IDR — is caught by the same window.
+    let mut last_output = Instant::now();
+    let mut fed_at_output: u64 = 0;
+    // Nothing-ever-arrived backstop (see [`NO_VIDEO_PATIENCE`]) — the mirror of the one above, for a
+    // session whose video plane delivers no AU at all.
+    let started = Instant::now();
+    let mut last_no_video_req: Option<Instant> = None;

    while !shutdown.load(Ordering::Relaxed) && !fatal {
        // Block for the next event (idle wait — excluded from the work tally). The short timeout
@@ -264,6 +308,7 @@ pub(super) fn run_async(
        };
        let work_t0 = Instant::now();
        let mut fmt_dirty = false;
+        let mut vsync_tick = false;
        let mut aus_dropped: u64 = 0;
        if let Some(ev) = ev0 {
            aus_dropped += u64::from(dispatch_event(
@@ -272,6 +317,7 @@ pub(super) fn run_async(
                &mut free_inputs,
                &mut ready,
                &mut fmt_dirty,
+                &mut vsync_tick,
                &mut fatal,
                &mut gate,
                &mut recovery_flags,
@@ -286,11 +332,17 @@ pub(super) fn run_async(
                &mut free_inputs,
                &mut ready,
                &mut fmt_dirty,
+                &mut vsync_tick,
                &mut fatal,
                &mut gate,
                &mut recovery_flags,
            ));
        }
+        if vsync_tick {
+            if let Some(p) = presenter.as_mut() {
+                p.on_vsync();
+            }
+        }
        stats.note_skipped(aus_dropped); // parked-AU overflow drops are client-side skips too
        if fmt_dirty {
            apply_hdr_dataspace(&codec, &window, &mut applied_ds);
@@ -304,6 +356,7 @@ pub(super) fn run_async(
            &mut oversized_dropped,
        );
        let had_output = !ready.is_empty();
+        let rendered_before = rendered;
        present_ready(
            &codec,
            &client,
@@ -313,14 +366,64 @@ pub(super) fn run_async(
            &in_flight,
            clock_offset.load(Ordering::Relaxed),
            &tracker,
+            &mut presenter,
            &mut rendered,
            &mut discarded,
            &mut gate,
            &mut recovery_flags,
        );
+        // The presenter's decision point runs EVERY pass — frame arrivals, vsync ticks and the
+        // 5 ms housekeeping wake all land here, which is what reopens the glass budget on time
+        // even when the choreographer clock is absent.
+        if let Some(p) = presenter.as_mut() {
+            let clock = vsync.as_ref().map(|v| v.shared().as_ref());
+            if p.pump(&codec, clock, &tracker, &stats, now_monotonic_ns()) {
+                rendered += 1;
+            }
+            // The 1 Hz window flush doubles as the phase-lock report tick: the measured latch
+            // p50 is the arrival-lead error signal the host's capture controller drives toward
+            // its target (design/phase-locked-capture.md §6). Timestamps convert
+            // monotonic→realtime→host here — the skew offset lives only client-side.
+            if let (Some(latch_p50_ns), Some(c)) = (p.flush_log(&meter, clock), clock) {
+                let period = c.panel_period_ns().max(c.period_ns());
+                if period > 0 {
+                    if let Some(t) = c.next_target(now_monotonic_ns(), 0) {
+                        let mono_now = now_monotonic_ns();
+                        let real_now = now_realtime_ns();
+                        let latch_real_ns = real_now + (t.expected_present_ns - mono_now) as i128;
+                        let latch_host_ns = (latch_real_ns
+                            + clock_offset.load(Ordering::Relaxed) as i128)
+                            .max(0) as u64;
+                        client.report_phase(
+                            latch_host_ns,
+                            period.clamp(0, u32::MAX as i64) as u32,
+                            1_000_000, // skew residual + latch jitter — conservative 1 ms
+                            latch_p50_ns.min(u32::MAX as u64) as u32,
+                        );
+                    }
+                }
+            }
+        }
+        let presented_now = rendered > rendered_before;
+        // Start the vsync clock LAZILY on the first decoded output (eager, it ticks the panel
+        // rate into a session that has no frame yet — the Apple deadline presenter's bootstrap
+        // lesson). A `None` from start (no choreographer surface) simply leaves ASAP targets.
+        if had_output && vsync.is_none() {
+            if let Some(tx) = vsync_tx.take() {
+                vsync = VsyncClock::start(
+                    panel_hz,
+                    Box::new(move || {
+                        let _ = tx.send(DecodeEvent::Vsync);
+                    }),
+                );
+                if vsync.is_none() {
+                    log::info!("decode: no choreographer clock — presenter uses ASAP targets");
+                }
+            }
+        }

        work_accum_ns += work_t0.elapsed().as_nanos() as i64;
-        if had_output {
+        if presented_now {
            if !hint_tried {
                hint_tried = true;
                let tids = client.hot_thread_ids();
@@ -344,6 +447,12 @@ pub(super) fn run_async(
                h.report_actual(work_accum_ns);
            }
            work_accum_ns = 0;
+            // The one line that separates "the stream never reached glass" from "it reached glass
+            // and looked wrong" — the periodic tally below only starts at 300 frames, which is no
+            // help at all on a session that renders none.
+            if rendered == 1 {
+                log::info!("decode: first frame presented (fed={fed} discarded={discarded})");
+            }
            if rendered > 0 && rendered % 300 == 0 {
                log::info!("decode: fed={fed} rendered={rendered} discarded={discarded}");
            }
@@ -356,7 +465,44 @@ pub(super) fn run_async(
        if aus_dropped > 0 {
            gate.arm(now);
        }
-        if (gate.poll(client.frames_dropped(), now) || aus_dropped > 0)
+        // Fed but silent: the decoder is holding nothing it can decode — the opening IDR never
+        // reached it, or its reference chain is gone. Ask for a fresh one and arm the freeze, so the
+        // concealment it may start emitting on the way back is withheld until a clean re-anchor
+        // (`gate.poll` keeps re-asking on the deadline until one arrives).
+        let starved = !had_output
+            && fed > fed_at_output
+            && now.duration_since(last_output) >= NO_OUTPUT_PATIENCE;
+        if had_output {
+            last_output = now;
+            fed_at_output = fed;
+        } else if starved {
+            log::warn!(
+                "decode: no output for {} ms with {} AU(s) fed — requesting a re-anchor keyframe",
+                now.duration_since(last_output).as_millis(),
+                fed - fed_at_output
+            );
+            gate.arm(now);
+            last_output = now; // one request per patience window, not per iteration
+            fed_at_output = fed;
+        }
+        // Nothing has EVER arrived: not an idle stream but a session that never got a picture — the
+        // `starved` test above cannot see it, because it needs `fed` to have moved. Evaluated after
+        // `feed_ready`, so an AU that arrived this pass has either been fed or is parked in
+        // `pending_aus`; both mean video IS flowing.
+        let no_video_yet = fed == 0 && pending_aus.is_empty();
+        if no_video_yet
+            && now.duration_since(started) >= NO_VIDEO_PATIENCE
+            && last_no_video_req.is_none_or(|t| now.duration_since(t) >= NO_VIDEO_RETRY)
+        {
+            log::warn!(
+                "decode: no video received {} ms into the session — requesting a keyframe",
+                now.duration_since(started).as_millis()
+            );
+            last_no_video_req = Some(now);
+            let _ = client.request_keyframe();
+            last_kf_req = Some(now); // share the throttle with the loss-recovery path below
+        }
+        if (gate.poll(client.frames_dropped(), now) || aus_dropped > 0 || starved)
            && last_kf_req.is_none_or(|t| now.duration_since(t) >= Duration::from_millis(100))
        {
            last_kf_req = Some(now);
@@ -364,6 +510,10 @@ pub(super) fn run_async(
        }
    }

+    if let Some(p) = presenter.as_mut() {
+        p.release_all(&codec); // hand every held output buffer back before the codec stops
+    }
+    drop(vsync); // stop + join the choreographer thread; its channel sends are harmless after
    let _ = codec.stop();
    shutdown.store(true, Ordering::SeqCst); // ensure the feeder wakes and exits, then join it
    if let Some(j) = feeder {
@@ -464,6 +614,7 @@ fn dispatch_event(
    free_inputs: &mut VecDeque<usize>,
    ready: &mut Vec<OutputReady>,
    fmt_dirty: &mut bool,
+    vsync_tick: &mut bool,
    fatal: &mut bool,
    gate: &mut ReanchorGate,
    recovery_flags: &mut VecDeque<(u64, u32)>,
@@ -496,6 +647,7 @@ fn dispatch_event(
            decoded_ns,
        }),
        DecodeEvent::FormatChanged => *fmt_dirty = true,
+        DecodeEvent::Vsync => *vsync_tick = true,
        DecodeEvent::Error { fatal: f } => {
            if f {
                *fatal = true;
@@ -557,13 +709,14 @@ fn feed_ready(
    }
 }

-/// Present only the NEWEST ready output (render = true) and release the rest without rendering — a
-/// burst of stale frames on glass is worse than skipping to the freshest (the sync loop's newest-ready
-/// policy, callback-driven). Every dequeued buffer, rendered or not, is the HUD's `decoded`
-/// measurement point (it finished decoding either way); samples are recorded in pts order so the
-/// receipt-map eviction stays monotonic. The presented frame's `(pts, decoded stamp)` is parked in
-/// `tracker` for the OnFrameRendered callback — the `display` stage's other endpoint. `ready` is
-/// drained.
+/// Route the ready outputs toward glass. With the timeline presenter (default): fold each output
+/// through the re-anchor gate in pts order, hand the approved ones to the presenter's store
+/// (newest-wins / smoothing FIFO — the actual release happens in `Presenter::pump`, budgeted and
+/// timeline-timed), and release withheld concealment unrendered. Legacy (`arrival` sysprop):
+/// present only the NEWEST ready output immediately and release the rest unrendered — the
+/// original policy. Every dequeued buffer, rendered or not, is the HUD's `decoded` measurement
+/// point (it finished decoding either way); samples are recorded in pts order so the receipt-map
+/// eviction stays monotonic. `ready` is drained.
 #[allow(clippy::too_many_arguments)] // one call site; mirrors the sync loop's drain
 fn present_ready(
    codec: &MediaCodec,
@@ -574,6 +727,7 @@ fn present_ready(
    in_flight: &Mutex<VecDeque<(u64, i128)>>,
    clock_offset: i64,
    tracker: &DisplayTracker,
+    presenter: &mut Option<Presenter>,
    rendered: &mut u64,
    discarded: &mut u64,
    gate: &mut ReanchorGate,
@@ -601,31 +755,46 @@ fn present_ready(
        }
    }
    // Fold EVERY output through the gate in pts (== decode) order — even the ones newest-wins discards —
-    // so the two-mark re-anchor count stays correct; the newest's verdict decides whether it reaches
-    // glass (`false` = withheld concealment; the SurfaceView keeps the last rendered frame frozen on).
+    // so the two-mark re-anchor count stays correct; a `false` verdict is withheld concealment (the
+    // SurfaceView keeps the last rendered frame frozen on).
    let now = Instant::now();
-    let last = ready.len() - 1;
    let mut skipped: u64 = 0;
-    for (i, o) in ready.drain(..).enumerate() {
-        let flags = take_flags(recovery_flags, o.pts_us);
-        let present = gate.on_decoded(flags, false, now) == GateVerdict::Present;
-        let render = i == last && present;
-        match codec.release_output_buffer_by_index(o.index, render) {
-            Ok(()) if render => {
-                *rendered += 1;
-                if stats.enabled() {
-                    tracker.note_rendered(o.pts_us, o.decoded_ns);
+    if let Some(p) = presenter.as_mut() {
+        for o in ready.drain(..) {
+            let flags = take_flags(recovery_flags, o.pts_us);
+            if gate.on_decoded(flags, false, now) == GateVerdict::Present {
+                let dropped = p.submit(codec, o.index, o.pts_us, o.decoded_ns);
+                skipped += dropped;
+                *discarded += dropped;
+            } else {
+                if let Err(e) = codec.release_output_buffer_by_index(o.index, false) {
+                    log::warn!("decode: release_output_buffer_by_index({}): {e}", o.index);
                }
-            }
-            Ok(()) => {
                *discarded += 1;
                skipped += 1;
            }
-            Err(e) => {
-                log::warn!(
-                    "decode: release_output_buffer_by_index({}, {render}): {e}",
-                    o.index
-                )
+        }
+    } else {
+        let last = ready.len() - 1;
+        for (i, o) in ready.drain(..).enumerate() {
+            let flags = take_flags(recovery_flags, o.pts_us);
+            let present = gate.on_decoded(flags, false, now) == GateVerdict::Present;
+            let render = i == last && present;
+            match codec.release_output_buffer_by_index(o.index, render) {
+                Ok(()) if render => {
+                    *rendered += 1;
+                    tracker.note_rendered(o.pts_us, o.decoded_ns, now_realtime_ns());
+                }
+                Ok(()) => {
+                    *discarded += 1;
+                    skipped += 1;
+                }
+                Err(e) => {
+                    log::warn!(
+                        "decode: release_output_buffer_by_index({}, {render}): {e}",
+                        o.index
+                    )
+                }
            }
        }
    }
@@ -35,32 +35,37 @@ pub(super) struct DisplayTracker {
    /// loaded per callback so mid-stream re-syncs apply. Holding the handle (not the client)
    /// keeps the leaked render-callback refcount from pinning the whole session alive.
    clock_offset: Arc<AtomicI64>,
-    /// `(pts_us, decoded_real_ns)` of frames released with `render = true`, in release order,
-    /// awaiting their callback. Pushes are HUD-gated by the caller, so this stays empty (and the
-    /// callback early-outs) while the overlay is hidden.
-    rendered: Mutex<VecDeque<(u64, i128)>>,
+    /// Always-on latch/display accumulator for the presenter's 1 Hz `pf-present` line —
+    /// independent of the HUD gate, so a HUD-off A/B stays measurable from logcat.
+    meter: Arc<super::presenter::PresentMeter>,
+    /// `(pts_us, decoded_real_ns, released_real_ns)` of frames released with `render = true`, in
+    /// release order, awaiting their callback. Pushed on EVERY render (no HUD gate — the ring is
+    /// a 64-tuple bound and the latch metric wants to exist when nobody is watching).
+    rendered: Mutex<VecDeque<(u64, i128, i128)>>,
 }

 impl DisplayTracker {
    pub(super) fn new(
        stats: Arc<crate::stats::VideoStats>,
        clock_offset: Arc<AtomicI64>,
+        meter: Arc<super::presenter::PresentMeter>,
    ) -> Arc<DisplayTracker> {
        Arc::new(DisplayTracker {
            stats,
            clock_offset,
+            meter,
            rendered: Mutex::new(VecDeque::new()),
        })
    }

-    /// Park one just-rendered frame's `(pts, decoded stamp)` for the render callback to pair.
-    /// Caller gates on the HUD being visible.
-    pub(super) fn note_rendered(&self, pts_us: u64, decoded_ns: i128) {
+    /// Park one just-rendered frame's `(pts, decoded stamp, release stamp)` for the render
+    /// callback to pair — the release stamp is the latch metric's start (release→displayed).
+    pub(super) fn note_rendered(&self, pts_us: u64, decoded_ns: i128, released_ns: i128) {
        let mut g = self
            .rendered
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
-        g.push_back((pts_us, decoded_ns));
+        g.push_back((pts_us, decoded_ns, released_ns));
        if g.len() > RENDERED_CAP {
            g.pop_front(); // render callbacks stopped coming (allowed under load) — evict
        }
@@ -128,7 +133,9 @@ pub(super) fn install_render_callback(
 /// deleting the codec stops its internal threads, so no callback can still be running (or run
 /// later) against this pointer.
 pub(super) unsafe fn release_render_callback(ud: *const DisplayTracker) {
-    drop(Arc::from_raw(ud));
+    // SAFETY: `ud` is the pointer `install_render_callback` leaked from `Arc::into_raw`, and this
+    // function's contract is that it is reclaimed exactly once, after the codec is gone.
+    unsafe { drop(Arc::from_raw(ud)) };
 }

 /// The `AMediaCodecOnFrameRendered` trampoline: fires (possibly batched) on a codec-internal
@@ -146,37 +153,46 @@ unsafe extern "C" fn on_frame_rendered(
    media_time_us: i64,
    system_nano: i64,
 ) {
-    let t = &*(userdata as *const DisplayTracker);
-    if !t.stats.enabled() {
-        return; // HUD hidden — the ring is empty too (pushes are caller-gated)
-    }
+    // SAFETY: the platform hands back exactly the `userdata` registered with the callback — the
+    // `Arc::into_raw` pointer from `install_render_callback`, whose refcount is held for as long as
+    // the codec exists, and the codec is what delivers this call.
+    let t = unsafe { &*(userdata as *const DisplayTracker) };
    let displayed_ns = now_realtime_ns() - (now_monotonic_ns() - system_nano as i128);
    let pts_us = media_time_us.max(0) as u64;
    // Pair the frame back to its release record, evicting older entries (their callbacks were
-    // dropped by the platform, or the entry predates a HUD toggle) — same monotonic-eviction
-    // discipline as `note_decoded_pts`.
-    let mut decoded_ns = None;
+    // dropped by the platform) — same monotonic-eviction discipline as `note_decoded_pts`.
+    let mut paired = None;
    {
        let mut g = t
            .rendered
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
-        while let Some(&(p, d)) = g.front() {
+        while let Some(&(p, d, r)) = g.front() {
            if p > pts_us {
                break; // future frame — leave it for its own callback
            }
            g.pop_front();
            if p == pts_us {
-                decoded_ns = Some(d);
+                paired = Some((d, r));
                break;
            }
        }
    }
+    // Clamped to (0, 10 s) like the e2e sample: a vendor's first render callbacks can carry a
+    // garbage `system_nano` (observed on-glass: an epoch-sized latch max on the session's first
+    // window), and one such sample would poison every max/percentile it lands in.
+    let clamp = |v: i128| (v > 0 && v < 10_000_000_000).then_some((v / 1000) as u64);
+    let display_us = paired.and_then(|(d, _)| clamp(displayed_ns - d));
+    let latch_us = paired.and_then(|(_, r)| clamp(displayed_ns - r));
+    // Always-on half: the presenter's pf-present line reads these with the HUD off.
+    t.meter.note_latch(latch_us);
+    if !t.stats.enabled() {
+        return; // HUD hidden — skip the skew math + the stats lock
+    }
    let e2e_ns =
        displayed_ns + t.clock_offset.load(Ordering::Relaxed) 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 display_us = decoded_ns.map(|d| ((displayed_ns - d).max(0) / 1000) as u64);
-    t.stats.note_displayed(e2e_us, display_us);
+    t.stats.note_displayed(e2e_us, display_us, latch_us);
 }

 /// React to an output-format change by signalling the stream's HDR dataspace on the Surface (SDR
@@ -9,8 +9,10 @@
 mod async_loop;
 mod display;
 mod latency;
+mod presenter;
 mod setup;
 mod sync_loop;
+mod vsync;

 use async_loop::run_async;
 pub(crate) use setup::{codec_label, codec_mime};
@@ -41,6 +43,47 @@ const PENDING_SPLIT_CAP: usize = 256;
 /// gets evicted.
 const RENDERED_CAP: usize = 64;

+/// How long the decoder may be FED while producing nothing before we treat it as un-anchored and
+/// ask the host for a fresh IDR.
+///
+/// The shared gate's per-AU streak ([`punktfunk_core::reanchor::ReanchorGate::on_no_output`]) can't
+/// be used verbatim here: it counts one-in/one-out decodes (the desktop clients' `LOW_DELAY`
+/// libavcodec path and Apple's VideoToolbox), while MediaCodec is pipelined — inputs and outputs
+/// don't pair up, so "this AU produced no output" isn't a thing this loop can observe. A wall-clock
+/// silence window is the same signal in the shape Android can measure.
+///
+/// Why it matters: the host opens a stream with an IDR and, under infinite GOP, sends no other one
+/// unless asked. Miss that one — the decode thread only starts at `surfaceCreated`, so a slow TV box
+/// can be handed the stream mid-GOP — and every later AU references a picture the decoder never had.
+/// A hardware decoder doesn't error on that; it simply emits nothing. Without this backstop the
+/// session sat there forever: AUs arriving, a healthy HUD, and a black surface, because nothing in
+/// the Android loops ever asked for the keyframe that would re-anchor it.
+///
+/// 500 ms because it must never fire on a decoder that is merely slow to spin up: even the pokiest
+/// hardware decoder emits its first frame within a couple of frame periods, and a wedge that only
+/// costs half a second before it self-heals is not a bug the user reports.
+const NO_OUTPUT_PATIENCE: std::time::Duration = std::time::Duration::from_millis(500);
+
+/// How long a session may deliver NO access unit at all before we ask for a keyframe and say so.
+///
+/// [`NO_OUTPUT_PATIENCE`] covers "fed but silent", and it deliberately requires `fed` to have moved
+/// so an idle stream never asks for anything. That leaves its mirror image uncovered: a session that
+/// receives nothing whatsoever. A decoder cannot be starved of output when it was handed no input,
+/// so no signal in either loop fires, and the session sits connected — audio, input and the control
+/// plane all alive — behind a black surface with a HUD reading `0 fps · 0.0 Mb/s`, which is exactly
+/// how it comes back in reports (2026-07-30).
+///
+/// Asking costs one small control message, and it is the right ask in the case we can actually fix:
+/// the host is encoding, but under infinite GOP every picture it sends references an IDR this client
+/// never saw. When the host is sending nothing at all, the request changes nothing — but the log line
+/// beside it is what separates that from "we received AUs and lost them", which no previous black
+/// screen report could tell us.
+const NO_VIDEO_PATIENCE: std::time::Duration = std::time::Duration::from_millis(1500);
+
+/// Re-ask cadence once [`NO_VIDEO_PATIENCE`] has elapsed with still nothing received. Slow, because
+/// this state is either self-healing on the first ask or not ours to heal — and each pass logs.
+const NO_VIDEO_RETRY: std::time::Duration = std::time::Duration::from_millis(2000);
+
 /// Whether low-latency mode uses the event-driven async decode loop (default) or the synchronous
 /// poll loop. Flip to `false` to A/B the two on the HUD (`design/…`); the async loop presents a
 /// decoded frame the instant it's ready instead of waiting out a poll interval. Only consulted when
@@ -65,6 +108,17 @@ pub(crate) struct DecodeOptions {
    /// TV form factor (Kotlin's `UiModeManager`): actively drive the HDMI output into the stream's
    /// refresh mode, vs. the softer seamless hint on a phone/tablet.
    pub is_tv: bool,
+    /// The user's presentation intent (`present_priority` setting): 0 = lowest latency
+    /// (newest-wins), 1 = smoothness (a small FIFO). Resolved by
+    /// [`presenter::PresentPriority::resolve`]; anything else = latency.
+    pub present_priority: i32,
+    /// The smoothness buffer depth (`smooth_buffer` setting): 0 = automatic (2), else 1..=3.
+    /// Only meaningful with `present_priority` = smooth.
+    pub smooth_buffer: i32,
+    /// The display mode's own refresh rate (Kotlin's `display.refreshRate` at stream start;
+    /// 0 = unknown) — the latch grid the presenter subdivides onto when the app's choreographer
+    /// stream is down-rated below the panel (see `vsync.rs`).
+    pub panel_hz: i32,
 }

 /// The decode entry point on the `pf-decode` thread: dispatches to the async or synchronous loop.
@@ -0,0 +1,408 @@
+//! The timeline presenter — Android's port of the Apple client's stage-4 deadline discipline
+//! (`clients/apple/.../Stage2Pipeline.swift`, the `.deadline` pacing):
+//!
+//!  * a **newest-wins slot** (or a small smoothing FIFO, by user intent) between decode and
+//!    release, so a burst coalesces in the app — as an explicit, counted drop — instead of
+//!    queueing behind the display;
+//!  * a **glass budget of exactly one**: at most one undisplayed release in flight to
+//!    SurfaceFlinger, reopened on the clock-predicted latch (with a 100 ms stale force-open as
+//!    the liveness backstop, mirroring Apple's `PresentGate.staleAfter`). The BufferQueue can
+//!    hold at most the frame being scanned out plus one — a standing queue is unconstructible;
+//!  * a **timed release**: `AMediaCodec_releaseOutputBufferAtTime` targeting the platform's own
+//!    frame timeline (API 33+, via [`super::vsync`]), so the latch phase is deterministic instead
+//!    of inheriting network + decode jitter. On the 31/32 fallback the release is ASAP —
+//!    identical to the legacy path — and only the budget prediction uses the measured period.
+//!
+//! The legacy behaviour (release the newest ready buffer immediately, unbudgeted) remains
+//! selectable at runtime: `adb shell setprop debug.punktfunk.presenter arrival` — the on-device
+//! A/B needs no rebuild. The user-facing escape hatch stays the "Low-latency mode" master toggle
+//! (off = the synchronous pre-overhaul loop, no presenter at all).
+
+use ndk::media::media_codec::MediaCodec;
+use std::collections::VecDeque;
+use std::sync::Mutex;
+use std::time::Instant;
+
+use super::display::DisplayTracker;
+use super::latency::now_realtime_ns;
+use super::vsync::VsyncShared;
+
+/// Submit-margin ahead of a timeline's EXPECTED PRESENT — SurfaceFlinger's own latch lead: the
+/// released buffer must be in the BufferQueue by SF's wakeup for that vsync (a few ms before
+/// present). A present closer than this is treated as missed and the next one is targeted. This
+/// is deliberately NOT the timeline's `deadline` (which budgets for GPU rendering a video
+/// buffer doesn't do — see `VsyncShared::next_target`); a too-tight gamble here presents one
+/// vsync later, the exact cost the deadline gate paid on every frame.
+///
+/// 2.5 ms: SF's latch runs ~1-2 ms before present on modern devices (its `sfOffset`), and the
+/// release itself is a binder call well under a ms. 4 ms measured latch p50 8-10; each ms cut
+/// here is a ms off every frame's display stage. If a device misses at this margin the `paced`
+/// counter shows it (a miss presents one vsync later, coalescing the next frame) — that is the
+/// signal to widen, not stutter.
+const LATCH_MARGIN_NS: i64 = 2_500_000;
+
+/// The budget's liveness backstop: a release whose predicted latch never seems to arrive
+/// (clock glitch, mode switch) force-reopens the budget this long after the release, counted in
+/// `forced` — reads 0 on healthy systems (Apple's `PresentGate.staleAfter`, same value).
+const STALE_REOPEN_NS: i64 = 100_000_000;
+
+/// Fallback latch-prediction period while the vsync clock is unmeasured/absent: one 120 Hz frame.
+const FALLBACK_PERIOD_NS: i64 = 8_333_333;
+
+/// The user's presentation intent — the Apple client's `PresentPriority`, same resolution rules:
+/// anything but an explicit "smooth" is latency; a smooth buffer outside 1..=3 becomes 2.
+#[derive(Clone, Copy, PartialEq)]
+pub(crate) enum PresentPriority {
+    /// Newest-wins, release the instant the budget opens. The default.
+    Latency,
+    /// A small FIFO (1..=3 frames) drained one per vsync: jitter absorbed at one refresh of
+    /// added display latency per slot, which the metrics show rather than hide.
+    Smooth { buffer: usize },
+}
+
+impl PresentPriority {
+    /// From the JNI ints (`presentPriority` 0 = latency / 1 = smooth; `smoothBuffer` 0 = auto).
+    pub(crate) fn resolve(priority: i32, buffer: i32) -> PresentPriority {
+        if priority != 1 {
+            return PresentPriority::Latency;
+        }
+        let b = if (1..=3).contains(&buffer) {
+            buffer as usize
+        } else {
+            2
+        };
+        PresentPriority::Smooth { buffer: b }
+    }
+}
+
+/// One decoded output buffer held for presentation.
+struct HeldFrame {
+    index: usize,
+    pts_us: u64,
+    /// The output callback's `CLOCK_REALTIME` stamp — the pace metric's start (decoded→release).
+    decoded_ns: i128,
+}
+
+/// The one-in-flight glass budget.
+struct InFlight {
+    /// Monotonic instant the budget reopens: the release target's expected present (clock), or
+    /// `release + period` on the fallback path.
+    reopen_at_ns: i64,
+    released_at_ns: i64,
+}
+
+/// Latch samples + display confirms recorded by the `OnFrameRendered` callback thread, drained by
+/// the presenter's 1 Hz `pf-present` line. Always on (independent of the HUD) — this is what makes
+/// a HUD-off wireless A/B readable from logcat.
+pub(super) struct PresentMeter {
+    inner: Mutex<PresentMeterInner>,
+}
+
+struct PresentMeterInner {
+    latch_us: Vec<u64>,
+    displays: u64,
+}
+
+impl PresentMeter {
+    pub(super) fn new() -> PresentMeter {
+        PresentMeter {
+            inner: Mutex::new(PresentMeterInner {
+                latch_us: Vec::with_capacity(256),
+                displays: 0,
+            }),
+        }
+    }
+
+    /// One displayed frame's release→displayed latch, µs. Callback thread; poison-proof.
+    pub(super) fn note_latch(&self, latch_us: Option<u64>) {
+        let mut g = self
+            .inner
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        g.displays += 1;
+        if let Some(l) = latch_us {
+            if g.latch_us.len() < 4096 {
+                g.latch_us.push(l);
+            }
+        }
+    }
+
+    fn drain(&self) -> (Vec<u64>, u64) {
+        let mut g = self
+            .inner
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let displays = g.displays;
+        g.displays = 0;
+        (std::mem::take(&mut g.latch_us), displays)
+    }
+}
+
+/// p50/max of an unsorted µs sample vec, in ms. (0, 0) when empty.
+fn p50_max_ms(mut v: Vec<u64>) -> (f64, f64) {
+    if v.is_empty() {
+        return (0.0, 0.0);
+    }
+    v.sort_unstable();
+    let p50 = v[v.len() / 2] as f64 / 1000.0;
+    let max = *v.last().unwrap() as f64 / 1000.0;
+    (p50, max)
+}
+
+pub(super) struct Presenter {
+    /// 0 = newest-wins; 1..=3 = smoothing FIFO capacity.
+    fifo_capacity: usize,
+    frames: VecDeque<HeldFrame>,
+    /// FIFO preroll: `take` withholds until the buffer filled to capacity once, re-armed on a dry
+    /// run — the Apple `FrameStore` semantics (headroom never builds without it).
+    prerolled: bool,
+    inflight: Option<InFlight>,
+    /// A vsync arrived since the last release — the FIFO's one-per-refresh drain pace.
+    vsync_tick: bool,
+    // -- 1 Hz pf-present window, always on --
+    released: u64,
+    paced_drops: u64,
+    no_budget: u64,
+    forced: u64,
+    dry: u64,
+    pace_us: Vec<u64>,
+    last_flush: Instant,
+}
+
+impl Presenter {
+    pub(super) fn new(priority: PresentPriority) -> Presenter {
+        Presenter {
+            fifo_capacity: match priority {
+                PresentPriority::Latency => 0,
+                PresentPriority::Smooth { buffer } => buffer,
+            },
+            frames: VecDeque::new(),
+            prerolled: false,
+            inflight: None,
+            vsync_tick: false,
+            released: 0,
+            paced_drops: 0,
+            no_budget: 0,
+            forced: 0,
+            dry: 0,
+            pace_us: Vec::with_capacity(256),
+            last_flush: Instant::now(),
+        }
+    }
+
+    /// A vsync pulse from the clock thread's event — the retry tick for a parked frame and the
+    /// FIFO's drain pace.
+    pub(super) fn on_vsync(&mut self) {
+        self.vsync_tick = true;
+    }
+
+    /// Accept one decoded, gate-approved output buffer. Newest-wins evicts everything older
+    /// (released unrendered — the explicit, counted drop); the FIFO evicts its oldest past
+    /// capacity. Returns how many frames were dropped by the policy (the HUD's `skipped`).
+    pub(super) fn submit(
+        &mut self,
+        codec: &MediaCodec,
+        index: usize,
+        pts_us: u64,
+        decoded_ns: i128,
+    ) -> u64 {
+        let mut dropped = 0u64;
+        if self.fifo_capacity == 0 {
+            while let Some(stale) = self.frames.pop_front() {
+                release_unrendered(codec, stale.index);
+                dropped += 1;
+            }
+        }
+        self.frames.push_back(HeldFrame {
+            index,
+            pts_us,
+            decoded_ns,
+        });
+        if self.fifo_capacity > 0 && self.frames.len() > self.fifo_capacity {
+            if let Some(stale) = self.frames.pop_front() {
+                release_unrendered(codec, stale.index);
+                dropped += 1;
+            }
+        }
+        self.paced_drops += dropped;
+        dropped
+    }
+
+    /// The present decision point — run on every loop pass (frame arrivals, vsync ticks, and the
+    /// 5 ms housekeeping wake all land here). Releases AT MOST one frame (the budget). Returns
+    /// `true` when a frame was released to glass this call.
+    #[allow(clippy::too_many_arguments)] // one call site; the seams are the point
+    pub(super) fn pump(
+        &mut self,
+        codec: &MediaCodec,
+        clock: Option<&VsyncShared>,
+        tracker: &DisplayTracker,
+        stats: &crate::stats::VideoStats,
+        now_mono_ns: i64,
+    ) -> bool {
+        // Budget bookkeeping first: reopen on the predicted latch, force-open on the backstop.
+        if let Some(f) = &self.inflight {
+            if now_mono_ns >= f.reopen_at_ns {
+                self.inflight = None;
+            } else if now_mono_ns - f.released_at_ns > STALE_REOPEN_NS {
+                self.forced += 1;
+                self.inflight = None;
+            }
+        }
+        // Pick the frame this pump may release.
+        let frame = if self.fifo_capacity == 0 {
+            self.frames.pop_back() // submit() kept it a single slot; back == the newest
+        } else {
+            // FIFO: drain exactly one frame per vsync tick, after preroll; a drain tick that
+            // finds the buffer dry re-arms preroll (the Apple `FrameStore` underflow semantics —
+            // the previous frame persists on glass, a repeat by omission, while headroom
+            // rebuilds). Everything is gated on the tick so an idle stream neither counts
+            // underflows nor churns the preroll flag 200×/s.
+            if !self.vsync_tick {
+                return false;
+            }
+            if !self.prerolled {
+                if self.frames.len() < self.fifo_capacity {
+                    return false;
+                }
+                self.prerolled = true;
+            }
+            if self.frames.is_empty() {
+                self.prerolled = false;
+                self.dry += 1;
+                self.vsync_tick = false; // this tick's drain ran (and found nothing)
+                return false;
+            }
+            self.frames.pop_front()
+        };
+        let Some(frame) = frame else { return false };
+        if self.inflight.is_some() {
+            // Budget closed — park it back; a fresher submit replaces it (newest-wins), the next
+            // vsync tick / loop pass retries the pairing.
+            self.no_budget += 1;
+            match self.fifo_capacity {
+                0 => self.frames.push_back(frame),
+                _ => self.frames.push_front(frame),
+            }
+            return false;
+        }
+        // Release: timeline-timed when the clock has one, ASAP otherwise.
+        let target = clock.and_then(|c| c.next_target(now_mono_ns, LATCH_MARGIN_NS));
+        let released = match target {
+            Some(t) => codec
+                .release_output_buffer_at_time_by_index(frame.index, t.expected_present_ns)
+                .map_err(|e| log::warn!("presenter: release_at_time({}): {e}", frame.index)),
+            None => codec
+                .release_output_buffer_by_index(frame.index, true)
+                .map_err(|e| log::warn!("presenter: release({}): {e}", frame.index)),
+        };
+        self.vsync_tick = false;
+        if released.is_err() {
+            return false; // the buffer is gone either way; nothing to book-keep
+        }
+        let period = clock.map(|c| c.period_ns()).filter(|&p| p > 0);
+        // Reopen at SurfaceFlinger's LATCH for the targeted vsync (expected present minus the
+        // latch lead) — the instant SF consumes the queued buffer and the slot frees, so the
+        // next release can target the NEXT refresh. Not the platform `deadline` (with the
+        // aggressive present gate it can already be in the past — an instant reopen would let
+        // two releases pile onto the same vsync) and not the present time itself (a period too
+        // late — it would cap the sustainable rate at roughly half the panel).
+        let reopen_at_ns = target
+            .map(|t| t.expected_present_ns - LATCH_MARGIN_NS)
+            .unwrap_or(now_mono_ns + period.unwrap_or(FALLBACK_PERIOD_NS));
+        self.inflight = Some(InFlight {
+            reopen_at_ns,
+            released_at_ns: now_mono_ns,
+        });
+        self.released += 1;
+        let release_real_ns = now_realtime_ns();
+        let pace_us = ((release_real_ns - frame.decoded_ns).max(0) / 1000) as u64;
+        if self.pace_us.len() < 4096 {
+            self.pace_us.push(pace_us);
+        }
+        stats.note_release(pace_us);
+        tracker.note_rendered(frame.pts_us, frame.decoded_ns, release_real_ns);
+        true
+    }
+
+    /// Release every held buffer unrendered — the teardown path, BEFORE `codec.stop()`.
+    pub(super) fn release_all(&mut self, codec: &MediaCodec) {
+        while let Some(f) = self.frames.pop_front() {
+            release_unrendered(codec, f.index);
+        }
+        self.inflight = None;
+    }
+
+    /// The 1 Hz `pf-present` logcat mirror (target `pf.present`) — the Apple client's Console
+    /// `pf-present` line, so a HUD-off on-device A/B is readable wirelessly:
+    /// `released` (to glass) / `displays` (OnFrameRendered confirms) / `paced` (policy drops) /
+    /// `noBudget` (waits on the closed budget) / `forced` (stale force-opens — 0 when healthy) /
+    /// `qDry` (FIFO underflows) / `pace` (decoded→release) / `latch` (release→displayed) /
+    /// `vsync` (the measured panel period).
+    ///
+    /// Returns this window's measured latch p50 (ns) when a window actually flushed — the
+    /// phase-lock reporter's `arrival_lead` error signal (design/phase-locked-capture.md §6).
+    pub(super) fn flush_log(
+        &mut self,
+        meter: &PresentMeter,
+        clock: Option<&VsyncShared>,
+    ) -> Option<u64> {
+        if self.last_flush.elapsed() < std::time::Duration::from_secs(1) {
+            return None;
+        }
+        self.last_flush = Instant::now();
+        let (latch, displays) = meter.drain();
+        if self.released == 0 && displays == 0 {
+            return None; // idle stream — nothing worth a line
+        }
+        let (pace_p50, pace_max) = p50_max_ms(std::mem::take(&mut self.pace_us));
+        let (latch_p50, latch_max) = p50_max_ms(latch);
+        let period_ms = clock.map(|c| c.period_ns() as f64 / 1e6).unwrap_or(0.0);
+        let panel_ms = clock
+            .map(|c| c.panel_period_ns() as f64 / 1e6)
+            .unwrap_or(0.0);
+        log::info!(
+            target: "pf.present",
+            "released={} displays={} paced={} noBudget={} forced={} qDry={} \
+             paceMs p50={:.2} max={:.2} latchMs p50={:.2} max={:.2} vsyncMs={:.2} panelMs={:.2}",
+            self.released,
+            displays,
+            self.paced_drops,
+            self.no_budget,
+            self.forced,
+            self.dry,
+            pace_p50,
+            pace_max,
+            latch_p50,
+            latch_max,
+            period_ms,
+            panel_ms,
+        );
+        self.released = 0;
+        self.paced_drops = 0;
+        self.no_budget = 0;
+        self.forced = 0;
+        self.dry = 0;
+        (latch_p50 > 0.0).then(|| (latch_p50 * 1e6) as u64)
+    }
+}
+
+fn release_unrendered(codec: &MediaCodec, index: usize) {
+    if let Err(e) = codec.release_output_buffer_by_index(index, false) {
+        log::warn!("presenter: release_output_buffer({index}, false): {e}");
+    }
+}
+
+/// `debug.punktfunk.presenter` sysprop: `arrival` = the legacy release-immediately path,
+/// anything else / unset = the timeline presenter. The rebuild-free on-device A/B lever.
+pub(super) fn presenter_disabled_by_sysprop() -> bool {
+    let mut buf = [0u8; 92]; // PROP_VALUE_MAX
+                             // SAFETY: __system_property_get with a valid name + PROP_VALUE_MAX buffer is always safe.
+    let n = unsafe {
+        libc::__system_property_get(
+            c"debug.punktfunk.presenter".as_ptr(),
+            buf.as_mut_ptr().cast(),
+        )
+    };
+    n > 0 && &buf[..n as usize] == b"arrival"
+}
@@ -180,8 +180,14 @@ pub(super) fn boost_thread_priority() {
 ///     mode (e.g. 60↔120) instead of leaving the panel at its default and judder-matching. The
 ///     forced switch may blank the panel briefly — acceptable once at stream start, not wanted on a
 ///     phone. Falls through to the 2-arg hint on API 30.
-///   - Otherwise: `ANativeWindow_setFrameRate` (**API 30**) with `compatibility = DEFAULT` — the
-///     softer, seamless-preferred hint for phones/tablets and the universal fallback.
+///   - Otherwise: `ANativeWindow_setFrameRate` (**API 30**) — the seamless-preferred hint for
+///     phones/tablets and the universal fallback.
+///
+/// Both paths pass `compatibility = FIXED_SOURCE` (1): the stream is fixed-rate video content the
+/// client cannot re-pace, which is exactly what that value declares — `DEFAULT` (0) told the
+/// platform the app could adapt to whatever rate it picked, an invitation some OEM refresh
+/// governors accepted by simply not switching. (The window-level `preferredDisplayModeId` pin in
+/// `MainActivity.setStreamDisplayMode` is the phone-side belt to this braces.)
 ///
 /// Returns `true` when the platform accepted a hint; `false` on API < 30 (symbols absent) or a
 /// decline.
@@ -200,8 +206,10 @@ pub(super) fn try_set_frame_rate(window: &NativeWindow, frame_rate: f32, is_tv:
        if lib.is_null() {
            return false;
        }
-        // TV: prefer the API-31 change-strategy form to force the mode switch (strategy 1 = ALWAYS,
-        // compatibility 0 = DEFAULT). Absent on API 30 ⇒ fall through to the 2-arg hint below.
+        // ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_FIXED_SOURCE — fixed-rate video content.
+        const FIXED_SOURCE: i8 = 1;
+        // TV: prefer the API-31 change-strategy form to force the mode switch (strategy 1 =
+        // ALWAYS). Absent on API 30 ⇒ fall through to the 2-arg hint below.
        if is_tv {
            let sym = libc::dlsym(
                lib,
@@ -209,7 +217,7 @@ pub(super) fn try_set_frame_rate(window: &NativeWindow, frame_rate: f32, is_tv:
            );
            if !sym.is_null() {
                let set = std::mem::transmute::<*mut c_void, SetFrameRateStrategyFn>(sym);
-                return set(window.ptr().as_ptr().cast(), frame_rate, 0, 1) == 0;
+                return set(window.ptr().as_ptr().cast(), frame_rate, FIXED_SOURCE, 1) == 0;
            }
        }
        let sym = libc::dlsym(lib, c"ANativeWindow_setFrameRate".as_ptr());
@@ -217,7 +225,7 @@ pub(super) fn try_set_frame_rate(window: &NativeWindow, frame_rate: f32, is_tv:
            return false; // device API < 30 — no per-surface frame-rate hint
        }
        let set_frame_rate = std::mem::transmute::<*mut c_void, SetFrameRateFn>(sym);
-        set_frame_rate(window.ptr().as_ptr().cast(), frame_rate, 0) == 0
+        set_frame_rate(window.ptr().as_ptr().cast(), frame_rate, FIXED_SOURCE) == 0
    }
 }

@@ -24,7 +24,10 @@ use super::setup::{
    android_hdr_static_info, boost_hot_threads, boost_thread_priority, codec_mime,
    configure_low_latency, create_codec, try_set_frame_rate,
 };
-use super::{DecodeOptions, IN_FLIGHT_CAP, PENDING_SPLIT_CAP};
+use super::{
+    DecodeOptions, IN_FLIGHT_CAP, NO_OUTPUT_PATIENCE, NO_VIDEO_PATIENCE, NO_VIDEO_RETRY,
+    PENDING_SPLIT_CAP,
+};

 /// The synchronous poll loop — the original decode path: the only one when low-latency mode is off,
 /// and the [`USE_ASYNC_DECODE`] A/B fallback when it's on. Feeds and drains on this one thread; the
@@ -41,6 +44,10 @@ pub(super) fn run_sync(
        ll_feature,
        low_latency_mode,
        is_tv,
+        // The timeline presenter lives in the async loop only; this loop IS the escape hatch.
+        present_priority: _,
+        smooth_buffer: _,
+        panel_hz: _,
    } = opts;
    boost_thread_priority();
    let mode = client.mode();
@@ -144,6 +151,16 @@ pub(super) fn run_sync(
    let mut fed: u64 = 0;
    let mut rendered: u64 = 0;
    let mut discarded: u64 = 0;
+    // No-output backstop (see [`NO_OUTPUT_PATIENCE`]): when the decoder last handed us a frame, and
+    // how many AUs it had been fed by then. Silence only counts while AUs are going in, so an idle
+    // stream asks for nothing; seeded at start so a decoder that never produces a FIRST frame — the
+    // missed opening IDR — is caught by the same window.
+    let mut last_output = Instant::now();
+    let mut fed_at_output: u64 = 0;
+    // Nothing-ever-arrived backstop (see [`NO_VIDEO_PATIENCE`]) — the mirror of the one above, for a
+    // session whose video plane delivers no AU at all.
+    let started = Instant::now();
+    let mut last_no_video_req: Option<Instant> = None;
    // AUs larger than the codec input buffer, dropped whole (see `feed`/`feed_ready`).
    let mut oversized_dropped: u64 = 0;
    // The AU waiting for a free codec input buffer. `feed` is non-blocking; on transient input
@@ -168,7 +185,11 @@ pub(super) fn run_sync(
    // render = true are parked in the tracker; the OnFrameRendered callback pairs them with
    // SurfaceFlinger's render timestamp. `render_cb` is the callback's leaked Arc refcount,
    // reclaimed after the codec is dropped below.
-    let tracker = DisplayTracker::new(stats.clone(), clock_offset.clone());
+    let tracker = DisplayTracker::new(
+        stats.clone(),
+        clock_offset.clone(),
+        std::sync::Arc::new(super::presenter::PresentMeter::new()),
+    );
    let render_cb = install_render_callback(&codec, &tracker);
    // 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
@@ -313,6 +334,11 @@ pub(super) fn run_sync(
        );
        rendered += r;
        discarded += d;
+        // The one line that separates "the stream never reached glass" from "it reached glass and
+        // looked wrong"; the tally above counts AUs FED, which a black session racks up happily.
+        if r > 0 && rendered == r {
+            log::info!("decode: first frame presented (fed={fed} discarded={discarded})");
+        }

        // 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
@@ -355,8 +381,46 @@ pub(super) fn run_sync(
        // a decode-error trigger rarely fires — the gate arms the freeze on the drop-count climb
        // instead. An overdue freeze (held REANCHOR_FREEZE_MAX with no clean re-anchor) re-asks while it
        // keeps holding: never resume to gray — a dead stream is the QUIC idle-timeout watchdog's job.
+        //
+        // Fed but silent is its own recovery trigger (see [`NO_OUTPUT_PATIENCE`]): a decoder that
+        // never got the opening IDR emits nothing at all and errors on nothing, so none of the
+        // signals above ever fire and the surface stays black for the life of the session.
        let now = Instant::now();
-        if gate.poll(client.frames_dropped(), now)
+        let had_output = r + d > 0;
+        let starved = !had_output
+            && fed > fed_at_output
+            && now.duration_since(last_output) >= NO_OUTPUT_PATIENCE;
+        if had_output {
+            last_output = now;
+            fed_at_output = fed;
+        } else if starved {
+            log::warn!(
+                "decode: no output for {} ms with {} AU(s) fed — requesting a re-anchor keyframe",
+                now.duration_since(last_output).as_millis(),
+                fed - fed_at_output
+            );
+            gate.arm(now);
+            last_output = now; // one request per patience window, not per iteration
+            fed_at_output = fed;
+        }
+        // Nothing has EVER arrived: not an idle stream but a session that never got a picture — the
+        // `starved` test above cannot see it, because it needs `fed` to have moved. `pending` holds
+        // an AU waiting for a free input buffer, so an empty one alongside `fed == 0` means the video
+        // plane has delivered nothing at all.
+        let no_video_yet = fed == 0 && pending.is_none();
+        if no_video_yet
+            && now.duration_since(started) >= NO_VIDEO_PATIENCE
+            && last_no_video_req.is_none_or(|t| now.duration_since(t) >= NO_VIDEO_RETRY)
+        {
+            log::warn!(
+                "decode: no video received {} ms into the session — requesting a keyframe",
+                now.duration_since(started).as_millis()
+            );
+            last_no_video_req = Some(now);
+            let _ = client.request_keyframe();
+            last_kf_req = Some(now); // share the throttle with the loss-recovery path below
+        }
+        if (gate.poll(client.frames_dropped(), now) || starved)
            && last_kf_req.is_none_or(|t| now.duration_since(t) >= Duration::from_millis(100))
        {
            last_kf_req = Some(now);
@@ -542,7 +606,7 @@ fn drain(
            Ok(()) if held_present => {
                rendered = 1;
                if let Some((pts_us, decoded_ns)) = meta {
-                    tracker.note_rendered(pts_us, decoded_ns);
+                    tracker.note_rendered(pts_us, decoded_ns, super::latency::now_realtime_ns());
                }
            }
            Ok(()) => discarded += 1, // held off the screen — awaiting a clean re-anchor
@@ -0,0 +1,448 @@
+//! The vsync clock behind the timeline presenter: an `AChoreographer` thread publishing the
+//! panel's vsync grid + upcoming frame timelines, and pulsing the decode loop's event channel so
+//! a frame parked on a closed glass budget gets its retry tick.
+//!
+//! On API 33+ the thread rides `AChoreographer_postVsyncCallback`, whose callback payload carries
+//! the platform's FRAME TIMELINES — for each upcoming refresh, when SurfaceFlinger expects to
+//! present and the deadline by which a frame must be submitted to make it. That pair is exactly
+//! what `AMediaCodec_releaseOutputBufferAtTime` wants as its target. On 31/32 the older
+//! `postFrameCallback64` supplies only the vsync instant; the presenter then releases ASAP
+//! (identical to the legacy path) and uses the measured period purely to predict the latch for
+//! its glass budget.
+//!
+//! Every `AChoreographer_*` symbol is dlsym-resolved from `libandroid.so` (mirrors
+//! [`super::setup::try_set_frame_rate`]): several sit above the crate's API floor, and one hard
+//! import of a too-new symbol fails `System.loadLibrary` on every older device.
+//!
+//! Started LAZILY on the first decoded frame (the Apple deadline presenter's bootstrap lesson:
+//! an eagerly started clock ticks uselessly for the whole connect window), stopped + joined via
+//! [`VsyncClock`]'s `Drop`.
+
+use std::ffi::c_void;
+use std::sync::atomic::{AtomicBool, AtomicI64, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+/// `CLOCK_MONOTONIC` now in nanoseconds — the clock AChoreographer stamps its timelines on and
+/// the one `AMediaCodec_releaseOutputBufferAtTime` compares against (`System.nanoTime` basis).
+/// Distinct from the stats path's `CLOCK_REALTIME`: presenter scheduling stays monotonic.
+pub(super) fn now_monotonic_ns() -> i64 {
+    let mut ts = libc::timespec {
+        tv_sec: 0,
+        tv_nsec: 0,
+    };
+    // SAFETY: `clock_gettime` with a valid out-pointer is an always-safe syscall.
+    unsafe { libc::clock_gettime(libc::CLOCK_MONOTONIC, &mut ts) };
+    // Explicit widening: timespec's fields are 32-bit on armv7 (time_t/c_long).
+    ts.tv_sec as i64 * 1_000_000_000 + ts.tv_nsec as i64
+}
+
+/// One upcoming frame timeline (API 33+ payload): when SurfaceFlinger expects to present the
+/// frame, and the last instant it can be submitted to make that present. Monotonic ns.
+#[derive(Clone, Copy)]
+pub(super) struct FrameTimeline {
+    pub expected_present_ns: i64,
+    pub deadline_ns: i64,
+}
+
+/// State the choreographer thread publishes and the decode loop reads. All monotonic ns.
+pub(super) struct VsyncShared {
+    stop: AtomicBool,
+    /// The latest vsync callback's frame time (0 = no callback yet).
+    last_vsync_ns: AtomicI64,
+    /// Estimated vsync period (EMA over callback deltas / timeline spacing; 0 = unmeasured).
+    ///
+    /// ⚠ This is the APP's render rate, not necessarily the panel's: Android down-rates a
+    /// process's vsync stream (frame-rate categories / per-uid overrides), so a quiet UI can be
+    /// served 60 Hz callbacks while the panel scans at 120 (observed on-glass, A024). Pacing
+    /// video to THIS rate would cap the stream — hence `panel_period_ns` + the subdivision in
+    /// [`Self::next_target`].
+    period_ns: AtomicI64,
+    /// The panel's own refresh period (from the display mode Kotlin resolved at stream start;
+    /// 0 = unknown). The grid SurfaceFlinger actually latches on.
+    panel_period_ns: AtomicI64,
+    /// Callback count, for the one-shot cadence diagnostic log.
+    ticks: std::sync::atomic::AtomicU32,
+    /// The latest callback's upcoming timelines, soonest first. Empty on the 31/32 fallback.
+    timelines: Mutex<Vec<FrameTimeline>>,
+}
+
+impl VsyncShared {
+    /// The measured vsync period, or 0 while unmeasured.
+    pub(super) fn period_ns(&self) -> i64 {
+        self.period_ns.load(Ordering::Relaxed)
+    }
+
+    /// The panel's own refresh period (0 = unknown) — for the pf-present line's decomposition.
+    pub(super) fn panel_period_ns(&self) -> i64 {
+        self.panel_period_ns.load(Ordering::Relaxed)
+    }
+
+    /// The release target for a frame submitted at `now`: the earliest stored timeline whose
+    /// EXPECTED PRESENT is still `margin` away, extrapolated forward by whole periods once the
+    /// stored set has aged out (timelines refresh once per vsync callback; a frame can decode
+    /// anywhere inside that window). `None` on the 31/32 fallback — the caller releases ASAP.
+    ///
+    /// Gated on `expected_present`, NOT the timeline's `deadline`, on purpose: the deadline
+    /// budgets for GPU rendering the app has yet to submit (`presDeadline` — 11.3 ms on the
+    /// A024, more than a full 120 Hz period), but a video buffer is already fully rendered —
+    /// the only real constraint is SurfaceFlinger's own latch lead, which is what the caller's
+    /// `margin` represents. Targeting by deadline cost every frame an extra refresh of waiting
+    /// (measured: latch p50 ~21 ms vs the ~2-interval floor); a mis-gamble here just means the
+    /// frame presents one vsync later — exactly what the conservative gate always paid.
+    ///
+    /// The picked target is then SUBDIVIDED onto the panel grid: the platform reports timelines
+    /// at the app's assigned render rate, but the panel latches at its own — when the app is
+    /// down-rated (60 Hz callbacks on a 120 Hz panel) the reported timelines are a whole panel
+    /// period apart or more, and pacing to them would cap the video. Pulling the target earlier
+    /// by whole panel periods (while its present still clears the margin) restores the true
+    /// grid; when callbacks run at the panel rate the pull condition is never true and this is
+    /// a no-op.
+    pub(super) fn next_target(&self, now_ns: i64, margin_ns: i64) -> Option<FrameTimeline> {
+        let mut t = {
+            let g = self
+                .timelines
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
+            let found = g
+                .iter()
+                .find(|t| t.expected_present_ns > now_ns + margin_ns)
+                .copied();
+            match found {
+                Some(t) => t,
+                None => {
+                    let last = g.last().copied()?;
+                    let period = self.period_ns();
+                    if period <= 0 {
+                        return None;
+                    }
+                    // All stored timelines have passed — step the last one forward whole
+                    // periods until its present clears `now + margin` again.
+                    let behind = (now_ns + margin_ns).saturating_sub(last.expected_present_ns);
+                    let k = behind / period + 1;
+                    FrameTimeline {
+                        expected_present_ns: last.expected_present_ns + k * period,
+                        deadline_ns: last.deadline_ns + k * period,
+                    }
+                }
+            }
+        };
+        let panel = self.panel_period_ns.load(Ordering::Relaxed);
+        if panel > 0 {
+            while t.expected_present_ns - panel > now_ns + margin_ns {
+                t.deadline_ns -= panel;
+                t.expected_present_ns -= panel;
+            }
+        }
+        Some(t)
+    }
+}
+
+// ---- dlsym'd AChoreographer surface ----
+
+type PostFrameCallback64 =
+    unsafe extern "C" fn(*mut c_void, unsafe extern "C" fn(i64, *mut c_void), *mut c_void);
+type PostVsyncCallback = unsafe extern "C" fn(
+    *mut c_void,
+    unsafe extern "C" fn(*const c_void, *mut c_void),
+    *mut c_void,
+);
+
+struct ChoreoApi {
+    get_instance: unsafe extern "C" fn() -> *mut c_void,
+    /// API 33: vsync callback with frame-timeline payload. Preferred.
+    post_vsync: Option<PostVsyncCallback>,
+    /// API 29 fallback: frame callback with only the vsync instant.
+    post_frame64: Option<PostFrameCallback64>,
+    // AChoreographerFrameCallbackData accessors (API 33; present iff `post_vsync` is).
+    fcd_frame_time: Option<unsafe extern "C" fn(*const c_void) -> i64>,
+    fcd_timelines_len: Option<unsafe extern "C" fn(*const c_void) -> usize>,
+    fcd_preferred_index: Option<unsafe extern "C" fn(*const c_void) -> usize>,
+    fcd_expected_present: Option<unsafe extern "C" fn(*const c_void, usize) -> i64>,
+    fcd_deadline: Option<unsafe extern "C" fn(*const c_void, usize) -> i64>,
+}
+
+impl ChoreoApi {
+    /// Resolve from `libandroid.so`. `None` when even the baseline symbols are missing.
+    fn resolve() -> Option<ChoreoApi> {
+        // SAFETY: dlopen of the always-mapped libandroid.so (refcount bump, never closed); each
+        // dlsym is null-checked before the transmute to its fn-pointer type.
+        unsafe {
+            let lib = libc::dlopen(c"libandroid.so".as_ptr(), libc::RTLD_NOW);
+            if lib.is_null() {
+                return None;
+            }
+            let sym = |name: &std::ffi::CStr| {
+                let p = libc::dlsym(lib, name.as_ptr());
+                (!p.is_null()).then_some(p)
+            };
+            let get_instance = sym(c"AChoreographer_getInstance")?;
+            let post_vsync = sym(c"AChoreographer_postVsyncCallback");
+            let post_frame64 = sym(c"AChoreographer_postFrameCallback64");
+            post_vsync.or(post_frame64)?; // neither post entry point — no clock on this device
+            Some(ChoreoApi {
+                get_instance: std::mem::transmute::<
+                    *mut c_void,
+                    unsafe extern "C" fn() -> *mut c_void,
+                >(get_instance),
+                post_vsync: post_vsync.map(|p| std::mem::transmute::<*mut c_void, PostVsyncCallback>(p)),
+                post_frame64: post_frame64
+                    .map(|p| std::mem::transmute::<*mut c_void, PostFrameCallback64>(p)),
+                fcd_frame_time: sym(c"AChoreographerFrameCallbackData_getFrameTimeNanos").map(|p| {
+                    std::mem::transmute::<*mut c_void, unsafe extern "C" fn(*const c_void) -> i64>(p)
+                }),
+                fcd_timelines_len: sym(c"AChoreographerFrameCallbackData_getFrameTimelinesLength")
+                    .map(|p| {
+                        std::mem::transmute::<*mut c_void, unsafe extern "C" fn(*const c_void) -> usize>(
+                            p,
+                        )
+                    }),
+                fcd_preferred_index: sym(
+                    c"AChoreographerFrameCallbackData_getPreferredFrameTimelineIndex",
+                )
+                .map(|p| {
+                    std::mem::transmute::<*mut c_void, unsafe extern "C" fn(*const c_void) -> usize>(p)
+                }),
+                fcd_expected_present: sym(
+                    c"AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos",
+                )
+                .map(|p| {
+                    std::mem::transmute::<
+                        *mut c_void,
+                        unsafe extern "C" fn(*const c_void, usize) -> i64,
+                    >(p)
+                }),
+                fcd_deadline: sym(c"AChoreographerFrameCallbackData_getFrameTimelineDeadlineNanos")
+                    .map(|p| {
+                        std::mem::transmute::<
+                            *mut c_void,
+                            unsafe extern "C" fn(*const c_void, usize) -> i64,
+                        >(p)
+                    }),
+            })
+        }
+    }
+}
+
+/// Everything a callback invocation needs. Owned by the choreographer thread's stack; callbacks
+/// only ever fire inside that thread's looper poll, so the borrow can't outlive the thread.
+struct CallbackCtx {
+    api: ChoreoApi,
+    choreographer: *mut c_void,
+    shared: Arc<VsyncShared>,
+    on_tick: Box<dyn Fn() + Send>,
+}
+
+impl CallbackCtx {
+    /// Common tail of both callback flavours: update the grid estimate, publish, pulse, re-arm.
+    fn tick(&self, frame_time_ns: i64, timelines: Vec<FrameTimeline>) {
+        let prev = self
+            .shared
+            .last_vsync_ns
+            .swap(frame_time_ns, Ordering::Relaxed);
+        // Panel-grid learner: timeline spacing is SurfaceFlinger's own grid, and the finest
+        // spacing ever observed is the panel's true period — trustworthy where the configured
+        // value is not (under a per-uid frame-rate override, `Display.getRefreshRate` REPORTS
+        // THE OVERRIDE, observed on-glass: a 120 Hz panel read back as 60 while early timelines
+        // ran at 8.28 ms). Corrects DOWNWARD only: subdividing onto a finer real grid is always
+        // valid, widening on a later down-rated window never is.
+        if timelines.len() >= 2 {
+            let spacing = timelines[1].expected_present_ns - timelines[0].expected_present_ns;
+            if (2_000_000..=42_000_000).contains(&spacing) {
+                let cur = self.shared.panel_period_ns.load(Ordering::Relaxed);
+                if cur == 0 || spacing < cur - 200_000 {
+                    self.shared
+                        .panel_period_ns
+                        .store(spacing, Ordering::Relaxed);
+                }
+            }
+        }
+        // One-shot cadence diagnostic (3rd tick, once deltas exist): the callback cadence vs the
+        // panel period is exactly the down-rating question, and this line answers it on-glass.
+        if self.shared.ticks.fetch_add(1, Ordering::Relaxed) == 2 {
+            let spacing = if timelines.len() >= 2 {
+                timelines[1].expected_present_ns - timelines[0].expected_present_ns
+            } else {
+                0
+            };
+            log::info!(
+                "vsync: cadence Δ={:.2}ms timelines={} spacing={:.2}ms panel={:.2}ms",
+                if prev > 0 {
+                    (frame_time_ns - prev) as f64 / 1e6
+                } else {
+                    0.0
+                },
+                timelines.len(),
+                spacing as f64 / 1e6,
+                self.shared.panel_period_ns.load(Ordering::Relaxed) as f64 / 1e6,
+            );
+        }
+        // Period: prefer timeline spacing (exact, straight from the platform), else the delta of
+        // successive callbacks (jittery — EMA'd), clamped to sane panel rates (24..500 Hz).
+        let mut period = 0i64;
+        if timelines.len() >= 2 {
+            period = timelines[1].expected_present_ns - timelines[0].expected_present_ns;
+        } else if prev > 0 {
+            period = frame_time_ns - prev;
+        }
+        if (2_000_000..=42_000_000).contains(&period) {
+            let old = self.shared.period_ns.load(Ordering::Relaxed);
+            let smoothed = if old > 0 {
+                (old * 7 + period) / 8
+            } else {
+                period
+            };
+            self.shared.period_ns.store(smoothed, Ordering::Relaxed);
+        }
+        if !timelines.is_empty() {
+            let mut g = self
+                .shared
+                .timelines
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
+            *g = timelines;
+        }
+        (self.on_tick)();
+        if !self.shared.stop.load(Ordering::Relaxed) {
+            self.repost();
+        }
+    }
+
+    fn repost(&self) {
+        // SAFETY: `choreographer` is this thread's instance; the ctx pointer stays valid for the
+        // thread's life and callbacks only fire on this thread (see the struct doc).
+        unsafe {
+            let ud = self as *const CallbackCtx as *mut c_void;
+            if let Some(post) = self.api.post_vsync {
+                post(self.choreographer, on_vsync, ud);
+            } else if let Some(post) = self.api.post_frame64 {
+                post(self.choreographer, on_frame64, ud);
+            }
+        }
+    }
+}
+
+/// API 33+ trampoline: harvest the frame timelines, then the common tick. Panic-free (an unwind
+/// out of an `extern "C"` fn aborts).
+unsafe extern "C" fn on_vsync(data: *const c_void, ud: *mut c_void) {
+    // SAFETY: `ud` is the thread's `CallbackCtx`, alive for the whole poll loop (see struct doc).
+    let ctx = unsafe { &*(ud as *const CallbackCtx) };
+    let api = &ctx.api;
+    let (mut frame_time, mut timelines) = (now_monotonic_ns(), Vec::new());
+    // SAFETY: `data` is the platform's callback payload, valid for this invocation; the accessors
+    // were resolved together with `post_vsync` (same API level) and are only called when present.
+    unsafe {
+        if let Some(f) = api.fcd_frame_time {
+            frame_time = f(data);
+        }
+        if let (Some(len_f), Some(pref_f), Some(exp_f), Some(dl_f)) = (
+            api.fcd_timelines_len,
+            api.fcd_preferred_index,
+            api.fcd_expected_present,
+            api.fcd_deadline,
+        ) {
+            let len = len_f(data).min(8);
+            // From the PREFERRED index on: earlier timelines are ones the platform already
+            // considers missed for a frame starting now.
+            let start = pref_f(data).min(len);
+            timelines = (start..len)
+                .map(|i| FrameTimeline {
+                    expected_present_ns: exp_f(data, i),
+                    deadline_ns: dl_f(data, i),
+                })
+                .collect();
+        }
+    }
+    ctx.tick(frame_time, timelines);
+}
+
+/// API 29 fallback trampoline: vsync instant only.
+unsafe extern "C" fn on_frame64(frame_time_ns: i64, ud: *mut c_void) {
+    // SAFETY: `ud` is the thread's `CallbackCtx` (see `on_vsync`).
+    let ctx = unsafe { &*(ud as *const CallbackCtx) };
+    ctx.tick(frame_time_ns, Vec::new());
+}
+
+/// The clock: a dedicated looper thread the choreographer calls back on. Dropping stops + joins.
+pub(super) struct VsyncClock {
+    shared: Arc<VsyncShared>,
+    join: Option<std::thread::JoinHandle<()>>,
+}
+
+impl VsyncClock {
+    /// Spawn the choreographer thread. `on_tick` fires once per vsync ON THAT THREAD — it must
+    /// only do something cheap and `Send` (the decode loop passes an event-channel send).
+    /// `panel_hz` is the display mode's own refresh rate (0 = unknown), the latch grid that
+    /// [`VsyncShared::next_target`] subdivides onto. `None` when the platform surface is missing
+    /// (very old device) — the presenter then runs clock-less (ASAP targets, predicted-latch
+    /// budget).
+    pub(super) fn start(panel_hz: i32, on_tick: Box<dyn Fn() + Send>) -> Option<VsyncClock> {
+        let api = ChoreoApi::resolve()?;
+        let timelines_live = api.post_vsync.is_some();
+        let shared = Arc::new(VsyncShared {
+            stop: AtomicBool::new(false),
+            last_vsync_ns: AtomicI64::new(0),
+            period_ns: AtomicI64::new(0),
+            panel_period_ns: AtomicI64::new(if panel_hz > 0 {
+                1_000_000_000 / panel_hz as i64
+            } else {
+                0
+            }),
+            ticks: std::sync::atomic::AtomicU32::new(0),
+            timelines: Mutex::new(Vec::new()),
+        });
+        let thread_shared = shared.clone();
+        let join = std::thread::Builder::new()
+            .name("pf-vsync".into())
+            .spawn(move || {
+                let looper = ndk::looper::ThreadLooper::prepare();
+                // SAFETY: getInstance on a thread with a prepared looper returns this thread's
+                // choreographer (never null once a looper exists).
+                let choreographer = unsafe { (api.get_instance)() };
+                if choreographer.is_null() {
+                    log::warn!("vsync: AChoreographer_getInstance returned null — no clock");
+                    return;
+                }
+                let ctx = CallbackCtx {
+                    api,
+                    choreographer,
+                    shared: thread_shared,
+                    on_tick,
+                };
+                ctx.repost();
+                // The bounded poll doubles as the stop check: no cross-thread wake needed, worst
+                // case teardown waits one timeout out. Callbacks fire inside poll_once_timeout.
+                while !ctx.shared.stop.load(Ordering::Relaxed) {
+                    let _ = looper.poll_once_timeout(Duration::from_millis(250));
+                }
+                // `ctx` drops here — after the loop, so no queued callback can outlive it (they
+                // only ever fire inside this thread's poll).
+            })
+            .ok()?;
+        log::info!(
+            "vsync: choreographer clock started ({})",
+            if timelines_live {
+                "frame timelines"
+            } else {
+                "frame callback fallback"
+            }
+        );
+        Some(VsyncClock {
+            shared,
+            join: Some(join),
+        })
+    }
+
+    pub(super) fn shared(&self) -> &Arc<VsyncShared> {
+        &self.shared
+    }
+}
+
+impl Drop for VsyncClock {
+    fn drop(&mut self) {
+        self.shared.stop.store(true, Ordering::Relaxed);
+        if let Some(j) = self.join.take() {
+            let _ = j.join();
+        }
+    }
+}
@@ -31,9 +31,10 @@ 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␟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.
+/// One resolved host, serialized to Kotlin as `key␟name␟addr␟port␟fp␟pair␟mac␟os`
+/// (`␟` = [`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. New fields append (the Kotlin
+/// parser tolerates both arities), never reorder.
 #[derive(Clone, PartialEq)]
 struct Host {
    key: String,
@@ -44,6 +45,9 @@ struct Host {
    pair: String,
    /// Wake-on-LAN MAC(s) from the mDNS `mac` TXT (comma-separated), for later wake. Empty if absent.
    mac: String,
+    /// OS-identity chain from the mDNS `os` TXT (`linux/fedora/bazzite`, ...), for the host
+    /// card's OS icon. Empty if absent (older host).
+    os: String,
 }

 impl Host {
@@ -56,7 +60,7 @@ 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}{}{FIELD_SEP}{}{FIELD_SEP}{}",
            clean(&self.key),
            clean(&self.name),
            clean(&self.addr),
@@ -64,6 +68,7 @@ impl Host {
            clean(&self.fp),
            clean(&self.pair),
            clean(&self.mac),
+            clean(&self.os),
        )
    }
 }
@@ -186,6 +191,7 @@ fn resolve(info: &ResolvedService) -> Option<Host> {
        fp: val("fp"),
        pair: val("pair"),
        mac: val("mac"),
+        os: val("os"),
    })
 }

@@ -206,7 +212,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␟mac` (`␟` = U+001F). Empty string = no hosts /
+/// newline-joined records of `key␟name␟addr␟port␟fp␟pair␟mac␟os` (`␟` = 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>(
@@ -268,10 +274,11 @@ mod tests {
            fp: "ab".repeat(32),
            pair: "required".into(),
            mac: "aa:bb:cc:dd:ee:ff".into(),
+            os: "linux/fedora/bazzite".into(),
        };
        let encoded = h.encode();
        let fields: Vec<&str> = encoded.split(FIELD_SEP).collect();
-        assert_eq!(fields.len(), 7);
+        assert_eq!(fields.len(), 8);
        assert_eq!(fields[0], "host-123");
        assert_eq!(fields[1], "home-worker-2");
        assert_eq!(fields[2], "192.168.1.70");
@@ -279,6 +286,7 @@ mod tests {
        assert_eq!(fields[4], "ab".repeat(32));
        assert_eq!(fields[5], "required");
        assert_eq!(fields[6], "aa:bb:cc:dd:ee:ff");
+        assert_eq!(fields[7], "linux/fedora/bazzite");
        assert!(
            !encoded.contains('\n'),
            "a record must never contain the record separator"
@@ -297,12 +305,13 @@ mod tests {
            fp: "ab\u{1f}cd".into(),
            pair: "required\n".into(),
            mac: "aa:bb\u{1f}cc".into(),
+            os: "linux\u{1f}evil/arch".into(),
        };
        let encoded = h.encode();
        assert_eq!(
            encoded.matches(FIELD_SEP).count(),
-            6,
-            "exactly seven fields"
+            7,
+            "exactly eight fields"
        );
        assert!(!encoded.contains('\n') && !encoded.contains('\r'));
        let fields: Vec<&str> = encoded.split(FIELD_SEP).collect();
@@ -310,5 +319,6 @@ mod tests {
        assert_eq!(fields[1], "evilhost");
        assert_eq!(fields[4], "abcd");
        assert_eq!(fields[5], "required");
+        assert_eq!(fields[7], "linuxevil/arch");
    }
 }
--- a/Show More
+++ b/Show More